Outlook 2013

 Copy code hover
[image]

Outlook 2013
Send feedback

Published: March 5, 2013

Outlook product logo

Use Outlook 2013 to create solutions that manage message, calendar, and people data to improve productivity and provide convenience.

Explore Outlook 2013 developer resources

New features and scenarios

New features

What's new for Outlook 2013 developers

Get started

Get started

Mail apps for Outlook 2013

Selecting an API or technology for developing solutions for Outlook 2013

Outlook developer roadmap

Getting Started with VBA in Outlook 2010

Code samples and downloads

Code samples

Sample mail apps

How do I... (Outlook 2013 developer reference)

MAPI Samples

OSC Sample Templates

References

Reference

Build apps for Office

Outlook 2013 developer reference

Outlook Social Connector 2013 provider reference

Extending the Weather Bar in Outlook 2013

Outlook 2013 auxiliary reference

Outlook 2013 MAPI Reference

Find training and other resources about Office

Email us to suggest content Subscribe to the Office developer RSS Read Office developer blogs Read Office developer forums Visit MSDN Office and SharePoint on Facebook Follow @MSDN_Office on Twitter

Download

Office updates

Office 365

Office code samples

Office scripts and sample files

Office downloads

Office 365 downloads

How To

Train Office 2010 end users

Office developer videos

Office IT pro training

Office IT pro videos

Sites

Office 365 IT pros

Office 2013 Resource Kit

SharePoint developers

SharePoint IT pros

Office.com

Microsoft.com: Office 365

Additional resources

  • Access 2013

  • Excel 2013

  • InfoPath 2013

  • Office 2013

  • OneNote 2013

  • PowerPoint 2013

  • Project 2013

  • Publisher 2013

  • SharePoint 2013

  • Visio 2013

  • Word 2013

© 2013 Microsoft Corporation. All rights reserved.


What's new for Outlook 2013 developers

 Copy code hover
[image]

What's new for Outlook 2013 developers
Send feedback

Published: July 23, 2013

This document provides a top-level view of the additions and enhancements for developers in Microsoft Outlook 2013, including mail apps, third party weather data services for the Weather Bar, and inline response. The document also describes changes to the Outlook Social Connector, Office Mobile Service, support for Outlook 2013 coexisting with a previous version of Outlook, and new performance criteria for add-ins. For developers who are ready to get a jump start on the Outlook platform, this document provides you with sufficient information to begin coding against Outlook 2013.

Provided by: Randy Byrne

In this article
Introduction
Mail apps
Custom weather data service for the Weather Bar
Outlook Object Model changes
Changes to Outlook Social Connector provider extensibility
Discontinuing support for Office Mobile Service
Coexistence with previous Outlook versions
Performance criteria for keeping add-ins enabled
Conclusion
Additional resources

Introduction

Outlook 2013 provide programmability support for a number of new features. Apps for Office is a new platform that allows developers to use web-based tools such as HTML and JavaScript to build apps that surface within the Outlook Reading Pane or inspector window. Unlike traditional COM Add-ins, apps don't require that you install or update a DLL on the user's computer. When a mail app is initialized by the user, the mail app uses the apps for Office JavaScript object model to provide contextual information about the selected message in the Outlook rich client and Outlook Web App. Your app runs on your web server and any changes you make in your web content will be immediately reflected in your app running on an Outlook client.

In addition to apps, there is extensibility support for the new Weather Bar, and changes to how Outlook 2013 supports Outlook Social Connector provider extensibility and Office Mobile Services. Other features such as Outlook coexistence and add-in performance monitoring are not related directly to any object model, but they will influence the way that you architect and build your solution.

The following are the important changes for developers in Outlook 2013:

  • Mail apps

  • Custom weather service for the Weather Bar

  • Inline response and other Outlook object model enhancements

  • Outlook Social Connector enhancements

  • Discontinuing support for Office Mobile Service

  • Coexistence with previous Outlook versions

  • Performance criteria for keeping add-ins enabled

Note Note

Objects, properties, methods, and events depicted in this article might change in the RTM release of Outlook 2013. Additional object model features might also be introduced before the RTM release of Outlook 2013. Be sure to obtain the RTM version of Outlook 2013 to test your code changes before you release your solution.

Mail apps

Apps for Office are a new feature that lets you incorporate web services directly into Outlook without having to write and deploy a traditional Outlook add-in. In Outlook 2013, mail apps provide rich and compelling experiences to users in Outlook or Outlook Web App using a single code base. A mail app displays an app pane adjacent to the Outlook Reading Pane or an inspector to provide web content appropriate for the displayed message or appointment. Apps are created using ubiquitous web technologies such as HTML and JavaScript. Mail apps do require Exchange 2013 and are not available for users with accounts on versions of Exchange previous to Exchange 2013 or with POP3 or IMAP accounts.

The following sections briefly describe the mail apps architecture, activation rules, and security model. These sections are not meant as a comprehensive technical reference. Please consult Build apps for Office for details on the manifest schema, rule conditions, built-in entities and custom regular expressions, the JavaScript Object Model, and submitting a mail app to the Office Store.

Architecture

The architecture of the mail apps platform is beautiful in its simplicity. An Exchange client such as the Outlook rich client or Outlook Web App downloads mail app manifests from the Exchange server. The XML manifest specifies a set of rules that are run on the client and determine whether the app is activated when a user selects an email message or appointment. If the activation rules are satisfied, then the app button will appear on the app bar. For example, in Figure 1 you see that both the Bing Maps and Action Item mail apps have activated based on the content of the selected email message and appear on the app bar.

Figure 1. Mail app showing context sensitive Bing map in Outlook

Bing Map mail app in Outlook

A mail app is said to be activated when its app button appears on the app bar. Once the user selects the app button, the app pane appears and runs an Initialize event handler in the JavaScript code of your web page hosted on your web server. Figure 2 describes the process that takes place when an Outlook client starts and the user selects an item in Outlook.

Figure 2. Mail app architecture and startup process

Flow of events when starting Outlook mail app

The JavaScript code of a mail app can access properties of the selected message or appointment item. Depending on the permission requested by the app, the app can also access custom properties, enumerate entities (such as addresses or meeting suggestions) or regular expression matches, and make Exchange Web Service (EWS) calls.

Activation Rules

Activation rules control when a mail app is activated in the user interface of an Outlook client. Rules are defined in the XML manifest and are applied by the rules evaluation engine to the selected item in the Reading Pane or an inspector window. If the rules evaluate to true, the app button is visible on the app bar. Note the following about rules:

  • Multiple rules can be combined for complex activation needs.

    Apply logical And or Or operators.

    Rules can be defined using regular expressions.

    Rules can access known entities such as phone numbers, URLs, and street addresses.

Rule types are as follows.

Type of rule

Description

ItemIs

A rule to check if the item is a specific type (appointment, message or custom message class). For example:

XML Copy code Copy code
<Rule xsi:type="ItemIs" ItemType="Message" />

ItemHasKnownEntity

A rule to check if the item has a specific entity. For example:

XML Copy code Copy code
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />

ItemHasRegularExpressionMatch

A rule to check if there are matches to the specified regular expression.

RuleCollection

Defines a rule composed of multiple rules (combined using And or Or).

Note that rules can recognize known entities or custom regular expressions that you define in the app manifest.

What are known entities? Known entities are parsed by the Exchange server during message transport and stamped on the message for use by the rules evaluation engine. The following table lists some known entities that you can use to create activation rules.

Type of known entity | Activation condition
Address | United States street addresses. For example: 1 Microsoft Way, Redmond, WA 07722
Contact | A personal name related to other entities. For example: Steve Ballmer, Microsoft, 1 Microsoft Way, Redmond, WA 98052
EmailAddress | Any SMTP email address. For example: someone@contoso.com
MeetingSuggestion | A reference to an event or meeting. For example: Let's meet next Tuesday for lunch.
PhoneNumber | United States telephone numbers. For example: (425) 555-1212
TaskSuggestion | Actionable sentences in an email. For example: Please install Office 2013 on my computer.
Url | A file name or web address. For example: http://microsoft.com

Security model

Your mailbox contains your private information. In a corporate setting, your mailbox contains privileged communications with your customers, suppliers, and your fellow employees. Outlook safeguards that information and ensures that mail apps keep that information secure. When a user acquires a mail app, the user must grant the permission level requested by the app in its manifest. If the user does not grant permission, the app is not installed into the user's Exchange mailbox. Mail apps use a three-tiered security model. What an app can do depends on the security grant by the end user or administrator, based on the permission requested in the app manifest. Note that apps that require the read/write mailbox permission cannot be installed by an end user. Apps that request the read/write mailbox permission must be installed by a system administrator.

Figure 3. Three-tiered security model for mail apps

3-tier permission model for user, developer, admin

Figure 3 and the table below describe the 3 permission levels. Note that the default permission, restricted, restricts an app from accessing personally identifiable information (PII) from the currently selected message. If the user grants an elevated level of permission such as read item, the app can obtain information such as the sender or recipients of the message. Read/write mailbox permission allows the app to call a subset of powerful EWS functions including the ability to create or modify items in a user's mailbox.

Actor

Permission in manifest

Access

End users installing low trust mail apps

Restricted

Subset of known entities from message: Address, PhoneNumber, Url

End users installing low trust mail apps

ReadItem

All known entities from message: Address, Contact, EmailAddress, MeetingSuggestion, PhoneNumber, TaskSuggestion, Url

Custom regular expression matches from message body.

JSOM:

  • Recipients/sender/attendees

  • Subject/location

  • Single sign on

  • User profile

  • GetUserIdentityTokenAsync method

Exchange administrators installing high trust mail apps

ReadWriteMailbox

ReadItem access and the following:

  • JSOM: makeEWSRequestAsync method

EWS: subset of EWS APIs

Custom weather data service for the Weather Bar

The new Weather Bar in Outlook 2013 uses MSN Weather to provide weather forecasts for user-selected locations. Third party weather data services can plug into Outlook to provide similar weather forecasts. Figure 4 shows the Weather Bar displaying a weather forecast for New York.

Figure 4. The Weather Bar displaying a weather forecast for New York

Weather Bar showing forecast for New York.

To plug into the Outlook Weather Bar, a weather data service can implement a web service that supports a simple 2-part protocol:

  1. The weather data service supports a base URL to a web service, for example, http://service.contoso.com/data.aspx.

  2. Part 1: The web service allows Outlook to append the following parameters to the base URL, to request a location code that corresponds to the user-selected location:

    • outputview=search, which indicates that the request is a location search.

    • weasearchstr=city, where city indicates the user-selected location for weather information.

    • culture=LCID, where LCID indicates the culture of the version of Office installed for the user. The value is defined in [RFC4646] Tags for Identifying Languages

    • src=outlook, which indicates that Outlook is the client application requesting the service.

    The web service response must conform to the Outlook Weather Location XML Schema.

    Figure 5 summarizes part 1 of the protocol to request and respond with a location code for the user-selected location.

    Figure 5. Web service request and response for a location code

    Weather location request and response

  3. Part 2: The web service also supports Outlook to append the following parameters, to request forecast information for the location code obtained from Part 1:

    • wealocations=code, where code is the location obtained from Part 1.

    • weadegreetype=degreetype, where degreetype can be c for metric or f for imperial units for temperature.

    • culture=LCID, where LCID indicates the culture of the version of Office, similar to that in Part 1.

    • src=outlook, which indicates that Outlook is the client application requesting the service, similar to Part 1.

    The web service response must conform to the Outlook Weather Information XML Schema.

    Figure 6 summarizes part 2 of the protocol to request and respond for weather data for the user-selected location.

    Figure 6. Web service request and response for weather information

    Weather information request and response

For more information, see Extending the Weather Bar in Outlook 2013.

Outlook Object Model changes

New objects, properties, methods, events, and enumeration values have been added to the Outlook object model to provide programmability support for new Outlook 2013 features. Additionally, object model improvements address frequent developer requests for changes to the Outlook platform.

Enhancements to existing Outlook objects

The following table lists enhancements to objects, collections, and enumerations that were available in previous versions of Outlook. Only new methods, properties, events, and enumeration values are listed in the New members column.

Table 1. Outlook object model enhancements

Object or enumeration | New members
AppointmentItem | ReadComplete event
ContactItem | ShowCheckAddressDialog method ShowCheckFullNameDialog method ReadComplete event
DistListItem | ReadComplete event
DocumentItem | ReadComplete event
Explorer | ActiveInlineResponse property ActiveInlineResponseWordEditor property InlineResponse event InlineResponseClose event
JournalItem | ReadComplete event
MailItem | ReadComplete event
MeetingItem | ReadComplete event
OlAccountType | olEas enumeration value
OlBusyStatus | olWorkingElsewhere enumeration value
OlObjectClass | olClassPeopleView enumeration value
OlSearchScope | olSearchScopeCurrentStore enumeration value
OlViewType | olPeopleView enumeration value
PostItem | ReadComplete event
RemoteItem | ReadComplete event
ReportItem | ReadComplete event
SharingItem | ReadComplete event
TaskItem | ReadComplete event
TaskRequestAcceptItem | ReadComplete event
TaskRequestDeclineItem | ReadComplete event
TaskRequestItem | ReadComplete event
TaskRequestUpdateItem | ReadComplete event

New objects

The following table lists the new objects introduced in Outlook 2013. All object members are listed in the Properties and Methods column.

Table 2. Outlook object model additions

Object | Properties | Methods
PeopleView | Application | Apply
 | Class | Copy
 | Filter | Delete
 | Language | GoToDate
 | LockUserChanges | Reset
 | Name | Save
 | Parent |
 | SaveOption |
 | Session |
 | SortFields |
 | Standard |
 | ViewType |
 | XML |

Deprecated objects and members

The following are the main deprecations in the Outlook object model in this release:

  • Support for the To-Do Bar

    Because the To-Do Bar is no longer supported in the Outlook 2013 user interface, attempting to use Explorer.ShowPane(olToDoBar) to display or hide the To-Do Bar returns an error. You should modify any existing code to handle the error or avoid calling ShowPane with the olToDoBar constant for code that runs in Outlook 2013.

  • Support for contact linking

    The contact linking feature and its object model support (through the Link and Links objects) has been deprecated. The Links property for each item object now returns Null (Nothing in Visual Basic), and you should modify any existing code to handle this behavior.

  • The MobileItem object. See the section Discontinuing support for Office Mobile Service for more information.

The following table lists the objects, members, and enumeration values deprecated in Outlook 2013. Only deprecated object members and enumeration values are listed in the Deprecated members column. Note that while deprecated members are hidden in the Visual Basic object browser, deprecated enumerations or enumeration values are not hidden, but nonetheless should no longer be used in your code.

Object, collection, or enumeration

Deprecated member or enumeration value

AppointmentItem

Links property

CalendarView

DayWeekFont property

DayWeekTimeFont property

MonthFont property

ContactItem

Links property

DistListItem

Links property

DocumentItem

Links property

Exception

ItemProperties property

JournalItem

Links property

Link

ApplicationClass property

Item property

Name property

Parent property

Session property

Type property

Links

ApplicationClass property

Count property

Parent property

Session property

AddItem method

Remove method

MailItem

Links property

MeetingItem

Links property

MobileItem

Properties

Actions property

Application property

Attachments property

BillingInformation property

Body property

Categories property

Class property

Companies property

ConversationIndex property

ConversationTopic property

CreationTime property

Count property

EntryID property

FormDescription property

GetInspector property

HTMLBody property

Importance property

ItemProperties property

LastModificationTime property

MessageClass property

Mileage property

MobileFormat property

NoAging property

OutlookInternalVersion property

OutlookVersion property

Parent property

PropertyAccessor property

ReceivedByEntryID property

ReceivedByName property

ReceivedTime property

Recipients property

ReplyRecipientNames property

ReplyRecipients property

Saved property

SenderEmailAddress property

SenderEmailType property

SenderName property

SendUsingAccount property

Sensitivity property

Sent property

SentOn property

Session property

Size property

SMILBody property

Subject property

Submitted property

To property

UnRead property

UserProperties property

Methods

Close method

Copy method

Delete method

Display method

Forward method

Move method

Reply method

ReplyAll method

Save method

SaveAs method

Send method

Events

AttachmentAdd event

AttachmentReadAttachmentRemove event

BeforeAttachmentAdd event

BeforeAttachmentPreview event

BeforeAttachmentRead event

BeforeAttachmentSave event

BeforeAttachmentWriteToTempFile event

BeforeAutoSave event

BeforeCheckNames event

BeforeDelete event

Close event

CustomAction event

CustomPropertyChange event event

Forward event

Open event

PropertyChange event

Read event

ReadComplete event

Reply event

ReplyAll event

Send event

UnloadWrite event

NoteItem

Links property

OlObjectClass

olLink enumeration value

olLinks enumeration value

olMobile enumeration value

OlPane

olToDoBar enumeration value

PostItem

Links property

RemoteItem

Links property

ReportItem

Links property

TaskItem

Links property

TaskRequestAcceptItem

Links property

TaskRequestDeclineItem

Links property

TaskRequestItem

Links property

TaskRequestUpdateItem

Links property

Working with an inline response

Outlook 2013 introduces the inline response feature where the user can compose a response in the Reading Pane, rather than opening a new inspector window. If your solution requires adding custom Office Fluent UI controls to the compose note ribbon, or you need to apply business logic or custom functionality to a response message before the response is sent, modify your solution to use the new InlineResponse event on the Explorer object.

Note Note

You can use inline response only if you have selected in the View menu to display the Reading Pane in the explorer.

The InlineResponse event is the inline equivalent to the NewInspector event on the Inspectors collection object. The NewInspector event fires when a new inspector window is opened. The InlineResponse event fires when the user performs an action that causes an inline response to appear in the Reading Pane as shown in Figure 7 below.

Figure 7. An Inline response is created when user selects a response action

An inline response is created

Object model support for inline response

The following members have been added to the Explorer object to provide programmatic support for the inline response feature:

Member | Description
ActiveInlineResponse property | Returns an item object representing the active inline response item in the Reading Pane. Read-only.
ActiveInlineResponseWordEditor property | Returns the Word Document object of the active inline response that is displayed in the Reading Pane. Read-only.
InlineResponse event | Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.

Using the InlineResponse event

Let's imagine a scenario where your code needs to insert a disclaimer for every compose message including reply, reply all, and forward messages. Since inline response is the default response mode in Outlook 2013, your code must hook up an event handler for the InlineResponse event on the Explorer object. The following C# code hooks up an event handler for the InlineResponse event in the OutlookExplorer class. In this code sample, OutlookExplorer is a wrapper class for a collection of Explorer objects.

C# Copy code Copy code
public OutlookExplorer(Outlook.Explorer explorer)
{
    m_Window = explorer;

    // Hook up InlineResponse event
    m_Window.InlineResponse +=
        new Outlook.ExplorerEvents_10_InlineResponseEventHandler
        (m_Window_InlineResponse);

    // Hook up other events if applicable.
}

Once the InlineResponse event fires, the sample code creates a MailItem instance of m_Mail and listens to the PropertyChange event for that MailItem object. m_Mail is an event-aware instance variable that you can use to implement any business logic required by your add-in.

The sample code compares the MailItem.Size property to 0 to determine whether the inline response is new or an existing draft. The ActiveInlineResponseWordEditor property returns a Word.Document object, doc, which represents the active inline response for the active Explorer. Using the Word object model, the code adds a disclaimer to the beginning of this doc object.

C# Copy code Copy code
// InlineResponse fires when the user creates an inline response item
void m_Window_InlineResponse(object Item)
{
    if (Item is Outlook.MailItem)
    {
        m_Mail = Item as Outlook.MailItem;
        // Hook up event-aware instance variable.
        // Use the variable to implement any business logic
        // required by your add-in.
        m_Mail.PropertyChange +=
            new Outlook.ItemEvents_10_PropertyChangeEventHandler(
                m_Mail_PropertyChange);
        // Implement any business logic.

        // Use mail.Size to determine if item is new
        // or is a draft inline response.
        // Size == 0 indicates a new inline response.
        if (m_Mail.Size == 0)
        {
            {
                Word.Document doc =
                    m_Window.ActiveInlineResponseWordEditor as Word.Document;
                Word.Application wdApp = doc.Application as Word.Application;
                Word.Range rng = wdApp.ActiveDocument.Range(Start: 1);
                rng.InsertBefore("My Disclaimer...");
            }
        }
        else
        {
            // Do nothing.
        }
    }
}

Note that the ActiveInlineResponse property returns a MailItem object representing the active inline response item. You can use the same properties and methods of the MailItem object on this item, except for the following:

  • MailItem.Actions property

  • MailItem.Close method

  • MailItem.Copy method

  • MailItem.Delete method

  • MailItem.Forward method

  • MailItem.Move method

  • MailItem.Reply method

  • MailItem.ReplyAll method

  • MailItem.Send method

On the other hand, if no inline response is active, the ActiveInlineResponseWordEditor and ActiveInlineResponse properties return null.

Adding custom controls to the Compose Tools contextual tab

Another possible scenario is that you want to extend the Outlook user interface for an inline reply. To extend the Outlook user interface, you need to use Office Fluent UI extensibility which is not covered in depth in this article. See the links supplied at the end of this article for additional information on extending the Outlook user interface. When an inline response is displayed in Outlook 2013, the user sees the Compose Tools contextual tab displayed on the Office Fluent ribbon. To add your control to the Compose Tools contextual tab, add your custom controls to the <contextualTabs> </contextualTabs> section of ribbon XML that will be passed to the GetCustomUI method of the IRibbonExtensibility interface for the RibbonID equal to "Microsoft.Outlook.Explorer". You must identify the tabSet element with the appropriate value for the idMso attribute, which in this case is "TabComposeTools". The following ribbon XML creates the MyButton control shown in Figure 7.

XML Copy code Copy code
    <contextualTabs>
      <tabSet idMso="TabComposeTools">
        <tab idMso="TabMessage">
          <group label="MyGroup" id="MyComposeToolsGroup">
            <button id="MyButtonInlineResponse"
                    size="large"
                    label="MyButton"
                    imageMso="MagicEightBall"
                    onAction="OnInlineResponseButtonClick" />
          </group>
        </tab>
      </tabSet>
    </contextualTabs>

When the user selects the MyButton control, the OnInlineResponseButtonClick handler is called. The following code sample uses the ActiveInlineResponseWordEditor property to obtain an instance of a Word.Document object. You can then use all the functionality of the Word.Document object to insert and format text as needed by your scenario.

C# Copy code Copy code
// Callback for inline response custom button.
public void OnInlineResponseButtonClick(Office.IRibbonControl control)
{
    if (control.Context is Outlook.Explorer)
    {
        Outlook.Explorer myExplorer =
            control.Context as Outlook.Explorer;
        Word.Document doc =
        myExplorer.ActiveInlineResponseWordEditor as Word.Document;
        Word.Application wdApp = doc.Application as Word.Application;
        Word.Range rng = wdApp.ActiveDocument.Range(Start: 1,
            End: wdApp.ActiveDocument.Characters.Count);
        rng.InsertBefore("\n" + "My Disclaimer...");
    }
}

Changes to Outlook Social Connector provider extensibility

In Office 2013, the Outlook Social Connector (OSC) has expanded its scope. It allows not only Outlook but all Office client applications that support displaying user presence and the Contact Card to display an aggregation of social information updates applied on a professional or social network site. In addition, SharePoint Server, SharePoint Workspace, and the Lync client also support the OSC.

One major change in OSC provider extensibility in Outlook 2013 is that activities are no longer synchronized using the activities cache. If an OSC provider supports displaying activities, then the provider must synchronize activities on demand to display up-to-date activities.

In addition, providers can now use the OSC XML Schema to communicate extra metadata for a person, for example, askmeabout, businessAddress, interests, skills, schools, website.

For detailed information, see What's New for Providers.

Discontinuing support for Office Mobile Service

In Office 2010, developers can build web services for Office Mobile Service (OMS) to integrate the mobile capabilities of Outlook and SharePoint with mobile devices. In Office 2013, only SharePoint continues to support OMS. Outlook 2013 has also deprecated the MobileItem object and its members. Attempting to create a MobileItem using Application.CreateItem returns E_INVALIDARG.

Coexistence with previous Outlook versions

Coexistence refers to the ability of delivering Outlook 2013 by Click-to-Run on the same computer where Outlook 2007 or Outlook 2010 is present. Coexistence, also known as side-by-side installation, allows the user to try Outlook 2013 without having to uninstall a previous Outlook version. Click-to-Run is the default delivery mechanism for Outlook 2013. Once Outlook 2013 is delivered on a computer, the user can run Outlook 2013 or the previous version of Outlook installed on their computer. Be aware that coexistence does not mean running two versions of Outlook simultaneously. Running two versions of Outlook simultaneously is not supported and Outlook displays an error dialog if you attempt to run a previous version of Outlook while Outlook 2013 is running.

Note Note

Coexistence of Outlook 2013 is not supported with versions of Outlook prior to Outlook 2007.

Version Support Matrix

This section describes the bitness and installation modes of earlier versions of Outlook that can coexist with Outlook 2013. Note the following:

  • MSI refers to the Microsoft Installer (MSI) installation of a previous version of Outlook.

  • Supported Windows versions for Office 2013 are Windows 7 and Windows 8 only.

  • Windows Server is not supported for Click-to-Run.

  • Outlook 2013 does not support coexistence with Outlook 2003 or earlier.

  • Outlook 2013 does not support coexistence with the same version of Outlook - that is, Outlook 2013 installed by MSI and Outlook 2013 delivered by Click-to-Run are not supported on the same computer.

  • Cross-bitness is not supported. The user must always install the Click-to-Run version that matches the bitness of the down-level MSI install.

Version | Outlook 2007 MSI | Outlook 2010 x86 MSI | Outlook 2010 x64 MSI
Outlook 2013 C2R x86 | Yes | Yes | No
Outlook 2013 C2R x64 | No | No | Yes

Version-dependent profiles

To support coexistence, Outlook 2013 stores Outlook profiles in a separate hive in the Windows registry. The profile from a previous version of Outlook is migrated to the Outlook 2013 profile hive during the first boot of Outlook 2013. Subsequent changes or additions to the profile for the previous version of Outlook are not migrated during subsequent boots of Outlook 2013.

Profiles hive in Windows Registry

Unlike previous versions of Outlook that stored profiles in a version-independent manner under HKCU\Software\Microsoft\Windows NT\Windows Messaging Subsystem\Profiles, Outlook 2013 stores profiles in a versioned hive under the following key:

HKEY_CURRENT_USER\Software\Microsoft\Office\<version>\Outlook\Profiles

where <version> is a string representing the xx.0 major version, such as 15.0 for Outlook 2013.

Calling MAPI profile APIs

There are no changes for applications to read profile data from a profile hive. After initializing MAPI (for either a down-level version or the most current MAPI version, depending on the application's requirements), an application can use common MAPI profile APIs to read values from the appropriate profile hive.

If an application initializes MAPI for Outlook 2013, MAPI profile APIs read or write profile data to the versioned hive. If the application initializes MAPI for a previous version of Outlook, MAPI profile APIs read or write profile data to the version-independent hive.

App Path registration

To prevent down-level applications from loading the wrong MAPI version, Outlook 2013 modifies the App Path registration in the registry. A down-level version of an application loading the wrong MAPI version can result in a crash in the application attempting to load MAPI. Typically, previous versions of Outlook have written the Outlook App Path to the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\OUTLOOK.EXE

Previous versions of Click-to-Run did not modify the App Path for Outlook. Delivering Outlook 2013 by Click-To-Run modifies the App Path as follows:

  • Installs patches for Outlook 2007 or Outlook 2010 to remove the dependency on App Path.

    Modify the App Path to point to the Outlook 2013 path for Outlook.exe.

    The default path for Outlook.exe for Outlook 2013 is C:\Program Files\Microsoft Office 15\root\office15.

MAPI Versioning

Applications that use MAPI calls the MAPIInitialize function to initialize a MAPI session. By default, applications that initialize MAPI use the version of MAPI provided by Outlook 2013. If you need to use a different version of MAPI, see the following topics in the Outlook 2013 MAPI Reference.

  • Building MAPI Applications on 32-Bit and 64-Bit Platforms

  • How to: Link to MAPI Functions

  • How to: Choose a Specific Version of MAPI to Load

Simple MAPI

Simple MAPI refers to the API that allows applications to send mail with attachments using MAPISendMail or the new MAPISendMailW API introduced with Windows 8.

  • The only supported Simple MAPI APIs are MAPISendMail (Windows 7) or MapiSendMailW (Windows 8).

    Developers should consider modifying existing Simple MAPI code to use MAPISendMailW (Windows 8) or MAPISendMailHelper (Windows 7) with full Unicode support and the ability to display a modeless Outlook inspector.

    If Outlook is not running or Outlook 2013 is running, calling MAPISendMail or MAPISendMailW displays an Outlook 2013 inspector.

    If a previous version of Outlook is running, calling MAPISendMail or MAPISendMailW displays the following error:

    This action is not supported while an older version of Outlook is running.

Protocol handlers

During installation, Outlook 2013 is registered as the default protocol handler for the common protocols listed in the following table. Outlook 2013, Outlook 2010, and Outlook 2007 support these protocols.

Protocol | Description
feed:, feeds: | Handler for RSS feeds
mailto: | Handler for MailTo links that display an Outlook inspector
stssync: | Handler for SharePoint sync
outlook: | Outlook protocol can only be used from Outlook item body or folder home page
webcal: | Handler for webcal protocol

Note the following if Outlook 2013 is present with an older version of Outlook on the same computer:

  • If no previous version of Outlook is running, calling the protocol handler invokes Outlook 2013 to handle the protocol handler request.

If a previous version of Outlook is running, calling the protocol handler uses a command line handoff to invoke the previous version of Outlook to handle the request.

File Associations

During installation, Outlook 2013 is registered as the default handler for the common file associations listed in the following table. Outlook 2013, Outlook 2010, and Outlook 2007 support all these file extensions.

File association | Description
.eml | Email message
.fdm | Outlook form definition
.hol | Outlook holiday
.ics | iCalendar file
.msg | Outlook message item
.oft | Outlook item template
.pst | Outlook data file
.vcf | vCard file
.vcs | vCalendar file

Note the following if Outlook 2013 is present with an older version of Outlook on the same computer:

  • If no previous version of Outlook is running, opening an item from the file system opens the item in Outlook 2013. This action starts Outlook 2013 if it is not already running.

  • If a previous version of Outlook is running, opening an item from the file system cause Outlook 2013 to launch and hand off the request to that previous version of Outlook.

Co-creating an Outlook Application object

Add-ins should use the Application object passed back in the OnConnection event (native add-ins) or ThisAddin_Startup event (managed add-ins built using Visual Studio Tools for Office). If your application co-creates an Outlook.Application object using CreateObject or another function that provides the ability to co-create an instance of Outlook.Application, you should be aware of the following in a coexistence environment:

  • If Outlook is not running or Outlook 2013 is running, calling CreateObject("Outlook.Application") returns an Outlook.Application object that represents Outlook 2013.

  • If a previous version of Outlook is running, calling CreateObject returns an Outlook.Application object that represents the previous version of Outlook.

  • Examine the Application.Version property to determine the version of Outlook that is running.

Detecting Click-to-Run

To detect the existence of Outlook in the Click-to-Run environment, verify that the VirtualOutlook key exists in the following registry key:

HKLM\Software\Microsoft\Office\15.0\Common\InstallRoot\Virtual\VirtualOutlook

If the VirtualOutlook key exists, then Outlook has been delivered as a Click-to-Run application.

Ensuring your solution will run in the coexistence environment

Since coexistence is the default delivery mode, you should test your solution against Outlook 2013 and previous versions of Outlook and check for the following possible issues:

  • Add-ins are registered in version-independent hive in the Windows registry under

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Outlook\Addins

    or

    HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Outlook\Addins

    Since the add-in registration is version-independent, your add-in should run when Outlook 2013 or a previous version of Outlook is running. Be sure to test an updated version of your add-in against Outlook 2013 and previous Outlook versions. The add-in should detect the Outlook version using Application.Version and adjust gracefully to the running Outlook version.

  • Remove dependencies on App Path from your code.

  • Do not use the Windows registry to enumerate profiles. Instead use the MAPI profile APIs.

Performance criteria for keeping add-ins enabled

Extending the add-in resiliency pillar of Outlook 2010, Outlook 2013 monitors add-in performance metrics such as add-in startup, shutdown, folder switch, item open, and invoke frequency. Outlook records the elapsed time in milliseconds for each performance monitoring metric.

For example, the startup metric measures the time required by each connected add-in during Outlook startup. Outlook then computes the median startup time over 5 successive iterations. If the median startup time exceeds 1000 milliseconds (1 second), then Outlook disables the add-in and displays a notification to the user that an add-in has been disabled. The user has the option of always enabling the add-in, in which case Outlook will not disable the add-in even if the add-in exceeds the 1000 millisecond performance threshold

Monitoring add-in performance for default disabling

Outlook uses the following criteria to determine if it should disable an add-in. The user has the option of always enabling an add-in and exempting the add-in from the add-in disabling criteria.

Criteria | Threshold (in milliseconds) | Description
Startup | 1000 | Measures the time in milliseconds for the add-in to complete startup using the IDTExtensibility2_OnConnection event. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Shutdown | 500 | Measures the time in milliseconds for the add-in to complete shutdown using the IDTExtensibility2_OnDisconnection event. Only applies to add-ins that request slow shutdown. Add-ins that use fast shutdown are not subject to this criteria. If the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in on the next startup of Outlook.
Folder switch | 500 | Measures the time in milliseconds for the add-in to complete folder switch using the BeforeFolderSwitch and FolderSwitch events on the Explorer object. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Item open | 500 | Measures the time in milliseconds for the add-in to complete opening an item using the Open event on an item. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Invoke frequency | 1000 | Measures the time interval in milliseconds between the add-in making 10,000 successive invoke calls. By default, if the interval between 10,000 successive calls and the next is less than the performance threshold, Outlook disables the add-in. Unlike the other 4 criteria, this criterion does not incur taking a median value.

System Administrator control over add-ins

The user has control over which add-ins run on their computer. For system administrators, Outlook 2013 provides an enhanced level of control over add-ins using group policy. Group policy will always override user settings and users are prevented from changing add-in settings for add-ins that have been configured by the group policy "List of Managed Add-ins". The policy key is as follows.

Key

HKCU\Software\Policies\Microsoft\Office\15.0\Outlook\Resiliency\AddinList

Name

List of Managed Add-ins

Description

This policy setting allows you to specify which add-ins are always enabled, always disabled (blocked), or configurable by the user.

Note Note

Here, the term "managed" refers to add-ins that are handled by the group policy, and does not relate to add-ins being developed in managed programming languages.

To block add-ins that are not managed by this policy setting, you must also configure the "Block all unmanaged add-ins" policy setting.

To enable this policy setting, provide the following information for each add-in:

  • In "Value name," specify the programmatic identifier (ProgID) for COM add-ins.

    To obtain the ProgID for an add-in, use the Registry Editor on the client computer where the add-in is installed to locate key names under

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Outlook\Addins

    or

    HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Outlook\Addins

  • In "Value," specify the value as follows:

    • To specify that an add-in is always disabled (blocked), specify 0.

    • To specify that an add-in is always enabled, specify 1.

    • To specify that an add-in is configurable by the user and not blocked by the "Block all unmanaged add-ins" policy setting when enabled, specify 2.

If you disable or do not enable this policy setting, the list of managed add-ins is deleted. If the "Block all unmanaged add-ins" policy setting is enabled, then all add-ins are blocked.

Add-ins that are disabled by this policy will never be disabled by the Outlook add-in disabling feature, which disables add-ins for performance, resiliency, or reliability reasons.

User interface for add-in disabling feature

When an add-in exceeds the performance threshold, Outlook displays the notification bar shown in Figure 8 that informs the user that one or more add-ins has been disabled.

Figure 8. Outlook displays a notification bar when an add-in is disabled automatically

If the user clicks the View Disabled Add-ins button on the notification bar, the Disabled Add-ins dialog will be displayed as shown in Figure 9.

Figure 9. Clicking "Always enable this add-in" button enables the add-in and exempts the add-in from the add-in disabling feature

Always enable an add-in

If the user decides that the performance timing required by the add-in is acceptable, the user has the choice of always enabling the add-in. An add-in that is always enabled will not be automatically disabled by Outlook based on performance criteria. If for some reason the user decides later that he or she no longer wants to exempt the add-in from the add-in disabling feature, the user can also disable the add-in from the Disabled Add-ins dialog shown in Figure 10.

Figure 10. Selecting the Disable this add-in button disables the add-in

Disable an add-in

Preventing an add-in from being disabled

While most add-ins will not be disabled by the add-in disabling feature, you don't want your add-in to be disabled consistently. Here are suggestions for improving add-in performance:

  • Prefer native COM add-ins over managed add-ins since managed add-ins must incur the overhead of loading the .NET Framework during Outlook startup.

  • If you have long-running tasks such as making an expensive connection to a database, defer those tasks to occur after startup.

  • If possible, cache data locally rather than making expensive network calls during the FolderSwitch and BeforeFolderSwitch events of an explorer, or Open events of an item.

  • Polling is an expensive operation, so always prefer an event-driven model over polling.

  • Be aware that all calls to the Outlook object model execute on Outlook's main foreground thread. Avoid making long-running Outlook object model calls if possible. Note that in Outlook 2013, calls to the Outlook object model return E_RPC_WRONG_THREAD when the Outlook object model is called from a background thread.

In particular, if you use Office developer tools in Visual Studio to create managed add-ins, be aware that the first add-in to load the CLR is likely to take a performance hit. Consider the following measures, and see the additional resources at the end of this document for details:

  • Load a managed add-in on demand.

  • Delay loading the CLR.

  • Use an MSI deployment package instead of ClickOnce.

  • If applicable, use a Fast Path to bypass schema validation, digital signatures validation in manifests, and automatic update checking. You can find more information about using the Fast Path in the blog post Performance Improvements Coming Soon to a Service Pack Near You (Stephen Peters).

  • If your add-in extends the ribbon and links in a large library, override ribbon reflection.

Conclusion

Mail apps provide an exciting opportunity for developers to bring web services and contextual web-driven UI directly into Outlook and Outlook Web App. We have delivered on our vision of "Write once, run anywhere" for Exchange and Outlook developers. We now offer two extensibility pillars, the first built on the Office COM add-in feature introduced in Office 2000 and the second built on the mail apps platform. The COM add-in model supports deep integration with only the Outlook client and requires that you touch every desktop when your solution is installed. If you have an existing add-in solution, you should consider updating the add-in to work with inline response, coexistence, and the add-in disabling feature. If you are looking for new opportunities to reach a very large audience using Outlook and Outlook Web App, create a mail app and enjoy web-simple deployment and integration of your web service directly into the Outlook UI. Whichever path you choose (and you might choose both), happy coding!

Additional resources

Apps for Office

  • Build apps for Office

Weather Bar

  • Extending the Weather Bar in Outlook 2013

  • Outlook Weather Location XML Schema

  • Outlook Weather Information XML Schema

Outlook and Office object models

  • Outlook 2013 Developer Reference

  • Extending the User Interface in Outlook 2010

Outlook Social Connector

  • Getting Started with Developing an Outlook Social Connector Provider

Coexistence and MAPI

  • Outlook 2013 MAPI Reference

  • Outlook 2010: MAPI Header Files

  • Outlook 2010 Messaging API (MAPI) Code Samples

  • SGriffin's MAPI Internals

Performance and Office add-ins development in Visual Studio

  • Demand-Loading VSTO Add-ins

  • Delay-loading the CLR in Office Add-ins

  • VSTO Performance: Delay Loading and You (Stephen Peters)

  • Performance Improvements Coming Soon to a Service Pack Near You (Stephen Peters)

  • VSTO Performance: Ribbon Reflection (Stephen Peters)

  • Publishing Office Solutions by Using Windows Installer

Miscellaneous

  • What's New for Office 2013 Developers


Selecting an API or technology for developing solutions for Outlook 2013

 Copy code hover
[image]

Selecting an API or technology for developing solutions for Outlook 2013
Send feedback

Published: January 08, 2013

This article describes the APIs and technologies you can use to extend Outlook 2013, and helps you decide the appropriate API or technology for your scenario.

Applies to: Outlook 2013 | Outlook 2010 | Outlook 2007 | Visual Studio 2012

In this article
Overview
Objective evaluation criteria
Decision factors for the apps for Office platform
Decision factors for the object model or PIA
Decision factors for MAPI
Decision factors for the Auxiliary APIs
Automating Outlook by in-process vs. out-of-process Solutions
Automating Outlook by managed vs. unmanaged solutions
Niche APIs and technologies
Conclusion
Additional resources—apps for Office
Additional resources—object model and PIA
Additional resources—Auxiliary APIs
Additional resources—primary references, resources, and code samples

Overview

Microsoft supports various APIs and technologies that extend Outlook:

  • Starting in Office 2013, the apps for Office platform opens up opportunities to extend Outlook functionality across Outlook clients on the desktop, tablet and smart phone. The platform includes a JavaScript API for Office and a schema for app manifests.

  • The object model, the corresponding Outlook Primary Interop Assembly (PIA), and the Messaging API (MAPI) have been the most commonly used APIs in Outlook solutions.

  • The auxiliary APIs complement MAPI in a few scenarios.

  • Outlook Social Connector (OSC) provider extensibility and the Weather Bar extensibility serve specific scenarios of their niche markets.

This article explains the selection criteria for the apps for Office platform, the object model, PIA, and MAPI. Note that apps for Office use the JavaScript API for Office and do not call into the object model, and vice versa. Solutions that use the other APIs can use one or more APIs. For example, a COM add-in written in C++ can use the object model, MAPI, and auxiliary APIs in the same solution.

To get the most benefit from this article, you should be familiar with Outlook at the user level and have general software development knowledge. However, you do not need to have a comprehensive understanding of the features that these APIs or technologies support. The article helps answer the following questions:

  • If you have only an idea about the goals of your solution, the target market, and available resources, what other criteria should you consider to select an API?

  • Why would you consider apps for Office, and when would you choose to create apps as opposed to add-ins?

  • If your solution has to run on earlier versions of Outlook, including Outlook 2003, how does that affect your API choice?

  • If your solution has to iterate through Outlook folders that contain thousands of items, and you need to be able to modify those items, which API would work best?

  • If your solution relies heavily on Outlook business logic and interacts with other Office applications, is the Outlook object model the best choice?

  • What do the object model and MAPI allow you to extend in Outlook?

  • If you can use either the object model or MAPI to achieve your task, how should you decide which API to use?

The article describes selection criteria in the following sections:

  • Objective evaluation criteria—Describes objective functional, development, security, and deployment characteristics for the apps for Office platform, object model, PIA, and MAPI.

  • Decision factors for the apps for Office platform—Lists the major points to consider when choosing to use the apps for Office platform.

  • Decision factors for the object model or PIA—Lists the major points to consider when choosing to use the object model or the PIA.

  • Decision factors for MAPI—Lists the major points to consider when choosing to use MAPI.

  • Decision factors for the Auxiliary APIs—Lists the major points to consider when choosing to use the auxiliary APIs.

  • Automating Outlook by in-process vs. out-of-process Solutions—Lists the major points to consider when deciding whether to automate Outlook by implementing a solution that runs in or out of the Outlook process.

  • Automating Outlook by managed vs. unmanaged solutions—Lists the major points to consider when deciding whether to automate Outlook by creating a managed or unmanaged solution.

  • Niche APIs and technologies—Provides a high-level description of OSC provider extensibility and the Weather Bar extensibility, and lists additional sources of information.

Objective evaluation criteria

This section describes criteria that you can use to compare the apps for Office platform, object model, PIA, and MAPI to determine which better meets your needs. Different criteria can be more or less important, depending on your projects and available resources.

The tables in this section define evaluation criteria in the following categories:

  • Functional criteria—Describes the things you can and cannot do with the technology.

  • Development criteria—Describes the development tools or information you need to use the technology

  • Security criteria—Describes the security and permissions issues related to the technology.

  • Deployment criteria—Describes the recommended deployment and distribution methods for the technology.

Objective evaluation criteria for the apps for Office platform

Starting in Office 2013, developers can use the apps for Office platform to extend web services and content into the context of Office rich and web clients. An app for Office is a web page that is developed using common web technologies, hosted inside an Office client application (such as Outlook), and can run on-premises or in the cloud. Of the few types of apps for Office, the type that Outlook supports is called mail apps. While the object model, PIA, and MAPI are often used to automate Outlook at an application level, you can use the JavaScript API for Office to interact at an item level with the content and properties of an email message, meeting request, or appointment. You can publish mail apps to the Office Store or an internal Exchange catalog.

End users and administrators can install mail apps on an Exchange mailbox, and use mail apps in the Outlook rich client as well as Outlook Web App. As a developer, you can choose to make your mail app available on only the desktop, or also on the tablet or smart phone. Figure 1 shows an example of a YouTube mail app, which is described in detail in How to: Build a mail app for Outlook to view YouTube videos. The YouTube mail app allows end users select a URL for a YouTube video and watch the video within Outlook or Outlook Web App, on the desktop or tablet.

Figure 1. YouTube mail app is active for the selected message, which contains a URL to a video on YouTube.com

YouTube mail app in Outlook

After a user installs a mail app, the app is available for use in the app bar when the current context matches the activation conditions that the app specifies. A mail apps allows you to specify rules about the currently selected item that activate a mail app only if certain conditions are met. For example, the YouTube mail app that lets you play a YouTube video within Outlook is relevant only when the selected Outlook item contains a URL to a video on YouTube.com. In this case, you would specify that the app should be active only when the selected message contains such a URL.

The following tables show the evaluation criteria for the apps for Office platform.

Functional criteria

Criteria

Mail apps support in apps for Office platform

Application domain

The scope of activity of a mail app is virtually any supported message or appointment item in the user's Exchange mailbox that the user has selected and that satisfies the activation conditions. The permissions of a mail app determine its access to the properties and specific entities (such as an email address or telephone number) that exist for that item. For example, a mail app requesting the read/write mailbox permission can read and write all the properties of any item in the user's mailbox; create, read, and write to any folder or item; and send an item from that mailbox.

Major objects

The JavaScript API for Office provides a few objects at the top level that are shared by all the types of apps for Office: Office, Context, and AysncResult. The next level in the API that is applicable and specific to mail apps includes the Mailbox, Item, and UserProfile objects, which support accessing information about the user and the item currently selected in the user's mailbox. At the data level, the CustomProperties and RoamingSettings objects support persisting properties set up by the mail app for the selected item and for the user's mailbox, respectively. Item-level objects include the Appointment and Message objects that inherit from Item, and the MeetingRequest object that inherits from Message. These represent the types of Outlook items that support mail apps: calendar items of appointments and meetings, and message items such as email messages, meeting requests, responses, and cancellations. Beyond this level in the API are item-level properties (such as Appointment.subject) as well as objects and properties that support certain known Entities objects (for example Contact, MeetingSuggestion, PhoneNumber, and TaskSuggestion).

See Fundamentals for developing mail apps in Outlook for a summary of the features supported for mail apps.

Data-access model

The JavaScript API for Office represents the following features as a hierarchical set of objects: the app's runtime environment, user's mailbox and profile, and data about an item.

Threading models

Each mail app executes in its own process separate from the Outlook process.

Application architectures

In Outlook, a mail app is a set of HTML and JavaScript web pages hosted as a separate process inside a web browser control which, in turn, is hosted inside an app runtime process that provides security and performance isolation.

Remote usage

Mail apps use the JavaScript API for Office to access data about the current user, mailbox, and selected item stored on the corresponding Exchange Server. Provided that they have the appropriate permissions and use the appropriate technique for cross-domain access, mail apps can also call Exchange Web Services and other third-party web services to extend their functionality.

Transactions

The JavaScript API for Office does not support transactions.

Availability

The JavaScript API for Office is available for mailboxes on Exchange Server 2013, starting in Outlook 2013.

Development criteria

Criteria | Mail apps support in apps for Office platform
Languages and tools | You can implement mail apps using any common web technology, including HTML5, JavaScript, CSS3, XML, and REST APIs. You can use your preferred web development tool. Alternatively, using "Napa" Office 365 Development Tools, Visual Studio 2012, or a later version of these tools provides conveniences that save you time in development.
Managed implementation | Where appropriate in your scenario, you can use managed .aspx pages to implement server-side code for your mail apps.
Scriptable | The JavaScript API for Office is directly used in scripts.
Test and debug tools | You can use any web development tools you prefer. "Napa" Office 365 Development Tools and Visual Studio provide an integrated development environment that facilitates app testing and debugging. Troubleshooting mail apps activation and How to: Debug item properties provide further help in troubleshooting and debugging mail apps.
Expert availability | Programmers who have the required level of web development expertise for apps for Office are relatively easy to find. The platform is intended for both professional and non-professional developers.
Available information | Information about developing and posting apps for Office is available at Build apps for Office and SharePoint. Specific documentation for mail apps is available at Mail apps for Outlook.
Developer and deployment licensing | Refer to Licensing apps for Office and SharePoint for information about the app license framework for apps for Office.

Security criteria

Criteria

Mail apps support in apps for Office platform

Design-time permissions

No special permissions are required to develop mail apps.

Setup permissions

By default, end users and administrators can install low-trust mail apps that require restricted or read item permission, and administrators can install high-trust mail apps that require read/write mailbox permission.

Run-time permissions

Mail apps request a specific level of permission that is based on a three-tier permissions model: restricted, read item, and read/write mailbox.

Built-in security features

The apps for Office runtime provides the following benefits to prevent an app from damaging the end user's environment:

  • Isolates the process that the app runs in.

  • Doesn't involve .dll or .exe replacement or ActiveX components.

  • Makes apps easy to install or uninstall by the end user.

  • The administrator and end users have control over the mail apps that are made available and whether to grant the requested permission before installing a mail app.

  • In the case of rich clients, governs the use of memory and CPU to prevent denial of service malicious attacks.

Security monitoring features

For mail apps, the following resources are monitored:

  • CPU core usage.

  • Memory usage.

  • Number of crashes.

  • Length of time blocking an application.

  • Regular expression response time.

  • Number of times re-evaluating regular expressions.

Administrators can override default settings that govern the resource usage.

Deployment criteria

Criteria | Mail apps support in apps for Office platform
Server platform requirements | The user's mailbox for which a mail app is installed must be on Exchange Server 2013 or a later version.
Client platform requirements | For a mail app to run on the Outlook rich client, Outlook 2013 and Internet Explorer 9, or a later version of these applications, must be installed on the local computer.
Deployment methods | You can publish mail apps to the Office Store or to an Exchange catalog that makes the app available to users on that Exchange Server. Administrators or users can then choose to install a mail app from the Office Store or Exchange catalog, by using either the Exchange Admin Center (EAC) or by running remote Windows PowerShell cmdlets. You can access the EAC from the Outlook Backstage view or Outlook Web App, or by directly signing into the EAC for your mailbox. For more information, see Deploying and installing mail apps for testing in Outlook.
Deployment notes | Once you install a mail app on Outlook or Outlook Web App, the mail app is available for that mailbox on both Outlook clients.

Objective evaluation criteria for the object model and PIA

Solutions that run on the client computer can use the Outlook object model or PIA to programmatically access Outlook items, such as contacts, messages, calendar items, meeting requests, and tasks. Unlike MAPI, the Outlook object model and PIA can provide event notifications for Outlook user-interface changes, such as changing the current folder or displaying an Outlook inspector.

Note Note

For a solution to access data that is stored in a Microsoft Exchange mailbox or a personal folders (.pst) file, Outlook must be installed and configured on the client computer on which the application is running.

The Outlook object model and PIA support the same functionality to extend Outlook. The PIA defines managed interfaces that map to the COM-based object model and that a managed solution can interact with. In the remaining discussions in this section, most of the functional, security, and deployment criteria apply to the object model and the PIA in the same way. For more information about how the PIA facilitates interoperability between COM and the .NET Framework, see Introduction to Interoperability Between COM and .NET and Architecture of the Outlook PIA.

The following tables show evaluation criteria for the Outlook object model and PIA.

Functional criteria

Criteria | Outlook object model or PIA
Application domain | Add-ins or standalone applications that use the Outlook object model or PIA typically handle user-specific messages, customize the Outlook user interface, or create custom item types for specialized solutions such as customer relationship management (CRM) solutions that integrate with Outlook. The Outlook object model or PIA is sometimes used for message processing in an informal workflow process, especially where application development on the Microsoft Exchange Server is not permitted. Unlike browser-based clients, cached-mode operation allows Outlook solutions to work when the user is offline or disconnected from the corporate network.
Major objects | The top-level object in the Outlook object model and PIA is the Outlook Application object. Explorers, Conversation, Inspectors, Views, NavigationPane, SolutionsModule, FormRegion, and related objects represent elements of the Outlook user interface. The NameSpace, Stores, Folders, Accounts, AccountSelector, AddressEntries, ExchangeUser, and related objects support extending Outlook sessions, profiles, user accounts, message stores, and folders. At the data level, a number of item-level objects, such as MailItem, AppointmentItem, ContactItem, and TaskItem, represent the built-in Outlook item types. The PropertyAccessor, Table, Search, ItemProperties, UserDefinedProperties, Attachments, Categories, Recipients, RecurrencePattern, Reminders, Rules, and related objects support customizing and manipulating item-level objects.
Data-access model | The Outlook object model and PIA represent all data as a hierarchical set of objects and collections.
Threading models | All calls to the Outlook object model and PIA execute on Outlook's main foreground thread. The only threading model that the Outlook object model supports is single-threaded apartment (STA). Calling the Outlook object model or PIA from a background thread is not supported and can lead to errors and unexpected results in your solution.
Application architectures | Typically, COM add-ins and other Office applications use the Outlook object model to extend Outlook. Managed solutions can use the Outlook PIA and the COM interoperability layer of Visual Studio and the .NET Framework to access the Outlook object model. Visual Studio provides templates and additional class libraries and manifests to facilitate Office document and application customizations. For more information about using Visual Studio to develop managed add-ins for Outlook, see Architecture of Application-Level Add-Ins and Outlook Solutions. The Outlook object model also supports Visual Basic for Applications (VBA) macros and Windows Scripting Host (WSH), but does not support Windows Service applications.
Remote usage | The Outlook object model and PIA can be used only on a computer on which Outlook is installed. The Outlook object model can be used to access information stored in Exchange that is available in the Outlook application.
Transactions | The Outlook object model and PIA do not support transactions.
Availability | The Outlook object model is currently available in all versions of Outlook. The PIA is available in versions of Outlook since Outlook 2003. There have been extensions and improvements with each new version of Outlook.

Development criteria

Criteria | Outlook object model or PIA
Languages and tools | You can implement Outlook object model applications by using any COM or automation-compatible language, such as Visual Basic or C#, as well as non-COM languages, such as native C or C++. Microsoft Office development tools in Microsoft Visual Studio 2010 are the preferred tools for development of managed add-ins for Outlook 2010 and Outlook 2007. Microsoft Visual Studio 2005 Tools for the Microsoft Office System are the preferred tools for Outlook 2003. You can also use Office development tools in Visual Studio 2010 to create solutions for 32-bit and 64-bit versions of Outlook. When you build a solution in Office development tools in Visual Studio 2010 or Microsoft Visual Studio Tools for the Microsoft Office System, specifying the Any CPU option for the target platform results in managed solutions that work for both 32-bit and 64-bit versions of Outlook 2010.
Managed implementation | The Outlook PIA enables the Outlook object model to be used in a managed-code environment, which is supported by a rich set of class libraries and support technologies that address many limitations of VBA and COM add-ins. The PIA is a COM wrapper that acts as a bridge between the managed and COM environments. For more information, see Why Use the Outlook PIA.
Scriptable | The Outlook object model can be used in scripts.
Test and debug tools | No special debugging tools are needed to use the Outlook object model or PIA. On the other hand, you can use Visual Studio to provide an integrated development environment that facilitates application testing and debugging.
Expert availability | Developers who can successfully develop applications by using the Outlook object model or PIA are relatively easy to find. The Outlook object model and PIA are intended for add-ins created by using widely available development tools, such as Visual Studio. These tools provide design-time environments that simplify the development process.
Available information | Information about programming by using the Outlook object model is available in both Microsoft and third-party resources. For more information about the Outlook object model, see the Outlook 2010 Developer Reference. For more information about the Outlook PIA, see the Outlook 2010 Primary Interop Assembly Reference. For examples of managed Outlook solutions developed by using Office development tools in Visual Studio, see Outlook Solutions with Visual Studio.
Developer and deployment licensing | Refer to your Exchange and Microsoft Developer Network (MSDN) subscription licensing agreements to determine whether additional licenses are required for Outlook and Outlook object model use in your applications.

Security criteria

Criteria

Outlook object model or PIA

Design-time permissions

No special permissions are required to develop applications by using the Outlook object model or PIA.

Setup permissions

No special permissions are required to install applications that use the Outlook object model or PIA. However, local administrator rights are required to install Office and Outlook.

Run-time permissions

No special permissions are required to run applications that use the Outlook object model or PIA.

Built-in security features

The Outlook object model and PIA communicate with Exchange by using MAPI and with Active Directory by using Active Directory Service Interfaces (ADSI). The current security context of the user who is running the application is used to determine what resources that code can access. By default, add-ins are trusted for full access to all objects, properties, and methods in the Outlook object model or PIA. IT administrators can exercise control over which add-ins and objects can access the Outlook object model or PIA. The Outlook object model and PIA prevent code that is run outside the Outlook process from accessing secure objects and methods.

Security monitoring features

Outlook monitors the following metrics of an add-in to determine whether it should disable the add-in:

  • Startup

  • Shutdown

  • Folder switch

  • Item open

  • Invoke frequency

Administrators can use group policy to override user settings and control the add-ins that run on the user's computers.

For more information, see Performance criteria for keeping add-ins enabled.

Deployment criteria

Criteria | Outlook object model or PIA
Server platform requirements | The Outlook object model and PIA are client-side technologies.
Client platform requirements | Applications that use the Outlook object model or PIA to access Exchange data require that Outlook be installed on the local computer.
Deployment methods | Applications that use the Outlook object model or PIA are distributed by using standard application installation software.
Deployment notes | Because Outlook should not be installed on the Exchange Server, applications that use the Outlook object model or PIA cannot be run on the Exchange Server.

Objective evaluation criteria for MAPI

You can use MAPI to access items and folders in public and private stores, as well as to access the properties stored with each item. All versions of Outlook use MAPI. You can create clients that use MAPI, and can create MAPI servers and MAPI forms handlers, as well. The information in this section applies only to MAPI client applications.

Note Note

MAPI is a mature mechanism used to access information in Exchange or in a personal folders (.pst) file, and MAPI provides some capabilities that are not available in any other API. However, MAPI does not work well outside an intranet, maintains an open connection for the duration of the MAPI session, and can be difficult to learn. MAPI does not enforce Outlook business logic, so you must take special care to ensure that Outlook business logic is maintained.

The following tables show evaluation criteria for MAPI.

Functional criteria

Criteria | MAPI
Application domain | Client applications that use MAPI access a user mailbox or public folder information stored in Exchange, and user directory information stored in Active Directory. Client applications that use MAPI are typically email clients, such as Outlook, and applications that require complex email processing.
Major objects | MAPI objects are all obtained through the IMAPISession : IUnknown interface. The session object provides the client access to objects for working with MAPI profiles, status, message service provider administration, message store tables, and address books. The message store table contains objects for the message store, folders, messages, attachments, and recipients. The address book tables contain objects for messaging users and distribution lists.
Data-access model | MAPI represents messages and users as a hierarchical set of objects.
Threading models | There are no specific threading prohibitions. However, applications that use free-threading should avoid sharing MAPI objects among threads due to the high costs of marshaling the object. MAPI and MAPI service providers use free-threading.
Application architectures | MAPI client applications are typically Windows Forms-based client applications. However, you can use MAPI to write N-tier applications.
Remote usage | MAPI uses remote procedure calls (RPCs) to communicate with the Exchange Server. Typically RPCs are intentionally blocked from passing through Internet firewalls.
Transactions | MAPI does not support transactions.
Availability | A MAPI stub currently ships with all versions of Windows. Office installs its own MAPI subsystem when it installs Outlook. No changes to MAPI are anticipated at this time.

Development criteria

Criteria | MAPI
Languages and tools | You can directly access MAPI by using C or C++. Other languages that can access the C/C++ calling convention may be able to access MAPI. The use of managed languages, such as Visual Basic or C#, is not supported. You must compile separate MAPI solutions for 32-bit and 64-bit versions of Outlook.
Managed implementation | MAPI is an unmanaged component. Use of MAPI is not supported under the COM interoperability layer of Visual Studio and the .NET Framework. For more information about MAPI support for managed components, see Knowledge Base article 266353: The support guidelines for client-side messaging development.
Scriptable | MAPI cannot be directly used in scripts.
Test and debug Tools | No special debugging tools are needed to debug applications that use MAPI. On the other hand, you can use MFCMAPI. MFCMAPI uses MAPI to provide access to MAPI stores through a graphical user interface, and facilitates investigation of issues when you extend Outlook by using MAPI.
Expert availability | Expert MAPI programmers can be difficult to find, and learning the technology can take a significant amount of time. In addition to the Microsoft communities, there are only a small number of high-quality third-party websites that provide helpful MAPI development information.
Available information | Both Microsoft and third-party books that describe MAPI programming are available.
Developer and deployment licensing | No special licensing is required for developing applications that use MAPI.

Security criteria

Criteria | MAPI
Design-time permissions | The developer must have permissions to access the data in the Exchange store. Exchange stores user and distribution list information in Active Directory, so developers who create MAPI client applications that access that information must have the ability to retrieve and set that information.
Setup permissions | Setting up MAPI-based applications typically requires the user to be a local administrator, or to have rights to install software.
Run-time permissions | Running a MAPI-based application usually requires only that the user has sufficient permissions to access the data on an Exchange store or personal folders (.pst) file.
Built-in security features | MAPI profiles can be password protected on most platforms.

Deployment criteria

Criteria | MAPI
Server platform requirements | The Exchange Server on which user data is stored for users of the MAPI client application must be properly configured to allow access by MAPI clients.
Client platform requirements | The client application installer should verify that the proper version of MAPI is available on the computer, and that it is properly configured by using the Mapisvc.inf file.
Deployment methods | Applications that use MAPI can be deployed to client computers by using standard software distribution technologies.
Deployment notes | The installer should verify that the correct version of MAPI is available.

Decision factors for the apps for Office platform

Because apps for Office use web technologies, they are best for connecting to services in the cloud or on-premises, and bringing the services into the context of the rich client and web client. By requesting appropriate permissions, mail apps also allow reading, writing, or sending items in a mailbox.

The following are common reasons why mail apps are a better choice for developers than add-ins:

  • You can use existing knowledge of and the benefits of web technologies such as HTML, JavaScript, and CSS. For power users and new developers, XML, HTML, and JavaScript require less significant ramp-up time than COM-based APIs, including the object model and MAPI.

  • You can use a simple web deployment model to update your mail app (including the web services that the app uses) on your web server without any complex installation on the Outlook client. In fact, any updates to the mail app, with the exception of the app manifest, do not require any updating on the Office client. You can update the code or user interface of the mail app conveniently just on the web server. This presents a significant advantage over the administrative overhead involved in updating add-ins.

  • You can use a common web development platform for mail apps that can roam across the Outlook rich client and Outlook Web App on the desktop, tablet, and smartphone. On the other hand, add-ins use the object model for the Outlook rich client and, hence, can run on only that rich client on a desktop form factor.

  • You can enjoy rapid turnaround of building and releasing apps via the Office Store.

  • Because of the three-tier permissions model, users and administrators perceive better security and privacy in mail apps than add-ins, which have full access to the content of each account in the user's profile. This, in turn, encourages user consumption of apps.

  • Depending on your scenarios, there are features unique to mail apps that you can take advantage of and that are not supported by add-ins:

    • You can specify a mail app to activate only for certain contexts (for example, Outlook displays the app in the app bar only if the message class of the user-selected appointment is IPM.Appointment.Contoso, or if the body of an email contains a package tracking number or a customer identifier).

    • You can activate a mail app if the selected message contains some known entities, such as an address, contact, email address, meeting suggestion, or task suggestion.

    • You can take advantage of authentication by identity tokens, and of Exchange Web Services.

However, the following features are unique to add-ins and may make them a more appropriate choice than mail apps in some circumstances:

  • You can use add-ins to extend or automate Outlook at an application-level, because the object model and PIA have extensive integration with Outlook features (such as all Outlook item types, user interface, sessions, and rules). At the item-level, add-ins can interact with an item in read or compose mode. With mail apps, you cannot automate Outlook at the application level, and you can extend Outlook's functionality in the context of only the read-mode of the supported items (messages and appointments) in the user's mailbox.

  • You can specify custom business logic for a new item type.

  • You can modify and add custom commands in the ribbon and Backstage view.

  • You can display a custom form page or form region.

  • You can detect events such as sending an item or modifying properties of an item.

  • You can use add-ins on Outlook 2013 and Exchange Server 2013, as well as earlier versions of Outlook and Exchange. On the other hand, mail apps work with Outlook and Exchange starting in Outlook 2013 and Exchange Server 2013, but not earlier versions

For more information about scenarios that the object model and PIA support, see the next section, Decision factors for the object model or PIA. For a comparison of the apps for Office platform with other extensibility technologies for Office, see The background on apps for Office and SharePoint.

Decision factors for the object model or PIA

In general, use the object model or the PIA if your solution customizes the Outlook user interface or relies on Outlook's business logic. Figure 2 shows the major baseline scenarios for which Outlook solutions use the object model or the PIA.

Note Note

For more information about the scenarios, click the boxes in the following figures.

Figure 2. Major baseline scenarios supported by the Outlook object model or PIA

Customize the Outlook UI Use Outlook items Customize item properties, fields, and forms

Process Outlook events

In addition to the baseline scenarios, if your Outlook solution supports any of the scenarios shown in Figure 3, and your solution is intended to run on Outlook 2007 or a later version but not earlier versions, you can use the object model or the PIA, as well. Figure 3 specifies the main objects or members you can use in the Outlook object model to extend each scenario (with the exception of the IDTExtensibility2 interface in the Visual Studio automation object model, and the IRibbonExtensibility interface in the Office object model, which you can integrate with the Outlook object model).

Figure 3. Additional scenarios supported by the object model or PIA since Outlook 2007

Customize the Outlook UI Customize form regions Use PropertyAccessor to access properties

Enumerate and view items in a folder Flag items as tasks Share calendars, RSS feeds, and folders

Manage rules, time zones, and views Add or remove a category

Get detailed information for an account Manage Exchange distribution lists and users Store private data for solutions

If your Outlook solution is intended to run on Outlook 2010 and not earlier versions, you can choose to use the object model or the PIA to support the scenarios shown in Figure 4. Figure 4 specifies the main objects or members you can use in the Outlook object model to extend each scenario (with the exception of the IRibbonControl, IRibbonExtensibility, and IRibbonUI interfaces that are in the Office object model, which you can integrate with the Outlook object model).

Figure 4. More scenarios supported by the object model or PIA since Outlook 2010

Customize the Outlook 2010 UI Manage items in a conversation Manage selection of items in an explorer

Manage selection of attachments in an inspector Support multiple Exchange accounts in one profile Create a contact card for an address entry

Organize solution-specific folders

And if your solution is intended to run on Outlook 2013 and not any earlier version, you can use the object model or the PIA to support the scenarios shown in Figure 5.

Figure 5. Additional scenarios supported by the object model or PIA since Outlook 2013

Display view for all contacts in current folder Inline response in reading pane Show check address or full name dialog for contact

Detecting reading item properties is complete

Decision factors for MAPI

In general, you use MAPI to access data on a MAPI-based server such as the Microsoft Exchange server, and to do tasks such as the following:

  • Create a custom service provider such as an address book provider, transport provider, or store provider.

  • Create a sink process.

  • Create or manipulate a profile.

  • Run an application as a Windows NT service.

  • Run tasks on a background thread. For example, enumerating numerous items in a folder and modifying the items' properties in a background thread can optimize performance.

For more information and code samples, see the Outlook 2013 MAPI Reference and MFCMAPI.

In addition, if your solution runs on a version of Outlook earlier than Outlook 2007, and scenarios such as the following apply to your solution, you should use MAPI to extend those scenarios.

  • Set and get built-in item-level properties that are not exposed in the object model.

  • Manage accounts, attachments, Exchange distribution lists, Exchange users, or stores.

  • Store private data for solutions.

  • Manage a message store for an account.

Since Outlook 2007, the object model has supported a range of features that, prior to Outlook 2007, developers had to resort to MAPI or other APIs such as Microsoft Collaboration Data Objects (CDO) 1.2.1 and Microsoft Exchange Client Extensions. So if any of the scenarios in the previous list applies to your solution, but your solution runs on Outlook 2007 or Outlook 2010, you can and should use the Outlook object model or PIA to support these scenarios. For more information about Outlook 2007 enhancements that unify Outlook development technologies, see What's New for Developers in Outlook 2007 (Part 1 of 2).

Decision factors for the Auxiliary APIs

The Outlook auxiliary APIs can integrate with Outlook business logic or MAPI in some scenarios where the object model or MAPI does not provide a solution. Use the Outlook auxiliary APIs in the following scenarios:

  • Account management: Manage account information, manipulate accounts, provide notification on account changes, and protect accounts from spam.

  • Data degradation: Wrap an object in a preferred character format rather than exposing the object in its native format.

  • Rebasing calendars and time zone support: Rebase Outlook calendars to support daylight saving time.

  • Free/busy status: Provide free/busy information on calendars.

  • Contact pictures: Determine the display of a contact's picture in Outlook.

  • Item currency: Determine whether an Outlook item has unsaved changes.

  • Categorizing an item: Categorize an Outlook item after sending the item.

For more information about the auxiliary APIs, see the Additional resources—Auxiliary APIs section.

Automating Outlook by in-process vs. out-of-process Solutions

Note Note

The discussion of automating Outlook in this section and the next is outside the scope of apps for Office, which are intended to extend the functionality of the Office client or web application but not to automate it.

Outlook supports automation by using add-ins that run in the same foreground process as the Outlook process, and by standalone solutions that run in their own separate process outside of the Outlook process. Generally, to automate Outlook, use an add-in to interact with Outlook through the object model, PIA, or MAPI, and in less common scenarios, through an auxiliary API (such as HrProcessConvActionForSentItem). Use an out-of-process solution only when it's necessary (for example, when you're writing a MAPI client application that uses the Tzmovelib.dll file to rebase Outlook calendars for customers, or enumerating numerous items in a folder and modifying the items' properties in a background thread to optimize performance).

Add-ins are the preferred solution to automate Outlook, because Outlook trusts only the Application object passed to the add-in during the OnConnection(Object, ext_ConnectMode, Object, Array) event of the add-in. You can avoid the display of security warnings of the Object Model Guard by deriving all objects, properties, and methods from this Application object. If the add-in creates a new instance of the Application object, Outlook does not trust that object, even if the add-in is on the list of trusted add-ins. Any objects, properties, and methods derived from such an Application object will not be trusted and the blocked properties and methods will invoke security warnings. For more information about the Outlook Object Model Guard, see Security Behavior of the Outlook Object Model.

Automating Outlook by managed vs. unmanaged solutions

Outlook supports automation by add-ins and standalone applications, written in managed or unmanaged languages. The more commonly used managed languages are C# and Visual Basic. C++ and Delphi tools are more common in unmanaged development. Available expertise is one consideration when choosing between managed and unmanaged development.

If your solution uses only the object model, you can consider developing a managed solution by using the PIA, or Office development tools in Visual Studio. The Office development tools in Visual Studio provide project templates and visual designers that simplify creating custom user interfaces and developing Office solutions.

On the other hand, because MAPI was developed years before the .NET Framework, and Microsoft does not provide managed wrappers for MAPI, Microsoft does not support using MAPI in managed code. If you are using MAPI, you must develop an unmanaged solution. For more information, see The support guidelines for client-side messaging development.

Niche APIs and technologies

The Outlook Social Connector (OSC) and Weather Bar support extending very specific scenarios in Outlook.

Outlook Social Connector (OSC) provider extensibility

The Outlook Social Connector (OSC) provider extensibility supports developing a provider for a social network to allow users to view, in Outlook and other Office client applications, friends and activities updates on that social network. Figure 6 shows the OSC displaying in the People Pane the activities of a person in social network sites.

Figure 6. The OSC displaying social network data in the People Pane

Outlook Social Connector pane

The OSC in Outlook allows users to view, in the People Pane, an aggregation of emails, attachments, and meeting requests from a person in Outlook. In an organizational environment, users who collaborate on a SharePoint site can see document updates and other site activities of this person on the SharePoint site. Outlook Social Connector provider extensibility supports developing a provider for the OSC to synchronize and surface social network updates in Outlook. Common OSC providers (such as Facebook and LinkedIn) are installed by default with Outlook. Depending on the social network sites that an Outlook user has signed into, the user can see, in the People Pane, updates such as photos, status, and activities on the corresponding social networks.

Weather Bar extensibility

Starting in Outlook 2013, the Weather Bar allows developers to plug in a third-party weather web service for the Weather Bar, to provide weather conditions data for a user-chosen location. The Weather Bar in Outlook displays weather conditions and forecast for a geographic location. A user can choose one or multiple locations, and conveniently see weather data in the Weather Bar in the calendar module. Figure 7 shows the Weather Bar displaying a three-day forecast for New York, NY.

Figure 7. Weather Bar in Outlook

Weather Bar showing forecast for New York.

By default, Outlook uses weather data provided by MSN Weather. The Weather Bar supports third-party weather data web services which follow a defined protocol to communicate with Outlook. As long as a third-party weather data service supports this protocol, users can choose that weather data service to provide weather data in the Weather Bar.

See the Additional resources—primary references, resources, and code samples section for more information about using OSC provider extensibility and the Weather Bar extensibility.

Conclusion

To determine the best API or technology for your solution, you must first define the goals of your solution:

  • The versions of Outlook you intend your solution to support.

  • The high-priority scenarios of your solution. Does your solution mainly interact with the content and properties of a message or appointment item? Or does your solution automate Outlook at an application level? If so, do these scenarios involve enumerating, filtering, or modifying folders that contain many Outlook items?

First, verify whether the mail app support in the apps for Office platform meets your needs. See the Functional Criteria section of Objective evaluation criteria for the apps for Office platform to determine whether the major objects and features support your scenarios. See the section Decision factors for the apps for Office platform to verify whether mail apps are a better choice than add-ins for your scenarios. In general, develop your solution as an app, if possible, to take advantage of the platform's support across Outlook clients over different form factors.

If your scenarios require you to extend beyond message and appointment items, or require you to automate Outlook at an application level, try to match your scenarios with those outlined in the section Decision factors for the object model or PIA. If the object model (or PIA) of your target Outlook versions supports your scenarios, and your solution does not manipulate folders with many items, you should implement your solution as an add-in, in either a managed or unmanaged language.

If the object model (or PIA) of a target Outlook version does not support some of your scenarios, verify whether the scenarios in the Decision factors for MAPI or Decision factors for the Auxiliary APIs section meet your needs. If MAPI meets your needs, you should implement your solution in unmanaged code. If an auxiliary API solves one of your scenarios, you can use managed or unmanaged code.

If your solution uses MAPI, you must implement it in unmanaged code, such as C++. Otherwise, the decision to use managed or unmanaged code to create the solution generally depends on your available resources and their expertise. As for deciding whether to implement the solution as an add-in or standalone application, choose an add-in to avoid the user constantly invoking the Outlook Object Model Guard, unless your scenario requires manipulation of folders that contain numerous items. In the latter scenario, implementing the solution to run as a background thread can optimize Outlook performance.

If your scenarios include showing social network information or updates in Outlook, you should use the OSC provider extensibility to create a COM-visible DLL. You can do this in either a managed or unmanaged language.

If you are interested in plugging in a third-party weather data service to the Weather Bar, you can follow the protocol defined by Weather Bar extensibility and provide the appropriate web services. You can create these web services in a managed language.

Once you have decided on the APIs or technologies to use in your solution, you can refer to additional documentation and code samples in the Additional resources—primary references, resources, and code samples section for more information.

Additional resources—apps for Office

Overview of apps for Office provides a good introduction of apps for Office, including the architecture and development life cycle.

See Mail apps for Outlook for a detailed roadmap of resources about developing mail apps.

Privacy and security

  • Privacy and security for apps for Office

  • Privacy and security for mail apps in Outlook 2013 Preview

  • Using the permission model for mail apps in Outlook

Activating mail apps

  • Defining rules to show a mail app in Outlook 2013 Preview

  • Using regular expressions to show a mail app in Outlook 2013 Preview

  • Using well-known entities in a mail app for Outlook 2013 Preview

Mail apps for different form factors

  • Designing a mail app for specific form factors in Outlook 2013 Preview

API references

  • JavaScript API for Office

  • Schema reference for apps for Office manifests

Additional resources—object model and PIA

The following resources provide more information about using the object model and PIA.

Accounts—primary Exchange account in profile

  • Account object

  • NameSpace.Accounts property

Accounts—multiple accounts in profile

  • Account object

  • Using Multiple Accounts for the Same Profile on Outlook

  • How to: Obtain Information for Multiple Accounts

  • Manipulating Multiple Exchange Accounts in Outlook 2010

Address book and Exchange users

  • Display Names from the Address Book

  • Access Exchange User or Distribution List Information from the Address Book

  • How to: List the Groups that My Manager Belongs to

  • How to: List the Name and Office Location of Each Manager Belonging to an Exchange Distribution List

  • AddressEntries object

  • AddressLists object

  • ExchangeDistributionList object

  • ExchangeUser object

  • SelectNamesDialog object

Attachments

  • How to: Attach a File to a Mail Item

  • Attachment file types restricted by Outlook 2010

  • Attachment object

  • AttachmentSelection object

  • AttachmentAdd event per item object

  • AttachmentRead event per item object

  • AttachmentRemove event per item object

  • BeforeAttachmentAdd event per item object

  • BeforeAttachmentPreview event per item object

  • BeforeAttachmentRead event per item object

  • BeforeAttachmentSave event per item object

  • BeforeAttachmentWrite event per item object

Attachments: selection in inspector

  • Inspector.AttachmentSelection property

  • Inspector.AttachmentSelectionChange event

Automating Outlook

  • Customizing Outlook using COM add-ins

  • Building a C++ Add-in for Outlook 2010

  • Introduction to Interoperability Between COM and .NET

  • Why Use the Outlook PIA

  • Best Practices in Developing Managed Outlook Add-Ins

  • How to: Obtain and Log On to an Instance of Outlook

  • Automating Outlook from a Visual Basic Application

  • Automating Outlook from Other Office Applications

Categories

  • Categorize Your Outlook Items

  • Category object

  • NameSpace.Categories property

Contacts: check address and full name

  • ContactItem.ShowCheckAddressDialog method

  • ContactItem.ShowCheckFullNameDialog method

Conversations

  • Managing Outlook Items as Conversations

  • How to: Obtain and Enumerate Selected Conversations

  • Conversation object

  • ConversationHeader object

  • SimpleItems object

  • ConversationID property per item object

Events

  • Working with Outlook Events

  • How to: Implement a Wrapper for Inspectors and Track Item-Level Events in Each Inspector

Explorer: inline response

  • Explorer.ActiveInlineResponse property

  • Explorer.ActiveInlineResponseWordEditor property

  • Explorer.InlineResponse event

Items: basic properties, fields, and forms

  • Outlook Item Objects

  • ItemProperties object

  • UserProperties object

  • Standard Fields Overview

  • Outlook Fields and Equivalent Properties

  • Custom Fields and Data Types Overview

  • Customizing Form Pages and Form Regions

Items: customizing properties

  • Properties Overview

  • Efficiently Getting and Setting Custom Properties in a Contact Folder in Outlook 2010

  • PropertyAccessor object

Items: enumerating, filtering, and sorting

  • Storing Outlook Items

  • Default Properties Displayed in a Table Object

  • Efficiently Filtering Contact Items in a Contact Folder in Outlook 2010

  • Enumerating, Searching, and Filtering Items in a Folder

  • Sorting Items in a Folder

  • Table object

Items: flag as tasks

See the following task-related properties in some item objects such as the MailItem object:

  • TaskCompleteDate property

  • TaskDueDate property

  • TaskStartDate property

  • TaskSubject property

  • ToDoTaskOrdinal property

Items: selection in explorer

  • Selection.GetSelection method

  • Selection.Location property

Miscellaneous: business cards, rules, and views

  • Customize and Share Business Cards

  • Managing Rules in the Outlook Object Model

  • How to: Create a Rule to Move Specific E-mails to a Folder

  • Rules object

  • RuleActions object

  • RuleConditions object

  • TimeZones object

  • Outlook Views

  • Views object

Security

  • Security Behavior of the Outlook Object Model

  • Shutdown Changes for Outlook 2010

  • Attachment file types restricted by Outlook 2010

  • Application Shutdown Changes in Outlook 2007 SP2

  • Code Security Changes in Outlook 2007

Sharing

  • Sharing Calendars

  • Sharing Online Calendars, RSS Feeds, Microsoft SharePoint Foundation Folders, and Exchange Folders

  • SharingItem object

Solutions: solution-specific folders

  • Programming the Outlook 2010 Solutions Module

  • SolutionsModule object

Solutions: storing data

  • Storing Data for Solutions

  • StorageItem object

User interface: customizing form regions

  • Customizing Form Pages and Form Regions

  • Form Regions

  • How to: Create a Form Region

  • Walkthrough: Add a Form Region to an Existing Page on a Form

  • Building an Outlook 2007 Form Region with a Managed Add-In

  • Implementing a Form Region to Display Email Headers in Outlook 2010

  • FormRegion object

  • FormRegionStartup object

User interface: customizing since Outlook 2007

  • Overview of Customizing the Ribbon

  • Customizing the Ribbon in Outlook 2007

  • Developing Interfaces in Outlook 2007

  • Custom Task Panes Overview

  • Targeting User Interface Solutions to the 2007 and 2010 Releases of Microsoft Office

  • Customizing the Navigation Pane

  • Outlook View Control Object Model Reference

  • IDTExtensibility2 interface

  • IRibbonExtensibility object

  • NavigationPane object

User interface: customizing since Outlook 2010

  • Extending the User Interface in Outlook 2010

  • Office Fluent User Interface Extensibility for Outlook

  • Programming the Outlook 2010 Solutions Module

  • Customizing the Context Menu of a Contact Card in Outlook 2010

  • IRibbonControl object

  • IRibbonExtensibility object

  • IRibbonUI object

User interface: solutions-specific folders

  • Programming the Outlook 2010 Solutions Module

  • Adding Solution-Specific Folders to the Solutions Module in Outlook 2010

  • SolutionsModule object

Additional resources—Auxiliary APIs

The following resources provide more information about the Outlook auxiliary APIs.

Account management

  • About the Account Management API

  • Account management API reference

  • About anti-spam settings

Categorizing items

  • HrProcessConvActionForSentItem

Contact pictures

  • How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)

Data degradation

  • About the Data Degradation Layer API

  • Data degradation layer API reference

Free/busy status

  • About the Free/Busy API

  • How to: Use relative time to access free/busy data

  • Free/busy API reference

Item currency

  • How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)

Rebase calendars

  • About rebasing calendars programmatically for Daylight Saving Time

  • About persisting TZDEFINITION to a stream to commit to a binary property

  • How to: Parse a stream from a binary property to read the TZDEFINITION structure

  • How to: Parse a stream from a binary property to read the TZREG structure

  • How to: Read time zone properties from an appointment

Additional resources—primary references, resources, and code samples

The following resources provide more information about the primary Outlook references, resources, and code samples.

Major references and resources

  • Build apps for Office

  • Outlook 2013 developer reference

  • Outlook 2010 Primary Interop Assembly Reference

  • Outlook 2013 MAPI Reference

  • Outlook 2013 Auxiliary Reference

  • Outlook Social Connector 2013 provider reference

  • Extending the Weather Bar in Outlook 2013

  • Outlook Weather Information XML Schema

  • Outlook Weather Location XML Schema

  • What's New in XML Schemas for Outlook 2010

  • Outlook 2010: XML Schema Reference

  • Developing Outlook 2010 Solutions for 32-Bit and 64-Bit Systems

Code samples

  • Mail apps samples

  • Object model code samples: How do I... (Outlook 2013 developer reference)

  • PIA code samples: How Do I... in Outlook 2010

  • MAPI Samples

  • Auxiliary API code samples: Sample tasks


Welcome to the Outlook 2013 developer reference

 Copy code hover
[image]

Welcome to the Outlook 2013 developer reference
Send feedback

Published: July 23, 2013

This reference contains conceptual overviews, programming tasks, samples, and references to guide you in developing solutions based on the object model for Outlook 2013.

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs.

We welcome your comments or questions about this content. You can send feedback to docthis@microsoft.com.

Versions of this documentation are accessible from the following locations:

  • From the MSDN Library: See the Outlook 2013 Developer Reference in the MSDN Library.

  • From the product: If you are connected to the Internet, you can view the version of this reference as posted on MSDN Library from within Outlook. On the Developer tab in the ribbon, choose Visual Basic. In the Visual Basic editor, choose Help, Microsoft Visual Basic for Applications Help.

    Note Note

    For the Outlook 2013 release, viewing from the product currently opens the Outlook 2010 help on MSDN. Use the MSDN TOC to navigate to the Outlook 2013 help.

This documentation contains the following information:

  • New objects, collections, and enumerations: Provides a list of new objects and enumerations. For more information about new programmability features in Outlook 2013, see What's new for Outlook 2013 developers in the MSDN Library.

  • New members and constants: Provides a list of new members by object and in alphabetical order.

  • Concepts: Provides important concepts for developing custom Outlook solutions.

  • How do I ... in Outlook: Provides a list of how-to topics for developing custom Outlook solutions.

  • Reference: Provides reference materials for the Outlook object model. This includes the Outlook object model reference, View Control reference, and Forms Script reference.

Note Note

The Outlook Forms Script reference includes documentation for the more commonly used objects, controls, and members in Outlook forms. For more information, you can refer to the Microsoft Forms Visual Basic reference, which you can find in the Visual Basic for Applications language reference.

Additional resources

  • Outlook 2013

  • Outlook for developers

  • Accessibility in Microsoft Products

  • Document Conventions

  • Outlook 2013 Developer Reference Copyright Information

  • Microsoft Online Privacy Notice


New objects, collections, and enumerations (Outlook)

 Copy code hover
[image]

New objects, collections, and enumerations (Outlook)
Send feedback

New Objects

The following object has been added to the object model in Outlook 2013.

Object or Collection | Description
PeopleView | Represents a view that displays a list of all the contacts in the current Contacts folder, and details for a selected contact.

There are no new collections or enumerations in the Outlook 2013 release. For new members and constants added to existing objects and enumerations, see New members and constants (Outlook)


New members and constants (Outlook)

 Copy code hover
[image]

New members and constants (Outlook)
Send feedback

New Members

The following properties, methods, and events have been added to existing objects in Outlook 2013.

AppointmentItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

ContactItem

Methods | Description
ShowCheckAddressDialog | Displays the Check Address dialog box to verify address details of the contact.
ShowCheckFullNameDialog | Displays the Check Full Name dialog box to verify name details of the contact.
Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

DistListItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

DocumentItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

Explorer

Properties | Description
ActiveInlineResponse property | Returns an item object representing the active inline response item in the explorer reading pane. Read-only.
ActiveInlineResponseWordEditor property | Returns the Word Document object of the active inline response that is displayed in the explorer Reading Pane. Read-only.
Events | Description
InlineResponse event | Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.
InlineResponseClose | Occurs when the user performs an action that causes the active inline response to close in the Reading Pane.

JournalItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

MailItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

MeetingItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

PeopleView

Properties | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the PeopleView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the PeopleView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.
Methods | Description
Apply | Applies the PeopleView object to the current view.
Copy | Creates a new View object based on the existing PeopleView object.
Delete | Deletes this object from the collection of views in the current folder.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets this built-in Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

PostItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

RemoteItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

ReportItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

SharingItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

TaskItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

TaskRequestAcceptItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

TaskRequestDeclineItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

TaskRequestItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

TaskRequestUpdateItem

Events | Description
ReadComplete | Occurs when Outlook has completed reading the properties of the item.

New Constants

The following constants have been added to existing enumerations in Outlook 2013.

Enumeration

New Constants

OlAccountType

  • olEas

OlBusyStatus

  • olWorkingElsewhere

OlObjectClass

  • olClassPeopleView

OlSearchScope

  • olSearchScopeCurrentStore

OlViewType

  • olPeopleView

  • olMobileItemSMS


Concepts (Outlook 2013 developer reference)

 Copy code hover
[image]

Concepts (Outlook 2013 developer reference)
Send feedback

This section provides important concepts for developing custom Outlook solutions. You can use the table of contents to navigate through the topics.


General Concepts

 Copy code hover
[image]

General Concepts
Send feedback

In this section

  • Using Macros to Customize Outlook

  • Using Visual Basic to Automate Outlook


Using Macros to Customize Outlook

 Copy code hover
[image]

Using Macros to Customize Outlook
Send feedback

In this section

  • Using Visual Basic for Applications in Outlook

  • Writing an Outlook Macro

  • Working with forms in the Visual Basic Editor

  • Using Outlook Visual Basic for Applications to Respond to Outlook Events


Using Visual Basic for Applications in Outlook

 Copy code hover
[image]

Using Visual Basic for Applications in Outlook
Send feedback

Visual Basic for Applications (VBA) makes it easy to control Microsoft Outlook within Microsoft Outlook itself. Using VBA in Outlook, you can create macros that perform complex or repetitive tasks automatically. You can also develop program code that responds to Outlook events, allowing you to automate common tasks (such as arranging windows when Outlook starts).

Visual Basic for Applications allows you to take almost full advantage of the Outlook object model, including the wide range of application-level events, without requiring you to run an external application (such as another Microsoft Office application or an application developed using Microsoft Visual Basic). And unlike form scripts developed using Microsoft Visual Basic Scripting Edition (VBScript), Outlook Visual Basic for Applications code is always available in the application; an item does not have to be open to run the code.

All Outlook Visual Basic for Applications code is contained in a project. The project is associated with a particular user, so all users who run Outlook on a computer can customize Outlook to meet their own needs. A project can contain code modules and User Form modules (note that User Form modules are not the same as Outlook forms ).

You use the Visual Basic Editor to create and remove modules, to design User Form modules, and to edit code in modules. This editor provides a powerful set of tools, including a built-in Object Browser and debugger to make developing and troubleshooting code easy. You can even use the Visual Basic Editor in Outlook to develop and test code that you can then copy to a standalone Visual Basic application or a Visual Basic for Applications application in another Microsoft Office application.

Managing Multiple Visual Basic for Applications Projects

Outlook supports only one Visual Basic for Applications project, Project1, at a time. You cannot add and run another project in the Visual Basic Editor at the same time. Project1 is stored on your hard disk as VbaProject.OTM; each user on the same computer can have a copy of VbaProject.OTM stored for him or her. On a computer running Windows XP, VbaProject.OTM is in <drive>:\Documents and Settings\<user>\Application Data\Microsoft\Outlook.

Because you can run only one Visual Basic for Applications project at a time, before you run a different project, you should exit Outlook, rename the current VbaProject.OTM with a different file name, name the project you want to run as VbaProject.OTM, and restart Outlook to run it. If appropriate, you can also manually integrate the projects to form one VbaProject.OTM to avoid the file naming and renaming.

Outlook Visual Basic for Applications code was designed to be a personal macro development environment, and was not designed to be deployed or distributed. To move a project from one computer to another, for example, moving the project from your work computer to your home computer, you can export the forms and code modules from the work computer and import them to the home computer. You can also copy and paste the source code of the project to Project1 on the home computer using the Visual Basic Editor.

If you are developing a solution that you intend to distribute to more than a few people, you should convert your Visual Basic for Applications code into an Outlook COM Add-in. However, developing a COM Add-in typically requires considerably more programming knowledge than creating a short macro, so if your Visual Basic for Applications project is relatively simple, and there are not too many people who need to use it, you may want to send them the code with instructions on how to set it up.


Writing an Outlook Macro

 Copy code hover
[image]

Writing an Outlook Macro
Send feedback

A macro is any public subroutine in a code module. A function or a private subroutine cannot be a macro, and a macro cannot be located in a class or form module.

To create a new macro

  1. In Outlook, on the Developer tab of the Microsoft Office Fluent ribbon, click Visual Basic.

  2. In the Project window, double-click the module you want to contain the macro.

  3. On the Insert menu, click Procedure.

  4. In the Name box, type a name for the macro. The name cannot contain spaces.

  5. Click OK. The template for the macro subroutine appears in the code module window.

  6. Type the code you want to run in the body of the subroutine.

For more information about using the Visual Basic Editor, see the Visual Basic Editor Help.

Once you've created a macro, you can create a menu item or toolbar button that will run the macro when you click it.


Working with forms in the Visual Basic Editor

 Copy code hover
[image]

Working with forms in the Visual Basic Editor
Send feedback

You can use the Visual Basic Editor to design a form that allows your users to interact with your Microsoft Visual Basic for Applications (VBA) program. Unlike an Outlook form, a Visual Basic for Applications form is not used to display an Outlook item, nor can a control on a Visual Basic for Applications form be bound to an item field.

Your Visual Basic for Applications program can use a Visual Basic for Applications user form to gather information from your users; your program can then use this information to set properties of new or existing Outlook items. For example, a program that creates a boilerplate mail message could use a Visual Basic for Applications form to allow the user to enter the specific information for the message to be sent. When the user closes the form, the program uses the information in the form to set the properties of the mail message and then sends the message.

The following sample uses the text in two text boxes to add information to a message before sending it.

Copy code Copy code
Private Sub CommandButton1_Click()
 Dim myMail As Outlook.MailItem
 Set myMail = Application.CreateItem(olMailItem)
 With myMail
 .To = TextBox1.Text
 .Subject = "Book overdue: " & TextBox2.Text
 .Body = "Please return this book as soon as possible."
 End With
 myMail.Send
End Sub

You can also use controls to display information about Outlook items, folders, and other features of the Outlook object model. The following example shows how to fill a combo box control with the subjects of the items in the user's Inbox.

Copy code Copy code
Dim myItems As Outlook.Items
Set myItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Items
For x = 1 To myItems.Count
 ComboBox1.AddItem myItems.Item(x).Subject
Next x

For more information about creating and using forms in the Visual Basic Editor, see the Visual Basic Editor Help.


Using Outlook Visual Basic for Applications to Respond to Outlook Events

 Copy code hover
[image]

Using Outlook Visual Basic for Applications to Respond to Outlook Events
Send feedback

You write an event procedure (also known as an event handler) to respond to events that occur in Microsoft Outlook. For example, you can write an event procedure that automatically maximizes the explorer window when Outlook starts.

Events are associated with particular objects. The Application object is the topmost object, and is always available (that is, it does not have to be created). You can add an Application event procedure in the ThisOutlookSession module window simply by selecting Application in the left list and then selecting the event in the right list.

Adding an event handler for objects other than the Application object requires a few additional steps.

First, you must declare a variable using the WithEvents keyword to identify the object whose event you want to handle. For example, to declare a variable representing the OutlookBarPane object, you would add the following to a code module.

Copy code Copy code
Dim WithEvents myOlBar as Outlook.OutlookBarPane

You can then select myOlBar in the Objects list of the module window and then select the event in the procedure list. The Visual Basic Editor will then add the template for the event procedure to the module window. You can then type the code you want to run when the event occurs. The following example shows code added to the BeforeNavigate event procedure for the OutlookBarPane object.

Copy code Copy code
Private Sub myOlBar_BeforeNavigate(ByVal Shortcut As OutlookBarShortcut, Cancel As Boolean)
 If Shortcut.Name = "Notes" Then
 MsgBox "You cannot open the Notes folder."
 Cancel = True
 End If
End Sub

The final step is to add code to set the object variable to the object whose event you want to handle. This code can exist in a macro, or if you want the event to be handled whenever Outlook runs, you can put it in the Startup event procedure, as in the following example.

Copy code Copy code
Private Sub Application_Startup()
 Set myOlBar = Application.ActiveExplorer.Panes(1)
End Sub


Using Visual Basic to Automate Outlook

 Copy code hover
[image]

Using Visual Basic to Automate Outlook
Send feedback

In this section

  • Automating Outlook from a Visual Basic Application

  • Automating Outlook from Other Office Applications

  • Support for COM Add-ins

  • Customizing Outlook using COM add-ins

  • Outlook COM add-in template

  • OLE Programmatic Identifiers (Outlook)

  • Support for Custom Property Pages

  • Adding Custom Property Pages

  • Support for Contact Linking

  • Support for Folder Synchronization

  • How to: Verify Whether Outlook Is a Click-to-Run Application on a Computer


Automating Outlook from a Visual Basic Application

 Copy code hover
[image]

Automating Outlook from a Visual Basic Application
Send feedback

Because Microsoft Outlook supports Automation, you can control Outlook from any program that is written with Microsoft Visual Basic. Automation provides a standard method for one application to access the objects, methods, properties, and events of other applications that support Automation.

The Outlook object model provides all of the functionality necessary to manipulate data that is stored in Outlook folders, and it provides the ability to control many aspects of the Outlook user interface (UI).

To start an Outlook Automation session, you can use either early or late binding. Late binding uses either the Visual Basic GetObject function or the CreateObject function to initialize Outlook. For example, the following code sets an object variable to the Outlook Application object, which is the highest-level object in the Outlook object model. All Automation code must first define an Outlook Application object to be able to access any other Outlook objects.

Copy code Copy code
Dim objOL as Object
Set objOL = CreateObject("Outlook.Application")

To use early binding, you first need to set a reference to the Outlook object library. Use the Reference command on the Visual Basic for Applications (VBA) Tools menu to set a reference to Microsoft Outlook xx.x Object Library, where xx.x represents the version of Outlook that you are working with. You can then use the following syntax to start an Outlook session.

Copy code Copy code
Dim objOL as Outlook.Application
Set objOL = New Outlook.Application

Most programming solutions interact with the data stored in Outlook. Outlook stores all of its information as items in folders. Folders are contained in one or more stores. After you set an object variable to the Outlook Application object, you will commonly set a NameSpace object to refer to MAPI, as shown in the following example.

Copy code Copy code
Set objOL = New Outlook.Application
Set objNS = objOL.GetNameSpace("MAPI")
Set objFolder = objNS.GetDefaultFolder(olFolderContacts)

Once you have set an object variable to reference the folder that contains the items you wish to work with, you use appropriate code to accomplish your task, as shown in the following example.

Copy code Copy code
Sub CreateNewDefaultOutlookTask()
    Dim objOLApp As Outlook.Application
    Dim NewTask As Outlook.TaskItem
    ' Set the Application object
    Set objOLApp = New Outlook.Application
    ' You can only use CreateItem for default items
    Set NewTask = objOLApp.CreateItem(olTaskItem)
    ' Display the new task form so the user can fill it out
    NewTask.Display
End Sub

If you are using VBA to create macros, there are two ways you can automate Outlook. You can implement a macro that creates a new instance of the Outlook Application object. The CreateNewDefaultOutlookTask() method above shows how to call New Outlook.Application to create a new Application object instance.

Caution note Caution

This new instance of Outlook is not trusted and can trigger the object model guard. For more information about the object model guard, see What's New for Developers in Outlook 2007 (Part 1 of 2).

As an alternative to creating and automating a separate instance of Outlook, you can use VBA to implement a macro that automates the current instance of Outlook. To do so, use the Application object intrinsic to the environment. This Application object is trusted and can avoid triggering the object model guard. For more information about the object model guard, see What's New for Developers in Outlook 2007 (Part 1 of 2). The following example shows the CreateAnotherNewDefaultOutlookTask() method using the Application object from the current instance of Outlook.

VBA Copy code Copy code
Sub CreateAnotherNewDefaultOutlookTask()
    Dim NewTask As Outlook.TaskItem

    ' You can only use CreateItem for default items
    Set NewTask = Application.CreateItem(olTaskItem)
    ' Display the new task form so the user can fill it out
    NewTask.Display
End Sub


Automating Outlook from Other Office Applications

 Copy code hover
[image]

Automating Outlook from Other Office Applications
Send feedback

You can use Microsoft Visual Basic for Applications (VBA) in any Microsoft Office application to control Microsoft Outlook. For example, if you are developing a cross-application solution using one primary application and several secondary applications, you can write VBA code in the primary application to automate Outlook to send messages and to store and retrieve information in Outlook items. For example, in Microsoft Office Excel you can write routines that send a workbook to an Outlook distribution list.

To control Outlook objects from outside Outlook, you must establish a reference to the Outlook object library from the project in which you are writing code. To do this, use the References dialog box in the Visual Basic Editor in the primary application. You can then write code that returns a reference to the Outlook Application object. Through this reference, your code has access to all the objects, properties, methods, and constants defined in the Outlook type library.

There are several ways to return a reference to the Outlook Application object.

  • You can use the CreateObject function to start a new session of Outlook and return a reference to the Application object that represents the new session.

  • You can use the Visual Basic GetObject function to return a reference to the Application object that represents a session that is already running. Note that because there can be only one instance of Outlook running at any given time, GetObject usually serves little purpose when used with Outlook. CreateObject can always be used to access the current instance of Outlook or to create a new instance if one does not exist. However, you can use error trapping with the GetObject method to determine whether Outlook is currently running.

  • You can use the New keyword in several types of statements to implicitly create a new instance of the Outlook Application object by using the Set statement to set an object variable to the new instance of the Application object. You can also use the New keyword with the Dim, Private, Public, or Static statement to declare an object variable. The new instance of the Application object is then created on the first reference to the variable.

Caution note Caution

When you create a new instance of Outlook, the new instance is not trusted and can trigger the object model guard. For more information about the object model guard, see What's New for Developers in Outlook 2007 (Part 1 of 2)What's New for Developers in Outlook 2007 (Part 1 of 2).

For examples of using these methods of referencing the Outlook Application object, see Automating Outlook from a Visual Basic Application.


Support for COM Add-ins

 Copy code hover
[image]

Support for COM Add-ins
Send feedback

Microsoft Outlook allows you to enhance and extend the application using Component Object Model (COM) add-ins. A COM add-in is a dynamic-link library (DLL) that's specially registered so that it can be loaded by an Office XP application. You can build a COM add-in with a variety of languages, such as Microsoft Visual Basic and Microsoft Visual C++.

The COMAddIns property of the Application object gives you access to the COM add-ins loaded by Outlook.

Learn more about customizing Outlook using COM add-ins.


Customizing Outlook using COM add-ins

 Copy code hover
[image]

Customizing Outlook using COM add-ins
Send feedback

Creating a COM add-in involves two major steps:

  1. Implement the IDTExtensibility2 interface in a class module of a dynamic link library (DLL).

  2. Register the COM add-in.

Implement the IDTExtensibility2 Interface

The IDTExtensibility2 interface consists of five event procedures. To implement this interface in a Visual Basic program, set a reference to the Microsoft Add-In Designer object library and then add the following statement to the Declarations section of a class module:

Copy code Copy code
Implements IDTExtensibility2

You can then add the empty event procedures to the code window of the class module and add your own program code to the procedures. You can also copy the empty procedures from an Outlook COM Add-in Template.

Register the COM add-in

In order to work with Outlook, the add-in DLL must be registered. The DLL's class ID is registered beneath the \HKEY_CLASSES_ROOT subtree in the registry.

In addition, information about the add-in must be added to the registry. This information provides the add-in's name, description, target application, initial load behavior, and connection state.

Note Note

If you use Microsoft Visual Basic 6.0 or later Developer to design your COM add-in, the add-in designer will perform the steps required to register the COM add-in for you.

The following example shows the contents of a sample registry-editor (.reg) file that illustrates how to register an Outlook COM add-in.

Copy code Copy code
[HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\Addins\SampleAddIn.AddInIFace]
"FriendlyName"="Sample Add-in"
"Description"="Sample Outlook Add-In"
"LoadBehavior"=dword:00000008

When the COM add-in is first registered, LoadBehavior can be set to any of the following flags.

Value | Description
2 | Load at startup. The COM add-in is to be loaded and connected when Outlook starts.
8 | Load on demand. The COM add-in is to be loaded and connected only when the user requests it, such as by using the COM Add-ins dialog box.
16 | Connect first time. The COM add-in is loaded and connected the first time the user runs Outlook after the COM add-in has been registered. The next time Outlook is run, the COM add-in is loaded when the user requests it. Use this value if your COM add-in modifies the user interface to allow the user to request the COM add-in be connected on demand (by clicking a button, for example).

After the COM add-in is registered and loaded, the LoadBehavior value can be combined with either of the following two flags to indicate current connection state of the COM add-in.

Flag | Description
0 | Disconnected
1 | Connected

To connect the COM add-in, set the Connected flag in LoadBehavior; clear the flag to disconnect the COM add-in.

The FriendlyName value specifies the name of the COM add-in as it's displayed in the COM Add-in dialog box. The Description value provides additional information about the COM add-in.


Outlook COM add-in template

 Copy code hover
[image]

Outlook COM add-in template
Send feedback

The following code example provides the empty event procedures required to implement a COM add-in.

Copy code Copy code
Implements IDTExtensibility2

Private Sub IDTExtensibility2_OnAddInsUpdate(custom() As Variant)
' Occurs when the set of connected COM add-ins changes, that is when
' any other add-in is connected or disconnected.
' The custom argument is ignored.
End Sub

Private Sub IDTExtensibility2_OnBeginShutdown(custom() As Variant)
' If the COM add-in is connected, occurs when Outlook begins its
' shutdown routines.
' The custom argument is ignored.

End Sub

Private Sub IDTExtensibility2_OnConnection(ByVal Application As Object, ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, ByVal AddInInst As Object, custom() As Variant)
' Occurs when the COM add-in is connected.
' The Application argument is the Outlook Application object.
' The ConnectMode argument specifies how the COM add-in was connected.
' It can be
' ext_cm_AfterStartup Add-in was connected after Outlook started,
' or the Connect property of the corresponding
' COMAddIn object was set to True
' ext_cm_Startup Add-in was connected on startup
' ext_cm_External
' ext_cm_CommandLine
' The AddInInst argument is the COMAddIn object that refers to the current
' instance of the add-in itself.
' The custom argument is ignored.
End Sub

Private Sub IDTExtensibility2_OnDisconnection(ByVal RemoveMode As AddInDesignerObjects.ext_DisconnectMode, custom() As Variant)
' Occurs when the COM add-in is disconnected.
' The RemoveMode argument specifies how the COM add-in was disconnected.
' It can be
' ext_dm_HostShutdown Add-in was disconnected when Outlook was
' closed.
' ext_dm_UserClosed Add-in was disconnected when the user
' cleared the corresponding check box in the
' COM Add-ins dialog box, or the Connect
' property of the corresponding COMAddIn
' object was set to False.
' The custom argument is ignored.
End Sub

Private Sub IDTExtensibility2_OnStartupComplete(custom() As Variant)
' If the COM add-in connects at startup, occurs when Outlook completes
' its startup routines. This event does not occur if the COM add-in is not
' connected when Outlook loads, even when the user connects the add-in in
' the COM Add-ins dialog box.
' The custom argument is ignored.
End Sub


OLE Programmatic Identifiers (Outlook)

 Copy code hover
[image]

OLE Programmatic Identifiers (Outlook)
Send feedback

You can use an OLE programmatic identifier (sometimes called a ProgID) to create an Automation object. The following tables list OLE programmatic identifiers for ActiveX controls, Microsoft Office applications, and Microsoft Office Web Components.

ActiveX Controls

Microsoft Access

Microsoft Excel

Microsoft Graph

Microsoft Outlook

Microsoft PowerPoint

Microsoft Word

ActiveX Controls

To create the ActiveX controls listed in the following table, use the corresponding OLE programmatic identifier.

To create this Microsoft Forms 2.0 control | Use this identifier
CheckBox | Forms.CheckBox.1
ComboBox | Forms.ComboBox.1
CommandButton | Forms.CommandButton.1
Frame | Forms.Frame.1
Image | Forms.Image.1
Label | Forms.Label.1
ListBox | Forms.ListBox.1
MultiPage | Forms.MultiPage.1
OptionButton | Forms.OptionButton.1
ScrollBar | Forms.ScrollBar.1
SpinButton | Forms.SpinButton.1
TabStrip | Forms.TabStrip.1
TextBox | Forms.TextBox.1
ToggleButton | Forms.ToggleButton.1

Microsoft Access

To create the Microsoft Access objects listed in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of Access available on the machine where the macro is running.

To create this object | Use one of these identifiers
Application | Access.Application
CurrentData | Access.CodeData, Access.CurrentData
CurrentProject | Access.CodeProject, Access.CurrentProject
DefaultWebOptions | Access.DefaultWebOptions

Microsoft Excel

To create the Microsoft Excel objects listed in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of Excel available on the machine where the macro is running.

To create this object | Use one of these identifiers | Comments
Application | Excel.Application |
Workbook | Excel.AddIn |
Workbook | Excel.Chart | Returns a workbook containing two worksheets; one for the chart and one for its data. The chart worksheet is the active worksheet.
Workbook | Excel.Sheet | Returns a workbook with one worksheet.

Microsoft Graph

To create the Microsoft Graph objects listed in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of Graph available on the machine where the macro is running.

To create this object | Use one of these identifiers
Application | MSGraph.Application
Chart | MSGraph.Chart

Microsoft Outlook

To create the Microsoft Outlook object given in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of Outlook available on the machine where the macro is running.

To create this object | Use one of these identifiers
Application | Outlook.Application

To create the ActiveX controls that are specific for Outlook forms, as listed in the following table, use the corresponding OLE programmatic identifier.

To create this Outlook control | Use this identifier
OlkBusinessCardControl | Outlook.OlkBusinessCardControl
OlkCategory | Outlook.OlkCategoryStrip
OlkCheckBox | Outlook.OlkCheckBox
OlkComboBox | Outlook.OlkComboBox
OlkCommandButton | Outlook.OlkCommandButton
OlkContactPhoto | Outlook.OlkContactPhoto
OlkDateControl | Outlook.OlkDateControl
OlkFrameHeader | Outlook.OlkFrameHeader
OlkInfoBar | Outlook.OlkInfoBar
OlkLabel | Outlook.OlkLabel
OlkListBox | Outlook.OlkListBox
OlkOptionButton | Outlook.OlkOptionButton
OlkPageControl | Outlook.OlkPageControl
OlkSenderPhoto | Outlook.OlkSenderPhoto
OlkTextBox | Outlook.OlkTextBox
OlkTimeControl | Outlook.OlkTimeControl
OlkTimeZoneControl | Outlook.OlkTimeZone

Microsoft PowerPoint

To create the Microsoft PowerPoint object given in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of PowerPoint available on the machine where the macro is running.

To create this object | Use one of these identifiers
Application | PowerPoint.Application

Microsoft Word

To create the Microsoft Word objects listed in the following table, use one of the corresponding OLE programmatic identifiers. If you use an identifier without a version number suffix, you create an object in the most recent version of Word available on the machine where the macro is running.

To create this object | Use one of these identifiers
Application | Word.Application
Document | Word.Document, Word.Template
Global | Word.Global


Support for Custom Property Pages

 Copy code hover
[image]

Support for Custom Property Pages
Send feedback

You can create your own property pages to customize the Properties dialog box for all folders.

A custom property page is an ActiveX control stored in a dynamic-link library (DLL) that implements the PropertyPage object and that's installed as a COM add-in . This object provides the interface through which Outlook can query the property page about its status and inform the property page that the user has clicked the Apply or OK button.

For more information about property pages, see adding custom property pages.

Note Note

Customizing the Outlook Options dialog box (available through the Microsoft Office Backstage view) by using property pages has been deprecated. However, you can customize your own tab on the Backstage view using Microsoft Office Fluent user interface extensibility. For more information, see Extending the User Interface in Outlook 2010.


Adding Custom Property Pages

 Copy code hover
[image]

Adding Custom Property Pages
Send feedback

Creating a custom property page for Microsoft Outlook involves four major steps:

  1. Create the page as an ActiveX control.

  2. Implement the PropertyPage object.

  3. Write a procedure that sets the value of the Dirty property and calls the OnStatusChange method.

  4. Create a Component Object Model (COM) add-in that contains an event procedure for OptionsPagesAdd for either the Application or NameSpace object, as appropriate. For information about creating a COM add-in, see Customizing Outlook using COM add-ins.

Create the page as an ActiveX control

A custom property page in Outlook is an ActiveX control that's implemented along with a dynamic link library (DLL) that's designed as a COM add-in. The easiest way to create a custom property page is using Microsoft Visual Basic version 6.0 or higher. This version of Visual Basic provides templates and tools that simplify the process of creating both ActiveX controls and COM add-ins.

When you create the ActiveX control, you populate it with the controls your user will require to set the properties your page is designed to support. Because Outlook might resize the control when it displays the property page in the dialog box, the control's Initialize event should position and size the child controls dynamically, depending on the final values of the control's Width and Height properties.

The dialog box in which the custom property page is displayed has three buttons below the property pages: an OK button, a Cancel button, and an Apply button. When the user clicks the OK button, changes to properties on all pages in the dialog box are applied and the dialog box is closed. If the user clicks the Cancel button, no properties are changed and the dialog box is closed. If the user clicks the Apply button, any changes to properties are applied but the dialog box remains open. You should design your property page to respond appropriately when the user clicks these buttons. Later sections in this topic describe how to notify Outlook that the status of your property page has changed and how Outlook notifies your program when the changed property values should be applied.

Implement the PropertyPage object

The PropertyPage object is an abstract object; that is, its interfaces are defined but not implemented by Outlook. If your custom property change will rely on the Apply or Help button of the parent dialog box, the module that contains the custom property page ActiveX control must implement the PropertyPage object. To implement the object, the module must have a reference set to the Outlook object library and must contain the following statement.

Copy code Copy code
Implements Outlook.PropertyPage

The module must then contain code that implements the methods and properties of the PropertyPage object. The following table describes these procedures.

Procedure | Description
Dirty property | Called by Outlook in response to the OnStatusChange method to determine whether the user has changed a value on the property page.
Apply method | Called by Outlook to notify your program that the user has clicked the OK or the Apply button. Usually this procedure applies any property values changed by the user in the property page.
GetPageInfo method | Called by Outlook to obtain the Help file and topic associated with the property page.

Write a procedure that sets the Dirty property and calls the OnStatusChange method

Most commonly, changes to property values are not applied immediately in response to user interaction with the controls that let the user specify those values. Instead, the values are applied when the user clicks OK or Apply in the dialog box. The Apply button is grayed until the user changes a value on a property page. To notify Outlook that the user has changed a value on your property page, your program should call the OnStatusChange method and then return True when Outlook queries the Dirty property.

Create a COM add-in containing an event procedure for the OptionsPagesAdd event

The OptionsPagesAdd event gives your program the opportunity to add your custom property page to the Microsoft OutlookOptions dialog box (if the event is fired for the Application object) or the folders Properties dialog box (if the event is called for the NameSpace object). When Outlook calls this event procedure, it passes a PropertyPages object. Your event procedure uses the Add method of the collection to add the PropertyPage object implemented by your program to the object.


Support for Contact Linking

 Copy code hover
[image]

Support for Contact Linking
Send feedback

Microsoft Outlook allows users to establish links between contact items and other items. The Outlook object model has been extended to give programs access to these links. All Outlook item objects have an associated Links collection object that contains the contacts to which a particular item is linked. You can use standard collection methods and properties (Add, Count, Item, and Remove) to create, access, and remove items from the collection.


Support for Folder Synchronization

 Copy code hover
[image]

Support for Folder Synchronization
Send feedback

Users who travel with their computers or who otherwise need to use Microsoft Outlook when disconnected from the network need to be able to synchronize their offline folders using different criteria, depending on the situation. For example, before departing on a trip, a user might synchronize all of her offline folders, plus the Address Book. When she arrives at her destination, she connects to her home office using a modem. Because of the slow data-transfer rate, she only wants to synchronize her Inbox and Outbox to receive and send messages.

Outlook supports multiple synchronization profiles so users can select how they want Outlook to synchronize offline folders in a given situation. The SyncObjects collection object represents all the synchronization profiles for a given user. Your program can use the Start and Stop methods of the SyncObject objects in this collection to begin and end synchronization using a particular profile, and can monitor the progress of the synchronization using the SyncStart, Progress, OnError, and SyncEnd Event events.


How to: Verify Whether Outlook Is a Click-to-Run Application on a Computer

 Copy code hover
[image]

How to: Verify Whether Outlook Is a Click-to-Run Application on a Computer
Send feedback

Click-to-Run is a software delivery and updating mechanism. Products delivered via Click-to-Run execute in a virtual application environment on the local operating system. This means that they have private copies of their files and settings, and that any changes they make are captured in the virtual environment. Click-to-Run is fast—users can start running an application within a short time without waiting for the entire product to finish installing. Updates are carried out automatically in the background, without requiring a user to first remove an installation or install patches. Click-to-Run products are virtualized and do not conflict with other installed software.

However, because a product delivered by Click-to-Run has private copies of all its files and registration, an add-in developer cannot determine the product's existence the same way as a product that has been installed on a client computer's hard drive. Starting in Office 2013, Click-to-Run is the default mechanism to deliver Office, and only a subset of Office customers can request physical media to install Office. Add-in developers should determine whether Outlook has been installed, and whether Outlook has been delivered as a Click-to-Run product.

In Office 2013, 32-bit Office and 64-bit Office are available via Click-to-Run. The default delivery is 32-bit Office for 32-bit or 64-bit Windows. You can also obtain 64-bit Office for a computer with 64-bit Windows. If you would like to have both Office 2010 and Office 2013 on the same computer, the bitness of the two versions of Office must be the same.

To check whether Outlook was delivered by Click-to-Run on a client computer:

  • Verify if the VirtualOutlook key exists in the following location in the Windows registry:

    Copy code Copy code
    HKEY_LOCAL_MACHINE\Software\Microsoft\Office\15.0\Common\InstallRoot\Virtual\VirtualOutlook

  • The VirtualOutlook key is a REG_SZ value that contains the culture tag of the installed product language, such as "en-us".


Accounts (Outlook)

 Copy code hover
[image]

Accounts (Outlook)
Send feedback

In this section

  • Using Multiple Accounts for the Same Profile on Outlook

  • How to: Obtain Information for Multiple Accounts

  • How to: Identify a Folder with an Account

  • How to: Create a Sendable Item for a Specific Account Based on the Current Folder (Outlook)


Using Multiple Accounts for the Same Profile on Outlook

 Copy code hover
[image]

Using Multiple Accounts for the Same Profile on Outlook
Send feedback

You can log on to Microsoft Outlook by using a profile that specifies one or more accounts associated with different delivery stores. For a given session, the NameSpace object has members that maintain and access information for the primary Exchange account, and the Accounts property of the NameSpace object holds information for all the accounts defined for the session's profile. The NameSpace.Accounts property returns an Accounts collection for the current profile, tracking information for all accounts including Exchange, IMAP, and POP3 accounts, each of which can be associated with a different delivery store. To identify the primary Exchange account in the Accounts collection for a session, look for the account that has the ExchangeStoreType property of the store (that is specified by Account.DeliveryStore) equal to OlExchangeStoreType.olPrimaryExchangeMailbox. In other words:

VBA Copy code Copy code
Account.DeliveryStore.ExchangeStoreType = OlExchangeStoreType.olPrimaryExchangeMailbox

The following table compares members of the NameSpace object and members of the Account, Accounts, or Store object depending on whether there is one account or multiple accounts in the session's profile.

Use the following members of the NameSpace object if there is only the primary Exchange account in the session's profile. | Purpose | Use the following members of the noted objects if there are multiple accounts in the session's profile. | Purpose
AutoDiscoverConnectionMode property, AutoDiscoverXml property, AutoDiscoverComplete event | To use auto discovery of the Exchange server that hosts the primary Exchange account mailbox. | Account.AutoDiscoverConnectionMode property, Account.AutoDiscoverXml property, Accounts.AutoDiscoverComplete event | To use auto discovery of the Exchange server that hosts the account mailbox.
ExchangeConnectionMode property, ExchangeMailboxServerName property, ExchangeMailboxServerVersion property | To obtain information for the Exchange server that hosts the primary Exchange account mailbox. | Account.ExchangeConnectionMode property, Account.ExchangeMailboxServerName property, Account.ExchangeMailboxServerVersion property | To obtain information for the Exchange server that hosts the account mailbox.
Categories property | To obtain a Categories collection that represents the Master Category List for the primary account of the session. | Store.Categories property | To obtain a Categories collection that represents the categories defined for the store that is associated with an account in the session's profile.
CurrentUser property | To obtain a Recipient object that represents the user currently logged on for the session. | Account.CurrentUser property | To obtain a Recipient object that represents the user of the account that is defined in the session's profile. The account can be any account that Outlook supports including Exchange, IMAP, and POP3.
DefaultStore property | To obtain the default store for the session's profile. | Account.DeliveryStore property | To obtain the default delivery store for the account that is defined in the session's profile. The account can be any account that Outlook supports including Exchange, IMAP, and POP3.
GetAddressEntryFromID method | To obtain an AddressEntry object that corresponds to the given entry ID. | Account.GetAddressEntryFromID method | To obtain an AddressEntry object that corresponds to the account and given entry ID. The account can be any account that Outlook supports including Exchange, IMAP, and POP3.
GetRecipientFromID method | To obtain a Recipient object that corresponds to the given entry ID. | Account.GetRecipientFromID method | To obtain a Recipient object that corresponds to the account and given entry ID. The account can be any account that Outlook supports including Exchange, IMAP, and POP3.

See the following tasks if you are operating with multiple accounts in the current profile:

  • How to: Obtain Information for Multiple Accounts

  • How to: Identify a Folder with an Account

  • How to: Create a Sendable Item for a Specific Account Based on the Current Folder

  • How to: Identify a Global Address List or a Set of Address Lists with a Store


How to: Obtain Information for Multiple Accounts

 Copy code hover
[image]

How to: Obtain Information for Multiple Accounts
Send feedback

Microsoft Outlook supports a profile that contains one or more accounts that are connected to a Microsoft Exchange Server. This topic shows how to obtain and display miscellaneous information about each account in the current profile.

The following method, EnumerateAccounts, displays the account name, user name, and Simple Mail Transfer Protocol (SMTP) address for each account that is defined in the current profile. If the account is connected to an Exchange server, EnumerateAccounts displays the Exchange server name and version information. And if the account resides on a delivery store, EnumerateAccounts displays the name of the default delivery store for the account.

EnumerateAccounts accesses most of this information from the Account object, except when the Account object does not contain information about the user name and SMTP address. In that case, EnumerateAccounts uses the AddressEntry and ExchangeUser objects. EnumerateAccounts obtains the AddressEntry object by using the AddressEntry property of the Recipient object obtained from the Account.CurrentUser property. EnumerateAccounts obtains the ExchangeUser object by using the GetExchangeUser method of the AddressEntry object. The following is the algorithm to obtain various information by using the Account, AddressEntry, and ExchangeUser objects:

  • If the Account object contains information about the user name and SMTP address, use the Account object to display the account name, user name, SMTP address, and Exchange server name and version information if the account is an Exchange account.

  • Otherwise, the Account object does not contain information about the user name and SMTP address, and proceed as follows:

    • If the account is not an Exchange account, use the AddressEntry object to display the user name and SMTP address.

    • Otherwise, the account is an Exchange account, and proceed as follows:

      1. Use the Account object to display the account name, Exchange server name, and Exchange version information.

      2. Use the ExchangeUser object to display the user name and SMTP address.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void EnumerateAccounts()
{
    Outlook.Accounts accounts =
        Application.Session.Accounts;

    // Enumerate each account defined in the current profile.
    foreach (Outlook.Account account in accounts)
    {
        try
        {
            StringBuilder sb = new StringBuilder();
            sb.AppendLine("Account: " + account.DisplayName);

            // If the account does not contain the SMTP address or
            // user name, use the AddressEntry and ExchangeUser objects.
            if (string.IsNullOrEmpty(account.SmtpAddress)
                || string.IsNullOrEmpty(account.UserName))
            {
                Outlook.AddressEntry oAE =
                    account.CurrentUser.AddressEntry
                    as Outlook.AddressEntry;

                // If the account is an Exchange account,
                // display also the Exchange server name and version.
                if (oAE.Type == "EX")
                {
                    Outlook.ExchangeUser oEU =
                        oAE.GetExchangeUser()
                        as Outlook.ExchangeUser;

                    // Use ExchangeUser object to display user name
                    // and SMTP address.
                    sb.AppendLine("UserName: " +
                        oEU.Name);
                    sb.AppendLine("SMTP: " +
                        oEU.PrimarySmtpAddress);

                    // Use Account object to display the Exchange
                    // server name and version information.
                    sb.AppendLine("Exchange Server: " +
                        account.ExchangeMailboxServerName);
                    sb.AppendLine("Exchange Server Version: " +
                        account.ExchangeMailboxServerVersion);
                }
                // The account is not connected to an Exchange
                // Server, use the AddressEntry object to display only
                // the user name and SMTP address.
                else
                {
                    sb.AppendLine("UserName: " +
                        oAE.Name);
                    sb.AppendLine("SMTP: " +
                        oAE.Address);
                }
            }
            // The account contains SMTP address and
            // user name,  then the Account object is sufficient.
            else
            {
                sb.AppendLine("UserName: " +
                    account.UserName);
                sb.AppendLine("SMTP: " +
                    account.SmtpAddress);

                // If the account is an Exchange account,
                // display also the Exchange server name and version.
                if(account.AccountType ==
                    Outlook.OlAccountType.olExchange)
                {
                    sb.AppendLine("Exchange Server: " +
                        account.ExchangeMailboxServerName);
                    sb.AppendLine("Exchange Server Version: " +
                        account.ExchangeMailboxServerVersion);
                }
            }

            // If the account is connected to a delivery store,
            // display the store name as well.
            if(account.DeliveryStore !=null)
            {
                sb.AppendLine("Delivery Store: " +
                    account.DeliveryStore.DisplayName);
            }
            sb.AppendLine("---------------------------------");
            Debug.Write(sb.ToString());
        }
        catch (Exception ex)
        {
            Debug.WriteLine(ex.Message);
        }
    }
}


How to: Identify a Folder with an Account

 Copy code hover
[image]

How to: Identify a Folder with an Account
Send feedback

In a Microsoft Outlook session that has multiple accounts defined in the profile, the folder that is displayed in the active explorer does not necessarily reside on the default store for that session; instead, it can reside on one of the multiple stores associated with the multiple accounts. This topic shows how to identify the account whose default delivery store is the same store that hosts the folder.

In the following code sample, the DisplayAccountForCurrentFolder function calls the GetAccountForFolder function to identify the account whose default delivery store hosts the current folder, and then displays the name of the folder. GetAccountForFolder matches the store of the current folder (obtained from the Folder.Store property) with the default delivery store of each account (obtained with the Account.DeliveryStore property) that is defined in the Accounts collection for the session. GetAccountForFolder returns the Account object when a match is found; otherwise, it returns null.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void DisplayAccountForCurrentFolder()
{
    Outlook.Folder myFolder = Application.ActiveExplorer().CurrentFolder
        as Outlook.Folder;
    string msg = "Account for Current Folder:" + "\n" +
        GetAccountForFolder(myFolder).DisplayName;
    MessageBox.Show(msg,
        "GetAccountForFolder",
        MessageBoxButtons.OK,
        MessageBoxIcon.Information);
}

Outlook.Account GetAccountForFolder(Outlook.Folder folder)
{
    // Obtain the store on which the folder resides.
    Outlook.Store store = folder.Store;

    // Enumerate the accounts defined for the session.
    foreach (Outlook.Account account in Application.Session.Accounts)
    {
        // Match the DefaultStore.StoreID of the account
        // with the Store.StoreID for the currect folder.
        if (account.DeliveryStore.StoreID  == store.StoreID)
        {
            // Return the account whose default delivery store
            // matches the store of the given folder.
            return account;
        }
     }
     // No account matches, so return null.
     return null;
}


How to: Create a Sendable Item for a Specific Account Based on the Current Folder (Outlook)

 Copy code hover
[image]

How to: Create a Sendable Item for a Specific Account Based on the Current Folder (Outlook)
Send feedback

When you use the CreateItem method of the Application object to create a Microsoft Outlook item, the item is created for the primary account for that session. In a session where multiple accounts are defined in the profile, you can create an item for a specific IMAP, POP, or Microsoft Exchange account. If there are multiple accounts in the current profile and you create a sendable item in the user interface, for example, by clicking New E-mail or New Meeting, an inspector displays a new mail item or meeting request in compose mode, and then you can select the account from which to send the item. This topic shows how to programmatically create a sendable item and send it by using a specific sending account. The topic has two code samples that show how to create a MailItem and an AppointmentItem for a specific account that is determined by the current folder in the active explorer.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The first method below, CreateMailItemFromAccount, creates a MailItem for a specific account and displays it in compose mode; the default delivery store of the specific account is the same as the store for the folder that is displayed in the active explorer. The current user of the account is set as the sender. CreateMailItemFromAccount first identifies the appropriate account by matching the store of the current folder (obtained from the Folder.Store property) with the default delivery store of each account (obtained with the Account.DeliveryStore property) that is defined in the Accounts collection for the session. CreateMailItemFromAccount then creates the MailItem. To associate the item with the account, CreateMailItemFromAccount assigns the user of the account as the sender of the item by setting the AddressEntry object for the account's user to the Sender property of the MailItem. Assigning the Sender property is the important step because otherwise, the MailItem is created for the primary account. At the end of the method, CreateMailItemFromAccount displays the MailItem. Note that if the current folder is not on a delivery store, CreateMailItemFromAccount simply creates the MailItem for the primary account for the session.

C# Copy code Copy code
private void CreateMailItemFromAccount()
{
    Outlook.AddressEntry addrEntry = null;

    // Get the store for the current folder.
    Outlook.Folder folder =
        Application.ActiveExplorer().CurrentFolder
        as Outlook.Folder;
    Outlook.Store store = folder.Store;

    Outlook.Accounts accounts =
        Application.Session.Accounts;

    // Match the delivery store of each account with the
    // store for the current folder.
    foreach (Outlook.Account account in accounts)
    {
        if (account.DeliveryStore.StoreID ==
            store.StoreID)
        {
            addrEntry =
                account.CurrentUser.AddressEntry;
            break;
        }
    }

    // Create MailItem. Account is either the primary
    // account or the account with a delivery store
    // that matches the store for the current folder.
    Outlook.MailItem mail =
        Application.CreateItem(
        Outlook.OlItemType.olMailItem)
        as Outlook.MailItem;

    if (addrEntry != null)
    {
        //Set Sender property.
        mail.Sender = addrEntry;
        mail.Display(false);
    }
}

The next method, CreateMeetingRequestFromAccount, is similar to CreateMailItemFromAccount except that it creates an AppointmentItem instead of a MailItem, and associates the AppointmentItem with the account by using its SendUsingAccount property. CreateMeetingRequestFromAccount creates an AppointmentItem in the Calender folder of an account whose default delivery store is the same as the store for the folder that is displayed in the active explorer. CreateMeetingRequestFromAccount first identifies the appropriate account by matching the store of the current folder (obtained from the Folder.Store property) with the default delivery store of each account (otained with the Account.DeliveryStore property) that is defined in the Accounts collection for the session. CreateMeetingRequestFromAccount then creates the AppointmentItem. To associate the item with the account, CreateMeetingRequestFromAccount assigns that account as the item's sending account by setting the Account object to the SendUsingAccount property of the AppointmentItem. Assigning the SendUsingAccount property is the important step because otherwise, the AppointmentItem is created for the primary account. At the end of the method, CreateMeetingRequestFromAccount displays the AppointmentItem. Note that if the current folder is not on a delivery store, CreateMeetingRequestFromAccount simply creates the AppointmentItem for the primary account for the session.

C# Copy code Copy code
private void CreateMeetingRequestFromAccount()
{
    Outlook.Account acct = null;

    // Get the store for the current folder.
    Outlook.Folder folder =
        Application.ActiveExplorer().CurrentFolder
        as Outlook.Folder;
    Outlook.Store store = folder.Store;

    Outlook.Accounts accounts =
        Application.Session.Accounts;

    // Match the delivery store of each account with the
    // store for the current folder.
    foreach (Outlook.Account account in accounts)
    {
        if (account.DeliveryStore.StoreID ==
            store.StoreID)
        {
            acct = account;
            break;
        }
    }

    // Create AppointmentItem. Account is either the primary
    // account or the account with a delivery store
    // that matches the store for the current folder.
    Outlook.AppointmentItem appt =
        Application.CreateItem(
        Outlook.OlItemType.olAppointmentItem)
        as Outlook.AppointmentItem;

    appt.MeetingStatus =
        Outlook.OlMeetingStatus.olMeeting;
    if (acct != null)
    {
        //Set SendUsingAccount property.
        appt.SendUsingAccount=acct;
        appt.Display(false);
    }
}


Address Book (Outlook)

 Copy code hover
[image]

Address Book (Outlook)
Send feedback

In this section

  • Display Names from the Address Book

  • Access Exchange User or Distribution List Information from the Address Book

  • How to: Display a Dialog Box for Selecting Entries from the Contacts Folder

  • How to: Display Address Entry Details for the Sender of a Message

  • How to: Identify the Global Address List or a Set of Address Lists with a Store

  • How to: List the Groups that My Manager Belongs to

  • How to: List the Name and Office Location of Each Manager Belonging to an Exchange Distribution List

  • How to: Map a Display Name to an E-mail Address

  • How to: Obtain the E-mail Address of a Recipient

  • How to: Programmatically Change the Display Format for All Contacts


Display Names from the Address Book

 Copy code hover
[image]

Display Names from the Address Book
See also Send feedback

This topic describes the address book and explains how to programmatically display names from an address book in the Outlook Address Book dialog box.

Outlook maintains a hierarchy of address books for a session. In order for the transport provider to deliver a message, the recipient must have an address entry in one of the address books in this hierarchy.

An address book contains one or more address lists. Each address list is composed of users, distribution lists, or other types of address entries. An example of an address list is the Exchange Global Address List. In the Outlook user interface, you can open the Address Book dialog box to view and select names in an address list. When you create a mail item or appointment item, or when you assign a task item, you can use the Address Book to help you select recipients.

The Outlook Address Book is an address list or a set of address lists that Outlook creates automatically. By default, it contains one address list for the contacts in your Contacts folder that have at least one e-mail address or fax number entry. As you create other folders in the Contacts module, by default, each folder will also become an address list in the Outlook Address Book. In the Outlook Address Book tab of the Properties dialog box for the folder, you can select or de-select Show this folder as an e-mail address book.

From the programmability perspective, Outlook maintains a collection of AddressLists for the current session. Each AddressList consists of a collection of AddressEntries. There are different types of address lists (as enumerated by OlAddressListType) and different types of address entries (as enumerated by OlAddressEntryUserType). When you add a folder to the Contacts module, you can use Folder.ShowAsOutlookAB to specify whether that folder will be displayed as an address list in the Outlook Address Book.

The Recipient object is associated with an AddressEntry object that is specified by the Recipient.Address property. You can also use the AddressEntry.AddressEntryUserType property to identify the type of the recipient, for example, whether the recipient is a Contact item, an Exchange user, or an Exchange distribution list.

The SelectNamesDialog object allows you to display names from an address list in a dialog box that resembles the Select Names dialog box in the Outlook user interface. The following figure is an example of the Select Names dialog box displaying the Contacts folder.

This dialog box allows a user to select entries from one or more address lists in the Address Book, and returns the selected recipients in the SelectNamesDialog.Recipients property. Through properties and methods of SelectNamesDialog, you can control the following aspects of the dialog box:

  • The initial address list to be displayed in the dialog box, and whether to show only this address list.

  • The number of recipient selectors, for example, whether to show all three labels of To, Cc, and Bcc.

  • The strings representing the title, To, Cc, and Bcc labels where applicable. Long titles and labels will be truncated without resizing the width of the dialog box.

  • Whether the user can select one or more address entries at a time.

  • Whether to resolve recipient names before closing the dialog box.

  • What to do if not all recipients are resolved.

To display the dialog box with names from an address list:

  1. Use the GetSelectNamesDialog method of the current session (indicated by Application.Session) to obtain an instance of the SelectNamesDialog object for the current session.

  2. Use the AddressLists property of the current session to obtain the collection of AddressLists for the current session.

  3. By default, the dialog box is initialized with the address list that has AddressList.IsInitialAddressList set to True. If necessary, you can use SelectNamesDialog.InitialAddressList to initialize the dialog box with another AddressList from the AddressLists collection in Step 2.

  4. Use SelectNamesDialog.Display to display the dialog box. This method returns a True or False depending on SelectNamesDialog.ForceResolution and the user's response:

    • This method returns True if SelectNamesDialog.ForceResolution is set, all selected names are resolved, and the user clicks OK.

    • It returns False if SelectNamesDialog.ForceResolution is set, but not all the recipients are resolved.

    • It returns False if SelectNamesDialog.ForceResolution is not set and the user clicks OK.

    • It returns False if the user clicks Cancel or the Close icon.

  5. If SelectNamesDialog.Display returns True, obtain the selected address entries using SelectNamesDialog.Recipients.

See also

Concepts

How to: Identify the Global Address List or a Set of Address Lists with a Store


Access Exchange User or Distribution List Information from the Address Book

 Copy code hover
[image]

Access Exchange User or Distribution List Information from the Address Book
Send feedback

This topic describes the objects that support accessing information about an Exchange user or distribution list from the Address Book.

The Address Book contains address lists of users, distribution lists, and other types of address entries, as enumerated by OlAddressEntryUserType. Specifically, the Exchange user address entry and the Exchange distribution list address entry have many of their properties exposed as explicit built-in properties in the Outlook object model through the ExchangeUser and ExchangeDistributionList objects. Both of these objects inherit from the AddressEntry object. They also support specific methods that facilitate accessing information about these entry types.

Exchange User

The ExchangeUser object supports properties like OfficeLocation, JobTitle, FirstName, and LastName that the parent AddressEntry object does not support. You can access these properties directly through the ExchangeUser object. You can access other properties of the Exchange user that are not exposed in the object model using ExchangeUser.PropertyAccessor.

The ExchangeUser object also supports methods like GetDirectReports, GetExchangeUserManager, and GetMemberOfList to facilitate accessing information specific to this Exchange user, such as full AddressEntry information for the associated direct reports, manager, and distribution lists.

Security

Certain properties like OfficeLocation and JobTitle are read-write and can only be updated (using ExchangeUser.Update) by code that is running under an appropriate Exchange administrator account.

Exchange Distribution List

The ExchangeDistributionList obect supports properties like Alias, Comments, and PrimarySmtpAddress that the parent AddressEntry object does not support. Other properties of the Exchange distribution list that are not exposed in the object model are accessible through ExchangeDistributionList.PropertyAccessor.

The ExchangeDistributionList object also supports methods like GetExchangeDistributionListMembers, GetMemberOfList and GetOwners to facilitate accessing information specific to a distribution list, such as full AddressEntry information for the associated members in this distribution list, other distribution lists that this list is a member of, and owners of this list.

Security

Certain properties like Comments are read-write and can only be updated (using ExchangeDistributionList.Update) by code that is running under an appropriate Exchange administrator account.


How to: Display a Dialog Box for Selecting Entries from the Contacts Folder

 Copy code hover
[image]

How to: Display a Dialog Box for Selecting Entries from the Contacts Folder
Send feedback

This topic describes how to use the SelectNamesDialog object to display entries from the Contacts folder in a dialog box that resembles the Select Names dialog box in the Outlook user interface.

  1. Look for the address list that corresponds with the Contacts folder.The SelectNamesDialog object displays entires in a dialog box based on an AddressList. To display entries in the Contacts folder, look for the AddressList that corresponds with the Contacts folder. Iterate through all the address lists defined for the current session, and for each address list, use AddressList.GetContactsFolderto match the corresponding folder with the Contacts folder.

  2. Initialize the dialog box with the address list of the Contacts folder.

  3. Use SelectNamesDialog.Display to display the dialog box. If SelectNamesDialog.Display returns True, then selected entries will be available in SelectNamesDialog.Recipients.

Copy code Copy code
Sub ShowContactsInDialog()
 Dim oDialog As SelectNamesDialog
 Dim oAL As AddressList
 Dim oContacts As Folder

 Set oDialog = Application.Session.GetSelectNamesDialog
 Set oContacts = _
 Application.Session.GetDefaultFolder(olFolderContacts)

 'Look for the address list that corresponds with the Contacts folder
 For Each oAL In Application.Session.AddressLists
 If oAL.GetContactsFolder = oContacts Then
 Exit For
 End If
 Next
 With oDialog
 'Initialize the dialog box with the address list representing the Contacts folder
 .InitialAddressList = oAL
 .ShowOnlyInitialAddressList = True
 If .Display Then
 'Recipients Resolved
 'Access Recipients using oDialog.Recipients
 End If
 End With
End Sub


How to: Display Address Entry Details for the Sender of a Message

 Copy code hover
[image]

How to: Display Address Entry Details for the Sender of a Message
Send feedback

The recipient of each mail message deliverable by a transport provider has an address entry in the provider's hierarchy of address books for the session. This topic describes how to programmatically display the address entry information of the sender of a mail item that is currently displayed in an inspector.

  1. For the currently displayed mail item, use the PropertyAccessor object to determine the Entry ID of the sender.

  2. Use the NameSpace.GetAddressEntryFromID method of the current session to return an AddressEntry object.

  3. Use the AddressEntry.AddressEntryUserType property to determine the type of the AddressEntry, and then display the details accordingly:

    • If the address entry is a contact item in the Outlook Contacts folder, or if the SMTP address of the sender matches an e-mail address of one contact item in the default Contacts folder, then display the address entry information in a Contacts inspector. To match e-mail addresses in the Contacts folder, use the Table object to do a quick filter on the ContactItem.Email1Address, ContactItem.Email2Address, and ContactItem.Email3Address properties of items in that folder.

    • In all other cases, display the address entry information in the E-mail Properties dialog box.

Remarks

To run this code sample:

  1. Open a mail message to have it displayed in the active inspector.

  2. Place the code in the built-in ThisOutlookSession module.

  3. Run the TestAddressEntryDetails procedure to display address entry details on the mail message in the active inspector:

Copy code Copy code
Sub TestAddressEntryDetails()
 Dim oMail As MailItem

 Set oMail = Application.ActiveInspector.CurrentItem
 DisplayAddressEntryDetails oMail
End Sub

Sub DisplayAddressEntryDetails(oM As MailItem)
 Dim oPA As Outlook.PropertyAccessor
 Dim oContact As Outlook.ContactItem
 Dim oSender As Outlook.AddressEntry
 Dim SenderID As String

 'Create an instance of PropertyAccessor
 Set oPA = oM.PropertyAccessor

 'Obtain PidTagSenderEntryId and convert to string
 SenderID = oPA.BinaryToString _
 (oPA.GetProperty("http://schemas.microsoft.com/mapi/proptag/0x0C190102"))

 'Obtain AddressEntry Object of the sender
 Set oSender = Application.Session.GetAddressEntryFromID(SenderID)

 'Examine AddressEntryUserType
 If oSender.AddressEntryUserType = olOutlookContactAddressEntry Then
 'Obtain ContactItem for AddressEntry
 Set oContact = oSender.GetContact
 oContact.Display
 'Display details for Exchange or SMTP sender
 Else
 oSender.Details
 End If
End Sub


How to: Identify the Global Address List or a Set of Address Lists with a Store

 Copy code hover
[image]

How to: Identify the Global Address List or a Set of Address Lists with a Store
Send feedback

In a Microsoft Outlook session where multiple Microsoft Exchange accounts are defined in the profile, there can be multiple address lists associated with a store. This topic has two code samples that show how to retrieve the Global Address List for a given store, and how to obtain all of the AddressList objects associated with a given store. In each of these code samples, the specific store of interest is the store for the current folder displayed in the active explorer, but the algorithm to get a Global Address List or a set of address lists for a store applies to any Exchange store.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The first code sample contains the DisplayGlobalAddressListForStore method and the GetGlobalAddressList function. The DisplayGlobalAddressListForStore method displays the Global Address List that is associated with the current store in the Select Names dialog box. DisplayGlobalAddressListForStore first obtains the current store. If the current store is an Exchange store, calls GetGlobalAddressList to obtain the Global Address List associated with the current store. GetGlobalAddressList uses the PropertyAccessor object and the MAPI property, http://schemas.microsoft.com/mapi/proptag/0x3D150102, to obtain the UIDs of an address list and the current store. GetGlobalAddressList identifies an address list as associated with a store if their UIDs match, and the address list is the Global Address List if its AddressListType property is olExchangeGlobalAddressList. If the call to GetGlobalAddressList succeeds, DisplayGlobalAddressListForStore uses the SelectNamesDialog object to display the returned Global Address List in the Select Names dialog box.

C# Copy code Copy code
void DisplayGlobalAddressListForStore()
{
    // Obtain the store for the current folder
    // as the current store.
    Outlook.Folder currentFolder =
        Application.ActiveExplorer().CurrentFolder
        as Outlook.Folder;
    Outlook.Store currentStore = currentFolder.Store;

    // Check if the current store is Exchange.
    if (currentStore.ExchangeStoreType !=
        Outlook.OlExchangeStoreType.olNotExchange)
    {
        Outlook.SelectNamesDialog snd =
            Application.Session.GetSelectNamesDialog();

        // Try to get the Global Address List associated
        // with the current store.
        Outlook.AddressList addrList =
            GetGlobalAddressList(currentStore);
        if (addrList != null)
        {
            // Display the Global Address List in the
            // Select Names dialog box.
            snd.InitialAddressList = addrList;
            snd.Display();
        }
    }
}

public Outlook.AddressList GetGlobalAddressList(Outlook.Store store)
{
    // Property string for the UID of a store or address list.
    string  PR_EMSMDB_SECTION_UID =
        @"http://schemas.microsoft.com/mapi/proptag/0x3D150102";

    if (store == null)
    {
        throw new ArgumentNullException();
    }

    // Obtain the store UID using the proprety string and
    // property accessor on the store.
    Outlook.PropertyAccessor oPAStore = store.PropertyAccessor;

    // Convert the store UID to a string value.
    string storeUID = oPAStore.BinaryToString(
        oPAStore.GetProperty(PR_EMSMDB_SECTION_UID));

    // Enumerate each address list associated
    // with the session.
    foreach (Outlook.AddressList addrList
        in Application.Session.AddressLists)
    {
        // Obtain the address list UID and convert it to
        // a string value.
        Outlook.PropertyAccessor oPAAddrList =
            addrList.PropertyAccessor;
        string addrListUID = oPAAddrList.BinaryToString(
            oPAAddrList.GetProperty(PR_EMSMDB_SECTION_UID));

        // Return the address list associated with the store
        // if the address list UID matches the store UID and
        // type is olExchangeGlobalAddressList.
        if (addrListUID == storeUID && addrList.AddressListType ==
            Outlook.OlAddressListType.olExchangeGlobalAddressList)
        {
            return addrList;
        }
    }
    return null;
}

The second code sample contains the EnumerateAddressListsForStore method and GetAddressLists function. The EnumerateAddressListsForStore method displays the type and resolution order of each address list defined for the current store. EnumerateAddressListsForStore first obtains the current store, then it calls GetAddressLists to obtain a .NET Framework generic List object that contains AddressList objects for the current store. GetAddressLists enumerates each address list defined for the session, uses the PropertyAccessor object and the MAPI named property, http://schemas.microsoft.com/mapi/proptag/0x3D150102, to obtain the UIDs of an address list and the current store. GetGlobalAddressList identifies an address list as associated with a store if their UIDs match, and returns a set of address lists for the current store. EnumerateAddressListsForStore then uses the AddressListType and ResolutionOrder properties of the AddressList object to display the type and resolution order for each returned address list.

C# Copy code Copy code
private void EnumerateAddressListsForStore()
{
    // Obtain the store for the current folder
    // as the current store.
    Outlook.Folder currentFolder =
       Application.ActiveExplorer().CurrentFolder
       as Outlook.Folder;
    Outlook.Store currentStore = currentFolder.Store;

    // Obtain all address lists for the current store.
    List<Outlook.AddressList> addrListsForStore =
        GetAddressLists(currentStore);
    foreach (Outlook.AddressList addrList in addrListsForStore)
    {
        // Display the type and resolution order of each
        // address list in the current store.
        Debug.WriteLine(addrList.Name
            + " " + addrList.AddressListType.ToString()
            + " Resolution Order: " +
            addrList.ResolutionOrder);
     }
}

public List<Outlook.AddressList> GetAddressLists(Outlook.Store store)
{
    List<Outlook.AddressList> addrLists =
        new List<Microsoft.Office.Interop.Outlook.AddressList>();

    // Property string for the UID of a store or address list.
    string PR_EMSMDB_SECTION_UID =
        @"http://schemas.microsoft.com/mapi/proptag/0x3D150102";

    if (store == null)
    {
        throw new ArgumentNullException();
    }

    // Obtain the store UID and convert it to a string value.
    Outlook.PropertyAccessor oPAStore = store.PropertyAccessor;
    string storeUID = oPAStore.BinaryToString(
        oPAStore.GetProperty(PR_EMSMDB_SECTION_UID));

    // Enumerate each address list associated
    // with the session.
    foreach (Outlook.AddressList addrList
        in Application.Session.AddressLists)
    {
        // Obtain the address list UID and convert it to
        // a string value.
        Outlook.PropertyAccessor oPAAddrList =
            addrList.PropertyAccessor;
        string addrListUID = oPAAddrList.BinaryToString(
            oPAAddrList.GetProperty(PR_EMSMDB_SECTION_UID));

        // Add the address list to the resultant set of address lists
        // if the address list UID matches the store UID.
        if (addrListUID == storeUID)
        {
            addrLists.Add(addrList);
        }
    }
    // Return the set of address lists associated with the store.
    return addrLists;
}


How to: List the Groups that My Manager Belongs to

 Copy code hover
[image]

How to: List the Groups that My Manager Belongs to
Send feedback

This topic describes how to obtain the names of the Exchange distribution lists that the manager of the current user belongs to. It uses the ExchangeUser object to obtain specific Exchange user information such as the user's Exchange account alias, details about the user's manager, and the distribution lists that the user's manager has joined:

  1. Obtain the current user's ExchangeUser object. Use the GetExchangeUser method of the AddressEntry object for the current user to get the ExchangeUser object that represents the current user.

  2. Obtain the distribution lists that the user's manager has joined.Use the ExchangeUser methods GetExchangeUserManager and GetMemberOfList to find these distribtution lists. Use the ExchangeDistributionList object to obtain further information about a distribution list, such as its display name.

Copy code Copy code
Sub ShowManagerDistLists()
 Dim oAE As Outlook.AddressEntry
 Dim oExUser As Outlook.ExchangeUser
 Dim oDistListEntries As Outlook.AddressEntries

 'Obtain the AddressEntry for CurrentUser
 Set oExUser = _
 Application.Session.CurrentUser.AddressEntry.GetExchangeUser

 'Obtain distribution lists that the user's manager has joined
 Set oDistListEntries = oExUser.GetExchangeUserManager.GetMemberOfList
 For Each oAE In oDistListEntries
 If oAE.AddressEntryUserType = _
 olExchangeDistributionListAddressEntry Then
 Debug.Print (oAE.name)
 End If
 Next
End Sub


How to: List the Name and Office Location of Each Manager Belonging to an Exchange Distribution List

 Copy code hover
[image]

How to: List the Name and Office Location of Each Manager Belonging to an Exchange Distribution List
Send feedback

This topic describes how to allow a user to select an Exchange distribution list and display the name and office location of each member who is a manager belonging to that distribution list. The major steps of this procedure are as follows:

  1. The code sample below displays a Select Distribition List dialog box for the user to select a distribution list.

    It uses the SelectNamesDialog object to display the dialog box and obtain user selection. The sample then obtains the user selection through the SelectNamesDialog.Recipients property.

  2. For each member in the selected distribution list:

    1. If the member is a manager, then the code sample displays the name and office number of the manager.

      Each member in the distribution list is an AddressEntry object. By checking if the AddressEntry.AddressEntryUserType is either olExchangeUserAddressEntry or olExchangeRemoteUserAddressEntry, the sample then assigns the AddressEntry object to an ExchangeUser object, and uses ExchangeUser.GetDirectReports.Count >0 as a criterion to determine if the user is a manager. It then displays the Name and OfficeLocation properties of the ExchangeUser object.

    2. If the member is a distribution list, the code sample calls the subroutine EnumerateDLManagers. For each member in that distribution list, if the member is a manager, the code sample then displays the name and office number of the manager.

Copy the following Visual Basic for Applications code sample to the Visual Basic Editor, and run ShowManagersOfGroups. Note that this code sample only applies to a distribution list that has only Exchange users as members, or that has Exchange distribution lists as members but all members of the latter will have to be Exchange users. Further customization of the code will be necessary if there is more nesting of distribution lists as members.

VBA Copy code Copy code
Sub ShowManagersOfGroups()
    Dim oRecip As Outlook.Recipient
    Dim oSND As Outlook.SelectNamesDialog
    Dim oAE As Outlook.AddressEntry
    Dim oAEs As Outlook.AddressEntries
    Dim oEU As Outlook.ExchangeUser
    Dim oDL As Outlook.ExchangeDistributionList
    Dim oLists As Outlook.AddressLists
    Dim oList As Outlook.AddressList
    Set oLists = Application.Session.AddressLists
    For Each oList In oLists
        If oList.Name = "All Groups" Then
            Exit For
        End If
    Next
    Set oSND = Application.Session.GetSelectNamesDialog
    With oSND
        .NumberOfRecipientSelectors = olShowTo
        .InitialAddressList = oList
        .Caption = "Select Distribution List"
        .ToLabel = "D/L"
        .ShowOnlyInitialAddressList = True
        .AllowMultipleSelection = False
        .Display
    End With
    For Each oRecip In oSND.Recipients
        If oRecip.AddressEntry.AddressEntryUserType = _
            olExchangeDistributionListAddressEntry Then
            Set oDL = oRecip.AddressEntry.GetExchangeDistributionList
            Set oAEs = oDL.GetExchangeDistributionListMembers
            For Each oAE In oAEs
                If oAE.AddressEntryUserType = olExchangeUserAddressEntry _
                    Or oAE.AddressEntryUserType = olExchangeRemoteUserAddressEntry Then
                    Set oEU = oAE.GetExchangeUser
                    If oEU.GetDirectReports.Count Then
                        Debug.Print oEU.Name, oEU.OfficeLocation
                    End If
                ElseIf oAE.AddressEntryUserType = _
                    olExchangeDistributionListAddressEntry Then
                    EnumerateDLManagers oAE
                End If
            Next
        End If
    Next
End Sub

Sub EnumerateDLManagers(oAddress As AddressEntry)
    Dim oAE As Outlook.AddressEntry
    Dim oAEs As Outlook.AddressEntries
    Dim oEU As Outlook.ExchangeUser
    Dim oDL As Outlook.ExchangeDistributionList

    Set oDL = oAddress.GetExchangeDistributionList
    Set oAEs = oDL.GetExchangeDistributionListMembers
    For Each oAE In oAEs
        If oAE.AddressEntryUserType = olExchangeUserAddressEntry _
            Or oAE.AddressEntryUserType = olExchangeRemoteUserAddressEntry Then
            Set oEU = oAE.GetExchangeUser
            If oEU.GetDirectReports.Count Then
                Debug.Print oEU.Name, oEU.OfficeLocation
            End If
        End If
    Next
End Sub


How to: Map a Display Name to an E-mail Address

 Copy code hover
[image]

How to: Map a Display Name to an E-mail Address
Send feedback

This topic shows a code sample in Visual Basic for Applications (VBA) that takes a display name and tries to map it to an e-mail address known to the messaging system in the current session.

For each Outlook session, the transport provider defines a set of address book containers that the messaging system can deliver messages to. Each address book container corresponds to an address list in Outlook. If a display name is defined in the set of address book containers, the display name can be resolved in the current session and there exists an entry in an address list that maps to this display name. Note that entries in an address list can be of various types, including an Exchange user and Exchange distribution list.

In this code sample, the function ResolveDisplayNameToSMTP uses the display name "Dan Wilson" as an example. It first tries to verify that the display name is defined in an address list by creating a Recipient object based on this display name and then calling Recipient.Resolve. If the name is resolved, then ResolveDisplayNameToSMTP uses the AddressEntry object that is mapped to the Recipient object to further obtain the type and, if possible, the e-mail address:

  • If the type of the AddressEntry object is an Exchange user, ResolveDisplayNameToSMTP calls AddressEntry.GetExchangeUser to obtain the corresponding ExchangeUser object. ExchangeUser.PrimarySmtpAddress provides the e-mail address that maps to the display name.

  • If the AddressEntry object is an Exchange distribution list, ResolveDisplayNameToSMTP calls AddressEntry.GetExchangeDistributionList to obtain an ExchangeDistributionList object. ExchangeDistributionList.PrimarySmtpAddress provides the e-mail address that maps to the display name.

VBA Copy code Copy code
Sub ResolveDisplayNameToSMTP()
 Dim oRecip As Outlook.Recipient
 Dim oEU As Outlook.ExchangeUser
 Dim oEDL As Outlook.ExchangeDistributionList

 Set oRecip = Application.Session.CreateRecipient("Dan Wilson")
 oRecip.Resolve
 If oRecip.Resolved Then
 Select Case oRecip.AddressEntry.AddressEntryUserType
 Case OlAddressEntryUserType.olExchangeUserAddressEntry
 Set oEU = oRecip.AddressEntry.GetExchangeUser
 If Not (oEU Is Nothing) Then
 Debug.Print oEU.PrimarySmtpAddress
 End If
 Case OlAddressEntryUserType.olExchangeDistributionListAddressEntry
 Set oEDL = oRecip.AddressEntry.GetExchangeDistributionList
 If Not (oEDL Is Nothing) Then
 Debug.Print oEDL.PrimarySmtpAddress
 End If
 End Select
 End If
End Sub


How to: Obtain the E-mail Address of a Recipient

 Copy code hover
[image]

How to: Obtain the E-mail Address of a Recipient
Send feedback

This topic shows how to obtain the SMTP address for each recipient in a Recipients collection.

The method in the code sample, GetSMTPAddressForRecipients, takes a MailItem as an input argument and then displays the SMTP address of each recipient for that mail item. The method first retrieves the Recipients collection that represents the set of recipients specified for the mail item. For each Recipient in that Recipients collection, the method then obtains the PropertyAccessor object that corresponds to that Recipient object, and uses the PropertyAccessor to get the value of the MAPI property http://schemas.microsoft.com/mapi/proptag/0x39FE001E, that maps to the SMTP address of the recipient.

This topic contains two code samples. The following code sample is written in Microsoft Visual Basic for Applications (VBA).

VBA Copy code Copy code
Sub GetSMTPAddressForRecipients(mail As Outlook.MailItem)
    Dim recips As Outlook.Recipients
    Dim recip As Outlook.Recipient
    Dim pa As Outlook.PropertyAccessor
    Const PR_SMTP_ADDRESS As String = _
        "http://schemas.microsoft.com/mapi/proptag/0x39FE001E"
    Set recips = mail.Recipients
    For Each recip In recips
        Set pa = recip.PropertyAccessor
        Debug.Print recip.name & " SMTP=" _
           & pa.GetProperty(PR_SMTP_ADDRESS)
    Next
End Sub

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void GetSMTPAddressForRecipients(Outlook.MailItem mail)
{
    const string PR_SMTP_ADDRESS =
        "http://schemas.microsoft.com/mapi/proptag/0x39FE001E";
    Outlook.Recipients recips = mail.Recipients;
    foreach (Outlook.Recipient recip in recips)
    {
        Outlook.PropertyAccessor pa = recip.PropertyAccessor;
        string smtpAddress =
            pa.GetProperty(PR_SMTP_ADDRESS).ToString();
        Debug.WriteLine(recip.Name + " SMTP=" + smtpAddress);
    }
}


How to: Programmatically Change the Display Format for All Contacts

 Copy code hover
[image]

How to: Programmatically Change the Display Format for All Contacts
Send feedback

In Outlook, you can specify the default setting for how to file new contacts through the options for Contacts, as well as when you create the new contact. For example, the default setting is Last, First, which files a contact by the last name followed by the first name. However, changing this setting only applies to new contacts that you create. For contacts that already exist, if you want to change the way that their names are filed by, for example, changing from the default Last, First to First, Last, you will have to either do it individually for each existing contact in the inspector, or, you will have to write a macro to change the setting for all existing contacts in the Contacts folder.

This topic shows a code sample that goes through all the Contact items in the default Contacts folder and uses the FileAs property of each Contact item to specify the string to file the contact by; in this particular example, the string is changed to first name followed by a blank and then the last name. The code sample then saves the changes to the Contact item.

Note Note

Generally, a folder in Outlook can contain heterogeneous items, and the Contact folder can contain ContactItem objects as well as other items. The code sample ensures that it only changes the file-as format for Contact items by filtering on the message class IPM.Contact. For more information on item types and message classes, see Item Types and Message Classes.
VBA Copy code Copy code
Private Sub ReFileContacts()
 Dim items As items, item As ContactItem, folder As folder
 Dim contactItems As Outlook.items
 Dim itemContact As Outlook.ContactItem

 Set folder = Session.GetDefaultFolder(olFolderContacts)
 Set items = folder.items
 Count = items.Count
 If Count = 0 Then
 MsgBox "Nothing to do!"
 Exit Sub
 End If

 'Filter on the message class to obtain only contact items in the folder
 Set contactItems = items.Restrict("[MessageClass]='IPM.Contact'")

 For Each itemContact In contactItems
 itemContact.FileAs = itemContact.FirstName + " " + itemContact.LastName
 itemContact.Save
 Next

 MsgBox "Your contacts have been re-filed."
End Sub


Attachments (Outlook)

 Copy code hover
[image]

Attachments (Outlook)
Send feedback

In this section

  • How to: Attach a File to an Outlook Email Message

  • How to: Attach an Outlook Contact Item to an Email Message

  • How to: Limit the Size of an Attachment to an Outlook Email Message

  • How to: Modify an Attachment of an Outlook Email Message


How to: Attach a File to an Outlook Email Message

 Copy code hover
[image]

How to: Attach a File to an Outlook Email Message
See also Send feedback

This topic describes how to programmatically attach one or more files to an outgoing email message in Microsoft Outlook.

Provided by: Ken Getz, MCW Technologies, LLC

Object Model Support for Attachments

In Outlook, the Attachments property of the MailItem object supports attaching one or more files to an email message. To attach one or more files to a mail item before sending the item, you call the Add(Object, Object, Object, Object) method of the Attachments object for each of the attachment files. The Add method allows you to specify the file name (the Source parameter) and the attachment type (the Type parameter) by using the OlAttachmentType enumeration. For files in the file system, specify the Type parameter as the Outlook.olAttachmentType.olByValue enumerated value.

Note Note

Since Microsoft Office Outlook 2007, you would always use this value to attach a copy of a file in the file system; Outlook.olAttachmentType.olByReference is no longer supported.

In addition, when you send an email in Rich Text Format (RTF), you can also specify two other optional parameters—Position and DisplayName—when you call the Add method. The Position parameter allows you to specify the position within the email where the attachment should appear. Use one of the following values for the Position parameter:

  • The value 0 hides the attachment within the body of the email.

  • The value 1 places the attachment before the first character.

  • A number that is larger than the number of characters in the body of the email item places the attachment at the end of the body text.

For RTF email messages, you can also specify the DisplayName parameter, which provides the name that is displayed within the body of the message for the attachment. For plain text or HTML email messages, the attachment displays only the name of the file.

Sending a Message with Files as Attachments

The SendEmailWithAttachments sample procedure in the code example later in this topic accepts the following:

  • A reference to the Outlook Application object.

  • Strings that contain the subject and body of the message.

  • A generic list of strings that contain a list of the SMTP addresses for recipients of the message.

  • A string that contains the SMTP address of the sender.

  • A generic list of strings that contain the paths for the files to be attached.

After creating a new email item, the code adds each recipient to the Recipients collection property of the mail item. Once the code calls the ResolveAll() method, it sets the Subject and Body properties of the mail item before looping through each item in the provided list of attachment paths, adding each to the Attachments property of the mail item.

Before actually sending the email, you must specify the account from which to send the email message. One technique for finding this information is to use the SMTP address of the sender. The GetAccountForEmailAddress function accepts a string that contains the sender's SMTP email address, and returns a reference for the corresponding Account object. This method compares the sender's SMTP address with the SmtpAddress property for each configured email account defined for the session's profile. application.Session.Accounts returns an Accounts collection for the current profile, tracking information for all accounts including Exchange, IMAP, and POP3 accounts, each of which can be associated with a different delivery store. The Account object that has an associated SmtpAddress property value that matches the sender's SMTP address is the account to use to send the email message.

After identifying the appropriate account, the code completes by setting the SendUsingAccount property of the mail item to that Account object, and then calling the Send() method.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code shows how to programmatically attach files to an outgoing email message in Outlook. To demonstrate this functionality, in Visual Studio, create a new managed Outlook add-in named AttachFileAddIn, and replace the contents of the ThisAddIn.vb or ThisAddIn.cs file with the example code shown here. Modify the ThisAddIn_Startup procedure to include a reference to a file in your file system, and update the email addresses appropriately. The SMTP address included in the call to the SendMailWithAttachments procedure must correspond to the SMTP address of one of the outgoing email accounts you have previously configured in Outlook.

C# Copy code Copy code
using System.Collections.Generic;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace AttachFileAddIn
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            List<string> attachments = new List<string>();
            attachments.Add("c:\\somefile.txt");

            List<string> recipients = new List<string>();
            recipients.Add("john@contoso.com");
            recipients.Add("john@example.com");
            SendEmailWithAttachments(Application, "Test", "Body", recipients, "john@example.com",
              attachments);
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        private void SendEmailWithAttachments(Outlook.Application application,
            string subject, string body, List<string> recipients,
            string smtpAddress, List<string> attachments)
        {

            // Create a new MailItem and set the To, Subject, and Body properties.
            var newMail = application.CreateItem(Outlook.OlItemType.olMailItem) as Outlook.MailItem;

            // Set up all the recipients.
            foreach (var recipient in recipients)
            {
                newMail.Recipients.Add(recipient);
            }
            if (newMail.Recipients.ResolveAll())
            {
                newMail.Subject = subject;
                newMail.Body = body;
                foreach (string attachment in attachments)
                {
                    newMail.Attachments.Add(attachment, Outlook.OlAttachmentType.olByValue);
                }
            }

            // Retrieve the account that has the specific SMTP address.
            Outlook.Account account = GetAccountForEmailAddress(application, smtpAddress);
            // Use this account to send the e-mail.
            newMail.SendUsingAccount = account;
            newMail.Send();
        }

        private Outlook.Account GetAccountForEmailAddress(Outlook.Application application,
            string smtpAddress)
        {

            // Loop over the Accounts collection of the current Outlook session.
            Outlook.Accounts accounts = application.Session.Accounts;
            foreach (Outlook.Account account in accounts)
            {
                // When the email address matches, return the account.
                if (account.SmtpAddress == smtpAddress)
                {
                    return account;
                }
            }
            // If you get here, no matching account was found.
            throw new System.Exception(string.Format("No Account with SmtpAddress: {0} exists!",
                smtpAddress));
        }

        #region VSTO generated code

        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }

        #endregion
    }
}
Visual Basic Copy code Copy code
Public Class ThisAddIn

    Private Sub ThisAddIn_Startup() Handles Me.Startup
        Dim attachments As New List(Of String)
        attachments.Add("c:\somefile.txt")

        Dim recipients As New List(Of String)
        recipients.Add("john@contoso.com")
        recipients.Add("john@example.com")
        SendEmailWithAttachments(Application, "Test", "Body", recipients, "john@contoso.com", attachments)
    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown

    End Sub

    Private Sub SendEmailWithAttachments(ByVal application As Outlook.Application, _
        ByVal subject As String, ByVal body As String,
        ByVal recipients As List(Of String),
        ByVal smtpAddress As String,
        ByVal attachments As List(Of String))

        ' Create a new MailItem and set the To, Subject, and Body properties.
        Dim newMail As Outlook.MailItem =
            DirectCast(application.CreateItem(Outlook.OlItemType.olMailItem),
            Outlook.MailItem)

        ' Set up all the recipients.
        For Each recipient In recipients
            newMail.Recipients.Add(recipient)
        Next
        If newMail.Recipients.ResolveAll() Then
            newMail.Subject = subject
            newMail.Body = body
            For Each attachment As String In attachments
                newMail.Attachments.Add(attachment, Outlook.OlAttachmentType.olByValue)
            Next
        End If

        ' Retrieve the account that has the specific SMTP address.
        Dim account As Outlook.Account = GetAccountForEmailAddress(application, smtpAddress)
        ' Use this account to send the e-mail.
        newMail.SendUsingAccount = account
        newMail.Send()
    End Sub

    Private Function GetAccountForEmailAddress(
        ByVal application As Outlook.Application,
        ByVal smtpAddress As String) As Outlook.Account

        ' Loop over the Accounts collection of the current Outlook session.
        Dim accounts As Outlook.Accounts = application.Session.Accounts
        For Each account In accounts
            ' When the email address matches, return the account.
            If account.SmtpAddress = smtpAddress Then
                Return account
            End If
        Next
        ' If you get here, no matching account was found.
        Throw New System.Exception(
            String.Format("No Account with SmtpAddress: {0} exists!", smtpAddress))
    End Function
End Class

See also

Concepts

How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message


How to: Attach an Outlook Contact Item to an Email Message

 Copy code hover
[image]

How to: Attach an Outlook Contact Item to an Email Message
See also Send feedback

This topic describes how you can programmatically attach a copy of a Microsoft Outlook item, such as a contact, calendar item, or another email message, to an email message before sending the message.

Provided by: Ken Getz, MCW Technologies, LLC

To attach one or more files or Outlook items to a mail message, you can use the Attachments property of the MailItem object that represents your outgoing mail, and call the Add(Object, Object, Object, Object) method of the Attachments object for each of the attachments. The Add method allows you to specify the file name and how you want to associate the attachment. To attach Outlook items, such as the contact item shown in the example code for this topic, specify the Type parameter of the Add method as the Outlook.olAttachmentType.olEmbeddedItem enumerated value.

The SendMailItem sample procedure in the code example later in this topic accepts the following:

  • A reference to the Outlook Application object.

  • Strings that contain the subject and body of the message.

  • A generic list of strings that contain the SMTP addresses for recipients of the message.

  • A string that contains the SMTP address of the sender.

After creating a new mail item, the code loops through all the recipient addresses, adding each to the Recipients collection of the message. Once the code calls the ResolveAll() method of the Recipients object, it sets the Subject and Body properties of the mail item. Next, the code creates a new Outlook ContactItem object and adds this new contact item as an attachment to the mail message, specifying the Outlook.olAttachmentType.olEmbeddedItem value as a parameter to the Add method call.

Before actually sending the email, you must specify the account from which to send the email message. One technique for finding this information is to use the SMTP address of the sender. The GetAccountForEmailAddress function accepts a string that contains the sender's SMTP email address, and returns a reference for the corresponding Account object. This method compares the sender's SMTP address with the SmtpAddress for each configured email account defined for the session's profile. application.Session.Accounts returns an Accounts collection for the current profile, tracking information for all accounts including Exchange, IMAP, and POP3 accounts, each of which can be associated with a different delivery store. The Account object that has an associated SmtpAddress property value that matches the sender's SMTP address is the account to use to send the email message.

After identifying the appropriate account, the code completes by setting the SendUsingAccount property of the mail item to that Account object, and then calling the Send() method.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code shows how to programmatically attach a copy of a contact item to a mail message. To demonstrate this functionality, in Visual Studio, create a new managed Outlook add-in named EmbedOutlookItemAddIn, and replace the contents of the ThisAddIn.vb or ThisAddIn.cs file with the example code shown here. Modify the ThisAddIn_Startup procedure and update the email addresses appropriately. The SMTP address included in the call to the SendMailWithAttachments procedure must correspond to the SMTP address of one of the outgoing email accounts you have previously configured in Outlook.

C# Copy code Copy code
using System;
using System.Collections.Generic;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace EmbedOutlookItemAddIn
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            List<string> recipients = new List<string>();
            recipients.Add("john@contoso.com");
            recipients.Add("john@example.com");

            // Replace the SMTP address for sending.
            SendMailItem(Application, "Outlook started", "Outlook started at " +
                DateTime.Now, recipients, "john@contoso.com");
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        public void SendMailItem(Outlook.Application application,
            string subject, string body,
            List<string> recipients, string smtpAddress)
        {

            Outlook.MailItem newMail =
                application.CreateItem(Outlook.OlItemType.olMailItem) as Outlook.MailItem;

            // Set up all the recipients.
            foreach (var recipient in recipients)
            {
                newMail.Recipients.Add(recipient);
            }
            if (newMail.Recipients.ResolveAll())
            {
                // Set the details.
                newMail.Subject = subject;
                newMail.Body = body;

                Outlook.ContactItem contact = (Outlook.ContactItem)(application.CreateItem
                    Outlook.OlItemType.olContactItem));

                // Create a new contact. Use an existing contact instead,
                // if you have one to work with.
                contact.FullName = "Kim Abercrombie";
                contact.LastName = "Kim";
                contact.FirstName = "Abercrombie";
                contact.HomeTelephoneNumber = "555-555-1212";
                contact.Save();

                newMail.Attachments.Add(contact, Outlook.OlAttachmentType.olEmbeddeditem);
                newMail.SendUsingAccount = GetAccountForEmailAddress(application, smtpAddress);
                newMail.Send();
             }
          }

        public Outlook.Account GetAccountForEmailAddress(Outlook.Application application,
            string smtpAddress)
        {
            // Loop over the Accounts collection of the current Outlook session.
            Outlook.Accounts accounts = application.Session.Accounts;
            foreach (Outlook.Account account in accounts)
            {
                // When the email address matches, return the account.
                if (account.SmtpAddress == smtpAddress)
                {
                    return account;
                }
             }
             // If you get here, no matching account was found.
             throw new System.Exception(string.Format("No Account with SmtpAddress: {0} exists!",
                 smtpAddress));
        }
    }

    #region VSTO generated code

    /// <summary>
    /// Required method for Designer support - do not modify
    /// the contents of this method with the code editor.
    /// </summary>
    private void InternalStartup()
    {
        this.Startup += new System.EventHandler(ThisAddIn_Startup);
        this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
    }

    #endregion

}
Visual Basic Copy code Copy code
Public Class ThisAddIn

    Private Sub ThisAddIn_Startup() Handles Me.Startup
        Dim recipients As New List(Of String)
        recipients.Add("john@contoso.com")
        recipients.Add("john@example.com")

        ' Replace the SMTP address for sending.
        SendMailItem(Application, "Outlook started",
            "Outlook started at " & DateTime.Now, recipients,
            "john@contoso.com")
    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown

    End Sub

    Private Sub SendMailItem(ByVal application As Outlook.Application, _
        ByVal subject As String, ByVal body As String, ByVal recipients As List(Of String), _
        ByVal smtpAddress As String)

        Dim newMail As Outlook.MailItem = _
            DirectCast(application.CreateItem(Outlook.OlItemType.olMailItem), _
            Outlook.MailItem)

        ' Set up all the recipients.
        For Each recipient In recipients
            newMail.Recipients.Add(recipient)
        Next
        If newMail.Recipients.ResolveAll() Then
          ' Set the details.
          newMail.Subject = subject
          newMail.Body = body

          Dim contact As Outlook.ContactItem =_
             DirectCast(application.CreateItem(
             Outlook.OlItemType.olContactItem), Outlook.ContactItem)

          ' Create a new contact. Use an existing contact instead,
          ' if you have one to work with.
          contact.FullName = "Kim Abercrombie"
          contact.LastName = "Kim"
          contact.FirstName = "Abercrombie"
          contact.HomeTelephoneNumber = "555-555-1212"
          contact.Save()

          newMail.Attachments.Add(contact, Outlook.OlAttachmentType.olEmbeddeditem)
          newMail.SendUsingAccount = GetAccountForEmailAddress(application, smtpAddress)
          newMail.Send()
        End If
    End Sub

    Private Function GetAccountForEmailAddress(ByVal application As Outlook.Application,_
        ByVal smtpAddress As String) As Outlook.Account
        ' Loop over the Accounts collection of the current Outlook session.
        Dim accounts As Outlook.Accounts = application.Session.Accounts
        For Each account In accounts
            ' When the email address matches, return the account.
            If account.SmtpAddress = smtpAddress Then
                Return account
            End If
        Next
        ' If you get here, no matching account was found.
        Throw New System.Exception(_
            String.Format("No Account with SmtpAddress: {0} exists!", smtpAddress))
    End Function
End Class

See also

Concepts

How to: Attach a File to a Mail Item
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message


How to: Limit the Size of an Attachment to an Outlook Email Message

 Copy code hover
[image]

How to: Limit the Size of an Attachment to an Outlook Email Message
See also Send feedback

This topic describes how you can create a managed add-in for Outlook that cancels sending email if the total attachment size is greater than a fixed limit.

Provided by: Ken Getz, MCW Technologies, LLC

A given email message can contain one or more file attachments, and you may want to limit the total attachment size in email messages that you send. The sample code in this topic demonstrates how you can handle the ItemSend event in an Outlook add-in, and in the event handler, cancel the sending of the email message if the combined size of all the attachments is larger than a specific value (2 MB, in this example).

The Outlook ItemSend event receives as its parameters a reference to the item being sent, and a Boolean variable that is passed by reference and that allows you to cancel the send operation. It is up to your own code in the event handler to determine whether you want to cancel the event; you do so by setting the Cancel parameter to True if you do wish to cancel the event.

In this example, to determine whether the total attachment size is larger than a specific size, the code loops through each attachment in the item's Attachments collection. For each item, the code retrieves the Size property, summing as it loops. If the sum ever exceeds the size of the maxSize constant, the code sets the tooLarge variable to True, and exits the loop. After the loop, if the tooLarge variable is True, the code alerts the user and sets the Cancel parameter to the event handler (which was passed by reference) to True, causing Outlook to cancel the sending of the item.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code shows how to cancel sending an email if the total attachment size is greater than the specified limit. To demonstrate this functionality, in Visual Studio, create a new managed Outlook add-in named LimitAttachmentSizeAddIn. Replace the code in ThisAddIn.cs or ThisAddIn.vb with the example code shown here.

C# Copy code Copy code
using Outlook = Microsoft.Office.Interop.Outlook;

namespace LimitAttachmentSizeAddIn
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
          Application.ItemSend +=new Outlook.ApplicationEvents_11_ItemSendEventHandler(Application_ItemSend);
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        void Application_ItemSend(object Item, ref bool Cancel)
        {
            // Specify the maximum size for the attachments. For this example,
            // the maximum size is 2 MB.
            const int maxSize = 2 * 1024 * 1000;
            bool tooLarge = false;

            Outlook.MailItem mailItem = Item as Outlook.MailItem;
            if (mailItem != null)
            {
                var attachments = mailItem.Attachments;
                double totalSize = 0;
                foreach (Outlook.Attachment attachment in attachments)
                {
                    totalSize += attachment.Size;
                    if (totalSize > maxSize)
                    {
                        tooLarge = true;
                        break;
                    }
                }
            }
            if (tooLarge)
            {
                // If the sum of the attachment sizes is too large, alert the user
                // and cancel the send.
                System.Windows.Forms.MessageBox.Show(
                    "The total attachment size is too large. Sending canceled.",
                    "Outlook Add-In");
                Cancel = true;
            }
        }

        #region VSTO generated code

        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }

        #endregion
    }
}
Visual Basic Copy code Copy code
Public Class ThisAddIn

    Private Sub ThisAddIn_Startup() Handles Me.Startup

    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown

    End Sub

    Private Sub Application_ItemSend(ByVal Item As Object, ByRef Cancel As Boolean) Handles Application.ItemSend
        ' Specify the maximum size for the attachments. For this example,
        ' the maximum size is 2 MB.
        Const maxSize As Integer = 2 * 1024 * 1000
        Dim tooLarge As Boolean = False

        Dim mailItem As Outlook.MailItem = TryCast(Item, Outlook.MailItem)
        If mailItem IsNot Nothing Then
            Dim attachments = mailItem.Attachments
            Dim totalSize As Double = 0

            For Each attachment As Outlook.Attachment In attachments
                totalSize += attachment.Size
                If totalSize > maxSize Then
                    tooLarge = True
                    Exit For
                End If
            Next attachment
        End If

        If tooLarge Then
            ' If the sum of the attachment sizes is too large, alert the user
            ' and cancel the send.
            System.Windows.Forms.MessageBox.Show(
                "The total attachment size is too large. Sending canceled.",
                "Outlook Add-In")
            Cancel = True
        End If
    End Sub
End Class

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Modify an Attachment of an Outlook Email Message


How to: Modify an Attachment of an Outlook Email Message

 Copy code hover
[image]

How to: Modify an Attachment of an Outlook Email Message
See also Send feedback

This topic describes how you can programmatically modify a Microsoft Outlook email attachment without changing the original file.

Provided by: Ken Getz, MCW Technologies, LLC

Sending an email message with one or more attachments is easy, both in the Outlook interface and programmatically. In some scenarios, however, you may want to be able to modify the attachment after it has been attached to the mail item, without changing the original file in the file system. In other words, you may need a programmatic way to access the contents of the attachment in memory.

For example, imagine that your application requires converting the text in all attachments that have a .txt extension to uppercase. In a managed Outlook add-in, you can easily handle the ItemSend event. In that event, perform the work before sending the mail item. The difficult part of the scenario is in retrieving the contents of the attachments to modify the contents of each text file.

The sample code in this topic demonstrates how to solve this particular problem, using the GetProperty(String) and SetProperty(String, Object) methods of the Attachment interface. In each case, you supply a value that contains the MAPI property PidTagAttachDataBinary to obtain (and then set) the contents of the attachment.

Note Note

The namespace representation of the PidTagAttachDataBinary property is http://schemas.microsoft.com/mapi/proptag/0x37010102. For more information about using the PropertyAccessor object on properties that are referenced by namespace, see Referencing Properties by Namespace.

The sample code handles the ItemSend event of a mail item. In the custom event handler, for any attachment that has a .txt extension, the code calls the ConvertAttachmentToUpperCase method. ConvertAttachmentToUpperCase takes an Attachment object and a MailItem object as input arguments, retrieves a byte array that is filled with the contents of the attachment, converts the byte array to a string, converts the string to uppercase, and then sets the contents of the attachment to the converted string as a byte array.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code shows how to programmatically modify an Outlook email attachment without changing the original file. To demonstrate this functionality, in Visual Studio, create a new managed Outlook add-in named ModifyAttachmentAddIn. Replace the code in ThisAddIn.cs or ThisAddIn.vb with the following code.

C# Copy code Copy code
using Outlook = Microsoft.Office.Interop.Outlook;

namespace ModifyAttachmentAddIn
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            Application.ItemSend += new Outlook.ApplicationEvents_11_ItemSendEventHandler(Application_ItemSend);
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        void Application_ItemSend(object Item, ref bool Cancel)
        {
            Outlook.MailItem mailItem = Item as Outlook.MailItem;

            if (mailItem != null)
            {
                var attachments = mailItem.Attachments;
                // If the attachment a text file, convert its text to all uppercase.
                foreach (Outlook.Attachment attachment in attachments)
                {

                    ConvertAttachmentToUpperCase(attachment, mailItem);
                }
            }
        }

        private void ConvertAttachmentToUpperCase(Outlook.Attachment attachment, Outlook.MailItem mailItem)
        {
            const string PR_ATTACH_DATA_BIN =
                "http://schemas.microsoft.com/mapi/proptag/0x37010102";

            // Confirm that the attachment is a text file.
            if (System.IO.Path.GetExtension(attachment.FileName) == ".txt")
            {
                // There are other heuristics you could use to determine whether the
                // the attachment is a text file. For now, keep it simple: Only
                // run this code for *.txt.

                // Retrieve the attachment as an array of bytes.
                var attachmentData =
                    attachment.PropertyAccessor.GetProperty(
                    PR_ATTACH_DATA_BIN);

                // Convert the byte array into a Unicode string.
                string data = System.Text.Encoding.Unicode.GetString(attachmentData);
                // Convert to upper case.
                data = data.ToUpper();
                // Convert the data back to an array of bytes.
                attachmentData = System.Text.Encoding.Unicode.GetBytes(data);

                //Set PR_ATTACH_DATA_BIN to attachmentData.
                attachment.PropertyAccessor.SetProperty(PR_ATTACH_DATA_BIN,
                    attachmentData);
            }
        }

        #region VSTO generated code

        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }

        #endregion
    }
}
Visual Basic Copy code Copy code
Public Class ThisAddIn

    Private Sub ThisAddIn_Startup() Handles Me.Startup

    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown

    End Sub

    Private Sub Application_ItemSend(ByVal Item As Object, _
        ByRef Cancel As Boolean) Handles Application.ItemSend

        Dim mailItem As Outlook.MailItem = TryCast(Item, Outlook.MailItem)

        If mailItem IsNot Nothing Then
            Dim attachments = mailItem.Attachments
            For Each attachment As Outlook.Attachment In attachments
                ' If the attachment is a text file, convert to uppercase.
                ConvertAttachmentToUpperCase(attachment, mailItem)
            Next attachment
        End If
    End Sub

    Private Sub ConvertAttachmentToUpperCase(ByVal attachment As Outlook.Attachment, _
        ByVal mailItem As Outlook.MailItem)
        Const PR_ATTACH_DATA_BIN As String = "http://schemas.microsoft.com/mapi/proptag/0x37010102"

        ' Confirm that the attachment is a text file.
        If System.IO.Path.GetExtension(attachment.FileName) = ".txt" Then

            ' There are other heuristics you could use to determine whether the
            ' the attachment is a text file. For now, keep it simple: Only
            ' run this code for *.txt.

            ' Retrieve the attachment as an array of bytes.
            Dim attachmentData = attachment.PropertyAccessor.GetProperty(PR_ATTACH_DATA_BIN)

            ' Convert the byte array into a Unicode string.
            Dim data As String = System.Text.Encoding.Unicode.GetString(attachmentData)
            ' Convert to upper case.
            data = data.ToUpper()
            ' Convert the data back to an array of bytes.
            attachmentData = System.Text.Encoding.Unicode.GetBytes(data)

            'Set PR_ATTACH_DATA_BIN to attachmentData.
            attachment.PropertyAccessor.SetProperty(PR_ATTACH_DATA_BIN, attachmentData)
         End If
    End Sub

End Class

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message


Categories

 Copy code hover
[image]

Categories
Send feedback

In this section

  • Categorize Your Outlook Items


Categorize Your Outlook Items

 Copy code hover
[image]

Categorize Your Outlook Items
Send feedback

Microsoft Outlook provides color categorization functionality, in which Outlook items can be categorized and displayed by category. Multiple color categories can be applied to a single Outlook item, and Outlook items can be grouped or sorted by color category. Shortcut keys can be assigned to each color category, to allow users to more easily categorize items. Color categories are user-defined, and can be created, deleted, and changed either programmatically or by user action within the Outlook user interface.

The Category object represents a single user-defined color category in the Master Category List, the list of color categories presented in the Outlook user interface and represented by the Categories collection of the NameSpace object. Category objects are identified with a globally unique identifier (GUID) when created, and this identifier cannot be changed. However, the name, color, and shortcut key associated with a color category can be changed by setting the Name, Color, and ShortcutKey properties, respectively, of the Category object. The CategoryID property can be used to retrieve the identifier of a Category object.

Assigning Categories to Outlook Items

Categories can be assigned to Outlook items by specifying the names of the appropriate Category objects in a comma-delimited string in the Categories property of the following objects:

AppointmentItem | RemoteItem
ContactItem | ReportItem
DistListItem | SharingItem
DocumentItem | PostItem
JournalItem | TaskItem
MailItem | TaskRequestAcceptItem
MeetingItem | TaskRequestDeclineItem
MobileItem | TaskRequestItem
NoteItem | TaskRequestUpdateItem

Outlook items are displayed based on the category name stored in the Categories property of that Outlook item. Because category names are stored as part of the Outlook item, it is possible to have a category name in an Outlook item that is not present in the Master Category List. For example, a category may have been removed.

If a Category object with a corresponding Name property value does not exist in the Categories collection of the NameSpace object that contains the Outlook item, the category name associated with that Outlook item is still displayed, but without an associated color.


Conversations (Outlook)

 Copy code hover
[image]

Conversations (Outlook)
Send feedback

In this section

  • Managing Outlook Items as Conversations

  • How to: Obtain and Enumerate Selected Conversations


Managing Outlook Items as Conversations

 Copy code hover
[image]

Managing Outlook Items as Conversations
See also Send feedback

In Microsoft Outlook, a conversation groups messages that share the same subject and belong to the same thread. In the Outlook user interface, you can expand a conversation in Conversation view to provide a visual relationship between messages, including any responses and related messages from other folders. A conversation can also include branches, such as when a message gets two or more responses and discussions grow independently from each. Since Microsoft Outlook 2010, Conversation view relates all items in the same conversation across folders and stores.

From the programmatic perspective, items in the same conversation can be heterogeneous, belonging to one or more item types. For example, a conversation can contain MailItem and TaskItem objects. Before Outlook 2010, support for items that belong to the same conversation was limited to the ConversationIndex and ConversationTopic properties (for all item types except the NoteItem object). Clearing the ConversationIndex was limited to the MailItem, PostItem, and SharingItem objects. Since Outlook 2010, Outlook supports the Conversation object, which relates all items in the same conversation across folders and across stores by using the ConversationID property on the Conversation object as well as on each item of the conversation. Outlook provides a GetConversation method for most item types to enable you to obtain a Conversation object based on the item.

Conversation view is supported by stores that are POP, IMAP, PST, or Microsoft Exchange Server (at least Microsoft Exchange Server 2010, or Microsoft Exchange Server 2007 if Outlook is running in cached mode). You can call the IsConversationEnabled property of the Store object to verify whether the store supports Conversation view. You can call the GetConversation method to get a Conversation object based on an item in the conversation only if the store in which the item resides supports Conversation view.

To navigate a conversation hierarchy, you can call the GetChildren, GetParent, and GetRootItems methods of the Conversation object. The SimpleItems collection exists to provide easy access to items of the conversation. The order of items in the SimpleItems collection is the same as the order of items in the conversation. The collection is ordered by the MAPI PidTagCreationTime property of each item in ascending order.

To enumerate items in a conversation, you can use the Table object. The rows of the table represent items of the conversation, and the columns of the table, which you can customize, represent properties for each item. To obtain conversation items by using a Table object, use the following procedure:

  1. Obtain the object of any item in the conversation.

  2. To verify that the store supports Conversation view, use the IsConversationEnabled property of the Store object that represents the store in which the item resides. You can obtain a Conversation object based on an item only if the item resides in a store that supports Conversation view.

  3. If the store supports Conversation view, call the GetConversation method of that item to get the Conversation object.

  4. Call the GetTable method of that Conversation object to get a Table.

  5. You can now use methods that the Table object supports to enumerate rows that represent conversation items, and use the default columns to access default item properties (or customize columns to access other properties of the items).

You can use the SetAlwaysDelete and SetAlwaysMoveToFolder methods to always move existing conversation items, and future items that arrive in a specific conversation, to the Deleted Items folder or another folder. The moving of items is supported in the specific store where the item resides, unless the store is a non-delivery store such as a PST store. You can use the GetAlwaysDelete and GetAlwaysMoveToFolder methods to get these folders, and the StopAlwaysDelete and StopAlwaysMoveToFolder methods to stop moving existing and future conversation items to such folders.

In addition, you can apply actions to all existing and future items of a conversation.

  • Call the SetAlwaysAssignCategories and GetAlwaysAssignCategories methods to set and get categories, respectively, for existing and future conversation items.

  • Call the MarkAsRead and MarkAsUnread methods to mark items as read or unread, respectively.

See also

Concepts

How to: Obtain and Enumerate Selected Conversations


How to: Obtain and Enumerate Selected Conversations

 Copy code hover
[image]

How to: Obtain and Enumerate Selected Conversations
Send feedback

By default, Microsoft Outlook displays items in the Inbox by conversation. If a user makes a selection in the Inbox, you can obtain the selection programmatically, including conversation headers and conversation items. The code example in this topic shows how to obtain a selection in the Inbox and enumerate the mail items in each conversation in the selection.

The example contains one method, DemoConversationHeadersFromSelection. The method sets the current view to the Inbox, and then checks to see if the current view is a table view that displays conversations sorted by date. To obtain a selection, including any selected ConversationHeader objects, DemoConversationHeadersFromSelection uses the GetSelection method of the Selection object, specifying the OlSelectionContents.olConversationHeaders constant as an argument. If conversation headers are selected, DemoConversationHeadersFromSelection uses the SimpleItems object to enumerate items in each selected conversation, and then displays the subject of those conversation items that are MailItem objects.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void DemoConversationHeadersFromSelection()
{
    // Obtain Inbox.
    Outlook.Folder inbox =
        Application.Session.GetDefaultFolder(
        Outlook.OlDefaultFolders.olFolderInbox)
        as Outlook.Folder;

    // Set ActiveExplorer.CurrentFolder to Inbox.
    // Inbox must be current folder.
    Application.ActiveExplorer().CurrentFolder = inbox;

    // Ensure that the current view is a table view.
    if (inbox.CurrentView.ViewType ==
        Outlook.OlViewType.olTableView)
    {
        Outlook.TableView view =
            inbox.CurrentView as Outlook.TableView;
        // And check if the table view organizes conversations by date.
        if (view.ShowConversationByDate == true)
        {
            Outlook.Selection selection =
                Application.ActiveExplorer().Selection;
            Debug.WriteLine("Selection.Count = " + selection.Count);

             // Call GetSelection to create a Selection object
            //  that includes any selected conversation header objects.
            Outlook.Selection convHeaders =
                selection.GetSelection(
                Outlook.OlSelectionContents.olConversationHeaders)
                as Outlook.Selection;
            Debug.WriteLine("Selection.Count (ConversationHeaders) = "
                + convHeaders.Count);

            // Check if any conversation headers are selected.
            if (convHeaders.Count >= 1)
            {
                foreach (Outlook.ConversationHeader convHeader in convHeaders)
                {
                    // Enumerate the items in each conversation header object.
                    Outlook.SimpleItems items = convHeader.GetItems();
                    for (int i = 1; i <= items.Count; i++)
                    {
                        // Only enumerate MailItems in this example.
                        if (items[i] is Outlook.MailItem)
                        {
                            Outlook.MailItem mail =
                                items[i] as Outlook.MailItem;
                            Debug.WriteLine(mail.Subject
                                + " Received:" + mail.ReceivedTime);
                        }
                    }
                }
            }
        }
    }
}


Electronic Business Cards (Outlook)

 Copy code hover
[image]

Electronic Business Cards (Outlook)
Send feedback

In this section

  • Customize and Share Business Cards

  • How to: Share Contact Information Including the Business Card


Customize and Share Business Cards

 Copy code hover
[image]

Customize and Share Business Cards
Send feedback

Contact information stored in Microsoft Outlook can be represented as an Electronic Business Card (EBC), in which the layout and formatting of the information contained in a ContactItem object can be customized for that contact item. An Electronic Business Card can be shared with other users and can be used as a signature on Outlook mail items.

The ContactItem object has a default business card design associated with it at the time the object is created, and this design can be changed at any time either programmatically or by using the Edit Business Card dialog box. Only one Electronic Business Card design can be defined for a single ContactItem object. You can use the ShowBusinessCardEditor method of the ContactItem object to programmatically display the Edit Business Card dialog box. For more information about creating an Electronic Business Card design for a ContactItem object using the Edit Business Card dialog box, search for the topic "Create Electronic Business Cards" in the Outlook Help.

Several methods are provided in Office Outlook 2007 to share contact information, including Electronic Business Cards. You can use the ForwardAsVcard and ForwardAsBusinessCard method of the ContactItem object in to create a new MailItem object that contains the contact information from the specified ContactItem attached as a vCard (.vcf) file, or you can use the AddBusinessCard method of the MailItem object to attach the contact information for a specified ContactItem as a vCard file.

If you use the ForwardAsBusinessCard or AddBusinessCard methods, the Electronic Business Card is also appended to the body of the mail item if the BodyFormat property of the MailItem object is set to olFormatHTML. You can also use the SaveBusinessCardImage method of the ContactItem object to save an Electronic Business Card as a Portable Network Graphics (.png) image file.


How to: Share Contact Information Including the Business Card

 Copy code hover
[image]

How to: Share Contact Information Including the Business Card
Send feedback

You can use the ForwardAsVcard and ForwardAsBusinessCard method of the ContactItem object to create a new MailItem object that contains the contact information from the specified ContactItem attached as a vCard (.vcf) file, or you can use the AddBusinessCard method of the MailItem object to attach the contact information for a specified ContactItem as a vCard file. If you use the ForwardAsBusinessCard or AddBusinessCard methods, an image of the business card is also appended to the body of the mail item if the BodyFormat property of the MailItem object is set to olFormatHTML.

The following code sample in Microsoft Visual Basic for Applications (VBA) is a function, ForwardContactItem, that accepts a ContactItem object as a parameter and forwards the ContactItem object as an attachment to a new mail item. ForwardContactItem first checks if the object is a valid object. If the object is valid, ForwardContactItem calls the ForwardAsBusinessCard method of the ContactItem object to create a new MailItem object that has the contact information attached as a vCard. ForwardContactItem then displays and returns the MailItem object.

VBA Copy code Copy code
Private Function ForwardContactItem(objContactItem As Outlook.ContactItem) As Outlook.MailItem

 Dim objMailItem As MailItem

 On Error GoTo ErrRoutine

 If objContactItem Is Nothing Then
 ForwardContactItem = Nothing
 Else
 ' Forward the contact item, including a business card
 ' image, and display the new MailItem object.
 Set objMailItem = objContactItem.ForwardAsBusinessCard
 objMailItem.Display
 ForwardContactItem = objMailItem
 End If

EndRoutine:
 Exit Function

ErrRoutine:
 MsgBox Err.Number & " - " & Err.Description, _
 vbOKOnly Or vbCritical, _
 "ForwardContactItem"
 GoTo EndRoutine
End Function


Events (Outlook)

 Copy code hover
[image]

Events (Outlook)
Send feedback

In this section

  • Working with Outlook Events

  • Using Events with Automation


Working with Outlook Events

 Copy code hover
[image]

Working with Outlook Events
Send feedback

Outlook provides a wide range of events through which it can notify your Microsoft Visual Basic, Microsoft Visual Basic for Applications (VBA), and Microsoft Visual Basic Scripting Edition (VBScript) programs that a significant change has occurred. For example, Outlook events can notify a program when an item has been opened or when a new mail arrives in the InBox.

To receive notification of a significant event, write an event-handler procedure. Depending on whether the event is handled in Visual Basic or Visual Basic for Applications or in VBScript, this is either a Sub or a Function that Outlook calls when the event is called. The code you put in the event handler allows your program to respond appropriately to the event and, in some cases, even lets your program cancel the default action associated with the event, such as preventing a mail item from being sent.

Types of Events

Outlook events can be divided into two main categories: item-level events and application-level events.

Item-level events pertain to a particular item, and are typically handled by VBScript code contained within the form associated with the item. These events notify your program when an item has been opened, sent or posted, saved, or closed, and when the user has replied to or forwarded a message or initiated a custom action. Item-level events can also notify your program when the user has clicked a control on the form or when an item property has changed.

Application-level events are typically handled by Visual Basic or Visual Basic for Applications because they pertain to more than the items associated with a particular form. Application-level events can pertain to the application itself, to explorer collections and windows (including the Shortcuts pane), inspector collections and windows, folders and folders collections, items collections, and synchronization objects.

Responding to Events

To respond to item-level events, add event-handler procedures to the script of the form that displays the item. For example, to run code when an item is opened in the form, add a procedure like the following to the script in the form.

Copy code Copy code
Function Item_Open()
 MsgBox "A new item has opened in this form."
End Function

Responding to application-level events is somewhat more involved because steps must be taken to associate the event handler with the part of Outlook in which the event is occurring. Learn about writing an application-level event handler.

Order of Events

Except for certain form events, your program cannot assume that events will occur in a particular order, even if they appear to be called in a consistent sequence. The order in which Outlook calls event handlers might change depending on other events that might occur, or the order might change in future versions of Outlook.


Using Events with Automation

 Copy code hover
[image]

Using Events with Automation
Send feedback

To create an event handler for Microsoft Outlook objects in Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) in another application, you need to complete the following four steps:

  1. Set a reference to the Outlook Object Library.

  2. Declare an object variable to respond to the events.

  3. Write the specific event procedures.

  4. Initialize the declared object.

Learn about working with events in Outlook Visual Basic for Applications.

Set the Reference to the Outlook Object Library

Before you can use an Outlook object in Visual Basic or Visual Basic for Applications code, you must first set a reference to the Outlook Object Model in the References dialog box. For more information about using this dialog box, see the online Help for your programming environment.

Declare the Object Variable

Once you've referenced the object model library, you must declare variables that reference the object you want to use. You can declare the variable in the module in which the object will be used (that is, the module containing the event-handler procedure), but more commonly you' ll declare it in a class module so it can be used in any module in your program.

For example, to declare an object variable for the Application object in a class module, you use code like the following.

Copy code Copy code
Public WithEvents myOlApp As Outlook.Application

You must use the WithEvents keyword to specify that the object variable will be used to respond to events triggered by the object.

Write the Event Procedure

After the new object has been declared with events, it appears in the Object list in the class module Code window, and you can select the object's event procedures from the Procedures/Events list. For example, when you select the ItemSend event for an Application object declared as myOlApp, the following empty procedure appears in the Code window.

Copy code Copy code
Private Sub myOlApp_ItemSend(Item as Object, Cancel as Boolean)

End Sub

Initialize the Declared Object

Before the procedure will run, you must connect the declared object (in this example, myOlApp) with the Application object. If you declared the object in a class module named EventClassModule, then you can use the following code in any module.

VBA Copy code Copy code
Dim myClass as New EventClassModule
Sub Register_Event_Handler()
    Set myClass.myOlApp = "Outlook.Application"
End Sub

When the

Copy code Copy code
Register_Event_Handler

procedure is run, the myOlApp object in the form or class module points to the Outlook Application object, and the event procedure will run when the event occurs.


Follow-Up

 Copy code hover
[image]

Follow-Up
Send feedback

In this section

  • Setting Items for Follow-up


Setting Items for Follow-up

 Copy code hover
[image]

Setting Items for Follow-up
Send feedback

Microsoft Outlook provides a new task flagging system in which certain Outlook items such as mail items or contact items can be flagged for follow-up. Flagging an Outlook item for follow-up displays information about that Outlook item, along with other task-based information, on the To-Do Bar and Calendar navigation module in the Outlook user interface.

The following Outlook item objects have been extended to support the task flagging system:

  • ContactItem

  • DistListItem

  • MailItem

  • PostItem

  • SharingItem

Marking an Item as a Task

You can determine if an Outlook item object is marked for follow-up by checking the value of the IsMarkedAsTask property for an Outlook item. Use the MarkAsTask method to mark an Outlook item for follow-up and the ClearTaskFlag method to unmark the Outlook item.

Setting Task Properties

When an Outlook item is marked for follow-up using the MarkAsTask method, an OlMarkInterval constant is used to specify default settings for the TaskStartDate, TaskDueDate, TaskCompletedDate, and ToDoTaskOrdinal properties of the Outlook item. These properties are used not only to determine the duration and completion state of the task associated with the Outlook item, but also to determine the order in which the Outlook item is displayed in the To-Do Bar and Calendar navigation module.

However, you can programmatically set these properties individually, after calling the MarkAsTask method, to support custom durations, or to change the completion state or display order of the Outlook item.

Once an Outlook item is flagged for follow-up, you can also set the TaskSubject property of the Outlook item to display a task description other than the value of the Subject property for the flagged Outlook item.

Task Items and Task Flagging

The TaskItem object supports the ToDoTaskOrdinal property, so that the display order for Outlook task items displayed on the To-Do Bar can also be changed programmatically.

Filtering Items Marked as Tasks

You can take advantage of the DAV Searching and Locating (DASL) filtering capabilities of Outlook to filter Outlook items marked for follow-up. The following Visual Basic for Applications (VBA) example defines a DASL filter that filters only those Outlook items with an IsMarkedAsTask property value set to True, then uses the filter to build a Table object containing filtered Outlook items retrieved from the Inbox default folder.

Copy code Copy code
Private Sub TableForIsMarkedAsTask()
 Dim objTable As Outlook.Table
 Dim objRow As Outlook.Row
 Dim strFilter As String

 On Error GoTo ErrRoutine

 ' Define a DASL filter string that filters only those items
 ' with an IsMarkedAsTask property value set to True.
 strFilter = "@SQL=" & Chr(34) & _
 "http://schemas.microsoft.com/mapi/proptag/0x0E2B0003" & _
 Chr(34) & " = 1"

 ' Use the filter to construct a table of Outlook items
 ' retrieved from the Inbox default folder.
 Set objTable = Application.Session.GetDefaultFolder(olFolderInbox).GetTable(strFilter)

 With objTable
 ' Add task-related columns to the table.
 .Columns.Add ("From")
 .Columns.Add ("FlagRequest")
 .Columns.Add ("TaskStartDate")
 .Columns.Add ("TaskDueDate")
 .Columns.Add ("TaskCompletedDate")

 ' Report the contents of the table
 ' to the Immediate window.
 Do Until .EndOfTable
 Set objRow = .GetNextRow
 Debug.Print objRow("Subject"), _
 objRow("From"), _
 objRow("FlagRequest"), _
 objRow("TaskStartDate"), _
 objRow("TaskDueDate"), _
 objRow("TaskCompletedDate")
 Loop
 End With

EndRoutine:
 ' Clean up
 Set objRow = Nothing
 Set objTable = Nothing

 Exit Sub

ErrRoutine:
 MsgBox Err.Number & " - " & Err.Description, _
 vbOKOnly Or vbCritical, _
 "TableForIsMarkedAsTask"

 GoTo EndRoutine
End Sub


Forms (Outlook)

 Copy code hover
[image]

Forms (Outlook)
Send feedback

In this section

  • Overview (Outlook Forms)

  • Understanding Outlook Forms

  • Customizing Outlook Forms


Overview (Outlook Forms)

 Copy code hover
[image]

Overview (Outlook Forms)
Send feedback

In this section

  • Customizing Form Pages and Form Regions

  • Best Practices to Migrate Outlook 97-2003 Custom Forms


Customizing Form Pages and Form Regions

 Copy code hover
[image]

Customizing Form Pages and Form Regions
Send feedback

You can customize a form in Outlook in two ways: by customizing pages of the form, and by creating form regions for the form. Customizing form pages has been supported since Microsoft Office Outlook 97, and form regions are supported since Microsoft Office Outlook 2007.

This topic compares customizing forms on form pages with customizing forms on form regions, and identifies the advantages of form regions.

Note Note

Even though custom form pages and form regions can exist in the same custom form, for simpler deployment and easier maintenance, you should develop future custom form solutions using only form regions. For more information on your options for existing form solutions, see Best Practices to Migrate Outlook 97-2003 Custom Forms.

Comparison Aspect

Form Pages

Form Regions

Outlook version

Supported since Microsoft Office Outlook 97.

Supported since Office Outlook 2007.

Customization venue

Adding fields and controls in the Outlook forms designer. Optionally programming controls in VBScript using the Script Editor.

Adding fields and controls in the Outlook forms designer. Optionally programming controls using an add-in.

Controls

When running on versions of Outlook prior to Office Outlook 2007, form pages support Microsoft Forms 2.0 controls and some third-party ActiveX controls, but not Outlook controls. When running on Office Outlook 2007 or later, form pages support Forms 2.0 controls and Outlook controls. Form pages always display Forms 2.0 controls with a classic look. For more information, see Controls in a Custom Form.

Form regions support Microsoft Forms 2.0 controls, some third-party ActiveX controls, and Outlook controls. By default, Outlook replaces some Forms 2.0 controls that have themed Outlook counterpart controls by the corresponding themed controls, and therefore always displays them with a themed look. For more information, see Controls in a Custom Form.

Scope of customization in design time

You can only customize the following pages:

  • The Message page of the message form (IPM.Note)

  • The Message page of the post form (IPM.Post)

  • The General page of the contact form (IPM.Contact)

  • Up to 5 form pages (P2 to P6) for each standard Outlook form

You can hide supplementary pages in a standard form (for example, the Details page of the contact form), but you cannot customize them.

You can customize the following pages:

  • The default page of any standard form.

  • Up to 30 separate form regions as extra pages.

You can also use a standard form as a template, replace the default page by a replacement form region or replace the entire standard form by a replace-all form region, and register that form region for a message class derived from the original message class.

Adding user interface to the default page

You can only add user interface to the default page of the message form, post form, and contact form, and pages P2 through P6 of any standard form. To add user interface to any other default page, for example, the default page of an appointment form, you will need to uncheck Display This Page to hide the page, re-create the default page on a supplementary page like P2, and add custom user interface to that page.

You can add user interface as adjoining form regions to the default page of any standard form.

Adding extra pages

Up to 5 form pages (P2 to P6) for each form. Check Display This Page to show the page in a form.

Up to 30 separate form regions and 50 adjoining form regions for each form.

Removing default user interface

You can remove default user interface on only the following pages:

  • The Message page of the message form

  • The Message page of the post form

  • The General page of the contact form

Alternatively, you can hide any default page or supplementary page in a standard form.

You can remove or hide default user interface the same way as under "Form Pages". Alternatively, you can create a replacement form region to "replace" the default page of a form, or create a replace-all form region to "replace" all pages of a form, without having to remove the user interface on the default page. Note that replacement and replace-all form regions are only supported for a custom message class derived from an Outlook message class.

Customizing entire page

You can hide any page in a standard form, and add custom user interface to pages P2 through P6.

You can hide any page in a standard form, use a separate form region to add an extra page to the form, use a replacement form region to replace the default page of the form, or use a replace-all form region to replace the entire form. Note that any replacement is only supported for a custom message class derived from an Outlook message class.

Support for new (derived) message classes

The administrator uses the Forms Administrator tool to register a custom form for a derived message class.

You can register form regions for a derived message class in the Windows registry.

Deployment

The administrator registers and installs the custom form. If an add-in exists for the form, the administrator installs it separately from the form.

An administrator installs the add-in. In turn, the add-in installs files for the form regions and registers the form regions for the custom form.

Display of customization in runtime

Customization is only displayed in the inspector.

Customization is displayed in the inspector and the Reading Pane.

Support for localized user interface

No

Supports localized strings for form region names, control names, and user actions based on locale.

Sharing between solutions

Each custom form can only be customized by one add-in (except through the ModifiedFormPages property of the Inspector object).

Except for the message class IPM, a form for any message class can be customized by more than one add-in.


Best Practices to Migrate Outlook 97-2003 Custom Forms

 Copy code hover
[image]

Best Practices to Migrate Outlook 97-2003 Custom Forms
Send feedback

In general, a custom form solution that was built with Microsoft Office Outlook 2003 or earlier and that has been published to a forms library or Outlook folder are still supported. If you are used to sending a custom form definition with items (as one-off forms) using Outlook 2003 or an earlier version of Outlook, there will be circumstances where this will fail, for example, if you use Microsoft Exchange Server 2007. In such cases, instead of sending the custom form definition, you should make the form available by publishing it to a forms library or an Outlook folder.

If you want to further customize your Outlook 97-2003 custom form to take advantage of form regions, it is best that you redesign the entire solution to use only form regions. In particular, if your Outlook 97-2003 custom form is associated with a custom message class, you should deprecate that form and associate the custom message class with the new form region solution.

However, if for some reason, you cannot implement some existing functionality using form regions, you should keep the existing custom form pages together with any of their custom actions as intact as possible, and implement only new functionality using form regions. In this case, you should add new actions as custom actions only to the form regions.


Understanding Outlook Forms

 Copy code hover
[image]

Understanding Outlook Forms
Send feedback

In this section

  • Forms and Message Classes

  • Fields and Controls

  • Customizing Forms (Outlook)


Forms and Message Classes

 Copy code hover
[image]

Forms and Message Classes
Send feedback

In this section

  • Designing Outlook Workgroup Solutions

  • How Outlook Forms and Items Work Together

  • Selecting the Item on Which to Base a Form

  • Form Name and Message Class Overview

  • Item Types and Message Classes

  • Changing the Form Used by Existing Items in a Folder

  • Globally Change a Default Form

  • Appointment Forms Overview

  • Contact Forms Overview

  • Distribution List Forms Overview

  • Journal Forms Overview

  • Mail Forms Overview

  • Post Forms Overview

  • Task Forms Overview

  • Understanding the Forms Cache


Designing Outlook Workgroup Solutions

 Copy code hover
[image]

Designing Outlook Workgroup Solutions
Send feedback

With Microsoft Outlook, you can create a variety of workgroup solutions and forms. You can create simple forms with no programming involved or create advanced forms by using custom controls, properties, and Microsoft Visual Basic Scripting Edition (VBScript). You can also use form regions, including Separate form regions, which are individual pages that you can add to a standard Outlook form, or that you can use to create a new custom form that is based on a standard Outlook form. For more information, see Form Regions.

There are a few basic approaches to creating Outlook solutions. One method is to modify an existing item, such as a contact entry or an e-mail message, by adding additional pages and fields. With this method, you can extend the use of the item by adding the fields and pages that you need without writing any code. To create advanced forms, you can use the Control Toolbox and VBScript to access properties, events, methods, and objects within Outlook.

What method do you want to use?

  • Extending a Form Region with an Add-in

  • Extending the Use of an Outlook Item by Adding Fields and Pages

  • Creating Custom Forms by Using VBScript


How Outlook Forms and Items Work Together

 Copy code hover
[image]

How Outlook Forms and Items Work Together
Send feedback

Microsoft Outlook stores its information in individual items in a folder. An Outlook item is similar to a record in a database in that it consists of a group of fields that collectively store information about the specific item.

Outlook displays the contents of an item in one of two ways: through a view in an explorer window, or through a form in an inspector window. A form usually provides a more complete display of the information and lets the user interact with the contents of the item in more ways. In a sense, a form is the principal user interface for an item. Outlook provides one or more standard forms for each type of item (mail message, contact, and so on). You can create customized versions of these forms to change the way Outlook displays items. You can display additional pages that are usually hidden, and you can add controls to those pages. Typically, these controls are bound to fields in the item so that the user can view and edit the contents of those fields. You can also customize forms by using form regions. For more information, see Customizing Form Pages and Form Regions.

Every item contains a Message Class field; this field contains the name of the form that Outlook provides to view and edit the item. For example, a contact item has a default message class of "IPM.Contact". If you create a custom form called "Customer", the Message Class field of items using that form will contain "IPM.Contact.Customer". The message class of all Outlook items always begins with "IPM". The second part of the message class denotes the type of Outlook form that the form is based on. The third portion of the message class is present only if the form is a customized version of a standard Outlook form.

If you are creating custom forms by using form regions, the message class must be specified in the Windows Registry. For more information, see Specifying Form Regions in the Windows Registry.


Selecting the Item on Which to Base a Form

 Copy code hover
[image]

Selecting the Item on Which to Base a Form
Send feedback

Each Microsoft Outlook item is a collection of fields. These collections of fields are what define the various forms. Some of these forms might be more useful for some applications than for others. To see the complete list of fields for an item, click All in the Field Chooser. For example, to see all the fields in a mail message, click All Mail Fields. If the field that you want is not listed, you can create a custom field by clicking New in the Field Chooser.

Form | What the form is used for
Contact | Keeping track of information about a person or organization.
Distribution List | Creating a list of contacts and e-mail addresses that can be used as a single e-mail address.
Task | Tracking information about a task.
Message | Sending information to someone in a specific format, or providing a means to enter data so that it can be shared electronically.
Post | Facilitating a threaded conversation that is saved in a folder, or for attaching files to a folder.
Appointment | Representing a meeting or scheduled event.
Journal Entry | Logging information about an item or event.
Meeting Request | Sending specifically formatted meeting requests and requesting a response.
Task Request | Sending information about a task to others and requestiong a response.
RSS Article | Representing a blog post or other item from an RSS feed.


Form Name and Message Class Overview

 Copy code hover
[image]

Form Name and Message Class Overview
Send feedback

The message class is an internal identifier that Microsoft Outlook and Microsoft Exchange use to locate and activate a form.

The message class property determines which folder to route the message to, and which form to activate to view the message. (The message class property corresponds to the MAPI property PidTagMessageClass.)

Creating a message class when customizing form regions

Form regions give you more control over how Outlook handles your customized form. Depending on the type of form region that you use when you customize a form, you must create a unique message class for your form. For more information, see How to: Create a Form Region.

Creating a message class when customizing form pages

First, some preliminaries. In the Publish Form As dialog box, when you type a name in the Display name field, note that the Form name field reflects the display name by default. You can leave the form name the same as the display name or you can change the form name. The display name becomes the caption at the top of your form. The display name is also used to construct the name under which your form is published. When you publish your form, the display name is listed in the Choose Form dialog box.

Outlook automatically constructs a message class for the form that uses the name of the form, preceded by "IPM". For example, if you want to publish a mail message form named "MyForm", type "This is my Form" in the Display name field, and type "MyForm" in the Form name field. At the bottom of the dialog box, Outlook displays the message class for your new form as: "IPM.Note.MyForm".

When you search in the Choose Form dialog box, locate "This is my Form" displayed in the list. If you select it, the Display name field at the bottom of the dialog box displays, "This is my Form" and the Form name field displays, "MyForm".

Outlook automatically generates a message class from the form name and assigns it to the form. Then, when a form with that message class is selected, Outlook loads and displays an instance of that form. For example, Outlook uses the message class, "IPM.Note.MyForm" to locate the form with the display name, "This is my Form".


Item Types and Message Classes

 Copy code hover
[image]

Item Types and Message Classes
Send feedback

The message class for an item is defined by its MessageClass property, and is used to identify the form that should be used to display the item. The following table lists the message classes and their corresponding forms.

Message class ID | Message class is used to identify a form for:
IPM.Activity | Journal entries
IPM.Appointment | Appointments
IPM.Contact | Contacts
IPM.DistList | Distribution lists
IPM.Document | Documents
IPM.OLE.Class | Exception item of a recurrence series
IPM | Items for which the specified form cannot be found
IPM.Note | E-mail messages
IPM.Note.IMC.Notification | Reports from the Internet Mail Connect (the Exchange Server gateway to the Internet)
IPM.Note.Rules.Oof.Template.Microsoft | Out-of-office templates
IPM.Post | Posting notes in a folder
IPM.StickyNote | Creating notes
IPM.Recall.Report | Message recall reports
IPM.Outlook.Recall | Recalling sent messages from recipient Inboxes
IPM.Remote | Remote Mail message headers
IPM.Note.Rules.ReplyTemplate.Microsoft | Editing rule reply templates
IPM.Report | Reporting item status
IPM.Resend | Resending a failed message
IPM.Schedule.Meeting.Canceled | Meeting cancellations
IPM.Schedule.Meeting.Request | Meeting requests
IPM.Schedule.Meeting.Resp.Neg | Responses to decline meeting requests
IPM.Schedule.Meeting.Resp.Pos | Responses to accept meeting requests
IPM.Schedule.Meeting.Resp.Tent | Responses to tentatively accept meeting requests
IPM.Note.Secure | Encrypted notes to other people
IPM.Note.Secure.Sign | Digitally signed notes to other people
IPM.Task | Tasks
IPM.TaskRequest.Accept | Responses to accept task requests
IPM.TaskRequest.Decline | Responses to desline task requests
IPM.TaskRequest | Task requests
IPM.TaskRequest.Update | Updates to requested tasks


Changing the Form Used by Existing Items in a Folder

 Copy code hover
[image]

Changing the Form Used by Existing Items in a Folder
Send feedback

In some cases you may need to change the form associated with items that are already in a folder. This is often necessary after importing items, or if you create a custom form after you have already created items based on a standard Outlook form.

The Message Class field cannot be directly changed using the Outlook user interface, but you can use VBScript, Visual Basic, or Visual Basic for Applications to change the Message Class field.

The following Automation code can be used as a basis for developing your own solution. This code assumes that the name of the new form is MyForm. It will change all contacts in your default contacts folder so that they will use MyForm.

Copy code Copy code
Sub ChangeMessageClass()
Set olNS = Application.GetNameSpace("MAPI")
Set ContactsFolder = _
 olNS.GetDefaultFolder(olFolderContacts)
Set ContactItems = ContactsFolder.Items

For Each Itm in ContactItems
 If Itm.MessageClass <> "IPM.Contact.MyForm" Then
 Itm.MessageClass = "IPM.Contact.MyForm"
 Itm.Save
 End If
Next
End Sub
Note Note

If you want to use a folder other than a default folder, use the Folders collection object to refer to any folder that is available in your Folder List.


Globally Change a Default Form

 Copy code hover
[image]

Globally Change a Default Form
Send feedback

You can change the default form in Microsoft Outlook by making changes to the Microsoft Windows registry. The registry settings specify which forms are substituted for the default Outlook forms. For example, if you create a custom form called "Default," that custom form has a message class of IPM.Note.Default, instead of the standard Outlook e-mail message class of IPM.Note. You can add certain registry keys to indicate that Outlook should substitute the IPM.Note.Default form for the standard IPM.Note form.

Caution note Caution

Custom forms may have certain limitations. Before you change the detault form in Outlook to a custom form, be aware of possible implications especially if the form will be deployed to many users. See Microsoft Knowledge Base article 241235 for further information.

The Forms Administrator utility does not create the registry keys in the correct location for Microsoft Office Outlook 2003 or later. However, you can use the Forms Administrator utility to create a Windows registry file and make the necessary changes. To use a Windows registry file to change the default form in Outlook 2003 or later:

  1. Download the Outlook 2000 Forms Administrator utility.

  2. Run the Forms Administrator utility, and then change the settings as you would for Outlook 2000 or Outlook 2002.

  3. To save the registry settings on your computer, click Save. This also makes the Export Saved Settings button available.

  4. Click Export Saved Settings to save a Windows registry (.reg) file.

  5. Open the .reg file in a text editor, such as Notepad.

  6. The registry key paths reference 9.0, which is the location for Outlook 2000 registry settings. Change all of the references of 9.0 to 11.0, 12.0, or 14.0, depending on your current version of Outlook.

  7. Save the .reg file.

  8. Run the .reg file on each computer where you want to change the default form, so that the keys are added to the Windows registry on that computer.

Note Note

If you used the Forms Administrator utility to change the default forms in Outlook 2000 or Outlook 2002, and you then upgrade to Outlook 2003 or later, Microsoft Office or Outlook Setup migrates the registry keys to the correct location so that Outlook continues to use the substituted forms.


Appointment Forms Overview

 Copy code hover
[image]

Appointment Forms Overview
Send feedback

You cannot customize the default pages of an appointment form by using Microsoft Outlook form pages customizations. However, you can customize the first page of an appointment form by adding an adjoining form region. You can also use form regions to replace existing form pages. For more information, see Form Regions.

  • You can hide the default pages that cannot be customized. However, because those pages provide much of the Outlook appointment scheduling, it is recommended that instead of hiding them, you create new pages with additional functionality. You can also use form regions to customize the default pages by using the page control.

  • Meeting request forms are not designed to be customized. Instead, customize an appointment form. The custom form is used when the appointment is converted to a meeting.


Contact Forms Overview

 Copy code hover
[image]

Contact Forms Overview
Send feedback

Although you can hide any of the default pages and create new pages on a Contact Form, the General page is the only page that you can modify. To customize the page, add an adjoining form region or use form regions to replace existing form pages. For more information, see Form Regions.

Note Note

On the General page, you cannot modify the Address, Phone, and E-mail "selector" lists that contain the names of standard Outlook fields. In addition, the FileAs list offers a limited number of choices that are based on the information that you provide, and those choices cannot be modified. To create a FileAs list with more options, use a form region.


Distribution List Forms Overview

 Copy code hover
[image]

Distribution List Forms Overview
Send feedback

You cannot customize the default pages of a distribution list form. Because the default pages provide much of the Microsoft Outlook distribution list functionality, do not hide them; instead, add additional functionality to a new page on the form.

You can customize the first page of a form by adding an adjoining form region or by using form regions to replace existing form pages. For more information, see Form Regions.


Journal Forms Overview

 Copy code hover
[image]

Journal Forms Overview
Send feedback

You cannot modify the default page of the journal form in Microsoft Outlook by using form pages customizations, but you can hide this page and create new pages on the form.

You can customize the first page of a form by adding an adjoining form region. You can also use form regions to replace existing form pages. For more information, see Form Regions.

Note Note

You cannot customize the list of Entry Type entries .


Mail Forms Overview

 Copy code hover
[image]

Mail Forms Overview
Send feedback

You can customize all pages of an e-mail form in Microsoft Outlook by using form pages.

You can also use form regions to remove and add pages for customization.

Like post forms, mail forms have separate Compose and Read pages. When a user opens a new e-mail message, the form is displayed in Compose mode, and pages are displayed so that the user can fill out the form to be sent. When the recipient opens the item, the form is displayed in Read mode, and a different set of pages and controls can be used to display the data in the fields. When designing an e-mail message form, you can choose to disable the separate Read and Compose pages so that the form is identical at all times. If you use separate pages, you can often copy and paste the controls from the one set of pages to the other.

If you are customizing a mail form for use in an organization that is using Microsoft Exchange Server, the form should be published in the Organizational Forms Library.

Note Note

  • E-mail forms only work within organizations.

  • Using the Send form definition with item property is not recommended nor needed. Publishing the form to the Organizational Forms Library makes it available. This also uses less network bandwidth and makes updating the form much easier because each client is using the shared form that is published on the server.

When you design a mail form, it is important to consider which type of message format the form should be in. The choices are Microsoft Rich Text, HTML, and plain text. You should give careful consideration to what versions of Outlook that potential recipients will be using.

Note Note

Some of the properties and objects related to mail formats might behave differently depending on whether Outlook 98, Outlook 2000, or Outlook 2003 is running in Corporate Workgroup mode or Internet Mail Only mode. Outlook 2002, Outlook 2007 and later do not distinguish between the Corporate Workgroup mode and Internet Mail Only mode.

For more information, see the following topics:

  • Form Regions

  • Making Separate Compose and Read Pages


Post Forms Overview

 Copy code hover
[image]

Post Forms Overview
Send feedback

Similar to mail forms, all post form pages are customizable, and have separate Compose and Read pages that you can modify. (You can also use form regions to remove and add pages for customization.)

A folder that contains posts is usually grouped by the Conversation field to keep related topics together. The Conversation field, also known as the ConversationTopic property in the Microsoft Outlook object model, is set based on the Subject field of a new post in the folder. All replies to this item inherit the Conversation field from the parent item. However, if the user changes the Subject field, the Conversation field is set to the new subject, which creates a new conversation.

For more information, see the following topics:

  • Form Regions

  • How to: Make Separate Compose and Read Versions for a Form


Task Forms Overview

 Copy code hover
[image]

Task Forms Overview
Send feedback

You cannot customize the default pages of a task form by using Microsoft Outlook form pages. However, you can hide these pages and create new pages on the form.

By using form regions, you can customize the default pages of a form by adding an adjoining form region. For more information, see form regions.

When tasks are used in a personal folder, you can assign tasks to other people. However, when task items are placed in a Microsoft Exchange public folder, they cannot be assigned. Instead, the Owner field can be modified to reflect who currently owns the task. It is recommended that you create a custom view so that the tasks are grouped by their owner.


Understanding the Forms Cache

 Copy code hover
[image]

Understanding the Forms Cache
Send feedback

The forms cache is a folder that is located on a computer's hard disk, and stores a local copy of a standard Microsoft Outlook form. The forms cache does not cache form regions because these form components are already stored on the computer's hard disk.

The forms cache improves the load time of a form because commonly used forms are loaded from the hard disk instead of downloaded from the server. When a form is activated for the first time, the form definition file is copied from its forms library to the Forms folder. The forms cache keeps a temporary copy of the form definition in a subfolder. This subfolder's name roughly matches the name of the form.

The form table, Frmcache.dat, also located in the Forms folder, is used to locate a form and to prevent multiple instances of the same form from being loaded in the cache. When a form is activated, Outlook checks to see if a form with the same message class is already in the cache. If not, it copies the form definition to the cache. In addition, if a change has been made to a form, Outlook copies the new form definition to the cache.

Since Microsoft Office Outlook 2007, Outlook looks for forms in the following order. When it finds a match, Outlook opens the form and does not search further.

  1. Forms cached in memory. If you have another item open that uses the same form, Outlook already has that form in memory and uses that copy instead of reloading the form.

  2. Forms already cached in the form cache on the local disk drive.

  3. Forms published in the folder that is currently selected.

  4. Forms in the Personal Forms Library.

  5. Forms in the Organizational Forms Library.

  6. Standard Outlook forms, such as Note, Post, and Contact, in the Application Forms Library.

Note Note

Before it looks for a custom form, Outlook determines whether the message class of any form region matches the message class of the item being loaded. If there is a match, Outlook loads the form region. By default, Outlook also loads any form region that has a message class derived from the message class of the item, unless the exactMessageClass element of the form region is set to True. After loading the appropriate form regions, Outlook proceeds to look for forms in the order specified above. However, if any of the loaded form regions is a replacement or replace-all form region that has the loadLegacyForm element set to False, Outlook will not continue to look for and load any form that contains custom form pages. For more information about the exactMessageClass and loadLegacyForm elements, see the Outlook 2010 XML Schema Reference in the MSDN Library.

Because Outlook caches forms, avoid having more than one form with the same name or publishing the same form to more than one forms library. Forms that are used in a folder-based solution should be published only in the folder. If you are developing a solution based on mail message forms, you can temporarily publish the forms in your Personal Forms Library. After you finalize a form, publish it to the Organizational Forms Library on the Microsoft Exchange Server. Make a backup copy of the form, and then delete it from your Personal Forms Library. If you need to publish a form in more than one location, make sure that you keep all forms libraries up-to-date with the current version of the form.

Note Note

  • It is not possible to disable the forms cache. If you set the size of the form cache to 0, Outlook cannot open any custom forms.

  • If you are using an earlier version of Outlook, you can find more about forms cache in Description of Outlook 2002 forms cache and How to use the Outlook 2003 forms cache and to troubleshoot forms cache.


Fields and Controls

 Copy code hover
[image]

Fields and Controls
Send feedback

In this section

  • Standard Fields Overview

  • Outlook Fields and Equivalent Properties

  • Custom Fields and Data Types Overview

  • Examples of Standard Formats for Data Types

  • Examples of Formula and Combination Fields

  • How to: Change the Value of a Field

  • Using the Field Chooser

  • Validating User Input to a Field

  • Difference between a Field and a Column

  • Controls in a Custom Form

  • Control Toolbox Overview

  • ToolTips and Control Tips Overview

  • Adding Custom Controls to the Control Toolbox

  • Active Controls and Selected Controls (Outlook)

  • Control Groups Overview

  • Using Fields with Controls

  • Binding a Control to a Field

  • Troubleshooting Custom Fields

  • Outlook Controls


Standard Fields Overview

 Copy code hover
[image]

Standard Fields Overview
Send feedback

Microsoft Outlook provides standard fields for each standard item. Some fields are available in individual items. You can add and remove all fields from a table or card view type.

The value for fields with the Yes/No data type is saved as -1 or 0. The value for fields with the Duration data type is saved as minutes.

What do you want more information about?

Standard fields in an appointment or meeting request

Field | Edit in view | Data type and meaning
All Day Event | Yes | Yes/No. If set to Yes, the Duration field is set to 24 hours (1440 minutes).
Attachment | No | Yes/No.
Billing Information | Yes | Text.
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Contacts | No | Text. Names of contacts linked to this item. Multiple names are separated by commas.
Conversation | No | Text. Value of the Subject field in the original message in a conversation.
Created | No | Date/Time. Date and time the Calendar item is created.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the Calendar item.
Duration | No | Duration. 24 hours (1440 minutes) if the All Day Event field is set to Yes. Otherwise, the difference between the values of the End and Start fields. Saved as minutes.
End | Yes | Date/Time. End date and time of a Calendar item.
Importance | Yes | The following settings apply: 0 Low importance 1 Normal importance 2 High importance
Icon | Yes | Internal data type.
In Folder | No | Text. Name of the folder that contains the Calendar item.
Location | Yes | Text. Location of a meeting or appointment.
Meeting Status | No | The following settings apply: 0 None 1 Meeting organizer 2 Tentatively accepted 3 Accepted 4 Declined 5 Not yet accepted
Message Class | No | Specifies the message class for the type of item.
Mileage | Yes | Text.
Modified | No | Date/Time. Last time the Calendar item was modified.
NetMeeting AutoStart | Yes | Yes/No. Specifies whether an online meeting starts immediately when the reminder appears.
NetMeeting Office Document Path | Yes | Text. Specifies the path of the Microsoft Office document used for online-meeting collaboration.
NetMeeting Organizer E-mail | Yes | Text. E-mail address of the online-meeting organizer.
NetMeeting Server | Yes | Text. Name of the NetMeeting server for the online meeting.
NetMeeting Type | No | The following settings apply: 0 NetMeeting 1 NetShow
NetMeeting URL | Yes | Text. The URL of the online meeting.
Notes | No | Text. Value of the text box of the appointment.
Online Meeting | Yes | Yes/No.
Online Meeting Type | Yes | The following settings apply: 0 NetMeeting 1 NetShow
Optional Attendees | No | Text. Names of optional attendees for a meeting or appointment. Multiple names are separated by semicolons.
Organizer | No | Text. Name of the organizer of a meeting or appointment.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the Calendar item is created in.
Read | No | Yes/No. Specifies whether the Calendar item has been marked as read.
Recurrence | No | The following settings apply: 0 None 1 Daily 2 Weekly 3 Monthly 4 Yearly
Recurrence Pattern | No | Text. Combination of the values of the Recurrence, Start, and End fields.
Recurrence Range End | No | Date/Time. Last date and time of a recurring Calendar item.
Recurrence Range Start | No | Date/Time. First date and time of a recurring Calendar item.
Recurring | No | Yes/No. Specifies whether the Calendar item recurs.
Remind Beforehand | Yes | Number. Minutes before the reminder runs prior to a meeting or appointment.
Reminder | Yes | Yes/No. If the start time for the meeting or appointment has already passed, the Reminder field cannot be set.
Reminder Override Default | Yes | Yes/No. If set to Yes, the Remind Beforehand, Reminder Sound, and Reminder Sound File fields are used to control the reminder for the item. If set to No, the reminders options on the Advanced tab of the Outlook Options dialog are used. (To open the Outlook Options dialog box, click the File tab and then click Options.)
Reminder Sound | Yes | Yes/No. Specifies whether to play the sound file as a reminder.
Reminder Sound File | Yes | Text. Path of the sound file to be played as a reminder.
Required Attendees | No | Text. Names of required attendees for a meeting or appointment. Multiple names are separated by semicolons.
Resources | No | Text. Names of resources for a meeting or appointment. Multiple names are separated by semicolons.
Response Requested | Yes | Yes/No. In a meeting request, specifies whether the recipient has been asked to respond.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Show Time As | Yes | The following settings apply: 0 Free 1 Tentative 2 Busy 3 Out of Office
Size | No | Number. Number of bytes used by the Calendar item.
Start | Yes | Date/Time. Start time of a Calendar item.
Subject | Yes | Text.

Standard fields in a contact

Field | Edit in view | Data type and meaning
Account | Yes | Text.
Address Selected | Yes | Displays the address text that was entered into the Address field based on the value of the Address Selector field.
Address Selector | Yes | The following settings apply: Home Business Other
Anniversary | Yes | Date/Time. When the Anniversary field has a value, a Calendar item is attached to the contact, and the Attachment field is set to Yes.
Assistant's Name | Yes | Text.
Assistant's Phone | Yes | Text.
Attachment | No | Yes/No. Set to Yes when the Anniversary or Birthday field is a non-empty field.
Billing Information | Yes | Text.
Birthday | Yes | Date/Time. When the Birthday field has a value, a Calendar item is attached to the contact, and the Attachment field is set to Yes.
Business Address | Yes (Card view only) | Text.
Business Address City | Yes | Text.
Business Address Country | Yes | Text.
Business Address PO Box | Yes | Text.
Business Address Postal Code | Yes | Text.
Business Address State | Yes | Text.
Business Address Street | Yes (Card view only) | Text.
Business Fax | Yes | Text.
Business Home Page | Yes | Text.
Business Phone | Yes | Text.
Business Phone 2 | Yes | Text.
Callback | Yes | Text.
Car Phone | Yes | Text.
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Children | Yes | Text.
City | Yes | Text.
Company | Yes | Text.
Company Main Phone | Yes | Text.
Computer Network Name | Yes | Text.
Contacts | No | Text. Names of contacts linked to this item. Multiple names are separated by commas.
Country/Region | Yes | Text.
Created | No | Date/Time. The date and time the contact is created.
Customer ID | Yes | Text.
Department | Yes | Text.
E-mail | No | Text.
E-mail 2 | No | Text.
E-mail 3 | No | Text.
E-mail Selected | Yes | Displays the e-mail address that was entered based on the value of the E-mail Selector field.
E-mail Selector | Yes | The following settings apply:0 E-mail 1 E-mail 2 2 E-mail 3
E-mail Display As | Yes | Text. Alternate text that represents the e-mail address stored in the E-mail field. This text displays on the To line when addressing a message or appointment.
E-mail2 Display As | Yes | Text. Alternate text that represents the e-mail address stored in the E-mail 2 field. This text displays on the To line when addressing a message or appointment.
E-mail3 Display As | Yes | Text. Alternate text that represents the e-mail address stored in the E-mail 3 field. This text displays on the To line when addressing a message or appointment.
File As | No | Text. Value of the Full Name field, unless modified by the user.
First Name | Yes | Text.
Follow Up Flag | Yes | Text.
FTP Site | Yes | Text. FTP site name for the contact.
Full Name | Yes | Text. Value of the Title, First, Middle, Last, and Suffix fields of the item, separated by spaces. Any changes made to the Full Name field are reflected in its component fields.
Gender | Yes | The following settings apply: 0 Unspecified 1 Female 2 Male
Government ID Number | Yes | Text.
Hobbies | Yes | Text.
Home Address | Yes (Card view only) | Text.
Home Address City | Yes | Text.
Home Address Country | Yes | Text.
Home Address PO Box | Yes | Text.
Home Address Postal Code | Yes | Text.
Home Address State | Yes | Text.
Home Address Street | Yes (Card view only) | Text.
Home Fax | Yes | Text.
Home Phone | Yes | Text.
Home Phone 2 | Yes | Text.
Icon | Yes | Internal Data Type.
IM Address | Yes | Instant Messaging address. (Instant Messaging is a feature of the Microsoft MSN Messenger Service and Microsoft Exchange Instant Messaging Service.)
In Folder | Yes | Text. Name of the folder that contains the contact.
Initials | Yes | Text.
Internet Free-Busy Address | Yes | Text. Refers to the reading and publishing of a calendar user's free/busy map of events. The map is retrieved when a user plans a meeting.
ISDN | Yes | Text. Phone number for ISDN connection.
Job Title | Yes | Text.
Journal | Yes | Yes/No. Specifies whether activities are automatically recorded in the Journal for the contact.
Language | Yes | Text.
Last Name | Yes | Text.
Location | Yes | Text.
Mailing Address | Yes (Card view only) | Text.
Mailing Address Indicator | Yes | Yes/No. Indicates whether the address specified by the Address Selector field is the mailing address.
Manager's Name | Yes | Text.
Message Class |  | Text. Specifies the message class for the type of item.
Middle Name | Yes | Text.
Mileage | Yes | Text.
Mobile Phone | Yes | Text.
Modified | No | Date/Time. Last date and time the contact was modified.
Nickname | Yes | Text.
Notes | No | Text. Value of the text box of the contact.
Office Location | Yes | Text.
Organizational ID Number | Yes | Text.
Other Address | Yes (Card view only) | Text.
Other Address City | Yes | Text.
Other Address Country | Yes | Text.
Other Address PO Box | Yes | Text.
Other Address Postal Code | Yes | Text.
Other Address State | Yes | Text.
Other Address Street | Yes (Card view only) | Text.
Other Fax | Yes | Text.
Other Phone | Yes | Text.
Outlook Internal Version | No | For administrator use only
Outlook Version | No | Text. Version of Outlook that the contact is created in.
Pager | Yes | Text.
Personal Home Page | Yes | Text.
Phone 1 Selected (through Phone 8 Selected) |  | Displays the phone number that was selected in the corresponding Phone Selector field.
Phone 1 Selector (through Phone 8 Selector) |  | The following settings apply: Business, Home, Business Fax, Mobile, Radio, Car, Other, and ISDN
PO Box | Yes | Text.
Primary Phone | Yes | Text.
Private | Yes | Yes/No. Indicates whether a specific contact is visible to others who have access to the Contacts folder.
Profession | Yes | Text.
Radio Phone | Yes | Text.
Read | No | Yes/No. Specifies whether the contact has been marked as read.
Referred By | Yes | Text.
Reminder | Yes | Yes/No.
Reminder Time | Yes | Date/Time. Date and time that a reminder is run for a contact.
Reminder Topic | Yes | Text. Caption displayed with reminder flag.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Size | No | Number. Number of bytes used by the contact.
Send Plain Text Only | Yes | Text.
Spouse | Yes | Text.
State | Yes | Text.
Street Address | Yes (Card view only) | Text.
Subject | Yes | Text. Value of the Full Name field. If the Full Name field is empty, the value of the File As field is used.
Suffix | Yes | Text. Name suffix, such as Jr. or Ph.D.
Telex | Yes | Text.
Title | Yes | Text. Name title, such as Mr., Ms., or Mrs.
TTY/TDD Phone | Yes | Text. Phone number for TTY/TDD connection.
User Field 1 - 4 | Yes | Text. User-defined fields provided for compatibility with other programs.
Web Page | Yes | Text.
ZIP/Postal Code | Yes | Text.

Standard fields in a distribution list

Field | Edit in view | Data type and meaning
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Distribution List Name | Yes | Text. The name of the distribution list.
Icon | Yes | Internal data type.
In Folder | No | Text. Name of the folder that contains the distribution list item.
Message Class | No | Specifies the message class for the type of item.
Modified | No | Date/Time. Last time the distribution list item was modified.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the distribution list item is created in.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Size | No | Number. Number of bytes used by the distribution list item.

Standard fields in a Journal entry

Field | Edit in view | Data type and meaning
Attachment | No | Yes/No.
Billing Information | Yes | Text.
Categories | Yes | Text. User-defined field used to group and find related items. Multiple categories are separated by commas.
Company | Yes | Text.
Contact | No | Text. Name of the contact the Journal entry is recorded for.
Contacts | No | Text. Names of contacts linked to this item. Multiple names are separated by commas.
Created | No | Date/Time. Date and time the Journal entry is created.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the Journal entry.
Duration | No | Duration. Saved as minutes.
End | Yes | Date/Time. End date and time set for the Journal entry.
Entry Type | No | Text. Type of entry made for the Journal entry.
Icon | Yes | Internal data type.
In Folder | No | Text. Name of the folder that contains the Journal entry.
Message Class | No | Text. Specifies the message class for the type of item.
Mileage | Yes | Text.
Modified | No | Date/Time. Last time the Journal entry was modified.
Notes | No | Text. First 255 characters in the body of the Journal entry.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the Journal entry is created in.
Read | No | Yes/No. Specifies whether the Journal entry has been marked as read.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Size | No | Number. Number of bytes used by the Journal entry.
Start | Yes | Date/Time. Start time for the Journal entry.
Subject | Yes | Text.

Standard fields in an e-mail message

Field | Edit in view | Data type and meaning
Attachment | No | Yes/No.
BCC | No | Text. Names in the Bcc box of a message.
Billing Information | Yes | Text.
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
CC | No | Text. Names in the Cc box of a message.
Contacts | No | Text. Names of contacts linked to this item. Multiple names are separated by commas.
Conversation | No | Text. Value of the Subject field in the original message in a conversation.
Created | No | Date/Time. Date and time the message is created.
Defer Until | Yes | Date/Time. Date and time a message is to be delivered. The server delays delivery of the message.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the message.
Due By | Yes | Date/Time. Date and time the action associated with a Message Flag is set to be completed by. When a value is entered for Due By, the Flag Status field is set to 2.
Expires | Yes | Date/Time. Date and time a message expires.
Flag Status | Yes | The following settings apply: 0 Normal 1 Completed 2 Flagged
Follow Up Flag | Yes | Text.
From | No | Text. Names in the From box in a message.
Have Replies Sent To | No | Text. Names in the Have replies sent to box in a message.
Header status | No | Indicates the download state of the message.
Icon | Yes | Internal data type.
Importance | Yes | The following settings apply: 0 Low importance 1 Normal importance 2 High importance
In Folder | No | Text. Name of the folder that contains the message.
Junk E-mail type | Yes | Internal data type.
Message | No | Text. Value of the text box in a message.
Message Class | No | Specifies the message class for the type of item.
Message Flag | Yes | Text. Action associated with a Message Flag. When a value is entered for Message Flag, the Flag Status field is set to 2.
Mileage | Yes | Text.
Modified | No | Date/Time. Last date and time the message was modified.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the message is created in.
Read | No | True/False. Specifies whether the message has been marked as read.
Receipt Requested | No | Yes/No. Indicates whether message was sent with a read or delivery receipt requested.
Received | No | Date/Time. Date and time the message is received.
Relevance | Yes | Number. User-defined significance.
Remote Status | No | Specifies the status of Remote Mail header. The following settings apply: 0 None 1 Marked 2 Marked for download 3 Marked for copy
Retrieval Time | No | Duration. Specifies the time it takes to download the message with Remote Mail. Saved as minutes.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Sent | No | Date/Time. Date and time the message is sent.
Size | No | Number. Number of bytes used by the message.
Subject | Yes | Text.
To | No | Text. Names in the To box in a message.
Tracking Status | No | Tracking status of a message. The following settings apply: 1 Delivered 5 Read 6 Not Read

Standard fields in a note

Field | Edit in view | Data type and meaning
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Color | Yes | The following settings apply: 0 Blue 1 Green 2 Pink 3 Yellow 4 White
Content | No | Text. Value of the text box of a note.
Created | No | Date/Time. Date and time the note is created.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the note.
Icon | Yes | Internal data type.
In Folder | No | Text. Name of the folder that contains the note.
Message Class | No | Text. Specifies the message class for the type of item.
Modified | No | Date/Time. Last date and time the note was modified.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the note is created in.
Read | No | Yes/No. Specifies whether the note has been marked as read.
Size | No | Number. Number of bytes used by the note.
Subject | No | Text.

Standard fields in a task

Field | Edit in view | Data type and meaning
% Complete | Yes | Percent.
Actual Work | Yes | Duration. Time spent on a task. Saved as minutes.
Assigned | No | The following settings apply: 0 Not assigned 1 Assigned by me 2 Assigned to me
Attachment | No | Yes/No.
Billing Information | Yes | Text.
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Company | Yes | Text.
Complete | Yes | Yes/No. Specifies whether the task is marked as completed.
Contacts | No | Text. Names of contacts linked to this item. Multiple names are separated by commas.
Conversation | No | Text. Value of the Subject field of the original task.
Created | No | Date/Time. Date and time the task is created.
Date Completed | Yes for non-recurring tasks. No for recurring tasks. | Date/Time. Date and time the task is completed. If the Date Completed field has a value, the Complete field is set to Yes, and the % Complete field is set to 100.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the task.
Due Date | Yes | Date/Time.
Icon | Yes | Internal data type.
In Folder | No | Text. Name of the folder that contains the task.
Message Class | No | Text. Specifies the message class of the type of item.
Mileage | Yes | Text.
Modified | No | Date/Time. Last date and time the task was modified.
Notes | Yes | Text. Value of the text box of the task.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the task is created in.
Owner | Yes, if task is in a public folder; otherwise, No. | Text. Owner of the task.
Priority | Yes | The following settings apply: 0 Low priority 1 Normal priority 2 High priority
Read | No | Yes/No. Specifies whether the task has been marked as read.
Recurring | No | Yes/No. Specifies whether the task recurs.
Reminder | No | Yes/No. Specifies whether a reminder has been set for the task.
Reminder Override Default | Yes | Yes/No.
Reminder Sound | Yes | Yes/No. Specifies whether to play the sound file as a reminder.
Reminder Sound File | Yes | Text. Path of the sound file to be played as a reminder.
Reminder Time | Yes | Date/Time. Date and time that a reminder is run for a task.
Request Status | No | The following settings apply: 0 No setting 1 Not responded 2 Accepted 3 Declined
Requested By | No | Text. In a task request, the person's name who assigned the task.
Role | Yes | Text.
Schedule+ Priority | Yes | Text.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Size | No | Number. Number of bytes used by the task.
Start Date | Yes | Date/Time. Start date and time for the task.
Status | Yes | The following settings apply: 0 Not Started 1 In Progress 2 Completed 3 Waiting on someone else 4 Deferred
Subject | Yes | Text.
Team Task | Yes | Yes/No.
To | No | The owner of an assigned task.
Total Work | Yes | Duration. Time the task is expected to take. Saved as minutes.

Standard fields in a post

Field | Edit in view | Data type and meaning
Attachment | No | Yes/No.
Billing Information | Yes | Text.
Categories | Yes | Text. Field used to group and find related items. Multiple categories are separated by commas.
Conversation | No | Text. Value of the Subject field in the original item in a conversation.
Created | No | Date/Time. Date and time the message is created.
Defer Until | Yes | Date/Time. Date and time a message is to be delivered. The server delays delivery of the message.
Do Not AutoArchive | Yes | Yes/No. Specifies whether to archive the message.
Expires | Yes | Date/Time. Date and time a message expires.
From | No | Text. Names in the From box in a message.
Header status | No | Indicates the download state of the message.
Icon | Yes | Internal data type.
Importance | Yes | The following settings apply: 0 Low importance 1 Normal importance 2 High importance
In Folder | No | Text. Name of the folder that contains the message.
Message | No | Text. Value of the text box in a message.
Message Class | No | Specifies the message class for the type of item.
Mileage | Yes | Text.
Modified | No | Date/Time. Last date and time the message was modified.
Outlook Internal Version | No | For administrator use only.
Outlook Version | No | Text. Version of Outlook that the message is created in.
Read | No | True/False. Specifies whether the message has been marked as read.
Received | No | Date/Time. Date and time the message is received.
Remote Status | No | Specifies the status of Remote Mail header. The following settings apply: 0 None 1 Marked 2 Marked for download 3 Marked for copy
Retrieval Time | No | Duration. Specifies the time it takes to download the message with Remote Mail. Saved as minutes.
Sensitivity | No | The following settings apply: 0 Normal 1 Personal 2 Private 3 Confidential
Sent | No | Date/Time. Date and time the message is sent.
Size | No | Number. Number of bytes used by the message.
Subject | Yes | Text.


Outlook Fields and Equivalent Properties

 Copy code hover
[image]

Outlook Fields and Equivalent Properties
Send feedback
Name of field in Microsoft Outlook Field Chooser | Name of equivalent Outlook object model property
% Complete | PercentComplete
Account | Account
Actual Work | ActualWork
Address Selected | N/A
Address Selector | N/A
All Day Event | AllDayEvent
Anniversary | Anniversary
Assigned | DelegationState
Assistant's Name | AssistantName
Assistant's Phone | AssistantTelephoneNumber
Attachment | Attachments
Bcc | BCC
Billing Information | BillingInformation
Birthday | Birthday
Business Address | BusinessAddress
Business Address City | BusinessAddressCity
Business Address Country | BusinessAddressCountry
Business Address PO Box | BusinessAddressPostOfficeBox
Business Address Postal Code | BusinessAddressPostalCode
Business Address State | BusinessAddressState
Business Address Street | BusinessAddressStreet
Business Fax | BusinessFaxNumber
Business Home Page | BusinessHomePage
Business Phone | BusinessTelephoneNumber
Business Phone 2 | Business2TelephoneNumber
Callback | CallbackTelephoneNumber
Car Phone | CarTelephoneNumber
Categories | Categories
Cc | CC
Changed By | N/A
Children | Children
City | HomeAddressCity
Color | Color
Company | Companies
Company | CompanyName
Company Main Phone | CompanyMainTelephoneNumber
Complete | Complete
Computer Network Name | ComputerNetworkName
Contact | FormDescription .ContactName
Contacts | Links
Content | Body
Conversation | ConversationTopic
Country | HomeAddressCountry
Created | CreationTime
Customer ID | CustomerID
Date Completed | DateCompleted
Defer until | DeferredDeliveryTime
Department | Department
Distribution List Name | DLName
Do Not AutoArchive | NoAging
Download State | N/A
Due By | FlagDueBy
Due Date | DueDate
Duration | Duration
E-mail | Email1Address
E-mail 2 | Email2Address
E-mail 3 | Email3Address
E-mail Selected | N/A
E-mail Selector | N/A
End | End
Entry Type | Type
Expires | ExpiryTime
File As | FileAs
First Name | FirstName
Flag Status | FlagStatus
Follow-up Flag | FlagRequest
From | SentOnBehalfOfName
FTP Site | FTPSite
Full Name | FullName
Gender | Gender
Government ID Number | GovernmentIDNumber
Have Replies Sent To | ReplyRecipientNames
Hobbies | Hobby
Home Address | HomeAddress
Home Address City | HomeAddressCity
Home Address Country | HomeAddressCountry
Home Address PO Box | HomeAddressPostOfficeBox
Home Address Postal Code | HomeAddressPostalCode
Home Address State | HomeAddressState
Home Address Street | HomeAddressStreet
Home Fax | HomeFaxNumber
Home Phone | HomeTelephoneNumber
Home Phone 2 | Home2TelephoneNumber
Icon | FormDescription .Icon
Importance | Importance
In Folder | Parent
Initials | Initials
Internet Free Busy Address | InternetFreeBusyAddress
ISDN | ISDNNumber
Job Title | JobTitle
Journal | Journal
Junk E-Mail Type | N/A
Language | Language
Last Name | LastName
Last Saved Time | N/A
Location | Location
Mailing Address | MailingAddress
Mailing Address Indicator | N/A
Manager's Name | ManagerName
Meeting Status | MeetingStatus
Message | Body
Message Class | MessageClass
Message Flag | FlagStatus
Middle Name | MiddleName
Mileage | Mileage
Mobile Phone | MobileTelephoneNumber
Modified | LastModificationTime
Meeting Workspace URL | MeetingWorkspaceURL
Nickname | NickName
Notes | Body
Office Location | OfficeLocation
Optional Attendees | OptionalAttendees
Organizational ID Number | OrganizationalIDNumber
Organizer | Organizer
Other Address | OtherAddress
Other Address City | OtherAddressCity
Other Address Country | OtherAddressCountry
Other Address PO Box | OtherAddressPostOfficeBox
Other Address Postal Code | OtherAddressPostalCode
Other Address State | OtherAddressState
Other Address Street | OtherAddressStreet
Other Fax | OtherFaxNumber
Other Phone | OtherTelephoneNumber
Outlook Internal Version | OutlookInternalVersion
Outlook Version | OutlookVersion
Owner | Owner
Pager | PagerNumber
Personal Home Page | PersonalHomePage
Phone n Selected | N/A
Phone n Selector | N/A
PO Box | HomeAddressPostOfficeBox
Primary Phone | PrimaryTelephoneNumber
Priority | Importance
Private | Sensitivity
Profession | Profession
Radio Phone | RadioTelephoneNumber
Read | UnRead
Received | ReceivedTime
Recurrence | RecurrencePattern .RecurrenceType
Recurrence Pattern | N/A
Recurrence Range End | RecurrencePattern .PatternEndDate
Recurrence Range Start | RecurrencePattern .PatternStartDate
Recurring | IsRecurring
Referred By | ReferredBy
Remind Beforehand | ReminderMinutesBeforeStart
Reminder | ReminderSet
Reminder Override Default | ReminderOverrideDefault
Reminder Sound | ReminderPlaySound
Reminder Sound File | ReminderSoundFile
Reminder Time | ReminderTime
Reminder Topic | N/A
Remote Status | RemoteStatus
RequestStatus | N/A
Requested By | N/A
Required Attendess | RequiredAttendees
Resources | Resources
Response Requested | ResponseRequested
Retrieval Time | N/A
Role | Role
Schedule+ Priority | SchedulePlusPriority
Send Plain Text Only | N/A
Sensitivity | Sensitivity
Sent | SentOn
Show Time As | BusyStatus
Size | Size
Spouse | Spouse
Start | Start
Start Date | StartDate
State | HomeAddressState
Status | Status
Street Address | HomeAddressStreet
Subject | Subject
Suffix | Suffix
Team Task | TeamTask
Telex | TelexNumber
Title | Title
To | To
Total Work | TotalWork
Tracking Status | TrackingStatus
TTY/TDD Phone | TTYTDDTelephoneNumber
User Field 1 | User1
User Field 2 | User2
User Field 3 | User3
User Field 4 | User4
Web Page | WebPage
ZIP/Postal Code | HomeAddressPostalCode


Custom Fields and Data Types Overview

 Copy code hover
[image]

Custom Fields and Data Types Overview
Send feedback

You can use custom fields in several ways in Microsoft Outlook, including the following:

  • You can create new data-entry fields for a view or a form so that users can add their own custom information. For example, you can create a Date/Time field named "Last Talked To" in a contact folder and then add the field to a Phone List view.

  • You can create new views by combining the standard fields in a single column. For example, you can create a column that combines the State and Country fields in an address list to save space.

  • You can create a formula field to show information in a new way. For example, you can create a field that displays "Large" when a message is more than 10,000 bytes and "Small" when a message is under the same limit.

Any field that you create is stored in the folder where you create it. To use a field in more than one folder, you must create the field in each folder.

You can create and view custom fields in table views and card views. You can create custom fields with the following data types in Outlook.

Data type | Use to represent
Combination | Combinations of values of fields and text in a column (table) or row (card). You can specify whether to show each field or show only the first non-empty field. You can also combine text with fields without the use of quotation marks.
Currency | Numeric data as currency or mathematical calculations that involve money.
Date/Time | Date and time data.
Duration | Numeric data. You can enter a duration as minutes, hours, or days. Values are saved as minutes.
Formula | Calculations based on standard and custom fields. You can use any appropriate functions and operators to complete the formula.
Integer | Non-decimal numeric data.
Keywords | When filled in, this user-defined field is used to group and find related items similar to the way the Categories field is used in Outlook. Text with multiple values to be separated by commas. Each value can be grouped individually in a view.
Number | Numeric data or mathematical calculations except those that involve money. (For money, use Currency data type.)
Percent | Numeric data as a percentage.
Text | Text or combinations of text and numbers, such as addresses. Can be up to 255 characters long.
Yes/No | Data that contains only one of two values, such as Yes/No, True/False, On/Off.

Each of the data types except Combination, Formula, and Keywords has a series of standard formats that you can use to show the values of the fields.


Examples of Standard Formats for Data Types

 Copy code hover
[image]

Examples of Standard Formats for Data Types
Send feedback

You can format fields that you create with different formats based on the data type. The following table provides a list of some of the formats that Microsoft Outlook includes.

View a complete list of standard formats available for fields

  • In Outlook, on the View menu, point to Current View, and then click Format Columns.

Note Note

If you do not find the format you want, you can create a custom format with a Formula data type and the Format function.

Data type | Standard format examples
Currency | $12,345.60 or ($12,345.60) $12,346 or ($12,346)
Date/Time | Tuesday, March 03, 2009 8:00 AM 3/03/2009 8:00 AM March 3, 2009 Tue 3/3 8:00 AM 8:00 AM
Duration | 12h 12 hours 12h (Work Time) (see the Note below) 12 hours (Work Time) (see the Note below)
Integer | 1,234
Keywords | Text
Number | All Digits: 1,234.567 or -1,234.567 Truncated: 1,235 or -1,235 Scientific: 1235E+03 or -1235E+03 Computer: 64 K or 128MB or 1 GB
Percent | 65.4321% 65.43% or -65.43% 65% or -65%
Text | Text
Yes/No | Yes or No On or Off True or False
Note Note

Values entered in a field of a Duration data type with a regular format assume a 24-hour day.


Examples of Formula and Combination Fields

 Copy code hover
[image]

Examples of Formula and Combination Fields
Send feedback
Display | Custom field | Result in custom field
Number of days since the item was received. (Formula field) | DateValue (Now())-DateValue ([Received]) & " Day(s)" | 6 Day(s)
Description of a meeting or appointment in Calendar. (Formula field) | "This meeting occurs " & [Recurrence Pattern] & " in " & [Location] | The meeting occurs every day from 12:00 P.M. to 1:30 P.M. in room 1231
Amount to be charged for a phone call recorded in the Journal at $0.75 a minute. (Formula field) | IIF ([Entry Type] = "Phone call" , Format ([Duration] * .75, "Currency"), "None") | $1.50
Description of a Message Flag. (Formula field) | IIF ( [Flag Status] = "2", [Message Flag] & " " & [Due By],"") | Follow up 3/5/2009 8:00:00 A.M.
The first phone number recorded for a contact, in order of appearance in the formula. (Combination field) | [Business Phone] [Business Phone 2] [Home Phone] [Home Phone 2] [Cell Phone] | (555) 555-1234
A description of a field combined with the field itself. (Combination field) | Task Due: [Due Date] | Task Due: 3/5/2009 8:00:00 A.M.


How to: Change the Value of a Field

 Copy code hover
[image]

How to: Change the Value of a Field
Send feedback

To change the value of an Outlook field, use the property name of the associated standard field. For example, to change the value of the Subject field, use the following code.

Copy code Copy code
Item.Subject = "New Subject"

To change the value of a custom field, use the following code to refer to a custom field.

Copy code Copy code
Item.UserProperties.Find("MyProperty").Value = "New Value"


Using the Field Chooser

 Copy code hover
[image]

Using the Field Chooser
Send feedback

Although you can add a control to a form and then bind the control to a field, it is usually more effective to use the Field Chooser. When you bind a control, you establish a link between the control and the source of data, which in this case is a field in the item. You can use the Field Chooser to add a control and bind it to a field in a single step. Also, in many cases, the built-in control that the Field Chooser provides has special features and capabilities that cannot be duplicated by binding a field to a standard control.

Microsoft Outlook displays the Field Chooser whenever you open a form in design mode. For more information, see Run in Developer Mode in Outlook.

Note Note

  • For some field types, dragging the field from the Field Chooser may not use the same control that is displayed in the built-in form. To use these controls, you must add them to the form from the Toolbox, and then bind them to the field. For example, dragging the Start field from the Field Chooser results in a basic text box on the form that is bound to the Start field. However, to get a richer date selector experience for the Start field, use the Outlook Date Picker control instead.

  • Some entries in the Field Chooser, such as Categories, display ellipses after them. These entries correspond to actions. When you drag one of these entries in the Field Chooser to a form page, Outlook creates a button that can be clicked to open the window for the action. Two exceptions to ellipses indicating actions are the Submit and Account fields. Each of these is an action and creates a button, but there are no ellipses in the field names.


Validating User Input to a Field

 Copy code hover
[image]

Validating User Input to a Field
Send feedback

You can require any field, or any control that is bound to a field, to have a value. For example, you can set the exact text, range of numbers, or any other criteria for the field. You can also show a custom message (based on a validation formula) that tells users how to fill in the field if their entries do not match the value that you want. For example, you can limit the number of characters that can be entered in a TextBox.

For more information, see:

  • How to: Require a Value for a Field or Control

  • How to: Create a Validation Formula and Message


Difference between a Field and a Column

 Copy code hover
[image]

Difference between a Field and a Column
Send feedback

A column is collection of cells aligned vertically in a table. A field is an element in which one piece of information is stored, such as the Received field. Usually, a column in a table contains the values of a single field. However, you can show several fields in a column by using a Formula or a Combination field. Fields can also be shown as rows in a card view or as controls on a form. A column is just one way to display the contents of a field.

For more information, see the following topics:

  • How to: Create a Combination Field for a Folder

  • How to: Create a Formula Field for a Folder


Controls in a Custom Form

 Copy code hover
[image]

Controls in a Custom Form
Send feedback

Form controls allow you to customize the user interface and behavior of a custom form. Because all code behind a form is called from a form event or a control event, programming the response to control events is one of the primary means to extend a form programmatically. This topic describes adding and displaying Microsoft Forms 2.0 controls and Microsoft Outlook controls in Outlook forms. For information on programming Forms 2.0 controls, see the Form Script Reference. For more information on programming Outlook controls, see the Object Model Reference.

Design Time

In the forms designer, you can add a control from the control toolbox to a form page or a form region. The control toolbox is initialized with a number of Forms 2.0 controls. You can add other ActiveX controls that have been installed on your computer to the control toolbox.

Microsoft Forms 2.0 Controls

The following Forms 2.0 controls exist in the control toolbox by default:

  • Microsoft Forms 2.0 CheckBox control

  • Microsoft Forms 2.0 ComboBox control

  • Microsoft Forms 2.0 CommandButton control

  • Microsoft Forms 2.0 Frame control

  • Microsoft Forms 2.0 Image control

  • Microsoft Forms 2.0 Label control

  • Microsoft Forms 2.0 ListBox control

  • Microsoft Forms 2.0 MultiPage control

  • Microsoft Forms 2.0 OptionButton control

  • Microsoft Forms 2.0 ScrollBar control

  • Microsoft Forms 2.0 SpinButton control

  • Microsoft Forms 2.0 TabStrip control

  • Microsoft Forms 2.0 TextBox control

  • Microsoft Forms 2.0 ToggleButton control

Microsoft Outlook Controls

The following table lists Outlook controls that are installed on your computer when you install Microsoft Office Outlook 2007 or a later version of Outlook. These controls support Microsoft Windows themes. Before you can use them in Outlook forms, you must first add them to the control toolbox.

Use these controls only in form regions and not form pages in custom forms.

Some of these controls are designed to leverage features in Outlook, for example, the Microsoft Outlook Body Control is designed to display the body of an Outlook item. All of the Outlook controls are designed for use only in Outlook add-ins.

Control | Designed for Specific Outlook Features
Microsoft Outlook Body Control | Yes
Microsoft Outlook Business Card Control | Yes
Microsoft Outlook Category Control | Yes
Microsoft Outlook Check Box Control | No
Microsoft Outlook Combo Box Control | No
Microsoft Outlook Command Button Control | No
Microsoft Outlook Contact Photo Control | Yes
Microsoft Outlook Date Control | Yes
Microsoft Outlook Frame Header Control | Yes
Microsoft Outlook InfoBar Control | Yes
Microsoft Outlook Label Control | No
Microsoft Outlook List Box Control | No
Microsoft Outlook Option Button Control | No
Microsoft Outlook Page Control | Yes
Microsoft Outlook Recipient Control | Yes
Microsoft Outlook Sender Photo Control | Yes
Microsoft Outlook Text Box Control | No
Microsoft Outlook Time Control | Yes
Microsoft Outlook Time Zone Control | Yes

Run Time

On custom form pages, Forms 2.0 controls are always displayed with a classic look without Windows theming. In a form region, any Forms 2.0 control that has a themed Outlook counterpart control assumes an appearance that is themed to Windows and in fact can be cast with the type of the counterpart. For example, if the user has dropped a Forms 2.0 TextBox control in a form region, programmatically, Outlook will replace this instance of the control by an instance of the Outlook counterpart control, and you will be able to apply a cast of Microsoft.Office.Interop.Outlook.OlkTextBox to this control and access it as an Outlook TextBox control. You should not access it as a Microsoft.Vbe.Interop.Forms.TextBox control. For more information on casting controls in an add-in, see Extending a Form Region with an Add-in. The following table lists each Forms 2.0 control and the corresponding Outlook control (if one exists).

Forms 2.0 Control | Outlook Control
Microsoft Forms 2.0 CheckBox control | Microsoft Outlook Check Box Control
Microsoft Forms 2.0 ComboBox control | Microsoft Outlook Combo Box Control
Microsoft Forms 2.0 CommandButton control | Microsoft Outlook Command Button Control
Microsoft Forms 2.0 Frame control | Microsoft Outlook Frame Header Control
Microsoft Forms 2.0 Image control | (No parity)
Microsoft Forms 2.0 Label control | Microsoft Outlook Label Control
Microsoft Forms 2.0 ListBox control | Microsoft Outlook List Box Control
Microsoft Forms 2.0 MultiPage control | (No parity)
Microsoft Forms 2.0 OptionButton control | Microsoft Outlook Option Button Control
Microsoft Forms 2.0 ScrollBar control | (No parity)
Microsoft Forms 2.0 SpinButton control | (No parity)
Microsoft Forms 2.0 TabStrip control | (No parity)
Microsoft Forms 2.0 TextBox control | Microsoft Outlook Text Box Control
Microsoft Forms 2.0 ToggleButton control | (No parity)

Because Outlook controls are installed on computers running Office Outlook 2007 or later, a form that contains these controls will not be displayed properly in any earlier version of Outlook.

Summary

The following summarizes the differences between Forms 2.0 controls and Outlook controls:

Comparison Aspect | Forms 2.0 Controls | Outlook Controls
Available in Outlook 2003 or earlier | Yes | No
Available in Office Outlook 2007 or later | Yes | Yes
Exists in control toolbox by default | Yes | No
How displayed on a form page in Office Outlook 2007 or later | Classic look without Windows theming | Do not use Outlook controls in custom form pages, but use only in form regions
How displayed in a form region in Office Outlook 2007 or later | Displayed as its themed counterpart, if one exists, and can be cast with the type of its themed counterpart; classic look if themed counterpart does not exist | Themed look
Controls displayed properly in runtime in Outlook 2003 or earlier | Yes | No
Controls displayed properly in runtime in Office Outlook 2007 or later | Yes | Yes


Control Toolbox Overview

 Copy code hover
[image]

Control Toolbox Overview
Send feedback

The Control Toolbox identifies the controls that you can add to a Frame or a page of a form.

You can customize the Control Toolbox in many ways including the following:

  • Add pages to the Control Toolbox.

  • Move controls from one page in the Control Toolbox to another.

  • Rename Control Toolbox pages.

  • Add other controls, including ActiveX controls, to the Control Toolbox.

  • Copy modified controls from the form to the Control Toolbox. For example, OK and Cancel buttons are special types of CommandButtons. If you copy OK and Cancel templates to the Control Toolbox, you can quickly add them to other forms.

Note Note

When you add a control to a form by using the Control Toolbox, the control is not bound to a field.


ToolTips and Control Tips Overview

 Copy code hover
[image]

ToolTips and Control Tips Overview
Send feedback

Both ToolTips and control tips are short, descriptive phrases that appear when the user holds the mouse pointer briefly over a control or another part of the user interface. The difference between ToolTips and control tips is that Microsoft Outlook provides ToolTips to developers at design time, and developers provide control tips to end users at run time.

You can customize ToolTips for controls and for the Control Toolbox.

A control tip is set with the ControlTipText property. For example, use ControlTipText to set the control tip text for the Page object.


Adding Custom Controls to the Control Toolbox

 Copy code hover
[image]

Adding Custom Controls to the Control Toolbox
Send feedback

You can add a modified control (based on modifications made to the advanced properties) to the Control Toolbox. You can also add other custom controls to the Control Toolbox, such as ActiveX controls that are not part of Outlook.

You can use a variety of custom controls in Outlook forms, but there are some limitations with Outlook form pages. Form pages support most ActiveX properties and methods but do not support custom event handling. The Click event is the only event for which you can write code. To access the methods of an ActiveX control, use the Visual Basic Application (VBA) Object Browser to browse ActiveX control methods.

There are no similar limitations on adding custom controls when using form regions to customize Outlook forms; form regions support the full event model for any control.

For more information, see the following topics:

  • How to: Add a Modified Control to the Control Toolbox

  • Adding Other Custom Controls to the Control Toolbox

  • Form Regions


Active Controls and Selected Controls (Outlook)

 Copy code hover
[image]

Active Controls and Selected Controls (Outlook)
Send feedback

In design mode, controls have an active state and a selected state. When a control is active, it means that you are working with the contents of the control; when a control is selected, it means that you are working with the control itself.

Most controls are automatically selected when you put them on the form. In design mode, sizing handles appear around the control border when the control is selected. If you cancel the selection, you can click the control to select it again.

When you click a selected control, you put it in the active state. In that state, you can directly edit the control Caption or Value property, depending on the control.

In both the selected and the active state, you can use DEL, CTRL+X, and CTRL+C for the Delete, Cut, and Copy commands, respectively. In the selected state, these commands are available on the shortcut menu and affect the control itself. In the active state, these commands affect whatever text is selected inside the control; if no text is selected, these commands have no effect. These commands are not available on the shortcut menu for active controls.

Note Note

For more information about design mode, see Run in Developer Mode in Outlook.


Control Groups Overview

 Copy code hover
[image]

Control Groups Overview
Send feedback

A group is a collection of two or more controls on a form that you can work with as a single unit. You can include any control on the form in a group. After controls belong to a group, you can work with the entire group, or you can select a single control.

There are many ways to work with groups and the controls in groups. After you select a group, you can do any of the following:

  • Size all controls in the group at the same time.

  • Separate controls in the group so that each is independent of the others.

  • Show the group shortcut menu for quick access to commands that affect the group.

  • Select a single control within the group without separating other controls in the group. You can then change the property settings of the selected control without affecting other controls in the group.


Using Fields with Controls

 Copy code hover
[image]

Using Fields with Controls
Send feedback

When you drag a field from the Field Chooser, the field automatically binds to the appropriate control. Unless you have a special requirement to use a standard control from the Control Toolbox, you should use the Field Chooser to provide access to fields on your forms.

When you put a control from the Control Toolbox on a form, you must bind the control to a form if you want to save a value to or from a control. In most cases, you would bind controls like the check box, combo box, date, list box, option button, and text box to fields. Other controls, such as the Image and label controls, that contain static information with which the user does not interact are generally not bound to a field.

To bind a control to a field, right-click the control, and then click Properties on the shortcut menu. Click the Value tab. Click Choose Field, and then click a field or click New to create a custom field. Outlook fields are based on MAPI properties. In this way, the values of fields are stored with the item when you save or send the item. The controls from the Control Toolbox are only the visual containers for a field on a form. You can set the appearance of the control using its properties, but you cannot save a value. Controls only exist when the specific form appears that contains the controls. Fields can be used on any form. If you change a field value in one place, this value changes everywhere the field is used.

For example, to change the value of a custom field called Fax, you use the following code:

Copy code Copy code
Item.UserProperties.Find("Fax").Value = "555-1234"

Note that since this is a field, you do not need to specify the page or the control the field is bound to. In the following code example, a control called txtFax is made invisible. When you work with a control, you must specify the page and the control name.

Copy code Copy code
Item.GetInspector.ModifiedFormPages("General").Controls("txtFax").Visible = False

You can bind a control to a field at run time by using the internal property named ItemProperty. The following example binds a TextBox to a field named Business Address.

Copy code Copy code
Item.GetInspector.SetControlItemProperty("Textbox1", "Business Address")
Note Note

If you create a control by dragging a plain text field to a form, you cannot bind the control to a field of a different type. For example, you cannot drag a Subject field to a form and then bind it to a field containing an Email type (such as the To field).


Binding a Control to a Field

 Copy code hover
[image]

Binding a Control to a Field
Send feedback

If you have created a control using the Control Toolbox and you would like the information in this control to be saved with the form, the control must be bound to a field. This means that a link will be established between the control and the source of data, in this case, a field in the item.

  1. In the Forms Designer, right-click the control you want to bind to a field and then click Properties on the shortcut menu.

  2. On the Value tab, click Choose Field, point to a field set, and then click the field to which you want to bind the control. If you would like to bind the control to a new field that you create, click New. In the New Field box, type the name of your new field in the Name: area. Click OK in the New Field box.

  3. Click OK in the Properties box.

Note Note

If you bind a CheckBox, ComboBox, ListBox, or OptionButton to a field, then the Click event does not fire. You need to use the PropertyChange or CustomPropertyChange event of the item to detect the change via code, as shown in the following example:
Copy code Copy code
Sub Item_PropertyChange(ByVal Name)
Set MyListBox = Item.GetInspector.ModifiedFormPages("Message").Controls("ListBox1")
Select Case Name
 Case "Mileage"
 Item.CC = MyListBox.Value
 Item.Subject = MyListBox.Value
 Case Else
End Select
End Sub


Troubleshooting Custom Fields

 Copy code hover
[image]

Troubleshooting Custom Fields
Send feedback

Use the following troubleshooting tips to help troubleshoot problems with custom fields.

The custom field I created is not visible.

Forms customized with form pages

  • Custom fields are stored in the folder in which you create them. Open the folder in which you created the custom field to see if it is visible. You must recreate a custom field for each folder in which you want to use it.

  • Custom fields are stored in the field set called User-defined fields in the Field Chooser and in the Show Fields dialog box. To see all the custom fields in a folder, do the following:

    1. Open the folder.

    2. On the View menu, select Current View, and then click Customize Current View.

    3. In the Customize View dialog box, click Fields.

    4. In the Select available fields from box, click User-defined fields in folder.

Forms customized with form regions

  • When using a custom field on a form region, you must create the field by using an add-in in each folder where you store items that use the form. That way, you can add the field to the view and it is searchable. If you create the field on only the form region, it will not be accessible in the view and it might not pick up the appropriate default value when you create a new item that uses the form.For more information, see Extending a Form Region with an Add-in.

When I try to sort, group, or filter a formula field or combination field, I receive an error message.

  • You cannot sort, group, or filter a formula field or a combination field in Microsoft Outlook.


Outlook Controls

 Copy code hover
[image]

Outlook Controls
Send feedback

In this section

  • Extra Members for Outlook Controls

  • ControlTipText Property (Outlook Controls)

  • Height Property (Outlook Controls)

  • Left Property (Outlook Controls)

  • Move Method (Outlook Controls)

  • Name Property (Outlook Controls)

  • SetFocus Method (Outlook Controls)

  • TabIndex Property (Outlook Controls)

  • TabStop Property (Outlook Controls)

  • Tag Property (Outlook Controls)

  • Top Property (Outlook Controls)

  • Visible Property (Outlook Controls)

  • Width Property (Outlook Controls)

  • ZOrder Method (Outlook Controls)


Extra Members for Outlook Controls

 Copy code hover
[image]

Extra Members for Outlook Controls
Send feedback

Outlook controls have access to a set of members that belong to the Microsoft Forms 2.0 Control interface. These members include the following properties:

  • ControlTipText

  • Height

  • Left

  • Name

  • TabIndex

  • TabStop

  • Tag

  • Top

  • Visible

  • Width

And the following methods:

  • Move

  • SetFocus

  • ZOrder

Because these members are not part of the Outlook object model, they are not displayed in the object browser and are not supported by intellisense. However, you can search for specific help topics for these members in the Outlook Developer Help.

To access these members, you can directly reference the member, as in the following example, an OlkTextBox control, TextBoxControl, accesses the ControlTipText property directly with the following line of code.

VBA Copy code Copy code
TextBoxControl.ControlTipText = "Enter name of product here"

Alternatively, you can add a reference to the Microsoft Forms 2.0 type library (fm20.dll) and bind the Outlook control dynamically at runtime, as in the following code sample.

Copy code Copy code
Sub AddControlTip()
 Dim TextBoxControl As OlkTextBox
 Dim ictrl As MSForms.Control

 Set ictrl = TextBoxControl
 ictrl.ControlTipText = "Enter product description here"
End Sub


ControlTipText Property (Outlook Controls)

 Copy code hover
[image]

ControlTipText Property (Outlook Controls)
Send feedback

Returns or sets a String that appears when the user briefly holds the mouse pointer over a control without clicking. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ControlTipText

expression A variable that represents an Outlook control object.

Remarks

The ControlTipText property lets you give users tips about a control in a running form. The property can be set during design time but only appears by the control during runtime.

The default value of ControlTipText is an empty string. When the value of ControlTipText is set to an empty string, no tip is available for that control.

Note that for the OlkBusinessCardControl and OlkContactPhoto controls, ControlTipText is not displayed when mousing over the control.


Height Property (Outlook Controls)

 Copy code hover
[image]

Height Property (Outlook Controls)
Send feedback

Returns or sets a Single that specifies the height, in points, of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Height

expression A variable that represents an Outlook control object.

Remarks

The Height and Width properties are automatically updated when you move or size a control. If you specify a setting for the Left or Top property that is less than zero, that value will be used to calculate the height or width of the control, but a portion of the control will not be visible on the form.

If you move a control from one part of a form to another, the setting of Height or Width only changes if you size the control as you move it. The settings of the control's Left and Top properties will change to reflect the control's new position relative to the edges of the form that contains it.

The value assigned to Height or Width must be greater than or equal to zero. For most systems, the recommended range of values is from 0 to +32,767. Higher values may also work depending on your system configuration.

For most systems, the recommended range of values for Left and Top is from -32,767 to +32,767. Other values may also work depending on your system configuration. For an OlkComboBox control, values of Left and Top apply to the text box portion of the control, not to the list portion. When you move or size a control, its new Left setting is automatically entered in the property sheet.


Left Property (Outlook Controls)

 Copy code hover
[image]

Left Property (Outlook Controls)
Send feedback

Returns or sets a Single that represents the distance between a control and the left edge of the form that contains it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Left

expression A variable that represents an Outlook control object.

Remarks

Setting the Left or Top property to 0 places the control's edge at the left or top edge of its container.

For most systems, the recommended range of values for Left and Top is from -32,767 to +32,767. Other values may also work depending on your system configuration. For an OlkComboBox control, values of Left and Top apply to the text box portion of the control, not to the list portion. When you move or size a control, its new Left setting is automatically entered in the property sheet.

The Height and Width properties are automatically updated when you move or size a control. If you specify a setting for the Left or Top property that is less than zero, that value will be used to calculate the height or width of the control, but a portion of the control will not be visible on the form.

If you move a control from one part of a form to another, the setting of Height or Width only changes if you size the control as you move it. The settings of the control's Left and Top properties will change to reflect the control's new position relative to the edges of the form that contains it.


Move Method (Outlook Controls)

 Copy code hover
[image]

Move Method (Outlook Controls)
Send feedback

Moves a control to the specified location.

Version Information

Version Added: Outlook 2007

Syntax

expression .Move(Left, Top, Width, Height, Layout)

expression A variable that represents an Outlook control object.

Parameters

Name | Required/Optional | Data Type | Description
Left | Optional | Variant | Single-precision value, in points, indicating the horizontal coordinate for the left edge of the object.
Top | Optional | Variant | Single-precision value, in points, that specifies the vertical coordinate for the top edge of the object.
Width | Optional | Variant | Single-precision value, in points, indicating the width of the object.
Height | Optional | Variant | Single-precision value, in points, indicating the height of the object.
Layout | Optional | Variant | A Boolean value indicating whether the Layout event is initiated for the control's parent following this move. False is the default value.

Remarks

The maximum and minimum values for the Left, Top, Width, and Height arguments vary from one application to another.

You can move a control to a specific location relative to the edges of the form that contains the control.

You can use named arguments, or you can enter the arguments by position. If you use named arguments, you can list the arguments in any order. If not, you must enter the arguments in the order shown, using commas to indicate the relative position of arguments you do not specify. Any unspecified arguments remain unchanged.


Name Property (Outlook Controls)

 Copy code hover
[image]

Name Property (Outlook Controls)
Send feedback

Returns or sets a String that identifies the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents an Outlook control object.

Remarks

Guidelines for assigning a string to Name, such as the maximum length of the name, vary from one application to another.

For objects, the default value of Name consists of the object's class name followed by an integer. For example, the default name for the first OlkTextBox you place on a form is OlkTextBox1. The default name for the second OlkTextBox is OlkTextBox2.

You can set the Name property for a control from the control's property sheet or, for controls added at run time, by using program statements. If you add a control at design time, you cannot modify its Name property at run time.

Each control added to a form at design time must have a unique name.


SetFocus Method (Outlook Controls)

 Copy code hover
[image]

SetFocus Method (Outlook Controls)
Send feedback

Moves the focus to this instance of an object.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetFocus

expression A variable that represents an Outlook control object.

Remarks

If setting the focus fails, the focus reverts to the previous object and an error is generated.

By default, setting the focus to a control does not activate the control's window or place it on top of other controls.


TabIndex Property (Outlook Controls)

 Copy code hover
[image]

TabIndex Property (Outlook Controls)
Send feedback

Returns or sets an Integer that specifies the position of a control in the form's tab order. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TabIndex

expression A variable that represents an Outlook control object.

Remarks

The TabIndex is an integer from 0 to one less than the number of controls on the form that have a TabIndex property. Assigning a TabIndex value of less than 0 generates an error. If you assign a TabIndex value greater than the largest index value, the system resets the value to the maximum allowable value.

The index value of the first object in the tab order is zero.


TabStop Property (Outlook Controls)

 Copy code hover
[image]

TabStop Property (Outlook Controls)
Send feedback

Returns or sets a Boolean that indicates whether an object can receive focus when the user tabs to it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TabStop

expression A variable that represents an Outlook control object.

Remarks

True to designate the object as a tab stop (default), False to bypass the object when the user is tabbing, although the object still holds its place in the actual tab order, as determined by the TabIndex property.

You can combine the settings of the Enabled and the TabStop properties to prevent the user from selecting a command button with TAB, while still allowing the user to click the button. Setting TabStop to False means that the command button won't appear in the tab order.


Tag Property (Outlook Controls)

 Copy code hover
[image]

Tag Property (Outlook Controls)
Send feedback

Returns or sets a String that specifies additional information about a control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Tag

expression A variable that represents an Outlook control object.

Remarks

The default is a zero-length string ("").

Use the Tag property to assign an identification string to a control without affecting other property settings or attributes.

For example, you can use Tag to check the identity of a control that is passed as a variable to a procedure.


Top Property (Outlook Controls)

 Copy code hover
[image]

Top Property (Outlook Controls)
Send feedback

Returns or sets a Single that represents the distance between a control and the top edge of the form that contains it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Top

expression A variable that represents an Outlook control object.

Remarks

Setting the Left or Top property to 0 places the control's edge at the left or top edge of its container.

For most systems, the recommended range of values for Left and Top is from -32,767 to +32,767. Other values may also work depending on your system configuration. For an OlkComboBox control, values of Left and Top apply to the text box portion of the control, not to the list portion. When you move or size a control, its new Left setting is automatically entered in the property sheet.

The Height and Width properties are automatically updated when you move or size a control. If you specify a setting for the Left or Top property that is less than zero, that value will be used to calculate the height or width of the control, but a portion of the control will not be visible on the form.

If you move a control from one part of a form to another, the setting of Height or Width only changes if you size the control as you move it. The settings of the control's Left and Top properties will change to reflect the control's new position relative to the edges of the form that contains it.


Visible Property (Outlook Controls)

 Copy code hover
[image]

Visible Property (Outlook Controls)
Send feedback

Returns or sets a Boolean that specifies whether a control is visible or hidden. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents an Outlook control object.

Remarks

True if the control is visible (default); False if the control is hidden.

Use the Visible property to control access to information without displaying it. For example, you could use the value of a control on a hidden form as the criteria for a query.

All controls are visible at design time.


Width Property (Outlook Controls)

 Copy code hover
[image]

Width Property (Outlook Controls)
Send feedback

Returns or sets a Single that specifies the width, in points, of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Width

expression A variable that represents an Outlook control object.

Remarks

The Height and Width properties are automatically updated when you move or size a control. If you specify a setting for the Left or Top property that is less than zero, that value will be used to calculate the height or width of the control, but a portion of the control will not be visible on the form.

If you move a control from one part of a form to another, the setting of Height or Width only changes if you size the control as you move it. The settings of the control's Left and Top properties will change to reflect the control's new position relative to the edges of the form that contains it.

The value assigned to Height or Width must be greater than or equal to zero. For most systems, the recommended range of values is from 0 to +32,767. Higher values may also work depending on your system configuration.

For most systems, the recommended range of values for Left and Top is from -32,767 to +32,767. Other values may also work depending on your system configuration. For an OlkComboBox control, values of Left and Top apply to the text box portion of the control, not to the list portion. When you move or size a control, its new Left setting is automatically entered in the property sheet.


ZOrder Method (Outlook Controls)

 Copy code hover
[image]

ZOrder Method (Outlook Controls)
Send feedback

Places the object at the front or back of the z-order.

Version Information

Version Added: Outlook 2007

Syntax

expression .ZOrder(zPosition)

expression A variable that represents an Outlook control object.

Parameters

Name | Required/Optional | Data Type | Description
zPosition | Optional | Variant | A control's position, front or back, in the container's z-order.

Remarks

The settings for zPosition are:

Value | Description
0 | Places the control at the front of the z-order. The control appears on top of other controls (default).
1 | Places the control at the back of the z-order. The control appears underneath other controls.

The z-order determines how windows and controls are stacked when they are presented to the user. Items at the back of the z-order are overlaid by closer items; items at the front of the z-order appear to be on top of items at the back. When the zPosition argument is omitted, the object is brought to the front.

In design mode, the Bring to Front or Send To Back commands set the z-order. Bring to Front is equivalent to using the ZOrder method and putting the object at the front of the z-order. Send To Back is equivalent to using ZOrder and putting the object at the back of the z-order.

You can't Undo or Redo layering commands, such as Send To Back or Bring to Front. For example, if you select an object and click Move Backward on the shortcut menu, you won't be able to Undo or Redo that action.


Customizing Forms (Outlook)

 Copy code hover
[image]

Customizing Forms (Outlook)
Send feedback

Insert introduction here.

Section Heading

Insert section body here.

Subsection Heading

Insert subsection body here.


How to: Create an Outlook Form

 Copy code hover
[image]

How to: Create an Outlook Form
Send feedback

You must base all custom forms in Microsoft Outlook on standard forms. Some of the default pages of these forms can be customized. If you do not want to use the functionality in a default form that Outlook provides, you can customize the form by hiding, adding, or replacing portions of pages or entire pages, or by replacing entire standard forms.

There are a few things to consider when you select the standard Outlook form for your custom form solution:

  • Routing versus folder-based solutions

    If you plan to distribute the custom form by e-mail, choose the standard mail message form. If you plan to post the custom form in a public folder, choose the standard post form.

  • Built-in fields on the standard form

    Select the form for the type of item that has fields best suited to the needs of your custom solution. Each type of Outlook item has a set of fields built into it. For example, to see all of the fields that are available in an e-mail message, click All Mail Fields in the Field Chooser. For more information, see Using the Field Chooser.

  • Extent of customization

    When you select a standard form, consider the extent to which you want to customize the form. Most standard forms have more than one page on the form, but only the pages on the mail and post forms, and the General page on the contact form are customizable. To change many of the existing standard form pages, you can:

    • Hide the existing page on the form, create a new page, and add fields or controls to that page.

    • Use additive form regions to extend the user interface on the default form or to add an extra page to a standard form.

    • Use replacement form regions to replace a default page or an entire standard form.

To design an Outlook form

  1. On the Developer tab, in the Custom Forms group, click Design a Form, and then select the standard form on which to base your custom form.

  2. Add the fields, controls, and code that you want to your new form. For more information, see Using Fields with Controls, Using Visual Basic with Outlook, and How to: Create a Form Region.

  3. Set form attributes for the custom form.

  4. Publish the form. (For more information, see How to: Publish a Form.)

    Note Note

    • To make the custom form available so that you or other users can create new items in a folder, you must publish the form to the folder. If you want the form to be available to other users, publish the form to a public folder so that it is available to users who have permissions to that folder. If you want the form to be available only to you, publish it in a personal folder.

    • Form regions cannot be published to the server; you must deploy them by using an add-in. For more information, see Extending a Form Region with an Add-in.


Add-ins Overview

 Copy code hover
[image]

Add-ins Overview
Send feedback

You can use add-ins to customize your Microsoft Outlook form pages and form regions.

COM add-ins are executable (.exe) files or dynamic-link library (.dll) files that add extra functionality to Outlook. Use COM add-ins with form regions to expand the capabilities of those regions to include custom business logic or advanced functionality. In contrast to the way you customize form pages in an Outlook form, you do not use Visual Basic Scripting Edition (VBScript) to write code behind a form; instead, you program form regions with a COM add-in. For more information, see Extending a Form Region With Add-ins.

For more information, see How to: Add or Remove an Add-in.


Troubleshooting Forms

 Copy code hover
[image]

Troubleshooting Forms
Send feedback

My solution doesn't run on other computers.

Use the following troubleshooting tips to help troubleshoot problems if your forms or programming solution works on some computers, but not others.

Microsoft Visual Basic Scripting Edition (VBScript) version If your solution involves forms that use VBScript, you may need to make sure that all computers are using the same version of VBScript that is being used on your development computer. VBScript is a shared component. Installing other software, such as a newer version of Windows Internet Explorer, may result in newer versions of VBScript being installed. For the latest information about VBScript versions, go to http://www.microsoft.com/scripting.

Controls If your solution uses any nonstandard controls, check to see if the controls are properly installed on all of the user's computers. If you are using any control other than one of the Forms 2.0 controls that are installed by Microsoft Office, you should provide your users with a Setup program to ensure that all of your controls are installed correctly.

Permissions or user rights Make sure that any user experiencing problems has proper permissions or rights to use any public folders or other resources that your solution uses.

The Click event of a control doesn't fire.

The Click event doesn't fire for controls bound to a field. Because the controls are bound to a field, you can use the PropertyChange or CustomPropertyChange event of the item to detect any change to the value of the field.

Is there anything that helps debugging my custom form?

Problems in the user interface If your custom form is extended by an add-in, the problems you see in the user interface of the form may be caused by the add-in. In the Other tab of the Options dialog box, click Advanced Options. Select the check box for Show add-in user interface errors. This will help you debug errors that your add-in causes in the user interface.

Problems in the functionality or behavior of the form If your custom form contains a form region, check the XML that defines the form region. Form region XML can be specified inline in the Windows registry, but more commonly the XML would be defined in the corresponding form region manifest XML file. Make sure that the XML validates against the form region XML schema. For more information, see Using the Form Region XML Manifest to Define a Form Region.


Customizing Forms Using Form Regions

 Copy code hover
[image]

Customizing Forms Using Form Regions
Send feedback

In this section

  • Form Regions

  • How to: Create a Form Region


Form Regions

 Copy code hover
[image]

Form Regions
Send feedback

Form regions are custom pieces of user interface that can be used to customize a standard form. There are four types of form regions:

  • adjoining form region

  • separate form region

  • replacement form region

  • replace-all form region

An adjoining form region is a form region added to the bottom of the default page of a standard Outlook form, and a separate form region is an individual page added to a standard Outlook form. Adjoining form regions and separate form regions are additive form regions. You can have up to 50 adjoining form regions and up to 30 separate form regions in a form.

A replacement form region is a page that replaces the default page of a standard form, and a replace-all form region replaces all pages in a standard Outlook form.

Although you can create a custom form that contains a form region without using an add-in, add-ins allow you to deploy and further extend a standard Outlook form. Add-ins customize form regions of a form in a way similar to other custom pages of a form, by adding fields from the Field Chooser and controls from the control toolbox. However, while you add code behind a custom form page using the Script Editor and Visual Basic Scripting Edition (VBScript), you add code behind a form region using an add-in. For more information on using an add-in to extend a form region, see Extending a Form Region with an Add-in.

Form regions allow greater flexibility in customizing and extending a standard Outlook form in the following ways:

  • You can add new user interface as adjoining form regions to the default page of any standard Outlook form.

  • If you are using adjoining or separate form regions to add user interface to a standard form, you can choose to specify the message class of the form regions as the same message class of the standard form (for example, IPM.Contact), or as a custom message class derived from the standard message class (for example, IPM.Contact.PersonalContacts).

  • You can use a replacement form region to replace the default page of a standard form, or a replace-all form region to replace the entire standard form. In this case, you must specify a derived message class for the form region and register the form region for that message class.

  • Multiple add-ins can add form regions to the same form.

  • Administrators can more conveniently deploy a form customized with form regions by installing and running an add-in. For more information, see the Office Resource Kit Web site.


How to: Create a Form Region

 Copy code hover
[image]

How to: Create a Form Region
Send feedback

This topic lists the considerations and steps for creating a form region.

There are different types of form regions, depending on how you want to customize the form and where you place the form region in the form. A form region can add extra user interface to the default page or add an extra page to a standard form. Or, it can replace the default page of a standard form, or replace the entire standard form, resulting in a new form for a derived message class. You specify the type of the form region in a form region manifest XML file, using the <formRegionType> tag as described in step 7. Aside from this, the means to create and design these various types of form regions is identical:

  1. Use the Forms Designer to create and design the layout (steps 1 through 5)

  2. Save the form region to an Outlook Form Storage (.OFS) file (step 6)

  3. Create a form region manifest XML file to specify other details about the form region to Microsoft Outlook (step 7)

  4. Register the form region for a message class (step 9)

When you restart Outlook, the form region will be available for use. Alternatively, you can create the form region and the form region manifest XML file, use an add-in to extend the form region and register the form region programmatically. When you install the add-in, the add-in will also install the form that contains the form region. For more information, see Extending a Form Region with an Add-in.

The following procedure details the steps to create a form region using the Forms Designer without an add-in.

  1. On the Developer tab, in the Custom Forms group, click Design a Form.

  2. Select one of the nine standard Outlook forms that is best suited for your purpose: Appointment, Contact, Journal Entry, Meeting Request, Message, Post, RSS Article, Task, and Task Request.

    When you customize a form, you always start with a standard form as a template. When you choose the standard form, you should consider the following:

    • The actions associated with the form, for example, whether you will be sending the form to other people, in which case you should choose the Message form.

    • The kinds of fields you will need in the form, for example, whether they are mostly contact-specific fields.

  3. Plan the scope of your customization. Will it suffice if you add extra controls to the bottom of the default page of the standard form? Will you need an extra custom page? Or, will you want to modify the user interface so substantially that it would be easier to create a new form? Note that you can replace pages on a form only if you specify that form for a derived message class.

  4. In the Forms Designer, on the Developer tab, in the Design group, click New Form Region.

    Note that any type of form region opens as a separate page in the Forms Designer. At runtime, the form region will be displayed the way you have specified in the form region manifest XML file, as described in step 7.

  5. Design the layout of the form region by dragging and dropping controls from the Toolbox to the form region, and binding them to fields where appropriate.

    Similar to customizing a form page, customizing a form region involves defining custom fields, inserting controls using the Toolbox, and binding the controls with fields using the Field Chooser. For more information, see Controls in a Custom Form and the section Design the Form Region in Walkthrough: Add a Form Region to an Existing Page on a Form. Optionally, you can use an add-in to program events of the controls.

  6. Save the layout of the form region by clicking Save Region, and then Save Form Region in the Design group. The form region layout file will be saved with a .OFS extension.

  7. Use an XML editor such as Notepad to create a form region manifest XML file.

    You must specify XML for each form region to tell Outlook how to display it and the actions it supports. The XML must validate against the form region manifest schema (for more information about the schema, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library). The schema supports many elements, such as the more commonly used ones enumerated below:

    • The <addin> tag specifies the ProgID of the add-in that manages the form region and provides storage for it. You should only specify this tag if you use an add-in to create and manage the form region.

    • The <customActions> tag that specifies the actions supported by the form region, for example, reply and forward.

    • The <displayAfter> tag specifies the form region that precedes the current form region in the same form. This information defines the initial order of multiple adjoining form regions or multiple separate form regions in the same form.

    • The <formRegionType> tag specifies whether the form region is an additive form region (adjoining or separate form region), or is a replacement or replace-all form region (replacing the default page or the entire standard form and resulting as a new form for a derived message class).

    • The <layoutFile> tag specifies the location of the .OFS file, if one exists. Note that any file paths in the .OFS file, including this file path, can be specified as a relative path to the location of the form region manifest XML file specified in the registry. However, also note that UNC paths are not supported. If you use an add-in to create and manage the form region, you must specify the <addin> tag but not this tag.

    • The <name> tag specifies the name for the form region used only in code.

    • The <title> tag specifies the display name of a separate form region in the Actions menu and the Choose Form dialog box.

    • The <icons> tag specifies the location of icon files.

      Note Note

      By default, the icon file is in the same folder as, or in a path relative to, the form region manifest XML file. You can also specify a full path for the icon file, for example:

      <icons><default>c:\myicon.ico</default></icons>

      or a full path for a resource file, for example:

      <icons><unread>c:\myresource.dll,101</unread> </icons>

      which loads the icon resource 101 in the resource file c:\myresource.dll. However, do not use the implicit convention that specifies icons embedded in the add-in assembly file. For example:

      <icons><read>,102</read></icons>

      will not be supported and will not load the icon resource 102 in the add-in dll.

  8. Close Outlook.

  9. Register the form region in the Windows registry, specifying the message class that this form region is intended for, and the full file path for the form region manifest XML file.

    Register form regions under either the HKEY_CURRENT_USER or the HKEY_LOCAL_MACHINE hive in the Windows registry. For example, additive form regions for the IPM.Contact message class for the current user should be registered under the same key, HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions\IPM.Contact. Note that the form region will be displayed for the current user in all forms applied to IPM.Contact and any message class derived from IPM.Contact. If you want a form region to be used only for IPM.Contact and do not wish derived message classes to use that form region, you can specify this using the <exactMessageClass> tag in the form region manifest XML file.

  10. Start Outlook. When you open an item of the message class that you have specified for the form region in step 9, you will see the form region in the inspector.


Customizing Forms Using Form Pages

 Copy code hover
[image]

Customizing Forms Using Form Pages
Send feedback

In this section

  • Setting Default Properties for a Form

  • Setting the Attributes of a Form

  • Testing and Publishing Your Forms

  • Creating Custom Forms by Using Visual Basic Scripting Edition


Setting Default Properties for a Form

 Copy code hover
[image]

Setting Default Properties for a Form
Send feedback

To set the default properties for a custom form that has form pages, use the Properties tab in the Forms Designer.

Note Note

For more information about how to set the default properties in a Microsoft Outlook form that has form regions as opposed to form pages, see How to: Create a Form Region.

The following are the default properties for custom forms that have form pages:

  • Category You can specify a category for your form to help organize the forms in the Choose Form dialog box when you select a form.

  • Sub-Category You can further refine the category by specifying a sub-category.

  • Always use Microsoft Word as the e-mail editor Since Microsoft Office Outlook 2007, Outlook uses Microsoft Word as the e-mail editor. However, using Word as the editor is optional in earlier versions. If you create forms for users who use earlier versions of Outlook, you can use this option to specify Word as the editor for the message portion (or control) of your form. Users then have all the formatting options that are available with Word, such as the spell checker and thesaurus. For these options to be available, the recipients of your form must have Word installed.

    Note Note

    This feature has not been changed from earlier versions of Microsoft Office. The code behind this option uses an older architecture for using Word as the e-mail editor and does not provide the same user experience with Word that clicking Options on the Microsoft Office Backstage view does. Solutions that you create for earlier versions using Word as the e-mail editor might not work, or might not work properly, in Office Outlook 2007 or a later version of Outlook.

  • Template You can specify the Word template to use to format the text in the message control of the form.

    Note Note

    Although Word is now the e-mail editor, this setting, as applicable to Outlook forms, is enabled only if you select the Always use Microsoft Word as the e-mail editor check box. If this check box is cleared, you cannot set templates.

  • Contact When you click Contact, you can access the Address Book, where you can select the people who maintain, upgrade, or distribute information about this form. The contact information that you provide appears in the Forms Manager dialog box and the form Properties page.

  • Description You can type a description for your form. For example, you could include instructions for how to use the form or explain the purpose of the form. Outlook displays the description in the About dialog box on the Help menu of the form and in the Properties dialog box for the form.

  • Version You can set a version number for this form. This is a free-form text field and does not affect Outlook behavior in any way.

  • Form Number You can set a unique form number that identifies the form. This is a free-form text field and does not affect Outlook behavior in any way.

  • Change Large Icon Click this button to open the File Open dialog box, where you can select a different large icon for your form. Large icons appear in the form Properties dialog box.

  • Change Small Icon Click this button to open the File Open dialog box, where you can select a different small icon for your form. Small icons appear in the Outlook folder to represent an item of the type the form creates.

  • Send form definition with item Instructs Outlook to include the form definition when you send the form. (Note that the form is much larger when it includes the form definition.) When you select this option, Outlook creates a self-contained form that the recipients can use to view the form, even if they do not have access to the same forms library as the sender.

    Note Note

    Because of improvements to security since Office Outlook 2007, this option is not recommended nor is it necessary in most cases. In general, publishing the form is all that is needed.

    Outlook does not run Microsoft Visual Basic Scripting Edition (VBScript) code if the form definition is included with the item. In most cases, it is better to publish a form instead of including the form definition with the item. If you do send the form with the item, you can re-enable the VBScript code if you use the Outlook custom security settings. In that case, if you send a form with this box checked, the recipients see a Warning dialog box, and they have the option to disable the macros because the form is not published. Harmful macros could delete or copy their files, or send e-mail messages from their mailbox to another user.If network or file transfer time is an issue, and you cannot publish the form for some reason, an alternative to sending the form definition is to save the form and send it as an attachment to another form. Recipients can take the attached form and publish it in their own forms library.

  • Use form only for responses Hides a form when it is published to a forms library. This option is useful in situations when you create a form to use solely for replies. In another form, you can specify that your reply form will be used instead of the default reply form.To use your form only for responses, select the Use form only for responses check box, and then publish your form. Open a second form in design mode. On the Actions page of the second form, you can specify your published form in the Reply or Reply to All action. To use your form as the default reply form, double-click the Reply action in the second form. You can select the name of your published reply form in the Form name field of the Form Action Properties dialog box.


Setting the Attributes of a Form

 Copy code hover
[image]

Setting the Attributes of a Form
Send feedback

To set the attributes of a custom form that has form pages, use the Properties and Actions pages in design mode. The Properties page includes information such as Description, Category, and Form Number that helps users to find and identify your form in the Choose Form dialog box. The Actions page includes all of the various ways that users can reply to a form, including Reply, Reply All, Forward, and so on.

When you customize a form with form regions, you set the attributes for a form region inside the form region manifest file. The values that you specify on the properties and actions pages in the forms designer are not saved with a form region and are not used when a form region is loaded. For more information, see How to: Create a Form Region.

One important attribute of your form to consider is whether to send the form definition with the form. The form definition includes all the fields and the code that you add to the form. As a general rule, publish the form definition to a forms library instead of sending the form definition with the item. If you cannot publish your form to a forms library, you can select the Send form definition with item check box on the Properties page so that other users can see the form pages when they receive items that are composed by using the form.

Forms that you only intend to use once and not publish are referred to as "one-off forms." Because of security concerns with one-off forms, users might not see the form correctly when they open items sent to them with a one-off form. In this case, sending the form definition with the one-off form provides the necessary information required to display the form correctly for the users.

If you plan to publish your form to a forms library that other users can access, such as an Organizational Forms Library or a Public Folder library, you do not need to send the form definition; it is stored in the library. The form definition can add considerable size to items that are saved by using your form.

To change how users reply to your form, click the Actions page. The Actions page lists the default Reply forms that are available. You can also add your own custom Reply forms. For example, forms based on a new e-mail message have built-in Reply, Reply to All, Forward, and Reply to Folder forms. When users receive your form, the form contains buttons and menu commands so that users can respond to the form. You can disable some or all of these default forms and set attributes that define how these Reply forms appear.


Testing and Publishing Your Forms

 Copy code hover
[image]

Testing and Publishing Your Forms
Send feedback

After you design and complete your form, test it to make sure that it works the way that you designed it to work.

Note Note

You cannot test form regions from inside Microsoft Outlook. You must save the form as an .ofs file, update the add-ins that are used with the form regions, and then restart Outlook. For more information, see How to: Create a Form Region.

To test, at run time, an Outlook form that has customized form pages, publish the form to a folder or your Personal Forms Library, and then open it to see how it works. Send the form to yourself to check the Reply actions, and then publish the form to a public folder or to your Organization Forms Library for others to use. You can also save a form to use in e-mail or as a template.

What do you want to do?

  • How to: Test a Form in Run Time

  • How to: Publish a Form


Creating Custom Forms by Using Visual Basic Scripting Edition

 Copy code hover
[image]

Creating Custom Forms by Using Visual Basic Scripting Edition
Send feedback

Microsoft Visual Basic Scripting Edition (VBScript) is a subset of Microsoft Visual Basic for Applications (VBA). You can use VBScript to create procedures that control Microsoft Outlook folders, objects, items, and properties.

VBScript in Outlook requires a special object syntax that is different from referencing objects in VBA. For more information, see Outlook Object Model.

You can choose the Outlook item on which to base your custom form. For more information, see Choosing an Item.

You can extend Outlook forms by using custom controls from the Control Toolbox. Outlook forms can use most of the properties and methods that come with the controls. Since controls cannot store values, you must bind the control to an Outlook field to store the value. For more information, see Binding.

The Outlook object browser displays the classes, properties, methods, events, and constants that are available from the Outlook object library. Open the object browser to view and use objects, and to obtain information about the syntax for using the object. For more information, see Viewing and Using the Object Browser.


Customizing Outlook Forms

 Copy code hover
[image]

Customizing Outlook Forms
Send feedback

In this section

  • Getting Started with Customizing Form Pages

  • Getting Started with Creating Form Regions

  • Configuring Forms

  • Specifying Form Appearance

  • Specifying Form Behavior

  • Using Fields and Controls to Interact with Users

  • Using Visual Basic to Customize Outlook Forms

  • Extending Forms and Form Regions Using Add-ins


Getting Started with Customizing Form Pages

 Copy code hover
[image]

Getting Started with Customizing Form Pages
Send feedback

In this section

  • How to: Customize Pages on a Form

  • How to: Manage Your Forms in Forms Manager

  • How to: Open a Form

  • How to: Save a Form as a File

  • How to: Save a Form in a Forms Library

  • How to: Save a Form with the Item (One-off Forms)

  • How to: Save and Distribute a Form

  • How to: Set Properties for a Form

  • How to: Publish a Form

  • How to: Test a Form in Run Time


How to: Customize Pages on a Form

 Copy code hover
[image]

How to: Customize Pages on a Form
Send feedback

In general, you can customize up to five pages on a form. For e-mail messages and posts, you can customize a sixth page, the Message page; for contacts, you can customize the General page. You can also customize forms by using form regions. For a side-by-side comparison of both options, see Customizing Form Pages and Form Regions.

Forms customized with form regions

When you customize a form by using form regions, you begin with a standard form as a template, just as you do when you customize a form page. Any type of form region opens as a separate blank page in the Forms Designer, and you design your layout from there. For more information, see How to: Create a Form Region and Walkthrough: Add a Form Region to an Existing Page on a Form.

Forms customized with form pages

In the Forms Designer, do the following:

  1. Click the page that you want to customize.

  2. From the Field Chooser, drag a field to the page. Outlook automatically sizes the field for you. If you do not see the Field Chooser box, on the Developer tab, in the Tools group, click Field Chooser.If the field that you want does not appear in the Field Chooser, click a different field set from the list in the box at the top of the Field Chooser.

  3. To align, size, or remove fields, right-click the field, and then select the options that you want from the shortcut menu.

  4. Add and remove controls.

Tip Tip

  • To create fields, click New in the Field Chooser. Type a name for the field in the Name box, and then select a field type and format. Fields support calculated expressions, validation formulas, and field formatting.

  • If you drag a field or control to a hidden page, the form automatically displays the page at run time.


How to: Manage Your Forms in Forms Manager

 Copy code hover
[image]

How to: Manage Your Forms in Forms Manager
Send feedback

You can use Forms Manager to view and organize all of your published forms.

Note Note

Forms that are customized with form regions are registered in the Windows registry instead of published; you cannot view them in Forms Manager. For more information, see Form Regions and How to: Create a Form Region.

In Forms Manager, you can browse to the folders where your forms are stored and identify them by number, version, and name. You can also move and copy forms, and view the properties of each form.

To open Forms Manager

  1. Click the File tab.

  2. Click Options.

  3. Click Advanced.

  4. In the Developers heading, click Custom Forms, and then click Manage Forms.


How to: Open a Form

 Copy code hover
[image]

How to: Open a Form
Send feedback

To open a form region

  1. In the Forms Designer, open the base form that contains the form region.

  2. On the Developer tab, in the Design group, click Open Form Region.

To open forms with customized form pages

To open a form that is | Do this
In the Outlook Folders Library | On the Developer tab, in the Custom Forms group, click Choose Form. In the Choose Form dialog box, select Outlook Folders in the Look In drop down list.
In the Standard Forms Library | On the Developer tab, in the Custom Forms group, click Choose Form. In the Choose Form dialog box, select Standard Forms Library in the Look In drop down list.
In the Personal Forms Library | On the Developer tab, in the Custom Forms group, click Choose Form. In the Choose Form dialog box, select Personal Forms Library in the Look In drop down list.
Saved as an Outlook template | On the Developer tab, in the Custom Forms group, click Choose Form. In the Choose Form dialog box, select User Templates in File System in the Look In drop down list. Click Browse and then select the folder that contains the saved Outlook template.
Saved as a file | Click the File tab. Click Open, and then click Open Outlook Data File. Select the folder that contains the file and then select the file. Click Open.


How to: Save a Form as a File

 Copy code hover
[image]

How to: Save a Form as a File
Send feedback

Forms customized with form regions

When you save a form that is customized with form regions, you must save each form region layout as an Outlook Form Storage (.OFS) file. Additional steps include creating an XML manifest for each form region and registering them in the Windows registry, specifying the message class that each form region is intended for. For more information about saving form regions. see How to: Create a Form Region.

Forms customized with form pages

  1. Click the File tab.

  2. Click Save As.

  3. In the File name box, type a name for the form.

  4. In the Save as type box, click a file type.

    To save the form as an Outlook template, click Outlook Template, and then save the form in the Templates folder.


How to: Save a Form in a Forms Library

 Copy code hover
[image]

How to: Save a Form in a Forms Library
Send feedback
Note Note

This Help topic describes how to save a form that you customized with form pages; it does not apply to forms that you customized with form regions. With form regions, you save the layout of the form region by clicking Form Region, and then Save Form Region to save the form region layout file with an .ofs extension. After that, you must create a form region manifest XML file and register the form region in the Windows registry. For more information, see How to: Create a Form Region.

Forms customized with form pages

  1. In an open form, on the Developer tab, in the Form group, click Publish, and then click Publish Form As.

    Note Note

    If you do not see the Developer tab in the open form, see the topic Run in Developer Mode in Outlook.

  2. In the Display Name box, type the display name for the form.

  3. In the Form box, type the name for the form.

  4. To change the location (library) where the form is stored, select a folder in the Look In box, or click the browse button and select a folder.

  5. (Exchange only) To save the form in the Organizational Forms Library, click Organizational Forms Library in the Forms Library box. To save the form in the Outlook Folders Library, click Outlook Folders, and then click the folder where you want to save the form. To save the form in the Personal Forms Library, click Personal Forms Library.

  6. After you select the folder where you want to publish your form, click Publish.


How to: Save a Form with the Item (One-off Forms)

 Copy code hover
[image]

How to: Save a Form with the Item (One-off Forms)
Send feedback
Note Note

This Help topic describes how to save a form that is customized with form pages; it does not apply to forms that are customized with form regions. With form regions, you save the layout of the form region by clicking Form Region, and then Save Form Region to save the form region layout file with an .ofs extension. After that, you must create a form region manifest XML file and register the form region in the Windows registry. For more information, see How to: Create a Form Region.

Forms customized with form pages

When you create a solution by using custom forms in Microsoft Outlook, it is important to understand how Outlook uses your custom form in relation to the items in a folder.

For example, when you create a custom contact form to replace the default Outlook contact form, you typically follow these steps:

  1. Start with a new, default contact item to use as the basis for your custom form.

  2. Modify the form to meet your needs.

  3. Publish the form to the Contacts folder.

  4. Set the form as the default form for the Contacts folder by changing the folder properties.

In this typical scenario, information about the form (the form definition) is not saved with each item. Instead, the form is stored in the location where it was published and is referenced by using the Message Class field. This way, each item only stores the data associated with it, and its size is relatively small.

However, it is possible to have Outlook store the form definition within individual items in a folder. These items are called one-off items and always use the form definition that is stored within the item instead of the published form.

In most situations, the form definition should not be stored within the item. The most common exception to this is a custom e-mail message form. If you use Microsoft Exchange Server, you can publish a custom e-mail message form to the Organizational Forms Library so that it is always available to everyone in the organization. This way, you do not have to store the form definition in the item. If you do not use Exchange Server, or if you are sending the form to another organization where the form is not available, select the Send form definition with item check box on the Properties page of the form when in design mode. Depending on security restrictions, this might enable the recipient to view the e-mail message with the custom form.

Note Note

If the recipient still cannot view your custom form, make sure that you customized or disabled the Read page of the custom e-mail form.

If the custom form contains Microsoft Visual Basic Scripting Edition (VBScript), Outlook displays the macro virus warning unless the form is published in the Exchange Server Organizational Forms Library.

The following scenarios commonly result in items becoming one-off items.

  • You have a folder-based solution whereby the form is published in the folder and the items use the published form. You open an existing item in a folder, make changes to the form in design mode, and then save the item.

    Because the form definition has changed and the form was not republished, Outlook saves the new form definition with the item. To change the form for all items in the folder, instead of opening an existing item, follow these steps:

    1. Open a new item based on your custom form.

    2. Make the form design changes to that item.

    3. Republish the form with the same name.

    4. Close and do not save changes to the item.

    All the items in the folder will use the updated custom form the next time that the items are opened, because the message class of the items still refers to the published form.

  • VBScript code in the custom form changed the form definition of the item.

    If VBScript code within an item programmatically changes the form, in many cases the result is that the form definition is saved with the item. The following Outlook object model methods most commonly cause this behavior:

    • UserProperties.Add method.

    • Methods and properties of the FormDescription object.

    • Some methods or properties of controls, such as Enabled.

    • Methods and properties of the Actions collection object.

Although solutions and situations vary greatly, the following might indicate that an item has become a one-off item.

  • VBScript code in the form does not run, or a macro virus warning unexpectedly appears, indicating that the item itself, and not just a published form, contains VBScript code.

  • The size of an item increases unexpectedly.

  • An item's icon changes unexpectedly.


How to: Save and Distribute a Form

 Copy code hover
[image]

How to: Save and Distribute a Form
Send feedback

There are two ways in Microsoft Outlook to save a form that has customized form pages. (If you customize a form with form regions, the procedure to save the form region and make the form available is also different.)

Note Note

Outlook custom forms cannot be directly converted into other types of forms, such as Microsoft Exchange Web forms for Microsoft Outlook Web Access or Microsoft Office InfoPath forms.

Forms customized with form regions

To save the layout of the form region, click Form Region, and then click Save Form Region to save the form region layout file with an .ofs extension. After that, you must create a form region manifest XML file and register the form region in the Windows registry.

For more information, see the following topics:

  • Form Regions

  • How to: Create a Form Region

Forms customized with form pages

  • Save the form in a forms library when you want to save a form to a location for easy access. There are three forms libraries. To open the libraries in an open form, on the Developer tab, in the Form group, click Choose Form. The libraries are listed in the Look In box.

    • Personal Forms Library Forms saved in this library are accessible only to you and are stored in your mailbox. Use this library when you create a form for your own personal use, such as a form to track mileage.

    • Outlook Folders Forms saved in this library can be accessible to everyone (in a public folder) or only to you (in a private folder). If the form is saved in a library on your hard disk, it is accessible to you only while you are working in the folder. These forms are available on the item menu while you are in the folder. Use this library when saving forms to a specific folder, generally a public folder. For example, in a customer-tracking public folder, you could have a meeting report form and a customer profile form.

    • Organizational Forms Library Forms saved in this library are accessible to everyone in your organization and are stored on the server. You must have write permission to save to the server. For more information, see your administrator. Use this library when you want to make the form available to everyone in your organization, such as a form to report vacation time. Saving to this library provides a quick and easy way to distribute and update forms.

  • Save the form as a file. Use this option when you want to work with the form in another program or you want to save the form as a template, and you do not plan to share the form with others, or you want to send the form to others by using e-mail.

For more information, see the following topics:

  • How to: Save a Form in a Forms Library

  • How to: Save a Form as a File


How to: Set Properties for a Form

 Copy code hover
[image]

How to: Set Properties for a Form
Send feedback

Forms customized with form regions

To set properties for a form region in a custom form, you must use the XML manifest file instead of the Forms Designer. To learn more, see How to: Create a Form Region.

Forms customized with form pages

  1. In the Forms Designer, click the (Properties) tab.

  2. To be able to send a copy of the form in e-mail, select the Send form definition with item check box.

  3. To have the form show only for replies to messages, select the Use form only for responses check box.

  4. Select other options that you want.


How to: Publish a Form

 Copy code hover
[image]

How to: Publish a Form
Send feedback
Note Note

You cannot publish forms that you customized with form regions to the server; instead, you must deploy them by using an add-in. For more information, see How to: Extend a Form Region with an Add-in.

Publish a form customized with form pages

  1. In Microsoft Outlook, on the Developer tab, in the Custom Forms group, click Choose Form.

  2. In the Choose Form dialog box, select a customized form from the forms library and click Open.

  3. On the Developer tab, in the Form group, click Publish, and then click Publish Form.

Note Note

Publishing a form that has not been previously published will open the Publish Form As dialog box.


How to: Test a Form in Run Time

 Copy code hover
[image]

How to: Test a Form in Run Time
Send feedback

Forms customized with form regions

You cannot test forms that you customize with form regions from inside Outlook. Instead, you must save the form as an .ofs file, update the add-ins that are used with the form regions, and then restart Outlook. For more information, see How to: Create a Form Region.

Forms customized with form pages

  1. To switch the form between design mode and run mode (that is, the way the form appears when it is used) do the following. In the Forms Designer, on the Developer tab, in the Form group, click Run This Form.

    Note Note

    You can test the form outside the Microsoft Outlook design environment by opening a new instance of the form.

  2. Type information in the form, send or post it, and then open the form to make sure that it behaves as expected.


Getting Started with Creating Form Regions

 Copy code hover
[image]

Getting Started with Creating Form Regions
Send feedback

In this section

  • Walkthrough: Add a Form Region to an Existing Page on a Form

  • Specifying Form Regions in the Windows Registry

  • Designing Form Regions with the Form Region XML Schema


Walkthrough: Add a Form Region to an Existing Page on a Form

 Copy code hover
[image]

Walkthrough: Add a Form Region to an Existing Page on a Form
Send feedback

This walkthrough shows how to add an adjoining form region to the General page of the standard Contact form. The major steps are as follows:

  1. Use the Forms Designer to create an adjoining form region, and save the form region to an Outlook Form Storage (.OFS) file, Contoso.ofs.

  2. Use a text editor, such as Notepad, to create a form region manifest XML file for the form region. This file describes to Outlook how to display the form region (for example, title, and localized action names) and what it does (for example, custom actions and add-in support).

  3. Use the Windows Registry Editor to register the form region with a message class, identifying to Outlook the type of items that are elgible to use this form region.

  4. Restart Outlook to use the updated Contact form.

Design the Form Region

To create and design a form region, you will use the Forms Designer in much the same way as you customize a form page, by adding controls from the control toolbox to the form region and optionally binding controls to fields. You will create an adjoining form region that will append to the end of the General page of the contact form. This form region will contain six controls. You will insert the controls in the form region, create three user-defined fields, and bind the controls to the fields. When you are done with designing, you will save the form region to an .OFS file. Figure 1 shows the resultant General page of the Contact form.

Figure 1. The customized Contact form at runtime - the General page showing an adjoining form region at the bottom.

  1. In Outlook, on the Developer tab of the Microsoft Office Fluent ribbon, click Design a Form.

  2. In the Design Form box, click Contact and then click Open, as in Figure 2.

    Figure 2. Choose a standard form to start your customization.

  3. In the Forms Designer, click Form Region and then New Form Region, as in Figure 3.

    Figure 3. Create a form region.

  4. Next, you will create three custom fields: Frequent Flyer Number, Vegetarian, and Seat Preference. If the Field Chooser has not been automatically displayed, click Field Chooser to display it as in Figure 4.

    Figure 4. Use the Field chooser to create custom fields.

  5. Click New. Type Frequent Flyer Number as the Name (see Figure 5), and click OK to create the Frequent Flyer Number field as a custom text field.

    Figure 5. Create the custom field Frequent Flyer Number.

  6. Click New. Type Vegetarian as the Name, select Yes/No as the Type, and select Yes/No as the Format (see Figure 6), and click OK to create the Vegetarian field as a Yes/No field.

    Figure 6. Create the custom field Vegetarian.

  7. Click New. Type Seat Preference as the Name, select Text as the Type (see Figure 7), and click OK to create the Seat Preference field as a custom text field.

    Figure 7. Create the custom field Seat Preference.

  8. In steps 9 through 12, you will insert six Outlook controls in the form region.

    Note Note

    The control toolbox is initialized only with Microsoft Forms 2.0 controls. When you insert a Forms 2.0 control in a form region, if a themed Outlook counterpart control exists as an Outlook control, Outlook will automatically replace the Forms 2.0 control with the themed counterpart. In this walkthrough, the six controls that you will be inserting include one check box control, one combo box control, three label controls, and one text box control. By default, the Forms 2.0 version of these controls exist in the Toolbox. If you insert these controls in a form region, Outlook will always display these controls in the themed look; you do not need to add the Outlook counterpart controls to the Toolbox. This is because after you insert the Forms 2.0 controls from the Toolbox in the form region, Outlook will replace them with their themed Outlook counterpart controls - the Microsoft Outlook Check Box Control, the Microsoft Outlook Combo Box Control, the Microsoft Outlook Label Control, and the Microsoft Outlook Text Box Control. However, there are other Microsoft Outlook controls (for example, the Microsoft Outlook Recipient Control and the Microsoft Outlook Sender Photo Control) that do not exist in the Toolbox by default. To use these Outlook controls for the first time, you will have to add them to the Toolbox, by right-clicking the bottom of the Toolbox and clicking Custom Controls.

    Figure 8 shows the resultant layout of the form region we are going to create. Steps 9, 10, 11, and 12 involve inserting controls from the Toolbox, and binding user-defined fields to some of the controls.

    Figure 8. The desired form region in the Forms Designer.

  9. Add a label control for the title of the form region, Contoso Airlines.

    1. Pick and click the label control to add it from the Toolbox to the form region as shown in Figure 8.

      Note Note

      Using pick-and-click instead of drag-and-drop to insert a control from the Toolbox to the form region allows you to insert the control in the appropriate default size in the form region.

    2. Right-click the label control, click Properties. On the Display tab, type Contoso Airlines as the Caption.

    3. Click Font, and select 14 under Size. Click OK.

    4. Click OK.

    5. Use the mouse to pull on the right handle of the label control to adjust the width to accommodate the length of the caption.

  10. Add a label control and a text box control, and bind the Frequent Flyer Number field to the text box control.

    1. Pick and click another label control to add it from the Toolbox to the form region as shown in Figure 9.

    2. Right-click the label control, click Properties. On the Display tab, type Frequent Flyer Number: as the Caption. Click OK.

    3. Use the mouse to pull on the right handle of the label control to adjust the width to accommodate the length of the caption.

    4. Pick and click the text box control to add it from the Toolbox to the form region as shown in Figure 9.

    5. Right-click the text box control, click Properties. On the Value tab, click Choose Field. Point to User-defined field in folder in the drop-down list, and click Frequent Flyer Number, as in Figure 9. Then click OK.

      Figure 9. Bind the Frequent Flyer Number field to the text box control.

  11. Add a check box control and bind the Vegetarian field to the check box control.

    1. Pick and click the check box control to add it from the Toolbox to the form region as shown in Figure 10.

    2. Right-click the check box control, click Properties. On the Display tab, type Vegetarian? as the Caption, as in Figure 10.

      Figure 10. Specify a caption for the check box control.

    3. Click the Value tab, click Choose Field. Point to User-defined field in folder in the drop-down list, and click Vegetarian, as in Figure 11. Then click OK.

      Figure 11. Bind the Vegetarian field to the check box control.

  12. Add a label control and a combo box control, and bind the Seat Preference field to the combo box control.

    1. Pick and click the label control to add it from the Toolbox to the form region as shown in Figure 12.

    2. Right-click the label control, click Properties. On the Display tab, type Seat Preference: as the Caption. Click OK.

    3. Pick and click the combo box control to add it from the Toolbox to the form region as shown in Figure 12.

    4. Right-click the combo box control, click Properties. On the Value tab, click Choose Field. Point to User-defined field in folder in the drop-down list, and click Seat Preference, as in Figure 12.

      Figure 12. Bind the Seat Preference field to the combo box control.

    5. To define values for the drop-down list, type Aisle,Center,Window as the Possible Values.

    6. Check Set the initial value of this field to:, and type Aisle in the next text box as the initial display value. Then click OK.

  13. Align controls on the form region.

    1. Hold down SHIFT, select the three label controls for Contoso Airlines, Frequent Flyer Number, and Seat Preference:.

    2. Right-click, point to Align, and select Align Left. This will align the selected controls by their left edges.

    3. Hold down SHIFT, select the text box control and the combo box control.

    4. Right-click, point to Align, and select Align Left.

    5. Hold down SHIFT, select the label control for Frequent Flyer Number, the text box control, and the check box control.

    6. Right-click, point to Align, and select Align Bottom. This will align the selected controls by their bottom edges.

    7. Hold down SHIFT, select the label control for Seat Preference: and the combo box control.

    8. Right-click, point to Align, and select Align Bottom.

  14. Click Form Region, and click Save Form Region. Create a folder Form Regions in the c: drive, type Contoso as the file name, and click Save.

  15. When Outlook asks Do you want to save changes, click No.

Create the Form Region Manifest XML File

Use an XML editor such as Notepad to create a form region manifest XML file, Contoso.xml, in the folder c:\Form Regions. Type the following lines:

Visual Basic - C# Copy code Copy code
<?xml version="1.0"?>
<FormRegion xmlns="http://schemas.microsoft.com/office/outlook/12/formregion.xsd">
    <!-- Internal name -->
    <name>ContosoAdjoining</name>
    <!-- Display name -->
    <title>Contoso Airlines</title>
    <!--  Additive adjoining form region -->
    <formRegionType>adjoining</formRegionType>
    <!--  Outlook form region file is in the current folder relative to the location of contoso.xml -->
    <layoutFile>Contoso.ofs</layoutFile>
    <!-- Display form region when inspector is in the Reading Pane -->
    <showPreview>true</showPreview>
    <!-- Version of form region -->
    <version>1.0</version>
</FormRegion>

Register the Form Region

To run the form region, you must register it in the Windows registry, specifying the message class and other necessary information required for Outlook to display the form region. You will register this form region to display contact items, under the current user key, HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions\IPM.Contact.

  1. Close Outlook.

  2. Add the following key to the registry if it does not already exist: HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions.

  3. Under the FormRegions key, add the key IPM.Contact, if it does not already exist.

  4. For the key IPM.Contact, add a value of the type String, specifying ContosoAdjoining as the name, and c:\Form Regions\contoso.xml as the data.

  5. Close the registry.

Use the Form Region

  1. Start Outlook.

  2. Open a contact item.

You will see the form region Contoso Airlines at the bottom of the General page of the Contact form, as in Figure 1.


Specifying Form Regions in the Windows Registry

 Copy code hover
[image]

Specifying Form Regions in the Windows Registry
Send feedback

To run a form that contains a form region on a client computer, you must register the form region in the Windows registry, specifying the message class and other information necessary for Microsoft Outlook to display the form region. This information includes the display name, where the form region appears in a form, any layout file or add-in that implements the form region, any supported user actions, and any localized terms for the user interface. The structure of this information follows a form region XML schema; for more information on the XML schema for form regions, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

There are a few ways to specify this information about the form region in the registry. You can explicitly specify the XML, or a full path to an XML file, that contains this information for the form region and that conforms to the form region XML schema. You can also choose to specify the ProgID of an add-in which will provide Outlook the XML manifest for the form region. When Outlook starts, it reads the list of form regions from the registry and caches the associated data.

Caution note Caution

Incorrectly editing the Windows registry may severely damage your system. Before making changes to the registry, you should back up any valued data on the computer.

Registering a Form Region

Register form regions under the FormRegions key in the Windows registry, under the local machine key (as HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions) or under the current user key (as HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions). Under the FormRegions key, create a separate key for each message class for which form regions have been created. For example, the mail item has the message class IPM.Note; you can register all form regions used to display the mail item for the current user under the key, HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions\IPM.Note.

The following steps show how to register a form region under the local machine:

  1. Close Outlook.

  2. Add the following key to the registry if it does not already exist: HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions.

  3. Under the FormRegions key, add a key with the name of the message class that the form region is associated with, if that key does not already exist. For example, to create a form region for the contact item, add a key with the name IPM.Contact, if it does not already exist.

  4. For that key, add a value of the type REG_SZ, and specify the name to be the same as the name element of the form region. This is the internal name for the form region; the internal name supports only ASCII characters. Specify the data as one of the following possible values:

    • Explicitly the XML that specifies the layout, behavior, and other characteristics for the form region, and that conforms to the form region XML schema. In this case, you must precede the data with a less than sign (<).

    • The ProgID of an add-in that will provide Outlook the XML manifest for the form region. In this case, you must precede the data with an equal sign (=). For example, if the ProgID of an add-in is MyAddinProject1.ConnectClass, you would specify the data of the key to be =MyAddinProject1.ConnectClass.

    • The full local file path name to a form region XML manifest file that describes the layout, behavior, and other characteristics of the form region. If the data does not precede with a less than sign (<) or an equal sign (=), then Outlook will assume the data is a path name to the form regions XML manifest file. For example, if your form region XML manifest file, map.xml, is at c:\Form Regions\, you would specify the data of the key to be c:\Form Regions\map.xml.

Specifying Form Regions as Replacements for Standard Forms

Outlook allows you to customize the standard form for each of the Outlook message classes by adding adjoining form regions or separate form regions to the form. The following table shows the standard forms and corresponding message classes in Outlook.

Standard Form | Message Class
Appointment | IPM.Appointment
Contact | IPM.Contact
Journal Entry | IPM.Activity
Meeting Request | IPM.Meeting.Schedule.Request
Message | IPM.Note
Post | IPM.Post
Task | IPM.Request
Task Request | IPM.Task
Note Note

You cannot specify form regions for the root Outlook message class, IPM.

You can add separate form regions as extra pages to a standard form, but you cannot replace any existing pages on the standard form and keep the form for the same Outlook message class. If you need to replace the default page or all pages of a standard form, you will have to derive a new message class for that form, specify a replacement form region to replace the default page or a replace-all form region to replace the entire form, and register that form region for the derived message class.

For example, you can create a replacement form region that replaces the General page of the Contact form, and register that form region for a message class derived from IPM.Contact, such as IPM.Contact.MyContact. You cannot register the form region for the IPM.Contact message class.

When Outlook opens an item and sees a derived message class (for example, IPM.Contact.MyContact.Personal.Family), it looks for a replacement or replace-all form region (that is, a form region that has a formRegionType element being equal to replace or replaceAll), and that matches exactly the derived message class, IPM.Contact.MyContact.Personal.Family. If there is no exact match, Outlook will try IPM.Contact.MyContact.Personal, and if that fails, Outlook will try IPM.Contact.MyContact. Note that Outlook ignores any replacement or replace-all form regions for IPM.Contact. If there is not yet an exact match, Outlook will look for any form region with formRegionType equal to adjoining or separate for the derived class, IPM.Contact.MyContact.Personal.Family.

Multiple Form Regions for the Same Message Class

When one or more add-ins registers multiple form regions for the same message class, the display order of adjoining form regions on the default page and the order of separate form regions in the form depends on the order that the add-ins are installed and the order that the add-ins register the form regions. If an add-in specifies more than one adjoining form region or more than one separate form region for a message class, the add-in can use the displayAfter element to specify the order of these form regions. The order specified by displayAfter takes precedence over the order of the form regions in the registry. This is the only means add-ins can specify the order of form regions in a form.

After the form regions are installed on a client computer, form users can further customize the order of adjoining form regions by opening the form and moving the form regions up or down on the default page through the form region header context menu.

Example

The following is an example of the XML for a form region for a derived message class, IPM.Contact.MapUser. The form region is applied to all users on a computer. The XML file, map.xml, is located in c:\Form Regions.

To register the form region, create the following key in the Windows registry:

Key | HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions\IPM.Contact.MapUser
Name | MapTab
Type | REG_SZ
Data | c:\Form Regions\map.xml

The following lists the content of map.xml:

Copy code Copy code
<?xml version="1.0"?>
<FormRegion xmlns="http://schemas.microsoft.com/office/outlook/12/formregion.xsd">
    <!-- Internal name -->
    <name>MapTab</name>
    <!-- Display name -->
    <title>Directions</title>
    <!--  Additive separate form region -->
    <formRegionType>separate</formRegionType>
    <!--  Layout file -->
    <layoutFile>Map.ofs</layoutFile>
    <!-- Icon for form region in all contexts -->
    <icons>
        <default>generic.ico</default>
    </icons>
</FormRegion>

The form region is added to the form as a page following the last non-hidden built-in page in the Contact form (normally, this would follow the All Fields page). The page is titled Directions and has an internal programmatic name "MapTab". Map.xml specifies a layout file and an icon file. Note that all file paths in the xml file can be specified as full file paths, or paths relative to the location of the form region XML manifest file.


Designing Form Regions with the Form Region XML Schema

 Copy code hover
[image]

Designing Form Regions with the Form Region XML Schema
Send feedback

In this section

  • Using the Form Region XML Manifest to Define a Form Region

  • How to: Name a Form Region

  • How to: Specify the Location of a Form Region in a Custom Form

  • How to: Specify a Layout File for a Form Region

  • How to: Prevent the Inspector from Displaying a Form Region When You are Composing a Message

  • How to: Prevent the Inspector from Displaying a Form Region When You are Reading a Message

  • How to: Prevent the Reading Pane from Displaying a Form Region When You are Previewing a Message

  • How to: Prevent a Replacement Form Region from Being Used to Create a New Item or from Being Modified in the Forms Designer

  • How to: Specify a Form Region to be Used Only for the Exact Message Class

  • How to: Specify Locale-Specific User Interface for a Form Region

  • Defining Actions for Form Regions


Using the Form Region XML Manifest to Define a Form Region

 Copy code hover
[image]

Using the Form Region XML Manifest to Define a Form Region
Send feedback

To run a form region, you must register it in the Windows registry and specify the message class and other necessary information that Microsoft Outlook needs to display the form region. The form region XML schema allows you to specify information related to the functionality, behavior, and other innate properties of the form region. Typically, you would specify XML that follows this schema in a form region manifest XML file, and then register this file in the Windows registry so as to use the form region to display items of the corresponding message class.

For example, if you are designing a form region for items of the message class IPM.Contact, you can specify a form region manifest XML file, contoso.xml, that defines characteristics of the form region. When you register the form region in the Windows registry, under the current user key, you can add the key IPM.Contact, add a value of the type String, and specify the name of the form region, ContosoAdjoining, as the name of the key, and the form region manifest XML file, c:\Form Regions\contoso.xml, as the data of the key. For more information, see Specifying Form Regions in the Windows Registry.

You can specify the functionality, behavior, and other innate properties of a form region through elements in the form region XML schema. Some of the more commonly used elements are listed as follows. For more information on the form region XML schema, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

Schema Elements | Purpose | Further Information
name, title, formRegionName | Identify a form region internally and in the user interface. | How-to: Name a Form Region
formRegionType | Specify a form region to occupy part of a page or an entire page of a form. | How to: Specify the Location of a Form Region in a Custom Form
displayAfter | Order multiple form regions in a custom form. | How to: Specify the Location of a Form Region in a Custom Form
layoutFile | Specify a layout file for a form region. | How to: Specify a Layout File for a Form Region
showInspectorCompose | Prevent the inspector from displaying a form region when you are composing a message. | How to: Prevent the Inspector from Displaying a Form Region When You are Composing a Message
showInspectorRead | Prevent the inspector from displaying a form region when you are reading a message. | How to: Prevent the Inspector from Displaying a Form Region When You are Reading a Message
showReadingPane | Prevent the Reading Pane from displaying a form region when you are previewing a message. | How to: Prevent the Reading Pane from Displaying a Form Region When You are Previewing a Message
hidden | Prevent a form region from being modified in the Forms Designer. | How to: Prevent a Replacement Form Region from Being Used to Create a New Item or from Being Modified in the Forms Designer
exactMessageClass | Specify a form region is to be used only for items that have exactly the same message class as the form region. | How to: Specify a Form Region to be Used Only for the Exact Message Class
action and its child elements | Modify a standard action that is available to a form region. | How to: Modify a Built-in Action for a Form Region
action and its child elements | Create a custom action for a form region. | How to: Create a Custom Action for a Form Region
icons and its child elements | Specify custom icons for a form region. | How to: Specify Icons to be Displayed for a Form Region
stringOverride and its child elements | Specify locale-specific strings in the user interface of a form region. | How to: Specify Locale-Specific User Interface for a Form Region


How to: Name a Form Region

 Copy code hover
[image]

How to: Name a Form Region
Send feedback

Depending on the purpose, there are multiple ways you can provide identifiers for a form region. Only one of these identifiers is mandatory, which is the name that you associate with the form region manifest XML file when you register the form region in the Windows registry. You can optionally specify the other identifiers through the name, title, and formRegionName elements of the form region XML schema.

To provide an identifier in the Windows registry

  1. In the Windows registry, under the current user key, create a key for the message class that the form region is created for, if the key does not already exist.

  2. Add a value of the type String.

  3. Specify an identifier for the form region as the name of the key.

  4. Specify the full path name of the form region manifest XML file as the data of the key.

For more information, see Specifying Form Regions in the Windows Registry.

Optional: To provide an internal identifier using the name element

  • In the form region manifest XML file, specify a string identifier for the form region as a value of the name element. The value of the name element is an internal name used by Outlook and any form region add-in to identify this form region. The following example specifies TestFormRegion as the internal identifier of a form region:<name>TestFormRegion</name> If the name element is not specified in the form region manifest XML file, then the identifier specified in the Windows registry will be used as the internal name.

Optional: To provide a display name using the title element

  • In the form region manifest XML file, specify a string identifier for the form region as a value of the title element. The value of the title element is the display name of the form region in the default locale. If the form region is a replacement or replace-all form region, the value of title is used in the Actions menu and the Choose Form dialog box. This value can be overridden with a locale-specific value according to the regional settings and any form region localization manifest. The following example specifies Sample Form Region as the display name of a form region:<title>Sample Form Region</title> In general, the value for the title element is optional. If the title element is not specified in the form region manifest XML file, then the value for formRegionName, if it is defined, will be used as the display name. If no value for formRegionName has been specified, then the internal name will be used. The exception is for a replacement or replace-all form region that has the hidden attribute being false. In this case, if the title element is not set, the form region will not be displayed in the Actions menu, Choose Form dialog, and Design Form dialog.

Optional: To provide a form region identifier using the formRegionName element

  • In the form region manifest XML file, specify a string identifier for the form region as a value of the formRegionName element. The value of the formRegionName element identifies the form region in the Show group of the ribbon in the default locale. If the form region is an adjoining form region, the value is also used in the header that separates the beginning of an adjoining form region from the preceding portion of the form. This value can be overridden with a locale-specific value according to the regional settings and any form region localization manifest. The following example specifies Additional Information as the form region identifier of a separate form region:<formRegionName>Additional Information</formRegionName> If the formRegionName element is not specified in the form region manifest XML file, then the value for title, if it is defined, will be used. If no value has been specified for title, then the internal name will be used.


How to: Specify the Location of a Form Region in a Custom Form

 Copy code hover
[image]

How to: Specify the Location of a Form Region in a Custom Form
Send feedback

A form region is a piece of custom user interface that you add to a form. You can designate the form region to be displayed in one of several ways in a custom form. To do so, you will be specifying the formRegionType and displayAfter elements of the form region XML schema in the corresponding form region manifest XML file.

On the Default Page

There are several ways you can display a form region or form regions on the default page of a standard form.

To add a form region to the default page

  • In the form region manifest XML file, specify adjoining as the value of the formRegionType element.

The form region will be added to the bottom of the default page of the original standard form, and will be displayed in an Inspector or the Reading Pane.

For example, to add a form region to the bottom of the default page of the standard Message form, you can specify the following in the form region manifest XML file of the form region:

Copy code Copy code
<formRegionType>adjoining</formRegionType>

You can use the resulting custom form to display items of the same message class as the original standard form, or you can assign a derived message class for the custom form and use the custom form to display only items of the derived message class.

To add multiple form regions to the default page

  1. For each form region, in the corresponding form region manifest XML file, specify adjoining as the value of the formRegionType element.

  2. Except for the form region that will appear as the first form region on the default page, for each of the other form regions, in the corresponding form region manifest XML file, specify the internal name of the form region that will precede this one as the value of the displayAfter element.

You can use the resulting custom form to display items of the same message class as the original standard form, or you can assign a derived message class for the custom form and use the custom form to display only items of the derived message class.

The first form region will be added to the bottom of the default page of the original standard form, and will be appended by the other form regions in the order that you have specified in the corresponding displayAfter element.

For example, if you want to order three form regions, A, B, and C, that have the internal names FormRegionA, FormRegionB, and FormRegionC to be displayed in the order A, B, and C, you will specify the following in A's form region manifest XML file:

Copy code Copy code
<formRegionType>adjoining</formRegionType>

You will specify the following in B's form region manifest XML file:

Copy code Copy code
<formRegionType>adjoining</formRegionType>
<displayAfter>FormRegionA</displayAfter>

You will specify the following in C's form region manifest XML file:

Copy code Copy code
<formRegionType>adjoining</formRegionType>
<displayAfter>FormRegionB</displayAfter>
Note Note

You can use the displayAfter element to specify the order of multiple adjoining form regions in a custom form. However, this order is only valid the first time that the form is displayed for the user on the local computer. The user has the option to change the order of adjoining form regions by opening the form and moving the form regions up or down on the default page through the form region header context menu. Outlook caches the updated order and uses the cached order on subsequent displays of the form.

To "replace" the entire default page by a form region

  1. In the form region manifest XML file, specify replace as the value of the formRegionType element.

  2. When you register the form region in the Windows registry, under the local machine key (as HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions) or the current user key (as HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions), create a separate key for the derived message class for this form region. Add a value of the type REG_SZ, specifying the internal name of the form region as the name of the key, and the full local file path name to the form region manifest XML file as the data of the key.

When you are "replacing" the default page of a standard form, you are in reality using the standard form as a template and creating a new custom form that has your form region as the default page. If the original standard form contains other form pages or separate form regions, they will remain as part of the custom form.

You must assign a derived message class to the resulting custom form and use the form to display items of that message class.

For example, you have created a form region that has the internal name CustomPage and form region manifest XML file CustomPage.xml in c:\Form Regions\. To use the form region to replace the default page of the standard Message form, you can specify the following in the form region manifest XML file of CustomPage:

Copy code Copy code
<formRegionType>replace</formRegionType>

When you register this form region in the Windows registry, you must not specify the message class of the original standard form, IPM.Note, but specify a derived message class, such as IPM.Note.CustomPage. For this example, you will register the form region under the current user key, HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions, by creating a key IPM.Note.CustomPage. You will then add a value of the type REG_SZ, specifying the internal name, CustomPage, of the form region as the name of the key, and the full local file path name to the form region manifest XML file, c:\Form Regions\CustomPage.xml, as the data of the key.

To "replace" the entire standard form by a form region

  1. In the form region manifest XML file, specify replaceall as the value of the formRegionType element.

  2. When you register the form region in the Windows registry, under the local machine key (as HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions) or the current user key (as HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions), create a separate key for the derived message class for this form region. Add a value of the type REG_SZ, specifying the internal name of the form region as the name of the key, and the full local file path name to the form region manifest XML file as the data of the key.

When you are "replacing" the entire standard form with a form region, you are in reality using the standard form as a template and creating a new custom form that has the form region as the default page. If the original standard form contains other form pages or separate form regions, they will not remain as part of the custom form.

You must assign a derived message class to the resulting custom form and use the form to display items of that message class.

For example, you have created a form region that has the internal name CustomMessage and form region manifest XML file CustomMessage.xml in c:\Form Regions\. To use the standard Message form as the template for a new custom form that will contain CustomMessage as the default page, you can specify the following in the form region manifest XML file of CustomMessage:

Copy code Copy code
<formRegionType>replaceall</formRegionType>

When you register this form region in the Windows registry, you will specify a derived message class, such as IPM.Note.CustomMessage. For this example, you will register the form region under the current user key, HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions, by creating a key IPM.Note.CustomMessage. You will then add a value of the type REG_SZ, specifying the internal name, CustomMessage, of the form region as the name of the key, and the full local file path name to the form region manifest XML file, c:\Form Regions\CustomMessage.xml, as the data of the key.

On Pages Other than the Default Page

You can add one or more form regions as separate pages to a standard form.

To add a form region as a separate page

  • In the form region manifest XML file, specify separate as the value of the formRegionType element.

The form region will be added as a separate page following all the existing pages of the original standard form, and will be displayed as a standalone page in an Inspector.

For example, to add a form region as a separate page to the standard Contact form, you can specify the following in the form region manifest XML file of the form region:

Copy code Copy code
<formRegionType>separate</formRegionType>

The form region will be displayed as a separate page following the All Fields page of the standard Contact form.

You can use the resulting custom form to display items of the same message class as the original standard form, or you can assign a derived message class for the custom form and use the custom form to display only items of the derived message class.

To add multiple form regions as separate pages

  1. For each form region, in the corresponding form region manifest XML file, specify separate as the value of the formRegionType element.

  2. Except for the form region that will appear as the first form region in the custom form, for each of the other form regions, in the corresponding form region manifest XML file, specify the internal name of the form region that will precede this one as the value of the displayAfter element.

You can use the resulting custom form to display items of the same message class as the original standard form, or you can assign a derived message class for the custom form and use the custom form to display only items of the derived message class.

The first form region will be added as a separate page of the original standard form, and will be appended by the other form regions in the order that you have specified in the corresponding displayAfter element.

For example, if you want to order three separate form regions, A, B, and C, that have the internal names FormRegionA, FormRegionB, and FormRegionC to be displayed as separate pages in the order A, B, and C, you will specify the following in A's form region manifest XML file:

Copy code Copy code
<formRegionType>separate</formRegionType>

You will specify the following in B's form region manifest XML file:

Copy code Copy code
<formRegionType>separate</formRegionType>
<displayAfter>FormRegionA</displayAfter>

You will specify the following in C's form region manifest XML file:

Copy code Copy code
<formRegionType>separate</formRegionType>
<displayAfter>FormRegionB</displayAfter>


How to: Specify a Layout File for a Form Region

 Copy code hover
[image]

How to: Specify a Layout File for a Form Region
Send feedback

You can design and deploy a form region with or without an add-in.

When you design a form region without an add-in, you create the form region in the Forms Designer and save the form region in an Outlook Form Storage file (.OFS). For more information on creating a form region, see How to: Create a Form Region.

To run the form region, you must register it in the Windows registry and specify the message class and the corresponding form region manifest XML file.

To specify a file as the layout file for a form region

  • In the form region manifest XML file, specify the file name of the .OFS file as the value of the layoutFile element.

If you do not specify a full path name for the .OFS file, then Outlook will look for the file in the same folder as the form region manifest XML file that you have specified in the Windows registry for the form region. Otherwise, you can use environment variables in the layoutFile element, such as the following:

Copy code Copy code
<layoutFile>%ProgramFiles%\Addin\Addin.ofs</layoutFile>

You cannot use file paths expressed in the Universal Naming Convention (UNC) for the layoutFile element.

If you use an add-in to design and deploy a form region, then you must specify the addin element and must not specify the layout element.


How to: Prevent the Inspector from Displaying a Form Region When You are Composing a Message

 Copy code hover
[image]

How to: Prevent the Inspector from Displaying a Form Region When You are Composing a Message
Send feedback

When you create a form region in a custom form, by default, the form region will be displayed in the inspector when you compose a message that uses that custom form. If you want to prevent the inspector from displaying the form region, specify this in the form region manifest XML file that you register for the form region. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

To prevent the inspector from displaying a form region while in compose mode

  • In the form region manifest XML file, specify false as the value of the showInspectorCompose element.

The following example disables the inspector from displaying a form region when in compose mode:

Copy code Copy code
<showInspectorCompose>false</showInspectorCompose>
Note Note

You can assign showInspectorCompose either a string value or an integer value. The default value is true or 1. To prevent the inspector from displaying the form region in compose mode, assign either false or 0.


How to: Prevent the Inspector from Displaying a Form Region When You are Reading a Message

 Copy code hover
[image]

How to: Prevent the Inspector from Displaying a Form Region When You are Reading a Message
Send feedback

When you create a form region in a custom form for mail or post items, by default, the form region will be displayed in the inspector when you read a mail or post item that uses that custom form. If you want to prevent the inspector from displaying the form region, specify this in the form region manifest XML file that you register for the form region. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

To prevent the inspector from displaying a form region while in read mode

  • In the form region manifest XML file, specify false as the value of the showInspectorRead element.

The following example disables the inspector from displaying a form region when in read mode:

Copy code Copy code
<showInspectorRead>false</showInspectorRead>
Note Note

You can assign showInspectorRead either a string value or an integer value. The default value is true or 1. To prevent the inspector from displaying the form region in read mode, assign either false or 0.


How to: Prevent the Reading Pane from Displaying a Form Region When You are Previewing a Message

 Copy code hover
[image]

How to: Prevent the Reading Pane from Displaying a Form Region When You are Previewing a Message
Send feedback

When you create a form region in a custom form, by default, the form region will be displayed in the Reading Pane when you preview a message that uses that custom form. If you want to prevent the Reading Pane from displaying the form region, specify this in the form region manifest XML file that you register for the form region. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

To prevent the Reading Pane from displaying a form region

  • In the form region manifest XML file, specify false as the value of the showReadingPane element.

The following example disables the Reading Pane from displaying a form region:

Copy code Copy code
<showReadingPane>false</showReadingPane>
Note Note

You can assign showReadingPane either a string value or an integer value. The default value is true or 1. To prevent the Reading Pane from displaying the form region, assign either false or 0.


How to: Prevent a Replacement Form Region from Being Used to Create a New Item or from Being Modified in the Forms Designer

 Copy code hover
[image]

How to: Prevent a Replacement Form Region from Being Used to Create a New Item or from Being Modified in the Forms Designer
Send feedback

Through the Actions menu or the Choose Form dialog, you can select a replacement or replace-all form region in the current folder to create a new item. Through the drop down list of the Design Form dialog, you can also select a replacement or replace-all form region and modify it in the Forms Designer. If you want to prevent a replacement or replace-all form region from being displayed in the above dialog boxes and menu, specify so in the form region manifest XML file that you register for the form region. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

To prevent a form region from being modified in the Forms Designer

  • In the form region manifest XML file, specify false as the value of the hidden element.

The following example disables a replacement form region from being used to create a new item or from being modified in the Forms Designer:

Copy code Copy code
<hidden>false</hidden>
Note Note

You can assign either a string value or an integer value to hidden. The default value is false or 0. To prevent a form region from being used to create a new item or from being modified in the Forms Designer, assign either true or 1.


How to: Specify a Form Region to be Used Only for the Exact Message Class

 Copy code hover
[image]

How to: Specify a Form Region to be Used Only for the Exact Message Class
Send feedback

When you register a form region for a message class, by default, the inspector displays the form region for any item belonging to that message class, as well as any item that belongs to a derived message class. For example, if you create a form region and register it for IPM.Appointment, the inspector will display that form region for any item that belongs to IPM.Appointment, and any item that belongs to a message class derived from IPM.Appointment, such as IPM.Appointment.Customers. If you want the inspector to use the form region for only the exact message class that the form region is registered for, specify this in the form region manifest XML file for the form region. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

To allow a form region to be used for only the exact message class

  • In the form region manifest XML file, specify true as the value of the exactMessageClass element.

The following example disables a form region from being modified in the Forms Designer:

Copy code Copy code
<exactMessageClass>true</exactMessageClass>
Note Note

You can assign exactMessageClass either a string value or an integer value. The default value is false or 0. To allow a form region to be used for only the exact message class, assign either true or 1.


How to: Specify Locale-Specific User Interface for a Form Region

 Copy code hover
[image]

How to: Specify Locale-Specific User Interface for a Form Region
Send feedback

You can specify localized versions of certain pieces of user interface in a form region. For example, you can specify an English version of the form region display name and a Spanish version of the display name.

To support localized user interface for the same locale, specify the locale and the localized user interface under the stringOverride element in the form region manifest XML file. In general, if there is one or more locales that share the same localization strings, you can specify their locales and localized user interface under the same stringOverride element.

Under the stringOverride element, you can specify the localization information in one of two ways: you can either specify it as values of child elements, or specify a localization file that contains the localization information. You will specify the stringOverride element in the form region manifest XML file that you will use when you register the form region in the Windows registry. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

The following table shows the pieces of user interface in a form region that you can localize. If you choose to specify the localization information inline, you can use the corresponding XML child elements under the stringOverride element.

Localizeable User Interface | XML Child Elements
Display name of the form region | title
Form region identifier | formRegionName
Description of the form region | description
Display name of a control in the form region | control
Display name and subject prefix of an action defined for the form region | action

If you choose to provide a localization file, you will specify it as the value of the file attribute of the stringOverride element.

Localization files follow an XML schema consisting of elements similar to the child elements of the stringOverride element in the form region XML schema. For more information on the localization XML schema, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

To specify the locale

  • In the form region manifest XML file, specify the Locale ID (LCID) of the locale as the value of the language attribute of the stringOverride element.

    If there are multiple locales sharing the same localized user interface, specify the LCID of all these locales, separating them with semicolons, as the combined value of the language attribute of a single stringOverride element. Specify only one stringOverride element in a form region manifest XML file for each unique value (or combined value) of the language attribute.

    You can also specify all as the value of the language attribute to specify that the user interface specified in that stringOverride element applies to all locales.

    The following example lists the locale IDs for Spanish-Spain and French-France as the two locales under the same stringOverride element:

    Copy code Copy code
    <stringOverride language="1034;1036">
    <!-- specify localization strings here -->
</stringOverride>

Optional: To specify a localization file

  • In the form region manifest XML file, specify the path to a file that contains the localized strings for the specified locale as the value of the file attribute of the stringOverride element.

    The path to the localization file can be a full path or a path relative to the location of the form region manifest XML file that you specify when you register the form region.

    When specifying the location of the localization file, you can use the system variable %langid% as a placeholder for the LCID of the current stringOverride element. For example:

    Copy code Copy code
    <stringOverride language="1034" file="%langid%\UserStrings.xml" />
    <!-- no need to specify localization strings here -->
    Note Note

    If a file is specified for the file attribute of the stringOverride element, Outlook will ignore all child elements of the stringOverride element.

Optional: To specify a localization string for the display name of the form region

  • In the form region manifest XML file, under the stringOverride element, specify a string identifier for the form region as a value of the title child element.

    The value of the title element is the display name of the form region for the specified locale or locales. If the form region is a replacement or replace-all form region, the value of title is displayed in the Actions menu and the Choose Form dialog box.

    The following example specifies a display name for a form region localized for the English-Canada locale.

    Copy code Copy code
    <stringOverride language="4105">
    <title>Template for Canadians</title>
</stringOverride>

Optional: To specify a localization string for the form region identifier

  • In the form region manifest XML file, under the stringOverride element, specify a string identifier for the form region as a value of the formRegionName child element.

    The value of the formRegionName element identifies the form region in the Show tab of the ribbon for the specified locale or locales. If the form region is an adjoining form region, the value is also used in the header that separates the beginning of an adjoining form region from the preceding portion of the form.

    The following example specifies Addendum as the form region identifier of an adjoining form region localized for the English-Canada locale:

    Copy code Copy code
    <stringOverride language="4105">
    <formRegionName>Addendum</formRegionName>
</stringOverride>

Optional: To specify a localization string for the description of the form region

  • In the form region manifest XML file, under the stringOverride element, specify a string identifier for the form region as a value of the description child element.

    The value of the description element is a text description of the form region for the specified locale or locales. If the form region is a replacement or replace-all form region, the value of description is displayed in the Choose Form dialog box.

    The following example specifies a description for a form region localized for the English-Canada locale:

    Copy code Copy code
    <stringOverride language="4105">
    <description>This template is intended for English speaking Canadians.</description>
</stringOverride>

Optional: To specify a localization string for the display name of a control in the form region

  1. In the form region manifest XML file, under the stringOverride element, specify the value of the name property as the value of the name attribute of the control child element.

    The value of the name property is accessible from the user interface when you right-click the control in the Forms Designer and select Properties. For example, the default name for an Outlook Text Box control is TextBox1.

  2. Under the control element, specify a localized string for the caption child element.

    The value of the caption element is the display name of the control localized for the specified locale or locales.

    The following example specifies a localized name for an Outlook Text Box control for the English-Canada locale:

    Copy code Copy code
    <stringOverride language="4105">
    <control name="TextBox1">
        <caption>Canadian postal code</caption>
    </control>
</stringOverride>

Optional: To specify a localization string for the display name of an action

  1. In the form region manifest XML file, under the stringOverride element, specify the internal name of the action as the value of the name attribute of the action child element.

  2. Under the action element, specify a localized string for the display name of the action as the value of the title child element.

    The value of the title element is localized for the specified locale or locales.

    The following example specifies a localized display name for a custom action for the English-Canada locale:

    Copy code Copy code
    <stringOverride language="4105">
    <action name="replyToBlog">
        <title>Reply to Blog</title>
    </action>
</stringOverride>

Optional: To specify a localization string for the subject prefix of an item resulting from an action

  1. In the form region manifest XML file, under the stringOverride element, specify the internal name of the action as the value of the name attribute of the action child element.

  2. Under the action element, specify a localized string for the subject prefix as the value of the subject child element.

    The value of the subject element is the prefix for the subject field of an item that results from the action, and is localized for the specified locale or locales.

    The following example specifies a localized subject prefix for a custom action for the English-Canada locale:

    Copy code Copy code
    <stringOverride language="4105">
    <action name="replyToBlog">
        <subject>Re</subject>
    </action>
</stringOverride>


Defining Actions for Form Regions

 Copy code hover
[image]

Defining Actions for Form Regions
Send feedback

In this section

  • How to: Modify a Built-in Action for a Form Region

  • How to: Create a Custom Action for a Form Region

  • How to: Specify the Message Class and Form for an Item Resulting from an Action

  • How to: Include the Original Body in an Item Resulting from an Action

  • How to: Specify the Way Outlook Responds When Executing an Action

  • How to: Specify a Subject Prefix of an Item Resulting from an Action


How to: Modify a Built-in Action for a Form Region

 Copy code hover
[image]

How to: Modify a Built-in Action for a Form Region
Send feedback

By default, there are four built-in actions available to a form region: reply, reply-all, reply-to-folder, and forward. You can modify a built-in action in the following ways, by making the specifications in the form region manifest XML file that you register for the form region:

  • The message class of the item that results from executing the action.

  • The way that the body of the current item is included in the resulting item.

  • The way that Outlook responds when executing the action.

  • The prefix value in the subject of the resulting item.

  • Disabling the built-in action for the form region.

For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

If customizing a built-in action in the above ways does not suit your needs, then you should consider creating a new custom action. For more information, see How to: Create a Custom Action for a Form Region

Identifying Actions for a Form Region

Whether you choose to modify a built-in action or create a custom action, you define the action in the form region manifest XML file. Define these actions under the customActions element, enclosing each action in its own action element and identifying it by the mandatory name attribute. The value of the name attribute is a string that represents the internal name of the action.

To specify the internal name of a built-in action

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the built-in action as the value of the name attribute of the action element.

The following example identifies the two built-in actions, reply and replyAll, before modifying them:

Copy code Copy code
<customActions>
    <action name="reply">
        <!-- further modify this action -->
    </action>
    <action name="replyAll">
        <!-- further modify this action -->
    </action>
</customActions>

Note that by default, there are four built-in actions for each form region. You can identify them with the following keywords:

Keyword | Built-in Action
forward | Forward current item.
reply | Reply to current item.
replyAll | Reply to all recipients of the current item.
replyToFolder | Post a reply to a folder.

Modifying a Built-in Action

After you have identified a built-in action in an action element, you can modify it by specifying optional child elements and attribute for the action element.

To specify the message class and the form for the resulting item

To specify the way that the body of the current item is included in the resulting item

To specify the way that Outlook responds when executing the action

To specify the prefix value in the subject of the resulting item

To disable the built-in action for the form region

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify true as the value of the disabled attribute of the action element.

The following example identifies the built-in action, replyToFolder, and disables it:

Copy code Copy code
<customActions>
    <action name="replyToFolder" disabled="true">
    </action>
</customActions>
Note Note

You can assign disabled either a string value or an integer value. The default value is false or 0. To disable a built-in action for a form region, assign disabled either true or 1.


How to: Create a Custom Action for a Form Region

 Copy code hover
[image]

How to: Create a Custom Action for a Form Region
Send feedback

You can specify custom actions for a form region. By default, four built-in actions exist for any form region. To create an action that suit your needs, you can either modify a built-in action or create a new custom action. For more information on modifying a built-in action, see How to: Modify a Built-in Action for a Form Region.

When you create a custom action, you can specify the following characteristics in the form region manifest XML file that you register for the form region:

  • The display name for the custom action.

  • Whether the custom action will be displayed on the ribbon of an inspector.

  • The way that the resulting item will be addressed.

  • The message class of the item that results from executing the action.

  • The way that the body of the current item is included in the resulting item.

  • The way that Outlook responds when executing the action.

  • The prefix value in the subject of the resulting item.

For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

Identifying Actions for a Form Region

Whether you choose to modify a built-in action or create a custom action, you define the action in the form region manifest XML file. Define these actions under the customActions element, enclosing each action in its own action element and identifying it by the mandatory name attribute. The value of the name attribute is a string that represents the internal name of the action.

To specify an internal name for an action

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

The following example assigns replyToBlog as the internal name of one custom action, and postToBlog as the internal name of another custom action:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <!-- further characterize this action -->
    </action>
    <action name="postToBlog">
        <!-- further characterize this action -->
    </action>
</customActions>

Defining a Custom Action

After you have identified an action in an action element, you can further define the action by specifying optional child elements for the action element.

To define a display name for the action

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify the display name of the action as the value of the child title element of the action element.

The following example assigns replyToBlog as the internal name of a custom action, and Reply to Blog as the display name of the action:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <title>Reply to Blog</title>
        <!-- Further characterize this action -->
    </action>
</customActions>

To specify that an action is to be displayed on the ribbon of an inspector

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify true as the value of the child showOnRibbon element of the action element.

The following example assigns replyToBlog as the internal name of a custom action and specifies that it should not be displayed in the ribbon of an inspector:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <showOnRibbon>false</showOnRibbon>
        <!-- Further characterize this action -->
    </action>
</customActions>
Note Note

You can assign showOnRibbon either a string value or an integer value. Specifying true or 1 will display the action on the ribbon; specifying false or 0 will prevent it from being displayed on the ribbon.

To specify the way that a resulting item will be addressed

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify a value for the child addressLike element of the action element.

The following example assigns replyToBlog as the internal name of a custom action and specifies that the resulting new item will be addressed as a reply-all item, with all the original recipients copied over to the new item:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <addressLike>replyAll</addressLike>
        <!-- Further characterize this action -->
    </action>
</customActions>
Note Note

The child addressLike element of the action element can contain one of the following values:

Value | Description
forward | Addresses the resulting item like a forward message that has no recipients specified. This also preserves attachments in the current item.
reply | Addresses the resulting item as a standard reply, with the sender specified in the To line, and no one in the CC or BCC lines.
replyAll | Addresses the resulting item like a reply-all message, with all of the original recipients copied over to the resulting item.
replyToFolder | Addresses the resulting item like a post message to the current folder. This also clears the subject of the resulting item.
response | Addresses the resulting item as a response to vote, with the sender specified in the To line, and no one in the CC or BCC lines.

To specify the message class and the form for the resulting item

To specify the way that the body of the current item is included in the resulting item

To specify the way that Outlook responds when executing the action

To specify the prefix value in the subject of the resulting item


How to: Specify the Message Class and Form for an Item Resulting from an Action

 Copy code hover
[image]

How to: Specify the Message Class and Form for an Item Resulting from an Action
Send feedback

To specify the message class and the form for the resulting item

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify a string that represents the message class of the resulting item as the value of the child targetForm element of the action element.

The following example assigns replyToBlog as the internal name of a custom action, and IPM.Post as the message class of the resulting item. The resulting item will use the same form that a contact item uses by default:

XML Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <targetForm>IPM.Post</targetForm>
        <!-- Further characterize this action -->
    </action>
</customActions>
Note Note

You can specify this as the value of the targetForm element to use the same message class and same form as those that the form region is defined on.


How to: Include the Original Body in an Item Resulting from an Action

 Copy code hover
[image]

How to: Include the Original Body in an Item Resulting from an Action
Send feedback

To specify the way that the body of the current item is included in the resulting item

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify a value for the child body element of the action element.

The following example assigns replyToBlog as the internal name of a custom action, and specifies that the body of the current item will be included and indented in the resulting item:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <body>indent</body>
        <!-- Further characterize this action -->
    </action>
</customActions>

Note that the child body element of the action element can contain one of the folowing values:

Value | Description
attach | The current item is attached to the resulting item.
include | The body of the current item is included as the body of the resulting item.
indent | The body of the current item is included in the body of the resulting item and indented.
link | A link to the current item is provided in the resulting item.
omit | The body of the current item is omitted from the resulting item.
prefix | The body of the current item is included in the body of the resulting item and prefixed with the quotation character.
user | The user's preferences are applied in how the body should be handled.


How to: Specify the Way Outlook Responds When Executing an Action

 Copy code hover
[image]

How to: Specify the Way Outlook Responds When Executing an Action
Send feedback

To specify the way that Outlook responds when executing an action

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify a value for the child method element of the action element.

The following example assigns replyToBlog as the internal name of a custom action, and specifies that Outlook will prompt the user to determine if he or she wants to open the resulting item now or send the item immediately:

XML Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <method>prompt</method>
        <!-- Further characterize this action -->
    </action>
</customActions>

Note that the child method element of the action element can contain one of the following values:

Value | Description
open | Outlook will open the resulting item in the inspector for the user to edit.
prompt | Outlook will prompt the user whether to open the resulting item now or send it immediately.
send | Outlook will send the resulting item automatically.


How to: Specify a Subject Prefix of an Item Resulting from an Action

 Copy code hover
[image]

How to: Specify a Subject Prefix of an Item Resulting from an Action
Send feedback

To specify the prefix value in the subject of the resulting item

  1. In the form region manifest XML file, specify the action as a child action element of the customActions element for that form region.

  2. Specify the internal name of the action as the value of the name attribute of the action element.

  3. Specify a string that represents the prefix of the subject line of the resulting item as the value of the child subjectPrefix element of the action element.

The following example assigns replyToBlog as the internal name of a custom action, and specifies Re as the subject line prefix for the resulting item:

Copy code Copy code
<customActions>
    <action name="replyToBlog">
        <subjectPrefix>Re</subjectPrefix>
        <!-- Further characterize this action -->
    </action>
</customActions>


Configuring Forms

 Copy code hover
[image]

Configuring Forms
Send feedback

In this section

  • How to: Change the Default Form for a Folder

  • How to: Hide or Show Form Pages

  • Creating a Reply Form

  • How to: Disable a Standard Reply Form

  • How to: Make Separate Compose and Read Versions for a Form

  • How to: Use Standard Reply and Forward Headers on a Form

  • How to: Add a Command to the Ribbon to Start a Reply Form

  • How to: Automatically Insert Prefix Text into the Subject Field of a Reply Form

  • How to: Pre-address a Reply Form to a Public Folder or an E-mail Address


How to: Change the Default Form for a Folder

 Copy code hover
[image]

How to: Change the Default Form for a Folder
Send feedback

You can change the default form for a particular public folder so that when a new item is created, it will use a custom form. This procedure requires Owner permissions on a public folder.

  1. If the Folder List is not visible, click the Folder List button at the bottom of the Navigation Pane.

  2. Right-click the public folder for which you want to specify the default form, and then click Properties.

  3. In the When posting to this folder, use box, click the form that you want others to use.

Note Note

To copy, install, delete, and update forms in this folder, click Manage on the Forms tab. You can also specify available forms in a public folder by selecting an option under the Allow these forms in this folder box.

If you are interested in this topic, you might also be interested in learning how to Change the Form for Existing Items in a Folder.


How to: Hide or Show Form Pages

 Copy code hover
[image]

How to: Hide or Show Form Pages
Send feedback

When you customize an Outlook form, the procedure that you use for form pages is different from the one that you use for form regions.

Forms customized with form regions

The GetFormRegionStorage method controls which form region is displayed on a form by calling the appropriate form regions storage file (.ofs). Form regions cannot be hidden or shown at run time once the form storage has been returned. For more information, see How to: Create a Form Region and Extending a Form Region with an Add-in.

Forms customized with form pages

  1. In the Forms Designer, click the page that you want to hide or show.

  2. On the Developer tab, in the Form group, click Page, and then click Display This Page.

Note Note

  • Parentheses around a page name indicate that the page is hidden. You cannot show the (Properties) or (Actions) pages.

  • If you drag a field or control to a hidden page, the page automatically shows.

  • To change what appears on the default or first page of an item, hide the first page, and then create a new version on one of the custom pages.

  • At least one page must be visible in a form.


Creating a Reply Form

 Copy code hover
[image]

Creating a Reply Form
Send feedback

When you create a message form, you often want users to send a reply by using a reply form.

An Action automatically opens a reply form, typically after a user clicks Reply, Forward, or another command on the form. For example, an Action can create a Forward button, that, when selected by the user, opens a forward form for the user to fill in and send. You can specify that the form use standard Reply and Forward headers, and you can even add prefix text, such as "RE:," to the Subject field of your custom reply form.

You can use the default reply forms included with Microsoft Outlook (these are the forms listed on the Actions page), or you can disable any of these forms and create a custom reply form. (For more information, see How to: Disable a Standard Reply Form?) The custom reply forms that you create are listed on the Actions page in design mode in the form.

You can create custom buttons and menu commands and specify what happens when the user selects them. You can also create a button or menu command that opens a task, a Calendar item, or even a note.

You can send information without opening a reply form by pre-addressing a custom reply form to go to a specific e-mail address or to a public folder.

For more information, see the following topics:

  • How to: Add a custom button or menu command to start a reply form

  • How to: Use standard Reply and Forward headers on a form

  • How to: Automatically insert text into the Subject field of a reply form

  • How to: Specify whether a form prompts the user, opens, or is sent

  • How to: Pre-address a reply form to a public folder or an e-mail address


How to: Disable a Standard Reply Form

 Copy code hover
[image]

How to: Disable a Standard Reply Form
Send feedback

Use this procedure to customize a form page in Microsoft Outlook. To customize a form region, see How to: Create a Custom Action for a Form Region.

  1. In the Forms Designer, click the (Actions) page of your form.

  2. Click the action that you want to modify, and then click Properties.

  3. Clear the Enabled check box.


How to: Make Separate Compose and Read Versions for a Form

 Copy code hover
[image]

How to: Make Separate Compose and Read Versions for a Form
Send feedback

You can create and edit separate compose and read versions for each page of a form. The compose version is the one that is displayed when you create an item. The read version is the one that Outlook displays after the item has been saved—for example, what Outlook displays in an inspector window when you read your email.

Note Note

Outlook only supports separate compose and read versions on some item types; in particular, items that you can send, such as mail and post. Other item types always display the compose form.

Forms customized with form regions

When you use form regions to create separate compose and read versions for a form, you must design two separate form regions, one for each version, and then register them independently on the same message class. Properties that you set in the XML manifest indicate which form is for the read-only view and which should be used for compose.

For more information, see How to: Create Separate Read and Compose Pages Using Form Regions in a Custom Form.

Forms customized with form pages

  1. In Forms Designer, on the Developer tab, in the Form group, do one of the following:

    • To create or edit the compose page, click Page, then click Edit Compose Page.

    • To create or edit the read page, click Page, then click Edit Read Page.

  2. Customize pages on the form.

    For more information, see How to: Customize Pages on a Form.

Note Note

You can quickly switch between the two versions by clicking Edit Compose Page and Edit Read Page in the Design group. If these commands are not available, you have set the compose and read versions to be the same. To have separate compose and read versions, click Separate Read Layout in the Design group.


How to: Use Standard Reply and Forward Headers on a Form

 Copy code hover
[image]

How to: Use Standard Reply and Forward Headers on a Form
Send feedback

  1. In the Forms Designer, click the (Actions) page of the form.

  2. Click an action that you created, and then click Properties.

  3. In the Address form like a box, click the header that you want to use.

Use this header | To
Reply | Include the sender in the To field and the subject of the message in the Subject field.
Reply to All | Include all the recipients of the message in the To and Cc fields and the subject of the message in the Subject field.
Forward | Include the subject of the message in the Subject field and leave the To field blank.
Reply to Folder | Show the active folder and show the subject as a conversation, and add Subject and Categories fields.
Response | Use the standard response fields.


How to: Add a Command to the Ribbon to Start a Reply Form

 Copy code hover
[image]

How to: Add a Command to the Ribbon to Start a Reply Form
Send feedback

Use this procedure to customize a Microsoft Outlook form page. To customize a form region, see How to: Create a Custom Action for a Form Region.

  1. In the Forms Designer, click the (Actions) page of your form.

  2. Click an action that you created, and then click Properties.

  3. Select the Show action on check box.Outlook uses the text in the Action name box as the command name or the button name on the form.After you complete the procedure, the new command is available for Custom Actions on the ribbon.

    Note Note

    The Menu and Toolbar and Menu only options apply only to forms displayed in versions of Outlook earlier than Microsoft Office Outlook 2007.


How to: Automatically Insert Prefix Text into the Subject Field of a Reply Form

 Copy code hover
[image]

How to: Automatically Insert Prefix Text into the Subject Field of a Reply Form
Send feedback

Customizing with form regions

In a form region, you can set the subject prefix in the XML manifest file of the form region. Alternatively, you can write code in the BeforeFormRegionShow method of the FormRegionStartup interface.

For more information, see How to: Specify a Subject Prefix of an Item Resulting from an Action.

Customizing with form pages

  1. In the Forms Designer, click the (Actions) page of your form.

  2. Click the action to which you want to add the prefix text, and then click Properties.

  3. In the Subject prefix box, type the text as you want it to appear (Outlook automatically adds a colon after the text).

    For example, you could add the prefix "Re:" to a reply form.


How to: Pre-address a Reply Form to a Public Folder or an E-mail Address

 Copy code hover
[image]

How to: Pre-address a Reply Form to a Public Folder or an E-mail Address
Send feedback
Note Note

To pre-address a form to a public folder, you must first add the public folder to your Contacts folder.

  1. Open the type of form that you want to pre-address.

  2. Click To on the form.

  3. Next to Search, select More Columns.

  4. In the Search box, type the e-mail address or the public folder that you want to appear in the To box on the form, and then click OK.

  5. On the Developer tab, in the Form group, click Design This Form to open the form in design mode. If you do not see the Developer tab in the open contact, see Run in Developer Mode in Outlook.

Note Note

Each person who uses the form must have permission to access the public folder that you specify in the To field.


Specifying Form Appearance

 Copy code hover
[image]

Specifying Form Appearance
Send feedback

In this section

  • How to: Set the Background Color of a Form

  • How to: Assign a Picture to a Form

  • How to: Change the Icons Associated with your Form

  • How to: Specify Icons to be Displayed for a Form Region


How to: Set the Background Color of a Form

 Copy code hover
[image]

How to: Set the Background Color of a Form
Send feedback

  1. Open the form that you want to modify in design mode.

    Note Note

    For more information, see Run in Developer Mode in Outlook.

  2. On the Developer tab, in the Tools group, click Advanced Properties.

  3. Click the BackColor property, and then type a value in the Properties box.

  4. Click Apply.

Note Note

When you use form regions, if the form background value is set to Button Face (the default), the background color is automatically determined based on the current Microsoft Office theme. Setting the color to another value prevents the color from being automatically determined. For more information, see Creating a Form Region.


How to: Assign a Picture to a Form

 Copy code hover
[image]

How to: Assign a Picture to a Form
Send feedback

  1. In the Forms Designer, click the tab for the page or the form region that you want to assign the picture to.

  2. Right-click the page or form region, and then click Advanced Properties.

  3. In the Properties dialog box, click the Picture property, and then click the Load Property button ([...]) that is next to the Apply box.

  4. Find the picture file that you want to use, and then click Apply.

  5. To set additional properties for the picture, choose one or more of the following, and then click Apply.

    Property

    Value

    Picture

    The name of the picture that you want to use.

    PictureAlignment

    TopLeft

    PictureSizeMode

    Clip

    PictureTiling

    True


How to: Change the Icons Associated with your Form

 Copy code hover
[image]

How to: Change the Icons Associated with your Form
Send feedback

Forms customized with form regions

When you customize icons on a form region, you can set icons for each of the different states of the form as well, such as replied, forwarded, or unread. For more information, see How to: Specify Icons to be Displayed for a Form Region.

Forms customized with form pages

  1. In the Forms Designer, click the Properties page.

  2. Click Change Large Icon or Change Small Icon.

  3. Select the icon that you want to use and then click Open.

Note Note

Sometimes you may find that even if you specify that a custom form should use a particular icon, when you view an item in a folder, a standard icon is used instead. This can happen in the following scenarios:

  • You published the form in a location that is not accessible to everyone. For example, when they receive a custom e-mail message form, they do not have access to the custom form. Therefore, Outlook displays the standard icon.

    Solution Publish the form to a location that is accessible to everyone who uses the form, typically the Organizational Forms Library.

  • The item has become a one-off form. In this case, the message class of the item changes to the default message class for that particular type of item, and the icon reverts back to the default icon for that type of item.

    Solution Reset the message class of the item.

  • You replied to or forwarded an item in a folder, and the new item does not use the custom icon. In this case, the form action that started the new item did not specify a custom message class. Therefore, the new item is a standard form that does not have a custom icon.

    Solution Disable the standard Reply, ReplyAll, and Forward actions and create custom Reply, ReplyAll, or Forward actions that start your custom form instead.

  • You replied to or forwarded an item in a folder. In this case, Outlook replaces the custom icon with the standard icon so that the reply or forward indicator arrows can be displayed.

    Solution This is a design limitation of Outlook. The forward or reply icons are always used instead of your custom icon.


How to: Specify Icons to be Displayed for a Form Region

 Copy code hover
[image]

How to: Specify Icons to be Displayed for a Form Region
Send feedback

When you define a form region for a custom message class, such as IPM.Note.Customer, you can specify custom icons to be displayed in the explorer, inspector, and the ribbon for items belonging to that message class.

Icons are specified as resources in a Win32 resource DLL file. You can refer to an icon file in the standard Win32 embedded icon notation. For example:

  • <default>c:\myicon.ico<.default> loads the default icon from the specified path, c:\

  • <unread>c:\myresource.dll,101</unread> loads the icon resource that has the resource ID 101 from the resource file myresource.dll in the specified path, c:\

Note that you can specify environment variables in the file path names, but you cannot specify paths in Universal Naming Convention (UNC).

By default, if you do not specify any custom icons, the icons assigned to the parent message class will be used. For example, if you do not specify any icons for a form region for IPM.Note.Customer, then the icons for IPM.Note will be used.

Depending on the type of item, there are different states of the item that you can consider distinguishing with separate icons. For example, in the explorer, a task item can use a custom icon to identify itself as recurrent, and a mail item can use a custom icon to identify itself as having been replied to. You do not have to specify a separate icon for each state that the type of item can be in; you can choose to specify a default icon that will be displayed in all states in the explorer, inspector, and ribbon that apply for that item type.

The following table shows the states of an item that you can consider to identify with custom icons in the explorer, inspector, or ribbon. All custom icons for a form region are specified under the icons element in the form region manifest XML file for that form region. Each state is mapped with an XML child element of the icons element. You will specify this form region manifest XML file when you register the form region in the Windows registry. For more information on registering a form region, see Specifying Form Regions in the Windows Registry.

State of an Item | XML Child Element | Example
Any state that applies to the item, if no other custom icon has been defined for that state. | default | <default>c:\default.ico</default>
Icon to identify in the explorer that item has been encrypted. | encrypted | <encrypted>c:\encryptedicon.ico</encrypted>
Icon to identify in the explorer that item has been forwarded. | forwarded | <forwarded>c:\forwardedicon.ico</forwarded>
Icon to identify in the ribbon that item belongs to a specific derived message class. | page | <page>c:\pageicon.ico</page>
Icon to identify in the explorer that item has been read. | read | <read>c:\readicon.ico</read>
Icon to identify in the explorer that item is recurrent. | recurring | <recurring>c:\recurringicon.ico</recurring>
Icon to identify in the explorer that item has been replied to. | replied | <replied>c:\repliedicon.ico</replied>
Icon to identify in the explorer that item has been signed with a digital signature. | signed | <signed>c:\signedicon.ico</signed>
Icon to identify in the explorer that item has been sent. | submitted | <submitted>c:\submittedicon.ico</submitted>
Icon to identify in the explorer that item has not yet been read. | unread | <unread>c:\unreadicon.ico</unread>
Icon to identify in the explorer that item is pending and has not yet been sent. | unsent | <unsent>c:\unsenticon.ico</unsent>
Icon to be displayed in the inspector when this item type has been opened. | window | <window>c:\windowicon.ico</window>

To specify a custom icon for a form region

  1. In the form region manifest XML file, under the icons element, specify the child element that maps to the state that you would like to customize.

  2. Depending on how you would like the custom icon file to be specified, do either of the following:

    • If you want Outlook to load the icon from an icon file or a resource file, specify the location of the icon file or resource file in the child element.

    • If you want an add-in to inform Outlook which icon to display, specify addin in the child element.

The following example specifies custom icons for several states of an item belonging to the message class supported by a form region:

XML Copy code Copy code
<icons>
 <default>c:\icons\MyIcon.ico</default>
 <unread>c:\icons\MyUnReadIcon.ico</unread>
 <read>c:\icons\MyReadIcon.ico</read>
 <encrypted>%windir%\myresource.dll,101</encrypted>
</icons>

The four custom icons include:

  • A custom icon file for the read state

  • A custom icon file for the unread state

  • A location in a resource file for the encrypted state

  • A default icon file for all other states applicable to the item

Note Note

The value of the child element can be expressed either as a file path to an icon file or a resource file, or as addin. The file path can be expressed as a full path or a path relative to the location of the form region manifest XML file, and can involve system variables. For more information on specifying an icon using an add-in, see How to: Use an Add-in to Specify Icons for a Form Region.


Specifying Form Behavior

 Copy code hover
[image]

Specifying Form Behavior
Send feedback

In this section

  • How to: Specify Whether a Form Prompts the User, Opens, or is Sent

  • How to: Create Custom Actions for a Form


How to: Specify Whether a Form Prompts the User, Opens, or is Sent

 Copy code hover
[image]

How to: Specify Whether a Form Prompts the User, Opens, or is Sent
Send feedback
Note Note

If you are setting properties for a form that is customized with form regions, you must use the XML manifest file instead of the Form Designer. To learn more, see How to: Create a Form Region.

Forms customized with form pages

  1. In the Form Designer, click the (Actions) page of your form.

  2. Click the action that you want, and then click Properties.

  3. Under This action will, click the option that you want the form to perform.

Click this option | To
Open the form | Open the form so that the user can add information.
Send the form immediately | Send the form to the specified address without opening it.
Prompt the user to open or send | Alert the user with a message that includes the option to open or send the form.
Note Note

If you click Send the form immediately, you must pre-address the form.


How to: Create Custom Actions for a Form

 Copy code hover
[image]

How to: Create Custom Actions for a Form
Send feedback

Actions are a very powerful feature of forms in Microsoft Outlook that you can use to create a wide variety of solutions without writing code. For example, you can use actions to open other forms, even forms of a different type, or you can create a message form with an action that opens a contact form.

Forms customized with form regions

You can specify custom actions for a form region. To create an action that suits your needs, you can either modify a built-in action or create a new custom action. For more information, see How to: Create a Custom Action for a Form Region.

Forms customized with form pages

In the Forms Designer, do the following:

  1. Click the (Actions) page.

  2. Click New.

  3. Select the options that you want.

Note Note

  • You can specify whether you want an action to appear as a command on both the Actions group of the form and the Form Design toolbar, or just on the item menu.

  • You can also use actions to create a new item. For example, you can create a message form with an action that creates a new contact. The new item is created in the open folder, not in the Contacts folder.

  • You must use the Forward action to include an attachment in a Reply. So even if your action is a Reply Action, use the Forward method to preserve attachments.

  • There is no direct way to automatically close the original item when the new item is opened. To do so, you must use Microsoft Visual Basic Scripting Edition (VBScript).


Using Fields and Controls to Interact with Users

 Copy code hover
[image]

Using Fields and Controls to Interact with Users
Send feedback

In this section

  • Managing Fields in the Forms Designer

  • Manipulating Controls in the Forms Designer

  • Manipulating Controls Programmatically


Managing Fields in the Forms Designer

 Copy code hover
[image]

Managing Fields in the Forms Designer
Send feedback

In this section

  • How to: Create a Combination Field for a Folder

  • How to: Create a Formula Field for a Folder

  • How to: Create a Simple Field for a Folder

  • How to: Extend the Use of an Outlook Item by Adding Fields and Pages

  • How to: Show or Hide Fields when Printing and Saving a Form

  • Examples of Validation Formulas

  • How to: Create a Validation Formula and Message


How to: Create a Combination Field for a Folder

 Copy code hover
[image]

How to: Create a Combination Field for a Folder
Send feedback

  1. In the Navigation Pane, click the folder for which you want to create the combination field.

  2. On the View tab, in the Current View group, click View Settings.

  3. In the Advanced View Settings: <view> dialog box, click Columns.

  4. In the Show Columns dialog box, click New Column.

  5. In the Name box, type a name for the column.

  6. In the Type box, click Combination.

  7. Click Edit.

  8. To append each value for the fields that you want to use together, click Joining fields and any text fragments to each other.To show only the first field that is not blank, click Showing only the first non-empty field, ignoring subsequent ones.

  9. Click Field, point to the field set that you want, and then click the field that you want to appear.

  10. Repeat step 9 to add each field that you want to appear.

  11. Click OK twice.

  12. To position the field between the other fields in the view, click the field, and then click Move Up or Move Down.

    To remove the field from the view, click Remove.

Note Note

  • Combination fields appear with the default format of the data type used. To display a data type with a custom format, you must create a formula field and use the Format function.

  • You cannot sort, group, or filter the contents of a combination field.


How to: Create a Formula Field for a Folder

 Copy code hover
[image]

How to: Create a Formula Field for a Folder
Send feedback

  1. In the Navigation Pane, select the folder for which you want to create the formula field.

  2. On the View tab, in the Current View group, click View Settings.

  3. In the Advanced View Settings: <view> dialog box, click Columns.

  4. In the Show Columns dialog box, click New Column.

  5. In the Name box, type a name for the column.

  6. In the Type box, click Formula.

  7. Click Edit.

  8. To insert a function in the formula, click Function, point to the function set that you want, and then click the formula that you want.

  9. To insert a field in the formula, select the argument that you want to replace, click Field, point to the field set that you want, and then click the field that you want.

  10. Click OK twice.

  11. To position the field between the other fields in the view, click the field, and then click Move Up or Move Down.

  12. To remove the field from the view, click Remove.

Note Note

  • Formula fields are updated with any change to a view. For example, if you change the width of a column, the formula fields are updated.

  • You cannot sort, group, or filter the contents of a formula field.


How to: Create a Simple Field for a Folder

 Copy code hover
[image]

How to: Create a Simple Field for a Folder
Send feedback

  1. In the Navigation Pane, click the folder for which you want to create the field.

  2. On the View tab, in the Current View group, click View Settings.

  3. In the Advanced View Settings: <view> dialog box, click Columns.

  4. In the Show Columns dialog box, click New Column.

  5. In the Name box, type a name for the column.

  6. In the Type box, click the data type that you want for the field. Do not select Combination or Formula.

  7. In the Format box, select the format that you want for the field.

  8. Click OK.

  9. To position the field between the other fields in the view, click Move Up or Move Down.

  10. To remove the field from the view, click Remove.


How to: Extend the Use of an Outlook Item by Adding Fields and Pages

 Copy code hover
[image]

How to: Extend the Use of an Outlook Item by Adding Fields and Pages
Send feedback

In this approach, you take a standard Microsoft Outlook item, such as a contact, message, task request, or meeting request, and add fields and extra pages. (You can also extend the use of an Outlook item with form regions. For more information, see Form Regions.)

Note Note

You must base all custom forms on existing Outlook forms. If you do not want to use the default form functionality that Outlook provides, you can hide all the default form pages and use only the extra blank pages to create a complete custom form. In addition, you can extend the functionality of a customized form by using form regions.

Customizing with form pages

  1. Open the item on which you want to base the form. For example, if you want your form to organize and collect information about a person or organization, open a contact.

  2. In the item, on the Developer tab, in the Form group, click Design This Form to open the item in design mode.

    Note Note

    If you do not see the Developer tab in the open contact, see the topic Run in Developer Mode in Outlook.

  3. Set attributes for the form. In design mode, you add attributes such as a caption, password, or description on the Properties page. The Actions page lists default Reply forms. You can add your own custom Reply forms to the Actions page, and you can change several aspects of how the default Reply forms work.

  4. Design the form by moving, removing, and adding fields and pages in the form. All the fields in the form and all the fields you add from the Field Chooser retain their built-in properties and functionality.

  5. Test and publish your form. You can see how your form looks right away; open your new form in run mode by clicking Run This Form in the Form group on the form. You can publish your form to your Personal Forms Library or to a folder to test it, and then publish the form to a public folder or to the Organization Forms Library so that others can use it.


How to: Show or Hide Fields when Printing and Saving a Form

 Copy code hover
[image]

How to: Show or Hide Fields when Printing and Saving a Form
Send feedback

  1. In the Forms Designer, right-click the field, and then click Properties.

  2. Click the Validation tab.

  3. Select or clear the Include this field for Printing and Save As check box.


Examples of Validation Formulas

 Copy code hover
[image]

Examples of Validation Formulas
Send feedback
Use | To evaluate
<50 | Numbers less than fifty.
>50 | Numbers greater than fifty.
=50 | Equal to fifty.
? | The number of characters.

For more information, see:

  • How to: Create a Validation Formula and Message

  • Validating User Input to a Field


How to: Create a Validation Formula and Message

 Copy code hover
[image]

How to: Create a Validation Formula and Message
Send feedback

  1. In the Forms Designer, right-click the field or control for which you want to create a validation formula, then click Properties.

  2. Click the Validation tab in the Properties dialog box.

  3. Select the Validate this field before closing the form check box.

  4. In the Validation Formula box, type the formula that you want to use to evaluate user input.

  5. In the Display this message if the validation fails box, type the text that you want to appear in the message.

  6. Click OK.

For more information, see the following:

  • How to: Require a Value for a Field or Control

  • Validating User Input to a Field


Manipulating Controls in the Forms Designer

 Copy code hover
[image]

Manipulating Controls in the Forms Designer
Send feedback

In this section

  • Control Toolbox Tasks

  • Basic Control Tasks

  • Secondary Control Tasks


Control Toolbox Tasks

 Copy code hover
[image]

Control Toolbox Tasks
Send feedback

In this section

  • How to: Add a Modified Control to the Control Toolbox

  • How to: Add a Page to the Control Toolbox

  • How to: Add Other Custom Controls to the Control Toolbox

  • How to: Change the Name and Control Tip of a Page in the Control Toolbox

  • How to: Change the Order of Pages in the Control Toolbox

  • How to: Customize an Icon for a Control in the Control Toolbox

  • How to: Delete a Control from the Control Toolbox

  • How to: Delete a Page in the Control Toolbox

  • How to: Import or Export a Control Toolbox Page

  • How to: Move a Control to Another Page in the Control Toolbox

  • How to: Show or Hide the Control Toolbox


How to: Add a Modified Control to the Control Toolbox

 Copy code hover
[image]

How to: Add a Modified Control to the Control Toolbox
Send feedback

  1. In an open form on the Developer tab, in the Tools group, click [image] Control Toolbox.

    Note Note

    If you do not see the Developer tab in the open form, see the topic Run in Developer Mode in Outlook.

  2. Drag a control from the Control Toolbox to your form and customize it. For example, to create an OK button, drag a CommandButton control onto the form, set its Caption property to OK, and set its Default property to True.

  3. Select the customized control.

  4. Drag the control to the Control Toolbox.

Note Note

When you drag a control onto the Control Toolbox, you only transfer the advanced property values. Any lines of code or Outlook property values that you have written for that control do not transfer with the control. You must write new code or copy code from the control on the form to the control on the Control Toolbox.


How to: Add a Page to the Control Toolbox

 Copy code hover
[image]

How to: Add a Page to the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, click [image] Control Toolbox in the Tools group on the Developer tab.

  2. Right-click outside the Controls tab in the Control Toolbox, and then click New Page on the shortcut menu.


How to: Add Other Custom Controls to the Control Toolbox

 Copy code hover
[image]

How to: Add Other Custom Controls to the Control Toolbox
Send feedback

  1. In Forms Designer, on the Developer tab, in the Tools group, click Control Toolbox.

  2. Right-click any control or an empty area on any page of the Control Toolbox, and then click Custom Controls on the shortcut menu.

  3. In the Available Controls box, select the check box next to the controls that you want to add.


How to: Change the Name and Control Tip of a Page in the Control Toolbox

 Copy code hover
[image]

How to: Change the Name and Control Tip of a Page in the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. Right-click the label of the page that you want in the Control Toolbox, and then click Rename.

  3. In the Caption box, type a new name for the page.

  4. In the Control Tip Text box, type new text for the control tip.


How to: Change the Order of Pages in the Control Toolbox

 Copy code hover
[image]

How to: Change the Order of Pages in the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. Right-click the label of any page in the Control Toolbox, and then click Move.

  3. In the Page Order box, click the name of a page that you want to move.

  4. Click Move Up or Move Down.


How to: Customize an Icon for a Control in the Control Toolbox

 Copy code hover
[image]

How to: Customize an Icon for a Control in the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. In the Control Toolbox, right-click the control that you want to customize, and then click Customize <control name>.

  3. To change the ToolTip, type the text in the Tool Tip Text box.

  4. To edit the icon, click Edit Picture. In the Color box, click the color that you want to use, and then click the pixel in the Picture box where you want to apply the color. Click OK.

  5. To assign a new bitmap, click Load Picture. In the File name box, type the name of the file that contains the bitmap you want to use as the icon. The bitmap cannot be larger than an icon.


How to: Delete a Control from the Control Toolbox

 Copy code hover
[image]

How to: Delete a Control from the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. In the Control Toolbox, right-click the control that you want to delete, and then click Delete <control name>.


How to: Delete a Page in the Control Toolbox

 Copy code hover
[image]

How to: Delete a Page in the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. Right-click the label of the page that you want to delete in the Control Toolbox, and then click Delete Page.

Note Note

All controls on a page are deleted when the page is deleted.


How to: Import or Export a Control Toolbox Page

 Copy code hover
[image]

How to: Import or Export a Control Toolbox Page
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. To import a page, right-click the label of any page in the Control Toolbox, and then click Import Page. To export a page, right-click the label of the page, and then click Export Page.

  3. In the File name box, type the name of the page that you want to import, or type the name of the file to which you want to export the page.

Note Note

Exporting a page does not remove it from the Control Toolbox.


How to: Move a Control to Another Page in the Control Toolbox

 Copy code hover
[image]

How to: Move a Control to Another Page in the Control Toolbox
Send feedback

  1. If the Control Toolbox is not visible, on the Developer tab, in the Tools group, click [image] Control Toolbox.

  2. Drag a control on any page to the label of another page. Hold the mouse pointer over the label until the page appears on top, and then drag the control onto the page.

Note Note

If the page to which you want to move a control is not visible, increase the width of the Control Toolbox to show all the pages, and then drag the control to the appropriate page.


How to: Show or Hide the Control Toolbox

 Copy code hover
[image]

How to: Show or Hide the Control Toolbox
Send feedback

To open the Control Toolbox

  • In the Forms Designer, on the Developer tab, in the Tools group, click [image] Control Toolbox.

To close the Control Toolbox

  • Click Close ( [image]) in the upper right corner.


Basic Control Tasks

 Copy code hover
[image]

Basic Control Tasks
Send feedback

In this section

  • How to: Add a Control to a Form

  • How to: Add or Remove Controls on a Form

  • How to: Adjust Spacing for Controls

  • How to: Align Controls

  • How to: Center Controls in a Form

  • How to: Change the Appearance of a Control

  • How to: Change the Name Property of a Control

  • How to: Enable or Disable a Control on a Page

  • How to: Hide or Show a Control

  • How to: Set Properties for Controls

  • How to: Size Controls


How to: Add a Control to a Form

 Copy code hover
[image]

How to: Add a Control to a Form
Send feedback

Use this procedure to add a control from the Control Toolbox to your form. You can also use this procedure to insert a control in a Frame, TabStrip, or MultiPage on the form.

  1. In an open form on the Developer tab, in the Tools group, click Control Toolbox.

    Note Note

    If you do not see the Developer tab in the open form, see the topic Run in Developer Mode in Outlook.

  2. Do one of the following:

    • Click a control in the Control Toolbox and then click in the form. The control appears in its default size. You can then drag the border of the control to change its size.

    • Drag a control from the Control Toolbox to the form. The control appears in its default size.

    • Double-click the control in the Control Toolbox, and then click in the form once for each control that you want to create. For example, to create four command buttons, double-click the CommandButton control in the Control Toolbox, and then click four times in the form.


How to: Add or Remove Controls on a Form

 Copy code hover
[image]

How to: Add or Remove Controls on a Form
Send feedback

You can add or remove controls on a form. In the Forms Designer, do one of the following:

To add a control

  1. Click [image] Control Toolbox , and then drag the control to the form.

  2. Set the control properties.

To remove a control

  1. Right-click the control, and then click Delete.


How to: Adjust Spacing for Controls

 Copy code hover
[image]

How to: Adjust Spacing for Controls
Send feedback

  1. In Forms Designer, select the controls for which you want to adjust the spacing.

  2. On the Developer tab, in the Arrange group, click Align, point to Distribute Horizontally or Distribute Vertically, and then click one of the following.

    Click

    To

    Make Equal

    Make all horizontal and vertical spaces between controls the same size. The amount of horizontal and vertical space will vary based on the area that is available to show the controls and the combined width of all controls.

    Increase

    Increase the space between controls by one grid block .

    Decrease

    Decrease the space between controls by one grid block.

    Remove

    Remove the space between controls. The controls do not overlap, but are immediately adjacent to each other.


How to: Align Controls

 Copy code hover
[image]

How to: Align Controls
Send feedback

  1. Select the controls that you want to align to part of the dominant control. For more information, see Selecting Multiple Controls and the Dominant Control.

  2. On the Developer tab, in the Arrange group, click Align, and then choose one of the following:

    Click

    To

    Left

    Align controls to the left edge of the dominant control.

    Center

    Align the center of the controls to the vertical center of the dominant control.

    Right

    Align controls to the right edge of the dominant control.

    Top

    Align controls to the top edge of the dominant control.

    Middle

    Align the center of the controls to the horizontal center of the dominant control.

    Bottom

    Align controls to the bottom edge of the dominant control.

    Distributed Horizontally

    Align the center of the controls with the horizontal center of the form. Note that this option is not based on the position of the dominant control.

    Distributed Vertically

    Align the center of the controls with vertical center of the form. Note that this option is not based on the position of the dominant control.

    Snap to Grid

    Align the upper-left corner of the controls with their nearest grid point. Note that this option is not based on the position of the dominant control.

    Align to Grid

    Align the center of the controls with the center of each grid. Note that this option is not based on the position of the dominant control.

    Center in Form

    Align the controls with the center of the form.


How to: Center Controls in a Form

 Copy code hover
[image]

How to: Center Controls in a Form
Send feedback

  1. Select the controls or groups of controls that you want to center. (The dominant control does not affect this procedure. For more information, see How to: Select Multiple Controls and the Dominant Control).

  2. On the Developer tab, in the Arrange group, click Align, point to Center in Form, and then click Horizontally or Vertically.


How to: Change the Appearance of a Control

 Copy code hover
[image]

How to: Change the Appearance of a Control
Send feedback

Outlook includes several properties that you can use to define the appearance of controls in your form:

  • ForeColor determines the foreground color. The foreground color applies to any text that is associated with the control, such as the caption or the control contents.

  • BackColor and BackStyle apply to the control background. The background is the area that is within the control boundaries, such as the area surrounding the text in a control, but not the control border. BackColor determines the background color. BackStyle determines whether the background is transparent. A transparent control background is useful if your form has a background picture. For ForeColor and BackColor, you can use the color scheme defined by your system, or you can use a custom color that you pick from the color palette. Using a system color, such as Menu Text, ensures that your form matches the colors and palette used by your applications. Custom colors do not always appear the same across systems and screen resolutions, but they do offer the widest choice of colors.

  • BorderColor, BorderStyle, and SpecialEffect apply to the control border. You can use BorderStyle or SpecialEffect to choose a border type. Only one of these two properties can be used at a time. When you assign a value to one of these properties, the system sets the other property to None. With SpecialEffect, you can choose one of several border styles, but you can only use system colors for the border. BorderStyle supports only one border style, but you can choose any color that is a valid setting for BorderColor. BorderColor specifies the color of the control border and is only valid when you use BorderStyle to create the border.

    Note Note

    The BorderColor, BorderStyle, and SpecialEffect properties can only be applied to the standard controls that are provided by default in the Control Toolbox and are not applicable to form regions.

Outlook supports transparency (that is, the display of whatever is behind an object instead of its background) in two areas: the background of certain controls and in bitmaps that are used on certain controls.

You can show a bitmap on many controls. Certain controls support transparent bitmaps — that is, bitmaps in which one or more background colors are transparent. Bitmap transparency is not controlled by any control property; it is controlled by the color of the lower-left pixel in the image. Outlook does not provide a way to edit a bitmap and make it transparent; instead, you must use a picture editor.

Bitmaps are always transparent on the following controls: CheckBox, CommandButton, Label, OptionButton, and ToggleButton. In Outlook, the following do not support transparent bitmaps: the form, Frame control, Image control, and MultiPage control.

Transparent pictures sometimes have a hazy appearance. If you do not like that appearance, show the picture on a control that supports opaque images. If you use a transparent bitmap on a control that does not support transparent bitmaps, the bitmap appears correctly, but you cannot see what is behind the bitmap.

For more information, see the following topics:

  • How to: Use a System Color for a Background or Foreground

  • How to: Use a Custom Color for the Background or Foreground of a Control

  • How to: Set the Background Color of a Form

  • How to: Make a Control Transparent


How to: Change the Name Property of a Control

 Copy code hover
[image]

How to: Change the Name Property of a Control
Send feedback

  1. In the Forms Designer, right-click the control, and then click Properties.

  2. On the Display tab, type a name in the Name box.

    Note Note

    Each control should have a unique name.


How to: Enable or Disable a Control on a Page

 Copy code hover
[image]

How to: Enable or Disable a Control on a Page
Send feedback

  1. In the Forms Designer, right-click the control that you want to modify, then click Properties.

  2. In the Properties dialog box, on the Display page, select or clear the Enabled check box.


How to: Hide or Show a Control

 Copy code hover
[image]

How to: Hide or Show a Control
Send feedback

  1. In the Forms Designer, right-click the control that you want to modify, then click Properties.

  2. In the Properties dialog box, on the Display page, select or clear the Visible check box.


How to: Set Properties for Controls

 Copy code hover
[image]

How to: Set Properties for Controls
Send feedback

There are two types of properties for a control: Outlook properties and advanced properties. Outlook properties are the basic properties needed to design a control. Advanced properties offer additional functionality.

Outlook properties are set in the Properties dialog box and must be set individually. Advanced properties are set in the Advanced Properties dialog box and can be set for multiple controls at once.

To set properties for a control

  1. Right-click the control, then click Properties.

  2. Select the options that you want.

To set advanced properties for controls

  1. Select the control(s) that you want to modify, right-click one of the controls, and then click Advanced Properties.

  2. Select the options that you want.


How to: Size Controls

 Copy code hover
[image]

How to: Size Controls
Send feedback

  1. Select the controls that you want to size to the dominant control. For more information, see How to: Select Multiple Controls and the Dominant Control.

  2. On the Developer tab, in the Arrange group, click Size, click Make Same Size, and then click one of the following.

    Click

    To

    Width

    Make all selected controls the same width as the dominant control.

    Height

    Make all selected controls the same height as the dominant control.

    Both

    Make all selected controls the same height and width as the dominant control.
Note Note

To size a control to fit its contents (both its picture and any text assigned to the Caption or Text property), select the control, click Size in the Arrange group, then click Size to Fit.


Secondary Control Tasks

 Copy code hover
[image]

Secondary Control Tasks
Send feedback

In this section

  • Adding Items to a List

  • How to: Add Items to a List in Design Mode

  • How to: Align Text in a Control

  • How to: Assign a Control Tip, Caption, or Accelerator Key to a Page or Tab

  • How to: Align a Picture on a Control

  • How to: Allow Multiple Lines of Text in a Control

  • How to: Assign a Control Tip, Caption, or Accelerator Key to a Control

  • How to: Assign a Picture to a Control

  • How to: Create a Group of Controls

  • How to: Create a Set of OptionButton Controls

  • How to: Create a Set of OptionButtons by Using the GroupName Property

  • How to: Delete a Picture from a Control

  • How to: Give a Control a 3-D Appearance

  • How to: Make a Control Read-only

  • How to: Make a Control Transparent

  • How to: Match Entries in a List to Entries Typed by Users

  • How to: Move a Control One Unit at a Time

  • How to: Require a Value for a Field or Control

  • How to: Right-Align a Control on a Form

  • How to: Select and Edit a Control Within a Group

  • How to: Select Multiple Controls and the Dominant Control

  • How to: Separate Controls in a Group

  • How to: Set Tab Order of Controls on a Page

  • How to: Set the Grid Size

  • How to: Show or Hide the Grid

  • How to: Show the Shortcut Menu for Controls and Groups of Controls

  • How to: Turn On or Off Sizing Controls to the Grid

  • How to: Use a Custom Color for the Background or Foreground of a Control

  • How to: Use a System Color for a Background or Foreground


Adding Items to a List

 Copy code hover
[image]

Adding Items to a List
Send feedback

You can add items to a list box or a combo box at design time or at run time.

To save contents in an item, ListBox and ComboBox controls must be bound to a field.

For more information, see the following topics:

  • How to: Add Items to a List at Design Time

  • How to: Add Items to a List at Run Time


How to: Add Items to a List in Design Mode

 Copy code hover
[image]

How to: Add Items to a List in Design Mode
Send feedback

  1. In Forms Designer, drag the ListBox or ComboBox control from the Control Toolbox to the form.

  2. Right-click the control, then click Properties on the shortcut menu.

  3. In the Properties dialog box, on the Value tab, click Choose Field, point to the User-defined field set, and then click the custom field to which you want the control bound.

  4. In the Possible values box, type the values for the items that you want to appear in the list, separated by semicolons.


How to: Align Text in a Control

 Copy code hover
[image]

How to: Align Text in a Control
Send feedback

This procedure is available only for the ComboBox, Label, and TextBox controls.

  1. Right-click the control, and then click Advanced Properties.

  2. To set the TextAlign property, in the Properties dialog box, click the property, type a value in the Apply box, and then click Apply.

    For more information about the correct TextAlign property for a specific control, see the following:

    • TextAlign property for the ComboBox control.

    • TextAlign property for the Label control.

    • TextAlign property for the TextBox control.


How to: Assign a Control Tip, Caption, or Accelerator Key to a Page or Tab

 Copy code hover
[image]

How to: Assign a Control Tip, Caption, or Accelerator Key to a Page or Tab
Send feedback

This procedure sets properties on a Page or Tab in a MultiPage or TabStrip control only.

  1. In the Forms Designer, select a page or tab in a MultiPage or TabStrip control. For more information, see How to: Select and Edit a Control Within a Group and How to: Assign a Control Tip, Caption, or Accelerator Key to a Control.

    Note Note

    Be sure to select an individual page or tab, and not the corresponding MultiPage or TabStrip. When you select a page or tab, a rectangle appears around its caption.

  2. Right-click the caption of the selected page or tab, and then click Rename.

  3. In the Control Tip Text box, type the text that you want to use as the control tip.

  4. In the Caption box, type the text that you want to use as the caption.

  5. In the Accelerator Key box, type a single character from the caption of the control. Note that the selected character is underlined in the control caption.

Tip Tip

To assign a control tip for a MultiPage or TabStrip, use the ControlTipText property. If you assign a control tip to a MultiPage or a TabStrip, control tips for the individual page or tab objects within the MultiPage do not appear.

For more information about the ControlTipText property to set for a specific control, see:

  • The ControlTipText property for the Page control.

  • The ControlTipText property for the Tab control.


How to: Align a Picture on a Control

 Copy code hover
[image]

How to: Align a Picture on a Control
Send feedback

  1. Right-click the control that has the bitmap that you want to align, then click Advanced Properties.

  2. Set one or all of the following properties. To set a property, select the property, type a value in the Properties box, and then click Apply.

    Property

    Description

    PictureAlignment

    Centers the picture within the Image or aligns any corner of the picture with the corresponding corner of the Image.

    PictureSizeMode

    Clips, stretches, or zooms the picture within the Image (stretching can distort the picture but zooming does not).

    PictureTiling

    Shows multiple copies of the picture within the Image.


How to: Allow Multiple Lines of Text in a Control

 Copy code hover
[image]

How to: Allow Multiple Lines of Text in a Control
Send feedback

  1. In Forms Designer, right-click the control, and then click Properties.

  2. In the Properties dialog box, on the Display tab, select the Multi-line check box.


How to: Assign a Control Tip, Caption, or Accelerator Key to a Control

 Copy code hover
[image]

How to: Assign a Control Tip, Caption, or Accelerator Key to a Control
Send feedback

  1. Right-click the control, and then click Advanced Properties.

  2. To set the property, open the Properties dialog box, click the property, type a value in the Apply box, and then click Apply.

    Property

    Description

    ControlTipText

    Use this string as the control tip.

    Caption

    Use this string as the caption.

    Accelerator

    Use a single character as the value for the ALT + Key entry. If you use a character from the caption of the control, the character is underlined.

For more information about the property to set for a specific control, see the following:

  • The ControlTipText property for the Page control.

  • The ControlTipText property for the Tab control.

  • The Caption property for the CheckBox control.

  • The Caption property for the CommandButton control.

  • The Caption property for the Frame control.

  • The Caption property for the Label control.

  • The Caption property for the OptionButton control.

  • The Caption property for the Page control.

  • The Caption property for the Tab control.

  • The Caption property for the ToggleButton control.

  • The Accelerator property for the CheckBox control.

  • The Accelerator property for the CommandButton control.

  • The Accelerator property for the Label control.

  • The Accelerator property for the OptionButton control.

  • The Accelerator property for the Page control.

  • The Accelerator property for the Tab control.

  • The Accelerator property for the ToggleButton control.

For more information, see How to: Assign a Control Tip, Caption, or Accelerator Key to a Page or Tab.


How to: Assign a Picture to a Control

 Copy code hover
[image]

How to: Assign a Picture to a Control
Send feedback

  1. Right-click the control that you want to assign a picture to, and then click Advanced Properties.

  2. In the Properties dialog box, select the Picture property and then click the ellipses ([...]) button that is next to the Apply box.

  3. In the Load Picture dialog box, type the name of the picture in the File name box.

Note Note

If the picture is larger than the control, Outlook scales the picture to fit the control.

For more information about the Picture property to set for a specific control, see the following:

  • The Picture property for the CheckBox control.

  • The Picture property for the CommandButton control.

  • The Picture property for the Frame control.

  • The Picture property for the Image control.

  • The Picture property for the Label control.

  • The Picture property for the OptionButton control.

  • The Picture property for the Page control.

  • The Picture property for the ToggleButton control.


How to: Create a Group of Controls

 Copy code hover
[image]

How to: Create a Group of Controls
Send feedback

  1. Select each control that you want to include in the group. (The dominant control does not affect this procedure. For more information, see How to: Select Multiple Controls and the Dominant Control.)

  2. On the Developer tab, in the Arrange group, click Group, and then click Group.


How to: Create a Set of OptionButton Controls

 Copy code hover
[image]

How to: Create a Set of OptionButton Controls
Send feedback

By default, all OptionButton controls in a container are part of a single option group. This means that selecting one of the buttons automatically sets all other option buttons on the form to False.

If you want more than one option group on the form, there are two ways to create additional groups:

  • Use the GroupName property to identify related buttons. This method reduces the number of controls required on the form, which can reduce the hard disk space required and improve the performance of the form. If you want to create an option group in a TabStrip (which is not a container), you must use the GroupName property. For more information, see How to: Create a Set of OptionButtons by Using the GroupName Property.

  • Put related buttons in a Page, MultiPage, or Frame on the form. For more information, see How to: Add a Control to a Form.


How to: Create a Set of OptionButtons by Using the GroupName Property

 Copy code hover
[image]

How to: Create a Set of OptionButtons by Using the GroupName Property
Send feedback

  1. Place all required OptionButton controls on the form.

    Note Note

    Option buttons in a Page, MultiPage, or Frame automatically form an option group.

  2. For each button in the group, right-click the control, and in the Properties box, set the GroupName property to the same value.


How to: Delete a Picture from a Control

 Copy code hover
[image]

How to: Delete a Picture from a Control
Send feedback

  1. Right-click the control, and then click Advanced Properties.

  2. In the Properties list, select the value of the Picture property (the word "bitmap").

  3. Press the DELETE key.


How to: Give a Control a 3-D Appearance

 Copy code hover
[image]

How to: Give a Control a 3-D Appearance
Send feedback

  1. In the Forms Designer, right-click the control, and then click Advanced Properties.

  2. In the Properties list, click SpecialEffect, and then click the option that you want from the drop-down list box next to the Apply box.

    Note Note

    The SpecialEffect property is not available for all controls.

  3. Click Apply.


How to: Make a Control Read-only

 Copy code hover
[image]

How to: Make a Control Read-only
Send feedback

  1. In the Forms Designer, right-click the control, then click Properties.

  2. In the Properties dialog box, on the Display page, select the Read only check box.


How to: Make a Control Transparent

 Copy code hover
[image]

How to: Make a Control Transparent
Send feedback

  1. Right-click the control that you want to make transparent, then click Advanced Properties.

    Note Note

    In this context, "transparent" means that the control inherits the background color of the parent control.

  2. Set the BackStyle property to Transparent. To set the property, click the BackStyle property, and then click Transparent in the Apply list. If the control supports the BorderStyle property, set it to None.

Note Note

When you make a control transparent, the background color does not appear, so the BackColor property is ignored. However, the setting for BackColor is not changed when a control is transparent.


How to: Match Entries in a List to Entries Typed by Users

 Copy code hover
[image]

How to: Match Entries in a List to Entries Typed by Users
Send feedback

  1. In the Form Designer, drag the ListBox or ComboBox control from the Control Toolbox to the form.

  2. Right-click the list box or combo box, and then click Advanced Properties.

  3. To set the MatchEntry property, click the property, specify a value in the Properties box, and then click Apply.

    For more information about the property for the specific control, see the following:

    • MatchEntry property for the ListBox control.

    • MatchEntry property for the ComboBox control.

    Set this MatchEntry value

    To

    No matching

    Provide no matching.

    First letter

    Compare the most recently typed letter to the first letter of each entry in the list (the first match in the list is selected).

    Complete

    Compare the user's entry and an exact match in an entry from the list.
Note Note

  • The matching feature resets after two seconds (six seconds in the East Asian version). For example, if you have a list of the 50 states in the United States, and you type "co" quickly, you find "Colorado." But if you take longer than two seconds to type "co", you find "Ohio" because the autocomplete search resets between letters.

  • If you select Complete matching, it is a good idea to sort the list entries alphabetically by using the TextColumn property for the specific control. If the list is not sorted alphabetically, matching might not work correctly. For example, if the list includes Alabama, Louisiana, and Alaska, respectively, then "Alabama" is considered a complete match if the user types "ala". In fact, this result is not complete because there are two entries in the list that could match what the user typed. Sorting alphabetically eliminates this problem.


How to: Move a Control One Unit at a Time

 Copy code hover
[image]

How to: Move a Control One Unit at a Time
Send feedback

  1. In the Forms Designer, right-click the control, then click Properties.

  2. In the Properties dialog box, on the Layout page, type a number in the Top and Left boxes.


How to: Require a Value for a Field or Control

 Copy code hover
[image]

How to: Require a Value for a Field or Control
Send feedback

  1. In the Forms Designer, right-click the field or control, then click Properties.

  2. In the Properties dialog box, on the Validation page, select the A value is required for this field check box.


How to: Right-Align a Control on a Form

 Copy code hover
[image]

How to: Right-Align a Control on a Form
Send feedback

  1. Drag a Label control from the Control Toolbox to the left of the area where you want to align a control.

  2. Remove any text from the Caption property.

  3. Right-click the label, then click Properties.

  4. On the Display page, select the Resize with form check box.

  5. Create the control that you want to align.

  6. Place the control to the right of the Label control.


How to: Select and Edit a Control Within a Group

 Copy code hover
[image]

How to: Select and Edit a Control Within a Group
Send feedback

  1. Select the group of controls.

  2. Select a single control within the group. The sizing handles around the group become lighter, and dark sizing handles appear on the selected control.

  3. Make the changes that you want to the selected control properties. Any change you make affects only the selected control.

  4. When you are finished, click anywhere in the group, but do not click the selected control. The group is still selected.

  5. Select another control in the group, or continue to another task.


How to: Select Multiple Controls and the Dominant Control

 Copy code hover
[image]

How to: Select Multiple Controls and the Dominant Control
Send feedback

You can select more than one control in three ways. When you select multiple controls, one of the controls becomes a reference for the rest and is called the dominant control.

Selection method | Controls selected | Dominant control
SHIFT+CLICK | All controls in an invisible rectangle around the selected controls. | The first control that you select.
CTRL+CLICK | Individual controls, one at a time. | The last control that you select.
Select Objects pointer in Control Toolbox | All controls that fall within or touch a rectangle that you draw. | The control that is nearest to the mouse pointer when you begin to draw the rectangle.

Tip Tip

  1. Occasionally, the CTRL+CLICK method selects additional controls that are near to, or adjacent to, the selected controls. For more accuracy, use the Select Objects pointer method.

  2. If you CTRL+CLICK a selected control twice, that control becomes the dominant control.


How to: Separate Controls in a Group

 Copy code hover
[image]

How to: Separate Controls in a Group
Send feedback

  1. In the Forms Designer, on the General tab, select the group of controls.

  2. On the Developer tab, in the Arrange group, click Group, and then click Ungroup.


How to: Set Tab Order of Controls on a Page

 Copy code hover
[image]

How to: Set Tab Order of Controls on a Page
Send feedback

  1. In the Forms Designer, right-click a page, but not a control, and then click Tab Order.

  2. Select the name of the control that you want to reposition in the tab order.

  3. Click Move Up or Move Down.

Note Note

You can also set the tab order by changing the TabIndex property. The tab index of the first control in the tab order is 0; the tab index of the second control is 1, and so on.


How to: Set the Grid Size

 Copy code hover
[image]

How to: Set the Grid Size
Send feedback

When you design a form, use the grid to align controls easily and precisely.

  1. In the Forms Designer, on the Developer tab, in the Arrange group, click Align, and then click Set Grid Size.

    Note Note

    When you customize forms with form regions, the grid is not displayed by default. For more information, see How to: Hide or Show the Grid.

  2. In the Height and Width boxes, type the dimensions for the grid.

    Tip Tip

    If you set the grid size to position command buttons in your application, use small grid settings so that you can position the command buttons closer to the edge of the form.


How to: Show or Hide the Grid

 Copy code hover
[image]

How to: Show or Hide the Grid
Send feedback

When you design a form, use the grid to align controls easily and precisely.

  • In the Forms Designer, on the Developer tab, in the Arrange group, click Align, and then click Show Grid.

Note Note

When you customize forms with form regions, the grid is not displayed by default.

For more information, see How to: Set the Grid Size.


How to: Show the Shortcut Menu for Controls and Groups of Controls

 Copy code hover
[image]

How to: Show the Shortcut Menu for Controls and Groups of Controls
Send feedback
To show the shortcut menu for a | Right-click
Page | The caption of that page.
Group of controls (groups created by using the Group command) | Anywhere inside the rectangle that surrounds the group.
Tab | The caption of that tab.
Any other control or container | The control or container.
Note Note

The commands on a shortcut menu vary based on the object that you select. For example, if you select multiple controls that are not in a group, the shortcut menu includes the Group command, whereas the shortcut menu for a text box does not.


How to: Turn On or Off Sizing Controls to the Grid

 Copy code hover
[image]

How to: Turn On or Off Sizing Controls to the Grid
Send feedback

  • In Forms Designer, on the Developer tab, in the Arrange group, click Align, and then click Snap to Grid.

    Note Note

    When Snap to Grid is selected, the sizing controls to the grid turns on.


How to: Use a Custom Color for the Background or Foreground of a Control

 Copy code hover
[image]

How to: Use a Custom Color for the Background or Foreground of a Control
Send feedback

  1. In the Forms Designer, right-click the control, and then click Advanced Properties.

  2. Click the BackColor or ForeColor property.

  3. In the top-right corner of the Properties dialog box, click the ellipsis button (...).

  4. Do one of the following:

    • Use an existing custom color by clicking it in the custom color palette.

    • Create a new custom color by clicking Define Custom Colors. Click the color in the color spectrum that you want to start with. To change the Red, Green, Blue, and Lum (luminosity) settings, slide the bar above the settings up or down. To change Hue and Saturation, type different settings. Add the new color to the palette by clicking Add to Custom Colors.

  5. To use the custom color for the current control, click it in the Custom colors palette, and then click OK.


How to: Use a System Color for a Background or Foreground

 Copy code hover
[image]

How to: Use a System Color for a Background or Foreground
Send feedback

  1. Right-click the control, then click Properties.

  2. On the Display tab, click an option from the Foreground color or Background color list boxes. A preview of the option that you click appears in the Font box.


Manipulating Controls Programmatically

 Copy code hover
[image]

Manipulating Controls Programmatically
Send feedback

In this section

  • How to: Accept User Input and Display the Values of Controls on a Form

  • How to: Access a Tab in a TabStrip Control

  • How to: Access a Page in a MultiPage Control

  • How to: Add, Cut, and Paste a Control on a Page

  • How to: Change the Accelerator and Caption of a Command Button

  • How to: Add a Control to a MultiPage Control

  • How to: Change the Name of a Control

  • How to: Resize a Control Horizontally and Vertically with the Form

  • How to: Add a Control to a Page

  • How to: Add and Remove Items from a List Box

  • How to: Add Scroll Bars to a Page and a Frame

  • How to: Align the Caption of an Option Button with the Control

  • How to: Allow a Command Button to Take Focus Upon Clicking

  • How to: Allow Multiple Lines, Word Wrapping, and Scrolling in a Text Box

  • How to: Allow Multiple Selections in a List Box

  • How to: Allow the Null State for a Check Box and a Toggle Button

  • How to: Automatically Size a Text Box with User Input

  • How to: Change the Column Widths of a Multi-Column List Box

  • How to: Change the Order of Pages and Tabs

  • How to: Add Items To a List or Combo Box at Run Time

  • How to: Use the Controls Collection to Move Controls on a Page

  • How to: Change the Style, Size, and Effects of a Font

  • How to: Control Character Matching in a Combo Box and List Box

  • How to: Control the Drop Button Style and When to Show the Drop Button

  • How to: Control the Extent of Scrolling in a Scroll Bar

  • How to: Control the Focus When the User Cycles through Controls in a Frame or MultiPage Control on a Form

  • How to: Control the Selection Behavior and Drag Behavior When Entering a Text Box

  • How to: Control the Style and Selection Behavior of a List Box

  • How to: Control the Text Box' Behavior on Clicking Enter

  • How to: Cut Text from One Text Box and Paste it on Another

  • How to: Display the List Portion of a Combo Box

  • How to: Display the Name of Each Control on a Form or a Page of a MultiPage Control

  • How to: Display the Name of Each Control on a Page

  • How to: Display the Number of Pages and Tabs in MultiPage and TabStrip Controls on a Form

  • How to: Enable and Lock a Text Box from User Entry

  • How to: Enhance the Border Style, Color, and Special Effects of a Text Box Control

  • How to: Give a Control a 3-D Appearance Programmatically

  • How to: Group Option Buttons

  • How to: Hide or Show a Control Programmatically

  • How to: Move a Text Box in Front of or Behind Another Control

  • How to: Move Controls on a Page

  • How to: Place an Image and a Caption on a Command Button

  • How to: Reference a Custom Property that Has the Same Name as a Built-in Property of the Control

  • How to: Reference the Parent Object of a Control

  • How to: Set Entry Matching in a Combo Box

  • How to: Set the Item at the Top of a List and the Item that Has Focus in the List

  • How to: Set the Height and Width of Tabs in a MultiPage and a TabStrip Control

  • How to: Set the Input Style for a Combo Box

  • How to: Set the Maximum and Minimum Values for a Scroll Bar

  • How to: Set the Number of Lines and the Length of Input in a Text Box

  • How to: Set the Style of Tabs for a MultiPage and a TabStrip Control

  • How to: Set the Tab Order of Controls in a Frame

  • How to: Set the Type of Mouse Pointer for a List Box

  • How to: Set the Width of the Drop-Down List of a Combo Box

  • How to: Simulate a Two-Dimensional Array with List Boxes

  • How to: Specify Additional Information for a Control

  • How to: Specify Control Tip Text for Controls

  • How to: Specify Possible Values for a List Box

  • How to: Specify Tab Support for a Control

  • How to: Specify the Column in a Multi-Column List Box to Display to the User

  • How to: Specify the Column in a Multi-Column List Box to Store Data for the Control

  • How to: Specify the Number of Rows in a Combo Box

  • How to: Swap Columns of a Multicolumn List Box

  • How to: Undo and Redo an Action in a Text Box or a Combo Box


How to: Accept User Input and Display the Values of Controls on a Form

 Copy code hover
[image]

How to: Accept User Input and Display the Values of Controls on a Form
Send feedback

The following example demonstrates the values that the different types of controls can have by displaying the Value property of a selected control. The user chooses a control by pressing TAB or by clicking on the control. Depending on the type of control, the user can also specify a value for the control by typing in the text area of the control, by clicking one or more times on the control, or by selecting an item, page, or tab within the control. The user can display the value of the selected control by clicking the appropriately labeled CommandButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A CommandButton named CommandButton1.

  • A TextBox named TextBox1.

  • A CheckBox named CheckBox1.

  • A ComboBox named ComboBox1.

  • A CommandButton named CommandButton2.

  • A ListBox named ListBox1.

  • A MultiPage named MultiPage1.

  • Two OptionButton controls named OptionButton1 and OptionButton2.

  • A ScrollBar named ScrollBar1.

  • A SpinButton named SpinButton1.

  • A TabStrip named TabStrip1.

  • A TextBox named TextBox2.

  • A ToggleButton named ToggleButton1.

Copy code Copy code
Sub CommandButton1_Click()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set Form = Item.GetInspector.ModifiedFormPages("P.2")
 TextBox1.Text = "Value of " & Form.ActiveControl.Name & " is " & Form.ActiveControl.Value
End Sub

Sub Item_Open()
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")

 CommandButton1.Caption = "Get value of current control"
 CommandButton1.AutoSize = True
 CommandButton1.TakeFocusOnClick = False
 CommandButton1.TabStop = False

 TextBox1.AutoSize = True

 For i = 0 To 10
 ComboBox1.AddItem "Choice " & (i + 1)
 ListBox1.AddItem "Selection " & (100 - i)
 Next

 CheckBox1.TripleState = True
 ToggleButton1.TripleState = True

 TextBox2.Text = "Enter text here."
End Sub


How to: Access a Tab in a TabStrip Control

 Copy code hover
[image]

How to: Access a Tab in a TabStrip Control
Send feedback

The following example accesses an individual tab of a TabStrip in several ways:

  • Using the Tabs collection with a numeric index.

  • Using the name of the individual Tab.

  • Using the SelectedItem property.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event of the item will activate. Make sure that the form contains a TabStrip named TabStrip1.

Copy code Copy code
Sub Item_Open()
 Dim TabStrip1
 Dim TabName

 Set TabStrip1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TabStrip1")
 For i = 0 To TabStrip1.Count - 1
 'Using index (numeric or string)
 MsgBox "TabStrip1.Tabs(i).Caption = " & TabStrip1.Tabs(i).Caption
 MsgBox "TabStrip1.Tabs.Item(i).Caption = " & TabStrip1.Tabs.Item(i).Caption

 'Use Tab object without referring to Tabs collection
 If i = 0 Then
 MsgBox "TabStrip1.Tab1. Caption = " & TabStrip1.Tab1.Caption
 ElseIf i = 1 Then
 MsgBox "TabStrip1.Tab2. Caption = " & TabStrip1.Tab2.Caption
 End If

 'Use SelectedItem Property
 TabStrip1.Value = i
 MsgBox " TabStrip1.SelectedItem.Caption = " & TabStrip1.SelectedItem.Caption
 Next
End Sub


How to: Access a Page in a MultiPage Control

 Copy code hover
[image]

How to: Access a Page in a MultiPage Control
Send feedback

The following example accesses an individual page of a MultiPage in several ways:

  • Using the Pages collection with a numeric index.

  • Using the name of the individual page in the MultiPage.

  • Using the SelectedItem property.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains a MultiPage named MultiPage1 and a CommandButton named CommandButton1.

Copy code Copy code
Sub CommandButton1_Click
 Dim PageName
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").MultiPage1

 For i = 0 To MultiPage1.Count - 1
 'Use index (numeric or string)
 MsgBox "MultiPage1.Pages(i).Caption = " & MultiPage1.Pages(i).Caption
 MsgBox "MultiPage1.Pages.Item(i).Caption = " & MultiPage1.Pages.Item(i).Caption

 'Use Page object without referring to Pages collection
 If i = 0 Then
 MsgBox "MultiPage1.Page1.Caption = " & MultiPage1.Page1.Caption
 ElseIf i = 1 Then
 MsgBox "MultiPage1.Page2.Caption = " & MultiPage1.Page2.Caption
 End If

 'Use SelectedItem Property
 MultiPage1.Value = i
 MsgBox "MultiPage1.SelectedItem.Caption = " & MultiPage1.SelectedItem.Caption
 Next
End Sub


How to: Add, Cut, and Paste a Control on a Page

 Copy code hover
[image]

How to: Add, Cut, and Paste a Control on a Page
Send feedback

The following example uses the Microsoft Forms 2.0 Controls collection, and the Controls.Add, Controls.Cut, and Page.Paste methods to add, cut, and paste a control on a Page of a MultiPage. The control involved in the cut and paste operations is dynamically added to the form.

This example assumes the user will add, then cut, then paste the new control.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Three CommandButton controls named CommandButton1 through CommandButton3.

  • A MultiPage named MultiPage1.

Copy code Copy code
Dim CommandButton1
Dim CommandButton2
Dim CommandButton3
Dim MultiPage1
Dim MyTextBox

Sub CommandButton1_Click()
 Set MyTextBox = MultiPage1.Pages(MultiPage1.Value).Controls.Add("Forms.TextBox.1", "MyTextBox", 1)
 CommandButton2.Enabled = True
 CommandButton1.Enabled = False
End Sub

Sub CommandButton2_Click()
 MultiPage1.Pages(MultiPage1.Value).Controls.Cut
 CommandButton3.Enabled = True
 CommandButton2.Enabled = False
End Sub

Sub CommandButton3_Click()
 Dim MyPage
 Set MyPage = MultiPage1.Pages.Item(MultiPage1.Value)

 MyPage.Paste
 CommandButton3.Enabled = False
End Sub

Sub Item_Open()
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton1")
 Set CommandButton2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton2")
 Set CommandButton3 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton3")
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("MultiPage1")

 CommandButton1.Caption = "Add"
 CommandButton2.Caption = "Cut"
 CommandButton3.Caption = "Paste"

 CommandButton1.Enabled = True
 CommandButton2.Enabled = False
 CommandButton3.Enabled = False
End Sub


How to: Change the Accelerator and Caption of a Command Button

 Copy code hover
[image]

How to: Change the Accelerator and Caption of a Command Button
Send feedback

This example changes the Accelerator and Caption properties of a CommandButton each time the user clicks the button by using the mouse or the accelerator key. The Click event contains the code to change the Accelerator and Caption properties.

To try this example, paste the code into the Script Editor of a form containing a CommandButton named CommandButton1. To run the code you need to open the form so the Open event will activate.

Copy code Copy code
Dim CommandButton1

Sub Item_Open()
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1
 CommandButton1.Accelerator = "C" 'Set Accelerator key to ALT + C
End Sub

Sub CommandButton1_Click ()
 If CommandButton1.Caption = "OK" Then 'Check caption, then change it.
 CommandButton1.Caption = "Clicked"
 CommandButton1.Accelerator = "C" 'Set Accelerator key to ALT + C
 Else
 CommandButton1.Caption = "OK"
 CommandButton1.Accelerator = "O" 'Set Accelerator key to ALT + O
 End If
End Sub


How to: Add a Control to a MultiPage Control

 Copy code hover
[image]

How to: Add a Control to a MultiPage Control
Send feedback

The following example uses the Add, Clear, and Remove methods of the Microsoft Forms 2.0 Controls collection to add a control to and remove a control from a Page of a MultiPage at run time.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A MultiPage named MultiPage1.

  • Three CommandButton controls named CommandButton1 through CommandButton3.

Copy code Copy code
Dim MyTextBox
Dim MultiPage1

Sub Item_Open()
 Set MyPage = Item.GetInspector.ModifiedFormPages("P.2")
 Set MultiPage1 = MyPage.MultiPage1
 MyPage.CommandButton1.Caption = "Add control"
 MyPage.CommandButton2.Caption = "Clear controls"
 MyPage.CommandButton3.Caption = "Remove control"
End Sub

Sub CommandButton1_Click()
 Set MyTextBox = MultiPage1.Pages(0).Controls.Add("Forms.TextBox.1", "MyTextBox", 1)
End Sub

Sub CommandButton2_Click()
 MultiPage1.Pages(0).Controls.Clear
End Sub

Sub CommandButton3_Click()
 If MultiPage1.Pages(0).Controls.Count > 0 Then
 MultiPage1.Pages(0).Controls.Remove "MyTextBox"
 End If
End Sub


How to: Change the Name of a Control

 Copy code hover
[image]

How to: Change the Name of a Control
Send feedback

The following code example uses the ModifiedFormPages property of the current Inspector object to set the Microsoft Forms 2.0 Name property of a CheckBox on a page named "Test" to "Selection."

Copy code Copy code
Item.GetInspector.ModifiedFormPages("Test").Checkbox1.Name = "Selection"
Note Note

Each control should have a unique name.


How to: Resize a Control Horizontally and Vertically with the Form

 Copy code hover
[image]

How to: Resize a Control Horizontally and Vertically with the Form
Send feedback

The following code sample shows how to resize a control with a form. It uses the OlkControl class that represents some basic properties (for example, HorizontalLayout and VerticalLayout) common to Outlook form controls. It assumes an existing Outlook text box control, myTextBox, in the form, and uses casting in Visual Basic to allow the text box control to use the properties of OlkControl.

Copy code Copy code
Dim olkCtrl As Outlook.OlkControl

    ' Let the text box control use the properties of OlkControl
    Set olkCtrl = myTextBox

    ' Enable automatic adjustments of the layout with respect to the rest of the form
    olkCtrl.EnableAutoLayout = True

    ' Allow resizing the text box control horizontally and vertically with the form
    olkCtrl.HorizontalLayout = olHorizontalLayoutGrow
    olkCtrl.VerticalLayout = olVerticalLayoutGrow


How to: Add a Control to a Page

 Copy code hover
[image]

How to: Add a Control to a Page
Send feedback

The following example uses the Add method of the Microsoft Forms 2.0 Controls collection to add a control to a form at run time.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains:

  • A CommandButton named CommandButton1.

Copy code Copy code
Dim Mycmd
Sub CommandButton1_Click()

 Set Mycmd = Item.GetInspector.ModifiedFormPages("P.2").Controls.Add("Forms.CommandButton.1") ', CommandButton2, Visible)
 Mycmd.Left = 18
 Mycmd.Top = 150
 Mycmd.Width = 175
 Mycmd.Height = 20
 Mycmd.Caption = "This is fun." & Mycmd.Name

End Sub


How to: Add and Remove Items from a List Box

 Copy code hover
[image]

How to: Add and Remove Items from a List Box
Send feedback

The following example adds and deletes the contents of a ListBox using the AddItem, RemoveItem, and SetFocus methods, and the ListIndex and ListCount properties.

Note Note

The SetFocus method is inherited from the Microsoft Forms 2.0 ListBox control.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

  • Two CommandButton controls named CommandButton1 and CommandButton2.

Copy code Copy code
Dim EntryCount
Dim Listbox1

Sub Item_Open()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").ListBox1
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1
 Set CommandButton2 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton2
 EntryCount = 0
 CommandButton1.Caption = "Add Item"
 CommandButton2.Caption = "Remove Item"
End Sub

Sub CommandButton1_Click()
 EntryCount = EntryCount + 1
 ListBox1.AddItem (EntryCount & " - Selection")
End Sub

Sub CommandButton2_Click()
 ListBox1.SetFocus

 'Ensure ListBox contains list items
 If ListBox1.ListCount >= 1 Then
 'If no selection, choose last list item.
 If ListBox1.ListIndex = -1 Then
 ListBox1.ListIndex = ListBox1.ListCount - 1
 End If
 ListBox1.RemoveItem (ListBox1.ListIndex)
 End If
End Sub


How to: Add Scroll Bars to a Page and a Frame

 Copy code hover
[image]

How to: Add Scroll Bars to a Page and a Frame
Send feedback

The following example uses the ScrollBars and the KeepScrollBarsVisible properties to add scroll bars to a page of a MultiPage and to a Frame. The user chooses an option button that, in turn, specifies a value for KeepScrollBarsVisible.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A MultiPage named MultiPage1.

  • A Frame named Frame1.

  • Four OptionButton controls named OptionButton1 through OptionButton4.

Copy code Copy code
Sub Item_Open()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")
 Set OptionButton4 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton4")

 MultiPage1.Pages(0).ScrollBars = 3 '3=fmScrollBarsBoth
 MultiPage1.Pages(0).KeepScrollBarsVisible = 0 '0=fmScrollBarsNone

 Frame1.ScrollBars = 3 '3=fmScrollBarsBoth
 Frame1.KeepScrollBarsVisible = 0 '0=fmScrollBarsNone

 OptionButton1.Caption = "No scroll bars"
 OptionButton1.Value = True
 OptionButton2.Caption = "Horizontal scroll bars"
 OptionButton3.Caption = "Vertical scroll bars"
 OptionButton4.Caption = "Both scroll bars"
End Sub

Sub OptionButton1_Click()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")

 MultiPage1.Pages(0).KeepScrollBarsVisible = 0 '0=fmScrollBarsNone
 Frame1.KeepScrollBarsVisible = 0 '0=fmScrollBarsNonefmScrollBarsNone
End Sub

Sub OptionButton2_Click()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")

 MultiPage1.Pages(0).KeepScrollBarsVisible = 1 '1=fmScrollBarsHorizontal
 Frame1.KeepScrollBarsVisible = 1 '1=fmScrollBarsHorizontal
End Sub

Sub OptionButton3_Click()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")

 MultiPage1.Pages(0).KeepScrollBarsVisible = 2 '2=fmScrollBarsVertical
 Frame1.KeepScrollBarsVisible = 2 '2=fmScrollBarsVertical
End Sub

Sub OptionButton4_Click()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")

 MultiPage1.Pages(0).KeepScrollBarsVisible = 3 '3=fmScrollBarsBoth
 Frame1.KeepScrollBarsVisible = 3 '3=fmScrollBarsBoth
End Sub


How to: Align the Caption of an Option Button with the Control

 Copy code hover
[image]

How to: Align the Caption of an Option Button with the Control
Send feedback

The following example demonstrates the Alignment property used with several OptionButton controls. In this example, the user can change the alignment by clicking a ToggleButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains the following controls:

  • Two OptionButton controls named OptionButton1 and OptionButton2.

  • A ToggleButton named ToggleButton1.

Copy code Copy code
Dim OptionButton1
Dim OptionButton2
Dim ToggleButton1

Sub Item_Open()
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("OptionButton2")
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ToggleButton1")

 OptionButton1.Alignment = 0 'fmAlignmentLeft
 OptionButton2.Alignment = 0 'fmAlignmentLeft

 OptionButton1.Caption = "Alignment with AutoSize"
 OptionButton2.Caption = "Choice 2"
 OptionButton1.AutoSize = True
 OptionButton2.AutoSize = True

 ToggleButton1.Caption = "Left Align"
 ToggleButton1.WordWrap = True
 ToggleButton1.Value = True
End Sub

Sub ToggleButton1_Click()
 If ToggleButton1.Value = True Then
 ToggleButton1.Caption = "Left Align"
 OptionButton1.Alignment = 0 'fmAlignmentLeft
 OptionButton2.Alignment = 0 'fmAlignmentLeft
 Else
 ToggleButton1.Caption = "Right Align"
 OptionButton1.Alignment = 1 'fmAlignmentRight
 OptionButton2.Alignment = 1 'fmAlignmentRight
 End If
End Sub


How to: Allow a Command Button to Take Focus Upon Clicking

 Copy code hover
[image]

How to: Allow a Command Button to Take Focus Upon Clicking
Send feedback

The following example uses the TakeFocusOnClick property to control whether a CommandButton receives the focus when the user clicks on it. The user clicks a control other than CommandButton1 and then clicks CommandButton1. If TakeFocusOnClick is True, CommandButton1 receives the focus after it is clicked. The user can change the value of TakeFocusOnClick by clicking the ToggleButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A CommandButton named CommandButton1.

  • A ToggleButton named ToggleButton1.

  • One or two other controls, such as an OptionButton or ListBox.

Copy code Copy code
Sub CommandButton1_Click()
 MsgBox "Watch CommandButton1 to see if it takes the focus."
End Sub

Sub ToggleButton1_Click()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 If ToggleButton1 = True Then
 CommandButton1.TakeFocusOnClick = True
 ToggleButton1.Caption = "TakeFocusOnClick On"
 Else
 CommandButton1.TakeFocusOnClick = False
 ToggleButton1.Caption = "TakeFocusOnClick Off"
 End If
End Sub

Sub Item_Open()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 CommandButton1.Caption = "Show Message"

 ToggleButton1.Caption = "TakeFocusOnClick On"
 ToggleButton1.Value = True
 ToggleButton1.Width = 90
End Sub


How to: Allow Multiple Lines, Word Wrapping, and Scrolling in a Text Box

 Copy code hover
[image]

How to: Allow Multiple Lines, Word Wrapping, and Scrolling in a Text Box
Send feedback

The following example demonstrates the MultiLine, WordWrap, and ScrollBars properties on a TextBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A TextBox named TextBox1.

  • Four ToggleButton controls named ToggleButton1 through ToggleButton4.

To see the entire text placed in the TextBox, set MultiLine and WordWrap to True by clicking the ToggleButton controls.

When MultiLine is True, you can enter new lines of text by pressing SHIFT+ENTER.

ScrollBars appears when you manually change the content of the TextBox.

Copy code Copy code
Dim ToggleButton1
Dim ToggleButton2
Dim ToggleButton3
Dim ToggleButton4
Dim TextBox1

Sub Item_Open
'Initialize TextBox properties and toggle buttons

 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton1
 Set ToggleButton2 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton2
 Set ToggleButton3 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton3
 Set ToggleButton4 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton4
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").TextBox1

 TextBox1.Text = "Type your text here. Enter SHIFT+ENTER to move to a new line."
 TextBox1.AutoSize = False
 ToggleButton1.Caption = "AutoSize Off"
 ToggleButton1.Value = False
 ToggleButton1.AutoSize = True

 TextBox1.WordWrap = False
 ToggleButton2.Caption = "WordWrap Off"
 ToggleButton2.Value = False
 ToggleButton2.AutoSize = True

 TextBox1.ScrollBars = 0
 ToggleButton3.Caption = "ScrollBars Off"
 ToggleButton3.Value = False
 ToggleButton3.AutoSize = True

 TextBox1.MultiLine = False
 ToggleButton4.Caption = "Single Line"
 ToggleButton4.Value = False
 ToggleButton4.AutoSize = True

End Sub

Sub ToggleButton1_Click
'Set AutoSize property and associated ToggleButton

 If ToggleButton1.Value = True Then
 TextBox1.AutoSize = True
 ToggleButton1.Caption = "AutoSize On"
 Else
 TextBox1.AutoSize = False
 ToggleButton1.Caption = "AutoSize Off"
 End if
End Sub

Sub ToggleButton2_Click
'Set WordWrap property and associated ToggleButton

 If ToggleButton2.Value = True Then
 TextBox1.WordWrap = True
 ToggleButton2.Caption = "WordWrap On"
 Else
 TextBox1.WordWrap = False
 ToggleButton2.Caption = "WordWrap Off"
 End if
End Sub

Sub ToggleButton3_Click
'Set ScrollBars property and associated ToggleButton

 If ToggleButton3.Value = True Then
 TextBox1.ScrollBars = 3
 ToggleButton3.Caption = "ScrollBars On"
 Else
 TextBox1.ScrollBars = 0
 ToggleButton3.Caption = "ScrollBars Off"
 End if
End Sub

Sub ToggleButton4_Click
'Set MultiLine property and associated ToggleButton

 If ToggleButton4.Value = True Then
 TextBox1.MultiLine = True
 ToggleButton4.Caption = "Multiple Lines"
 Else
 TextBox1.MultiLine = False
 ToggleButton4.Caption = "Single Line"
 End if
 End Sub


How to: Allow Multiple Selections in a List Box

 Copy code hover
[image]

How to: Allow Multiple Selections in a List Box
Send feedback

The following example uses the MultiSelect and Selected properties to demonstrate how the user can select one or more items in a ListBox. The user specifies a selection method by choosing an option button and then selects an item(s) from the ListBox. The user can display the selected items in a second ListBox by clicking the CommandButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Two ListBox controls named ListBox1 and ListBox2.

  • A CommandButton named CommandButton1.

  • Three OptionButton controls named OptionButton1 through OptionButton3.

Copy code Copy code
Sub CommandButton1_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set ListBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox2")
 ListBox2.Clear

 For i = 0 To 9
 If ListBox1.Selected(i) = True Then
 ListBox2.AddItem ListBox1.List(i)
 End If
 Next

End Sub

Sub OptionButton1_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 0 '0=fmMultiSelectSingle
End Sub

Sub OptionButton2_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 1 '1=fmMultiSelectMulti
End Sub

Sub OptionButton3_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 2 '2=fmMultiSelectExtended
End Sub

Sub Item_Open()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 For i = 0 To 9
 ListBox1.AddItem "Choice " & (ListBox1.ListCount + 1)
 Next

 OptionButton1.Caption = "Single Selection"
 ListBox1.MultiSelect = 0 '0=fmMultiSelectSingle
 OptionButton1.Value = True

 OptionButton2.Caption = "Multiple Selection"
 OptionButton3.Caption = "Extended Selection"

 CommandButton1.Caption = "Show selections"
 CommandButton1.AutoSize = True
End Sub


How to: Allow the Null State for a Check Box and a Toggle Button

 Copy code hover
[image]

How to: Allow the Null State for a Check Box and a Toggle Button
Send feedback

The following example uses the TripleState property to allow Null as a legal value of a CheckBox and a ToggleButton. The user controls the value of TripleState through ToggleButton2. The user can set the value of a CheckBox or ToggleButton based on the value of TripleState. However, when a control is set to Null, no event is fired.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A CheckBox named CheckBox1.

  • A ToggleButton named ToggleButton1.

  • A ToggleButton named ToggleButton2.

Copy code Copy code
Sub Item_Open()
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set ToggleButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton2")

 CheckBox1.Caption = "Value is True"
 CheckBox1.Value = True
 CheckBox1.TripleState = False

 ToggleButton1.Caption = "Value is True"
 ToggleButton1.Value = True
 ToggleButton1.TripleState = False

 ToggleButton2.Value = False
 ToggleButton2.Caption = "Triple State Off"
End Sub

Sub ToggleButton2_Click()
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set ToggleButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton2")

 If ToggleButton2.Value = True Then
 ToggleButton2.Caption = "Triple State On"
 CheckBox1.TripleState = True
 ToggleButton1.TripleState = True
 Else
 ToggleButton2.Caption = "Triple State Off"
 CheckBox1.TripleState = False
 ToggleButton1.TripleState = False
 End If
End Sub

Sub CheckBox1_Click()
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")
 If IsNull(CheckBox1.Value) Then
 CheckBox1.Caption = "Value is Null"
 ElseIf CheckBox1.Value = False Then
 CheckBox1.Caption = "Value is False"
 ElseIf CheckBox1.Value = True Then
 CheckBox1.Caption = "Value is True"
 End If
End Sub

Sub ToggleButton1_Click()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 If IsNull(ToggleButton1.Value) Then
 ToggleButton1.Caption = "Value is Null"
 ElseIf ToggleButton1.Value = False Then
 ToggleButton1.Caption = "Value is False"
 ElseIf ToggleButton1.Value = True Then
 ToggleButton1.Caption = "Value is True"
 End If
End Sub


How to: Automatically Size a Text Box with User Input

 Copy code hover
[image]

How to: Automatically Size a Text Box with User Input
Send feedback

The following example demonstrates the effects of the AutoSize property with a single-line TextBox and a multiline TextBox. The user can enter text into either of the TextBox controls and turn AutoSize on or off independently of the contents of the TextBox. This code sample also uses the Text property.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Two TextBox controls named TextBox1 and TextBox2.

  • A ToggleButton named ToggleButton1.

Copy code Copy code
Dim ToggleButton1
Dim TextBox1
Dim TextBox2

Sub Item_Open()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton1
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").TextBox1
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").TextBox2

 TextBox1.Text = "Single-line TextBox. Type your text here."

 TextBox2.MultiLine = True
 TextBox2.Text = "Multi-line TextBox. Type your text here. Use SHIFT+ENTER to start a new line."

 ToggleButton1.Value = True
 ToggleButton1.Caption = "AutoSize On"
 TextBox1.AutoSize = True
 TextBox2.AutoSize = True
End Sub

Sub ToggleButton1_Click()
 If ToggleButton1.Value = True Then
 ToggleButton1.Caption = "AutoSize On"
 TextBox1.AutoSize = True
 TextBox2.AutoSize = True
 Else
 ToggleButton1.Caption = "AutoSize Off"
 TextBox1.AutoSize = False
 TextBox2.AutoSize = False
 End If
End Sub


How to: Change the Column Widths of a Multi-Column List Box

 Copy code hover
[image]

How to: Change the Column Widths of a Multi-Column List Box
Send feedback

The following example uses the ColumnWidths property to change the column widths of a multicolumn ListBox. The example uses three TextBox controls to specify the individual column widths and uses the Click event to specify the units of measure of each TextBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

  • Three custom text fields named Text1, Text2, and Text3.

  • Three TextBox controls named TextBox1, TextBox2, and TextBox3 that are bound to the custom text fields above.

  • A CommandButton named CommandButton1.

Try entering the value 0 to hide a column.

Copy code Copy code
Dim MyArray(2, 3)
Dim ListBox1
Dim TextBox1
Dim TextBox2
Dim TextBox3
Dim CommandButton1

Sub Item_Open()
Dim i, j, Rows

Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").ListBox1
Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").TextBox1
Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").TextBox2
Set TextBox3 = Item.GetInspector.ModifiedFormPages("P.2").TextBox3
Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1

ListBox1.ColumnCount = 3
Rows = 2

For j = 0 To ListBox1.ColumnCount - 1
 For i = 0 To Rows - 1
 MyArray(i, j) = "Row " & i & ", Column " & j
 Next
Next

ListBox1.List() = MyArray 'Load MyArray into ListBox1

TextBox1.Text = "1 in" '1-inch columns initially
TextBox2.Text = "1 in"
TextBox3.Text = "1 in"

End Sub

Sub CommandButton1_Click()
 'ColumnWidths requires a value for each column separated by semicolons
 ListBox1.ColumnWidths = TextBox1.Text & ";" & TextBox2.Text & ";" & TextBox3.Text
End Sub

Sub Item_CustomPropertyChange(ByVal Name)
msgbox Name
Select Case Name
Case "Text1"
 'ColumnWidths accepts points (no units), inches or centimeters; make inches the default
 If Not (InStr(TextBox1.Text, "in") > 0 Or InStr(TextBox1.Text, "cm") > 0) Then
 TextBox1.Text = TextBox1.Text & " in"
 End If
Case "Text2"
 'ColumnWidths accepts points (no units), inches or centimeters; make inches the default
 If Not (InStr(TextBox2.Text, "in") > 0 Or InStr(TextBox2.Text, "cm") > 0) Then
 TextBox2.Text = TextBox2.Text & " in"
 End If
Case "Text3"
 'ColumnWidths accepts points (no units), inches or centimeters; make inches the default
 If Not (InStr(TextBox3.Text, "in") > 0 Or InStr(TextBox3.Text, "cm") > 0) Then
 TextBox3.Text = TextBox3.Text & " in"
 End If
End Select
End Sub


How to: Change the Order of Pages and Tabs

 Copy code hover
[image]

How to: Change the Order of Pages and Tabs
Send feedback

The following example uses the Index property to change the order of the pages and tabs in a MultiPage and TabStrip. The user chooses CommandButton1 to move the third page and tab to the front of the MultiPage and TabStrip. The user chooses CommandButton2 to move the selected page and tab to the back of the MultiPage and TabStrip.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains:

  • Two CommandButton controls named CommandButton1 and CommandButton2.

  • A MultiPage named MultiPage1.

  • A TabStrip named TabStrip1.

Copy code Copy code
Dim MyPageOrTab
Dim MultiPage1
Dim TabStrip1

Sub CommandButton1_Click()
'Move third page and tab to front of control
 MultiPage1.page3.Index = 0
 TabStrip1.Tab3.Index = 0
End Sub

Sub CommandButton2_Click()
'Move selected page and tab to back of control
 Set MyPageOrObject = MultiPage1.SelectedItem
 MsgBox "MultiPage1.SelectedItem = " & MultiPage1.SelectedItem.Name
 MyPageOrObject.Index = 4

 Set MyPageOrObject = TabStrip1.SelectedItem
 MsgBox "TabStrip1.SelectedItem = " & TabStrip1.SelectedItem.Caption
 MyPageOrObject.Index = 4
End Sub

Sub Item_Open()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("MultiPage1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TabStrip1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton1")
 Set CommandButton2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton2")

 MultiPage1.Width = 200
 MultiPage1.Pages.Add
 MultiPage1.Pages.Add
 MultiPage1.Pages.Add

 TabStrip1.Width = 200
 TabStrip1.Tabs.Add
 TabStrip1.Tabs.Add
 TabStrip1.Tabs.Add

 CommandButton1.Caption = "Move third page/tab to front"
 CommandButton1.Width = 120

 CommandButton2.Caption = "Move selected item to back"
 CommandButton2.Width = 120
 End Sub


How to: Add Items To a List or Combo Box at Run Time

 Copy code hover
[image]

How to: Add Items To a List or Combo Box at Run Time
Send feedback

In a ListBox or ComboBox with a single column, use the AddItem method to add an individual entry to the list.

In a multicolumn list box or combo box, you can use the List and Column properties to load the list from a two-dimensional array, as shown in the following steps.

  1. Create a multicolumn ListBox or ComboBox control.

  2. In VBScript, create a two-dimensional array that contains the items you want to put in the list.

  3. Set the ColumnCount property of the list box or combo box to match the number of entries in the list. To set the property, click the property and enter a value in the Apply box.

  4. Do one of the following:

    • Assign the array as the value of the List property. The contents of the list box will match the contents of the array exactly.

    • Assign the array as the value of the Column property. Column transposes rows and columns, so each row of the list box matches the corresponding column of the array.


How to: Use the Controls Collection to Move Controls on a Page

 Copy code hover
[image]

How to: Use the Controls Collection to Move Controls on a Page
Send feedback

The following example accesses individual controls from the Microsoft Forms 2.0 Controls collection using a For Each...Next loop. When the user presses CommandButton1, the other controls are placed in a column along the left edge of the form using the Move method of the control.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event of the item will activate. Make sure that the form contains a CommandButton named CommandButton1 and several other controls.

Copy code Copy code
Dim CtrlHeight
Dim CtrlTop
Dim CtrlGap
Dim CommandButton1

Sub Item_Open()
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1

 CtrlHeight = 20
 CtrlGap = 5

 CommandButton1.Caption = "Click to move controls"
 CommandButton1.AutoSize = True
 CommandButton1.Left = 120
 CommandButton1.Top = CtrlTop
End Sub

Sub CommandButton1_Click()
 Dim MyControl

 Set AllControls = Item.GetInspector.ModifiedFormPages("P.2").Controls

 CtrlTop = 5

 For i = 0 to AllControls.Count - 1
 Set MyControl = AllControls(i)
 If MyControl.Name = "CommandButton1" Then
 'Don't move or resize this control.
 Else
 'Move method using unnamed arguments (left, top, width, height)
 MyControl.Move 5, CtrlTop, ,CtrlHeight

 'Calculate top coordinate for next control
 CtrlTop = CtrlTop + CtrlHeight + CtrlGap
 End If
 Next

End Sub


How to: Change the Style, Size, and Effects of a Font

 Copy code hover
[image]

How to: Change the Style, Size, and Effects of a Font
Send feedback

The following example demonstrates a Font object and the Bold, Italic, Size, Strikethrough, Underline, and Weight properties related to fonts. You can manipulate font properties of an object directly or by using an alias, as this example also shows.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1.

  • Four ToggleButton controls named ToggleButton1 through ToggleButton4.

  • A second Label and a TextBox named Label2 and TextBox1.

Copy code Copy code
Dim MyFont
Dim ToggleButton1
Dim ToggleButton2
Dim ToggleButton3
Dim ToggleButton4
Dim Label1
Dim Label2
Dim TextBox1

Sub Item_Open()
 Set MyPage = Item.GetInspector.ModifiedFormPages("P.2")
 Set ToggleButton1 = MyPage.ToggleButton1
 Set ToggleButton2 = MyPage.ToggleButton2
 Set ToggleButton3 = MyPage.ToggleButton3
 Set ToggleButton4 = MyPage.ToggleButton4
 Set Label1 = MyPage.Label1
 Set Label2 = MyPage.Label2
 Set TextBox1 = MyPage.TextBox1
 Set MyFont = Label1.Font

 ToggleButton1.Value = True
 ToggleButton1.Caption = "Bold On"

 Label1.AutoSize = True 'Set size of Label1
 Label1.AutoSize = False

 ToggleButton2.Value = False
 ToggleButton2.Caption = "Italic Off"

 ToggleButton3.Value = False
 ToggleButton3.Caption = "StrikeThrough Off"

 ToggleButton4.Value = False
 ToggleButton4.Caption = "Underline Off"

 Label2.Caption = "Font Weight"
 TextBox1.Text = Label1.Font.Weight
 TextBox1.Enabled = False

End Sub

Sub ToggleButton1_Click()
 If ToggleButton1.Value = True Then
 MyFont.Bold = True 'Using MyFont alias to control font
 ToggleButton1.Caption = "Bold On"
 MyFont.Size = 22 'Increase the font size
 Else
 MyFont.Bold = False
 ToggleButton1.Caption = "Bold Off"
 MyFont.Size = 8 'Return font size to initial size
 End If

 TextBox1.Text = CStr(MyFont.Weight) 'Bold and Weight are related
End Sub

Sub ToggleButton2_Click()
 If ToggleButton2.Value = True Then
 Label1.Font.Italic = True 'Using Label1.Font directly
 ToggleButton2.Caption = "Italic On"
 Else
 Label1.Font.Italic = False
 ToggleButton2.Caption = "Italic Off"
 End If
End Sub

Sub ToggleButton3_Click()
 If ToggleButton3.Value = True Then
 Label1.Font.Strikethrough = True 'Using Label1.Font directly
 ToggleButton3.Caption = "StrikeThrough On"
 Else
 Label1.Font.Strikethrough = False
 ToggleButton3.Caption = "StrikeThrough Off"
 End If
End Sub

Sub ToggleButton4_Click()
 If ToggleButton4.Value = True Then
 MyFont.Underline = True 'Using MyFont alias for Label1.Font
 ToggleButton4.Caption = "Underline On"
 Else
 Label1.Font.Underline = False
 ToggleButton4.Caption = "Underline Off"
 End If
End Sub


How to: Control Character Matching in a Combo Box and List Box

 Copy code hover
[image]

How to: Control Character Matching in a Combo Box and List Box
Send feedback

The following example uses the MatchEntry property to demonstrate character matching that is available for ComboBox and ListBox. In this example, the user can set the type of matching with the OptionButton controls and then type into the ComboBox to specify an item from its list.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Three OptionButton controls named OptionButton1 through OptionButton3.

  • A ComboBox named ComboBox1.

Copy code Copy code
Sub OptionButton1_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 ComboBox1.MatchEntry = 2 '2=fmMatchEntryNone
End Sub

Sub OptionButton2_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 ComboBox1.MatchEntry = 0 '0=fmMatchEntryFirstLetter
End Sub

Sub OptionButton3_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 ComboBox1.MatchEntry = 1 '1=fmMatchEntryComplete
End Sub

Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")

 For i = 1 To 9
 ComboBox1.AddItem "Choice " & i
 Next
 ComboBox1.AddItem "Chocoholic"

 OptionButton1.Caption = "No matching"
 OptionButton1.Value = True

 OptionButton2.Caption = "Basic matching"
 OptionButton3.Caption = "Extended matching"
End Sub


How to: Control the Drop Button Style and When to Show the Drop Button

 Copy code hover
[image]

How to: Control the Drop Button Style and When to Show the Drop Button
Send feedback

The following example demonstrates the different symbols that you can specify for a drop-down arrow in a ComboBox or TextBox. In this example, the user chooses a drop-down arrow style from a ComboBox. This example also uses the TextBox.Locked property. To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains:

  • A ComboBox named ComboBox1.

  • A Label named Label1.

  • A TextBox named TextBox1 placed beneath Label1.

Copy code Copy code
Dim TextBox1
Dim ComboBox1
Dim Label1

Sub ComboBox1_Click()
 ComboBox1.DropButtonStyle = ComboBox1.Value
 TextBox1.DropButtonStyle = ComboBox1.Value
End Sub

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ComboBox1")
 Set Label1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("Label1")

 ComboBox1.ColumnCount = 2
 ComboBox1.BoundColumn = 2
 ComboBox1.TextColumn = 1

 ComboBox1.AddItem "Blank Button"
 ComboBox1.List(0, 1) = 0
 ComboBox1.AddItem "Down Arrow"
 ComboBox1.List(1, 1) = 1
 ComboBox1.AddItem "Ellipsis"
 ComboBox1.List(2, 1) = 2
 ComboBox1.AddItem "Underscore"
 ComboBox1.List(3, 1) = 3

 ComboBox1.Value = 0

 TextBox1.Text = "TextBox1"
 TextBox1.ShowDropButtonWhen = 2 'fmShowDropButtonWhenAlways
 TextBox1.Locked = True

 Label1.Caption = "TheDropButton also applies to a TextBox."
 Label1.AutoSize = True
 Label1.WordWrap = False
End Sub


How to: Control the Extent of Scrolling in a Scroll Bar

 Copy code hover
[image]

How to: Control the Extent of Scrolling in a Scroll Bar
Send feedback

The following example demonstrates the LargeChange and SmallChange properties when used with a stand-alone ScrollBar. The user can set the LargeChange and SmallChange values to any integer in the range of 0 to 100. This example also uses the TextBox.MaxLength property to restrict the number of characters entered in the TextBox controls for the LargeChange and SmallChange values.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1

  • A TextBox named TextBox1 that is bound to the custom number field named ScrollBarSmallChange

  • A Label named Label2

  • A TextBox named TextBox2 that is bound to the custom number field named ScrollBarLargeChange.

  • A ScrollBar named ScrollBar1 that is bound to the custom number field named ScrollBarValue.

  • A Label named Label3.

Copy code Copy code
Sub Item_Open()
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set ScrollBar1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ScrollBar1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set Label2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label2")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set Label3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label3")

 ScrollBar1.Min = -1000
 ScrollBar1.Max = 1000

 Label1.Caption = "SmallChange 0 to 100"
 ScrollBar1.SmallChange = 1
 TextBox1.Text = ScrollBar1.SmallChange
 TextBox1.MaxLength = 3

 Label2.Caption = "LargeChange 0 to 100"
 ScrollBar1.LargeChange = 100
 TextBox2.Text = ScrollBar1.LargeChange
 TextBox2.MaxLength = 3

 ScrollBar1.Value = 0
 Label3.Caption = ScrollBar1.Value
End Sub

Sub Item_CustomPropertyChange(byval pname)
 Set ScrollBar1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ScrollBar1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set Label3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label3")

 If pname = "ScrollBarMin" Then

 If IsNumeric(TextBox1.Text) Then
 TempNum = CInt(TextBox1.Text)
 If TempNum >= 0 And TempNum <= 100 Then
 ScrollBar1.SmallChange = TempNum
 Else
 TextBox1.Text = ScrollBar1.SmallChange
 End If
 Else
 TextBox1.Text = ScrollBar1.SmallChange
 End If

 ElseIf pname = "ScrollBarMax" Then

 If IsNumeric(TextBox2.Text) Then
 TempNum = CInt(TextBox2.Text)
 If TempNum >= 0 And TempNum <= 100 Then
 ScrollBar1.LargeChange = TempNum
 Else
 TextBox2.Text = ScrollBar1.LargeChange
 End If
 Else
 TextBox2.Text = ScrollBar1.LargeChange
 End If

 ElseIf pname = "ScrollBarValue" Then

 Label3.Caption = ScrollBar1.Value
 End If
End Sub


How to: Control the Focus When the User Cycles through Controls in a Frame or MultiPage Control on a Form

 Copy code hover
[image]

How to: Control the Focus When the User Cycles through Controls in a Frame or MultiPage Control on a Form
Send feedback

The following example defines the Cycle property for a Frame and two Page objects in a MultiPage.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Frame named Frame1.

  • A MultiPage named MultiPage1 that contains two objects named Page1 and Page2.

  • Two CommandButton controls named CommandButton1 and CommandButton2.

In the form, the Frame, and each Page of the MultiPage, place a couple of controls, so you can see how Cycle affects the tab order of the Frame and MultiPage.

The user should tab through the controls to observe how Cycle affects the tab order. Pressing CommandButton1 extends the tab order to include controls in the Frame and Page objects. Pressing CommandButton2 restricts the tab order.

Copy code Copy code
Dim Frame1
Dim MultiPage1

Sub Item_Open()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Frame1
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").MultiPage1
 RestrictCycles
End Sub

Sub RestrictCycles()
 'Limit tab order for the Frame and Page objects
 Frame1.Cycle = 2
 MultiPage1.Page1.Cycle = 2
 MultiPage1.Page2.Cycle = 2
End Sub
Sub CommandButton1_Click()
 'Extend tab order subforms (the Frame and Page objects)
 Frame1.Cycle = 0
 MultiPage1.Page1.Cycle = 0
 MultiPage1.Page2.Cycle = 0
End Sub

Sub CommandButton2_Click()
 RestrictCycles
End Sub


How to: Control the Selection Behavior and Drag Behavior When Entering a Text Box

 Copy code hover
[image]

How to: Control the Selection Behavior and Drag Behavior When Entering a Text Box
Send feedback

The following example uses the DragBehavior and EnterFieldBehavior properties to demonstrate the different effects that you can provide when entering a control and when dragging information from one control to another.

The sample uses two TextBox controls. You can set DragBehavior and EnterFieldBehavior for each control and see the effects of dragging from one control to another.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A TextBox named TextBox1.

  • Two ToggleButton controls named ToggleButton1 and ToggleButton2. These controls are associated with TextBox1.

  • A TextBox named TextBox2.

  • Two ToggleButton controls named ToggleButton3 and ToggleButton4. These controls are associated with TextBox2.

Copy code Copy code
Dim TextBox1, TextBox2
Dim ToggleButton1, ToggleButton2, ToggleButton3, ToggleButton4

Sub Item_Open()
 set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 set ToggleButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton2")
 set ToggleButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton3")
 set ToggleButton4 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton4")

 TextBox1.Text = "Once upon a time in a land ...,"
 ToggleButton1.Value = True
 ToggleButton1.Caption = "Drag Enabled"
 ToggleButton1.WordWrap = True
 TextBox1.DragBehavior = 1 'fmDragBehaviorEnabled

 ToggleButton2.Value = True
 ToggleButton2.Caption = "Recall Selection"
 ToggleButton2.WordWrap = True
 TextBox1.EnterFieldBehavior = 1 'fmEnterFieldBehaviorRecallSelection

 TextBox2.Text = "XXX, YYYY"
 ToggleButton3.Value = False
 ToggleButton3.Caption = "Drag Disabled"
 ToggleButton3.WordWrap = True
 TextBox2.DragBehavior = 0 'fmDragBehaviorDisabled

 ToggleButton4.Value = False
 ToggleButton4.Caption = "Select All"
 ToggleButton4.WordWrap = True
 TextBox2.EnterFieldBehavior = 0 'fmEnterFieldBehaviorSelectAll
End Sub

Sub ToggleButton1_Click()
 If ToggleButton1.Value = True Then
 ToggleButton1.Caption = "Drag Enabled"
 TextBox1.DragBehavior = 1 'fmDragBehaviorEnabled
 Else
 ToggleButton1.Caption = "Drag Disabled"
 TextBox1.DragBehavior = 0 'fmDragBehaviorDisabled
 End If
End Sub

Sub ToggleButton2_Click()
 If ToggleButton2.Value = True Then
 ToggleButton2.Caption = "Recall Selection"
 TextBox1.EnterFieldBehavior = 1 'fmEnterFieldBehaviorRecallSelection
 Else
 ToggleButton2.Caption = "Select All"
 TextBox1.EnterFieldBehavior = 0 'fmEnterFieldBehaviorSelectAll
 End If
End Sub

Sub ToggleButton3_Click()
 If ToggleButton3.Value = True Then
 ToggleButton3.Caption = "Drag Enabled"
 TextBox2.DragBehavior = 1 'fmDragBehaviorEnabled
 Else
 ToggleButton3.Caption = "Drag Disabled"
 TextBox2.DragBehavior = 0 'fmDragBehaviorDisabled
 End If
End Sub

Sub ToggleButton4_Click()
 If ToggleButton4.Value = True Then
 ToggleButton4.Caption = "Recall Selection"
 TextBox2.EnterFieldBehavior = 1 'fmEnterFieldBehaviorRecallSelection
 Else
 ToggleButton4.Caption = "Select All"
 TextBox2.EnterFieldBehavior = 0 'fmEnterFieldBehaviorSelectAll
 End If
End Sub


How to: Control the Style and Selection Behavior of a List Box

 Copy code hover
[image]

How to: Control the Style and Selection Behavior of a List Box
Send feedback

The following example uses the ListStyle and MultiSelect properties to control the appearance of a ListBox. The user chooses a value for ListStyle using the ToggleButton and chooses an OptionButton for one of the MultiSelect values. The appearance of the ListBox changes accordingly, as well as the selection behavior within the ListBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

  • A Label named Label1.

  • Three OptionButton controls named OptionButton1 through OptionButton3.

  • A ToggleButton named ToggleButton1.

Copy code Copy code
Sub Item_Open()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")

 For i = 1 To 8
 ListBox1.AddItem "Choice" & (ListBox1.ListCount + 1)
 Next

 Label1.Caption = "MultiSelect Choices"
 Label1.AutoSize = True

 ListBox1.MultiSelect = 0 '0=fmMultiSelectSingle
 OptionButton1.Caption = "Single entry"
 OptionButton1.Value = True
 OptionButton2.Caption = "Multiple entries"
 OptionButton3.Caption = "Extended entries"

 ToggleButton1.Caption = "ListStyle - Plain"
 ToggleButton1.Value = True
 ToggleButton1.Width = 90
 ToggleButton1.Height = 30
End Sub

Sub OptionButton1_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 0 '0=fmMultiSelectSingle
End Sub

Sub OptionButton2_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 1 '1=fmMultiSelectMulti
End Sub

Sub OptionButton3_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 ListBox1.MultiSelect = 2 '2=fmMultiSelectExtended
End Sub

Sub ToggleButton1_Click()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")

 If ToggleButton1.Value = True Then
 ToggleButton1.Caption = "Plain ListStyle"
 ListBox1.ListStyle = 0 '0=fmListStylePlain
 Else
 ToggleButton1.Caption = "OptionButton or CheckBox"
 ListBox1.ListStyle = 1 '1=fmListStyleOption
 End If
End Sub


How to: Control the Text Box' Behavior on Clicking Enter

 Copy code hover
[image]

How to: Control the Text Box' Behavior on Clicking Enter
Send feedback

The following example uses the EnterKeyBehavior property to control the effect of ENTER in a TextBox. In this example, the user can specify either a single-line or multiline TextBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A TextBox named TextBox1.

  • Two ToggleButton controls named ToggleButton1 and ToggleButton2.

Copy code Copy code
Dim TextBox1
Dim ToggleButton1
Dim ToggleButton2

Sub Item_Open()
 set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")
 set ToggleButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ToggleButton1")
 set ToggleButton2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ToggleButton2")
 TextBox1.EnterKeyBehavior = True
 ToggleButton1.Caption = "EnterKeyBehavior is True"
 ToggleButton1.Width = 70
 ToggleButton1.Value = True

 TextBox1.MultiLine = True
 ToggleButton2.Caption = "MultiLine is True"
 ToggleButton2.Width = 70
 ToggleButton2.Value = True

 TextBox1.Height = 100
 TextBox1.WordWrap = True
 TextBox1.Text = "Type your text here. If EnterKeyBehavior is True,"& _
 " press Enter to start a new line. Otherwise, press SHIFT+ENTER."
End Sub

Sub ToggleButton1_Click()
 If ToggleButton1.Value = True Then
 TextBox1.EnterKeyBehavior = True
 ToggleButton1.Caption = "EnterKeyBehavior is True"
 Else
 TextBox1.EnterKeyBehavior = False
 ToggleButton1.Caption = "EnterKeyBehavior is False"
 End If
End Sub

Sub ToggleButton2_Click()
 If ToggleButton2.Value = True Then
 TextBox1.MultiLine = True
 ToggleButton2.Caption = "MultiLine TextBox"
 Else
 TextBox1.MultiLine = False
 ToggleButton2.Caption = "Single-line TextBox"
 End If
End Sub


How to: Cut Text from One Text Box and Paste it on Another

 Copy code hover
[image]

How to: Cut Text from One Text Box and Paste it on Another
Send feedback

The following example uses the Cut and Paste methods to cut text from one TextBox and paste it on another TextBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Two TextBox controls named TextBox1 and TextBox2.

  • A CommandButton named CommandButton1.

Copy code Copy code
Dim TextBox1
Dim TextBox2
Dim CommandButton1

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox2")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton1")

 TextBox1.Text = "From TextBox1!"
 TextBox2.Text = "Hello "

 CommandButton1.Caption = "Cut and Paste"
 CommandButton1.AutoSize = True
End Sub

Sub CommandButton1_Click()
 TextBox2.SelStart = 0
 TextBox2.SelLength = TextBox2.TextLength
 TextBox2.Cut

 TextBox1.SetFocus
 TextBox1.SelStart = 0

 TextBox1.Paste
 TextBox2.SelStart = 0
End Sub


How to: Display the List Portion of a Combo Box

 Copy code hover
[image]

How to: Display the List Portion of a Combo Box
Send feedback

The following example uses the DropDown method to display the list in a ComboBox. The user can display the list of a ComboBox by clicking the CommandButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ComboBox named ComboBox1.

  • A CommandButton named CommandButton1.

Copy code Copy code
Dim ComboBox1

Sub CommandButton1_Click()
 ComboBox1.DropDown
End Sub

Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ComboBox1")
 ComboBox1.AddItem "Turkey"
 ComboBox1.AddItem "Chicken"
 ComboBox1.AddItem "Duck"
 ComboBox1.AddItem "Goose"
 ComboBox1.AddItem "Grouse"
End Sub


How to: Display the Name of Each Control on a Form or a Page of a MultiPage Control

 Copy code hover
[image]

How to: Display the Name of Each Control on a Form or a Page of a MultiPage Control
Send feedback

The following example uses the Item method to access individual members of the Microsoft Forms 2.0 Controls collection and Pages collection. The user chooses an option button for either the Controls collection or the MultiPage, and then clicks the CommandButton. The name of the appropriate control is returned in the Label.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A CommandButton named CommandButton1.

  • A Label named Label1.

  • Two OptionButton controls named OptionButton1 and OptionButton2.

  • A MultiPage named MultiPage1.

Copy code Copy code
Dim ControlsIndex

Sub CommandButton1_Click()
 Set Controls = Item.GetInspector.ModifiedFormPages("P.2").Controls
 Set OptionButton1 = Controls("OptionButton1")
 Set OptionButton2 = Controls("OptionButton2")
 Set Label1 = Controls("Label1")
 Set MultiPage1 = Controls("MultiPage1")

 If OptionButton1.Value = True Then
 'Process Controls collection for UserForm
 Set MyControl = Controls.Item(ControlsIndex)
 Label1.Caption = MyControl.Name

 'Prepare index for next control on Userform
 ControlsIndex = ControlsIndex + 1
 If ControlsIndex >= Controls.Count Then
 ControlsIndex = 0
 End If

 ElseIf OptionButton2.Value = True Then
 'Process Current Page of Pages collection
 Set MyControl = MultiPage1.Pages.Item(MultiPage1.Value)
 Label1.Caption = MyControl.Name
 End If
End Sub

Sub Item_Open()
 ControlsIndex = 0

 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 OptionButton1.Caption = "Controls Collection"
 OptionButton2.Caption = "Pages Collection"
 OptionButton1.Value = True

 CommandButton1.Caption = "Get Member Name"
End Sub


How to: Display the Name of Each Control on a Page

 Copy code hover
[image]

How to: Display the Name of Each Control on a Page
Send feedback

The following example displays the Name property of each control on a form. This example uses the Microsoft Forms 2.0 Controls collection to cycle through all the controls placed directly on the User form.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains a CommandButton named CommandButton1 and several other controls.

Copy code Copy code
Sub CommandButton1_Click()
 Set Controls = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls
 For i = 0 to Controls.Count - 1
 MsgBox "MyControl.Name = " & Controls.Item(i).Name
 Next
End Sub


How to: Display the Number of Pages and Tabs in MultiPage and TabStrip Controls on a Form

 Copy code hover
[image]

How to: Display the Number of Pages and Tabs in MultiPage and TabStrip Controls on a Form
Send feedback

The following example displays the Count property of the Microsoft Forms 2.0 Controls collection for the form, and the Count property identifying the number of pages and tabs of each MultiPage and TabStrip.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. The form can contain any number of controls, with the following restrictions:

  • Names of MultiPage controls must start with "MultiPage".

  • Names of TabStrip controls must start with "TabStrip".

Note Note

You can add pages to a MultiPage or add tabs to a TabStrip while in design mode. Double-click on the control, then right click in the tab area of the control and choose New Page from the shortcut menu.
Copy code Copy code
Sub Item_Open
 Dim Controls
 Dim MyControl

 Set Controls = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls
 MsgBox "Controls.Count = " & Controls.Count
 For i = 0 to Controls.Count -1
 Set MyControl = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls.Item(i)
 If (MyControl.Name = "MultiPage1") Then
 MsgBox MyControl.Name & ".Pages.Count = " & MyControl.Pages.Count
 ElseIf (MyControl.Name = "TabStrip1") Then
 MsgBox MyControl.Name & ".Tabs.Count = " & MyControl.Tabs.Count
 End If
 Next
End Sub


How to: Enable and Lock a Text Box from User Entry

 Copy code hover
[image]

How to: Enable and Lock a Text Box from User Entry
Send feedback

The following example demonstrates the Enabled and Locked properties and how they complement each other. This example exposes each property independently with a CheckBox, so you observe the settings individually and combined. This example also includes a second TextBox so you can copy and paste information between the TextBox controls and verify the activities supported by the settings of these properties.

Note Note

You can copy the selection to the Clipboard using CTRL+C and paste using CTRL+V.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains:

  • A TextBox named TextBox1.

  • Two CheckBox controls named CheckBox1 and CheckBox2.

  • A second TextBox named TextBox2.

Copy code Copy code
Dim TextBox1
Dim TextBox2
Dim CheckBox1
Dim CheckBox2

Sub CheckBox1_Click()
 TextBox2.Text = "TextBox2"
 TextBox1.Enabled = CheckBox1.Value
End Sub

Sub CheckBox2_Click()
 TextBox2.Text = "TextBox2"
 TextBox1.Locked = CheckBox2.Value
End Sub

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox2")
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CheckBox1")
 Set CheckBox2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CheckBox2")

 TextBox1.Text = "TextBox1"
 TextBox1.Enabled = True
 TextBox1.Locked = False

 CheckBox1.Caption = "Enabled"
 CheckBox1.Value = True

 CheckBox2.Caption = "Locked"
 CheckBox2.Value = False

 TextBox2.Text = "TextBox2"
End Sub


How to: Enhance the Border Style, Color, and Special Effects of a Text Box Control

 Copy code hover
[image]

How to: Enhance the Border Style, Color, and Special Effects of a Text Box Control
Send feedback

The following example demonstrates the BorderColor and SpecialEffect properties, showing each border available through these properties. The example also demonstrates how to control color settings by using the BackColor, BackStyle, BorderColor, and ForeColor properties.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Six TextBox controls named TextBox1 through TextBox6.

  • Two ToggleButton controls named ToggleButton1 and ToggleButton2.

Copy code Copy code
Dim TextBox1
Dim TextBox2
Dim TextBox3
Dim TextBox4
Dim TextBox5
Dim TextBox6
Dim ToggleButton1
Dim ToggleButton2

Sub Item_Open()
Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").TextBox1
Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").TextBox2
Set TextBox3 = Item.GetInspector.ModifiedFormPages("P.2").TextBox3
Set TextBox4 = Item.GetInspector.ModifiedFormPages("P.2").TextBox4
Set TextBox5 = Item.GetInspector.ModifiedFormPages("P.2").TextBox5
Set TextBox6 = Item.GetInspector.ModifiedFormPages("P.2").TextBox6
Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton1
Set ToggleButton2 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton2
'Initialize each TextBox with a border style or special effect,
'and foreground and background colors

'TextBox1 initially uses a borderstyle
TextBox1.Text = "BorderStyle-Single"
TextBox1.BorderStyle = 1
TextBox1.BorderColor = RGB(255, 128, 128) 'Color - Salmon
TextBox1.ForeColor = RGB(255, 255, 0) 'Color - Yellow
TextBox1.BackColor = RGB(0, 128, 64) 'Color - Green #2

'TextBoxes 2 through 6 initially use special effects
TextBox2.Text = "Flat"
TextBox2.SpecialEffect = 0
TextBox2.ForeColor = RGB(64, 0, 0) 'Color - Brown
TextBox2.BackColor = RGB(0, 0, 255) 'Color - Blue

'Ensure the background style for TextBox2 is initially opaque.
TextBox2.BackStyle = 1

TextBox3.Text = "Etched"
TextBox3.SpecialEffect = 3
TextBox3.ForeColor = RGB(128, 0, 255) 'Color - Purple
TextBox3.BackColor = RGB(0, 255, 255) 'Color - Cyan

'Define BorderColor for later use (when borderstyle=fmBorderStyleSingle)
TextBox3.BorderColor = RGB(0, 0, 0) 'Color - Black

TextBox4.Text = "Bump"
TextBox4.SpecialEffect = 6
TextBox4.ForeColor = RGB(255, 0, 255) 'Color - Magenta
TextBox4.BackColor = RGB(0, 0, 100) 'Color - Navy blue

TextBox5.Text = "Raised"
TextBox5.SpecialEffect = 1
TextBox5.ForeColor = RGB(255, 0, 0) 'Color - Red
TextBox5.BackColor = RGB(128, 128, 128) 'Color - Gray

TextBox6.Text = "Sunken"
TextBox6.SpecialEffect = 2
TextBox6.ForeColor = RGB(0, 64, 0) 'Color - Olive
TextBox6.BackColor = RGB(0, 255, 0) 'Color - Green #1

ToggleButton1.Caption = "Swap styles"
ToggleButton2.Caption = "Transparent/Opaque background"
End Sub

Sub ToggleButton1_Click()

'Swap borders between TextBox1 and TextBox3
If ToggleButton1.Value = True Then
 'Change TextBox1 from BorderStyle to Etched
 TextBox1.Text = "Etched"
 TextBox1.SpecialEffect = 3

 'Change TextBox3 from Etched to BorderStyle
 TextBox3.Text = "BorderStyle-Single"
 TextBox3.BorderStyle = 1
Else
 'Change TextBox1 back to BorderStyle
 TextBox1.Text = "BorderStyle-Single"
 TextBox1.BorderStyle = 1

 'Change TextBox3 back to Etched
 TextBox3.Text = "Etched"
 TextBox3.SpecialEffect = 3
End If
End Sub

Sub ToggleButton2_Click()

'Set background to Opaque or Transparent
If ToggleButton2.Value = True Then
 'Change TextBox2 to a transparent background
 TextBox2.BackStyle = 0
Else
 'Change TextBox2 back to opaque background
 TextBox2.BackStyle = 1
End If

End Sub


How to: Give a Control a 3-D Appearance Programmatically

 Copy code hover
[image]

How to: Give a Control a 3-D Appearance Programmatically
Send feedback

The following code example uses the ModifiedFormPages property of the current Inspector object to set the SpecialEffect property of a CheckBox on a page named "Test." By setting the SpecialEffect property to 2, the CheckBox will have a sunken effect.

Copy code Copy code
Item.GetInspector.ModifiedFormPpages("Test").Checkbox1.SpecialEffect = 2


How to: Group Option Buttons

 Copy code hover
[image]

How to: Group Option Buttons
Send feedback

The following example uses the GroupName property to create two groups of OptionButton controls on the same form.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains five OptionButton controls named OptionButton1 through OptionButton5.

Copy code Copy code
Sub Item_Open()
 set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")
 set OptionButton4 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton4")
 set OptionButton5 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton5")

 OptionButton1.Caption = "Widgets"
 OptionButton2.Caption = "Widgets"
 OptionButton3.Caption = "Widgets"
 OptionButton1.GroupName = "Widgets"
 OptionButton2.GroupName = "Widgets"
 OptionButton3.GroupName = "Widgets"

 OptionButton4.Caption = "Gadgets-Group2"
 OptionButton5.Caption = "Gadgets-Group2"
 OptionButton4.GroupName = "Gadgets-Group2"
 OptionButton5.GroupName = "Gadgets-Group2"
End Sub


How to: Hide or Show a Control Programmatically

 Copy code hover
[image]

How to: Hide or Show a Control Programmatically
Send feedback

The following code example uses the ModifiedFormPages property of the current Inspector object to set the Microsoft Forms 2.0 Visible property of a CheckBox on a page named "Test."

Copy code Copy code
Item.GetInspector.ModifiedFormPages("Test").Checkbox1.Visible = False


How to: Move a Text Box in Front of or Behind Another Control

 Copy code hover
[image]

How to: Move a Text Box in Front of or Behind Another Control
Send feedback

The following example sets the z-order of a TextBox, so the user can display the entire TextBox (by bringing it to the front of the z-order) or can place the TextBox behind other controls (by sending it to the back of the z-order).

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Three TextBox controls named TextBox1 through TextBox3.

  • A ToggleButton named ToggleButton1.

Copy code Copy code
Dim ToggleButton1
Dim TextBox1
Dim TextBox2
Dim TextBox3

Sub Item_Open()
Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").TextBox1
Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").TextBox2
Set TextBox3 = Item.GetInspector.ModifiedFormPages("P.2").TextBox3
Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").ToggleButton1

'Set up text boxes to show z-order in the form
TextBox1.Text = "TextBox 1"
TextBox2.Text = "TextBox 2"
TextBox3.Text = "TextBox 3"

TextBox1.Height = 40
TextBox2.Height = 40
TextBox3.Height = 40

TextBox1.Width = 60
TextBox2.Width = 60
TextBox3.Width = 60

TextBox1.Left = 10
TextBox1.Top = 10

TextBox2.Left = 25 'Overlap TextBox2 on TextBox1
TextBox2.Top = 25

TextBox3.Left = 40 'Overlap TextBox3 on TextBox2, TextBox1
TextBox3.Top = 40

ToggleButton1.Value = False
ToggleButton1.Caption = "Bring TextBox2 to Front"
ToggleButton1.Left = 10
ToggleButton1.Top = 90
ToggleButton1.Width = 50
ToggleButton1.Height = 50

End Sub

Sub ToggleButton1_Click()
If ToggleButton1.Value = True Then
 TextBox2.ZOrder (fmTop) 'Place TextBox2 on Top of z-order

 'Update ToggleButton caption to identify next state
 ToggleButton1.Caption = "Send TextBox2 to back"
Else
 TextBox2.ZOrder (1) 'Place TextBox2 on Bottom of z-order

 'Update ToggleButton caption to identify next state
 ToggleButton1.Caption = "Bring TextBox2 to front"
End If
End Sub


How to: Move Controls on a Page

 Copy code hover
[image]

How to: Move Controls on a Page
Send feedback

The following example demonstrates moving all the controls on a form by using the Move method with the Microsoft Forms 2.0 Controls collection. The user clicks on the CommandButton to move the controls.

To use this example, copy this sample code to the Script Editor of a form. Make sure that the form contains a CommandButton named CommandButton1 and several other controls.

Copy code Copy code
Sub CommandButton1_Click()
 Set Controls = Item.GetInspector.ModifiedFormPages("P.2").Controls
 'Move each control on the form right 25 points and up 25 points.
 Controls.Move 25, -25
End Sub


How to: Place an Image and a Caption on a Command Button

 Copy code hover
[image]

How to: Place an Image and a Caption on a Command Button
Send feedback

The following example uses a ComboBox to show the picture placement options for a control. Each time the user clicks a list choice, the picture and caption are updated on the CommandButton. This code sample also uses the AddItem method to populate the ComboBox choices.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1.

  • A CommandButton named CommandButton1 with the Picture property set to use an image on your computer.

  • A ComboBox named ComboBox1.

Copy code Copy code
Dim Label1
Dim CommandButton1
Dim ComboBox1

Sub Item_Open()
Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Label1
Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1
Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").ComboBox1

 Label1.Left = 18
 Label1.Top = 12
 Label1.Height = 12
 Label1.Width = 190
 Label1.Caption = "Select picture placement relative to the caption."

 'Add list entries to combo box. The value of each entry matches the
 'corresponding ListIndex value in the combo box.
 ComboBox1.AddItem "Left Top" 'ListIndex = 0
 ComboBox1.AddItem "Left Center" 'ListIndex = 1
 ComboBox1.AddItem "Left Bottom" 'ListIndex = 2
 ComboBox1.AddItem "Right Top" 'ListIndex = 3
 ComboBox1.AddItem "Right Center" 'ListIndex = 4
 ComboBox1.AddItem "Right Bottom" 'ListIndex = 5

 ComboBox1.AddItem "Above Left" 'ListIndex = 6
 ComboBox1.AddItem "Above Center" 'ListIndex = 7
 ComboBox1.AddItem "Above Right" 'ListIndex = 8
 ComboBox1.AddItem "Below Left" 'ListIndex = 9
 ComboBox1.AddItem "Below Center" 'ListIndex = 10
 ComboBox1.AddItem "Below Right" 'ListIndex = 11

 ComboBox1.AddItem "Centered" 'ListIndex = 12

 ComboBox1.Style = 2 'Use drop-down list

 ComboBox1.BoundColumn = 0 'Combo box values are ListIndex values
 ComboBox1.ListIndex = 0 'Set combo box to first entry
 ComboBox1.Left = 18
 ComboBox1.Top = 36
 ComboBox1.Width = 90
 ComboBox1.ListWidth = 90

 'Initialize CommandButton1
 CommandButton1.Left = 230
 CommandButton1.Top = 36
 CommandButton1.Height = 120
 CommandButton1.Width = 120

 'Note: Be sure to refer to have set the CommandButton1 to a bitmap file
 'Note: that is present on your system
 CommandButton1.PicturePosition = ComboBox1.Value
End Sub

Sub ComboBox1_Click()
 Select Case ComboBox1.Value
 Case 0 'Left Top
 CommandButton1.Caption = "Left Top"
 CommandButton1.PicturePosition = 0

 Case 1 'Left Center
 CommandButton1.Caption = "Left Center"
 CommandButton1.PicturePosition = 1

 Case 2 'Left Bottom
 CommandButton1.Caption = "Left Bottom"
 CommandButton1.PicturePosition = 2

 Case 3 'Right Top
 CommandButton1.Caption = "Right Top"
 CommandButton1.PicturePosition = 3

 Case 4 'Right Center
 CommandButton1.Caption = "Right Center"
 CommandButton1.PicturePosition = 4

 Case 5 'Right Bottom
 CommandButton1.Caption = "Right Bottom"
 CommandButton1.PicturePosition = 5

 Case 6 'Above Left
 CommandButton1.Caption = "Above Left"
 CommandButton1.PicturePosition = 6

 Case 7 'Above Center
 CommandButton1.Caption = "Above Center"
 CommandButton1.PicturePosition = 7

 Case 8 'Above Right
 CommandButton1.Caption = "Above Right"
 CommandButton1.PicturePosition = 8

 Case 9 'Below Left
 CommandButton1.Caption = "Below Left"
 CommandButton1.PicturePosition = 9

 Case 10 'Below Center
 CommandButton1.Caption = "Below Center"
 CommandButton1.PicturePosition = 10

 Case 11 'Below Right
 CommandButton1.Caption = "Below Right"
 CommandButton1.PicturePosition = 11

 Case 12 'Centered
 CommandButton1.Caption = "Centered"
 CommandButton1.PicturePosition = 12

 End Select

End Sub


How to: Reference a Custom Property that Has the Same Name as a Built-in Property of the Control

 Copy code hover
[image]

How to: Reference a Custom Property that Has the Same Name as a Built-in Property of the Control
Send feedback

Assume a new control has a Top property that is different from the standard Top property in Microsoft Forms. You can use either property, based on the syntax:

  • Copy code Copy code
    control.Top

    uses the standard Top property.

  • Copy code Copy code
    control.Object.Top

    uses the Top property from the added control.


How to: Reference the Parent Object of a Control

 Copy code hover
[image]

How to: Reference the Parent Object of a Control
Send feedback

The following example uses the Microsoft Forms 2.0 Parent property to refer to the control, form, or other object that contains a specific control or object.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Two Label controls named Label1 and Label2.

  • A CommandButton named CommandButton1.

  • One or more additional controls of your choice.

Copy code Copy code
Dim MyControl
Dim MyParent
Dim ControlsIndex

Sub Item_Open()
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1
 ControlsIndex = 0
 CommandButton1.Caption = "Get Control and Parent"
 CommandButton1.AutoSize = True
 CommandButton1.WordWrap = True
End Sub

Sub CommandButton1_Click()
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Label1
 Set Label2 = Item.GetInspector.ModifiedFormPages("P.2").Label2

 'Process Controls collection for UserForm
 Set MyControl = Item.GetInspector.ModifiedFormPages("P.2").Controls.Item(ControlsIndex)
 Set MyParent = MyControl.Parent
 Label1.Caption = MyControl.Name
 Label2.Caption = MyParent.Name

 'Prepare index for next control on Userform
 ControlsIndex = ControlsIndex + 1
 If ControlsIndex >= Item.GetInspector.ModifiedFormPages("P.2").Controls.Count Then
 ControlsIndex = 0
 End If
End Sub


How to: Set Entry Matching in a Combo Box

 Copy code hover
[image]

How to: Set Entry Matching in a Combo Box
Send feedback

The following example uses the MatchFound and MatchRequired properties to demonstrate additional character matching for ComboBox. The matching verification occurs in the Change event.

In this example, the user specifies whether the text portion of a ComboBox must match one of the listed items in the ComboBox. The user can specify whether matching is required by using a CheckBox and then type into the ComboBox to specify an item from its list.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ComboBox named ComboBox1 that is bound to the Subject field.

  • A CheckBox named CheckBox1.

Copy code Copy code
Sub CheckBox1_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")

 If CheckBox1.Value = True Then
 ComboBox1.MatchRequired = True
 MsgBox "To move the focus from the ComboBox, you must match an entry in the list or press ESC."
 Else
 ComboBox1.MatchRequired = False
 MsgBox " To move the focus from the ComboBox, just tab to or click another control. Matching is optional."
 End If
End Sub

Sub Item_PropertyChange(byval pname)
 if pname = "Subject" then
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 If ComboBox1.MatchRequired = True Then
 'MSForms handles this case automatically
 Else
 If ComboBox1.MatchFound = True Then
 MsgBox "Match Found; matching optional."
 Else
 MsgBox "Match not Found; matching optional."
 End If
 End If
 end if
End Sub

Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set CheckBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CheckBox1")

 For i = 1 To 9
 ComboBox1.AddItem "Choice " & i
 Next
 ComboBox1.AddItem "Chocoholic"

 CheckBox1.Caption = "MatchRequired"
 CheckBox1.Value = True
End Sub


How to: Set the Item at the Top of a List and the Item that Has Focus in the List

 Copy code hover
[image]

How to: Set the Item at the Top of a List and the Item that Has Focus in the List
Send feedback

The following example identifies the top item displayed in a ListBox and the item that has the focus within the ListBox. This example uses the TopIndex property to identify the item displayed at the top of the ListBox and the ListIndex property to identify the item that has the focus. The user selects an item in the ListBox. The displayed values of TopIndex and ListIndex are updated when the user selects an item or when the user clicks the CommandButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1.

  • A TextBox named TextBox1.

  • A Label named Label2.

  • A TextBox named TextBox2.

  • A CommandButton named CommandButton1.

  • A ListBox named ListBox1 that is bound to the Subject field.

Copy code Copy code
Sub CommandButton1_Click()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")

 ListBox1.TopIndex = ListBox1.ListIndex
 TextBox1.Text = ListBox1.TopIndex
 TextBox2.Text = ListBox1.ListIndex
End Sub

Sub Item_PropertyChange(byval pname)
 if pname = "Subject" then
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")

 TextBox1.Text = ListBox1.TopIndex
 TextBox2.Text = ListBox1.ListIndex
 end if
End Sub

Sub Item_Open()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ListBox1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set Label2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label2")

 For i = 0 To 24
 ListBox1.AddItem "Choice " & (i + 1)
 Next
 ListBox1.Height = 66
 CommandButton1.Caption = "Move to top of list"
 CommandButton1.AutoSize = True
 CommandButton1.TakeFocusOnClick = False

 Label1.Caption = "Index of top item"
 TextBox1.Text = ListBox1.TopIndex

 Label2.Caption = "Index of current item"
 Label2.AutoSize = True
 Label2.WordWrap = False
 TextBox2.Text = ListBox1.ListIndex
End Sub


How to: Set the Height and Width of Tabs in a MultiPage and a TabStrip Control

 Copy code hover
[image]

How to: Set the Height and Width of Tabs in a MultiPage and a TabStrip Control
Send feedback

The following example uses the TabFixedHeight and TabFixedWidth properties to set the size of the tabs used in MultiPage and TabStrip. The user clicks the SpinButton controls to adjust the height and width of the tabs within the MultiPage and TabStrip.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A MultiPage named MultiPage1.

  • A TabStrip named TabStrip1.

  • A Label named Label1 for the width control.

  • A SpinButton named SpinButton1 for the width control that is bound to a custom number field named SpinButtonWidth.

  • A TextBox named TextBox1 for the width control.

  • A Label named Label2 for the height control.

  • A SpinButton named SpinButton2 for the height control that is bound to a custom number field named SpinButtonHeight.

  • A TextBox named TextBox2 for the height control.

Copy code Copy code
Sub UpdateTabWidth()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")

 TextBox1.Text = SpinButton1.Value
 TabStrip1.TabFixedWidth = SpinButton1.Value
 MultiPage1.TabFixedWidth = SpinButton1.Value
End Sub

Sub UpdateTabHeight()
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set SpinButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton2")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")

 TextBox2.Text = SpinButton2.Value
 TabStrip1.TabFixedHeight = SpinButton2.Value
 MultiPage1.TabFixedHeight = SpinButton2.Value
End Sub

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set SpinButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton2")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set Label2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label2")

 MultiPage1.Style = 1 '1=fmTabStyleButtons

 Label1.Caption = "Tab Width"
 SpinButton1.Min = 0
 SpinButton1.Max = TabStrip1.Width / TabStrip1.Tabs.Count
 SpinButton1.Value = 0
 TextBox1.Locked = True

 UpdateTabWidth

 Label2.Caption = "Tab Height"
 SpinButton2.Min = 0
 SpinButton2.Max = TabStrip1.Height
 SpinButton2.Value = 0
 TextBox2.Locked = True

 UpdateTabHeight
End Sub

Sub Item_CustomPropertyChange(byval pname)
'msgbox pname
 If pname = "SpinButtonWidth" Then
 UpdateTabWidth
 ElseIf pname = "SpinButtonHeight" Then
 UpdateTabHeight
 End If
End Sub


How to: Set the Input Style for a Combo Box

 Copy code hover
[image]

How to: Set the Input Style for a Combo Box
Send feedback

The following example uses the Style property to change the style of user input of a ComboBox. The user chooses a style by selecting an OptionButton control and then types into the ComboBox to select an item. When Style is StyleDropDownList, the user must choose an item from the drop-down list. When Style is StyleDropDownCombo, the user can type into the text area to specify an item in the drop-down list.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • Two OptionButton controls named OptionButton1 and OptionButton2.

  • A ComboBox named ComboBox1.

Copy code Copy code
Sub OptionButton1_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 ComboBox1.Style = 0 '0=fmStyleDropDownCombo
End Sub

Sub OptionButton2_Click()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 ComboBox1.Style = 2 '2=fmStyleDropDownList
End Sub

Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")

 For i = 1 To 10
 ComboBox1.AddItem "Choice " & i
 Next

 OptionButton1.Caption = "Select like ComboBox"
 OptionButton1.Value = True
 ComboBox1.Style = 0 '0=fmStyleDropDownCombo

 OptionButton2.Caption = "Select like ListBox"
End Sub


How to: Set the Maximum and Minimum Values for a Scroll Bar

 Copy code hover
[image]

How to: Set the Maximum and Minimum Values for a Scroll Bar
Send feedback

The following example demonstrates the Max and Min properties when used with a stand-alone ScrollBar. The user can set the Max and Min values to any integer in the range of -1000 to 1000. This example also uses the TextBox.MaxLength property to restrict the number of characters entered for the Max and Min values.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1

  • A TextBox named TextBox1 that is bound to the custom number field named ScrollBarMin.

  • A Label named Label2

  • A TextBox named TextBox2 that is bound to the custom number field named ScrollBarMax.

  • A ScrollBar named ScrollBar1 that is bound to the custom number field named ScrollBarValue.

  • A Label named Label3.

Copy code Copy code
Sub Item_Open()
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set ScrollBar1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ScrollBar1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set Label2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label2")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set Label3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label3")

 Label1.Caption = "Min -1000 to 1000"
 ScrollBar1.Min = -1000
 TextBox1.Text = ScrollBar1.Min
 TextBox1.MaxLength = 5

 Label2.Caption = "Max -1000 to 1000"
 ScrollBar1.Max = 1000
 TextBox2.Text = ScrollBar1.Max
 TextBox2.MaxLength = 5

 ScrollBar1.SmallChange = 1
 ScrollBar1.LargeChange = 100
 ScrollBar1.Value = 0
 Label3.Caption = ScrollBar1.Value
End Sub

Sub Item_CustomPropertyChange(byval pname)
 Set ScrollBar1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ScrollBar1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set TextBox2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox2")
 Set Label3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label3")

 If pname = "ScrollBarMin" Then

 If IsNumeric(TextBox1.Text) Then
 TempNum = CInt(TextBox1.Text)
 If TempNum >= -1000 And TempNum <= 1000 Then
 ScrollBar1.Min = TempNum
 Else
 TextBox1.Text = ScrollBar1.Min
 End If
 Else
 TextBox1.Text = ScrollBar1.Min
 End If
 ElseIf pname = "ScrollBarMax" Then

 If IsNumeric(TextBox2.Text) Then
 TempNum = CInt(TextBox2.Text)
 If TempNum >= -1000 And TempNum <= 1000 Then
 ScrollBar1.Max = TempNum
 Else
 TextBox2.Text = ScrollBar1.Max
 End If
 Else
 TextBox2.Text = ScrollBar1.Max
 End If
 ElseIf pname = "ScrollBarValue" Then

 Label3.Caption = ScrollBar1.Value
 End If
End Sub


How to: Set the Number of Lines and the Length of Input in a Text Box

 Copy code hover
[image]

How to: Set the Number of Lines and the Length of Input in a Text Box
Send feedback

The following example counts the characters and the number of lines of text in a TextBox by using the LineCount and TextLength properties, and the SetFocus method. In this example, the user can type into a TextBox, and can retrieve current values of the LineCount and TextLength properties.

Note Note

The SetFocus method is inherited from the Microsoft Forms 2.0 TextBox control.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains the following controls:

  • A TextBox named TextBox1.

  • A CommandButton named CommandButton1.

  • Two Label controls named Label1 and Label2.

Copy code Copy code
'Type SHIFT+ENTER to start a new line in the text box.

Dim CommandButton1
Dim TextBox1
Dim Label1
Dim Label2

Sub CommandButton1_Click()
 'Must first give TextBox1 the focus to get line count
 TextBox1.SetFocus
 Label1.Caption = "LineCount = " & TextBox1.LineCount
 Label2.Caption = "TextLength = " & TextBox1.TextLength
End Sub

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")
 Set Label1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("Label1")
 Set Label2 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("Label2")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("CommandButton1")

 CommandButton1.WordWrap = True
 CommandButton1.AutoSize = True
 CommandButton1.Caption = "Get Counts"

 Label1.Caption = "LineCount = "
 Label2.Caption = "TextLength = "

 TextBox1.MultiLine = True
 TextBox1.WordWrap = True
 TextBox1.Text = "Enter your text here."
End Sub


How to: Set the Style of Tabs for a MultiPage and a TabStrip Control

 Copy code hover
[image]

How to: Set the Style of Tabs for a MultiPage and a TabStrip Control
Send feedback

The following example uses the Style property to specify the appearance of the tabs in MultiPage and TabStrip. This example also demonstrates using a Label. The user chooses a style by selecting an OptionButton.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1.

  • Three OptionButton controls named OptionButton1 through OptionButton3.

  • A MultiPage named MultiPage1.

  • A TabStrip named TabStrip1.

  • Any control inside the TabStrip.

  • Any control in each page of the MultiPage.

Copy code Copy code
Sub OptionButton1_Click()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 MultiPage1.Style = 0 '0=fmTabStyleTabs
 TabStrip1.Style = 0 '0=fmTabStyleTabs
End Sub

Sub OptionButton2_Click()
 'Note that the page borders are invisible
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 MultiPage1.Style = 1 '1=fmTabStyleButtons
 TabStrip1.Style = 1 '1=fmTabStyleButtons
End Sub

Sub OptionButton3_Click()
 'Note that the page borders are invisible and
 'the page body begins where the tabs normally appear.
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")
 MultiPage1.Style = 2 '2=fmTabStyleNone
 TabStrip1.Style = 2 '2=fmTabStyleNone
End Sub

Sub Item_Open()
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton1")
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton2")
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("OptionButton3")
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")
 Set TabStrip1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TabStrip1")

 Label1.Caption = "Page/Tab Style"
 OptionButton1.Caption = "Tabs"
 OptionButton1.Value = True
 MultiPage1.Style = 0 '0=fmTabStyleTabs
 TabStrip1.Style = 0 '0=fmTabStyleTabs

 OptionButton2.Caption = "Buttons"
 OptionButton3.Caption = "No Tabs or Buttons"
End Sub


How to: Set the Tab Order of Controls in a Frame

 Copy code hover
[image]

How to: Set the Tab Order of Controls in a Frame
Send feedback

The following example uses the TabIndex property to display and set the tab order for individual controls. The TabIndex property is a Microsoft Forms 2.0 property that applies to every control that can exist in a Frame. The user can press TAB to reach the next control in the tab order and to display the TabIndex of that control. The user can also click on any control, except a TextBox or ScrollBar, to display its TabIndex. The user can change the TabIndex of a control by specifying a new index value in the TextBox and clicking CommandButton3. Changing the TabIndex for one control also updates the TabIndex for other controls in the Frame.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A Label named Label1.

  • A TextBox named TextBox1.

  • A Frame named Frame1.

  • A TextBox in the Frame named TextBox2.

  • Two CommandButton controls in the Frame named CommandButton1 and CommandButton2.

  • A ScrollBar in the Frame named ScrollBar1.

  • A CommandButton (not in the Frame) named CommandButton3.

Copy code Copy code
Sub MoveToFront()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")

 Temp = Frame1.ActiveControl.TabIndex
 For i = 0 To Temp - 1
 Frame1.Controls.Item(i).TabIndex = i + 1
 Next

 Frame1.ActiveControl.TabIndex = 0
 TextBox1.Text = Frame1.ActiveControl.TabIndex
End Sub

Sub CommandButton3_Click()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")

 If IsNumeric(TextBox1.Text) Then
 Temp = CInt(TextBox1.Text)

 If Temp >= Frame1.Controls.Count Or Temp < 0 Then
 'Entry out of range; move control to front of tab order
 MoveToFront
 ElseIf Temp > Frame1.ActiveControl.TabIndex Then
 'Move entry down the list
 For i = Frame1.ActiveControl.TabIndex + 1 To Temp
 Frame1.Controls.Item(i).TabIndex = i - 1
 Next
 Frame1.ActiveControl.TabIndex = Temp
 TextBox1.Text = Frame1.ActiveControl.TabIndex
 Else
 'Move Entry up the list
 For i = Frame1.ActiveControl.TabIndex - 1 To Temp
 Frame1.Controls.Item(i).TabIndex = i + 1
 Next
 Frame1.ActiveControl.TabIndex = Temp
 TextBox1.Text = Frame1.ActiveControl.TabIndex
 End If
 Else
 'Text entry; move control to front of tab order
 MoveToFront
 End If
End Sub

Sub Item_Open()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")
 Set CommandButton3 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton3")

 Label1.Caption = "TabIndex"

 Frame1.Controls(0).SetFocus
 TextBox1.Text = Frame1.ActiveControl.TabIndex

 Frame1.Cycle = 2 '2=fmCycleCurrentForm

 CommandButton3.Caption = "Set TabIndex"
 CommandButton3.TakeFocusOnClick = False
End Sub

Sub CommandButton1_Click()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")

 TextBox1.Text = Frame1.ActiveControl.TabIndex
End Sub

Sub CommandButton2_Click()
 Set Frame1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Frame1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")

 TextBox1.Text = Frame1.ActiveControl.TabIndex
End Sub


How to: Set the Type of Mouse Pointer for a List Box

 Copy code hover
[image]

How to: Set the Type of Mouse Pointer for a List Box
Send feedback

The following example demonstrates how to specify a mouse pointer that is appropriate for a specific control or situation. For the ListBox control, you can assign one of several available mouse pointers using the ListBox.MousePointer property.

This example works in the following ways:

  • Choose a mouse pointer from the ListBox to change the mouse pointer associated with the ListBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

Copy code Copy code
Dim ListBox1

Sub Item_Open()
 set ListBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ListBox1")
 'Load ListBox with MousePointer choices
 ListBox1.Clear
 ListBox1.AddItem "Default"
 ListBox1.AddItem "Arrow"
 ListBox1.AddItem "Cross"
 ListBox1.AddItem "IBeam"
 ListBox1.AddItem "SizeNESW"
 ListBox1.AddItem "SizeNS"
 ListBox1.AddItem "SizeNWSE"
 ListBox1.AddItem "SizeWE"
 ListBox1.AddItem "UpArrow"
 ListBox1.AddItem "Hourglass"
 ListBox1.AddItem "NoDrop"
 ListBox1.AddItem "AppStarting"
 ListBox1.AddItem "Help"
 ListBox1.AddItem "SizeAll"
End Sub

Sub ListBox1_Click()
 If IsNull(ListBox1.Value) = False Then
 Select Case ListBox1.Value
 Case "Default"
 pointer = 0 'Standard pointer.
 Case "Arrow"
 pointer = 1 'Arrow.
 Case "Cross"
 pointer = 2 'Cross-hair pointer.
 Case "IBeam"
 pointer = 3 'I-beam.
 Case "SizeNESW"
 pointer = 6 'Double arrow pointing northeast and southwest.
 Case "SizeNS"
 pointer = 7 'Double arrow pointing north and south.
 Case "SizeNWSE"
 pointer = 8 'Double arrow pointing northwest and southeast.
 Case "SizeWE"
 pointer = 9 'Double arrow pointing west and east.
 Case "UpArrow"
 pointer = 10 'Up arrow.
 Case "Hourglass"
 pointer = 11 'Hourglass.
 Case "NoDrop"
 pointer = 12 '"Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
 Case "AppStarting"
 pointer = 13 'Arrow with an hourglass.
 Case "Help"
 pointer = 14 'Arrow with a question mark.
 Case "SizeAll"
 pointer = 15 'Size all cursor (arrows pointing north, south, east, and west).
 End Select
 ListBox1.MousePointer = pointer
 End If
End Sub


How to: Set the Width of the Drop-Down List of a Combo Box

 Copy code hover
[image]

How to: Set the Width of the Drop-Down List of a Combo Box
Send feedback

The following example uses a SpinButton to control the width of the drop-down list of a ComboBox. The user changes the value of the SpinButton, then clicks on the drop-down arrow of the ComboBox to display the list.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ComboBox named ComboBox1.

  • A SpinButton named SpinButton1 that is bound to a custom number field named SpinButtonValue.

  • A Label named Label1.

Copy code Copy code
Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")

 For i = 1 To 20
 ComboBox1.AddItem "Choice " & (ComboBox1.ListCount + 1)
 Next
 SpinButton1.Min = 0
 SpinButton1.Max = 130

 'convert listwidth value from '122 pt' to an integer
 intpos = instr(combobox1.listwidth," ")
 intwidth = left(combobox1.listwidth,intpos-1)
 SpinButton1.Value = intwidth
 SpinButton1.SmallChange = 5
 Label1.Caption = "ListWidth = " & SpinButton1.Value
End Sub

Sub Item_CustomPropertyChange(byval pname)
 If pname = "SpinButtonValue" Then
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")

 ComboBox1.ListWidth = SpinButton1.Value
 Label1.Caption = "ListWidth = " & SpinButton1.Value
 End If
End Sub


How to: Simulate a Two-Dimensional Array with List Boxes

 Copy code hover
[image]

How to: Simulate a Two-Dimensional Array with List Boxes
Send feedback

The following example loads a two-dimensional array with data and, in turn, loads two ListBox controls using the Column and List properties. Note that the Column property transposes the array elements during loading.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains two ListBox controls named ListBox1 and ListBox2.

Copy code Copy code
Dim MyArray(6,3)

Sub Item_Open()
 Dim i

 Set ListBox1 = Item.GetInspector.ModifiedFormPages("P.2").ListBox1
 Set ListBox2 = Item.GetInspector.ModifiedFormPages("P.2").ListBox2

 ListBox1.ColumnCount = 3 'The 1st list box contains 3 data columns
 ListBox2.ColumnCount = 6 'The 2nd box contains 6 data columns

 'Load integer values into first column of MyArray
 For i = 0 To 5
 MyArray(i, 0) = i
 Next

 'Load columns 2 and three of MyArray
 MyArray(0, 1) = "Zero"
 MyArray(1, 1) = "One"
 MyArray(2, 1) = "Two"
 MyArray(3, 1) = "Three"
 MyArray(4, 1) = "Four"
 MyArray(5, 1) = "Five"

 MyArray(0, 2) = "Zero"
 MyArray(1, 2) = "Un ou Une"
 MyArray(2, 2) = "Deux"
 MyArray(3, 2) = "Trois"
 MyArray(4, 2) = "Quatre"
 MyArray(5, 2) = "Cinq"

 'Load data into ListBox1 and ListBox2
 ListBox1.List() = MyArray
 ListBox2.Column() = MyArray

End Sub


How to: Specify Additional Information for a Control

 Copy code hover
[image]

How to: Specify Additional Information for a Control
Send feedback

The following example uses the Tag property to store additional information about each control on the Microsoft Forms 2.0 UserForm. The user clicks a control and then clicks the CommandButton. The contents of Tag for the appropriate control are returned in the TextBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A TextBox named TextBox1.

  • A CommandButton named CommandButton1.

  • A ScrollBar named ScrollBar1.

  • A ComboBox named ComboBox1.

  • A MultiPage named MultiPage1.

Copy code Copy code
Sub CommandButton1_Click()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set MultiPage1= Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")

 TextBox1.Text = Item.GetInspector.ModifiedFormPages("P.2").ActiveControl.Tag
End Sub

Sub Item_Open()
 Set TextBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("TextBox1")
 Set CommandButton1= Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")
 Set ComboBox1= Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set ScrollBar1= Item.GetInspector.ModifiedFormPages("P.2").Controls("ScrollBar1")
 Set MultiPage1= Item.GetInspector.ModifiedFormPages("P.2").Controls("MultiPage1")

 TextBox1.Locked = True
 TextBox1.Tag = "Display area for Tag properties."
 TextBox1.AutoSize = True

 CommandButton1.Caption = "Show Tag of Current Control."
 CommandButton1.AutoSize = True
 CommandButton1.WordWrap = True
 CommandButton1.TakeFocusOnClick = False
 CommandButton1.Tag = "Shows tag of control that has the focus."

 ComboBox1.Style = fmStyleDropDownList
 ComboBox1.Tag = "ComboBox Style is that of a ListBox."

 ScrollBar1.Max = 100
 ScrollBar1.Min = -273
 ScrollBar1.Tag = "Max = " & ScrollBar1.Max & " , Min = " & ScrollBar1.Min

 MultiPage1.Pages.Add
 MultiPage1.Pages.Add
 MultiPage1.Tag = "This MultiPage has " & MultiPage1.Pages.Count & " pages."
End Sub


How to: Specify Control Tip Text for Controls

 Copy code hover
[image]

How to: Specify Control Tip Text for Controls
Send feedback

The following example defines the ControlTipText property for three CommandButton controls and two Page objects in a MultiPage.

Note Note

The Microsoft Forms 2.0 CommandButton control includes the ControlTipText property.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A MultiPage named MultiPage1.

  • Three CommandButton controls named CommandButton1 through CommandButton3.

Note Note

For an individual Page of a MultiPage, ControlTipText becomes enabled when the MultiPage or a control on the current page of the MultiPage has the focus.
Copy code Copy code
Sub Item_Open()
 Set MultiPage1 = Item.GetInspector.ModifiedFormPages("P.2").MultiPage1
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton1
 Set CommandButton2 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton2
 Set CommandButton3 = Item.GetInspector.ModifiedFormPages("P.2").CommandButton3

 MultiPage1.Page1.ControlTipText = "Here in page 1"
 MultiPage1.Page2.ControlTipText = "Now in page 2"

 CommandButton1.ControlTipText = "And now here's"
 CommandButton2.ControlTipText = "a tip from"
 CommandButton3.ControlTipText = "your controls!"
End Sub


How to: Specify Possible Values for a List Box

 Copy code hover
[image]

How to: Specify Possible Values for a List Box
Send feedback

The following example fills a ListBox control with the values "Test1", "Test2", and "Test3" when you open the form.

Copy code Copy code
Sub Item_Open()

 ' Sets the name of page on the form, in this case, the
 ' Message page on a MailItem form.
 Set FormPage = Item.GetInspector.ModifiedFormPages("Message")

 ' Sets Control to a list box called ListBox1.
 Set Control = FormPage.Controls("ListBox1")

 ' Assign values to the list box.
 Control.PossibleValues = "Test1;Test2;Test3"

End Sub


How to: Specify Tab Support for a Control

 Copy code hover
[image]

How to: Specify Tab Support for a Control
Send feedback

The following example uses the TabStop property to control whether a user can press TAB to move the focus to a particular control. The TabIndex property is a Microsoft Forms 2.0 property that applies to every control that supports tabbing. The user presses TAB to move the focus among the controls on the form, and then clicks the ToggleButton to change TabStop for CommandButton1. When TabStop is False, CommandButton1 will not receive the focus by using TAB.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A CommandButton named CommandButton1.

  • A ToggleButton named ToggleButton1.

  • One or two other controls, such as an OptionButton or ListBox.

Copy code Copy code
Sub CommandButton1_Click()
 MsgBox "Clicked CommandButton1."
End Sub

Sub ToggleButton1_Click()
 Dim CommandButton1
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 If ToggleButton1 = True Then
 CommandButton1.TabStop = True
 ToggleButton1.Caption = "TabStop On"
 Else
 CommandButton1.TabStop = False
 ToggleButton1.Caption = "TabStop Off"
 End If
End Sub

Sub Item_Open()
 Set ToggleButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ToggleButton1")
 Set CommandButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("CommandButton1")

 CommandButton1.Caption = "Show Message"

 ToggleButton1.Caption = "TabStop On"
 ToggleButton1.Value = True
 ToggleButton1.Width = 90
End Sub


How to: Specify the Column in a Multi-Column List Box to Display to the User

 Copy code hover
[image]

How to: Specify the Column in a Multi-Column List Box to Display to the User
Send feedback

The following example uses the TextColumn property to identify the column of data in a ListBox that supplies data for its Text property. This example sets the third column of the ListBox as the text column. As you select an entry from the ListBox, the value from the TextColumn will be displayed in the TextBox.

This example also demonstrates how to load a multicolumn ListBox using the AddItem method and the List property.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

  • A TextBox named TextBox1.

Copy code Copy code
Dim ListBox1
Dim TextBox1

Sub Item_Open()
 Set ListBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("ListBox1")
 Set TextBox1 = Item.GetInspector.ModifiedFormPages.Item("P.2").Controls("TextBox1")

 ListBox1.ColumnCount = 3

 ListBox1.AddItem "Row 1, Col 1"
 ListBox1.List(0, 1) = "Row 1, Col 2"
 ListBox1.List(0, 2) = "Row 1, Col 3"

 ListBox1.AddItem "Row 2, Col 1"
 ListBox1.List(1, 1) = "Row 2, Col 2"
 ListBox1.List(1, 2) = "Row 2, Col 3"

 ListBox1.AddItem "Row 3, Col 1"
 ListBox1.List(2, 1) = "Row 3, Col 2"
 ListBox1.List(2, 2) = "Row 3, Col 3"

 ListBox1.TextColumn = 3

End Sub

Sub ListBox1_Click()
 TextBox1.Text = ListBox1.Text
End Sub


How to: Specify the Column in a Multi-Column List Box to Store Data for the Control

 Copy code hover
[image]

How to: Specify the Column in a Multi-Column List Box to Store Data for the Control
Send feedback

The following example demonstrates how the BoundColumn property influences the value of a ListBox. The user can choose to set the value of the ListBox to the index value of the specified row, or to a specified column of data in the ListBox.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ListBox named ListBox1.

  • A Label named Label1.

  • Three OptionButton controls named OptionButton1, OptionButton2, and OptionButton3.

Copy code Copy code
Dim Listbox1
Dim OptionButton1
Dim OptionButton2
Dim OptionButton3
Dim Label1

Sub Item_Open
 Set Listbox1 = Item.GetInspector.ModifiedFormPages("P.2").Listbox1
 Set OptionButton1 = Item.GetInspector.ModifiedFormPages("P.2").OptionButton1
 Set OptionButton2 = Item.GetInspector.ModifiedFormPages("P.2").OptionButton2
 Set OptionButton3 = Item.GetInspector.ModifiedFormPages("P.2").OptionButton3
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Label1

 Listbox1.ColumnCount = 2
 Listbox1.AddItem "Item 1, Column 1"
 Listbox1.List(0, 1) = "Item 1, Column 2"
 Listbox1.AddItem "Item 2, Column 1"
 Listbox1.List(1, 1) = "Item 2, Column 2"
 Listbox1.Value = "Item 1, Column 1"
 OptionButton1.Caption = "List Index"
 OptionButton2.Caption = "Column 1"
 OptionButton3.Caption = "Column 2"
 OptionButton2.Value = True
End Sub

Sub OptionButton1_Click
 Listbox1.BoundColumn = 0
 Label1.Caption = Listbox1.Value
End Sub

Sub OptionButton2_Click
 Listbox1.BoundColumn = 1
 Label1.Caption = Listbox1.Value
End Sub

Sub OptionButton3_Click
 Listbox1.BoundColumn = 2
 Label1.Caption = Listbox1.Value
End Sub

Sub Listbox1_Click
 Label1.Caption = Listbox1.Value
End Sub


How to: Specify the Number of Rows in a Combo Box

 Copy code hover
[image]

How to: Specify the Number of Rows in a Combo Box
Send feedback

The following example uses a SpinButton to control the number of rows in the drop-down list of a ComboBox. The user changes the value of the SpinButton, then clicks on the drop-down arrow of the ComboBox to display the list.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A ComboBox named ComboBox1.

  • A SpinButton named SpinButton1 that is bound to a custom number field named SpinButtonValue.

  • A Label named Label1.

Copy code Copy code
Sub Item_Open()
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")

 For i = 1 To 20
 ComboBox1.AddItem "Choice " & (ComboBox1.ListCount + 1)
 Next

 SpinButton1.Min = 0
 SpinButton1.Max = 12
 SpinButton1.Value = ComboBox1.ListRows
 Label1.Caption = "ListRows = " & SpinButton1.Value
End Sub

Sub Item_CustomPropertyChange(byval pname)
 If pname = "SpinButtonValue" Then
 Set ComboBox1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("ComboBox1")
 Set SpinButton1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("SpinButton1")
 Set Label1 = Item.GetInspector.ModifiedFormPages("P.2").Controls("Label1")

 ComboBox1.ListRows = SpinButton1.Value
 Label1.Caption = "ListRows = " & SpinButton1.Value
 End If
End Sub


How to: Swap Columns of a Multicolumn List Box

 Copy code hover
[image]

How to: Swap Columns of a Multicolumn List Box
Send feedback

The following example swaps columns of a multicolumn ListBox. The sample uses the List property in two ways:

  1. To access and exchange individual values in the ListBox. In this usage, List has subscripts to designate the row and column of a specified value.

  2. To initially load the ListBox with values from an array. In this usage, List has no subscripts.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains a ListBox named ListBox1 and a CommandButton named CommandButton1.

Copy code Copy code
Dim Listbox1
Dim MyArray(6, 3)

Sub Item_Open
 Dim i
 Set Listbox1 = Item.GetInspector.ModifiedFormPages("P.2").Listbox1

 Listbox1.ColumnCount = 3
 For i = 0 to 5
 MyArray(i, 0) = i
 MyArray(i, 1) = Rnd
 MyArray(i, 2) = Rnd
 Next

 Listbox1.List() = MyArray
End Sub

Sub CommandButton1_Click
 Dim i
 Dim Temp

 For i = 0 to 5
 Temp = Listbox1.List(i, 0)
 Listbox1.List(i, 0) = Listbox1.List(i, 2)
 Listbox1.List(i, 2) = Temp
 Next
End Sub


How to: Undo and Redo an Action in a Text Box or a Combo Box

 Copy code hover
[image]

How to: Undo and Redo an Action in a Text Box or a Combo Box
Send feedback

The following example demonstrates how to undo or redo text editing within a TextBox or within the text area of a ComboBox. This sample checks whether an undo or redo operation can occur and then performs the appropriate action. The sample uses the CanUndo and CanRedo properties, and the UndoAction and RedoAction methods.

To use this example, copy this sample code to the Script Editor of a form. To run the code you need to open the form so the Open event will activate. Make sure that the form contains:

  • A TextBox named TextBox1.

  • A ComboBox named ComboBox1.

  • Two CommandButton controls named CommandButton1 and CommandButton2.

Copy code Copy code
Dim UserForm1

Sub CommandButton1_Click()
 If UserForm1.CanUndo = True Then
 UserForm1.UndoAction
 MsgBox "Undid IT"
 Else
 MsgBox "No undo performed."
 End If
End Sub

Sub CommandButton2_Click()
 If UserForm1.CanRedo = True Then
 UserForm1.RedoAction
 MsgBox "Redid IT"
 Else
 MsgBox "No redo performed."
 End If
End Sub

Sub Item_Open()
 Set UserForm1 = Item.GetInspector.ModifiedFormPages("P.2")
 Set TextBox1 = UserForm1.Controls("TextBox1")
 Set ComboBox1 = UserForm1.Controls("ComboBox1")
 Set CommandButton1 = UserForm1.Controls("CommandButton1")
 Set CommandButton2 = UserForm1.Controls("CommandButton2")

 TextBox1.Text = "Type your text here."

 ComboBox1.ColumnCount = 3
 ComboBox1.AddItem "Choice 1, column 1"
 ComboBox1.List(0, 1) = "Choice 1, column 2"
 ComboBox1.List(0, 2) = "Choice 1, column 3"

 CommandButton1.Caption = "Undo"
 CommandButton2.Caption = "Redo"
End Sub


Using Visual Basic to Customize Outlook Forms

 Copy code hover
[image]

Using Visual Basic to Customize Outlook Forms
Send feedback

In this section

  • Using Visual Basic with Outlook

  • Run in Developer Mode in Outlook

  • Using Visual Basic Scripting Edition

  • Using the Outlook Object Model


Using Visual Basic with Outlook

 Copy code hover
[image]

Using Visual Basic with Outlook
Send feedback

You can use Visual Basic to customize and extend Outlook. You can control Outlook by writing a macro in Visual Basic for Applications, a custom form in VBScript, and other languages that you can use to write an add-in, such as Visual Basic. Which you use depends on what you want your program to do.

Visual Basic is a full-featured programming language you can use to create stand-alone applications or dynamic-link libraries (DLLs) that extend other applications. Visual Basic for Applications is a subset of Visual Basic that is run within an application to extend its capabilities. VBScript is a simplified version of Visual Basic for Applications and is run within an Outlook item. In all cases, these programming languages control Outlook through its object model.

Learn about the Outlook object model.

If you want to create a separate application that accesses data stored by Outlook and uses Outlook to send and receive messages, use Visual Basic to create the application. You can also use other programming languages, such as C++, to control Outlook through its object model. You can create a DLL that can extend Outlook as a COM add-in. One application of COM add-ins is to program form regions and create custom forms.

You use Visual Basic for Applications in one of two ways: You can use Visual Basic for Applications in other applications (such as Microsoft Excel or Microsoft Word) to automate Outlook, or you can use Visual Basic for Applications within Outlook to control Outlook. If you expect your users to be using another application most of the time, and you want to give them the ability to send a message using Outlook or to access information stored by Outlook, write Visual Basic for Applications programs in that application that control Outlook through the Outlook object model. If, on the other hand, you want to write Visual Basic code that customizes how Outlook works (like a macro), use Visual Basic for Applications within Outlook.

While you use an add-in to extend form regions in a custom form, you can extend the functionality of form pages in custom forms by using VBScript. VBScript programs are stored within a form. Because the program code is contained within the form, it can be sent with an item to another user. Other than the consideration of whether to customize a form with a form page or a form region, another important consideration in choosing which kind of the Visual Basic programming language you will use is the type of events you want your program to respond to. Because VBScript code is associated with a particular item, code that responds to events in specific items (such as when a particular item is opened or a value in a field is changed) is easiest to write using VBScript. If, on the other hand, you want your program to respond to events that occur in the application, in Windows Explorer, in folders, or in all items, then you should write your program using Visual Basic or Visual Basic for Applications.

Code written for Visual Basic or Visual Basic for Applications often does not work in VBScript without modification. For example, you must replace all built-in constants written in Visual Basic for Applications with the literal numeric values of those constants in VBScript. And VBScript uses only the Variant data type.

Learn about constants and variables in VBScript.

In Outlook Visual Basic for Applications and VBScript, you do not need to call CreateObject or GetObject to obtain an Application object. For example, the following code displays the Tasks folder:

Copy code Copy code
Set olMAPI = Application.GetNameSpace("MAPI")
olMAPI.GetDefaultFolder(13).Display

In Visual Basic or Visual Basic for Applications in other applications, you must either explicitly create the Application object, as shown in the following code:

Copy code Copy code
Set myOlApp = CreateObject("Outlook.Application")
Set olMAPI = myOlApp.GetNameSpace("MAPI")
olMAPI.GetDefaultFolder(olFolderTasks).Display

or use the Application object that is passed to the OnConnection event of the add-in.

Note Note

The Application object returned from calling the CreateObject method and any of its subordinate objects, properties, and methods are not trusted. For more information on using a trusted Application object in a COM add-in, see Security Behavior of the Outlook Object Model.


Run in Developer Mode in Outlook

 Copy code hover
[image]

Run in Developer Mode in Outlook
Send feedback

If you can see the Developer tab, you are running in developer mode. Otherwise, follow these steps to run in developer mode:

  1. Click the File tab.

  2. Click Options.

  3. Click Customize Ribbon.

  4. Select the Developer check box.

  5. Click OK.

You should now be able to see the Developer tab in the Office Fluent ribbon.


Using Visual Basic Scripting Edition

 Copy code hover
[image]

Using Visual Basic Scripting Edition
Send feedback

In this section

  • About Using VBScript in Outlook

  • How Can I Prevent the VBScript Code from Running?

  • Variants Supported in VBScript

  • Tools for Programming with Visual Basic Scripting Edition

  • Form Events

  • Test Tips for Using Visual Basic Scripting Edition in Outlook


About Using VBScript in Outlook

 Copy code hover
[image]

About Using VBScript in Outlook
Send feedback

One way of extending form pages in a custom form is by using Microsoft Visual Basic Scripting Edition (VBScript). VBScript is a powerful scripting language based on Microsoft Visual Basic that enables you to control objects, folders, forms, items, and controls within a page of a form. For example, you can change properties and values of controls on a page, modify the default Microsoft Outlook item events, and even create automated procedures, such as mailing a notice to all the contacts in a Contacts folder.

You add VBScript code to an Outlook form to respond to Click events that are fired by controls on the form page, or to respond to events fired by the items that have the same message class as the form. VBScript makes it especially easy to respond to item events because the VBScript code executes in the context of the item, so you don't have to set an object variable to point to the item. In addition, VBScript code is compact and can be contained within a form sent to other users.

With VBScript, you have full access to the Outlook object model, except for two areas: VBScript code cannot respond to events other than item and form events, and you cannot use named constants defined in the Outlook object type library.

You can also use Visual Basic for Applications in Outlook to respond to Outlook events and to create macros that automate procedures. Unlike VBScript code, however, Visual Basic for Applications code cannot be contained in a form and so cannot accompany an item that is sent to other users. Note that VBScript is only applicable to extending a form with a form page; if you are extending a form with a form region, you will not be able to use VBScript and will have to use an add-in.


How Can I Prevent the VBScript Code from Running?

 Copy code hover
[image]

How Can I Prevent the VBScript Code from Running?
Send feedback

To prevent any VBScript code from running, hold down the SHIFT key. For example, hold down SHIFT while you open an item to prevent the VBScript code for the Open event from running.


Variants Supported in VBScript

 Copy code hover
[image]

Variants Supported in VBScript
Send feedback

Microsoft VBScript in Outlook uses only the Variant data type.

A Variant is a special kind of data type that can contain different kinds of information, depending on how it's used. Because Variant is the only data type in VBScript, it's also the data type returned by all functions in VBScript.

At its simplest, a Variant can contain either numeric or string information. A Variant behaves as a number when you use it in a numeric context and as a string when you use it in a string context. That is, if you're working with data that looks like numbers, VBScript assumes that it is numbers and does the thing that is most appropriate for numbers. Similarly, if you're working with data that can only be string data, VBScript treats it as string data. Of course, you can always make numbers behave as strings by enclosing them in quotation marks (" ").


Tools for Programming with Visual Basic Scripting Edition

 Copy code hover
[image]

Tools for Programming with Visual Basic Scripting Edition
Send feedback

In this section

  • Using the Script Editor

  • About the Outlook Object Browser

  • Common Things You Can Do with VBScript

  • Using Visual Basic Scripting Edition to Customize Forms


Using the Script Editor

 Copy code hover
[image]

Using the Script Editor
Send feedback

The Microsoft Script Editor allows you to add Microsoft Visual Basic Scripting Edition (VBScript) procedures that respond to events generated by items or form controls.

To run in developer mode

If you can see the Developer tab, you are running in developer mode. Otherwise, see Run in Developer Mode in Outlook to run in developer mode.

To open the Script Editor

  1. Open an item of the type to which you want to add code.

  2. On the Developer tab, in the Form group, click Design This Form.

  3. In the Form group, click View Code.

The Script Editor makes it easy to insert the template for an item event handler.

To insert a blank item event handler

  1. On the Script menu, click Event Handler.

  2. Select the event you want to respond to, and then click Add.

The Script Editor can move the insertion point to a specific line of code. This makes it easy to debug the script when Microsoft Outlook reports an error at a specific location.

To move to a specific line

  1. On the Edit menu, click Go To.

  2. In the Line Number box, type in the number of the line of code to which you want to go. Click OK.

Learn about the Outlook object browser.


About the Outlook Object Browser

 Copy code hover
[image]

About the Outlook Object Browser
Send feedback

The Microsoft Outlook object browser displays the classes, properties, methods, and events available from the Outlook object library. The object browser lets you view and insert these objects into the Script Editor and obtain information about the syntax for using the object.

Learn about viewing and using the object browser.


Common Things You Can Do with VBScript

 Copy code hover
[image]

Common Things You Can Do with VBScript
Send feedback

The following topics are common tasks you can perform with VBScript in a form page of a custom Outlook form:

  • Create an Outlook Item

  • Add a Click Event for a Control in a Custom Form Page

  • Add an Outlook Event

  • Reference the Active User

  • How to: Change the Value of a Field

  • Reference a Folder

  • Use Current User Properties from the Microsoft Exchange Server Global Address List

  • Put a List of Fields and Values in the Message Body


Using Visual Basic Scripting Edition to Customize Forms

 Copy code hover
[image]

Using Visual Basic Scripting Edition to Customize Forms
Send feedback

In this section

  • Set Global Variables for a Form

  • Referencing Controls on an Outlook Form


Set Global Variables for a Form

 Copy code hover
[image]

Set Global Variables for a Form
Send feedback

A global variable is available to any procedure in a form while the script is running. To set a global variable, assign the value to the variables before any procedures.


Referencing Controls on an Outlook Form

 Copy code hover
[image]

Referencing Controls on an Outlook Form
Send feedback

If you need to refer to a control on an Outlook form within a procedure, you must also reference the inspector, page, and controls collection that contains the control, even if you are referencing the control with its own event procedure. The following example shows how to change the caption of a command button when it's clicked. To test this example, in design mode create a command button with the default name CommandButton1 on the page P.2.

Copy code Copy code
Sub CommandButton1_Click
 Set myButton = Item.GetInspector.ModifiedFormPages("P.2")_
 .Controls("CommandButton1")
 myButton.Caption = "New Caption"
End Sub


Form Events

 Copy code hover
[image]

Form Events
Send feedback

In this section

  • Item-Level Events

  • Control Events

  • Field Events

  • About the Order of Events

  • Add a Click Event for a Control in a Custom Form Page

  • Add an Outlook Event

  • Canceling an Event


Item-Level Events

 Copy code hover
[image]

Item-Level Events
Send feedback

Item-level events occur when something happens to an item displayed in a form, such as when it's saved or opened or when a user-defined action is started.

Most often, item-level events are handled by Microsoft Visual Basic Scripting Edition (VBScript) code within the form itself.

Some events can be cancelled. That is, your event handler can prevent Microsoft Outlook from performing the default action associated with the event. For example, you can write an event handler for the Forward event to prevent an item from being sent to recipients who are not on a list of approved recipients. Learn about canceling an event.

The following table lists the item-level events supported by Outlook.

Event | Cancelable? | Description
AttachmentAdd | No | Occurs when an attachment has been added to the item
AttachmentRead | No | Occurs when an attachment has been opened for reading
AttachmentRemove | No | Occurs when an attachment has been removed from an item
BeforeAttachmentAdd | Yes | Occurs before an attachment is added to an item
BeforeAttachmentPreview | Yes | Occurs before an attachment associated with an item is previewed
BeforeAttachmentRead | Yes | Occurs before an attachment associated with an item is read from the file system, an attachment stream, or an Attachment object
BeforeAttachmentSave | Yes | Occurs just before an attachment is saved into the Outlook item
BeforeAttachmentWriteToTempFile | Yes | Occurs before an attachment associated with an item is written to a temporary file
BeforeAutoSave | Yes | Occurs before the item is automatically saved by Outlook
BeforeCheckNames | Yes | Occurs before Outlook starts resolving names in the recipients collection of the item
BeforeDelete | Yes | Occurs before Outlook deletes an item that has been opened in an inspector
Close | Yes | Occurs before Outlook closes the inspector displaying the item
CustomAction | Yes | Occurs before Outlook executes a custom action of an item
CustomPropertyChange | No | Occurs when a custom item property has changed
Forward | Yes | Occurs before Outlook executes the Forward action of an item
Open | Yes | Occurs before Outlook opens an inspector to display the item
PropertyChange | No | Occurs when an item property has changed
Read | No | Occurs when an item is opened for editing by a user
Reply | Yes | Occurs before Outlook executes the Reply action of an item
ReplyAll | Yes | Occurs before Outlook executes the Reply to All action of an item
Send | Yes | Occurs before Outlook sends the item
Unload | No | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action
Write | Yes | Occurs before Outlook saves the item in a folder


Control Events

 Copy code hover
[image]

Control Events
Send feedback

Most Microsoft Forms 2.0 controls in an Microsoft Outlook custom form support only one event, the Click event.

A control bound to a field does not fire the Click event. You must handle the appropriate field event to detect a user's interaction with a control bound to a field.

The following Forms 2.0 controls and Outlook controls fire the Click event whenever a user clicks anywhere in the control.

CheckBox

CommandButton

Frame

Image

Label

OptionButton

ToggleButton

OlkBusinessCardControl

OlkCategory

OlkCheckBox

OlkCommandButton

OlkContactPhoto

OlkDateControl

OlkFrameHeader

OlkInfoBar

OlkLabel

OlkOptionButton

OlkSenderPhoto

OlkTextBox

OlkTimeControl

OlkTimeZoneControl

The following controls fire the Click event when the user selects an item in the list.

ComboBox

ListBox

OlkComboBox

OlkListBox

The following controls do not support the Click event.

MultiPage

ScrollBar

SpinButton

TabStrip

TextBox

While the MultiPage control itself does not support the Click event, an individual Page on a MultiPage control will fire the Click event if the user clicks inside the client area of the page, but not if the user clicks the tab associated with the page.

To detect a change in a TextBox control, bind the control to a field and then handle the appropriate field event.

If you have to further extend controls in a custom form, customize a form with Outlook controls in a form region instead of Forms 2.0 controls in a form page. For more information, see Controls in a Custom Form.


Field Events

 Copy code hover
[image]

Field Events
Send feedback

Outlook provides two events to notify your program that a field (property) in an item has changed. The PropertyChange event is fired whenever a standard Outlook field in an item has changed. Outlook fires the CustomPropertyChange event whenever a user-defined field changes.

A control that is bound to a field does not fire the Click event, whether the control was selected from the Control Toolbox and subsequently bound to a field, or was selected from the Field Chooser. Consequently, you must use the PropertyChange or CustomPropertyChange event to detect user interaction with a bound control.


About the Order of Events

 Copy code hover
[image]

About the Order of Events
Send feedback

The following events occur in the order specified when a user completes an action.

Events | When
Open | A form is opened to compose an item
Send, Write, Close | An item is sent
BeforeAttachmentAdd | Before an attachment is added to an item
BeforeAttachmentPreview | Before an attachment associated with an item is previewed
AttachmentAdd | An attachment has been added to an item
BeforeAttachmentRead | Before an attachment associated with an item is read from the file system, an attachment stream, or an Attachment object
AttachmentRead | An attachment has been opened for reading
BeforeAttachmentSave | Before an attachment is saved into the Outlook item
BeforeAttachmentWriteToTempFile | Before an attachment associated with an item is written to a temporary file
BeforeAutoSave | Before the item is automatically saved by Outlook
BeforeCheckNames | Before Outlook starts resolving names in the recipients collection of the item against the address book, after the user explicitly uses the Check Names command
Write, Close | An item is posted
Write | An item is saved
Read, Open | An item is opened in a folder
Reply | A user replies to an item's sender
ReplyAll | A user replies to an item's sender and all recipients
Forward | The newly-created item is passed to the procedure after the user selects the Forward action for an item
BeforeDelete | Before Outlook deletes the item
PropertyChange | One of the item's standard properties is changed
CustomPropertyChange | One of the item's custom properties is changed
CustomAction | A user-defined action is initiated
Unload | Before an Outlook item is unloaded from memory, either programmatically or by user action

The Click event occurs only when you have defined it for a control in the Script Editor.


Add a Click Event for a Control in a Custom Form Page

 Copy code hover
[image]

Add a Click Event for a Control in a Custom Form Page
Send feedback

You can use VBScript to extend the Click event of a control in a custom form page.

  1. Open the Script Editor.

    How?

  2. For the control to which you want to add a Click event, for example, a command button control, add the following. In the example, CommandButton1 is the name of the control.

    Copy code Copy code
    Sub CommandButton1_Click
    End Sub

  3. Enter the code that you want in the event.


Add an Outlook Event

 Copy code hover
[image]

Add an Outlook Event
Send feedback

You can use VBScript to add an event that happens to an item displayed in a custom form page.

  1. Open the Script Editor.

    How?

  2. On the Script menu, click Event Handler.

  3. In the Insert Events Handler box, click the event that you want to use, and then click Add.


Canceling an Event

 Copy code hover
[image]

Canceling an Event
Send feedback

Outlook calls event handlers in your program to allow your program to respond to such events as actions that the user takes or changes in the message store. Each event is accompanied by a default action that Outlook performs as a result of the event. For example, when the Open event occurs for an item, by default Outlook displays the item in an inspector window.

Some events only notify your program that a particular event has occurred. For these events, your event handler simply responds to the event. With other events, Outlook allows your event handler to cancel the event, that is, to instruct Outlook not to perform the default action associated with the event. In the case of the Open event, for example, your program can prevent Outlook from displaying the item in an inspector. If an event can be cancelled, the reference topic describing the event indicates how to cancel the event.

If an event can be cancelled, an event handler written in Microsoft Visual Basic or Microsoft Visual Basic for Applications receives a parameter that it sets before returning to indicate whether the event should be cancelled. For example, an event handler for the Open event written in Visual Basic for Applications might look like this. This example assumes that the value of OpenOK is set elsewhere.

Copy code Copy code
Sub myItem_Open(byRef Cancel as Boolean)
 If OpenOK Then
 Cancel = False ' Outlook performs default action
 Else
 Cancel = True ' Outlook does not perform default action
 EndIf
End Sub

Because of limitations in VBScript, however, this syntax cannot be used. An event handler for the Open event in the script of an item must be written as a function. To cancel the event, the value of the function is set to False before returning, as in the following example.

Copy code Copy code
Function Item_Open()
 If OpenOK Then
 Item_Open = True ' Outlook performs default action
 Else
 Item_Open = False ' Outlook does not perform default action
 End If
End Function


Test Tips for Using Visual Basic Scripting Edition in Outlook

 Copy code hover
[image]

Test Tips for Using Visual Basic Scripting Edition in Outlook
Send feedback

In this section

  • Test Tips for Using VBScript in Outlook

  • Go to a Line of Code in the Script Editor

  • Use Message Boxes to Return Values


Test Tips for Using VBScript in Outlook

 Copy code hover
[image]

Test Tips for Using VBScript in Outlook
Send feedback

There are several ways to test code in Outlook. If there is a syntax error in the code, when you run the form, an error message appears with the line number of the code. You can then go to the specific line of code. You can also use various methods to isolate run-time errors.

For more information, see the following topics:

  • Go to a Line of Code

  • Use Message Boxes to Return Values

  • Set Global Variables for a Form

  • Use the PropertyChange Event to Test Procedures


Go to a Line of Code in the Script Editor

 Copy code hover
[image]

Go to a Line of Code in the Script Editor
Send feedback

  1. Open the Script Editor.

    How?

  2. On the Edit menu, click Go To.

  3. In the Line Number box, type in the number of the line of code to which you want to go.


Use Message Boxes to Return Values

 Copy code hover
[image]

Use Message Boxes to Return Values
Send feedback

One way to isolate errors is to use a message box to display the value of a variable or property at a particular point in the code. This code example shows the selection length returned from the TextBox.SelLength property in a message box.

Copy code Copy code
MsgBox Item.GetInspector.ModifiedFormPages("Test").Textbox1.SelLength


Using the Outlook Object Model

 Copy code hover
[image]

Using the Outlook Object Model
Send feedback

In this section

  • About the Object Environment

  • Use the Outlook Object Browser

  • How to Use the Outlook Object Browser in the Script Editor

  • Constants and Variables in VBScript

  • Referencing Fields

  • Put a List of Fields and Values in the Message Body

  • Reference a Folder

  • Creating a New Item

  • Create an Outlook Item

  • Referencing Existing Items in a Folder

  • Filtering Items in a Collection

  • Reference the Active User

  • Use Current User Properties from the Microsoft Exchange Server Global Address List

  • Use the PropertyChange Event to Test Procedures


About the Object Environment

 Copy code hover
[image]

About the Object Environment
Send feedback

There are two ways to write code for Microsoft Outlook:

  • From outside the application, such as by using Microsoft Visual Basic or Microsoft Visual Basic for Applications in Microsoft Excel or another application.

  • From inside the application, such as by using Visual Basic for Applications or by using VBScript with an Outlook form.

Major components of the Outlook object model

The following table shows the major objects in the Outlook object model.

Application

The top of the object hierarchy that represents the entire application. Enables you to reference other objects in the application and create items and objects. For example, this code creates an appointment in Outlook:

Copy code Copy code
Application.CreateItem(1).Display

NameSpace

Represents the MAPI message store where all the Outlook items are stored. Provides methods for logging on and off Outlook and for referencing the default folders such as Mailbox, Inbox, Contacts, and others. For example, this code references the active user in Outlook:

Copy code Copy code
Application.GetNameSpace("MAPI").CurrentUser

Account

Represents an account defined for the current profile.

Store

Represents a file on the local computer or a network drive that stores e-mail messages and other items for an account in the current profile.

Folders

There are two folder objects, the Folders collection object that enables you to work with collections of folders and the Folder object that enables you to work with a single folder. For example, this code shows the collection of folders named Personal Folders in Outlook:

Copy code Copy code
Application.GetNameSpace("MAPI").Folders("Personal Folders")

Table

Represents a set of item data from a Folder or Search object, with items as rows of the table and properties as columns of the table.

Rule

Represents an Outlook rule.

View

Represents a customizable view used to sort, group, and view data.

Explorer

Represents the Outlook window. Enables you to show, return, and close the active window. For example, this code shows the active Outlook window in Outlook:

Copy code Copy code
Application.ActiveExplorer.Display

NavigationPane

Represents the Navigation Pane displayed by the active Explorer object.

Outlook items

There are two item objects, the Items collection that enables you to work with items within a folder and the item objects that represents the standard item types in Outlook, such as MailItem that represents a mail message. In VBScript, the active item is assumed, so you do not need to enter the object model to reference it. For example, this code sets the Subject field of the active message in VBScript:

Copy code Copy code
Item.Subject = "New Subject"

Inspector

References forms. Use to show forms and pages. For example, this code shows the Options page of a form in Outlook:

Copy code Copy code
Application.ActiveInspector.SetCurrentFormPage("Options")

FormRegion

Represents a form region in an Outlook form.

Attachment

Represents a document or link to a document contained in an Outlook item.

PropertyAccessor

Provides the ability to create, get, set, and delete properties on objects.

ItemProperty

Represents information about a given item property for an Outlook item object.

UserProperty

Represents a custom property of an Outlook item.

AddressEntry

Each AddressEntry object in the AddressEntries collection holds information that represents a person or process to which the messaging system can deliver messages.

AddressList

The AddressList object is an address book that contains a set of AddressEntry objects. The entire hierarchy is available through the parent AddressLists collection.

ExchangeUser

Provides detailed information about an AddressEntry that represents a Microsoft Exchange Server mailbox user.

ExchangeDistributionList

Provides detailed information about an AddressEntry that represents an Exchange distribution list.

Recipient

Represents a user or resource in Outlook, generally a mail message addressee.

Exception

The Exception object holds information about one instance of an AppointmentItem object which is an exception to a recurring series. Unlike most of the other Outlook objects, the Exception object is a read-only object.

Control

There are the Microsoft Forms 2.0 controls that exist in the control toolbox by default, and the Outlook controls that are installed on your computer by default and that you will add to the control toolbox before using them for the first time in a form.


Use the Outlook Object Browser

 Copy code hover
[image]

Use the Outlook Object Browser
Send feedback

The Outlook object browser displays the classes, properties, methods, events, and constants available from the Outlook object library. The object browser lets you view and use objects in the Script Editor and obtain information about the syntax for using the object.


How to Use the Outlook Object Browser in the Script Editor

 Copy code hover
[image]

How to Use the Outlook Object Browser in the Script Editor
Send feedback

To view the Outlook object browser

  1. On the Developer tab, in the Custom Forms group, click Design a Form.

    Note Note

    If you do not see the Developer tab, see Run in Developer Mode in Outlook to activate the Developer tab.

  2. In the Design Form dialog box, select the form that you would like to use the object browser with, and click Open to open the form in design mode.

  3. On the Developer tab, in the Form group, click View Code to open the selected form in the Script Editor.

  4. In the Script Editor, click Object Browser on the Script menu or press F2.

All of the available Outlook objects are listed in the Classes pane of the object browser in alphabetical order.

To view the members of an object, select the object in the Classes pane. The members of this object appear in alphabetical order in the Members of pane. The heading at the top of this pane will reflect the name of the object that you select. For example, if you select the AppointmentItem object in the Classes pane, the heading of the Members of pane will appear as Members of AppointmentItem.

The details pane shows the definition of the selected member. This text is read-only and cannot be copied and pasted into the Script Editor.

To insert an item from the object browser into the Script Editor

  1. In the Script Editor, position your cursor at the location for insertion.

  2. Select the desired object in the Classes pane.

  3. Select the desired member of this object in the Members of pane.

  4. Click Insert.

Note Note

The Insert button remains unavailable until a member of the object is selected.


Constants and Variables in VBScript

 Copy code hover
[image]

Constants and Variables in VBScript
Send feedback

In VBScript, constants must be referenced by their numeric values. The constant string does not work and returns a value of 0, which gives unpredictable results.

There are two types of variables. Procedure-level variables that are used only within a procedure and script-level variables that are available to all the procedures within your script. Declare script-level variables at the top of your script. Declare procedure-level variables inside procedures. You can use procedure-level variables with the same name in different procedures because each variable is recognized only by the procedure in which it's declared. When the procedure exits, the variable ends. Variables that refer to Outlook objects can be either procedure-level or script-level variables. However, the value of the variable must be set within a procedure. Do not attempt to access Outlook objects outside of a procedure.

Rules about variables:

  • Must begin with an alphanumeric character.

  • Cannot contain an embedded period.

  • Cannot exceed 255 characters.

  • Cannot use more than 127 procedure-level variables (arrays count as a single variable).

  • Cannot use more than 127 script-level variables.


Referencing Fields

 Copy code hover
[image]

Referencing Fields
Send feedback

When you need to access the fields in an item, the method you use depends on whether the field is a standard built-in Outlook field, or a custom field.

In either case, you do not access the field directly. Instead, you refer to the field as a property of the item you're working with.

For example, to retrieve the text from the Subject field of a mail message, you use the Subject property of the item, as shown in the following VBScript example.

Copy code Copy code
mySubject = Item.Subject

If the field is a custom (user-defined) field, you access it using the UserProperties property of the item, as shown in the following VBScript example. This example assumes that the item already contains a custom field named ReferredBy.

Copy code Copy code
MyReferral = Item.UserProperties("ReferredBy")


Put a List of Fields and Values in the Message Body

 Copy code hover
[image]

Put a List of Fields and Values in the Message Body
Send feedback

To add a list of fields and values in the body of an item, define a variable to contain the string, and then use Outlook properties that refer to the field you want to include. For example, to include the To field in the message body, use the following.

Copy code Copy code
Chr (13)

is the return character.

Copy code Copy code
MessageString = "This letter is sent to " & Item.To & chr(13)
MessageString = MessageString & "second line goes here"
Item.Body = MessageString


Reference a Folder

 Copy code hover
[image]

Reference a Folder
Send feedback

To reference a folder by the name of the folder, use the following code.

Copy code Copy code
Application.GetNameSpace("MAPI").Folders("Personal Folders").Folders("Product Ideas")

To reference a folder by a number, use the following code. In this example, the first folder in the folder collection Personal Folders is referenced.

Copy code Copy code
Application.GetNameSpace("MAPI").Folders("Personal Folders").Folders(1)

To reference any of the default Outlook folders, use the GetDefaultFolder method. Use the appropriate constant value from the OlDefaultFolders Enumeration to specify the folder you want to create.

Copy code Copy code
Application.GetNameSpace("MAPI").GetDefaultFolder(6)


Creating a New Item

 Copy code hover
[image]

Creating a New Item
Send feedback

To create a new item, use the CreateItem method of the Application object. This method returns an object that you can then use to work with the item.

The following Microsoft Visual Basic for Applications example shows how to create a mail message, add text to its subject and body, and display it. To use this sample, create a command button named Command1 on a form.

Copy code Copy code
Private Sub Command1_Click()
 Dim myOLItem As Outlook.MailItem

 Set myOLItem = Application.CreateItem(olMailItem)
 With myOLItem
 .Subject = "Sample item"
 .Body = "This is a sample message."
 End With
 myOLItem.Display
End Sub

The following example shows how to perform the same task using VBScript in a form.

Copy code Copy code
Sub CommandButton1_Click()
 Set myOLItem = Application.CreateItem(0)
 myOLItem.Subject = "Sample item"
 myOLItem.Body = "This is a sample message."
 myOLItem.Display
End Sub


Create an Outlook Item

 Copy code hover
[image]

Create an Outlook Item
Send feedback

This procedure uses the Click event to call CreateItem to create and show an appointment when a user clicks CommandButton1. The example shows how to do this in a custom form page using VBScript.

In design mode:

  1. Using the Control Toolbox, place a CommandButton on your form.

  2. Open the Script Editor. How?

  3. Enter the following code, using the appropriate constant value from the OlItemType enumeration to specify the type of item that you want to create.

    Copy code Copy code
    Sub CommandButton1_Click
 Application.CreateItem(1).Display
End Sub


Referencing Existing Items in a Folder

 Copy code hover
[image]

Referencing Existing Items in a Folder
Send feedback

There are a number of ways you can reference existing items in a folder using Microsoft Visual Basic. This topic provides information about:

  • Using a For … Next or For Each … Next loop

  • Using the Items collection

  • Using the Find method

  • Using the Restrict method

Using a For…Next or For Each...Next Loop

Typically these statements are used to loop through all of the items in a folder. The Items collection contains all the items in a particular folder, and you can specify which item to reference by using an index with the Items collection. This is typically used with the For i = 1 to n programming construct.

You can use For Each...Next to loop through the items in the collection without specifying an index. Both approaches achieve the same result.

The following examples use For…Next to loop through all the contacts in the Contacts folder and display the Full Name field in a dialog box.

Copy code Copy code
' Microsoft Visual Basic for Applications code example.
Set olns = Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' Get the number of items in the folder.
NumItems = MyFolder.Items.Count
' Set MyItem to the collection of items in the folder.
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
' Loop through all of the items in the folder.
For I = 1 to NumItems
   MsgBox MyItems(I).FullName
Next
Copy code Copy code
' Visual Basic Scripting Edition code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(10)
' Get the number of items in the folder.
NumItems = MyFolder.Items.Count
' Set MyItem to the collection of items in the folder.
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
' Loop through all of the items in the folder.
For I = 1 to NumItems
   MsgBox MyItems(I).FullName
Next

The following examples use For Each...Next to achieve the same result as the preceding examples:

Copy code Copy code
' Visual Basic/Visual Basic for Applications code example.
Set olns = Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' Set MyItems to the collection of items in the folder.
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
For Each SpecificItem in MyItems
   MsgBox SpecificItem.FullName
Next
Copy code Copy code
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(10)
' Set MyItem to the collection of items in the folder.
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
For Each SpecificItem in MyItems
   MsgBox SpecificItem.FullName
Next

Using the Items Collection

You can also use the Items collection and specify a text string that matches the Subject field of an item. The following examples display an item in the Inbox whose subject contains "Please help on Friday!"

Copy code Copy code
' Visual Basic/Visual Basic for Applications code example.
Set olns = Application.GetNameSpace("MAPI")
' Set MyFolder to the default Inbox.
Set MyFolder = olns.GetDefaultFolder(olFolderInbox)
Set MyItem = MyFolder.Items("Please help on Friday!")
MyItem.Display
Copy code Copy code
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default Inbox.
Set MyFolder = olns.GetDefaultFolder(6)
Set MyItem = MyFolder.Items("Please help on Friday!")
MyItem.Display

Using the Find Method

Use the Find method to search for an item in a folder based on the value of one of its fields. If the search is successful, you can then use the FindNext method to check for additional items that meet the same search criteria.

The following examples search to see if you have any high priority tasks.

Copy code Copy code
' Visual Basic/Visual Basic for Applications code example.
Set olns = Application.GetNamespace("MAPI")
Set myFolder = olns.GetDefaultFolder(olFolderTasks)
Set MyTasks = myFolder.Items
' Importance corresponds to Priority on the task form.
Set MyTask = MyTasks.Find("[Importance] = ""High""")
If MyTask Is Nothing Then ' the Find failed
   MsgBox "Nothing important. Go party!"
Else
   MsgBox "You have something important to do!"
End If
Copy code Copy code
' VBScript code example.
Set olns = Item.Application.GetNamespace("MAPI")
Set myFolder = olns.GetDefaultFolder(13)
Set MyTasks = myFolder.Items
' Importance corresponds to Priority on the task form.
Set MyTask = MyTasks.Find("[Importance] = ""High""")
If MyTask Is Nothing Then ' the Find failed
   MsgBox "Nothing important. Go party!"
Else
   MsgBox "You have something important to do!"
End If

Using the Restrict Method

The Restrict method is similar to the Find method, but instead of returning a single item, it returns a collection of items that meet the search criteria. For example, you could use this method to find all contacts that work at the same company.

The following examples display all of the contacts that work at ProseWare Corporation:

Copy code Copy code
' Automation code example.
Set olns = Application.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
MyClause = "[CompanyName] = ""ProseWare"""
Set MyPWItems = MyItems.Restrict(MyClause)
For Each MyItem in MyPWItems
   MyItem.Display
Next
Copy code Copy code
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(10)
Set myItems = myFolder.Items.Restrict("[MessageClass] = 'IPM.Contact'")
MyClause = "[CompanyName] = ""ProseWare"""
Set MyPWItems = MyItems.Restrict(MyClause)
For Each MyItem in MyPWItems
   MyItem.Display
Next


Filtering Items in a Collection

 Copy code hover
[image]

Filtering Items in a Collection
Send feedback

You can use the Microsoft Outlook object model to return information about all items in a folder. Often, however, the desired objective is to search for a specific item or to retrieve a subset of the items in the folder. Consider the following examples:

  • You are developing a Microsoft Access database. When the user enters a new contact record, you want to give the user the ability to click a button to check whether a contact with the same name already exists in Outlook. If a match is found, you can retrieve all the fields for the contact and automatically fill in the Access database record. In this situation, if the user filled in the first and last name fields on the Access form, you can use the Items.Find method in the Outlook object model to search for a match against the Outlook Full Name field. If you want to make sure there are no additional contacts in Outlook with the same name, you can then use the Items.FindNext method to conduct the same search again. Note that if you do not require the search results to contain values for all the built-in properties of the item, you should use the FindRow and Restrict methods of the Table object for better search performance. For more information on searching and filtering items using the Outlook object model, see Enumerating, Searching, and Filtering Items in a Folder.

  • You are writing a Microsoft Visual Basic program to automatically schedule appointments in users' calendars. In order to do this, you need to retrieve a user's appointments for a given day. In this case, you would use the Items.Restrict or Table.Restrict method to retrieve all appointments that fall on a particular day.

While the Items.Find, Items.Restrict, Table.FindRow, and Table.Restrict methods perform similar search and filter functions, Items.Find supports only the Microsoft Jet syntax whereas the others support both the Jet syntax and the DAV Searching and Locating (DASL) syntax. For more information on these syntaxes, see Filtering Items.


Reference the Active User

 Copy code hover
[image]

Reference the Active User
Send feedback

Use Application.GetNamespace to return the Outlook NameSpace object from the Application object, and then use the NameSpace.CurrentUser property to return a Recipient object repesenting the active user, as shown in the following example.

Copy code Copy code
Set myUser = Application.GetNameSpace("MAPI").CurrentUser


Use Current User Properties from the Microsoft Exchange Server Global Address List

 Copy code hover
[image]

Use Current User Properties from the Microsoft Exchange Server Global Address List
Send feedback

In code, open an OLE messaging session and log on, and then use the following table to reference the property you want to use.

Copy code Copy code
Set olemSession = Application.CreateObject("MAPI.Session")
ReturnCode = olemSession.Logon( Application.GetNameSpace("MAPI").CurrentUser, "", False, False, 0 )
myPage = Item.GetInspector.ModifiedFormPages("Message")
Set myUser = olemSession.CurrentUser
Item.UserProperties.Find("Name") = myUser.Name
Item.UserProperties.Find("Messaging Address") = myUser.Address
Item.UserProperties.Find("MAPI First Name") = myUser.Fields.item(&h3a06001e)

Address Book Property | Reference
PidTagGivenName | &h3a06001e
PidTagInitials | &h3a0a001e
PidTagSurname | &h3a11001e
PidTag7BitDisplayName | &h39ff001e
PidTagStreetAddress | &h3a29001e
PidTagLocality | &h3a27001e
PidTagStateOrProvince | &h3a28001e
PidTagPostalCode | &h3a2a001e
PidTagCountry | &h3a26001e
PidTagTitle | &h3a17001e
PidTagCompanyName | &h3a16001e
PidTagDepartmentName | &h3a18001e
PidTagOfficeLocation | &h3a19001e
PidTagAssistant | &h3a30001e
PidTagBusinessTelephoneNumber | &h3a08001e


Use the PropertyChange Event to Test Procedures

 Copy code hover
[image]

Use the PropertyChange Event to Test Procedures
Send feedback

This topic shows how to test procedures for a custom form page that uses VBScript and the Script Editor.

Perform the following steps to test simple procedures. Replace the code below with the code that you want to test. Each time a user changes the value of the Importance field, or any other default field, the code runs.

  1. Open the Script Editor. How?

  2. On the Script menu, click Event Handler.

  3. In the Events box, double-click PropertyChange.

  4. Add the following code in the event:

    Copy code Copy code
    MsgBox "This is my test procedure"

  5. On the Form menu, click Run This Form.

  6. Click the ! icon on the toolbar. The message box will appear.

  7. Click OK to close the message box.


Extending Forms and Form Regions Using Add-ins

 Copy code hover
[image]

Extending Forms and Form Regions Using Add-ins
Send feedback

In this section

  • How to: Add or Remove an Add-in

  • Extending a Form Region with an Add-in

  • How to: Use an Add-in to Specify Icons for a Form Region

  • How to: Create Separate Read and Compose Pages Using Form Regions in a Custom Form


How to: Add or Remove an Add-in

 Copy code hover
[image]

How to: Add or Remove an Add-in
Send feedback

Add-ins provide more options when you customize standard form pages and form regions in Microsoft Outlook. COM add-ins and Microsoft Exchange Client add-ins are available.

For best results, use Control Panel to add or remove add-ins.

For Microsoft Windows XP

  • Click Start, click Control Panel, and then click Add or Remove Programs.

For Windows Vista

  • Click Start, click Control Panel, and then click Programs.

For more information, see the following topics:

  • Add-ins Overview

  • Extending a Form Region with an Add-in


Extending a Form Region with an Add-in

 Copy code hover
[image]

Extending a Form Region with an Add-in
Send feedback

While you can create and run forms with form regions without a COM add-in, using a COM add-in will allow form regions to include custom business logic or advanced functionality. Unlike customizing form pages in a standard form, you do not use VBScript to write code behind a form; instead, you program form regions with a COM add-in. Your add-in will implement a new interface, FormRegionStartup. Add-ins will be able to use Microsoft Forms 2.0 controls and Microsoft Outlook controls in a form region. This topic describes how to implement FormRegionStartup and access Outlook controls in a form region.

Specifying the Use of an Add-in

When you register the form region for a message class, create a key in the Windows registry for that message class (if the key does not yet exist), and specify as data, an equal sign (=) followed by the ProgID of the add-in. For more information on registering a form region in the Windows registry, see Specifying Form Regions in the Windows Registry.

Implementing FormRegionStartup

In the same class that implements the IDTExtensibility2 interface of your COM Add-in, implement the Outlook.FormRegionStartup interface, which is defined in the Outlook type library. Outlook will call the four methods in this interface:

  • GetFormRegionStorage

  • BeforeFormRegionShow

  • GetFormRegionManifest

  • GetFormRegionIcon

GetFormRegionStorage

When Outlook is about to display a form region that is controlled by an add-in, Outlook will call the GetFormRegionStorage method. When the add-in receives a call from Outlook to GetFormRegionStorage specifying information for a form region, the add-in will return information for the layout. This information can be a local path to the layout file (.OFS file), a Microsoft Windows IStorage object, or a byte array with the contents of the OFS file, which allows an add-in to store the OFS as a resoruce. Outlook will use the returned information to instantiate controls and calculate the layout for the form region. Outlook will also instantiate a FormRegion object for the form region. The method prototype for GetFormRegionStorage in Microsoft Visual Basic and Microsoft C# are shown below.

In Visual Basic:

Visual Basic Copy code Copy code
Public Function GetFormRegionStorage(ByVal FormRegionName As String,
    ByVal Item As Object,
    ByVal LCID As Integer,
    _ ByVal FormRegionMode As Outlook.OlFormRegionMode,
    ByVal FormRegionSize As Outlook.OlFormRegionSize) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionStorage

In C#:

C# Copy code Copy code
public object GetFormRegionStorage(string FormRegionName,
    object Item,
    int LCID,
    Outlook.OlFormRegionMode FormRegionMode,
    Outlook.OlFormRegionSize FormRegionSize)

BeforeFormRegionShow

If GetFormRegionStorage is successful, just before the form region is displayed in an Inspector window or in the Reading Pane, Outlook will call BeforeFormRegionShow, passing the FormRegion object to the add-in. The add-in will use this chance before the form region is displayed to update anything in the user interface, such as changing label captions, as described in the section Accessing Outlook Controls below, and suppressing irrelevant content. The Visual Basic and C# method prototypes for BeforeFormRegionShow are shown below.

In Visual Basic:

Visual Basic Copy code Copy code
Public Sub BeforeFormRegionShow(ByVal Item As Object,
    ByVal FormRegion As Microsoft.Office.Interop.Outlook.FormRegion) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.BeforeFormRegionShow

In C#:

C# Copy code Copy code
public void BeforeFormRegionShow(object Item, Outlook.FormRegion FormRegion)

Accessing Outlook Controls

When using a COM add-in to extend a form region, you are often listening to control events, calling control methods, or reading and setting control properties. To access Microsoft Forms 2.0 controls, Outlook controls, or the form canvas object in an add-in, you must add a reference to the Microsoft Forms 2.0 object library. Adding this reference will give you access to the Microsoft.Vbe.Interop.Forms namespace in your add-in project.

After adding the reference, optionally, you can create an alias to the namespace of the type library to make it easier to use the included types. To create an alias, insert the following code at the top of the code file. The following are examples of how to do this if you are writing your add-in in Visual Basic or C#. These aliases will also be used in the code samples further below.

In Visual Basic:

Visual Basic Copy code Copy code
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Office = Microsoft.Office.Core
Imports MSForms = Microsoft.Vbe.Interop.Forms

In C#:

C# Copy code Copy code
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;
using MSForms = Microsoft.Vbe.Interop.Forms;

You can access controls through the FormRegion object obtained from BeforeFormRegionShow. The FormRegion.Form property returns an object representing a form; you can cast this object to the MSForms.UserForm class (exposed in the Microsoft Forms 2.0 object library) to access the form canvas for the form region.

Each instance of the UserForm object has a Controls collection that can be used to access the individual controls on the UserForm by control name. Many of the Microsoft Forms 2.0 controls have themed counterparts that are Outlook controls. In a form region, Outlook replaces those Forms 2.0 controls that have Outlook counterpart controls by the corresponding themed counterparts. Once you have obtained a reference to a themed control from the Controls collection, you can cast it to the proper type in the Outlook type library. You will then be able to access all the properties, methods, and events exposed for these controls in the Outlook type library. Unlike customizing forms with VBScript, you will be able to listen to all control events, and not only the Click event. For more information on controls, see Controls in a Custom Form.

The following code samples show how the BeforeFormRegionShow method uses the input parameter FormRegion from Outlook to obtain a form object, then casts it to an MSForms.UserForm class and accesses the collection of controls in the UserForm object. The form canvas represented by this UserForm object has two Outlook controls: a text box named OlkTextBox1 and a check box named OlkCheckBox1. It casts them to the proper Outlook control types and sets default values for these controls as follows.

In Visual Basic:

Visual Basic Copy code Copy code
Dim UserForm As MSForms.UserForm
Dim FormControls As MSForms.Controls
Dim TextBox1 As Outlook.OlkTextBox
Dim CheckBox1 As Outlook.OlkCheckBox

UserForm = FormRegion.Form
FormControls = UserForm.Controls

TextBox1 = FormControls.Item("OlkTextBox1")
TextBox1.Text = "Sample Form Region"
CheckBox1 = FormControls.Item("OlkCheckBox1")
CheckBox1.Value = True

In C#:

C# Copy code Copy code
MSForms.UserForm userForm = (MSForms.UserForm)FormRegion.Form;
MSForms.Controls formControls = userForm.Controls;

Outlook.OlkTextBox textBox1 =
   (Outlook.OlkTextBox)formControls.Item("OlkTextBox1");
textBox1.Text = "Sample Form Region";

Outlook.OlkCheckBox checkBox1 =
   (Outlook.OlkCheckBox)formControls.Item("OlkCheckBox1");
checkBox1.Value = true;

GetFormRegionManifest

When Outlook starts, it reads the list of form regions from the Windows registry and caches the data. Based on this data, if Outlook notices that an add-in is to provide the XML manifest for a form region, Outlook will use the ProgID provided in the cached data and call the GetFormRegionManifest method implemented by this add-in to obtain the XML it needs to display the form region. If the XML manifest is not valid and does not conform to the form region XML schema, Outlook will not be able to load the form region.

For more information on specifying a ProgID when registering a form region, see Specifying Form Regions in the Windows Registry.

The Visual Basic and C# method prototypes for GetFormRegionManifest are shown below.

In Visual Basic:

Visual Basic Copy code Copy code
Public Function GetFormRegionManifest(ByVal FormRegionName As String,
    ByVal LCID As Integer) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

In C#:

C# Copy code Copy code
public object GetFormRegionManifest(string FormRegionName, int LCID)

GetFormRegionIcon

When Outlook starts, it reads the list of form regions from the Windows registry and caches the data associated with the form regions. If a form region has been registered with a ProgID, Outlook will resort to the corresponding add-in by calling its implementation of GetFormRegionIcon for any icon in the XML manifest that has addin as the value of a child element of the icons element. For more information on using an add-in to specify icons, see How to: Use an Add-in to Specify Icons for a Form Region.

The Visual Basic and C# method prototypes for GetFormRegionIcon are shown below.

In Visual Basic:

Visual Basic Copy code Copy code
Public Function GetFormRegionIcon(ByVal FormRegionName As String,
    ByVal LCID As Integer, _
    ByVal Icon As Outlook.OlFormRegionIcon) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

In C#:

C# Copy code Copy code
public object GetFormRegionIcon(string FormRegionName, int LCID, Outlook.OlFormRegionIcon Icon)


How to: Use an Add-in to Specify Icons for a Form Region

 Copy code hover
[image]

How to: Use an Add-in to Specify Icons for a Form Region
Send feedback

You can use an add-in to specify the custom icons you would like to use to help identify the state of an item in the explorer, inspector, and ribbon. Through the form region manifest XML file that you use to register the form region, you can specify the add-in that extends the form region, and the circumstances for which the custom icon is intended. When the specified cirsumstances occur, Outlook would obtain the appropriate icon from the add-in.

To use an add-in to specify an icon for a form region

  1. Implement the FormRegionStartup interface.

    All add-ins that extend form regions must implement the FormRegionStartup interface. Outlook calls this interface to obtain layout storage data for a form region. For more information on add-ins for form regions, see Extending a Form Region with an Add-in.

    In particular, to specify custom icons, the add-in implements the GetFormRegionManifest and the GetFormRegionIcon methods of the FormRegionStartup interface, specifying a form region manifest XML file and the circumstances where Outlook should display custom icons in the explorer, inspector, or ribbon. For example, you can create a form region to display a type of task that occurs in the household only, and these household tasks belong to a message class, IPM.Task.Household, which is derived from IPM.Task. You can extend the form region with an add-in that specifies in the GetFormRegionIcon method a special recurrent icon that Outlook should display adjacent to recurrent household tasks in the explorer.

  2. In the form region manifest XML file, specify under the icons element, the value addin for each of the child elements where you would like to use a custom icon.

    When Outlook displays items in the explorer or inspector, Outlook would look in the cache for the form region manifests that are associated with items of specific message classes. Where a child element of the icons element has the value addin, Outlook calls GetFormRegionIcon to obtain the corresponding icon and displays it accordingly for items of that message class.

    As an extension of the last example, in the form region manifest XML file for the form region associated with IPM.Task.Household, you can specify under the icons element, the value addin for the recurring child element. When Outlook displays all tasks in the explorer, Outlook would look at the cached form region manifest for items belonging to IPM.Task.Household. When Outlook realizes that the recurring element has the value addin, Outlook will call GetFormRegionIcon to obtain the icon for recurrent houshold tasks, and displays in the explorer the special recurrent icon adjacent to this type of task. For more information on child elements of the icons element, see How to: Specify Icons to be Displayed for a Form Region.


How to: Create Separate Read and Compose Pages Using Form Regions in a Custom Form

 Copy code hover
[image]

How to: Create Separate Read and Compose Pages Using Form Regions in a Custom Form
Send feedback

To create distinct read and compose pages for a custom form, you can first use the Forms Designer to design a separate form region for the read page, and another separate form region for the compose page. For more information on creating a form region, see How to: Create a Form Region.

In order for Outlook to display the appropriate form region for the read page and the compose page, you can use an add-in that programmatically tells Outlook which form region to use in each case. Your add-in does this through the GetFormRegionStorage method of the FormRegionStartup interface.

To return the appropriate form region in the GetFormRegionStorage method

  • In GetFormRegionStorage, return the appropriate form region storage file (.OFS) based on the value that Outlook specifies for FormRegionMode.

    As with any COM add-in that extends a form region, your add-in will implement the Outlook.FormRegionStartup interface. In particular, when implementing the GetFormRegionStorage method of the FormRegionStartup interface, depending on the input value of the parameter FormRegionMode, your add-in will return the appropriate form region. For example, when Outlook calls GetFormRegionStorage to obtain the form region for the read page, specifying FormRegionMode as olFormRegionRead, your add-in will have implemented GetFormRegionStorage to return the form .OFS file for the form region created for the read page. Similarly, when Outlook calls GetFormRegionStorage to obtain the form region for the compose page, specifying FormRegionMode as olFormRegionCompose, GetFormRegionStorage will return the local path to the .OFS file for the form region created for the compose page. Note that if your add-in specifies a path to an .OFS file as the return value for GetFormRegionStorage, the path must be a local path. For more information on implementing GetFormRegionStorage, see Extending a Form Region with an Add-in.


Items, Folders, and Stores

 Copy code hover
[image]

Items, Folders, and Stores
Send feedback

In this section

  • Enumerating, Searching, and Filtering Items in a Folder

  • Sorting Items in a Folder

  • Storing Outlook Items

  • Working with EntryIDs and StoreIDs

  • Outlook Item Objects

  • How to: Attach a File to a Mail Item

  • How to: Create a Recurring Appointment that Occurs Every 2 Years

  • How to: Create an Appointment as a Meeting on the Calendar

  • How to: Delete All Items and Subfolders in the Deleted Items Folder

  • How to: Enumerate Folders on All Stores

  • How to: Enumerate Search Folders on All Stores

  • How to: Enumerate the Contacts Folder and Set Custom Property for only Contact Items

  • How to: Import Appointment XML Data into Outlook Appointment Objects (Outlook)

  • How to: Obtain a Folder Object from a Folder Path

  • How to: Send an E-mail Given the SMTP Address of an Account (Outlook)

  • How to: Specify an Internet Encoding Scheme for the Body and Attachments of a Message

  • How to: Specify Whether to Display a Contact's Picture in Outlook


Enumerating, Searching, and Filtering Items in a Folder

 Copy code hover
[image]

Enumerating, Searching, and Filtering Items in a Folder
Send feedback

The Outlook object model provides several entry points that support enumerating, searching, and filtering items in a folder.

Enumerating Items

The Items, Table, and Selection objects all support enumerating items in a folder. However, there are specific scenarios where you would choose one over the others.

You can obtain an Items collection by calling Folder.Items which returns the items in the folder. Each item object in the collection is complete with all its explicit built-in properties and custom properties, and supports read-write operations. The Items collection also supports filters and events that fire when items are added, changed, or removed from the collection.

You can use Folder.GetTable or Search.GetTable to obtain a Table object that represents a set of items in a folder or search folder. In both cases, you can specify a filter to obtain a subset of the items in the folder, or, if you do not specify any filter, obtain all the items in the folder. By default, each item in the returned Table contains only a default subset of its properties. You can view each row of a Table as an item in the folder, each column as a property of the item, and the Table is an in-memory light-weight rowset that allows fast enumeration and filtering of items in the folder. Although additions and deletions of the underlying folder are reflected by the rows in the Table, the Table does not support any events for adding, changing, and removing rows. If you require a writeable object from the Table row, obtain the Entry ID for that row from the default EntryID column in the Table and then use the GetItemFromID method of the NameSpace object to obtain a full item, such as a MailItem or ContactItem, that supports read-write operations. For more information on default columns in a Table, see Default Properties Displayed in a Table Object.

The Selection object supports enumerating items that a user has currently selected in an explorer. Since the explorer displays the contents of a folder, the Selection object supports enumeration of items in that folder as per the user's selection.

Note Note

A folder in Outlook can contain heterogeneous items. For example, the Contacts folder supports creating contact items and distribution list items by default. Since the Items, Table, and Selection objects encapsulate items in a folder or search folder, the items in them do not necessarily have the same message class. When enumerating items in these collections and objects, it is a good practice to first check for the message class of each item before accessing the item's properties.

Searching and Filtering Items

The Items, Table, Application, and View objects support searching and filtering of items in a folder. The following table describes and compares these entry points:

Entry Point | Action | Object of Search Filter | Jet Filter Support | DASL Filter Support | Comments
Application.AdvancedSearch | Sets the criteria for a Search object and returns the Search object. Search.Results specifies the search results. Search.Save updates a search folder with the search results. | Folder | No | Yes |
Folder.GetTable | Returns a Table of items in a folder based on any given filter. | Folder | Yes | Yes | Certain properties are not supported in the Table filter, including binary properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter.
Items.Find | Searches for first item that satisfies the specified filter. | Folder | Yes | No | Certain properties are not supported in the filter, including Body. For more information, see Items.Find.
Items.Restrict | Filters given set of items based on specified restrictions and returns another Items collection. | Folder | Yes | Yes | Certain properties are not supported in the filter, for example, Body. For more information, see Items.Restrict.
Search.GetTable | Returns a Table of items in a search folder based on any filter derived from Application.AdvancedSearch. | Search folder | No | Yes | Search.GetTable derives its filter from the Search object (specifically the Search.Filter property) returned from Application.AdvancedSearch.
Table.Restrict | Filters rows in the given table based on a specified filter and returns another Table object. | Folder | Yes | Yes | Certain properties are not supported in the Table filter, including binary properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter.
View.Filter | Sets a view's filter without changing the view's XML. Setting the filter for a view only changes the view in the user interface and does not result in a filtered Items collecton. | Folder | No | Yes |
View.XML | Gets or sets the XML for a view. Modifying the <Filter> node changes the view's filter. Setting the XML for a view only changes the view in the user interface and does not result in a filtered Items collecton. | Folder | No | Yes | View XML is being deprecated. Use the View object model to program views.


Sorting Items in a Folder

 Copy code hover
[image]

Sorting Items in a Folder
Send feedback

Items.Sort , Results.Sort, and Table.Sort allow you to sort Outlook items. This following table compares the few methods.

Items.Sort

Results.Sort

Table.Sort

Object of Sorting

Items in an Items collection based on a folder

Items in a Results collection based on a search

Items in a Table object based on a folder or search folder

Applicable Properties as Sort Fields

Explicit built-in properties with the exceptions listed in the Items.Sort topic

Explicit built-in properties with the exceptions listed in the Results.Sort topic

Explicit built-in properties and custom properties with the exception of binary and multi-valued properties

Referencing of Properties

  • By their explicit string names in the Outlook object model

  • Explicit built-in properties can only be referenced by their names in English and not any other localized language

  • By their explicit string names in the Outlook object model

  • Explicit built-in properties can only be referenced by their names in English and not any other localized language

  • By their explicit string names only; cannot reference properties by their namespaces

  • Explicit built-in properties can only be referenced by their names in English and not any other localized language

  • Custom properties can be referenced in English or a localized language

Format of Sort Fields

  • Enclosing square brackets ('['']') around explicit string names is optional

  • Property names are not case-sensitive

  • Enclosing square brackets ('['']') around explicit string names is optional

  • Property names are not case-sensitive

  • Enclosing square brackets ('['']') around explicit string names is optional

  • Property names are not case-sensitive

Error Conditions

  • Returns an error if property does not exist or property is not eligible for sorting.

  • If sort field is an empty string, no error is returned and the collection is not sorted.

  • Returns an error if property does not exist or property is not eligible for sorting.

  • If sort field is an empty string, no error is returned and the collection is not sorted.

  • Returns an error if property does not exist or property is not eligible for sorting.

  • Returns an error if sort field is an empty string


Storing Outlook Items

 Copy code hover
[image]

Storing Outlook Items
Send feedback

This topic describes how Outlook items are stored in folders and stores based on an account in the current profile.

The Outlook object model provides the following objects to store Outlook items:

  • The Folder object, which represents a container for other Folder objects and Outlook items.

    Note Note

    The Folder object has replaced the MAPIFolder object that existed in Microsoft Office Outlook 2003 and earlier versions of Outlook. New solutions should only use Folder.

  • The Folders collection, which represents all the Folder objects at one level of the folder tree in a store. The Folders collection can also represent a collection of search folders.

    Note Note

    Although a search folder is represented programmatically by a Folder object, not all events, methods, and properties of Folder apply to search folders.

  • The Store object, which represents a file on the local computer or a network drive that stores e-mail messages and other items. If you use an Exchange server, you can have a store on the server, in an Exchange Public folder, or on a local computer in a Personal Folders File (.pst) or Offline Folder File (.ost). For a POP3, IMAP, and HTTP e-mail server, a store is a .pst file.

    You can add a store to the current profile using NameSpace.AddStore and NameSpace.AddStoreEx, and remove an existing store from the current profile using NameSpace.RemoveStore.

  • The Stores collection, which represents all the stores in the current Outlook profile. A profile defines one or more e-mail accounts, and each e-mail account is associated with a server of a specific type. The type of server determines the type of the store and how e-mail and other items are delivered and stored. For example, an Exchange server stores e-mail and other items in either a .pst file or a .ost file on the local computer or a mapped network drive, and an HTTP server (such as Hotmail) stores items in a .pst file on the local computer.

The Store and Stores objects support the following:

  • Enumerating folders in a store using Store.GetRootFolder and then Folder.Folders.

  • Enumerating search folders in a store using Store.GetSearchFolders.

    Note Note

    Since a store does not necessarily support search folders, in general, you should trap for returned errors when using Store.GetSearchFolders to obtain any search folders on a store.

  • Better performance with enumerating folders. Because getting the root folder or search folders in a store requires the store to be open and opening a store imposes an overhead on performance, you can check the Store.IsOpen property before you decide to pursue the operation.

  • Locating a local store (.pst or .ost) for an Exchange server, or a store (.pst) for a POP3, IMAP, or HTTP e-mail server, using the Store.FilePath property.

  • Discovery of the Exchange store type and differentiation among different Exchange store types using the Store.ExchangeStoreType property.

  • Additional information for an Exchange server through the Store.IsCachedExchange and Store.IsDataFileStore properties.

  • The PropertyAccessor object through the Store.PropertyAccessor property, allowing access to store properties that are not exposed as explicit built-in properties in the Outlook object model.


Working with EntryIDs and StoreIDs

 Copy code hover
[image]

Working with EntryIDs and StoreIDs
Send feedback

This topic describes using the Entry ID of an item and Store ID of a store to access a specific item in a NameSpace.

If you're creating a more complex solution using Microsoft Outlook that involves linking or cross-referencing items in folders, one option is to use the MAPI-based identifiers (IDs) of each item. If you know the IDs of an item and the folder it's stored in, you can directly reference the item using the NameSpace.GetItemFromID method.

Each Outlook item has a field called EntryID, which is a unique ID field generated by the messaging storage system for use with the MAPI folders that store the item. It's important to note that whenever an item is created in a folder, it is assigned a new EntryID. This means that the EntryID field changes if an item is moved to a different folder or if an item is exported and then imported (even to the same folder).

Each folder has an ID field called Folder.StoreID, the value of which is the same for all the folders in a particular message store. Each folder also has a unique Entry ID field.

When using the GetItemFromID method to retrieve an item based on its ID, you should specify both the EntryID of the item and the StoreID of the folder. If you do not specify the StoreID, GetItemFromID searches the default message store.

The following Microsoft Visual Basic for Applications (VBA) example illustrates the use of the GetItemFromID method. The code retrieves the StoreID from the default Contacts folder, fills an array (MyEntryID) with the Entry IDs of all of the contacts in the folder, and finally retrieves a specific contact item:

Copy code Copy code
Sub OutlookEntryID()
 ' If there are more than 500 contacts, change the following line:
 Dim MyEntryID(500) As String
 Dim StoreID As String
 Dim EntryID As String

 Set olns = Application.GetNamespace("MAPI")
 Set objFolder = olns.GetDefaultFolder(olFolderContacts)
 ' Get the StoreID, which is a property of the folder.
 StoreID = objFolder.StoreID
 ' Set objAllContacts equal to the collection of all contacts.
 Set AllContacts = objFolder.Items
 I = 0
 ' Loop to get all of the EntryIDs for the contacts.
 For Each Item In AllContacts
 I = I + 1
 MyEntryID(I) = Item.EntryID
 Next
 ' Randomly choose the 2nd contact to retrieve.
 Set Item = olns.GetItemFromID(MyEntryID(2), StoreID)
 Item.Display
End Sub


Outlook Item Objects

 Copy code hover
[image]

Outlook Item Objects
Send feedback

The following are the item-level objects defined in the Outlook object model:

  • AppointmentItem Object

  • ContactItem Object

  • DistListItem Object

  • DocumentItem Object

  • JournalItem Object

  • MailItem Object

  • MeetingItem Object

  • NoteItem Object

  • PostItem Object

  • RemoteItem Object

  • ReportItem Object

  • SharingItem Object

  • StorageItem Object

  • TaskItem Object

  • TaskRequestAcceptItem Object

  • TaskRequestDeclineItem Object

  • TaskRequestItem Object

  • TaskRequestUpdateItem Object


How to: Attach a File to a Mail Item

 Copy code hover
[image]

How to: Attach a File to a Mail Item
Send feedback

This topic shows a procedure that attaches a spreadsheet file to a mail item. The procedure, AddAttachment, assumes that the specified spreadsheet, Q496.xlsx, exists in the specified path, D:\Documents. AddAttachment creates a new mail message, attaches Q496.xlsx to the mail message, assigns the attachment a descriptive caption, and displays the mail message with this attachment.

VBA Copy code Copy code
Sub AddAttachment()
 Dim myItem As Outlook.MailItem
 Dim myAttachments As Outlook.Attachments

 Set myItem = Application.CreateItem(olMailItem)
 Set myAttachments = myItem.Attachments
 myAttachments.Add "D:\Documents\Q496.xlsx", _
 olByValue, 1, "4th Quarter 1996 Results Chart"
 myItem.Display
End Sub


How to: Create a Recurring Appointment that Occurs Every 2 Years

 Copy code hover
[image]

How to: Create a Recurring Appointment that Occurs Every 2 Years
Send feedback

This topic shows a Visual Basic for Applications (VBA) code example that creates an appointment that occurs in the following pattern:

  • Starts at 2 P.M. and ends at 5 P.M.

  • Occurs on the last Monday of June.

  • Occurs every other year for three instances.

  • Becomes effective June 1, 2009.

The code example results in a recurring appointment from 2 P.M. to 5 P.M., on the last Monday of June in 2009 (June 29, 2009), 2011 (June 27, 2011), and 2013 (June 24, 2013). The appointment is saved in the default calendar and is then displayed.

VBA Copy code Copy code
Sub RecurringYearNth()
 Dim oAppt As AppointmentItem
 Dim oPattern As RecurrencePattern
 Set oAppt = Application.CreateItem(olAppointmentItem)
 Set oPattern = oAppt.GetRecurrencePattern
 With oPattern
 ' Appointment occurs every n-th year (with n indicated by the Interval property).
 .RecurrenceType = olRecursYearNth
 ' Appointment occurs on Monday.
 .DayOfWeekMask = olMonday
 ' Appointment occurs in June.
 .MonthOfYear = 6
 ' Appointment occurs on the 5th or last Monday (per the DayOfWeekMask property).
 .Instance = 5
 ' Appointment occurs three times.
 .Occurrences = 3
 ' Appointment lasts for 180 minutes each time.
 .Duration = 180
 ' Appointment becomes effective on June 1, 2009.
 .PatternStartDate = #6/1/2009#
 ' Appointment starts at 2 P.M.
 .StartTime = #2:00:00 PM#
 ' Appointment ends at 5 P.M.
 .EndTime = #5:00:00 PM#
 ' Appointment recurs every 2 years (per a RecurrenceType of olRecursYearNth).
 .Interval = 2
 End With
 oAppt.Subject = "Recurring every 2 years YearNth Appointment"
 oAppt.Save
 oAppt.Display
End Sub


How to: Create an Appointment as a Meeting on the Calendar

 Copy code hover
[image]

How to: Create an Appointment as a Meeting on the Calendar
Send feedback

This topic shows a Visual Basic for Applications (VBA) procedure, CreateAppt, that programmatically creates an appointment, sets various properties, and sends the appointment to request a meeting. CreateAppt uses the CreateItem method to create an AppointmentItem object. It sets the MeetingStatus property of the AppointmentItem to olMeeting to indicate the appointment as a meeting request, and sets a required attendee, an optional attendee, and a meeting location as a resource. The example then displays and sends the appointment item.

VBA Copy code Copy code
Sub CreateAppt()
 Dim myItem As Object
 Dim myRequiredAttendee, myOptionalAttendee, myResourceAttendee As Outlook.Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)
 myItem.MeetingStatus = olMeeting
 myItem.Subject = "Strategy Meeting"
 myItem.Location = "Conf Rm All Stars"
 myItem.Start = #9/24/2009 1:30:00 PM#
 myItem.Duration = 90
 Set myRequiredAttendee = myItem.Recipients.Add("Nate Sun")
 myRequiredAttendee.Type = olRequired
 Set myOptionalAttendee = myItem.Recipients.Add("Kevin Kennedy")
 myOptionalAttendee.Type = olOptional
 Set myResourceAttendee = myItem.Recipients.Add("Conf Rm All Stars")
 myResourceAttendee.Type = olResource
 myItem.Display
 myItem.Send
End Sub


How to: Delete All Items and Subfolders in the Deleted Items Folder

 Copy code hover
[image]

How to: Delete All Items and Subfolders in the Deleted Items Folder
Send feedback

This topic shows a code sample in Visual Basic for Applications (VBA) that deletes all items and subfolders in the Deleted Items folder.

Note Note

When you delete items or folders from a collection, you must use a decrementing loop counter. An incrementing loop counter will fail.

You can only empty the Deleted Items folder and you cannot remove the folder itself. However, to delete subfolders of the Deleted Items folder, you can simply delete the subfolder without first deleting its contents.

VBA Copy code Copy code
Sub RemoveAllItemsAndFoldersInDeletedItems()
 Dim oDeletedItems As Outlook.Folder
 Dim oFolders As Outlook.Folders
 Dim oItems As Outlook.Items
 Dim i As Long
 'Obtain a reference to deleted items folder
 Set oDeletedItems = Application.Session.GetDefaultFolder(olFolderDeletedItems)
 Set oItems = oDeletedItems.Items
 For i = oItems.Count To 1 Step -1
 oItems.Item(i).Delete
 Next
 Set oFolders = oDeletedItems.Folders
 For i = oFolders.Count To 1 Step -1
 oFolders.Item(i).Delete
 Next
End Sub


How to: Enumerate Folders on All Stores

 Copy code hover
[image]

How to: Enumerate Folders on All Stores
Send feedback

This topic shows a code sample that enumerates all folders on all stores for a session.

  1. The code sample begins by getting all the stores for the current session using the NameSpace.Stores property of the current session, Application.Session.

  2. For each store of this session, it uses Store.GetRootFolder to obtain the folder at the root of the store.

  3. For the root folder of each store, it iteratively calls the EnumerateFolders procedure until it has visited and displayed the name of each folder in that tree.

Remarks

To run this code sample, place the code in the built-in ThisOutlookSession module. Run the EnumerateFoldersInStores procedure:

Copy code Copy code
Sub EnumerateFoldersInStores()
 Dim colStores As Outlook.Stores
 Dim oStore As Outlook.Store
 Dim oRoot As Outlook.Folder

 On Error Resume Next
 Set colStores = Application.Session.Stores
 For Each oStore In colStores
 Set oRoot = oStore.GetRootFolder
 Debug.Print (oRoot.FolderPath)
 EnumerateFolders oRoot
 Next
End Sub

Private Sub EnumerateFolders(ByVal oFolder As Outlook.Folder)
 Dim folders As Outlook.folders
 Dim Folder As Outlook.Folder
 Dim foldercount As Integer

 On Error Resume Next
 Set folders = oFolder.folders
 foldercount = folders.Count
 'Check if there are any folders below oFolder
 If foldercount Then
 For Each Folder In folders
 Debug.Print (Folder.FolderPath)
 EnumerateFolders Folder
 Next
 End If
End Sub


How to: Enumerate Search Folders on All Stores

 Copy code hover
[image]

How to: Enumerate Search Folders on All Stores
Send feedback

This topic describes a code sample that enumerates the search folders on all stores for the current session.

  1. The code sample begins by getting all the stores for the current session using the NameSpace.Stores property of the current session, Application.Session.

  2. For each store of this session, it uses Store.GetSearchFolders to obtain the collection of search folders for that store.

  3. For each collection of search folders, it displays the name of each folder.

Remarks

To run this code sample, place the code in the built-in ThisOutlookSession module. Run the EnumerateSearchFoldersInStores procedure:

Copy code Copy code
Sub EnumerateSearchFoldersInStores()
 Dim colStores As Outlook.Stores
 Dim oStore As Outlook.Store
 Dim oSearchFolders As Outlook.folders
 Dim oFolder As Outlook.Folder

 On Error Resume Next
 Set colStores = Application.Session.Stores
 For Each oStore In colStores
 Set oSearchFolders = oStore.GetSearchFolders
 For Each oFolder In oSearchFolders
 Debug.Print (oFolder.FolderPath)
 Next
 Next
End Sub


How to: Enumerate the Contacts Folder and Set Custom Property for only Contact Items

 Copy code hover
[image]

How to: Enumerate the Contacts Folder and Set Custom Property for only Contact Items
Send feedback

An Outlook folder can contain items of more than one message class. For example, by default, you can create contact items and distribution list items in the Contacts folder. If you want to systematically apply an action to only the contact items or to only the distribution list items in the folder, you must check for the message class for each item in the folder before applying the action.

This topic shows a code sample that uses the message class of an item to identify contact items and sets a user-defined Affiliation field for all contact items in the Contacts folder. The following describes the process:

  1. The code sample gets all the items in the default Contacts folder.

  2. It uses Items.Restrict to filter contact items from all the items in the default Contacts folder.

  3. For each contact item, it uses UserProperties.Add to add a user-defined field Affiliation and sets it based on the existence of a home telephone number. If a home telephone number does not exist for the item, the Affiliation property is set to Business; otherwise, the field is set to Personal.

Remarks

To run this code sample, place the code in the built-in ThisOutlookSession module. Run the SetAffiliationForContacts procedure.

Note that if a field of the name Affiliation already exists, running this example will overwrite it.

Copy code Copy code
Sub SetAffiliationForContacts()
 Dim ns As NameSpace
 Dim foldContact As Folder
 Dim itemContact As ContactItem
 Dim colItems As Outlook.Items
 Dim myProperty As Outlook.UserProperty

 Set ns = Application.GetNamespace("MAPI")
 Set foldContact = ns.GetDefaultFolder(olFolderContacts)
 Set colItems = foldContact.Items.Restrict("[MessageClass]='IPM.Contact'")

 For Each itemContact In colItems
 ' Add user property to contact items
 Set myProperty = itemContact.UserProperties.Add("Affiliation", olText)
 If itemContact.HomeTelephoneNumber = "" Then
 myProperty = "Business"
 Else
 myProperty = "Personal"
 End If
 itemContact.Save
 Next
End Sub


How to: Import Appointment XML Data into Outlook Appointment Objects (Outlook)

 Copy code hover
[image]

How to: Import Appointment XML Data into Outlook Appointment Objects (Outlook)
Send feedback

This topic shows how to read appointment data formatted in XML, save the data to Microsoft OutlookAppointmentItem objects in the default calendar, and return the appointment objects in an array.

Helmut Obertanner provided the following code samples. Helmut is a Microsoft Most Valuable Professional with expertise in Microsoft Office development tools in Microsoft Visual Studio and Microsoft Office Outlook. Helmut maintains a professional site at X4Uelectronix.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code samples contain the CreateAppointmentsFromXml method of the Sample class, implemented as part of an Outlook add-in project. Each project adds a reference to the Outlook PIA, which is based on the Microsoft.Office.Interop.Outlook namespace.

The CreateAppointmentsFromXml method accepts two input parameters, application and xml:

  • application is a trusted Outlook Application object.

  • xml is either an XML string, or a string that represents a path to a valid XML file. For the purpose of the following code samples, the XML delimits appointment data by using the following XML tags:

    Appointment data

    Delimiting XML tag

    Entire set of appointment data

    <appointments>

    Each appointment in the set

    <appointment>

    Start time of an appointment

    <starttime>

    End time of an appointment

    <endtime>

    Title of an appointment

    <subject>

    Location of an appointment

    <location>

    Details of an appointment

    <body>

The following example shows input data for the xml parameter.

XML Copy code Copy code
<?xml version="1.0" encoding="utf-8" ?>
<appointments>
    <appointment>
        <starttime>2009-06-01T15:00:00</starttime>
        <endtime>2009-06-01T16:15:00</endtime>
        <subject>This is a Test-Appointment</subject>
        <location>At your Desk</location>
        <body>Here is the Bodytext</body>
    </appointment>
    <appointment>
        <starttime>2009-06-01T17:00:00</starttime>
        <endtime>2009-06-01T17:15:00</endtime>
        <subject>This is a second Test-Appointment</subject>
        <location>At your Desk</location>
        <body>Here is the Bodytext</body>
    </appointment>
    <appointment>
        <starttime>2009-06-01T17:00:00</starttime>
        <endtime>2009-06-01T18:15:00</endtime>
        <subject>This is a third Test-Appointment</subject>
        <location>At your Desk</location>
        <body>Here is the Bodytext</body>
    </appointment>
</appointments>

The CreateAppointmentsFromXml method uses the Microsoft COM implementation of the XML Document Object Model (DOM) to load and process the XML data that xml provides. CreateAppointmentsFromXml first checks whether xml specifies a valid source of XML data. If so, it loads the data into an XML document, DOMDocument. Otherwise, CreateAppointmentsFromXml throws an exception. For more information about the XML DOM, see DOM.

For each appointment child node delimited by the <appointment> tag in the XML data, CreateAppointmentsFromXml looks for specific tags, uses the DOM to extract the data, and assigns the data to corresponding properties of an AppointmentItem object: Start, End, Subject, Location, and Body. CreateAppointmentsFromXml then saves the appointment to the default calendar.

CreateAppointmentsFromXml uses the Add method of the List(type) class in the System.Collections.Generic namespace to aggregate these AppointmentItem objects. When the method has processed all the appointments in the XML data, it returns the AppointmentItem objects in an array.

The following is the C# code sample.

C# Copy code Copy code
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Xml;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace OutlookAddIn1
{
    class Sample
    {
        Outlook.AppointmentItem[] CreateAppointmentsFromXml(Outlook.Application application,
                                                            string xml)
        {
            // Create a list of appointment objects.
            List<Outlook.AppointmentItem> appointments = new
                List<Microsoft.Office.Interop.Outlook.AppointmentItem>();
            XmlDocument xmlDoc = new XmlDocument();

            // If xml is an XML string, create the document directly.
            if (xml.StartsWith("<?xml"))
            {
                xmlDoc.LoadXml(xml);
            }
            else if (File.Exists(xml))
            {
                xmlDoc.Load(xml);
            }
            else
            {
                throw new Exception(
                    "The input string is not valid XML data or the specified file doesn't exist.");
            }

            // Select all appointment nodes under the root appointements node.
            XmlNodeList appointmentNodes = xmlDoc.SelectNodes("appointments/appointment");
            foreach (XmlNode appointmentNode in appointmentNodes)
            {

                // Create a new AppointmentItem object.
                Outlook.AppointmentItem newAppointment =
                    (Outlook.AppointmentItem)application.CreateItem(Outlook.OlItemType.olAppointmentItem);

                // Loop over all child nodes, check the node name, and import the data into the
                // appointment fields.
                foreach (XmlNode node in appointmentNode.ChildNodes)
                {
                    switch (node.Name)
                    {

                        case "starttime":
                            newAppointment.Start = DateTime.Parse(node.InnerText);
                            break;

                        case "endtime":
                            newAppointment.End = DateTime.Parse(node.InnerText);
                            break;

                        case "subject":
                            newAppointment.Subject = node.InnerText;
                            break;

                        case "location":
                            newAppointment.Location = node.InnerText;
                            break;

                        case "body":
                            newAppointment.Body = node.InnerText;
                            break;

                    }
                }

                // Save the item in the default calendar.
                newAppointment.Save();
                appointments.Add(newAppointment);
            }

            // Return an array of new appointments.
            return appointments.ToArray();
        }

    }
}

The following is the Visual Basic code sample.

Visual Basic Copy code Copy code
Imports System.IO
Imports System.Xml
Imports Outlook = Microsoft.Office.Interop.Outlook

Namespace OutlookAddIn2
    Class Sample
        Function CreateAppointmentsFromXml(ByVal application As Outlook.Application, _
            ByVal xml As String) As Outlook.AppointmentItem()

            Dim appointments As New List(Of Outlook.AppointmentItem)
            Dim xmlDoc As New XmlDocument()

            If xml is an XML string, create the XML document directly.
            If xml.StartsWith("<?xml") Then
                xmlDoc.LoadXml(xml)
            ElseIf (File.Exists(xml)) Then
                xmlDoc.Load(xml)
            Else
                Throw New Exception("The input string is not valid XML data or the specified file doesn't exist.")
            End If

            ' Select all appointment nodes under the root appointements node.
            Dim appointmentNodes As XmlNodeList = xmlDoc.SelectNodes("appointments/appointment")

            For Each appointmentNode As XmlNode In appointmentNodes

                ' Create a new AppointmentItem object.
                Dim newAppointment As Outlook.AppointmentItem = _
                    DirectCast(application.CreateItem(Outlook.OlItemType.olAppointmentItem), _
                    Outlook.AppointmentItem)

                ' Loop over all child nodes, check the node name, and import the data into the appointment fields.

                For Each node As XmlNode In appointmentNode.ChildNodes
                    Select Case (node.Name)

                        Case "starttime"
                            newAppointment.Start = DateTime.Parse(node.InnerText)

                        Case "endtime"
                            newAppointment.End = DateTime.Parse(node.InnerText)

                        Case "subject"
                            newAppointment.Subject = node.InnerText

                        Case "location"
                            newAppointment.Location = node.InnerText

                        Case "body"
                            newAppointment.Body = node.InnerText

                    End Select
                Next

                ' Save the item in the default calendar.
                newAppointment.Save()
                appointments.Add(newAppointment)
            Next

            ' Return an array of new appointments.
            Return appointments.ToArray()
        End Function

    End Class
End Namespace


How to: Obtain a Folder Object from a Folder Path

 Copy code hover
[image]

How to: Obtain a Folder Object from a Folder Path
Send feedback

This topic shows a function that accepts a folder path and returns a Folder object that corresponds to the specified folder. For example, if you provide the folder path "Mailbox - Dan Wilson\Inbox\Customers", the code in the TestGetFolder procedure will display the Folder object that corresponds to the Customers folder under Dan Wilson's Inbox, if the Customers folder exists under the Inbox. If the Customers folder does not exist, GetFolder will return Nothing.

VBA Copy code Copy code
Function GetFolder(ByVal FolderPath As String) As Outlook.Folder
 Dim TestFolder As Outlook.Folder
 Dim FoldersArray As Variant
 Dim i As Integer

 On Error GoTo GetFolder_Error
 If Left(FolderPath, 2) = "\\" Then
 FolderPath = Right(FolderPath, Len(FolderPath) - 2)
 End If
 'Convert folderpath to array
 FoldersArray = Split(FolderPath, "\")
 Set TestFolder = Application.Session.Folders.item(FoldersArray(0))
 If Not TestFolder Is Nothing Then
 For i = 1 To UBound(FoldersArray, 1)
 Dim SubFolders As Outlook.Folders
 Set SubFolders = TestFolder.Folders
 Set TestFolder = SubFolders.item(FoldersArray(i))
 If TestFolder Is Nothing Then
 Set GetFolder = Nothing
 End If
 Next
 End If
 'Return the TestFolder
 Set GetFolder = TestFolder
 Exit Function

GetFolder_Error:
 Set GetFolder = Nothing
 Exit Function
End Function

Sub TestGetFolder()
 Dim folder As Outlook.Folder
 Set folder = GetFolder ("\\Mailbox - Dan Wilson\Inbox\Customers")
 If Not(folder Is Nothing) Then
 folder.Display
 End If
End Sub


How to: Send an E-mail Given the SMTP Address of an Account (Outlook)

 Copy code hover
[image]

How to: Send an E-mail Given the SMTP Address of an Account (Outlook)
Send feedback

This topic shows how to create an e-mail and send it from a Microsoft Outlook account, given the Simple Mail Transfer Protocol (SMTP) address of that account.

Helmut Obertanner provided the following code samples. Helmut is a Microsoft Most Valuable Professional with expertise in Microsoft Office development tools in Microsoft Visual Studio and Microsoft Office Outlook. Helmut maintains a professional site at X4Uelectronix.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code samples contain the SendEmailFromAccount and GetAccountForEmailAddress methods of the Sample class, implemented as part of an Outlook add-in project. Each project adds a reference to the Outlook PIA, which is based on the Microsoft.Office.Interop.Outlook namespace. The SendEmailFromAccount method accepts as input arguments a trusted Application object, and strings that represent the subject, body, a semicolon-delimited list of recipients, and the SMTP address of an e-mail account. SendEmailFromAccount creates a MailItem object and initializes the To, Subject, and Body properties with the given arguments. To find the Account object from which to send the e-mail, SendEmailFromAccount calls the GetAccountForEmailAddress method, which matches the given SMTP address with the SmtpAddress property of each account for the current profile. The matching Account object is returned to SendEmailFromAccount, which then initializes the SendUsingAccount property of the MailItem with this Account object, and sends the MailItem.

The following is the C# code sample.

C# Copy code Copy code
using System;
using System.Text;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace OutlookAddIn1
{
    class Sample
    {
        public static void SendEmailFromAccount(Outlook.Application application, string subject, string body, string to, string smtpAddress)
        {

            // Create a new MailItem and set the To, Subject, and Body properties.
            Outlook.MailItem newMail = (Outlook.MailItem)application.CreateItem(Outlook.OlItemType.olMailItem);
            newMail.To = to;
            newMail.Subject = subject;
            newMail.Body = body;

            // Retrieve the account that has the specific SMTP address.
            Outlook.Account account = GetAccountForEmailAddress(application, smtpAddress);
            // Use this account to send the e-mail.
            newMail.SendUsingAccount = account;
            newMail.Send();
        }

        public static Outlook.Account GetAccountForEmailAddress(Outlook.Application application, string smtpAddress)
        {

            // Loop over the Accounts collection of the current Outlook session.
            Outlook.Accounts accounts = application.Session.Accounts;
            foreach (Outlook.Account account in accounts)
            {
                // When the e-mail address matches, return the account.
                if (account.SmtpAddress == smtpAddress)
                {
                    return account;
                }
            }
            throw new System.Exception(string.Format("No Account with SmtpAddress: {0} exists!", smtpAddress));
        }

    }
}

The following is the Visual Basic code sample.

Visual Basic Copy code Copy code
Imports Outlook = Microsoft.Office.Interop.Outlook

Namespace OutlookAddIn2
    Class Sample

        Shared Sub SendEmailFromAccount(ByVal application As Outlook.Application, _
            ByVal subject As String, ByVal body As String, ByVal recipients As String, ByVal smtpAddress As String)

            ' Create a new MailItem and set the To, Subject and Body properties.
            Dim newMail As Outlook.MailItem = DirectCast(application.CreateItem(Outlook.OlItemType.olMailItem), Outlook.MailItem)
            newMail.To = recipients
            newMail.Subject = subject
            newMail.Body = body

            ' Retrieve the account that has the specific SMTP address.
            Dim account As Outlook.Account = GetAccountForEmailAddress(application, smtpAddress)
            ' Use this account to send the e-mail.
            newMail.SendUsingAccount = account
            newMail.Send()
        End Sub

        Shared Function GetAccountForEmailAddress(ByVal application As Outlook.Application, ByVal smtpAddress As String) As Outlook.Account

            ' Loop over the Accounts collection of the current Outlook session.
            Dim accounts As Outlook.Accounts = application.Session.Accounts
            Dim account As Outlook.Account
            For Each account In accounts
                ' When the e-mail address matches, return the account.
                If account.SmtpAddress = smtpAddress Then
                    Return account
                End If
            Next
            Throw New System.Exception(String.Format("No Account with SmtpAddress: {0} exists!", smtpAddress))
        End Function

    End Class
End Namespace


How to: Specify an Internet Encoding Scheme for the Body and Attachments of a Message

 Copy code hover
[image]

How to: Specify an Internet Encoding Scheme for the Body and Attachments of a Message
Send feedback

This topic shows how to use the MAPI property, PidTagInternetMailOverrideFormat, and the Microsoft Outlook object model to specify an Internet encoding scheme for the Exchange Internet Mail Service (IMS) to encode the body and attachments of a mail item.

The following code sample in Visual C# shows how to reference PidTagInternetMailOverrideFormat with its MAPI proptag namespace and use the PropertyAccessor object of the Outlook object model to specify MIME as the Internet encoding scheme for a message. PidTagInternetMailOverrideFormat is referenced as:

Copy code Copy code
http://schemas.microsoft.com/mapi/proptag/0x59020003

where 0x59020003 is the proptag of PidTagInternetMailOverrideFormat.

C# Copy code Copy code
private void SendMail_Click()
{
    Outlook.NameSpace objSession;
    Outlook.MailItem objMailItem;
    Outlook.Recipient objRecipient;
    Outlook.PropertyAccessor oPA;

    string Recipient, MsgSubject, ImageFile, TextFile, FileLocation, PropName;
    int EncodingFlag;

    //Modify the following to appropriate values.
    Recipient = "someone@example.com";
    EncodingFlag = 1; //Use MIME encoding
    MsgSubject = "Test Encoding";
    ImageFile = "garden.jpg";
    TextFile = "mytext.txt";
    FileLocation = "c:\\";

    objSession = Application.GetNamespace("MAPI");
    objSession.Logon(null, null, true, null);

    objMailItem = Application.CreateItem(
                Outlook.OlItemType.olMailItem) as Outlook.MailItem;
    objMailItem.Subject = MsgSubject;
    objMailItem.Body = "body";
    objMailItem.Attachments.Add(FileLocation + TextFile,
        Outlook.OlAttachmentType.olByValue, 1, TextFile);
    objMailItem.Attachments.Add(FileLocation + ImageFile,
        Outlook.OlAttachmentType.olByValue, 1, ImageFile);

    objRecipient = objMailItem.Recipients.Add(Recipient);
    objRecipient.Resolve();

    PropName = "http://schemas.microsoft.com/mapi/proptag/0x59020003";
    oPA = objMailItem.PropertyAccessor;
    oPA.SetProperty(PropName, EncodingFlag);

    objMailItem.Send();

    objSession.Logoff();

}


How to: Specify Whether to Display a Contact's Picture in Outlook

 Copy code hover
[image]

How to: Specify Whether to Display a Contact's Picture in Outlook
See also Send feedback

This topic shows how to use the dispidShowSenderPhoto dispatch ID to invoke the corresponding method on a Microsoft Outlook Explorer or Inspector object, to specify whether to display a contact's picture in the explorer or inspector window, according to a Boolean argument. Specifying true as the argument turns on the display, and false turns off the display. Note that the solution does not require the Outlook object model, but nonetheless, you can use C# code similar to the code sample in this topic to achieve the same in your managed Outlook solution.

Given a pointer to an Explorer or Inspector object, you can use the Object.GetType() method to obtain a System.Type object.

The function in this topic, SetSenderContactPhoto, accepts two input parameters:

  • Inspector—An InspectorPtr object.

  • ShowSenderContactPhoto—A Boolean value that specifies whether to display contacts' pictures.

SetSenderContactPhoto constructs the string representation of the dispidShowSenderPhoto dispatch ID as dispidShowSenderPhotoMemberName. SetSenderContactPhoto then calls the Type.InvokeMember method—specifying dispidShowSenderPhoto as the argument for the name parameter and the flag System.Reflection.BindingFlags.InvokeMethod as the argument for invokeAttr, and using ShowSenderContactPhoto to form the argument for the args parameter—to turn on or off the display in an inspector according to the value of ShowSenderContactPhoto.

C# Copy code Copy code
void SetSenderContactPhoto(object Inspector, bool ShowSenderContactPhoto)
{
    Type typeInspector = Inspector.GetType();
    string dispidShowSenderPhotoMemberName = String.Format("[DispID={0}]", 0xF0D0);
    object[] args = {ShowSenderContactPhoto};

    try
    {
        typeInspector.InvokeMember(dispidShowSenderPhotoMemberName,
            System.Reflection.BindingFlags.InvokeMethod,
            null,
            Inspector,
            args);
    }
    catch(System.Runtime.InteropServices.COMException comEx)
    {

    }
}

This setting does not persist across Outlook sessions and does not carry from one inspector or explorer to another. The default setting is to turn on the display. This means that if a picture is present, it is displayed. However, if no picture is present, no placeholder picture is displayed.

This setting works in conjunction with the TurnOffPhotograph policy key as well as the older ShowContactPicture registry key. The TurnOffPhotograph policy key was introduced in Microsoft Outlook 2010, and ShowContactPicture registry key was introduced in Microsoft Office Outlook 2007. The following table shows how these registry keys and dispidShowSenderPhoto interact. This setting does not turn on the display if administrator policy (TurnOffPhotograph policy key) or user preference (ShowContactPicture registry key) turns off the display. For more information about the TurnOffPhotograph policy key, see How to manage the Outlook Social Connector by using Group Policy. For more information about the ShowContactPicture registry key, see Deploying additional registry values in the Office Customization Tool for Outlook 2007.

Argument for method represented by dispidShowSenderPhoto | TurnOffPhotograph policy key | ShowContactPicture registry key | Is picture displayed if present?
True | 0 or not set | 1 or not set | Yes
True | 0 or not set | 0 | No
True | 1 | 1 or not set | No
True | 1 | 0 | No
False | 0 or not set | 1 or not set | No
False | 0 or not set | 0 | No
False | 1 | 1 or not set | No
False | 1 | 0 | No

See also

Concepts

How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)


Navigation

 Copy code hover
[image]

Navigation
Send feedback

In this section

  • Customizing the Navigation Pane

  • Adding Solution-Specific Folders to the Solutions Module

  • How to: Show or Hide the Navigation Pane

  • How to: Enumerate, Show, Hide, and Position Modules in the Navigation Pane

  • How to: Set a Module as the Currently Selected Module in the Navigation Pane

  • How to: Display Specific Modules in the Navigation Pane

  • How to: Add a Folder to the Favorite Folders Group

  • How to: Enumerate Active Folders in the Calendar View

  • How to: Add a Custom Folder to a Group and Display it in Overlay Mode by Default


Customizing the Navigation Pane

 Copy code hover
[image]

Customizing the Navigation Pane
See also Send feedback

The Navigation Pane provides access to information that pertains to the active explorer, including different views and different ways to accomplish tasks in that explorer. The NavigationPane object represents the Navigation Pane for an explorer; to obtain one, call the NavigationPane property of the Explorer object. If the explorer does not contain a Navigation Pane, this property returns Null (Nothing in Visual Basic).

Navigation Modules

The Navigation Pane contains the set of navigation modules that are available in Outlook; for example, the Mail module. Each navigation module is represented by a NavigationModule object or by an object that is derived from the NavigationModule object. The Modules property of the NavigationPane object provides access to the navigation modules that are in the Navigation Pane. You can use the following objects to access the corresponding navigation module:

Navigation module | Object
Calendar | CalendarModule
Contacts | ContactsModule
Journal | JournalModule
Folder List | NavigationModule
Mail | MailModule
Notes | NotesModule
Shortcuts | NavigationModule
Solutions | SolutionsModule
Tasks | TasksModule

Note that the Solutions module is not displayed in the Navigation Pane by default, and can only be created programmatically. The default name of the module is Solutions, but you can customize that name.

Navigation Groups and Navigation Folders

Each navigation module contains a set of navigation groups. A navigation group, represented by the NavigationGroup object, is a container for navigation folders. A navigation folder, represented by the NavigationFolder object, provides an access point in the Navigation Pane for a Folder object. You can obtain a NavigationGroup object reference by using the NavigationGroups property of a CalendarModule, ContactsModule, JournalModule, MailModule, NotesModule, or TasksModule object. The Folder List, Shortcuts, and Solutions navigation modules do not contain navigation groups.

You can create and delete custom navigation groups by using the NavigationGroups.Create and NavigationGroups.Delete methods. You can identify a custom navigation group by using the NavigationGroup.GroupType property to retrieve the navigation group type for the object, and you can retrieve the default navigation group for a specified group type by using the NavigationGroups.GetDefaultNavigationGroup method.

Once you have a NavigationGroup object, you can obtain a NavigationFolder object reference by using the NavigationGroup.NavigationFolders property. Each NavigationFolder represents a navigation folder associated with a Folder object. You can add navigation folders to a navigation group by using the NavigationFolders.Add method. Only one NavigationFolder object can be associated with a Folder object at any given time, so adding a NavigationFolder that is associated with a given Folder object to a navigation group automatically removes any existing NavigationFolder references that are associated with that Folder object. You can also delete navigation folders from a navigation group by using the NavigationFolders.Remove method, but only if the NavigationFolders.IsRemovable property is set to True for the NavigationFolder object to be removed. You cannot remove standard navigation folders, such as the Inbox folder, that are defined by Outlook.

Note Note

Navigation folders can be freely added or removed from the Favorite Folders navigation group, a special navigation group that is contained by the MailModule object, regardless of the IsRemovable property value of the navigation folder.

Displaying the Navigation Pane

The Navigation Pane can display navigation modules in either normal or collapsed mode. The Visible property of a NavigationModule object determines whether the navigation module is displayed in the Navigation Pane; the order that the visible navigation modules are displayed is determined by the Position property of each NavigationModule object.

You can use the IsCollapsed property to determine which mode the NavigationPane object uses. In normal mode, the visible navigation modules in the Navigation Pane are displayed as a combination of large and small buttons. The number of large buttons that are displayed in normal mode is determined by the DisplayedModuleCount property. If there are more visible navigation modules than are specified by this property, the remaining visible navigation modules are displayed as small buttons at the bottom of the Navigation Pane. In collapsed mode, the visible navigation modules in the Navigation Pane are displayed as small buttons. The number of small buttons displayed in collapsed mode is determined by the DisplayedModuleCount property. If there are more visible navigation modules than are specified by this property, the remaining visible navigation modules are not displayed.

To change the current navigation module, set the CurrentModule property of the NavigationPane object to one of the NavigationModule objects in the navigation pane.

In each navigation module, the NavigationGroup.Position property determines the display order of the navigation groups. Similarly, the NavigationFolder.Position property determines the display order of navigation folders within each navigation group. If a NavigationFolder object represents a calendar folder, the IsSideBySide property determines if the contents of the calendar folder are displayed in side-by-side or overlay mode.

Handling Navigation Pane Events

The NavigationPane object provides the ModuleSwitch event so that add-ins can identify when the current navigation module changes in the Navigation Pane, either programmatically or by user action.

The NavigationGroups object provides the NavigationFolderAdd and NavigationFolderRemove events so that add-ins can identify when a navigation folder is added or removed from a NavigationGroup object in the collection. The NavigationGroups object also provides the SelectedChange event. Add-ins use that event to identify when the IsSelected property of a navigation folder that is associated with a calendar folder changes in the Navigation Pane, either programmatically or by user action.

To detect a user change a folder in the Folder List, use the BeforeFolderSwitch and FolderSwitch events of the Explorer object. Similarly, to detect when the Solutions module is first displayed in the Navigation Pane, or to detect a user click a different folder in the Solutions module, use the BeforeFolderSwitch and FolderSwitch events.

See also

Concepts

Adding Solution-Specific Folders to the Solutions Module


Adding Solution-Specific Folders to the Solutions Module

 Copy code hover
[image]

Adding Solution-Specific Folders to the Solutions Module
See also Send feedback

The Solutions module is a navigation module that gives Microsoft Outlook solutions a way to expose one or more folders in the Navigation Pane. By default, its display name is Solutions, and its default position is '9' in the Navigation Pane, following the Tasks navigation module.

To add a solution and its folders programmatically to the Solutions module, you must use the AddSolution method of the SolutionsModule object. You can customize the name of the module if there is only one solution in the module; otherwise the name reverts back to Solutions.

The Solutions module shares some features with other navigation modules; for example, besides the module button itself, there is a smaller button for the module that users can click to collapse module buttons on the Navigation Pane. In addition, users can open the Solutions module in a new window and customize the display of modules and their relative positions on the Navigation Pane by using the shortcut menu.

The Solutions module displays folders from each solution in its own group. Each solution has a corresponding solution root folder, and any subfolders under that root are displayed in ascending alphabetical order. Subfolders contain items of different item types; for example, you might have one subfolder for calendar items and another subfolder for tasks items. You can specify whether these folders appear under the default folders for their respective item types as well. Solution root folders are displayed in the chronological order that you added them to the Solutions module and cannot be reordered.

A solution root folder and its subfolders must reside on the same store. If the solution root folder is the root folder of a store, all subfolders of the store root folder are displayed under the solution root folder. Subfolders of the store root folder include the Deleted Items folder and the Searches root folder. The active/inactive state of search subfolders under the Searches root folder is the same in the Solutions module as it is in the Folder List.

See also

Concepts

Customizing the Navigation Pane


How to: Show or Hide the Navigation Pane

 Copy code hover
[image]

How to: Show or Hide the Navigation Pane
Send feedback

You can set the IsCollapsed property of the NavigationPane object to collapse or expand the Navigation Pane for an Explorer object. The appearance of the Navigation Pane changes depending on the setting of the IsCollapsed property, as well as the settings of other properties for the NavigationPane object. The DisplayedModuleCount property of the NavigationPane object determines the number of modules that can be displayed by the Navigation Pane, while the Visible and Position property values of each NavigationModule object determine which modules are displayed, and in what order.

Setting the IsCollapsed property to True collapses the Navigation Pane. When collapsed, the Navigation Pane displays only the icon for each visible navigation module.

Setting the IsCollapsed property to False expands the Navigation Pane. When expanded, the Navigation Pane displays the icon and name for the number of topmost visible modules contained in the NavigationModules collection of the NavigationPane object, specified by the DisplayedModuleCount property. All other visible modules are displayed as icons at the bottom of the Navigation Pane.

For example, the NavigationModules collection of an expanded NavigationPane object for the active explorer contains eight modules. All modules have a Visible property value of True, with the exception of the third navigation module (the Module object with the Position property value set to 3.) If the DisplayedModuleCount property is set to 4, the icons and names of only the first four visible NavigationModule objects, with Position property values of 1, 2, 4, and 5, are displayed as large buttons in the Navigation Pane. The remaining three visible NavigationModule objects, in positions 6, 7, and 8, are displayed only as icons, on small buttons at the bottom of the Navigation Pane. If the IsCollapsed property is set to False, the collapsed Navigation Pane displays the first four visible NavigationModule objects only as icons. The remaining three visible NavigationModule objects are available on the Navigation Pane dropdown menu.

The following sample ensures that the Navigation Pane is always expanded whenever the currently selected navigation module changes, either programmatically or by user action, by setting the IsCollapsed property to False. The sample performs the following actions:

  1. The sample first obtains a reference to the NavigationPane object for the active explorer when the Startup event of the Application object is raised and assigns it to objPane, so the ModuleSwitch event of the NavigationPane object can be detected.

  2. When the ModuleSwitch event of the NavigationPane occurs, the sample then checks if the current navigation module has changed by comparing the contents of the CurrentModule parameter of the ModuleSwitch event against the CurrentModule property of the NavigationPane object. If these object references are different, the IsCollapsed property of the NavigationPane object is set to False.

Copy code Copy code
Dim WithEvents objPane As NavigationPane

Private Sub Application_Startup()
 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane
End Sub

Private Sub objPane_ModuleSwitch(ByVal CurrentModule As NavigationModule)

 ' Check if the currently selected navigation module
 ' has changed.
 If Not (CurrentModule Is objPane.CurrentModule) Then

 ' Set the IsCollapsed property to
 ' ensure that the Navigation Pane
 ' is visible.
 If Not (objPane Is Nothing) Then
 objPane.IsCollapsed = False
 End If
 End If

End Sub


How to: Enumerate, Show, Hide, and Position Modules in the Navigation Pane

 Copy code hover
[image]

How to: Enumerate, Show, Hide, and Position Modules in the Navigation Pane
Send feedback

The NavigationModules property of the NavigationPane object in Microsoft Outlook provides access to the navigation modules contained by the Navigation Pane. You can use the Item method to enumerate the NavigationModule objects contained by the collection, as the Item method is both the default property and the indexer property for the NavigationModules collection. The CurrentModule property determines which NavigationModule object is currently selected in the Navigation Pane.

Also, each NavigationModule object provides several properties that can be used to show, hide, or change the display position of modules in the Navigation Pane:

  • The Visible property determines whether a NavigationModule object can be displayed in the Navigation Pane.

  • The Position property determines the ordinal position of a NavigationModule object when displayed in the Navigation Pane.

The DisplayedModuleCount property of the NavigationPane object determines the number of visible NavigationModule objects that can be displayed by the Navigation Pane. If the Visible property of a NavigationModule object is set to False, or if the Position property of the NavigationModule object is set such that the module doesn't fall within the number of visible NavigationModule objects that can be displayed in the Navigation Pane, the module isn't displayed.

The following code samples in Microsoft Visual Basic for Applications (VBA) consist of the MoveCurrentModuleToTop and MakeAllModulesVisible procedures.

The MoveCurrentModuleToTop procedure uses the CurrentModule property of the NavigationPane object to retrieve the currently selected NavigationModule object and sets the Position property of that NavigationModule object to 1, making it the topmost displayed module in the Navigation Pane.

The MoveCurrentModuleToTop procedure enumerates the Modules collection of the NavigationPane object, setting the Visible property of each NavigationModule object contained in the collection to True. It finally sets the DisplayedModuleCount property of the NavigationPane object to the value of the Count property of the NavigationModules collection for the NavigationPane object, ensuring that every navigation module contained in the Navigation Pane is visible to the user.

VBA Copy code Copy code
Private Sub MoveCurrentModuleToTop()

 Dim objPane As NavigationPane

 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Set the Position property of the currently selected
 ' module to 1, making it the topmost module displayed
 ' in the Navigation Pane.
 objPane.CurrentModule.Position = 1
End Sub

Private Sub MakeAllModulesVisible()

 Dim objPane As NavigationPane
 Dim objModule As NavigationModule

 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane

 ' This loop enumerates through the Modules collection,
 ' setting the Visible property of each module to True.
 For Each objModule In objPane.Modules
 objModule.Visible = True
 Next

 ' Set the DisplayedModuleCount property to
 ' display all modules contained by the
 ' Navigation Pane.
 objPane.DisplayedModuleCount = objPane.Modules.count
End Sub


How to: Set a Module as the Currently Selected Module in the Navigation Pane

 Copy code hover
[image]

How to: Set a Module as the Currently Selected Module in the Navigation Pane
Send feedback

You can use the CurrentModule property of the NavigationPane object in Microsoft Outlook to set a NavigationModule object as the currently selected navigation module in the Navigation Pane of an Explorer object.

The following sample sets the Calendar navigation module as the currently selected navigation module if the Journal navigation module is selected, either programmatically or by user action, in the Navigation Pane. The sample performs the following actions:

  1. The sample first obtains a reference to the NavigationPane object for the active explorer when the Startup event of the Application object is raised and assigns it to objPane, so the ModuleSwitch event of the NavigationPane object can be detected.

  2. When the ModuleSwitch event of the NavigationPane occurs, the sample then checks if the current navigation module has changed by comparing the contents of the CurrentModule parameter of the ModuleSwitch event against the CurrentModule property of the NavigationPane object.

  3. If these object references are different, the sample then checks the NavigationModuleType property of the NavigationModule object reference in the CurrentModule parameter of the ModuleSwitch event.

  4. If the NavigationModuleType property of the currently selected Module object is set to olModuleJournal, the sample then displays a dialog box to indicate to the user that the currently selected Journal navigation module is temporarily unavailable, and that instead the Calendar navigation module will be selected.

  5. Finally, the sample uses the GetNavigationModule method of the Modules collection for the NavigationPane object to attempt to retrieve a CalendarModule object. If successful, the CurrentModule property of the NavigationPane object is set to the retrieved CalendarModule object reference.

Copy code Copy code
Dim WithEvents objPane As NavigationPane

Private Sub Application_Startup()
 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane

End Sub

Private Sub objPane_ModuleSwitch(ByVal CurrentModule As NavigationModule)
 Dim objModule As CalendarModule

 ' Check if the currently selected navigation module
 ' has changed.
 If Not (CurrentModule Is objPane.CurrentModule) Then
 ' If the Journal module was selected, forcibly change
 ' it to the Calendar module by setting the
 ' CurrentModule property of the NavigationPane object.
 If CurrentModule.NavigationModuleType = olModuleJournal Then

 ' Let the user know what's happening.
 MsgBox "The Journal module is temporarily unavailable. " & _
 " Outlook is switching to the Calendar module, if available."

 ' Retrieve the Calendar module, if one exists, for the
 ' current Navigation Pane.
 Set objModule = objPane.Modules.GetNavigationModule(olModuleCalendar)

 ' If we have one, set the CurrentModule property of the
 ' NavigationPane object to the Calendar module.
 If Not (objModule Is Nothing) Then
 Set objPane.CurrentModule = objModule
 End If
 End If
 End If

End Sub


How to: Display Specific Modules in the Navigation Pane

 Copy code hover
[image]

How to: Display Specific Modules in the Navigation Pane
Send feedback

The CurrentModule property of the NavigationPane object, in Microsoft Outlook, determines which navigation module is currently displayed in the Navigation Pane. You can retrieve a reference to a given NavigationModule object from a NavigationPane object by either enumerating the NavigationModules collection or by using the GetNavigationModule method of the NavigationModules collection.

The following sample sets the Mail navigation module as the currently selected navigation module if any navigation module is selected, either programmatically or by user action, in the Navigation Pane. The sample performs the following actions:

  1. The sample first obtains a reference to the NavigationPane object for the active explorer when the Startup event of the Application object is raised and assigns it to objPane, so the ModuleSwitch event of the NavigationPane object can be detected.

  2. When the ModuleSwitch event of the NavigationPane occurs, the sample then checks the NavigationModuleType property of the NavigationModule object reference in the CurrentModule parameter of the ModuleSwitch event.

  3. If the NavigationModuleType property of the currently selected NavigationModule object is set to olModuleMail, the sample uses the GetNavigationModule method of the NavigationModules collection for the NavigationPane object to attempt to retrieve a MailModule object. If successful, the sample finally sets the CurrentModule property of the NavigationPane object to the retrieved MailModule object reference.

Copy code Copy code
Dim WithEvents objPane As NavigationPane

Private Sub Application_Startup()
 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane
End Sub

Private Sub objPane_ModuleSwitch(ByVal CurrentModule As NavigationModule)
 Dim objModule As MailModule

 If CurrentModule.NavigationModuleType <> olModuleMail Then
 ' Use the GetModule method to obtain a MailModule from
 ' the current NavigationPane object.
 Set objModule = objPane.Modules.GetNavigationModule(olModuleMail)

 ' Set the CurrentModule property to the MailModule.
 Set objPane.CurrentModule = objModule
 End If
End Sub


How to: Add a Folder to the Favorite Folders Group

 Copy code hover
[image]

How to: Add a Folder to the Favorite Folders Group
Send feedback

You can add a folder to the Favorite Folders navigation group in Microsoft Outlook by using the Add method of the NavigationFolders collection for a NavigationGroup object. The Add method accepts a Folder object reference, to which the custom navigation folder is associated.

You can retrieve a NavigationGroup object reference to the default navigation group for a specified navigation group type by using the GetDefaultNavigationGroup method of the NavigationGroups object.

This sample creates a new mail folder for important items and adds a custom navigation folder for the new folder in the Favorite Folders navigation group of the Mail module.

Note Note

If you attempt to add a solution-specific folder, that is created for the Solutions module, to the Favorite Folders list, Outlook will raise an error.

The sample performs the following actions:

  1. The sample obtains a Folder object reference for the Inbox default folder for the current user, by using the GetDefaultFolder method of the NameSpace object.

  2. It then creates a new Folder object named "Important Items", representing the new mail folder, in the Folders collection of the Inbox default folder.

  3. The sample then obtains a reference to the NavigationPane object for the active explorer and uses the GetNavigationModule method of the NavigationModules collection to obtain a MailModule object reference.

  4. It then uses the GetDefaultNavigationGroup method of the NavigationGroups collection for the MailModule to obtains a NavigationGroup object reference to the Favorite Folders navigation group.

  5. Finally, the sample adds a new NavigationFolder object, based on the Folder object created earlier by the sample, to the navigation group by using the Add method of the NavigationGroups collection for that navigation group.

Copy code Copy code
Private Sub CreateImportantFavoritesFolder()
    Dim objNamespace As NameSpace
    Dim objCalendars As Folder
    Dim objFolder As Folder

    Dim objPane As NavigationPane
    Dim objModule As MailModule
    Dim objGroup As NavigationGroup
    Dim objNavFolder As NavigationFolder

    On Error GoTo ErrRoutine

    ' First, retrieve the default Inbox folder.
    Set objNamespace = Application.GetNamespace("MAPI")
    Set objCalendars = objNamespace.GetDefaultFolder(olFolderInbox)

    ' Create a new mail folder named "Important Items".
    Set objFolder = objCalendars.Folders.Add("Important Items")

    ' Get the NavigationPane object for the
    ' currently displayed Explorer object.
    Set objPane = Application.ActiveExplorer.NavigationPane

    ' Get the mail module from the Navigation Pane.
    Set objModule = objPane.Modules.GetNavigationModule(olModuleMail)

    ' Get the "Favorite Folders" navigation group from the
    ' mail module.
    With objModule.NavigationGroups
        Set objGroup = .GetDefaultNavigationGroup(olFavoriteFoldersGroup)
    End With

    ' Add a new navigation folder for the "Important Items"
    ' folder in the "Favorite Folders" navigation group.
    Set objNavFolder = objGroup.NavigationFolders.Add(objFolder)

EndRoutine:
    On Error GoTo 0
    Set objNavFolder = Nothing
    Set objFolder = Nothing
    Set objGroup = Nothing
    Set objModule = Nothing
    Set objPane = Nothing
    Set objNamespace = Nothing
    Exit Sub

ErrRoutine:
    MsgBox Err.Number & " - " & Err.Description, _
        vbOKOnly Or vbCritical, _
        "CreateImportantFavoritesFolder"
End Sub


How to: Enumerate Active Folders in the Calendar View

 Copy code hover
[image]

How to: Enumerate Active Folders in the Calendar View
Send feedback

In Microsoft Outlook, you can traverse the group and folder hierarchy of a module in the Navigation Pane by using the NavigationGroups and NavigationFolders collections. The NavigationGroups collection of the NavigationModule object contains each navigation group displayed in a navigation module, while the NavigationFolders collection of the NavigationGroup object contains each navigation folder displayed in a navigation group.

By using these collections in combination, you can enumerate each navigation folder for a navigation module displayed in the Navigation Pane.

The following sample counts the number of navigation folders selected for display in the Calendar navigation module of the Navigation Pane. The sample performs the following actions:

  1. The sample first obtains a reference to the NavigationPane object for the active explorer.

  2. It then uses the GetNavigationModule method of the NavigationModules collection to obtain a reference to the CalendarModule object from the NavigationPane object.

  3. The sample then enumerates through the NavigationGroups collection of the CalendarModule object. For each NavigationGroup in the collection, the sample then enumerates the NavigationFolders collection.

  4. If the IsSelected property of a NavigationFolder object contained in the NavigationFolders collection is set to True, the variable intCounter is incremented.

  5. Finally, the sample displays a dialog box containing the value of intCounter.

Copy code Copy code
Dim WithEvents objPane As NavigationPane

Private Sub EnumerateActiveCalendarFolders()
 Dim objModule As CalendarModule
 Dim objGroup As NavigationGroup
 Dim objFolder As NavigationFolder
 Dim intCounter As Integer

 On Error GoTo ErrRoutine

 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Get the CalendarModule object, if one exists,
 ' for the current Navigation Pane.
 Set objModule = objPane.Modules.GetNavigationModule(olModuleCalendar)

 ' Iterate through each NavigationGroup contained
 ' by the CalendarModule.
 For Each objGroup In objModule.NavigationGroups
 ' Iterate through each NavigationFolder contained
 ' by the NavigationGroup.
 For Each objFolder In objGroup.NavigationFolders
 ' Check if the folder is selected.
 If objFolder.IsSelected Then
 intCounter = intCounter + 1
 End If
 Next
 Next

 ' Display the results.
 MsgBox "There are " & intCounter & " selected calendars in the Calendar module."

EndRoutine:
 On Error GoTo 0
 Set objFolder = Nothing
 Set objGroup = Nothing
 Set objModule = Nothing
 Set objPane = Nothing
 intCounter = 0
 Exit Sub

ErrRoutine:
 MsgBox Err.Number & " - " & Err.Description, _
 vbOKOnly Or vbCritical, _
 "EnumerateActiveCalendarFolders"
End Sub


How to: Add a Custom Folder to a Group and Display it in Overlay Mode by Default

 Copy code hover
[image]

How to: Add a Custom Folder to a Group and Display it in Overlay Mode by Default
Send feedback

You can add custom navigation folders to a navigation group in Microsoft Outlook by using the Add method of the NavigationFolders collection for a NavigationGroup object. The Add method accepts a Folder object reference, to which the custom navigation folder is associated.

If the custom navigation folder is associated with a calendar folder, you can also use the IsSideBySide property of the NavigationFolder object to determine if the contents of the custom navigation folder are displayed in side-by-side or overlay mode.

This sample creates a new calendar folder for company events and adds a custom navigation folder for the new folder, configuring the custom navigation folder so that it is displayed by default in overlay mode.

The sample performs the following actions:

  1. The sample obtains a Folder object reference for the Calendar default folder for the current user, by using the GetDefaultFolder method of the NameSpace object.

  2. It then creates a new Folder object named "Company Events", representing the new calendar folder, in the Folders collection of the Calendar default folder.

  3. The sample then obtains a reference to the NavigationPane object for the active explorer and uses the GetNavigationModule method of the NavigationModules collection to obtain a CalendarModule object reference.

  4. It then uses the GetDefaultNavigationGroup method of the NavigationGroups collection for the CalendarModule to obtains a NavigationGroup object reference to the My Calendars navigation group.

  5. It then adds a new NavigationFolder object, based on the Folder object created earlier by the sample, to the navigation group by using the Add method of the NavigationGroups collection for that navigation group.

  6. The sample then sets the CurrentModule property of the NavigationPane object to the CalendarModule object reference, to ensure that the Calendar navigation module is currently displayed in the Navigation Pane.

  7. Finally, the sample then configures the navigation folder:

    • The sample sets the IsSelected property to True to display it in the active explorer.

    • The sample then sets the IsSideBySide property to False to display it by default in overlay mode.

Copy code Copy code
Private Sub CreateCompanyEventsFolder()
 Dim objNamespace As NameSpace
 Dim objCalendar As Folder
 Dim objFolder As Folder

 Dim objPane As NavigationPane
 Dim objModule As CalendarModule
 Dim objGroup As NavigationGroup
 Dim objNavFolder As NavigationFolder

 On Error GoTo ErrRoutine

 ' First, retrieve the default calendar folder.
 Set objNamespace = Application.GetNamespace("MAPI")
 Set objCalendar = objNamespace.GetDefaultFolder(olFolderCalendar)

 ' Create a new calendar folder named "Company Events".
 Set objFolder = objCalendar.Folders.Add("Company Events", olFolderCalendar)

 ' Get the NavigationPane object for the
 ' currently displayed Explorer object.
 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Get the calendar module from the Navigation Pane.
 Set objModule = objPane.Modules.GetNavigationModule(olModuleCalendar)

 ' Get the "My Calendars" navigation group from the
 ' calendar module.
 With objModule.NavigationGroups
 Set objGroup = .GetDefaultNavigationGroup(olMyFoldersGroup)
 End With

 ' Add a new navigation folder for the "Company Events"
 ' folder in the "My Calendars" navigation group.
 Set objNavFolder = objGroup.NavigationFolders.Add(objFolder)

 ' Set the navigation folder to be displayed in overlay mode
 ' by default. The IsSelected property can't be set to True
 ' unless the CalendarModule object is the current module
 ' displayed in the Navigation Pane.
 Set objPane.CurrentModule = objModule
 objNavFolder.IsSelected = True
 objNavFolder.IsSideBySide = False

EndRoutine:
 On Error GoTo 0

 Set objNavFolder = Nothing
 Set objFolder = Nothing
 Set objGroup = Nothing
 Set objModule = Nothing
 Set objPane = Nothing
 Set objNamespace = Nothing

 Exit Sub

ErrRoutine:
 MsgBox Err.Number & " - " & Err.Description, _
 vbOKOnly Or vbCritical, _
 "CreateCompanyEventsFolder"
End Sub


Properties (Outlook)

 Copy code hover
[image]

Properties (Outlook)
Send feedback

In this section

  • Properties Overview

  • Referencing Properties by Namespace

  • Creating a Property

  • Deleting a Property

  • Getting the Value of a Property

  • Setting the Value of a Property

  • Best Practices for Getting and Setting Properties

  • How to: Identify a Meeting Item as a Counter-Proposal to a Prior Meeting Request


Properties Overview

 Copy code hover
[image]

Properties Overview
Send feedback

Outlook Properties

A property is an attribute of a Microsoft Outlook object. Properties describe something about the object, such as the sender of a message item, or the number of items in a folder. Outlook defines many properties; these are referred to as built-in properties in this documentation. The Outlook object model exposes many built-in properties with string names, such as the Subject property of a mail item. These properties are further qualified as explicit built-in properties. Customers and service providers can extend the predefined properties of Outlook by creating new, custom properties. For example, through custom forms, customers can define properties to extend the functionality for a specific message class, and service providers can define properties to expose the unique features of their messaging system.

Object Model Entry Points

The Outlook object model provides several approaches to access Outlook properties, such as:

  • Referencing a property directly from the parent object to access explicit built-in properties of item objects (for example, the MailItem.SenderEmailAddress property)

  • Using ItemProperties and ItemProperty to enumerate explicit built-in properties and custom properties and access custom properties of item objects

  • Using UserProperties and UserProperty to enumerate and access custom properties of item objects

  • Using the PropertyAccessor object to access built-in and custom properties of the following objects:

    • AddressEntry

    • AddressList

    • Attachment

    • ExchangeDistributionList

    • ExchangeUser

    • Folder

    • Outlook item objects

    • Recipient

    • Store

Note Note

Although ItemProperties and UserProperties support enumerating explicit built-in properties, and UserProperties.Find supports searching for explicit built-in properties, use these objects primarily for custom properties of item objects. Use the PropertyAccessor object to access properties of non-item objects, or item-level properties that are not explicitly exposed in the Outlook object model.

The following table shows when to use which entry points:

 | Object.Property | UserProperty, UserProperties | ItemProperty, ItemProperties | PropertyAccessor
Action on Properties | Get and set explicit built-in properties of item objects. | Enumerate, create, get, set, and remove custom properties of item objects. | Enumerate explicit built-in properties and custom properties of item objects; create, get, set, and remove custom properties of item objects. | Get and set built-in properties, and create, get, set, and remove custom properties. Objects include item objects and the following: AddressEntry, AddressList, Attachment, ExchangeUser, ExchangeDistributionList, Folder, Recipient, and Store. Access properties by the appropriate namespaces. For more information, see Referencing Properties by Namespace.
Performance | No performance overhead. | Enumerating and accessing properties using UserProperties can incur performance overhead. | Enumerating and accessing properties using ItemProperties can incur performance overhead. | Using the PropertyAccessor to access properties incurs performance overhead. For getting or setting multiple properties, use GetProperties and SetProperties as opposed to repeated calls to GetProperty and SetProperty.


Referencing Properties by Namespace

 Copy code hover
[image]

Referencing Properties by Namespace
See also Send feedback

This topic lists the namespaces that are supported by the PropertyAccessor, Table, View, and their children objects,and discusses referencing named properties.

Namespaces Used by Outlook Objects

The following table summarizes the namespaces and the Outlook objects that the namespaces support. Note that property references by namespaces are case-sensitive.

Namespaces | Supported Outlook Objects
http://schemas.microsoft.com/mapi/proptag | Outlook item objects, AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store objects.
http://schemas.microsoft.com/mapi/id | (Same as above)
http://schemas.microsoft.com/mapi/string | (Same as above)
http://schemas.microsoft.com/exchange | (Same as above)
urn:schemas-microsoft-com:office:office | Outlook item objects
urn:schemas-microsoft-com:office:outlook | Outlook item objects
DAV: | Outlook item objects
urn:schemas:calendar | Outlook item objects
urn:schemas:contacts | Outlook item objects
urn:schemas:httpmail | Outlook item objects
urn:schemas:mailheader | Outlook item objects

Messaging Application Programming Interface (MAPI) Namespaces

Many properties that Outlook supports are MAPI properties. The PropertyAccessor object supports three subnamespaces of the MAPI namespace: proptag, id, and string. Each of the following sections contains a description for the subnamespace, a description for the format to reference a property in that subnamespace, and a definition of the syntax as expressed in Augmented Backus-Naur Form (ABNF), that is specified in [RFC4234].

  • proptag namespace

    This namespace is used to access properties in the MAPI namespace using the property tag of a property. It supports only properties in the MAPI property range (that is, properties with a property identifier below 0x8000). The following is the format to reference a property in this namespace:

    http://schemas.microsoft.com/mapi/proptag/0xHHHHHHHH

    HHHHHHHH represents a hexadecimal property tag value, with a unique property identifier in the higher-order 16 bits, and a property type in the lower-order 16 bits. Every MAPI property must have a property tag, regardless of whether the property is defined by MAPI, Outlook, or a service provider. The hexadecimal value must follow the prefix "0x". Formally, references of properties in this namespace can be defined in ABNF as follows:

    Copy code Copy code
    proptag-specifier = "http://schemas.microsoft.com/mapi/proptag/x" property-id property-type
property-id = 4HEXDIG
property-type = 4HEXDIG

    For example, the following represents the MAPI property PidTagSubject that Outlook exposes in its object model as Subject:

    http://schemas.microsoft.com/mapi/proptag/0x0037001E

  • id namespace

    This namespace is used to access properties in a namespace identified by the globally unique identifier (GUID) of the namespace, using the identifier of the property. The following is the format to reference a property in this namespace:

    http://schemas.microsoft.com/mapi/id/{HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH}/HHHHHHHH

    {HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH} represents the namespace GUID, and HHHHHHHH represents the property tag.

    Formally, references of properties in this namespace can be defined in ABNF as follows:

    Copy code Copy code
    id-specifier = "http://schemas.microsoft.com/mapi/id/" property-set "/x" property-long-id
property-set = "{" 8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 12HEXDIG "}"
property-long-id = 8HEXDIG

    For example, the following represents the Outlook NoAging property:

    http://schemas.microsoft.com/mapi/id/{00062008-0000-0000-C000-000000000046}/850E000B

  • string namespace

    This namespace is used to access string-named properties in an identified namespace. The following is the format to reference a property in this namespace:

    http://schemas.microsoft.com/mapi/string/{HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH}/name

    {HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH} represents the namespace GUID, and name is the local property name defined as a string.

    Formally, references of properties in this namespace can be defined in ABNF as follows:

    Copy code Copy code
    string-specifier = "http://schemas.microsoft.com/mapi/string/" property-set "/" property-name
property-set = "{" 8*HEXDIG "-" 4*HEXDIG "-" 4*HEXDIG "-" 4*HEXDIG "-" 12*HEXDIG "}"
property-name = 1*CHAR

    The following is an example that uses this namespace:

    http://schemas.microsoft.com/mapi/string/{00020386-0000-0000-C000-000000000046}/content-class

    Escaping rules apply to referencing named properties in the string namespace. When referencing a named property that has a string identifier (for example, Author, Company, and Title), if the property name contains a space, single quote, double quote, or percent character, you must use Universal Resource Locator (URL) escaping and represent such characters with the corresponding escape string as shown in the following table.

    Character in Property Reference

    Escape String

    Space character

    %20

    Double quote

    %22

    Single quote

    %27

    Percent character

    %25

    The following is an example of how you specify and get the value of a named property, Mom's "Gift", defined in the MAPI string namespace, by using the PropertyAccessor.GetProperty method:

    Copy code Copy code
    PropertyAccessor.GetProperty("http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000-000000000046}/Mom%27s%20%22Gift%22")

Exchange Namespace

The exchange namespace is used to access string-named Exchange properties. The following is the format to reference a property in this namespace:

http://schemas.microsoft.com/exchange/name

name is the local property name defined as a string.

The following is an example of a property referenced by this namespace:

http://schemas.microsoft.com/exchange/readreceiptrequested

Office Namespaces

The PropertyAccessor object supports two Office subnamespaces:

  • Office namespace

    This namespace is used to access properties of the DocumentItem object. The following is the format to reference a property in this namespace:

    urn:schemas-microsoft-com:office:office#name

    name is the local property name defined as a string.

    The following are some examples of referencing DocumentItem properties using the Office namespace:

    • urn:schemas-microsoft-com:office:office#Subject

    • urn:schemas-microsoft-com:office:office#Template

  • Outlook namespace

    This namespace is used to access Outlook item-level properties. Similar to other namespaces that support property referencing, use this namespace to access Outlook properties that are not explicitly exposed in the object model. The following is the format to reference a property in this namespace:

    urn:schemas-microsoft-com:office:outlook#name

    name is the local property name defined as a string.

    The following is an example of referencing an Outlook item-level property by using the Outlook namespace:

    urn:schemas-microsoft-com:office:outlook#remotemessagesize

Distributed Authoring and Versioning (DAV) Namespaces

DAV namespaces are used to access Outlook item-level properties. A property in a DAV namespace is scoped using a Uniform Resource Identifier (URI) namespace reference. The format is a concatenation of the namespace URI prefix and the local property name expressed in a string, with the namespace URI being either a Uniform Resource Name (URN) or Uniform Resource Locator (URL).

The following are the DAV namespaces that the PropertyAccessor object supports:

  • DAV:

  • urn:schemas:calendar

  • urn:schemas:contacts

  • urn:schemas:httpmail

  • urn:schemas:mailheader

These are some examples of properties being referenced by different DAV namespaces:

  • DAV:checkintime

  • urn:schemas:httpmail:subject

  • urn:schemas:mailheader:subject

See also

Concepts

MAPI Property Tags
MAPI Property Identifier Overview
MAPI Property Type Overview
Property Identifier Ranges
Property Types
MAPI Named Properties


Creating a Property

 Copy code hover
[image]

Creating a Property
Send feedback

Outlook provides several ways to add custom properties:

 | UserProperties.Add | ItemProperties.Add | PropertyAccessor.SetProperty | PropertyAccessor.SetProperties
Action | Adds a custom property specified by Name and Type. If a property of the same name and type already exists, it will be overwritten by a new property. The default value for AddToFolderFields allows adding the property to the item and as a view field to the folder. | Adds a custom property specified by Name and Type even if a property of the same name and type already exists. The default value for AddToFolderFields allows adding the property to the item and as a view field to the folder. | Adds a custom property specified by SchemaName if the provider and the parent object supports property creation, the property does not already exist, and a valid schema name is specified for the property. | For each property in SchemaNames, PropertyAccessor.SetProperties adds it as a custom property if the provider and the parent object supports property creation, the property does not already exist, and a valid schema name is specified for the property.
Applicable Objects | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects including DocumentItem objects. | All Outlook item objects including DocumentItem objects.
Property Initial Value | Empty in VBA; requires subsequent assignment | Empty in VBA; requires subsequent assignment | Specified by Value. | Specified by the value of the corresponding element in the Values array
Property Type | Specified by Type | Specified by Type | If the property is specified by the MAPI proptag or id namespace, the property type is contained in the lowest 16 bits of the identifier; otherwise the property type is determined by the type of Value. | Type of each property is determined by the same principles as in the SetProperty column; where the property is not specified by any namespace involving its proptag, its property type is the type of the corresponding element in the Values array.
Upon Property Change | The CustomPropertyChange event will fire on property change. | The CustomPropertyChange event will fire on property change. | An item-level property added this way does not become part of the item's UserProperties collection. It will not generate Outlook Object Model events when it is changed. | Same event considerations as in the SetProperty column.


Deleting a Property

 Copy code hover
[image]

Deleting a Property
Send feedback

Outlook provides several ways to remove a custom property:

 | UserProperties.Remove | ItemProperties.Remove | PropertyAccessor.DeleteProperty | PropertyAccessor.DeleteProperties
Action | Removes a custom property specified by Index in the UserProperties collection for the item. The UserProperties collection is one-based. | Removes a custom property specified by Index in the ItemProperties collection for the item. The ItemProperties collection is zero-based. You can only remove custom properties in the collection and they are denoted by IsUserProperty. You cannot remove explicit built-in properties. | Removes a custom property specified by SchemaName, provided that the property is not read-only and the caller has permission to delete the property (for example, the caller is the owner of the folder to which the property has been added). You cannot remove a built-in Outlook or MAPI property. | For each custom property in SchemaNames, removes it provided that the same conditions described in the PropertyAccessor.DeleteProperty column are true. Any error will be returned in the corresponding element in the resultant error array.
Applicable Objects | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects but excluding the DocumentItem object, and any of the following objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store objects. | Same objects as listed in the DeleteProperty column.


Getting the Value of a Property

 Copy code hover
[image]

Getting the Value of a Property
Send feedback

Outlook provides several ways to get the value of a property:

 | Object.Property | UserProperty.Value | ItemProperty.Value | PropertyAccessor.GetProperty | PropertyAccessor.GetProperties
Action | Gets the value of the specified explicit built-in property. | Gets the value of the specified custom item-level property. No action takes place if the property does not exist. | Gets the value of the specified built-in or custom item-level property, provided the property is not a blocked property. No action takes place if the property does not exist. | Gets an object that represents the value of the property specified by SchemaName, provided the property is not a blocked property. Returns an error if the property does not exist. | For each property in SchemaNames, provided the property is not a blocked property, gets the value of the property into a corresponding element in a variant array. Returns the variant array with property values when PropertyAccessor.GetProperties obtains the value of all the properties in SchemaNames. Returns errors in the array otherwise.
Applicable Objects | All objects in the Outlook object model. | All Outlook item objects including Microsoft Office document items (DocumentItem objects) | All Outlook item objects including Microsoft Office document items (DocumentItem objects) | Use ItemProperty to get explicit built-in item-level properties. Use PropertyAccessor.GetProperty for item-level properties without explicit names, custom properties, or properties of any of the following objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store. | Same objects as stated in the GetProperty column.
Property Type Support | As specified in the Outlook object model. | Returns a Variant object. | Returns a Variant object. | The type of the object returned will be the same as the type of the property specified by SchemaName. If you require conversion of the raw property type to a string (for PT_BINARY in MAPI) or a local time (PT_SYSTIME), use the PropertyAccessor helper methods PropertyAccessor.UTCToLocalTime or PropertyAccessor.BinaryToString. The PropertyAccessor does not support certain MAPI property types, for example, PT_OBJECT, and attempting to get the value of properties of such types will return "Property operation not supported" error. | Property type support is the same as in the GetProperty column because the type of each value should be the same as the type of the corresponding property in SchemaNames. Any error including type mismatch is returned in the resultant array.
Security | On a client computer running Microsoft Office Outlook 2007 or later, without an appropriately set up antivirus software, untrusted code attempting to access protected properties will, by default, get the address book security warning. | Trusted and untrusted code can use the UserProperty object. On a client computer running Office Outlook 2007 or later without an appropriately set up antivirus software, untrusted code attempting to use the UserProperty object to access a protected property will, by default, get the address book security warning. | Trusted and untrusted code can use the ItemProperty object. On a client computer running Office Outlook 2007 or later without an appropriately set up antivirus software, untrusted code attempting to use the ItemProperty object to access a protected property will, by default, get the address book security warning. | On a client computer without an appropriately set up antivirus software, untrusted code attempting to access the PropertyAccessor property of an item object will by default invoke the address book security warning. | Same security considerations as in the GetProperty column.
Performance | No performance overhead. Use this whenever the property is an explicit built-in property. | No performance overhead. Use this object whenever the property is a custom property at the item-level. | No performance overhead. Use this object whenever the property is a custom item-level property. | Using the PropertyAccessor to access properties incurs performance overhead. For getting multiple properties, use PropertyAccessor.GetProperties as opposed to repeated PropertyAccessor.GetProperty. | Using the PropertyAccessor to access properties incurs performance overhead. For getting multiple properties, use GetProperties as opposed to repeated GetProperty.


Setting the Value of a Property

 Copy code hover
[image]

Setting the Value of a Property
Send feedback

Outlook provides several ways to set the value of a property:

 | Object.Property | UserProperty.Value | ItemProperty.Value | PropertyAccessor.SetProperty | PropertyAccessor.SetProperties
Action | Sets the value of the specified explicit built-in property. | Sets the custom item-level property with a given value. If the property doesn't exist, setting it will return an "Object variable or with block variable not set" error. | Sets the built-in or custom item-level property with a given value, provided the property is not a read-only or blocked property. Returns a runtime error if the property does not exist. | Sets the property specified by SchemaName with the given value, provided the property is not a read-only or blocked property. If the property does not exist, and if the provider and the parent object supports property creation, and a valid schema name is specified for the property, SetProperty creates the property. | For each property in SchemaNames, provided the property is not a read-only or blocked property, sets the property with the corresponding value in the Values array. If the property does not already exist, property creation as stated in the SetProperty column may take place. If the two arrays SchemaNames and Values do not match in size, then SetProperties will return an invalid argument error.
Applicable Objects | All objects in the Outlook object model. | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | All Outlook item objects except Microsoft Office document items (DocumentItem objects) | Use ItemProperty to set explicit built-in item-level properties. Use SetProperty for DocumentItem properties, item-level properties without explicit names, custom prroperties, or properties of any of the following objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store. | Same objects as stated in the SetProperty column.
Property Type Matching | As specified in the Outlook object model. | Returns a runtime error if the value does not match the property type. | Returns a runtime error if the value does not match the property type. | If SchemaName uses the MAPI proptag namespace, and Value does not match the property type indicated by the property tag, SetProperty will return a type mismatch runtime error. If SchemaName uses the MAPI string namespace, SetProperty will attept to coerce the type to match the property type. If the type coercion fails, then SetProperty will return a type mismatch runtime error. The PropertyAccessor does not support certain MAPI property types, for example, PT_OBJECT, and attempting to set the value of properties of such types will return "Property operation not supported" error. | Property type matching is similar to SetProperty as each property in SchemaNames is matched with the type of the value in the Values array. Any error including type mismatch error is returned in the Errors array.
Property Change Events | The PropertyChange event fires when a built-in item-level property changes. | The CustomPropertyChange event fires when the value of a custom item-level property changes. | The PropertyChange event fires when a built-in item-level property changes. The CustomPropertyChange event fires when the value of a custom item-level property changes, provided that the custom property is in the UserProperties collection for the item. Note that an item-level property added implicitly by PropertyAccessor.SetProperty or PropertyAccessor.SetProperties does not automatically become part of the item's UserProperties collection. | Changing non-item-level properties does not fire any event. Changing item-level properties fires the same events as stated in the ItemProperty.Value column. Note that an item-level property added implicitly by SetProperty or SetProperties does not automatically become part of the item's UserProperties collection. An explicit UserProperties.Add is required to include the property so that the CustomPropertyChange event will fire on property change. | For each property in the SchemaNames array, changing its value may fire an event depending on circumstances as described in the SetProperty column.
Security | No security restrictions. | Trusted and untrusted code can use UserProperty. | Trusted and untrusted code can use ItemProperty. | On a client computer without an appropriately set up antivirus software, untrusted code attempting to access the PropertyAccessor property of an item object will by default invoke the address book security warning. | Same security considerations as in the SetProperty column.
Performance | No performance overhead. Use this whenever the property is an explicit built-in property. | No performance overhead. Use this object whenever the property is a custom property at the item-level. | No performance overhead. Use this object whenever the property is a named item-level property. | Using the PropertyAccessor to access properties incurs performance overhead. For setting multiple properties, use SetProperties as opposed to repeated SetProperty. | Using the PropertyAccessor to access properties incurs performance overhead. For setting multiple properties, use SetProperties as opposed to repeated SetProperty.

Remarks

Since the Value property is the default property for the ItemProperty and UserProperty objects, you do not necessarily have to explicitly specify the Value property when referring to the value of a property.

Similarly, the Find method is the default method for ItemProperties and UserProperties. You do not necessarily have to specify the Find method when referencing the value of a property.


Best Practices for Getting and Setting Properties

 Copy code hover
[image]

Best Practices for Getting and Setting Properties
Send feedback

Keep in mind the following best practices recommendations for getting and setting values for properties:

  • Reference a property directly off the parent object to get and set explicit built-in properties of item objects, for example, MailItem.Subject.

  • Use ItemProperties and ItemProperty to enumerate explicit built-in properties and custom properties, and get and set custom properties for items (except for DocumentItem object).

  • Use UserProperties and UserProperty to enumerate, get and set custom properties for items (except for the DocumentItem object).

  • Use PropertyAccessor to get and set custom properties for the DocumentItem object, built-in item-level properties that are not exposed in the Outlook object model, or properties for the following objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store.

  • To get or set multiple custom properties, use the PropertyAccessor object instead of the UserProperties object for better performance.

  • To create or access custom properties, use the MAPI string namespace for convenience over the MAPI proptag or id namespace. Use the GUID of your add-in as the namespace GUID.

  • When referencing properties by namespaces, be aware that such references are case-sensitive. For example, while urn:schemas:contacts:givenName is a valid namespace, urn:schemas:contacts:givenname is not.

  • To get or set multiple properties, use PropertyAccessor.GetProperties and PropertyAccessor.SetProperties, as opposed to repeated PropertyAccessor.GetProperty and PropertyAccessor.SetProperty, for better performance.

  • To have the CustomPropertyChange event fire when the value of an item-level custom property changes, the custom property must be in the item's UserProperties collection. An item-level property added implicitly by SetProperty or SetProperties does not automatically become part of the item's UserProperties collection. An explicit UserProperties.Add is required to include it.

  • To set for the first time a property created by the UserProperties.Add method, use the UserProperty.Value property instead of the SetProperties and SetProperty methods of the PropertyAccessor object.

This section describes the best practices for saving properties on an object:

  • For item objects, calling the item's Save method to save the item to the current folder also saves its properties on the item.

  • For non-item-level objects that do not have a Save method (AddressList, Folder, Recipient, and Store), calling PropertyAccessor.DeleteProperty, PropertyAccessor.DeleteProperties, SetProperty, or SetProperties will implicitly save the properties on the object.

This section describes the best practices for keeping type conversion simple when using the PropertyAccessor to get and set properties. For definitions of MAPI property types such as PT_SYSTIME, see Property Types.

  • Although most Outlook date-time values are stored in Coordinated Universal Time (UTC) format, there is no guarantee that all properties of the MAPI type PT_SYSTIME will always return UTC. Getting a PT_SYSTIME property will return a VT_DATE value. When setting a PT_SYSTIME property, ensure that you are setting the property as a UTC value rather than a local date-time value. The GetProperty, SetProperty, GetProperties, and SetProperties methods do not perform time zone conversion. Use the helper methods PropertyAccessor.LocalTimeToUTC and PropertyAccessor.UTCToLocalTime to perform explicit time zone conversion.

  • A multi-valued property (Microsoft Visual Basic type VT_ARRAY) is stored as a two-dimensional array that contains the same number of elements as are there are values in the property. Getting a multi-valued property will return a VT_ARRAY value. When setting a multi-valued property, pass a two-dimensional array (VT_ARRAY) with one element for each value that you want to set for the property.

  • A binary property (MAPI type PT_BINARY) is stored as an array of bytes rather than a string. Getting a binary property will return a value of type VT_ARRAY. The GetProperty, SetProperty, GetProperties, and SetProperties methods do not perform any conversion between binary array and string. Use the helper methods PropertyAccessor.BinaryToString and PropertyAccessor.StringToBinary to explicitly perform any conversion.

  • Certain MAPI property types, such as PT_OBJECT, are not supported by the PropertyAccessor. Attempting to get or set such properties will result in a "property operation not supported" error.

  • When getting or setting a property using a reference in the MAPI proptag namespace, make sure that the type specified in the proptag matches the underlying type of the property. Except for the case of a PT_STRING8 property where you can specify either a type of 001E or 001F in the proptag to get or set the property as a VT_BSTR, getting or setting a property does not involve any type coercion and an error will be returned if there is a type mismatch.

  • When setting a property, it may be less restrictive to use a property reference in the MAPI string namespace than one in the MAPI proptag namespace. Specifying the property in the MAPI string namespace does not strictly require the value to match the underlying type of the property. For example, you can pass a string value like VT_BSTR to set a date-time property such as PT_SYSTIME, and the type of the property becomes the type of the value, which is VT_BSTR.


How to: Identify a Meeting Item as a Counter-Proposal to a Prior Meeting Request

 Copy code hover
[image]

How to: Identify a Meeting Item as a Counter-Proposal to a Prior Meeting Request
Send feedback

This topic shows how to use the named property, PidLidAppointmentCounterProposal, and the Microsoft Outlook object model to identify a MeetingItem object as a counter proposal to a prior meeting request.

In the Outlook object model, all types of items, such as a mail item and a contact item, correspond to specific message classes. In particular, responses to a meeting request can be identified by the following message classes:

  • IPM.Schedule.Meeting.Resp.Neg for a decline response

  • IPM.Schedule.Meeting.Resp.Pos for an acceptance response

  • IPM.Schedule.Meeting.Resp.Ten for a tentative response

However, the Outlook object model does not provide a means to identify a response as the fourth possible response to a meeting request, which is a counter-proposal.

Using the PropertyAccessor object and the PSETID_Appointment namespace definition of PidLidAppointmentCounterProposal, you can program within the object model to distinguish all responses of a meeting request item. The following code sample in C# shows how to get the property value given a meeting item. Note that in the code sample, the named property is expressed as:

Copy code Copy code
"http://schemas.microsoft.com/mapi/id/00062002-0000-0000-C000-000000000046}/8257000B"

where {00062002-0000-0000-C000-000000000046} is the PSETID_Appointment namespace and 8257000B is the property tag of PidLidAppointmentCounterProposal.

C# Copy code Copy code
private bool IsCounterProposal(Outlook.MeetingItem meeting)
{
    const string counterPropose =
        "http://schemas.microsoft.com/mapi/id/{00062002-0000-0000-C000-000000000046}/8257000B";
    Outlook.PropertyAccessor pa = meeting.PropertyAccessor;
    if ((bool)pa.GetProperty(counterPropose))
        return true;
    else
        return false;
}


Office Fluent UI Extensibility

 Copy code hover
[image]

Office Fluent UI Extensibility
Send feedback

In this section

  • Office Fluent User Interface Extensibility for Outlook

  • Overview of Customizing the Ribbon

  • Updating Earlier Code for CommandBars

  • Implementing the IRibbonExtensibility Interface

  • Detecting Errors

  • Overview of the IRibbonUI Object

  • Overview of the IRibbonControl Object


Office Fluent User Interface Extensibility for Outlook

 Copy code hover
[image]

Office Fluent User Interface Extensibility for Outlook
See also Send feedback

Microsoft Office Fluent user interface (UI) extensibility refers to the mechanism that supports the programmatic customization of the Office Fluent UI in Microsoft Office applications. Microsoft Outlook expands user interface extensibility beyond the ribbons in the explorer and inspector windows to include other components of the Outlook UI, such as the following:

  • Microsoft Office Backstage view

  • Contextual tabs

  • New items menus

  • Shortcut menus

Add-ins implement the IRibbonExtensibility interface to extend the Outlook UI. To customize a part of the UI, specify your customizations in an XML markup file that complies with the schema definition for Office Fluent UI extensibility. Office calls the IRibbonExtensibility.GetCustomUI method, specifying a ribbon ID to load the XML that describes your customizations for the part of the Outlook UI that matches the ribbon ID. As a result of the XML markup, your add-in runs callback procedures that execute the custom actions that are associated with commands in the custom UI.

Unlike other Office applications such as Microsoft Word or Microsoft Excel, you cannot customize the ribbon by using Visual Basic for Applications in Outlook. To programmatically customize the UI in Outlook, you must write an add-in. You can update an existing add-in or write an add-in that only targets Outlook. The add-in can be native or managed. Outlook does not support the customization of the ribbon by using Microsoft Office Open XML Format Files.

For more information and examples of different ways to customize the Outlook UI, see Extending the User Interface in Outlook 2010 on the MSDN Web site.

See also

Concepts

Customizing Shortcut Menus
Updating Earlier Code for CommandBars
Implementing the IRibbonExtensibility Interface
Overview of Customizing the Ribbon


Overview of Customizing the Ribbon

 Copy code hover
[image]

Overview of Customizing the Ribbon
See also Send feedback

Similar to other Microsoft Office applications such as Microsoft Word, Microsoft Excel, and Microsoft PowerPoint, Microsoft Outlook uses the Microsoft Office Fluent user interface ribbon in its explorer and inspector windows. In an item inspector, such as an e-mail message in compose mode, Outlook uses the ribbon to expose commands in item-specific elements that make it easy for users to identify the commands they need to complete their tasks.

To customize the ribbon programmatically, Outlook uses ribbon extensibility. Each Outlook add-in can specify a custom user interface in an XML markup file, and then implement the IRibbonExtensibility interface. Office calls the IRibbonExtensibility.GetCustomUI method before the ThisAddin.Startup method to load ribbon customizations for the explorer ribbon, and calls the GetCustomUI method the first time that it displays a particular type of inspector. When it is called, the GetCustomID method takes a ribbon ID as an argument and loads the corresponding XML that your add-in associates with that ribbon ID. Consider using a Switch statement when you implement the GetCustomID method to load the ribbon XML for various ribbons; it is probably the most efficient way to accommodate the variety of ribbons that you might customize.

For a complete listing of ribbon identifiers, see Implementing the IRibbonExtensibility Interface.

For a detailed discussion of the ribbon and ribbon extensibility, see Overview of the Office Fluent Ribbon.

See also

Concepts

Detecting Errors
Updating Earlier Code for CommandBars
Overview of the IRibbonUI Object
Overview of the IRibbonControl Object
Office Fluent User Interface Extensibility for Outlook


Updating Earlier Code for CommandBars

 Copy code hover
[image]

Updating Earlier Code for CommandBars
See also Send feedback

In versions prior to Microsoft Outlook 2010, Outlook implemented the following items in the user interface as command bars:

  • Menu bars, toolbars, and shortcut menus.

  • Menus on menu bars and toolbars.

  • Submenus on menus, submenus, and shortcut menus.

Command bars have been deprecated since Outlook 2010. Explorer and inspector windows no longer use menu bars and toolbars. Instead, they use the Microsoft Office Fluent ribbon. Programmatically, although your add-in or VBScript code that customized command bars in an explorer or inspector might still work in Outlook, those who use your solution might not easily find the customizations that appear on the Add-ins tab of the customized ribbon in the explorer or inspector.

Instead of using the CommandBars property of the Explorer and Inspector objects, use ribbon extensibility to customize the ribbon and to customize any menus and submenus off the ribbon. Ribbon extensibility requires an add-in that implements the IRibbonExtensibility interface. For more information about customizing the ribbon in Outlook, see Overview of Customizing the Ribbon.

Consistent with the deprecation of command bars in the explorer and inspector windows, do not rely on the CommandBar object for your custom menus; instead, use an add-in through the IRibbonExtensibility interface to extend them. For more information, see Customizing Shortcut Menus.

See also

Concepts

Office Fluent User Interface Extensibility for Outlook


Implementing the IRibbonExtensibility Interface

 Copy code hover
[image]

Implementing the IRibbonExtensibility Interface
See also Send feedback

A Microsoft Outlook add-in that customizes the ribbon, shortcut menus, new-item menus, or Microsoft Office Backstage view must implement the following interfaces:

  • IDTExtensibility2

  • IRibbonExtensibility

In Visual C# and Visual Basic add-ins, you must implement these interfaces in the same class.

When you implement Office.IRibbonExtensibility, use the IRibbonExtensibility.GetCustomUI method to return XML markup for your custom user interface to Outlook. The way that Outlook calls GetCustomUI and when it calls it is unique among Microsoft Office applications:

  • Office calls GetCustomUI during Outlook startup to load ribbon customizations for the explorers.

  • Office calls GetCustomUI to load inspector-specific ribbon customizations when the first instance of a given inspector type, such as an appointment or contact inspector, is displayed.

  • Viewing an item in the Reading Pane does not cause GetCustomUI to be called because the ribbon is not displayed in the Reading Pane.

The ribbon ID is a string that is passed from Office to GetCustomUI and that specifies the UI customization to load. Add-in developers can use this string to determine the custom XML markup to return to Outlook. You can also use the ribbon ID to determine the type of Outlook item to display.

In some cases, such as a MailItem or PostItem, Outlook calls GetCustomUI once when the first compose note is displayed (where RibbonID = Microsoft.Outlook.Mail.Compose) and another time when the first read note is displayed (where RibbonID = Microsoft.Outlook.Mail.Read).

Outlook uses the following unique ribbon IDs.

Ribbon ID | Message Class
Microsoft.OMS.MMS.Compose | IPM.Note.Mobile.MMS.*
Microsoft.OMS.MMS.Read | IPM.Note.Mobile.MMS.*
Microsoft.OMS.SMS.Compose | IPM.Note.Mobile.MMS.*
Microsoft.OMS.SMS.Read | IPM.Note.Mobile.MMS.*
Microsoft.Outlook.Appointment | IPM.Appointment.*
Microsoft.Outlook.Contact | IPM.Contact.*
Microsoft.Outlook.DistributionList | IPM.DistList.*
Microsoft.Outlook.Journal | IPM.Activity.*
Microsoft.Outlook.Mail.Compose | IPM.Note.*
Microsoft.Outlook.Mail.Read | IPM.Note.*
Microsoft.Outlook.MeetingRequest.Read | IPM.Schedule.Meeting.Request or IPM.Schedule.Meeting.Canceled
Microsoft.Outlook.MeetingRequest.Send | IPM.Schedule.Meeting.Request
Microsoft.Outlook.Post.Compose | IPM.Post.*
Microsoft.Outlook.Post.Read | IPM.Post.*
Microsoft.Outlook.Report | IPM.Report.*
Microsoft.Outlook.Resend | IPM.Resend.*
Microsoft.Outlook.Response.Compose | IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.Response.CounterPropose | IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.Response.Read | IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.RSS | IPM.Post.Rss
Microsoft.Outlook.Sharing.Compose | IPM.Sharing.*
Microsoft.Outlook.Sharing.Read | IPM.Sharing.*
Microsoft.Outlook.Task | IPM.Task.* and IPM.TaskRequest.*
Microsoft.Outlook.Explorer | Not applicable. This ribbon ID lets you return XML for explorer ribbons, shortcut menus, and Backstage view.
Note Note

Sticky notes do not implement the ribbon, so IPM.StickyNote is not listed in the table of ribbon IDs and message classes.

For all of the ribbon ID values except for Microsoft.Outlook.Explorer, notice that the corresponding message class is listed as IPM.Type.* in the table. That means that either the first instance of the base message class (for example, IPM.Contact) or of a derived custom message class (IPM.Contact.ShoeStore) that appears in an inspector will cause Outlook to call GetCustomUI.

Because a base message class shares the same ribbon XML with the custom message classes that are derived from it, and because Outlook calls GetCustomUI only one time per ribbon ID, you cannot specify a ribbon XML markup that is applied exclusively to a derived custom message class, and not to the base message class. However, if you want controls to appear in the ribbon on inspectors for one custom message class and not all other message classes with the same base message class, do the following:

  1. In GetCustomUI, return the XML markup for the ribbon ID for the custom message class (for example, IPM.Contact.ShoeStore) to the ribbon. All ribbons that are used by items with the same base message class (for example, IPM.Contact) will contain the added controls.

  2. In the ribbon XML, specify IRibbonControl.Context callbacks for each tab, group, and control that is specific to the custom message class. These callbacks will be used to display the controls for the custom message class and to hide the controls for the base message class and all other message classes with the same base message class.

  3. In each getVisible callback, cast the IRibbonControl.Context parameter that is passed to the callback to an Outlook Inspector object. Use the MessageClass property of Inspector.CurrentItem to determine whether to return True or False in the getVisible callback.

To customize the ribbon on all or multiple Outlook message classes, use the following recommendations:

  • To customize the first built-in tab on all Outlook inspectors, you must supply separate ribbon XML for different ribbon IDs because built-in first tabs do not have the same name across all ribbon IDs.

  • To customize the ribbon on multiple Outlook inspectors, you might have to supply separate ribbon XML for different ribbon IDs depending upon the tab name.

For more information, including examples, about customizing explorer and inspector ribbons, shortcut menus, and Backstage view, see Extending the User Interface in Outlook 2010 on the MSDN Web site.

See also

Concepts

Office Fluent User Interface Extensibility for Outlook
Overview of the IRibbonUI Object
Detecting Errors
Overview of the IRibbonControl Object


Detecting Errors

 Copy code hover
[image]

Detecting Errors
See also Send feedback

The custom user interface XML markup that you return in the IRibbonExtensibility.GetCustomUI call typically contains callbacks that run when the corresponding Microsoft Office Fluent user interface (UI) that you are customizing (for example, explorer, inspector, or menu) is about to be displayed. You must add each callback in your XML markup to the add-in class that implements IRibbonExtensibility. In addition, you must declare the callbacks as public procedures. If for some reason you omit a callback or use an incorrect callback signature, your UI customization will fail silently unless you turn on error reporting when you debug your solution.

Note that if any portion of the XML markup specified by an add-in and returned by GetCustomUI does not adhere to the Office Fluent UI XML schema, none of the UI customization specified by that add-in is applied. For example, if you have a problem with one control that you have added to the ribbon, your customizations for that ribbon are not displayed.

To view any errors that your XML markup generates when it is loaded, follow these steps:

  1. Click the File tab, and then click Options.

  2. Click Advanced.

  3. Under Developers, select Show add-in user interface errors.

  4. Click OK to save your changes.

See also

Concepts

Office Fluent User Interface Extensibility for Outlook
Implementing the IRibbonExtensibility Interface


Overview of the IRibbonUI Object

 Copy code hover
[image]

Overview of the IRibbonUI Object
See also Send feedback

An add-in can use the IRibbonUI object to invalidate controls or menu items, and to update their content in the corresponding Microsoft Outlook user interface. The add-in specifies callback methods in the XML that IRibbonExtensibility.GetCustomUI returns. These callback methods handle events for custom controls or custom menu items. When Outlook calls one of these methods, it passes an IRibbonUI object as a parameter to the callback method. The IRibbonUI object is scoped so that the add-in can only invalidate its own controls or menu items that use the object. The add-in cannot invalidate the controls or menu items that another add-in created.

IRibbonUI exposes the following methods to customize the user interface in Outlook:

Method | Action | Description
Invalidate() | Callback | Marks all of the custom controls or menu items in your add-in for update.
InvalidateControl(string controlID) | Callback | Marks a specific control or menu item that is defined by a controlID in your add-in for update.
ActivateTab | Callback | Activates the specified custom tab on the Microsoft Office Fluent ribbon.
ActivateTabQ | Callback | Activates the specified custom tab on the ribbon by using the fully qualified name of the tab.

To minimize the impact on performance, use the InvalidateControl method instead of the Invalidate method unless you actually need to invalidate all the custom controls or menu items that your add-in defines. Calling Invalidate invalidates all controls and menu items that your add-in defines, and callbacks occur on open explorers, inspectors, and menus.

See also

Concepts

Implementing the IRibbonExtensibility Interface
Office Fluent User Interface Extensibility for Outlook


Overview of the IRibbonControl Object

 Copy code hover
[image]

Overview of the IRibbonControl Object
See also Send feedback

The IRibbonControl object is passed in most of the callbacks that are available for controls in the ribbon or Microsoft Office Backstage view, as well as the customizable menu items in Microsoft Outlook. The object is especially useful for Outlook developers because it provides an IRibbonControl.Context property that returns the related Outlook object to which the customization is applied and is about to be displayed. For example, the Context property returns the Explorer object if you customize the ribbon in an explorer, and returns the Store object if you customize the shortcut menu for a store folder.

IRibbonControl exposes the following properties.

Property | Type | Description
Context | Object | Returns an object that represents the window in which the custom ribbon is about to be displayed, or the related object to which the menu customization is applied and is about to be displayed. Read-only.
Id | String | Returns a string that represents the Id attribute for the control or custom menu item. Read-only.
Tag | String | Returns a string that represents the Tag attribute for the control or custom menu item. Read-only.

When you write managed code, try to cast the object represented by IRibbonControl.Context to the corresponding Outlook object. For example, if you customize a ribbon in an inspector, cast the Inspector object. Then, if the cast succeeds, you can compare the Inspector object that is returned by IRibbonControl.Context to other inspector windows that are open. To determine the underlying item that is displayed in an inspector window, examine Inspector.CurrentItem. Because CurrentItem is an Object type, your code must cast the object to an appropriate item type such as MailItem or ContactItem.

See also

Concepts

Office Fluent User Interface Extensibility for Outlook
Implementing the IRibbonExtensibility Interface


Rules (Outlook)

 Copy code hover
[image]

Rules (Outlook)
Send feedback

In this section

  • Managing Rules in the Outlook Object Model

  • Specifying Rule Actions

  • Specifying Rule Conditions

  • How to: Create a Rule to Move Specific E-mails to a Folder


Managing Rules in the Outlook Object Model

 Copy code hover
[image]

Managing Rules in the Outlook Object Model
Send feedback

The Rules object model supports the programmatic adding, editing, and deleting of rules. The Rule and Rules collection objects allow you to access, add, and delete rules defined for a session. The RuleAction and RuleCondition objects, their collection objects, and derived action and condition objects further support editing actions and conditions.

Note Note

The Rules object model provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. Although it does not support every single rule that you can possibly create using the Wizard, it supports the most commonly used rule actions and conditions. Just like any rule created by using the Rules and Alerts Wizard, rules created programmatically are applied to messages, which include mail items, meeting requests, task requests, documents, delivery receipts, read receipts, voting responses, and out-of-office notices.

Use Store.GetRules to obtain a Rules collection object representing the rules defined for the store used in the current session.

After obtaining the set of rules for the current session, you can then add new rules (by using Rules.Create), edit existing rules (by enabling or disabling rules, changing their execution order, and modifying rule actions and rule conditions), or delete rules (by using Rules.Remove) from this Rules collection. Note that while you can edit rules created in versions of Outlook before Microsoft Office Outlook 2007, you cannot use earlier versions of Outlook to edit rules that have been created in Office Outlook 2007 or later.

You can retrieve each rule in a Rules collection by indexing the collection using Rules.Item(Index), with Index being either the name of the rule (the default property Rule.Name), or a value ranging from 1 through the total number of rules in the collection, Rules.Count. Rule.ExecutionOrder indicates the order of execution of the rules in the collection and is directly mapped with the numerical value of Index in Rules.Items(Index). For example, Rules.Item(1) represents a rule with Rule.ExecutionOrder being 1, Rules.Item(2) represents a rule with Rule.ExecutionOrder being 2, and Rules.Item(Rules.Count) represents the rule with Rule.ExecutionOrder being Rules.Count.

After you have defined a rule, you should also enable it by setting the Rule.Enabled property to True, and then save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully. Note that Rules.Save can be an expensive operation in terms of performance on slow connections to Exchange server; you can optionally display a progress dialog box for the user to cancel the operation. A save fails when the user edits the same rule in the Rules and Alerts Wizard, or the user cancels the progress dialog box. In such cases, Rules.Save will raise an error, and the user will resolve the conflict by responding to the error dialog brought up by the Rules and Alerts Wizard.

When you use Rules.Save to save one or more rules that have been created in Office Outlook 2007, you will be prompted with a dialog to remind you that you will not be able to edit that rule using earlier versions of Outlook. You will have to confirm the dialog before the save opreation can proceed.

Use Rule.Execute to run a rule. Note that while you must enable and save a rule to have it enabled beyond the current session, you can run the rule regardless of its enabled state. When you execute a rule, you can optionally specify the folder to apply to rule to. The default is to execute the rule against all messages in the Inbox, but not subfolders of the Inbox.


Specifying Rule Actions

 Copy code hover
[image]

Specifying Rule Actions
Send feedback

The Rules object model supports the most commonly used rule actions and conditions. Each Rule object has an Actions property that represents the rule actions for that rule, as well as a Conditions property and an Exceptions property that represent the conditions for that rule. This topic describes how the Rules object model supports rule actions.

Rule actions for a rule are represented by a RuleActions collection object. A RuleActions object has properties that correspond to each commonly used rule action in a rule. For example, if a rule specifies two actions - moving the message to a specific folder and plays a sound - then the MoveToFolder and PlaySound properties of the rule's RuleActions collection object will return respective rule action objects that are enabled (RuleAction.Enabled is True). Actions that are not specified in a rule will not be enabled in the corresponding RuleAction object (RuleAction.Enabled is False). These rule action objects are represented by either the RuleAction object or customized objects derived from the RuleAction object. In the last example, specifically, the RuleActions.MoveToFolder property will return a MoveOrCopyRuleAction object, and the RuleActions.PlaySound property will return a PlaySoundRuleAction object, both of which are derived from the RuleAction object. The RuleAction object and its derived objects have the ActionType property that will indicate the type of the rule action. For example, MoveOrCopyRuleAction.ActionType will indicate the value olRuleActionMoveToFolder, and PlaySoundRuleAction.ActionType will indicate olRuleActionPlay.

Note that the Rules object model maintains partial parity with the Rules and Alerts Wizard. This means that while you can use the Wizard to create rules that specify any action and condition that you see in the Wizard, you can programmatically create rules that use some but not all of these actions and conditions. An example of an action that the Rules object model supports for rules created by the Wizard but not for those created by the object model is requesting a server reply. You can use the Wizard to create a rule specifying a certain server reply as an action. Using the Rules object model, you can enumerate these kinds of rules in the Rules collection - for each rule in the Rules collection, enumerate its RuleActions collection and look for an enabled rule action for a server reply. In code, this would mean for each rule in the Rules collection, enumerate RuleActions.Item(Index) using the Index from 1 to RuleActions.Count, and look for an enabled action with ActionType equal to olRuleActionServerReply. You can also enable or disable such a rule action in a rule. However, you cannot programmatically create a rule that specifies the olRuleActionServerReply action.

The following table lists all the rule actions supported by the Rules and Alerts Wizard, and whether each rule action is supported when creating a rule using the Rules object model. A rule action that is not supported in rules created by the Rules object model is supported only for programmatic enumeration and enabling or disabling in existing rules created by the Rules and Alerts Wizard. The table also shows whether the rule action applies to rules with the olRuleReceive rule type or olRuleSend rule type, or both.

Action | Constant in olRuleActionType | Supported when creating new rules programmatically? | Apply to olRuleReceive rules? | Apply to olRuleSend rules?
Assign the message to the categories specified in the AssignToCategoryRuleAction.Categories property | olRuleActionAssignToCategory | Yes | Yes | Yes
Cc the message to the recipient list specified in the SendRuleAction.Recipients property | olRuleActionCcMessage | Yes | No | Yes
Clear all categories for the message. | olRuleActionClearCategories | Yes | Yes | Yes
Copy the message to folder specified in the MoveOrCopyRuleAction.Folder property | olRuleActionCopyToFolder | Yes | Yes | Yes
Run a custom action | olRuleActionCustomAction | No | Yes | Yes
Defer the delivery by a specified number of minutes | olRuleActionDefer | No | No | Yes
Delete the message | olRuleActionDelete | Yes | Yes | No
Permanently delete the message | olRuleActionDeletePermanently | Yes | Yes | No
Display a desktop alert | olRuleActionDesktopAlert | Yes | Yes | No
Clear the message flag | olRuleActionFlagClear | No | Yes | No
Flag the message with the color specified | olRuleActionFlagColor | No | Yes | No
Flag the message for action in days specified | olRuleActionFlagForActionInDays | No | Yes | Yes
Forward the message to the recipient list specified in the SendRuleAction.Recipients property | olRuleActionForward | Yes | Yes | No
Forward the message as an attachment to the recipient list specified in the SendRuleAction.Recipients property | olRuleActionForwardAsAttachment | Yes | Yes | No
Mark the message with the specified Importance | olRuleActionImportance | No | Yes | Yes
Mark message as a task for followup using the FlagTo and MarkInterval properties of the MarkAsTaskRuleAction object | olRuleActionMarkAsTask | Yes | Yes | No
Mark as read | olRuleActionMarkRead | No | Yes | No
Move the message to the folder specified in the MoveOrCopyRuleAction.Folder property | olRuleActionMoveToFolder | Yes | Yes | No
Display the message specified in the NewItemAlertRuleAction.Text property | olRuleActionNewItemAlert | Yes | Yes | No
Notify that the message has been delivered | olRuleActionNotifyDelivery | Yes | No | Yes
Notify that the message has been read | olRuleActionNotifyRead | Yes | No | Yes
Play the .wav file specified in the PlaySoundRuleAction.FilePath property | olRuleActionPlaysound | Yes | Yes | No
Print the message to the default printer | olRuleActionPrint | No | Yes | No
Redirect the message to the recipient list specified in the SendRuleAction.Recipients property | olRuleActionRedirect | Yes | Yes | No
Start a script | olRuleActionRunScript | No | Yes | No
Mark the message with the specified sensitivity | olRuleActionSensitivity | No | No | Yes
Have server reply using the specified message | olRuleActionServerReply | No | Yes | No
Start an .exe | olRuleActionStartApplication | No | Yes | No
Stop processing more rules | olRuleActionStop | Yes | Yes | Yes
Reply using the specified template (.oft) file | olRuleActionTemplate | No | Yes | No
Unrecognized rule action | olRuleActionUnknown | No | Yes | No


Specifying Rule Conditions

 Copy code hover
[image]

Specifying Rule Conditions
Send feedback

The Rules object model supports the most commonly used rule actions and conditions. Each Rule object has an Actions property that represents the rule actions for that rule, as well as a Conditions property and an Exceptions property that represent the conditions for that rule. This topic describes how the Rules object model supports rule conditions.

Rule conditions for a rule are represented by a RuleConditions collection object. A RuleConditions object has properties that correspond to each commonly used rule condition in a rule. For example, if a rule specifies two conditions - the message is important and the subject contains certain words - then the Importance and Subject properties of the rule's RuleConditions collection object will return respective rule condition objects that are enabled (RuleCondition.Enabled is True). Conditions that are not specified in a rule will not be enabled in the corresponding RuleCondition object (RuleCondition.Enabled is False). Rule condition objects are represented by either the RuleCondition object or customized objects derived from the RuleCondition object. In the last example, the RuleConditions.Importance property will return an ImportanceRuleCondition object, and the RuleConditions.Subject property will return a TextRuleCondition object, both of which are derived from the RuleCondition object. The RuleCondition object and its derived objects have the ConditionType property that will indicate the type of the rule condition, for example, ImportanceRuleCondition.ConditionType will indicate the value olConditionImportance, and TextRuleCondition.ConditionType will indicate olConditionSubject.

Note that the Rules object model maintains partial parity with the Rules and Alerts Wizard. This means that while you can use the Wizard to create rules that specify any action and condition that you see in the Wizard, you can programmatically create rules that use some but not all of these actions and conditions. An example of a condition that the Rules object model supports for rules created by the Wizard but not for those created by the object model is messages of certain level of sensitivity. You can use the Wizard to create a rule specifying sensitivity as a condition. Using the Rules object model, you can enumerate this kind of rule in the Rules collection - for each rule in the Rules collection, enumerate its RuleConditions collection and look for an enabled rule condition for sensitivity. In code, this would mean for each rule in the Rules collection, enumerate RuleConditions.Item(Index) using the Index from 1 to RuleConditions.Count and look for an enabled condition with RuleCondition.ConditionType equal to olConditionSensitivity. You can also enable or disable such a rule condition in a rule. However, you cannot programmatically create a rule that specifies the olConditionSensitivity condition.

The following table lists all the rule conditions supported by the Rules and Alerts Wizard, and whether each rule condition is supported when creating a rule using the Rules object model. A rule condition that is not supported in rules created by the Rules object model is supported only for programmatic enumeration and enabling or disabling in existing rules created by the Rules and Alerts Wizard. The table also shows whether the rule condition applies to rules with the olRuleReceive rule type or olRuleSend rule type, or both.

Note Note

You cannot enable or disable a rule condition of the type olConditionOtherMachine. This type of rule condition indicates that the rule can run only on a certain computer, but the current computer is not that computer. This happens when the rule is created on one computer and the rule condition olConditionLocalMachineOnly is enabled, indicating that the rule can run only on that computer. In certain cases, olConditionLocalMachine is automatically set as a result of enabling another rule condition such as olConditionAccount. When you run the same rule on another computer, the rule will show that the condition olConditionOtherMachine is enabled.

Condition | Constant in olRuleConditionType | Supported when creating new rules programmatically? | Apply to olRuleReceive rules? | Apply to olRuleSend rules?
Account is the account specified in AccountRuleCondition.Account. | olConditionAccount | Yes | Yes | Yes
Message is assigned any category. | olCondtionAnyCategory | Yes | Yes | Yes
Body contains words specified in TextRuleCondition.Text. | olConditionBody | Yes | Yes | Yes
Body or subject contains words specified by TextRuleCondition.Text. | olConditionBodyOrSubject | Yes | Yes | Yes
Message is assigned the category or categories specified in CategoryRuleCondition.Categories. | olConditionCategory | Yes | Yes | Yes
Message has my name in the Cc box. | olConditionCc | Yes | Yes |
Message was received between x and y, where x and y are Integer values. | olConditionDateRange | No | Yes | Yes
Message is flagged for the specified action. | olConditionFlaggedForAction | No | Yes | Yes
Message uses the form specified in FormNameRuleCondition.FormName. | olConditionFormName | Yes | Yes | Yes
Sender is in the recipient list specified in ToOrFromRuleCondition.Recipients. | olConditionFrom | Yes | Yes | No
Message is generated from any RSS subscription. | olCondtionFromAnyRssFeed | Yes | Yes | No
Message is generated from a specified RSS subscription. | olCondtionFromRssFeed | Yes | Yes | No
Message has an attachment. | olConditionHasAttachment | Yes | Yes | Yes
Message is marked with the specified level of importance. | olConditionImportance | Yes | Yes | Yes
Rule can run only on this machine. | olConditionLocalMachineOnly | Yes | Yes | Yes
Message is a meeting invitation or update. | olConditionMeetingInviteOrUpdate | Yes | Yes | Yes
Message header contains words specified in TextRuleCondition.Text. | olConditionMessageHeader | Yes | Yes | No
Message does not have my name in the To box. | olConditionNotTo | Yes | Yes | No
Message is sent only to me. | olConditionOnlyToMe | Yes | Yes | No
Message is an out-of-office message. | olConditionOOF | No | Yes | No
Rule can run only on a specific machine that is not the current one. | olConditionOtherMachine | No | Yes | Yes
Document property is exactly, contains, or does not contain specified properties. | olConditionProperty | No | Yes | Yes
Recipient address contains words specified in TextRuleCondition.Text. | olConditionRecipientAddress | Yes | Yes | Yes
Sender address contains words specified in TextRuleCondition.Text. | olConditionSenderAddress | Yes | Yes | No
Sender is in the address list specified in AddressRuleCondition.Address. | olConditionSenderInAddressBook | Yes | Yes | No
Message is marked with the specified level of sensitivity. | olConditionSensitivity | No | Yes | Yes
Sent to recipients (To, Cc) are in the recipient list specified in ToOrFromRuleCondition.Recipients. | olConditionSentTo | Yes | Yes | Yes
Message size is between x and y in units of KB, where x and y are Date values. For example, "10;50" sets the size condition between 10 and 50KB. | olConditionSizeRange | No | Yes | Yes
Subject contains words specified in TextRuleCondition.Text. | olConditionSubject | Yes | Yes | Yes
My name is in the To box. | olConditionTo | Yes | Yes | No
Message has my name in the To or Cc box. | olConditionToOrCc | Yes | Yes | No
Unrecognized rule condition. | olConditionUnknown | No | Yes | No


How to: Create a Rule to Move Specific E-mails to a Folder

 Copy code hover
[image]

How to: Create a Rule to Move Specific E-mails to a Folder
Send feedback

This topic shows a code sample in Visual Basic for Applicatons (VBA) that uses the Rules object model to create a rule. The code sample uses the RuleAction and RuleCondition objects to specify a rule that moves messages from a specific sender to a specific folder, unless the message contains certain terms in the subject. Note that the code sample assumes that there already exists a folder named "Dan" under the Inbox.

The following describes the steps used to create the rule:

  1. Specify the target folder oMoveTarget to move specific messages as determined by the condition and exception condition. The target folder is a subfolder named "Dan" under the Inbox, and is assumed to already exist.

  2. Use Store.GetRules to obtain a set of all the rules in the current session.

  3. Using the Rules collection returned from the last step, use Rules.Create to add a new rule. The new rule specifies some action upon receiving a message, so it is of type olRuleReceive.

  4. Using the Rule object returned from the last step, use the RuleConditions.From property to obtain a ToOrFromRuleCondition object, oFromCondition. oFromCondition specifies the condition for the rule: when a message is from Dan Wilson.

  5. Using the same Rule object, use the RuleActions.MoveToFolder property to obtain a MoveOrCopyRuleAction object, oMoveRuleAction. oMoveRuleAction specifies the action for the rule: move the message to the target folder "Dan".

  6. Using the same Rule object, use the RuleConditions.Subject property to obtain a TextRuleCondition object, oExceptSubject. oExceptSubject specifies the exception condition: if the subject contains the terms "fun" or "chat", then do not apply the rule to move the message to the folder "Dan".

  7. Use Rules.Save to save the new rule together with the rest of the rules for the current store.

Copy code Copy code
Sub CreateRule()
    Dim colRules As Outlook.Rules
    Dim oRule As Outlook.Rule
    Dim colRuleActions As Outlook.RuleActions
    Dim oMoveRuleAction As Outlook.MoveOrCopyRuleAction
    Dim oFromCondition As Outlook.ToOrFromRuleCondition
    Dim oExceptSubject As Outlook.TextRuleCondition
    Dim oInbox As Outlook.Folder
    Dim oMoveTarget As Outlook.Folder

    'Specify target folder for rule move action
    Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)
    'Assume that target folder already exists
    Set oMoveTarget = oInbox.Folders("Dan")

    'Get Rules from Session.DefaultStore object
    Set colRules = Application.Session.DefaultStore.GetRules()

    'Create the rule by adding a Receive Rule to Rules collection
    Set oRule = colRules.Create("Dan's rule", olRuleReceive)

    'Specify the condition in a ToOrFromRuleCondition object
    'Condition is if the message is from "Dan Wilson"
    Set oFromCondition = oRule.Conditions.From
    With oFromCondition
        .Enabled = True
        .Recipients.Add ("Dan Wilson")
        .Recipients.ResolveAll
    End With

    'Specify the action in a MoveOrCopyRuleAction object
    'Action is to move the message to the target folder
    Set oMoveRuleAction = oRule.Actions.MoveToFolder
    With oMoveRuleAction
        .Enabled = True
        .Folder = oMoveTarget
    End With

    'Specify the exception condition for the subject in a TextRuleCondition object
    'Exception condition is if the subject contains "fun" or "chat"
    Set oExceptSubject = _
        oRule.Exceptions.Subject
    With oExceptSubject
        .Enabled = True
        .Text = Array("fun", "chat")
    End With

    'Update the server and display progress dialog
    colRules.Save
End Sub


Search and Filter (Outlook)

 Copy code hover
[image]

Search and Filter (Outlook)
Send feedback

In this section

  • Overview (Outlook Search and Filter)

  • Table

  • Filtering

  • Searching

  • How To


Overview (Outlook Search and Filter)

 Copy code hover
[image]

Overview (Outlook Search and Filter)
Send feedback


Table

 Copy code hover
[image]

Table
Send feedback

In this section

  • Adding Columns to a Table Object

  • Default Properties Displayed in a Table Object

  • Factors Affecting Property Value Representation in the Table and View Classes

  • Unsupported Properties in a Table Object or Table Filter


Adding Columns to a Table Object

 Copy code hover
[image]

Adding Columns to a Table Object
Send feedback

This topic describes how to add columns to a Table object.

To obtain an initial Table object, use Folder.GetTable or Search.GetTable. The returned Table object always contains a default set of properties depending on the folder type of the parent folder. If you want to change the columns in a Table, start with the Table object returned from a prior GetTable call. Use Table.Columns to obtain the Columns object, and call Columns.Add, Columns.Remove, or Columns.RemoveAll. As a result of the call on the Columns object, the parent Table object is updated.

Note Note

Each of these calls on the Columns object adjusts the columns in the parent Table. The rows in the Table however remain the same as before the call. You do not call GetTable subsequently to obtain an updated Table. GetTable always returns a Table with the default set of columns for that folder type.

Since a folder can contain heterogeneous items (for example, the Deleted Items folder), you can use Columns.Add to add columns that do not apply to all rows in that Table. In such cases, Row.Item would return an error indicating that an object could not be found for the row at the specific column. Consequently, before you access other column values in a Table, you should first check for the MessageClass of a row (by calling Row.Item("MessageClass")) to determine which columns in the Table apply to that row.

Note Note

Since the Item method is the default method for the Row object, Row.Item("MessageClass") is equivalent to Row("MessageClass").


Default Properties Displayed in a Table Object

 Copy code hover
[image]

Default Properties Displayed in a Table Object
Send feedback

A Table contains rows and columns, where rows represent items in a folder, and columns represent item properties. When you call Folder.GetTable, you obtain a Table object that has a small pre-defined set of columns corresponding to properties common to default items for that type of folder. Similarly, when you call Search.GetTable, you obtain a Table that has columns corresponding to properties common to default items for all folder types. The pre-defined sets of properties are explicit built-in properties. The small size of these sets allows the GetTable call to perform relatively efficiently.

The following tables list the set of properties returned by GetTable for each type of folder or a search folder. Properties are stored as a 1-based array in a Columns object.

Columns for all Folder Types

The following table shows the properties that are returned as default columns in a Table for any folder, including a search folder, Inbox, Sent Items, Deleted Items, Journal, and Notes:

Column | Description
1 | EntryID
2 | Subject
3 | CreationTime
4 | LastModificationTime
5 | MessageClass

Columns for the Calendar Folder

The following table shows the properties that are returned as default columns in a Table for the Calendar folder:

Column | Description
1 | EntryID
2 | Subject
3 | CreationTime
4 | LastModificationTime
5 | MessageClass
6 | Start
7 | End
8 | IsRecurring

Columns for the Contacts Folder

The following table shows the properties that are returned as default columns in a Table for the Contacts folder:

Column | Description
1 | EntryID
2 | Subject
3 | CreationTime
4 | LastModificationTime
5 | MessageClass
6 | FirstName
7 | LastName
8 | CompanyName

Columns for the Task Folder

The following table shows the properties that are returned as default columns in a Table for the Task folder:

Column | Description
1 | EntryID
2 | Subject
3 | CreationTime
4 | LastModificationTime
5 | MessageClass
6 | DueDate
7 | PercentComplete
8 | IsRecurring


Factors Affecting Property Value Representation in the Table and View Classes

 Copy code hover
[image]

Factors Affecting Property Value Representation in the Table and View Classes
Send feedback

There are a couple of factors that affect the type and format of a property in a Table and in a View. String properties are affected by the store provider, and binary, date, and multi-valued properties are affected by the way the property is referenced when it is first added to a Table, an OrderFields collection, or a ViewFields collection, or specified as a StartField or EndField in a CalendarView or TimelineView.

String Properties Affected by Store Providers

The length of the value of a string property depends on the store provider. For Exchange and OST/PST stores, the length of the string value will not exceed 255 bytes. This means that string values longer than 255 bytes will be truncated at the first 255 characters.

For example, if you use Columns.Add to add the PR_INTERNET_TRANSPORT_HEADERS property (referenced by namespace as http://schemas.microsoft.com/mapi/proptag/0x007d001e) to a Table, the Table will only store the first 255 characters of the full content of the property. If you need to determine the full content of the property, you must use the corresponding item's Entry ID in NameSpace.GetItemFromID to obtain a full item. Once you have the item, you can use the PropertyAccessor to obtain the complete property value.

Date, Binary, and Multi-valued Properties Affected by Property Reference

The type and format of a binary, date, or multi-valued property are affected by how the property is referenced when it is first added to a Table or as a field to a View. Is the property referenced by its explicit built-in name (if it has one), or is it referenced by namespace (regardless of the existence of an explicit built-in name)? The following table summarizes the difference in the property value representation (in terms of type and format) per original property type:

Type of Property | Type/Format Stored if Property Added by Referencing an Explicit Built-in Name | Type/Format Stored if Property Added by Referencing a Namespace
Binary | String | Byte array
Date | Local time | Coordinated Universal Time (UTC)
Multi-valued | String containing comma-separated values | 1-dimensional array containing one element for each keyword
Note Note

For more information on referencing properties by namespace, see Referencing Properties by Namespace.


Unsupported Properties in a Table Object or Table Filter

 Copy code hover
[image]

Unsupported Properties in a Table Object or Table Filter
Send feedback

This topic lists the properties that you cannot add to a Table or use in a Table filter. You cannot add these properties through Columns.Add, and you cannot specify these properties in a filter used by the following methods:

  • Folder.GetTable

  • Search.GetTable (Note that the filter is derived from the Search object returned by Application.AdvancedSearch)

  • Table.FindRow

  • Table.Restrict

Properties | In Table Object | In Table Filter | Comments
Binary properties | Supported | Not supported | If you add a binary property to a Table referencing its namespace, the value of the property in the Table is in binary. You can use Row.BinaryToString to convert the value to a string.
Body properties, including Body, HTMLBody, http://schemas.microsoft.com/mapi/proptag/0x10130102 (for PidTagHtml), and http://schemas.microsoft.com/mapi/proptag/0x10090102 (for PidTagRtfCompressed) | The Body property is supported with a condition that only the first 255 bytes of the value are stored in a Table. Other properties representing the body content in HTML or RTF are not supported. Because only the first 255 bytes of Body is stored in a Table, if you want to obtain the full body content of an item in text or HTML, use the item's EntryID in GetItemFromID to obtain the item object. Then retrieve the full value of Body through the item object. | Only the Body property represented in text is supported in a filter. This means that the property must be referenced in a DASL filter as urn:schemas:httpmail:textdescription, and you cannot filter on any HTML tags in the body. To improve performance, use context indexer keywords in the filter to match strings in the body. |
Computed properties, such as AutoResolvedWinner and BodyFormat. See below for a complete list of computed properties. | Not supported | Not supported | To obtain the value of a computed property for an item in a Table, use the item's EntryID in GetItemFromID to obtain the item object. Then retrieve the property value through the item object.
Multi-valued properties, such as Categories, Children, Companies, and VotingOptions | Supported | Although both Jet and DASL filters both support multi-valued properties, use content indexing in DASL filters for more efficient filtering. For more information, see Filtering Items Using a Comparison with a Keywords Property. | The format of the values of a multi-valued property in a Table depends on whether the property was added with its explicit built-in name or with a name referencing its namespace. If the property is added with its explicit built-in name, the value in the Table is a comma-delimited string. Otherwise, the value is a variant array. For more information, see How to: Access the Values of a Multi-valued Property in a Table.
Properties returning an object, such as Attachments, Parent, Recipients, RecurrencePattern, and UserProperties. | Not supported if property is referenced by its explicit built-in name; supported if property is referenced by its namespace. | Not supported if property is expressed in a Jet query; supported if property is expressed in a DASL query. |

Unsupported Computed Properties

If you attempt to add one of the computed properties listed below using Columns.Add, referencing the property either by the explicit property name or by namespace, you will get the error, IDS_ERR_BLOCKED_PROPERTY. To determine the value of these properties, obtain the item object using its Entry ID and then use the item object to determine the property value (as in object.property):

  • AutoResolvedWinner

  • BodyFormat

  • Class

  • ContactNames

  • Companies

  • DLName

  • DownloadState

  • FlagIcon

  • HtmlBody

  • InternetCodePage

  • IsConflict

  • IsMarkedAsTask

  • MeetingWorkspaceURL

  • MemberCount

  • Permission

  • PermissionService

  • RecurrenceState

  • ResponseState

  • Saved

  • Sent

  • Submitted

  • TaskSubject

  • Unread

  • VotingOptions

If you attempt to use one of the computed properties listed below in a Jet filter (referencing the property by its explicit property name) for Table.Restrict, you will get the error, IDS_ERR_ES_INVALIDRESTRICTION:

  • AutoResolvedWinner

  • Body

  • BodyFormat

  • Class

  • ContactNames

  • Companies

  • CompanyLastFirstNoSpace

  • CompanyLastFirstSpaceOnly

  • ContactNames

  • Contents

  • ConversationIndex

  • DLName

  • DownloadState

  • Email1EntryID

  • Email2EntryID

  • Email3EntryID

  • EntryID

  • HtmlBody

  • InternetCodePage

  • IsConflict

  • IsMarkedAsTask

  • LastFirstAndSuffix

  • LastFirstNoSpace

  • LastFirstNoSpaceAndSuffix

  • LastFirstNoSpaceCompany

  • LastFirstSpaceOnly

  • LastFirstSpaceOnlyCompany

  • MeetingWorkspaceURL

  • MemberCount

  • NetMeetingAlias

  • NetMeetingServer

  • Permission

  • PermissionService

  • RecurrenceState

  • ReceivedByEntryID

  • ReceivedOnBehalfOfEntryID

  • ReplyRecipients

  • ResponseState

  • Saved

  • Sent

  • Submitted

  • TaskSubject

  • VotingOptions

Note Note

For a computed property such as TaskSubject or IsMarkedAsTask, you cannot add it to a Table using Columns.Add or filter it using Table.Restrict, if you reference the property with the explicit property name. However, you can add or filter on the property if you reference it by namespace, as in the following code sample in Visual Basic for Applications:

Copy code Copy code
Sub TableForIsMarkedAsTask()
    Dim oT As Outlook.Table
    Dim oRow As Outlook.Row
    Dim filter As String
    '0x0E2B0003 represents IsMarkedAsTask
    filter = "@SQL=" & Chr(34) _
    & "http://schemas.microsoft.com/mapi/proptag/0x0E2B0003" & Chr(34) & " = 1"
    'Table only contains rows for items where IsMarkedAsTask is True
    Set oT = Application.Session.GetDefaultFolder(olFolderInbox).GetTable(filter)
    oT.Columns.Add ("TaskStartDate")
    oT.Columns.Add ("TaskDueDate")
    oT.Columns.Add ("TaskCompletedDate")
    'Use GUID/ID to represent TaskSubject
    oT.Columns.Add ( _
        "http://schemas.microsoft.com/mapi/id/{00062008-0000-0000-C000-000000000046}/85A4001E")
    Do Until oT.EndOfTable
        Set oRow = oT.GetNextRow
        Debug.Print oRow( _
        "http://schemas.microsoft.com/mapi/id/{00062008-0000-0000-C000-000000000046}/85A4001E"), _
        oRow("TaskStartDate"), oRow("TaskDueDate"), oRow("TaskCompletedDate")
    Loop
End Sub


Filtering

 Copy code hover
[image]

Filtering
Send feedback

In this section

  • Filtering Items

  • Filtering a Custom Field

  • Filtering Items Using a Boolean Comparison

  • Filtering Items Using a Comparison with a Keywords Property

  • Filtering Items Using a Date-time Comparison

  • Filtering Items Using a String Comparison

  • Filtering Items Using a Variable

  • Filtering Items Using an Integer Comparison

  • Filtering Items Using Comparison and Logical Operators

  • Filtering Items Using Query Keywords


Filtering Items

 Copy code hover
[image]

Filtering Items
Send feedback

This topic describes the general rules for specifying properties in filters that are supported by various objects in Outlook. See the topics in the Filter Syntax section for further information on specifying conditions on properties to complete a filter.

A filter is a condition or a set of conditions that you can apply to a set of items in order to obtain a subset of items that meets the specified conditions. Outlook supports filters using the Microsoft Jet query language syntax or the DAV Searching and Locating (DASL) syntax. Note that the Jet query language syntax has the same syntax as that supported by Microsoft Jet Expression Service, hence the name Jet query language.

As an example, you can filter contact items in your Contacts folder to obtain a list of contacts residing in Canada. In this case, you will be filtering on the HomeAddressCountry property. The filter, expressed as a Jet filter, will be "[HomeAddressCountry] = 'Canada'".

Outlook provides filtering through the following entry points:

Entry Point | Jet Filter Support | DASL Filter Support
Application.AdvancedSearch | No | Yes
Folder.GetTable | Yes | Yes
Items.Find | Yes | Yes. Note that if you use the query keywords ci_phrasematch or ci_startswith in the filter, you will get an error.
Items.Restrict | Yes | Yes
Search.GetTable | No | Yes
Table.FindRow | Yes | Yes. Note that if you use the query keywords ci_phrasematch or ci_startswith in the filter, you will get an error.
Table.Restrict | Yes | Yes
View.Filter | No | Yes

Note Note

A filter must contain a query in either Jet or DASL syntax but not a mixture of both.

Property Specifiers

When specifying properties in a Jet filter or DASL filter using any of the above entry points, follow these guidelines:

Jet Filter

DASL Filter

Applicable Properties

Most explicit built-in and custom item-level properties; see corresponding method topic for unsupported properties.

Most built-in and custom item-level properties with and without explicit string names; see corresponding method topic for unsupported properties.

Referencing Properties

  • By their explicit string names.

  • Explicit built-in properties can only be referenced by their names in English and not any other localized language.

  • Custom properties can be referenced by their names in English or a localized language.

By their namespaces.

Format of Reference

  • Enclose square brackets ('['']') around explicit string names.

  • Property names are not case-sensitive.

  • Spaces are not allowed in explicit built-in properties.

  • Spaces are allowed in custom properties.

  • All DASL queries begin with a case-sensitive prefix "@SQL=", with the exception of DASL queries for Application.AdvancedSearch.

  • Property referenced by namespace must be enclosed in double quotes.

  • Property referenced by namespace are case-sensitive.

  • If a space exists in the name of a custom property, the space must be replaced by "%20". In general, URL encoding applies the same way to characters in a DASL query as in a URL.

Error Conditions

Returns an error if a custom property in the filter is not defined, or the filter is empty, has an invalid argument, or cannot be parsed.

Returns an error if a custom property in the filter is not defined, or the filter is empty, has an invalid argument, or cannot be parsed.

Filter Syntax

The syntax of a filter depends on the type of the property you are filtering on. The following topics provide further information on how to construct a filter based on a specific property type:

  • Filtering a Custom Field

  • Filtering Items Using a Boolean Comparison

  • Filtering Items Using a Comparison with a Keywords Property

  • Filtering Items Using a Date-time Comparison

  • Filtering Items Using a String Comparison

  • Filtering Items Using a Variable

  • Filtering Items Using an Integer Comparison

  • Filtering Items Using Comparison and Logical Operators

  • Filtering Items Using Query Keywords


Filtering a Custom Field

 Copy code hover
[image]

Filtering a Custom Field
Send feedback

You can specify custom properties in filters using Microsoft Jet syntax or DAV Searching and Locating (DASL) syntax. The custom properties must be defined in the folder where you are applying the filter. If the custom properties are only defined in the item, the search will fail.

Jet Queries

Custom properties can contain spaces in the property name. In a Jet query, as in all property name references, simply enclose the custom property name in square brackets. For example, the following Jet query retrieves all contacts where the custom property named "Preferred Gift" is exactly "Diamonds". For the query to succeed, the custom property named "Preferred Gift" has been defined in the folder that contains the custom contact items:

Copy code Copy code
criteria = "[Preferred Gift] = 'Diamonds'"

DASL Queries

In a DASL query, if the name of a custom property contains spaces, you must apply Uniform Resource Locator (URL) encoding to each space character and replace the space with "%20". In general, URL encoding applies the same way to characters in a DASL query as in a URL.

When you construct a DASL query for a custom property, you must use the namespace GUID for Outlook custom properties in the following format:

http://schemas.microsoft.com/mapi/string/{GUID}/PropertyName

where {GUID} is the following GUID:

{00020329-0000-0000-C000-000000000046}

Filtering Custom Properties Referenced by the MAPI String Namespace

If the custom property you are filtering for does not exist in the UserDefinedProperties collection for the folder, and if you are referencing the custom property by the MAPI string namespace, then you must explicitly append a type specifier to the namespace representation of the custom property. Note that you need to specify the type only when applying a DASL filter to search and filter entry points in the Items collection and the Table object, and to the Application.AdvancedSearch method.

Note Note

The hexagonal type specifier must be of the form 0000HHHH with only 8 digits as opposed to 9. For more information on the hexagonal type specifiers (HHHH) for various MAPI types, see Property Types.

For example, if you want to use Items.Restrict to search for the custom Unicode string property named "MyProperty" and this property does not exist in the UserDefinedProperties collection for the folder, you must append the Unicode string type specifier, 0000001f, to the representation of the property in the MAPI string namespace:

Copy code Copy code
criteria = "@SQL=" & Chr$(34) & "http://schemas.microsoft.com/mapi/string/" _
& "{00020329-0000-0000-C000-000000000046}/MyProperty"_
& "/0000001f" & Chr(34) & " = '12-74440'"


Filtering Items Using a Boolean Comparison

 Copy code hover
[image]

Filtering Items Using a Boolean Comparison
Send feedback

Boolean values are specified differently in a filter in Microsoft Jet syntax than in a filter in DAV Searching and Locating (DASL) syntax.

Jet Queries

In Jet syntax, boolean operators such as True/False, Yes/No, On/Off, and so on, should be used as is and should not be converted to a string. For example, to create a filter to return unread items, you can use this filter:

Copy code Copy code
criteria = "[UnRead] = True"
Note Note

If you convert the boolean value to a comparison string by enclosing it in quotation marks, then a Jet filter using any non-empty comparison string and filtering on a boolean property will return items that have the property True. A Jet filter comparing an empty string with a boolean property will return items that have the property False.

DASL Queries

In DASL syntax, you must convert True/False to an integer value, where 0 represents False and 1 represents True; likewise for Yes/No and On/Off. The DASL filter to return unread items is as follows:

Copy code Copy code
criteria = "@SQL=" & Chr(34) & "urn:schemas:httpmail:read" & Chr(34) _ & " = 0"


Filtering Items Using a Comparison with a Keywords Property

 Copy code hover
[image]

Filtering Items Using a Comparison with a Keywords Property
Send feedback

The following discussion uses the Categories property as an example, but can apply as well to any multi-valued string property.

The Categories property of an item is of type keywords which can contain multiple values. When being compared to a comparison string in a filter, the Categories property behaves like a text string where values are separated by a comma and a space. This is true for filters using Microsoft Jet syntax or DAV Searching and Locating (DASL) syntax.

Jet Queries

In a Jet query, you can only perform phrase-matching on a keywords property. You cannot perform starts-with or substring matching with a Jet query. Consider the following criteria for Table.Restrict:

Copy code Copy code
string filter  = "[Categories] = 'Partner'"

This Jet query will return rows for items where the Categories property for the item finds a phrase-match for Partner. It will return rows for items that are categorized as Partner, for items that are categorized as Partner and Important, and for items that are categorized as Tier1 Partner. It will not return rows for items that are categorized only as Partnership.

DASL Queries

To overcome the limitations of keywords restrictions using the Jet query syntax, use DASL syntax which allows starts-with or substring restrictions. The following criteria string will find all items that contain Partner as a category, as one of the words in a category, and as the beginning part of a word in the category, such as the category Partnership:

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas-microsoft-com:office:office#Keywords" _
& Chr(34) & " ci_startswith 'Partner'"

You can also use a DASL query for equivalence matching in a multi-valued string property. Consider an example where items have one or more of the following four categories:

  • Book

  • My Book

  • Book Review

  • Bookish

The DASL equivalence query:

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas-microsoft-com:office:office#Keywords" & Chr(34) _
& " = 'Book'"

returns any item that has Book as a category, including those categorized with multiple categories, where Book is one of the categories. The query does not return items that do not have Book as a category.

If the multi-valued property is added to the Table using a reference by namespace, the format of the values of the property is a variant array. To access these values, parse the elements in the array. Using the last example, this would also allow you to obtain the items that contain exactly Partner as a category.


Filtering Items Using a Date-time Comparison

 Copy code hover
[image]

Filtering Items Using a Date-time Comparison
Send feedback

Filtering Recurring Items in the Calendar Folder

To filter a collection of appointment items that include recurring appointments, you must use the Items collection. Use the Items.IncludeRecurrences property to specify that Items.Find or Items.Restrict should include recurring appointments. The Table object returns only one row representing the recurrent appointment item, instead of a row for each occurrence of the appointment.

Date-time Format of Comparison Strings

Outlook evaluates date-time values according to the time format, short date format, and long date format settings in the Regional and Language Options applet in the Windows Control Panel. In particular, Outlook evaluates time according to that specified time format without seconds. If you specify seconds in the date-time comparison string, the filter will not operate as expected.

Although dates and times are typically stored with a date format, filters using the Jet and DAV Searching and Locating (DASL) syntax require that the date-time value to be converted to a string representation. In Jet syntax, the date-time comparison string should be enclosed in either double quotes or single quotes. In DASL syntax, the date-time comparison string should be enclosed in single quotes.

To make sure that the date-time comparison string is formatted as Microsoft Outlook expects, use the Visual Basic for Applications Format function (or its equivalent in your programming language). The following example creates a Jet filter to find all contacts that have been modified before June 12, 2005 at 3:30 P.M local time.

VBA Copy code Copy code
criteria = "[LastModificationTime] < '" _
         & Format$("6/12/2005 3:30PM","General Date") & "'"

Time Zones Used in Comparison

When an explicit built-in property is referenced in a Jet query with its explict string name, the comparison evaluates the property value and the date-time comparison string as local time values.

When a property is referenced in a DASL query by namespace, the comparison evaluates the property value and the date-time comparison string as Coordinated Universal Time (UTC) values. For example, the following DASL query finds all contacts that have been modified before June 12, 2005 at 3:30 pm, UTC.

VBA Copy code Copy code
criteria = "@SQL=" & Chr(34) & "DAV:getlastmodified" & Chr(34) _
         & " < '" & Format$("6/12/2005 3:30PM","General Date") & "'"

Conversion to UTC for DASL Queries

Since DASL queries always perform date-time comparisons in UTC, if you use a date literal in a comparison string, you must use its UTC value for the comparison. You can use the Row.LocalTimeToUTC helper function or Outlook date-time macros to facilitate the conversion.

LocalTimeToUTC

One way to facilitate local time to UTC conversion is to use the helper function, LocalTimeToUTC, of the Row object. The following line of code uses this helper function to convert the value of the LastModificationTime property (which is a default column in all Table objects):

VBA Copy code Copy code
Row.LocalTimeToUTC("LastModificationTime")

Outlook Date-time Macros

The date macros listed below return filter strings that compare the value of a given date-time property with a specified date in UTC; SchemaName is any valid date-time property referenced by namespace.

Note Note

Outlook date-time macros can be used only in DASL queries.

Macro | Syntax | Description
today | %today("SchemaName")% | Restricts for items with SchemaName property value equal to today
tomorrow | %tomorrow("SchemaName")% | Restricts for items with SchemaName property value equal to tomorrow
yesterday | %yesterday("SchemaName")% | Restricts for items with SchemaName property value equal to yesterday
next7days | %next7days("SchemaName")% | Restricts for items with SchemaName property value equal to next 7 days
last7days | %last7days("SchemaName")% | Restricts for items with SchemaName property value equal to last 7 days
nextweek | %nextweek("SchemaName")% | Restricts for items with SchemaName property value equal to next week
thisweek | %thisweek("SchemaName")% | Restricts for items with SchemaName property value equal to this week
lastweek | %lastweek("SchemaName")% | Restricts for items with SchemaName property value equal to last week
nextmonth | %nextmonth("SchemaName")% | Restricts for items with SchemaName property value equal to next month
thismonth | %thismonth("SchemaName")% | Restricts for items with SchemaName property value equal to this month
lastmonth | %lastmonth("SchemaName")% | Restricts for items with SchemaName property value equal to last month

Example Showing Conversion to UTC

The following code example illustrates three filter strings that return all messages received today, and applies one of the filters to Items.Restrict and Application.AdvancedSearch. It first uses PropertyAccessor.LocalTimeToUTC to convert today's date to UTC date strings. The first filter uses the Outlook macro, today, to obtain a filter string that compares the ReceivedTime property with today's date in UTC. The second and third macros reference the ReceivedTime property by two different namespaces. The code example finally applies the third filter to items in the Inbox twice, first using Items.Restrict and then using Application.AdvancedSearch. It prints the number of items in the Inbox, and the number of items returned from each application of the filter.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Sub TestDASLDateComparison()
    Dim strFilter As String
    Dim colItems As Outlook.Items
    Dim colRestrict As Outlook.Items
    Dim oSearch As Outlook.Search
    Dim oResults As Outlook.Results
    Dim datStartUTC As Date
    Dim datEndUTC As Date
    Dim oMail As MailItem
    Dim oPA As PropertyAccessor
    Const SchemaPropTag As String = _
    "http://schemas.microsoft.com/mapi/proptag/"

    'Get items from Inbox
    Set colItems = _
    Application.Session.GetDefaultFolder(olFolderInbox).Items

    'This code is a workaround to get today's date
    'as UTC for DASL date comparison
    Set oMail = Application.CreateItem(olMailItem)
    Set oPA = oMail.PropertyAccessor
    datStartUTC = oPA.LocalTimeToUTC(Date)
    datEndUTC = oPA.LocalTimeToUTC(DateAdd("d", 1, Date))

    'All three filters shown below will return the same results
    'This filter uses DASL date macro for today
    strFilter = "%today(" _
    & AddQuotes("urn:schemas:httpmail:datereceived") & ")%"

    'This filter uses urn:schemas:httpmail namespace
    strFilter = AddQuotes("urn:schemas:httpmail:datereceived") _
    & " > '" & datStartUTC & "' AND " _
    & AddQuotes("urn:schemas:httpmail:datereceived") _
    & " < '" & datEndUTC & "'"

    'This filter uses http://schemas.microsoft.com/mapi/proptag
    strFilter = AddQuotes(SchemaPropTag & "0x0E060040") _
    & " > '" & datStartUTC & "' AND " _
    & AddQuotes(SchemaPropTag & "0x0E060040") _
    & " < '" & datEndUTC & "'"

    'Count of items in Inbox
    Debug.Print (colItems.Count)

    'This call succeeds with @SQL prefix
    Set colRestrict = colItems.Restrict("@SQL=" & strFilter)
    'Get count of restricted items
    Debug.Print (colRestrict.Count)

    Set oSearch = Application.AdvancedSearch("Inbox", strFilter, False)
    While blnSearchComp = False
        DoEvents
    Wend

    'Get count from Search object
    Set oResults = oSearch.Results
    Debug.Print (oResults.Count)
End Sub

Public Function AddQuotes(ByVal SchemaName As String) As String
    On Error Resume Next
    AddQuotes = Chr(34) & SchemaName & Chr(34)
End Function

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)
    MsgBox "The AdvancedSearchComplete Event fired"
    blnSearchComp = True
End Sub


Filtering Items Using a String Comparison

 Copy code hover
[image]

Filtering Items Using a String Comparison
Send feedback

This topic describes the support for filtering on a string property using Microsoft Jet syntax and DAV Searching and Locating (DASL) syntax.

Delimiting Strings and Using Escape Characters

When matching string properties, you can use either a pair of single quotes ('), or a pair of double quotes ("), to delimit a string that is part of the filter. For example, all of the following lines function correctly when the property is of type String:

Copy code Copy code
sFilter = "[CompanyName] = 'Microsoft'"

sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

In specifying a filter in a Jet or DASL query, if you use a pair of single quotes to delimit a string that is part of the filter, and the string contains another single quote or apostrophe, then add a single quote as an escape character before the single quote or apostrophe. Use a similar approach if you use a pair of double quotes to delimit a string. If the string contains a double quote, then add a double quote as an escape character before the double quote.

For example, in the DASL filter string that filters for the Subject property being equal to the word can't, the entire filter string is delimited by a pair of double quotes, and the embedded string can't is delimited by a pair of single quotes. There are three characters that you need to escape in this filter string: the starting double quote and the ending double quote for the property reference of http://schemas.microsoft.com/mapi/proptag/0x0037001f, and the apostrophe in the value condition for the word can't. Applying the appropriate escape characters, you can express the filter string as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'can''t'"

Alternatively, you can use the chr(34) function to represent the double quote (whose ASCII character value is 34) that is used as an escape character. Using the chr(34) substitution for a double-quote escape character, you can express the last example as follows:

Copy code Copy code
filter = "@SQL= " & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001f" _
    & Chr(34) & " = " & "'can''t'"

Escaping single and double quote characters is also required for DASL queries with the ci_startswith or ci_phrasematch operators. For example, the following query performs a phrase match query for can't in the message subject:

Copy code Copy code
filter = "@SQL=" & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001E" _
    & Chr(34) & " ci_phrasematch " & "'can''t'"

Another example is a DASL filter string that filters for the Subject property being equal to the words the right stuff, where the word stuff is enclosed by double quotes. In this case, you must escape the enclosing double quotes as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'the right ""stuff""'"

A different set of escaping rules apply to a property reference for named properties that contain the space, single quote, or double quote characters. If the property reference contains a space, single quote, or double quote character, you must use Universal Resource Locator (URL) escaping in the property reference as follows:

Character in Property Reference | Escape Character
Space character | %20
Double quote | %22
Single quote | %27

For example, you would use the following filter to search for a custom property named Mom's "Gift" that contains the word pearls:

Copy code Copy code
filter = "@SQL=" & Chr(34) & _
    "http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000-000000000046}/" _
    & "Mom%27s%20%22Gift%22" & Chr(34) & " like '%pearls%'"

String Comparisons Using Jet Syntax

The string comparison that Jet filters support is limited to an equivalence matching. You can filter items based on the value of a string property being equivalent to a specific string, for example, the LastName property being equal to "Wilson". Note that the comparison is not case sensitive; in the last example, specifying "Wilson" and "wilson" as the comparison string will return the same results.

String Comparisons Using DASL Syntax

The string comparison that DASL filters support includes equivalence, prefix, phrase, and substring matching. Note that when you filter on the Subject property, prefixes such as "RE: " and "FW: " are ignored. For example,

Copy code Copy code
sFilter = "[Subject] = 'cat'"

will match both "cat" and "RE: cat".

Equivalence Matching

Similar to Jet filters, DASL filters perform string equivalence comparison by using the equal (=) operator. The value of the string property must be equivalent to the comparison string, with the exception of prefixes "RE: " and "FW: " as mentioned above.

As an example, the following DASL query creates a filter for company name equals 'Microsoft':

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas-microsoft-com:office:office#Company" & Chr(34) _
& " = 'Microsoft'"

As another example, assume that the folder you are searching contains items with the following subjects:

  • Question

  • Questionable

  • Unquestionable

  • RE: Question

  • The big question

The following = restriction:

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas:httpmail:subject" & Chr(34) _
& " = 'question'"

will return the following results:

  • Question

  • RE: Question

Prefix, Phrase, and Substring Matching

DASL supports the matching of prefixes, phrases, and substrings in a string property using content indexer keywords ci_startswith and ci_phrasematch, and the keyword like. If a store is indexed, searching with content indexer keywords is more efficient than with like. If your search scenarios include substring matching (which content indexer keywords do not support), use the like keyword in a DASL query.

A DASL query can contain ci_startswith or ci_phrasematch, and like, but all string comparisons will be carried out as substring matching.

ci_startswith

The syntax of ci_startswith is as follows:

Copy code Copy code
<PropertySchemaName> ci_startswith <ComparisonString>

where PropertySchemaName is a valid name of a property referenced by namespace, and ComparisonString is the string used for comparison.

ci_startswith performs a search to match prefixes. It uses tokens (characters, word, or words) in the comparison string to match against the first few characters of any word in the string value of the indexed property. If the comparison string contains multiple tokens, every token in the comarison string must have a prefix match in the indexed property. For example:

  • Restricting for "sea" would match "search"

  • Restricting for "sea" would not match "research"

  • Restricting for "sea" would match "Subject: the deep blue sea"

  • Restricting for "law order" would match "law and order" or "law & order"

  • Restricting for "law and order" would match "I like the show Law and Order."

  • Restricting for "law and order" would not match "above the law"

  • Restricting for "sea creatures" would match "Nova special on sea creatures"

  • Restricting for "sea creatures" would match "sealife creatures"

  • Restricting for "sea creatures" would not match "undersea creatures"

Using the same example in Equivalence Matching, assume that the folder you are searching contains items with the following subjects:

  • Question

  • Questionable

  • Unquestionable

  • RE: Question

  • The big question

The following ci_startswith restriction:

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas:httpmail:subject" & Chr(34) _
& " ci_startswith 'question'"

will return the following results:

  • Question

  • Questionable

  • RE: Question

  • The big question

ci_phrasematch

The syntax of ci_phrasematch is as follows:

Copy code Copy code
<PropertySchemaName> ci_phrasematch <ComparisonString>

where PropertySchemaName is a valid name of a property referenced by namespace and ComparisonString is the string used for comparison.

ci_phrasematch performs a search to match phrases. It uses tokens (characters, word, or words) in the comparison string to match entire words in the string value of the indexed property. Tokens are enclosed in double quotes or parentheses. Each token in the comparison string must have a phrase match, and not a substring or prefix match. If the comparison string contains multiple tokens, every token in the comarison string must have a phrase match. Any word within a multiple word property like Subject or Body can match; it doesn't have to be the first word. For example:

  • Restricting for "cat" would match "cat", "cat box", "black cat"

  • Restricting for "cat" would match "re: cat is out"

  • Restricting for "cat" would not match "catalog", "kittycat"

  • Restricting for "kitty cat" would match "put the kitty cat out"

  • Restricting for "kitty cat" would not match "great kitty catalog"

Using the same example in Equivalence Matching, assume that the folder you are searching contains items with the following subjects:

  • Question

  • Questionable

  • Unquestionable

  • RE: Question

  • The big question

The following ci_phrasematch restriction:

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas:httpmail:subject" & Chr(34) _
& " ci_phrasematch 'question'"

will return the following results:

  • Question

  • RE: Question

  • The big question

like

like performs prefix, substring, or equivalence matching. Tokens (characters, word, or word) are enclosed with the % character in a specific way depending on the type of matching:

  • Copy code Copy code
    like '<token>%'

    provides prefix matching. For example, restricting for

    Copy code Copy code
    like 'cat%'

    would match "cat" and "catalog".

  • Copy code Copy code
    like '%<token>%'

    provides substring matching. For example, restricting for

    Copy code Copy code
    like '%cat%'

    would match "cat", "catalog", "kittycat", "decathalon".

  • Copy code Copy code
    like '<token>'

    provides equivalence matching. For example, restricting for

    Copy code Copy code
    like 'cat'

    would match "cat" and "RE: Cat".

Each token can match any part of a word in the string property. If the comparison string contains multiple tokens, every token in the comparison string must have a substring match. Any word within a multiple word property like Subject or Body can match; it does not have to be the first word.

Using the same example in Equivalence Matching, assume that the folder you are searching contains items with the following subjects:

  • Question

  • Questionable

  • Unquestionable

  • RE: Question

  • The big question

The following like restriction :

Copy code Copy code
criteria = "@SQL=" & Chr(34) _
& "urn:schemas:httpmail:subject" & Chr(34) _
& " like '%question%'"

will return the following results:

  • Question

  • Questionable

  • Unquestionable

  • RE: Question

  • The big question


Filtering Items Using a Variable

 Copy code hover
[image]

Filtering Items Using a Variable
Send feedback

You can use values from variables as part of a filter in Microsoft Jet syntax or DAV Searching and Locating (DASL) syntax. The following example illustrates the use of variables as part of a filter:

Copy code Copy code
fullname = "Dan Wilson"
' This approach uses Chr(34) to delimit the value.
criteria = "[FullName] = " & Chr(34) & fullname _ & Chr(34)
' This approach uses the double quotation mark to delimit the value.
criteria = "[FullName] = """ & fullname & """"
' This approach uses the escaped hexadecimal value of the double quotation mark to delimit the value.
criteria = "[FullName] = "%22" & fullname & "%22""


Filtering Items Using an Integer Comparison

 Copy code hover
[image]

Filtering Items Using an Integer Comparison
Send feedback

You can compare an integer property with an integer value in a filter string using Microsoft Jet syntax or DAV Searching and Locating (DASL) syntax. You can specify the integer value with or without quotation marks as delimiters. The following three filter strings filter on the condition that the Importance value is high:

Copy code Copy code
criteria = "[Importance] = 2"

If you want to use a value from an integer enumeration, convert the value to a string and append it to the filter string. The following filters are equivalent and test for items with importance set to high:

Copy code Copy code
criteria = "[Importance] = " _ & CStr(Outlook.OlImportance.olImportanceHigh)

criteria = "@SQL=" & Chr(34) & "urn:schemas:httpmail:importance" _ & Chr(34) & " = 2"


Filtering Items Using Comparison and Logical Operators

 Copy code hover
[image]

Filtering Items Using Comparison and Logical Operators
Send feedback

Comparison Operators

You can use the following comparison operators in filter strings using Microsoft Jet syntax or DAV Searching and Locating (DASL) syntax:

  • <

    Performs a less-than comparison.

  • >

    Performs a greater-than comparison.

  • <=

    Performs a less-than-or-equal-to comparison.

  • >=

    Performs a greater-than-or-equal-to comparison.

  • <>

    Performs a not-equal-to comparison.

  • =

    Performs a equal-to comparison.

Logical Operators

You can use the logical operators And, Not, Or in filter strings in Jet or DASL syntax. The order of precedence of these operators, from the highest to the lowest, is: Not, And, Or. You can use parentheses to indicate specific precedence in a filter. Logical operators are case-insensitive.

  • Not

    Performs a logical NOT on the condition. The following code retrieves all contacts whose first name is Jane and who do not work at Microsoft.

    Copy code Copy code
    criteria = _ "[FirstName] = 'Jane' And Not([CompanyName] = 'Microsoft')"

  • And

    Performs a logical AND on the condition. The following code retrieves all contacts who work at Microsoft and whose first name is Mary.

    Copy code Copy code
    criteria = _ "[FirstName] = 'Mary' And [CompanyName] = 'Microsoft'"

  • Or

    Performs a logical OR on the condition. The following code returns all contact items that have either a first name of Peter or Paul.

    Copy code Copy code
    criteria = "[FirstName] = 'Peter' Or [FirstName] = 'Paul'"


Filtering Items Using Query Keywords

 Copy code hover
[image]

Filtering Items Using Query Keywords
Send feedback

You can use the following query keywords only in DAV Searching and Locating (DASL) queries. Keywords are case-insensitive. Microsoft Jet does not support any query keywords.

  • ci_startwith and ci_phrasematch

    These content indexer keywords provide prefix and phrase matching respectively for items in an indexed store. For example, the following DASL query creates a filter for last name starting with "Smith" and uses a content indexer keyword to return the results:

    Copy code Copy code
    criteria = "@SQL=" & Chr(34) _
& "urn:schemas:contacts:sn" & Chr(34) _
& " ci_startswith 'Smith'"

    The following DASL query creates a filter for last name being exactly "Smith" and uses a content indexer keyword to return the results:

    Copy code Copy code
    criteria = "@SQL=" & Chr(34) _
& "urn:schemas:contacts:sn" & Chr(34) _
& " ci_phrasematch 'Smith'"

  • Is Null

    Evaluates if a property is null. Returns True if the property is null and False if the property is not null.

    Is Null operations are useful to determine if a date property has been set or if a string property is empty. If the date is null, the local time value of the date will be equal to 1/1/4501.

    The syntax of Is Null is as follows:

    Copy code Copy code
    [PropertyName] IS NULL

    where PropertyName is the name of a property referenced by namespace.

    You can combine the Is Null keywords with the Not operator to evaluate if a property is not null.

    The following DASL query retrieves all contacts where the custom property Order Date is not null and the CompanyName property is exactly Microsoft:

    Copy code Copy code
    criteria = "@SQL=" & "(NOT(" _
& Chr(34) & "http://schemas.microsoft.com/mapi/string/" _
& "{00020329-0000-0000-C000-000000000046}/Order%20Date" & Chr(34) _
& " IS NULL) AND " _ & Chr(34) & "urn:schemas-microsoft-com:office:office#Company"
& Chr(34) _ & " = 'Microsoft')"


Searching

 Copy code hover
[image]

Searching
Send feedback

In this section

  • Searching Items


Searching Items

 Copy code hover
[image]

Searching Items
Send feedback

This topic describes the entry points to search items in folders and access search results.

Application.AdvancedSearch

Explorer.Search

Search.GetTable

Purpose

Provides programmatic search on items in a specified folder based on a filter.

Performs a programmatic content indexer search that is analogous to a user executing a search from the Outlook user interface.

Provides an efficient way to access items (in a Table) returned by a prior Application.AdvancedSearch. This entry point does not carry out a separate search.

Scope of Search

Folder specified as a search parameter.

Determined by the parameter SearchAllItems. If SearchAllItems is True, the method will search across all folders that have the same folder type as the current folder (specified by the DefaultItemType property of Explorer.CurrentFolder) and all stores that have been selected for search in the Search Options dialog box. If SearchAllItems is False, the method will search only the folder represented by Explorer.CurrentFolder.

Since the Search object is returned from a prior Application.AdvancedSearch operation, the scope of the search associated with Search.GetTable is that of the prior Application.AdvancedSearch.

Search Filter

In DAV Searching and Locating (DASL) syntax.

Any valid keywords that are supported by Outlook search in the user interface. Search phrases are delimited by double quotes and can be concatenated to form a single search filter string.

Similar to the scope, the filter is of the search associated with Search.GetTable is the filter parameter of the prior Application.AdvancedSearch.

Search Completion

Use the AdvancedSearchComplete event to determine when a given search has completed.

Does not provide a callback to indicate search completion.

Search is completed in the prior Application.AdvancedSearch. Search.GetTable only returns the search results.

Search Results

Access the search results by one of these means:

  • Search.Results contains the search results as a Results collection. Each item in the collection contain the full set of item properties.

  • Search.Save saves the results to a search folder.

  • Search.GetTable also returns the same set of items as in the Results collection, but each item will contain only a default set of properties and therefore generally offers better performance.

Search results are displayed in the Explorer for the current folder. To remove any search results in the Explorer, call Explorer.ClearSearch.

Search results are returned in a Table which includes the same set of items returned from the prior Application.AdvancedSearch. Since the Table only includes a limited set of properties per item, this is generally a more efficient way to access search results. To include properties other than the default in the search results, use Columns.Add to get an updated Table. Since the item's Entry ID is one of the returned properties, you can also use GetItemFromID to obtain the item object, and access other item properties like Body and AutoResolvedWinner that are not supported by the Table object for performance reasons.


How To

 Copy code hover
[image]

How To
Send feedback

In this section

  • How to: Access the Values of a Multi-valued Property in a Table

  • How to: Use the Table Object to Performantly Enumerate Filtered Items in a Folder

  • How to: Filter the Body of a Mail Item

  • How to: Filter Items that Do Not Have Categories

  • How to: Search the Inbox for Items with Subject Containing "Office"

  • How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period

  • How to: Search the Calendar for Appointments Within a Date Range that Contain a Specific Word in the Subject

  • How to: Search and Obtain Items in an Aggregated View (Outlook)


How to: Access the Values of a Multi-valued Property in a Table

 Copy code hover
[image]

How to: Access the Values of a Multi-valued Property in a Table
Send feedback

Generally, if a multi-valued property is added to a Table using its explicit built-in name, the format of the values of the property is a comma-delimited string. If the multi-valued property is added to the Table using a reference by namespace, the format of the values of the property is a variant array.

The following code sample adds the multi-valued Categories property to a Table using a name that references its namespace, urn:schemas-microsoft-com:office:office#Keywords. To obtain the values for the Categories column for each row in the Table, assign

Copy code Copy code
oRow("urn:schemas-microsoft-com:office:office#Keywords")

to a variant, and enumerate the elements of the variant array. Note that for an item that has not been assigned any categories, to a variant, and enumerate the elements of the variant array. Note that for an item that has not been assigned any categories,

Copy code Copy code
oRow("urn:schemas-microsoft-com:office:office#Keywords")

returns an Empty value.

Copy code Copy code
Sub TableCategories()
    Dim oT As Outlook.Table
    Dim oRow As Outlook.Row
    Dim varCat
    Dim j As Integer
    Dim strCategories As String

    Set oT = Application.ActiveExplorer.CurrentFolder.GetTable()
    oT.Columns.Add ("urn:schemas-microsoft-com:office:office#Keywords")
    oT.Sort "LastModificationTime", True
    Do Until oT.EndOfTable
        Set oRow = oT.GetNextRow
        'Obtain any values of the Categories property
        varCat = oRow("urn:schemas-microsoft-com:office:office#Keywords")
        If Not (IsEmpty(varCat)) Then
            'Form a string out of the item's categories
            For j = 0 To UBound(varCat)
                strCategories = strCategories & (varCat(j)) & ", "
            Next
            'Remove last trailing ", "
            strCategories = Left(strCategories, Len(strCategories) - 2)
        Else
            'The item does not have any categories
            strCategories = ""
        End If
        Debug.Print ("Subject: " _
           & oRow("Subject") & vbCrLf & "Categories: ") & strCategories & vbCrLf
    Loop
End Sub


How to: Use the Table Object to Performantly Enumerate Filtered Items in a Folder

 Copy code hover
[image]

How to: Use the Table Object to Performantly Enumerate Filtered Items in a Folder
Send feedback

The code sample in this topic uses the Table object to enumerate a filtered set of items in the Inbox that were last modified after May 1, 2005. For each of these items, the code sample prints these values: the subject, the time that the item was last modified, and whether the item is hidden. The procedure is as follows:

  1. The sample defines a filter based on the value of the LastModificationTime property of mail items.

  2. It applies the filter to Folder.GetTable and obtains a Table of a subset of mail items in the Inbox that satisfies the filter.

    Note Note

    The returned table contains a default set of properties for each of the filtered items: EntryID, Subject, CreationTime, LastModificationTime, and MessageClass.

  3. It then uses Columns.RemoveAll and Columns.Add to update the Table with the actually desired properties: Subject, LastModificationTime, and the hidden attribute (PidTagAttributeHidden). It specifies properties with their explicit built-in names if they exist (for example, Subject, LastModificationTime), and only when they don't, it references the properties by their namespaces (for example, the hidden attribute of a mail item).

    Note Note

    The Table objects returned from Folder.GetTable in Step 2 and Columns.Add in Step 3 contain different property values but for the same set of filtered items in the Inbox.

  4. Lastly, it uses Table.GetNextRow to enumerate the filtered items (until Table.EndOfTable becomes true), displaying the values of the three desired properties for each item.

Copy code Copy code
Sub DemoTable()
 'Declarations
 Dim Filter As String
 Dim oRow As Outlook.Row
 Dim oTable As Outlook.Table
 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005
 Filter = "[LastModificationTime] > '5/1/2005'"
 'Restrict with Filter
 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set
 oTable.Columns.RemoveAll
 'Specify desired properties
 With oTable.Columns
 .Add ("Subject")
 .Add ("LastModificationTime")
 'PidTagAttributeHidden referenced by the MAPI proptag namespace
 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")
 End With

 'Enumerate the table using test for EndOfTable
 Do Until (oTable.EndOfTable)
 Set oRow = oTable.GetNextRow()
 Debug.Print (oRow("Subject"))
 Debug.Print (oRow("LastModificationTime"))
 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))
 Loop
End Sub


How to: Filter the Body of a Mail Item

 Copy code hover
[image]

How to: Filter the Body of a Mail Item
Send feedback

The code sample in this topic shows how to use content indexing in a DASL query to search for mail items that contain a specific word in the body.

The code sample sets up a DASL filter on the property urn:schemas:httpmail:textdescription (the Body property referenced by its DAV namespace) and uses the content indexer keyword ci_phrasematch to search for the word "office" in the body. It then applies the filter to items in the current folder. To access the filter results, it uses the Table object and prints the subject line of each item.

Notice that this sample prints the subject of each row in the returned Table; the Subject property is included in a Table returned by a search on any folder. But generally, a folder in Outlook can contain heterogenous items and is not confined to a single item type. If you want to access a property that is specific to an item type, use Columns.Add to include that property and update the Table, and for each row returned in the Table, check the message type of the item before accessing the property.

Note Note

Content indexing in a DASL query provides better performance than the like keyword. However, you can filter only on the text of the item body; if the body contains HTML tags, as in an HTML-formatted mail item, the tags will not be filtered. The match is not case-sensitive, so for example, any item containing "Office" or "office" in the body will be returned by Folder.GetTable. You can also return up to the first 255 characters of the body in a column of a Table, by adding the column (denoted by urn:schemas:httpmail:textdescription) to the Table. You cannot use a Jet query to filter on the Body property.

Copy code Copy code
Sub RestrictUsingBody()
 Dim strFilter As String
 Dim oT As Table
 Dim oRow as Row

 'Create DASL query for Body using content indexing phrase match for 'office'
 strFilter = "@SQL=" & Chr(34) & "urn:schemas:httpmail:textdescription" _
 & Chr(34) & " ci_phrasematch 'office'"
 'Obtain Table by applying the filter on the current folder
 Set oT = Application.ActiveExplorer.CurrentFolder.GetTable(strFilter)
 'Print subject line of each mail item in current folder that contains 'office' in the body
 Do Until oT.EndOfTable
 Set oRow = oT.GetNextRow
 Debug.Print oRow("Subject")
 Loop
End Sub


How to: Filter Items that Do Not Have Categories

 Copy code hover
[image]

How to: Filter Items that Do Not Have Categories
Send feedback

This topic shows a code sample that uses a DAV Searching and Locating (DASL) query to filter items in the current folder that do not have any category assigned to them. Note that filtering items with an empty string in their categories requires a DASL query; the Microsoft Jet syntax does not support such filters.

When filtering an empty string with a DASL query, you can use the Is Null keyword. Is Null operations are useful to determine if a string property is empty or if a date property has been set. For more information, see Filtering Items Using Query Keywords.

The code sample sets up a DASL filter on the Categories property, which in the DASL query is expressed in the Office namespace as urn:schemas-microsoft-com:office:office#Keywords. The filter compares the value of the Categories property with an emptry string using the Is Null keyword. The code sample then applies the filer to items in the current folder. It then prints the number of items in the current folder that have been found to have no categories.

VBA Copy code Copy code
Sub NullCategoryRestriction()
 Dim oFolder As Outlook.Folder
 Dim oItems As Outlook.Items
 Dim Filter As String

 'DASL Filter can test for null property.
 'This will return all items that have no category.
 Filter = "@SQL=" & Chr(34) & _
 "urn:schemas-microsoft-com:office:office#Keywords" & _
 Chr(34) & " is null"
 Set oFolder = Application.ActiveExplorer.CurrentFolder
 Set oItems = oFolder.Items.Restrict(Filter)
 Debug.Print oItems.Count
End Sub


How to: Search the Inbox for Items with Subject Containing "Office"

 Copy code hover
[image]

How to: Search the Inbox for Items with Subject Containing "Office"
Send feedback

This topic shows two code samples that use DASL queries to search for items in the Inbox that contain "Office" in the subject line. The first code sample uses Folder.GetTable and the second uses Application.AdvancedSearch to apply the DASL query.

Each of the code samples uses the content indexer keyword ci_phrasematch in a DASL filter on the property http://schemas.microsoft.com/mapi/proptag/0x0037001E (the Subject property referenced by the MAPI ID namespace) to search for the word "office" in the subject. It applies the filter to items in the Inbox (by using Folder.GetTable or Application.AdvancedSearch), and prints the subject line of each item returned from the search.

Note Note

The match is not case-sensitive so any item containing "Office" or "office" in the subject will be returned by Folder.GetTable or Application.AdvancedSearch. Notice that each sample prints the subject of each row in the resultant Table. It chooses to use the lighter weight Table object instead of the Search.Results object for better performance. The Subject property is included in a Table returned by a search on any folder. But like any folder in Outlook, the Inbox can contain heterogenous items and is not confined to mail items. If you want to access a property that is specific to a certain item type in the Inbox, use Columns.Add to include that property and update the Table, and for each row returned in the Table, check the message type of the item before accessing the property.

This code sample uses Folder.GetTable to do the search:

VBA Copy code Copy code
Sub RestrictTableForInbox()
    Dim oT As Outlook.Table
    Dim strFilter As String
    Dim oRow As Outlook.Row

    'Construct filter for Subject containing 'Office'
    Const PropTag  As String = "http://schemas.microsoft.com/mapi/proptag/"
    strFilter = "@SQL=" & Chr(34) & PropTag  _
        & "0x0037001E" & Chr(34) & " ci_phrasematch 'Office'"

    'Do search and obtain Table on Inbox
    Set oT = Application.Session.GetDefaultFolder(olFolderInbox).GetTable(strFilter)

    'Print Subject of each returned item
    Do Until oT.EndOfTable
        Set oRow = oT.GetNextRow
        Debug.Print oRow("Subject")
    Loop
End Sub

This code sample uses Application.AdvancedSearch to do the search:

VBA Copy code Copy code
Public blnSearchComp As Boolean
Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)
    MsgBox "The AdvancedSearchComplete Event fired"
    blnSearchComp = True
End Sub

Sub TestSearchWithTable()
    Dim oSearch As Search
    Dim oTable As Table
    Dim strQuery As String
    Dim oRow As Row

    blnSearchComp = False

    'Construct filter. 0x0037001E represents Subject
    strQuery = _
        "http://schemas.microsoft.com/mapi/proptag/0x0037001E" & _
        " ci_phrasematch 'Office'"

    'Do search
    Set oSearch = _
        Application.AdvancedSearch("Inbox", strQuery, False, "Test")
    While blnSearchComp = False
        DoEvents
    Wend

    'Obtain Table
    Set oTable = oSearch.GetTable

    'Print Subject of each returned item
    Do Until oTable.EndOfTable
        Set oRow = oTable.GetNextRow
        Debug.Print oRow("Subject")
    Loop
End Sub


How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period

 Copy code hover
[image]

How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period
Send feedback

This topic shows a code sample in Visual Basic for Applications (VBA) that uses a Jet query to search for appointments in the default calendar folder that occur in a given period of time with a specific start time and a specific end time. The query returns appointments that occur entirely within that period, starting on or after the start time and ending on or before the end time. The query also returns appointments that overlap with the period, including those that start before the period starts but end within the period, those that start within the period but end after the period ends, and those that start before the start time and end after the end time, overlapping with the entire time period. The returned results include recurring appointments.

You may think that querying for appointments that start on or after the start date, and end on or before the end date, should be the approach. This would translate to the following query:

Copy code Copy code
[Start] >= myStart AND [End] <= myEnd

However, to reliably find all appointments that occur entirely within the time period and those that overlap with the time period, you need to use a query that looks for appointments that start on or before the end time of the period, and end on or after the start time of the time period. This would translate to the following query:

Copy code Copy code
[Start] <= myEnd AND [End] >= myStart

Taking into consideration the appointments that overlap with the given time period is useful if you want to clear your calendar of all appointments that happen during that time period. In this case, querying only for appointments that start and end within the specified period would not be sufficient.

The FindApptsInTimeFrame function in the code sample first defines the time period to query, assigning the start time, myStart, as 12:00am on the current system date, and the end time, myEnd, as five days after the start time. It obtains all the items in the default calendar folder. To include recurrent appointments in the query, it sets Items.IncludeRecurrences to True and then sorts the items by the AppointmentItem.Start property. It then builds the query for all appointments that begin on or before myEnd, and end on or after myStart. It then applies the query to items in the default calendar folder, using the Items.Restrict method, and then prints the start time of all the returned appointments.

VBA Copy code Copy code
Sub FindApptsInTimeFrame()
    Dim myStart As Date
    Dim myEnd As Date
    Dim oCalendar As Outlook.folder
    Dim oItems As Outlook.items
    Dim oResItems As Outlook.items
    Dim oAppt As Outlook.AppointmentItem
    Dim strRestriction As String

    myStart = Date
    myEnd = DateAdd("d", 5, myStart)
    Debug.Print "Start:", myStart
    Debug.Print "End:", myEnd

    Set oCalendar = Application.session.GetDefaultFolder(olFolderCalendar)
    Set oItems = oCalendar.items

    oItems.IncludeRecurrences = True
    oItems.Sort "[Start]"

    strRestriction = "[Start] <= '" & Format$(myEnd, "mm/dd/yyyy hh:mm AMPM") _
    & "' AND [End] >= '" & Format(myStart, "mm/dd/yyyy hh:mm AMPM") & "'"
    Debug.Print strRestriction

    'Restrict the Items collection
    Set oResItems = oItems.Restrict(strRestriction)

    For Each oAppt In oResItems
        Debug.Print oAppt.Start, oAppt.Subject
    Next
End Sub


How to: Search the Calendar for Appointments Within a Date Range that Contain a Specific Word in the Subject

 Copy code hover
[image]

How to: Search the Calendar for Appointments Within a Date Range that Contain a Specific Word in the Subject
Send feedback

This topic shows a code sample in Visual Basic for Applications (VBA) that finds appointments in the default calendar that occur strictly within the next thirty days and that contain the word "team" in the subject. The returned results include recurrent appointments.

The FindAppts function in the code sample carries out the search using two different queries, first searching for appointments including recurrent appointments that start and end within the date range, then searching among appointments that meet the date range criteria that have "team" in the subject. The following is an outline of the steps:

  1. FindAppts first defines the time period to query, assigning the start time, myStart, as 12:00am on the current system date, and the end time, myEnd, as thirty days after the start time.

  2. It obtains all the items in the default calendar folder.

  3. To include all appointment items strictly within the date range including recurrent appointments, it sets Items.IncludeRecurrences to True and then sorts the items by the AppointmentItem.Start property.

  4. It builds the first query for all appointments that begin on or after myStart, and end on or before myEnd. This query is a Jet query.

  5. It applies the query to items in the default calendar folder, using the Items.Restrict method.

  6. It builds the second query for the appointment subject containing the word "team". It uses the like keyword for substring matching in a DAV Searching and Locating (DASL) query.

  7. It applies the second query to the set of appointments that meet the date range criteria, returned from the first query.

  8. It sorts and prints the start time of all the final returned appointments.

Note that if you want to include appointment items that overlap and do not fall strictly within the specific date range, you should change the first query to one that have appointments begin on or before myEnd, and end on or after myStart. For more information, see How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period.

VBA Copy code Copy code
Sub FindAppts()

    Dim myStart As Date
    Dim myEnd As Date
    Dim oCalendar As Outlook.folder
    Dim oItems As Outlook.items
    Dim oItemsInDateRange As Outlook.items
    Dim oFinalItems As Outlook.items
    Dim oAppt As Outlook.AppointmentItem
    Dim strRestriction As String

    myStart = Date
    myEnd = DateAdd("d", 30, myStart)

    Debug.Print "Start:", myStart
    Debug.Print "End:", myEnd

    'Construct filter for the next 30-day date range
    strRestriction = "[Start] >= '" & _
    Format$(myStart, "mm/dd/yyyy hh:mm AMPM") _
    & "' AND [End] <= '" & _
    Format$(myEnd, "mm/dd/yyyy hh:mm AMPM") & "'"
    'Check the restriction string
    Debug.Print strRestriction
    Set oCalendar = Application.session.GetDefaultFolder(olFolderCalendar)
    Set oItems = oCalendar.items
    oItems.IncludeRecurrences = True
    oItems.Sort "[Start]"
    'Restrict the Items collection for the 30-day date range
    Set oItemsInDateRange = oItems.Restrict(strRestriction)
    'Construct filter for Subject containing 'team'
    Const PropTag  As String = "http://schemas.microsoft.com/mapi/proptag/"
    strRestriction = "@SQL=" & Chr(34) & PropTag _
        & "0x0037001E" & Chr(34) & " like '%team%'"
    'Restrict the last set of filtered items for the subject
    Set oFinalItems = oItemsInDateRange.Restrict(strRestriction)
    'Sort and Debug.Print final results
    oFinalItems.Sort "[Start]"
    For Each oAppt In oFinalItems
        Debug.Print oAppt.Start, oAppt.Subject
    Next
End Sub


How to: Search and Obtain Items in an Aggregated View (Outlook)

 Copy code hover
[image]

How to: Search and Obtain Items in an Aggregated View (Outlook)
Send feedback

The GetTable method of the TableView object can return a Table object that contains items from one or more folders in the same store or spanning over multiple stores, in an aggregated view. This is particularly useful when you want to access items returned from a search; for example, a search on all mail items in a store. This topic shows an example of how to use Instant Search to search for all items received from the manager of the current user that are marked important, and then display the subject of each search result.

The following code sample contains the GetItemsInView method. GetItemsInView first makes a few checks to see if the current user of the Outlook session uses the Microsoft Exchange Server, whether the current user has a manager, and whether Instant Search is operational in the default store of the session. Because the eventual search relies on the Search method of the Explorer object, and the eventual result display uses the GetTable method, which is based on the current view of the current folder of the active explorer, GetItemsInView creates an explorer, displays the Inbox in this explorer, and sets up the search by using this Explorer object. GetItemsInView specifies the search criteria as important items from the current user's manager and the search scope as all folders of the MailItem item type. After GetItemsInView calls the Explorer.Search method, any search results are displayed in this explorer, including items from other folders and stores that meet the search criteria. GetItemsInView obtains a TableView object that contains this explorer view of the search results. By using the GetTable method of this TableView object, GetItemsInView then obtains a Table object that contains the aggregated items returned from the search. Finally GetItemsInView displays the subject column of each row of the Table object that represents an item in the search results.

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void GetItemsInView()
{
    Outlook.AddressEntry currentUser =
        Application.Session.CurrentUser.AddressEntry;

    // Check if the current user uses the Exchange Server.
    if (currentUser.Type == "EX")
    {
        Outlook.ExchangeUser manager =
            currentUser.GetExchangeUser().GetExchangeUserManager();

        // Check if the current user has a manager.
        if (manager != null)
        {
            string managerName = manager.Name;

            // Check if Instant Search is enabled and operational in the default store.
            if (Application.Session.DefaultStore.IsInstantSearchEnabled)
            {
                Outlook.Folder inbox =
                    Application.Session.GetDefaultFolder(
                    Outlook.OlDefaultFolders.olFolderInbox);

                // Create a new explorer to display the Inbox as
                // the current folder.
                Outlook.Explorer explorer =
                    Application.Explorers.Add(inbox,
                    Outlook.OlFolderDisplayMode.olFolderDisplayNormal);

                // Make the new explorer visible.
                explorer.Display;

                // Search for items from the manager marked important,
                // from all folders of the same item type as the current folder,
                // which is the MailItem item type.
                string searchFor =
                    "from:" + "\"" + managerName
                    + "\"" + " importance:high";
                explorer.Search(searchFor,
                    Outlook.OlSearchScope.olSearchScopeAllFolders);

                // Any search results are displayed in that new explorer
                // in an aggregated table view.
                Outlook.TableView tableView =
                    explorer.CurrentView as Outlook.TableView;

                // Use GetTable of that table view to obtain items in that
                // aggregated view in a Table object.
                Outlook.Table table = tableView.GetTable();
                while (!table.EndOfTable)
                {
                    // Then display each row in the Table object
                    // that represents an item in the search results.
                    Outlook.Row nextRow = table.GetNextRow();
                    Debug.WriteLine(nextRow["Subject"]);
                }
            }
        }
    }
}


Security (Outlook)

 Copy code hover
[image]

Security (Outlook)
Send feedback

In this section

  • Security Behavior of the Outlook Object Model

  • Outlook Object Model Security Warnings

  • Protected Properties and Methods


Security Behavior of the Outlook Object Model

 Copy code hover
[image]

Security Behavior of the Outlook Object Model
Send feedback

The Outlook object model includes entry points to access Outlook data, save data to specified locations, and send e-mails. These entry points are available to legitimate and malicious application developers alike. Versions of Outlook 98 and Outlook 2000 applied with the Outlook E-mail Security Update, and all subsequent versions starting from Outlook 2000 SP2 use the Object Model Guard to help protect users. The Object Model Guard warns users and prompts users for confirmation when untrusted applications attempt to use the object model to obtain e-mail address information, store data outside of Outlook, execute certain actions, and send e-mail messages. Although the Object Model Guard succeeds in identifying and protecting these entry points, two main issues exist that render the Object Model Guard rather unpractical:

  • The default circumstances that applications invoke the Object Model Guard in earlier versions of Outlook can result in excessive security prompting for legitimate applications.

  • The limitations of COM and Windows in identifying the specific application that is invoking the Object Model Guard have made it difficult for users to respond to the security prompts with certainty.

For more information on the various security prompts of the Object Model Guard, see Outlook Object Model Security Warnings. For more information on the protected object model entry points, see Protected Properties and Methods.

Default Security Behavior

Versions of Outlook prior to Outlook 2007 have relied on the Object Model Guard to protect Outlook address book data and avoid untrusted applications from sending e-mail. Although Outlook continues to use the Object Model Guard to provide similar protection, it has defined new default circumstances when the Object Model Guard generates warnings, reducing excessive security warnings under appropriate conditions while maintaining a reasonable degree of security for Outlook clients.

In-Process Add-ins

In-process Outlook add-ins run in the process of the host Outlook program. In-process COM add-ins in Outlook are trusted by default. These COM add-ins are registered on the list of trusted applications by the client computer's administrator, and must use the Application object that is passed to the OnConnection event of the add-in. Note that if you create a new Application object by using the CreateObject method, that object and any of its subordinate objects, properties, and methods are not trusted.

For more information about the OnConnection event, see the IDTExtensibility2 documentation on MSDN.

Cross-Process Add-ins

By default, Outlook relies on the existence and the status of an appropriate antivirus software on the client computer to trust cross-process applications: if Outlook detects that antivirus software is running with an acceptable status, Outlook will disable security warnings for the end user. All cross-process COM callers and add-ins will run without security warnings if all of the following conditions hold:

  • The client computer is running Windows XP Service Pack 2 (SP2), Windows Vista, or a later version of Windows, and Windows Security Center (WSC) indicates that antivirus software on the computer is in a "Good" health status.

  • The antivirus software installed on the client computer is designed for Windows XP SP2, Windows Vista, or later.

  • Outlook is configured on the client computer in one of the following ways:

    • Uses the default Outlook security settings (that is, no Group Policy set up)

    • Uses security settings defined by Group Policy but does not have programmatic access policy applied

    • Uses security settings defined by Group Policy which is set to warn when the antivirus software is inactive or out of date

For more information, see the "Code Security Changes in Microsoft Office Outlook 2007" article on MSDN.

Security Options

Windows Group Policy

Administrators can use the Trust Center in Outlook to change the default behavior. To access the Trust Center, select Tools and then Trust Center. In the Trust Center, click Programmatic Access. The Programmatic Access Security dialog provides options other than the default behavior.

The three settings in the Programmatic Access Security dialog are:

  • Warn me about suspicious activity when my antivirus software is inactive or out-of-date (recommended) This setting is the default, and implements the behavior described above. This is the recommended setting for all users.

  • Always warn me about suspicious activity This setting will revert Outlook to behave like Outlook 2003, where cross-process COM callers and untrusted add-ins will invoke security warnings.

  • Never warn me about suspicious activity (not recommended) This setting will never show security warnings and the Object Model Guard will be disabled. This setting should only be used in controlled environments where the risk of malicious code running on the computer is low.

These settings are only available if the current user is an administrator on the computer. Non-administrator users can see the current setting but will not be able to change it. Programmatic Access settings can also be controlled through Group Policy. For more information on configuring Outlook settings with Group Policy, see the Office Resource Kit Web site.

Security Form in Exchange Public Folder

Administrators can configure Outlook to locate the Outlook security form in a public folder. In this case, Outlook will not leverage the status of antivirus software and will by default only trust add-ins listed in the security form. There will only be three prompt behaviors: prompt user, never prompt and automatically allow, and never prompt and automatically deny.

To take advantage of the new code security behavior based on the status of antivirus software, administrators must use either the default Outlook security settings or configure Outlook to use Group Policy settings to override this behavior.


Outlook Object Model Security Warnings

 Copy code hover
[image]

Outlook Object Model Security Warnings
Send feedback

Subject to how Outlook has been configured to trust applications on a client computer, an application that uses the Outlook object model to access certain data or execute certain actions can invoke security warnings. Depending on the type of information or action that the program was attempting to access or execute, there are three different security prompts that applications can invoke through the Object Model Guard: the address book warning, send message warning, and execute action warning. This topic describes each of these security warnings. For more information on the default Outlook security behavior and security configuration options, see Security Behavior of the Outlook Object Model. For more information on the entry points in the object model that can trigger security warnings, see Protected Properties and Methods.

Address Book Warning

This warning is the most common security warning that is invoked when an untrusted application accesses Outlook data. Entry points that are identified with the "Address Book" prompt type in the topic Protected Properties and Methods can generate this warning.

This warning enables the user to allow or deny the action. The user can also choose to allow access to the address book for a period of time indicated in the drop-down box.

If the user clicks Deny, Outlook immediately blocks the call that invokes the warning and returns MAPI_E_NOT_SUPPORTED. Outlook does not return any data for the call. If the program does not properly handle the error, it might crash.

If the user clicks Allow without selecting the Allow access for check box, only the call that generated the warning will be allowed. Additional calls on the same line or calls for objects that derive from the blocked call may generate their own security warnings.

If the user clicks Allow after selecting the Allow access for check box, the call that generated the prompt, as well as future calls, will be allowed for the duration that the user has selected. During this time period, all callers to the object model, and not just the program that originally invoked the security warning, are approved for address-book access. After this time period expires, security warnings may reappear.

Send Message Warning

This warning is invoked when an untrusted solution attempts to send an item programmatically. This dialog box has a built-in timer that prevents untrusted add-ins from sending messages rapidly and automatically. The user must wait five seconds before clicking Allow.

If the user clicks Deny, Outlook blocks the call that invoked the warning and returns the MAPI_E_NOT_SUPPORTED error. Subsequent calls to send messages programmatically will invoke additional warnings.

If the user clicks Allow, the call that invoked the warning, and only that call, is allowed. Subsequent calls from an untrusted solution to send messages programmatically will continue to generate warnings.

Execute Action Warning

This warning is invoked when an untrusted solution executes a custom action from the Actions collection. Outlook displays a message similar to the previous warning, indicating that an action is being executed.

If the user clicks Deny, Outlook blocks the call to the Execute method for that action and returns the MAPI_E_NOT_SUPPORTED error.

If the user clicks Allow, the call that invoked the warning, and only that call, is allowed. Subsequent calls from an untrusted solution to execute an action will continue to invoke warnings.


Protected Properties and Methods

 Copy code hover
[image]

Protected Properties and Methods
Send feedback

This topic lists the properties and methods in the Outlook object model that are protected by the Object Model Guard. If untrusted code performs a get on these properties or uses these methods, under default conditions for how Outlook is set up, it will invoke a security warning. The user will then have to verify and respond to the warning in order to proceed.

There are three security prompts that an untrusted application can possibly invoke, depending on the protected property or method that the application uses:

  • The address book warning. This is the most common of the three security prompts. Unless marked otherwise, the properties and methods in the table below generate the address book warning.

  • The execute action warning. Properties and methods superscripted by 1 in the table below denote that they generate the execute action warning.

  • The send message warning. Properties and methods superscripted by 2 in the table below denote that they generate the send message warning.

For more information on security warnings, see Outlook Object Model Security Prompts.

Object | Protected Properties | Protected Methods
Account | CurrentUser, SmtpAddress | GetAddressEntryFromID, GetRecipientFromID
Action |  | Execute1
AddressEntries |  | Add, GetFirst, GetLast, GetNext, GetPrevious, Item
AddressEntry | Address, ID, Manager, Members, Parent, PropertyAccessor | GetExchangeDistributionList, GetExchangeUser, Update
AddressList | AddressEntries, ID, PropertyAccessor |
AddressLists |  | Item
AppointmentItem | Body, OptionalAttendees, Organizer, PropertyAccessor, RequiredAttendees, Resources, RTFBody | Respond2, SaveAs, Send2
Attachment | PropertyAccessor |
CalendarSharing |  | SaveAsICal
Columns |  | Add
ContactItem | Body, Email1Address, Email1AddressType, Email1DisplayName, Email1EntryID, Email2Address, Email2AddressType, Email2DisplayName, Email2EntryID, Email3Address, Email3AddressType, Email3DisplayName, Email3EntryID, IMAddress, NetMeetingAlias, PropertyAccessor, ReferredBy, RTFBody | SaveAs
DistListItem | Body, PropertyAccessor, RTFBody | GetMember, SaveAs
DocumentItem | Body, PropertyAccessor |
ExchangeDistributionList | Address, Alias, ID, Parent, PrimarySmtpAddress, PropertyAccessor | GetExchangeDistributionList, GetExchangeUser, GetMemberOfList, GetExchangeDistributionListMembers, GetOwners, Update
ExchangeUser | Address, Alias, ID, Parent, PrimarySmtpAddress, PropertyAccessor | GetDirectReports, GetExchangeDistributionList, GetExchangeUser, GetExchangeUserManager, GetMemberOfList, Update
Folder | GetCalendarExporter, PropertyAccessor |
Inspector | HTMLEditor, WordEditor |
ItemProperties | Any protected property for an item |
JournalItem | Body, ContactNames, PropertyAccessor | SaveAs
MailItem | Bcc, Body, Cc, HTMLBody, PropertyAccessor, ReceivedByName, ReceivedOnBehalfOfName, Recipients, ReplyRecipientNames, RTFBody, Sender, SenderEmailAddress, SenderEmailType, SenderName, SentOnBehalfOfName, To | SaveAs, Send2
MeetingItem | Body, PropertyAccessor, Recipients, RTFBody, SenderName | SaveAs
MobileItem | Body, HTMLBody, PropertyAccessor, ReceivedByName, Recipients, ReplyRecipientNames, SenderEmailAddress, SenderEmailType, SenderName, SMILBody, To | SaveAs, Send2
NameSpace | CurrentUser, SelectNamesDialog | GetAddressEntryFromID, GetRecipientFromID
NoteItem | Body, PropertyAccessor |
PostItem | Body, HTMLBody, PropertyAccessor, RTFBody, SenderName | SaveAs
Recipient | Any property | Any method
Recipients | Any property | Any method
RemoteItem | Body, PropertyAccessor |
ReportItem | Body, PropertyAccessor |
SelectNamesDialog | Recipients |
SharingItem | Bcc, Body, Cc, HTMLBody, PropertyAccessor, ReceivedByName, ReceivedOnBehalfOfName, ReplyRecipientNames, RTFBody, SenderEmailAddress, SenderEmailType, SenderName, SendOnBehalfOfName, To | Allow, SaveAs, Send2
StorageItem | Body, PropertyAccessor |
Store | PropertyAccessor |
TaskItem | Body, ContactNames, Contacts, Delegator, Owner, PropertyAccessor, RTFBody, StatusOnCompletionRecipients, StatusUpdateRecipients | SaveAs, Send2
TaskRequestAcceptItem | Body, PropertyAccessor, RTFBody |
TaskRequestDeclineItem | Body, PropertyAccessor, RTFBody |
TaskRequestItem | Body, PropertyAccessor, RTFBody |
TaskRequestUpdateItem | Body, PropertyAccessor, RTFBody |
UserProperties |  | Find
UserProperty | Formula |

Note Note

UserProperties.Find is protected if the property being requested is one of the built-in properties that contains address information. If you ask for a custom property or a property like Subject that doesn't contain address information, a prompt will not be displayed.


Sessions (Outlook)

 Copy code hover
[image]

Sessions (Outlook)
Send feedback

In this section

  • How to: Obtain and Log On to an Instance of Outlook


How to: Obtain and Log On to an Instance of Outlook

 Copy code hover
[image]

How to: Obtain and Log On to an Instance of Outlook
Send feedback

This topic shows how to obtain an Application object that represents an active instance of Outlook, if there is one running on the local computer, or to create a new instance of Outlook, log on to the default profile, and return that instance of Outlook.

Helmut Obertanner provided the following code samples. Helmut is a Microsoft Most Valuable Professional with expertise in Microsoft Office development tools in Microsoft Visual Studio and Microsoft Office Outlook. Helmut maintains a professional site at X4Uelectronix.

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code samples contain the GetApplicationObject method of the Sample class, implemented as part of an Outlook add-in project. Each project adds a reference to the Outlook PIA, which is based on the Microsoft.Office.Interop.Outlook namespace.

The GetApplicationObject method uses classes in the .NET Framework Class Library to check and obtain any Outlook process running on the local computer. It first uses the GetProcessesByName method of the Process class in the System.Diagnostics namespace to obtain an array of process components on the local computer that share the process name "OUTLOOK". To check whether the array does contain at least one Outlook process, GetApplicationObject uses Microsoft Language Integrated Query (LINQ). The Enumerable class in the System.Linq namespace provides a set of methods, including the Count method, that implement the IEnumerable(T) generic interface. Because the Array class implements the IEnumerable(T) interface, GetApplicationObject can apply the Count method to the array returned by GetProcessesByName to see whether there is an Outlook process running. If there is, GetApplicationObject uses the GetActiveObject method of the Marshal class in the System.Runtime.InteropServices namespace to obtain that instance of Outlook, and casts that object to an Outlook Application object.

If Outlook is not running on the local computer, GetApplicationObject creates a new instance of Outlook, uses the Logon method of the NameSpace object to log on to the default profile, and returns that new instance of Outlook.

The following is the C# code sample.

C# Copy code Copy code
using System;
using System.Diagnostics;
using System.Linq;
using System.Reflection;
using System.Runtime.InteropServices;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace OutlookAddIn1
{
    class Sample
    {
        Outlook.Application GetApplicationObject()
        {

            Outlook.Application application = null;

            // Check if there is an Outlook process running.
            if (Process.GetProcessesByName("OUTLOOK").Count() > 0)
            {

                // If so, use the GetActiveObject method to obtain the process and cast it to an Application object.
                application = Marshal.GetActiveObject("Outlook.Application") as Outlook.Application;
            }
            else
            {

                // If not, create a new instance of Outlook and log on to the default profile.
                application = new Outlook.Application();
                Outlook.NameSpace nameSpace = application.GetNamespace("MAPI");
                nameSpace.Logon("", "", Missing.Value, Missing.Value);
                nameSpace = null;
            }

            // Return the Outlook Application object.
            return application;
        }

    }
}

The following is the Visual Basic code sample.

Visual Basic Copy code Copy code
Imports System.Diagnostics
Imports System.Linq
Imports System.Reflection
Imports System.Runtime.InteropServices
Imports Outlook = Microsoft.Office.Interop.Outlook

Namespace OutlookAddIn2
    Class Sample

        Function GetApplicationObject() As Outlook.Application

            Dim application As Outlook.Application

            Check if there is an Outlook process running.
            If Process.GetProcessesByName("OUTLOOK").Count() > 0 Then

                ' If so, use the GetActiveObject method to obtain the process and cast it to an Application object.
                application = DirectCast(Marshal.GetActiveObject("Outlook.Application"), Outlook.Application)
            Else

                ' If not, create a new instance of Outlook and log on to the default profile.
                application = New Outlook.Application()
                Dim ns As Outlook.NameSpace = application.GetNamespace("MAPI")
                ns.Logon("", "", Missing.Value, Missing.Value)
                ns = Nothing
            End If

            ' Return the Outlook Application object.
            Return application
        End Function

    End Class
End Namespace


Sharing

 Copy code hover
[image]

Sharing
Send feedback

In this section

  • Sharing Calendars

  • Sharing Online Calendars, RSS Feeds, Microsoft SharePoint Foundation Folders, and Exchange Folders

  • How to: Export a Calendar using Payload Sharing

  • How to: Import Saved Items using OpenSharedItem

  • How to: Send a Sharing Invitation for a Calendar

  • How to: Send a Sharing Invitation for an RSS Feed


Sharing Calendars

 Copy code hover
[image]

Sharing Calendars
Send feedback

You can share calendar information in Microsoft Outlook by either sharing a calendar folder, if you have an Exchange Server account, or by exporting the contents of a calendar folder to an iCalendar calendar (.ics) file. Calendar information can also be shared online using a variety of protocols. For more information about sharing online calendars, see Sharing Online Calendars, RSS Feeds, Microsoft SharePoint Foundation Folders, and Exchange Folders.

Sharing Calendar Folders

Sharing messages are used to either invite or request access to a calendar folder, or to respond to a sharing invitation or request by either allowing or denying access to a calendar folder. To construct a sharing invitation or sharing request, the CreateSharingItem method of the NameSpace object is used to create a SharingItem object. A Folder object reference to the desired calendar folder is used to establish the sharing context for the sharing message.

Note Note

You can only reference the Calendar default folder when creating a sharing request. A single SharingItem object can represent both a sharing invitation and a sharing request, if the Calendar default folder is used as the sharing context.

Sharing responses are automatically created and sent by calling the Allow or Deny methods of a SharingItem which represents a sharing request. Calling the Allow or Deny method allows or denies, respectively, access to the requested folder - the user requesting access need not receive the sharing response.

Exporting Calendar Information

The CalendarSharing object is used to export information from the calendar folder to an iCalendar calendar file, and can also be used to create a MailItem object that not only contains the iCalendar calendar file as an attachment, but also provides the calendar information as formatted HTML within the body of the mail message. The CalendarSharing object provides several properties that can be used to limit the scope and detail of calendar information included in the iCalendar calendar file and in the body of the MailItem.

The GetCalendarExporter method of the Folder object is used to obtain a CalendarSharing object reference for a specified calendar folder. From the CalendarSharing object, you can either use the SaveAsICal method to save an iCalendar calendar file, or you can use the ForwardAsICal method to create a MailItem that contains both formatted calendar information and an iCalendar calendar file.

Once exported, an iCalendar calendar file can be opened by using the OpenSharedFolder method of the NameSpace object.


Sharing Online Calendars, RSS Feeds, Microsoft SharePoint Foundation Folders, and Exchange Folders

 Copy code hover
[image]

Sharing Online Calendars, RSS Feeds, Microsoft SharePoint Foundation Folders, and Exchange Folders
Send feedback

In Microsoft Outlook, you can share and subscribe to a variety of online resources, including:

  • Webcal calendars (webcal://mysite/mycalendar)

  • RSS feeds (feed://mysite/myfeed)

  • SharePoint Foundation folders (stssync://mysite/myfolder)

  • Exchange folders

Calendar information can also be shared either by providing direct access to a calendar folder or by exporting calendar information to an iCalendar calendar (.ics) file. For more information about sharing calendars, see Sharing Calendars.

Sharing Online Resources

For publically available online resources, such as Webcal calendars, RSS feeds, and SharePoint Foundation folders, a sharing message is not required. You can use the OpenSharedFolder method of the NameSpace object to open the online resource. For online resources to which access is required, such as Exchange folders, a sharing request can be created to request access. You can create a sharing request by using the CreateSharingItem method of the NameSpace object to create a SharingItem object. The shared resource (a Folder object reference to the desired Exchange default folder) is used to establish the sharing context for the sharing request.

You can also use a sharing invitation to direct another user to an online resource. To construct a sharing invitation, the CreateSharingItem method of the NameSpace object is used to create a SharingItem object. The shared resource (either a Folder object reference to the desired folder or a string containing the appropriate URI for the online resource) is used to establish the sharing context for the sharing invitation.

Note Note

Sharing requests can be created only for Exchange default folders. To access other Exchange folders, a sharing invitation from the owner of the folder is required.

Sharing Providers

Each type of online resource, such as Webcal calendars, is supported by a corresponding sharing provider. A sharing provider encapsulates the access and interpretation tools for a given online resource type. You can use the SharingProvider and SharingProviderGuid properties of a SharingItem to determine the sharing provider used by a given sharing message.


How to: Export a Calendar using Payload Sharing

 Copy code hover
[image]

How to: Export a Calendar using Payload Sharing
Send feedback

Microsoft Outlook includes the ability to share calendar information with other users by using an iCalendar (.ics) file attached to a MailItem. The CalendarSharing object is used to both generate the iCalendar file from a folder containing calendar items and to generate the MailItem to which the iCalendar file is attached.

This sample uses the CalendarSharing item to share free/busy information for the next seven days with a single recipient:

  1. The sample obtains a Folder object reference for the Calendar default folder for the current user, by using the GetDefaultFolder method of the NameSpace object.

  2. It uses the GetCalendarExporter method of the Folder object to create a CalendarSharing object reference for the folder.

  3. It then sets the following properties on the CalendarSharing object to restrict the range and level of information exported by the object:

    • The CalendarDetail property is set to limit the information for each calendar item to free/busy information only.

    • The StartDate and EndDate properties are set to restrict the calendar items included in the file to the next seven days.

    • The RestrictToWorkingHours property is set to restrict the calendar items to those that fall within working hours.

    • The IncludeAttachments property is set to exclude any attachments for calendar items exported by the object.

    • The IncludePrivateDetails property is set to exclude the details of any private calendar items exported by the object.

  5. It then calles the ForwardAsICal method of the CalendarSharing object to export the calendar items to an iCalendar file and create a MailItem object with the iCalendar file as an attachment. The olCalendarMailFormatDailySchedule constant of the olCalendarMailFormat enumeration is used with the ForwardAsICal method to indicate that the body of the MailItem should contain, in HTML format, free/busy information for the next seven days.

  6. Finally, the Add method for the Recipients collection of the newly created MailItem object is called to add the specified recipient and the Send method is used to send the MailItem.

Copy code Copy code
Public Sub ShareWorkCalendarByPayload()

 Dim oNamespace As NameSpace
 Dim oFolder As Folder
 Dim oCalendarSharing As CalendarSharing
 Dim oMailItem As MailItem

 On Error GoTo ErrRoutine
 ' Get a reference to the Calendar default folder
 Set oNamespace = Application.GetNamespace("MAPI")
 Set oFolder = oNamespace.GetDefaultFolder(olFolderCalendar)

 ' Get a reference to a CalendarSharing object for that
 ' folder.
 Set oCalendarSharing = oFolder.GetCalendarExporter

 ' Set the CalendarSharing object to restrict
 ' the information shared in the iCalendar file.
 With oCalendarSharing
 ' Send free/busy information only.
 .CalendarDetail = olFreeBusyOnly

 ' Send information for the next seven days.
 .startDate = Now
 .endDate = DateAdd("d", 7, Now)

 ' Restrict information to working hours only.
 .RestrictToWorkingHours = True

 ' Exclude attachments and private information.
 .IncludeAttachments = False
 .IncludePrivateDetails = False
 End With

 ' Get the mail item containing the iCalendar file
 ' and calendar information.
 Set oMailItem = oCalendarSharing.ForwardAsICal( _
 olCalendarMailFormatDailySchedule)

 ' Send the mail item to the specified recipient.
 With oMailItem
 .Recipients.Add "someone@example.com"
 .Send
 End With

EndRoutine:
 On Error GoTo 0
 Set oMailItem = Nothing
 Set oCalendarSharing = Nothing
 Set oFolder = Nothing
 Set oNamespace = Nothing
Exit Sub

ErrRoutine:
 Select Case Err.Number
 Case 287 ' &H0000011F
 ' The user denied access to the Address Book.
 ' This error occurs if the code is run by an
 ' untrusted application, and the user chose not to
 ' allow access.
 MsgBox "Access to Outlook was denied by the user.", _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147467259 ' &H80004005
 ' Export failed.
 ' This error typically occurs if the CalendarSharing
 ' method cannot export the calendar information because
 ' of conflicting property settings.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147221233 ' &H8004010F
 ' Operation failed.
 ' This error typically occurs if the GetCalendarExporter method
 ' is called on a folder that doesn't contain calendar items.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case Else
 ' Any other error that may occur.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 End Select

 GoTo EndRoutine
End Sub


How to: Import Saved Items using OpenSharedItem

 Copy code hover
[image]

How to: Import Saved Items using OpenSharedItem
Send feedback

Microsoft Outlook provides the OpenSharedItem method, for the NameSpace object, to open iCalendar appointment (.ics) files, vCard (.vcf) files, and Outlook message (.msg) files and return the Outlook item appropriate for the file. The type of object returned by this method depends on the type of shared item opened, as described in the following table.

Shared item type | Outlook item
iCalendar appointment (.ics) file | AppointmentItem
vCard (.vcf) file | ContactItem
Outlook message (.msg) file | Type corresponds to the type of the item that was saved as the .msg file

Once the shared item is opened, you can then import the item by using the Save method of the returned object to save it to the default folder appropriate to that Outlook item.

This sample opens and imports a vCard file into the Contacts default folder for the current user.

  1. The sample obtains a reference to a NameSpace object, then calls the GetSharedItem method of the NameSpace object to load the vCard file and return a ContactItem reference.

  2. It then calls the Save method of the ContactItem to save it to the Contacts default folder.

  3. Finally, it obtains a Folder object reference to the Contacts default folder for the current user by using the GetDefaultFolder method of the NameSpace object, and then displays the folder.

Copy code Copy code
Public Sub OpenSharedContact()

 Dim oNamespace As NameSpace
 Dim oSharedItem As ContactItem
 Dim oFolder As Folder

 On Error GoTo ErrRoutine

 ' Get a reference to a NameSpace object.
 Set oNamespace = Application.GetNamespace("MAPI")

 ' Open the vCard (.vcf) file containing the shared item.
 Set oSharedItem = oNamespace.OpenSharedItem( _
 "C:/SampleContact.vcf")

 ' Save the item to the Contacts default folder.
 oSharedItem.Save

 ' Get a reference to and display the Contacts default folder.
 Set oFolder = oNamespace.GetDefaultFolder( _
 olFolderContacts)
 oFolder.Display

EndRoutine:
 On Error GoTo 0
 Set oSharedItem = Nothing
 Set oFolder = Nothing
 Set oNamespace = Nothing
Exit Sub

ErrRoutine:
 Select Case Err.Number
 Case 287 ' &H0000011F
 ' This error occurs if the code is run by an
 ' untrusted application, and the user chose not to
 ' allow access.
 MsgBox "Access to Outlook was denied by the user.", _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147024894 ' &H80070002
 ' Occurs if the specified file or URL could not
 ' be found, or the file or URL cannot be
 ' processed by the OpenSharedItem method.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147352567 ' &H80020009
 ' Occurs if the specified file or URL is not valid,
 ' or you attempt to use the Move method on
 ' an Outlook item that represents a shared item.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case Else
 ' Any other error that may occur.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 End Select

 GoTo EndRoutine
End Sub


How to: Send a Sharing Invitation for a Calendar

 Copy code hover
[image]

How to: Send a Sharing Invitation for a Calendar
Send feedback

Sharing messages, including sharing invitations, sharing requests, and sharing responses, are represented in Microsoft Outlook by the SharingItem object. The CreateSharingItem method of the NameSpace object is used to create SharingItem objects for sharing invitations and sharing requests.

This sample uses the OpenSharingItem method to create a SharingItem that represents sharing invitation for your Calendar default folder. Once shared, the recipient can then use the OpenSharedFolder or GetSharedDefaultFolder methods of the NameSpace object, or the OpenSharedFolder method of the SharingItem object to open the shared folder.

  1. The sample obtains a Folder object reference for the Calendar default folder for the current user, by using the GetDefaultFolder method of the NameSpace object.

  2. It uses the CreateSharingItem method to create a new SharingItem object, using the Folder object to establish the sharing context used by the SharingItem.

  3. Finally, the Add method for the Recipients collection of the newly created SharingItem object is called to add the specified recipient and the Send method is used to send the SharingItem.

Copy code Copy code
Public Sub ShareCalendarByInvitation()
 Dim oNamespace As NameSpace
 Dim oFolder As Folder
 Dim oSharingItem As SharingItem

 On Error GoTo ErrRoutine

 ' Get a reference to the Calendar default folder
 Set oNamespace = Application.GetNamespace("MAPI")
 Set oFolder = oNamespace.GetDefaultFolder(olFolderCalendar)

 ' Create a new sharing invitation, using the Calendar
 ' default folder to establish sharing context.
 Set oSharingItem = oNamespace.CreateSharingItem(oFolder)

 ' Add a recipient to the Recipients collection of
 ' the sharing invitation.
 oSharingItem.Recipients.Add "someone@example.com"

 ' Send the sharing invitation.
 oSharingItem.Send

EndRoutine:
 On Error GoTo 0
 Set oSharingItem = Nothing
 Set oFolder = Nothing
 Set oNamespace = Nothing
Exit Sub

ErrRoutine:
 Select Case Err.Number
 Case 287 ' &H0000011F
 ' The user denied access to the Address Book.
 ' This error occurs if the code is run by an
 ' untrusted application, and the user chose not to
 ' allow access.
 MsgBox "Access to Outlook was denied by the user.", _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -313393143 ' &HED520009
 ' This error typically occurs if you set the
 ' AllowWriteAccess property of a SharingItem
 ' to True when sharing a default folder.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147467259 ' &H80004005
 ' This error typically occurs if the SharingItem
 ' cannot be sent because of incorrect or
 ' conflicting property settings.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case Else
 ' Any other error that may occur.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 End Select

 GoTo EndRoutine
End Sub


How to: Send a Sharing Invitation for an RSS Feed

 Copy code hover
[image]

How to: Send a Sharing Invitation for an RSS Feed
Send feedback

Sharing messages, including sharing invitations, sharing requests, and sharing responses, are represented in Microsoft Outlook by the SharingItem object. The CreateSharingItem method of the NameSpace object is used to create SharingItem objects for sharing invitations and sharing requests. Sharing responses are automatically created by Outlook when the Reply or ReplyAll methods of a SharingItem that represents a sharing invitation or sharing request are called.

This sample uses the OpenSharingItem method to create a SharingItem that represents a sharing invitation for a Really Simple Syndication (RSS) feed. Once shared, the recipient can then use the OpenSharedFolder method of the NameSpace object or the OpenSharedFolder method of the SharingItem object to open the RSS feed.

  1. The sample first creates a NameSpace object reference to the MAPI namespace.

  2. It then uses the CreateSharingItem method to create a new SharingItem object, using the URI of the RSS feed to establish the sharing context used by the SharingItem.

  3. Finally, the Add method for the Recipients collection of the newly created SharingItem object is called to add the specified recipient and the Send method is used to send the SharingItem.

Copy code Copy code
Public Sub ShareRSSByInvitation()
 Dim oNamespace As NameSpace
 Dim sRSSurl As String
 Dim oSharingItem As SharingItem

 On Error GoTo ErrRoutine

 ' Specify the RSS feed URL for which sharing is to
 ' be requested.
 sRSSurl = "feed://example.com/rss.xml"

 ' Get a reference to the MAPI namespace.
 Set oNamespace = Application.GetNamespace("MAPI")

 ' Create a new sharing request, using the RSS feed
 ' URL to establish sharing context.
 Set oSharingItem = oNamespace.CreateSharingItem(sRSSurl)

 ' Add a recipient to the Recipients collection of
 ' the sharing invitation.
 oSharingItem.Recipients.Add "someone@example.com"

 ' Send the sharing invitation.
 oSharingItem.Send

EndRoutine:
 On Error GoTo 0
 Set oSharingItem = Nothing
 Set oFolder = Nothing
 Set oNamespace = Nothing
Exit Sub

ErrRoutine:
 Select Case Err.Number
 Case 287 ' &H0000011F
 ' The user denied access to the Address Book.
 ' This error occurs if the code is run by an
 ' untrusted application, and the user chose not to
 ' allow access.
 MsgBox "Access to Outlook was denied by the user.", _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -313393143 ' &HED520009
 ' This error typically occurs if you set the
 ' AllowWriteAccess property to true for a
 ' default folder.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case -2147467259 ' &H80004005
 ' This error typically occurs if the SharingItem
 ' cannot be sent because of incorrect or
 ' conflicting property settings.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 Case Else
 ' Any other error that may occur.
 MsgBox Err.Description, _
 vbOKOnly, _
 Err.Number & " - " & Err.Source
 End Select

 GoTo EndRoutine
End Sub


Shortcut Menus

 Copy code hover
[image]

Shortcut Menus
Send feedback

In this section

  • Customizing Shortcut Menus


Customizing Shortcut Menus

 Copy code hover
[image]

Customizing Shortcut Menus
See also Send feedback

You can customize several different shortcut menus in Microsoft Outlook by using your add-in to change, disable, or remove existing menu items, or to add new menu items.

You customize shortcut menus by using Microsoft Office Fluent user interface (UI) extensibility, just as you would to customize the user interface on a ribbon in an explorer or inspector.

Because CommandBar objects have been deprecated since Outlook 2010, shortcut menu events of the Application object that relied on the CommandBar object are being deprecated as well, and might not work as expected. These events include the following:

  • AttachmentContextMenuDisplay event

  • ContextMenuClose event

  • FolderContextMenuDisplay event

  • ItemContextMenuDisplay event

  • ShortcutContextMenuDisplay event

  • StoreContextMenuDisplay event

  • ViewContextMenuDisplay event

To customize shortcut menus, implement the IRibbonExtensibility interface in your add-in. Specifically, implement the GetCustomUI method of the IRibbonExtensibility interface so that when Office calls the GetCustomUI method and specifies Microsoft.Outlook.Explorer as the ribbon ID, the method loads the custom shortcut menu that is delimited by the contextMenus tag in XML. For a complete listing of ribbon identifiers, see Implementing the IRibbonExtensibility Interface.

Customizable Shortcut Menus

You can use Office Fluent UI extensibility to customize the following types of shortcut menus:

  • Alternative interactions shortcut menus.

  • Attachment shortcut menus.

  • Folder shortcut menus.

  • Item, flagged item, new item, and item selection shortcut menus.

  • Persona shortcut menus.

  • A shortcut menu for a shortcut in the Shortcuts module.

  • Store shortcut menus.

  • View and view user interface shortcut menus.

For more information about customizing shortcut menus, including examples, see Extending the User Interface in Outlook 2010 on the MSDN Web site.

See also

Concepts

Office Fluent User Interface Extensibility for Outlook


Solution Storage

 Copy code hover
[image]

Solution Storage
Send feedback

In this section

  • Storing Data for Solutions

  • Creating and Saving Data to Solution Storage

  • Updating and Deleting Solution Storage

  • Security Concerns for Solution Storage

  • How to: Store Data in a StorageItem for a Solution

  • How to: Delete Data to Reset Solution Storage

  • How to: Save Auto-Archive Properties of a Folder in Solution Storage


Storing Data for Solutions

 Copy code hover
[image]

Storing Data for Solutions
Send feedback

This topic describes using the StorageItem object as a means for developers to store private solution data.

Outlook solution developers often require a place to store and maintain private application data. For example, you may need to store an incrementing order number. The Outlook object model provides the StorageItem object to store this private data.

The StorageItem object represents a thin wrapper on a message object in MAPI (the IMessage object). It is always saved to the associated portion of its parent MAPI folder so that the item is hidden in the folder. It is a child object of the Folder object. This means that solution private data is actually stored at the folder level, allowing the data to roam with the mailbox and be available online and offline.

You can identify a StorageItem object using its subject, message class, or Entry ID. A StorageItem is not tightly bound to only one solution. This allows you to create one or more StorageItem objects in one folder or in multiple folders. Instances of the same solution, or multiple collaborating solutions, can also share the data stored in the private storage.

You can create a StorageItem or get an existing StorageItem to store solution data. You can store the data as an attachment or a value to an item property. To clean up the storage for an application, you can delete the StorageItem objects that it uses, which removes these objects permanently.

The Outlook object model does not provide any collection object for StorageItem objects. However, you can use Folder.GetTable to obtain a Table with all the hidden items in a Folder, when you specify the TableContents parameter as olHiddenItems. If keeping your data private is of a high concern, you should encrypt the data before storing it.


Creating and Saving Data to Solution Storage

 Copy code hover
[image]

Creating and Saving Data to Solution Storage
Send feedback

This topic describes creating or using existing storage to store private solution data.

The Outlook object model supports creating and storing solution data as hidden items in a folder. You can use Folder.GetStorage to create a StorageItem object in a specified folder. You can identify this object by the subject, message class, or Entry ID. Solutions can create StorageItem objects in all folders except when:

  • The folder is a Microsoft Exchange public folder, an Internet Message Access Protocol (IMAP), MSN Hotmail, or a Microsoft SharePoint Foundation folder.

  • The user permission for the folder is read-only.

  • The store provider does not support hidden items.

In these cases, Folder.GetStorage will return an error: "Cannot create StorageItem in this folder."

When you call Folder.GetStorage specifying a subject or a message class and the specified item does not exist in the folder, the call creates and returns a StorageItem object with the message class IPM.Storage; if you specified an Entry ID, howwever, the call will return the error, "The operation failed. An object could not be found."

Obtaining an Existing StorageItem

You can call Folder.GetStorage for an item that already exists in a folder. For example, the item can be one that the solution has previously created; it can be an item with a well-known message class such as IPC.MS.Outlook.AgingProperties, or an item that existed as a hidden message in the folder in a previous version of Outlook. In these cases, the call will return a StorageItem object representing the item. The message class of the item however will not change.

If you call Folder.GetStorage specifying a subject or message class and more than one item exists in the folder, then the call returns the item that was last modified (that is, the item with the most recent PidTagLastModificationTime).

Storing Data in a StorageItem

After obtaining a StorageItem object, you can store private data as an attachment to the item, or as a value to the Body property or a custom property of the item. The initial size of the item is 0. As you store data to the item, the StorageItem.Size is updated. Call StorageItem.Save to update the contents of the item in the folder.


Updating and Deleting Solution Storage

 Copy code hover
[image]

Updating and Deleting Solution Storage
Send feedback

This topic describes updating and deleting solution storage.

Updating Solution Storage

You can store private solution data as an attachment or as the value of a property of a StorageItem object in most folders. Since it is possible for multiple solutions to share the same solution storage, after updating an attachment or property, a solution should call StorageItem.Save to update the item in the folder. In cases where there is more than one solution accessing the same object, the object would always show the updates through the most recent StorageItem.Save.

Attempting to save to a StorageItem object that has been deleted will result in the error, "Unable to perform the operation."

Deleting Solution Storage

Solutions can remove a StorageItem object by calling StorageItem.Delete. This call permanently removes the object from the folder; it does not move it to the Deleted Items folder. This allows a solution to clean up or reset the storage for its private data.

Attempting to delete a StorageItem that has been removed by a prior StorageItem.Delete call will result in the error, "Could not complete the deletion."

Note Note

Solution storage can only be removed through the Delete method of the corresponding StorageItem object. If the creator solution has been uninstalled and there is no other solution that can access the object to delete it, the object will remain as a hidden item in the folder for as long as the folder exists.


Security Concerns for Solution Storage

 Copy code hover
[image]

Security Concerns for Solution Storage
Send feedback

This topic describes security considerations for storing private data in solution storage.

The Outlook object model intends StorageItem objects to be created and accessed by only the solution or collaborating solutions that use them. Hence, it does not expose a StorageItems collection for all StorageItem objects in a folder. Custom properties created for the StorageItem are not exposed in the Field Chooser dialog box either.

The Folder.GetTable method supports a TableContents parameter that returns a Table containing only hidden items in a folder if you specify the parameter as olHiddenItems.

However, there exist technologies outside of the Outlook object model that allow modifying or deleting data stored as hidden items in MAPI folders. Solutions that are concerned with the privacy of their data should encrypt their private data at the property level with their own encryption algorithms.


How to: Store Data in a StorageItem for a Solution

 Copy code hover
[image]

How to: Store Data in a StorageItem for a Solution
Send feedback

This topic describes how to store private application data in solution storage provided by the Outlook object model.

  1. Determine the folder where you would like to store your application data.

    Note Note

    Because solution storage is created as hidden items in a folder, you can only store solution data if the store provider supports hidden items and the client has rights to write to that folder.

  2. Use Folder.GetStorage to obtain either an existing StorageItem object or a new StorageItem object if one does not already exist.

  3. Use StorageItem.Size to determine if the StorageItem is new. If it is, then use the Add method of StorageItem.UserProperties to create a custom property Order Number.

  4. Set the Order Number property. This assumes that an existing StorageItem already has the custom property Order Number defined.

  5. Use StorageItem.Save to save the StorageItem object as a hidden item in the folder.

Copy code Copy code
Sub StoreData()
 Dim oInbox As Folder
 Dim myStorage As StorageItem
 Dim myPrivateProperty As UserProperty

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)
 ' Get an existing instance of StorageItem by subject, or create new if it doesn't exist
 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 If myStorage.Size = 0 Then
 'There was no existing StorageItem by this subject, so created a new one
 'Create a custom property for Order Number
 Set myPrivateProperty = myStorage.UserProperties.Add("Order Number", olNumber)
 Else
 'Assume that existing storage has the Order Number property already
 Set myPrivateProperty = myStorage.UserProperties("Order Number")
 End If
 myPrivateProperty.Value = lngOrderNumber
 myStorage.Save
End Sub


How to: Delete Data to Reset Solution Storage

 Copy code hover
[image]

How to: Delete Data to Reset Solution Storage
Send feedback

This topic describes how to delete existing solution data to reset the solution storage:

  1. Use Folder.GetStorage to obtain an existing StorageItem object in a specific folder. This call will return a new StorageItem object if none already exists.

  2. Use StorageItem.Delete to remove the object permanently from the folder.

  3. Use Folder.GetStorage to create a new instance of the StorageItem object with the same subject.

  4. Use the Add method of StorageItem.UserProperties to create a custom property Order Number.

  5. Set the Order Number property.

  6. Use StorageItem.Save to save the StorageItem object to the folder.

Copy code Copy code
Sub StoreData()
 Dim oInbox As Folder
 Dim myStorage As StorageItem
 Dim myPrivateProperty As UserProperty

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)
 ' Get an existing instance of StorageItem by subject
 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 'Remove the storage permanently assuming it's old
 myStorage.Delete
 Set myStorage = Nothing

 'Get a new instance of StorageItem in the Inbox
 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 'Create custom property for Order Number
 Set myPrivateProperty = myStorage.UserProperties.Add("Order Number", olNumber)

 'Store application data in the Order Number property
 myPrivateProperty.Value = 1000

 'Save the data to the Inbox
 myStorage.Save
End Sub


How to: Save Auto-Archive Properties of a Folder in Solution Storage

 Copy code hover
[image]

How to: Save Auto-Archive Properties of a Folder in Solution Storage
Send feedback

This topic shows a solution that saves its private data in a few MAPI auto-archive properties. The solution stores these properties in a StorageItem object of the folder to which the auto-archive properties apply. StorageItem objects are stored as hidden data in the associated portion of a folder, and because solutions can optionally encrypt their data, they offer the privacy required of solution data. Because the MAPI auto-archive properties are not exposed as explicit built-in properties in the Outlook object model, the solution uses the PropertyAccessor on the StorageItem object to set these properties.

The following illustrates the procedure:

  1. The ChangeAgingProperties function accepts the following as input parameters:

    • oFolder is the Folder object to which the aging properties apply and where their values are stored.

    • AgeFolder indicates whether to archive or delete items in the folder as specified.

    • DeleteItems indicates whether to delete, instead of archive, items that are older than the aging period.

    • FileName indicates a specific file for archiving aged items. If this is an empty string, the default archive file, archive.pst, will be used.

    • Granularity indicates the unit of time for aging, whether archiving is to be calculated in units of months, weeks, or days.

    • Period indicates the amount of time in the given granularity. Together, the Granularity and Period values indicate an aging period. Items in the given folder older than this aging period are to be archived or deleted as specified. For example, a Granularity of 2 and Period of 14 specifies an aging period of 14 days, when items in the given folder older than 14 days should be either archived or deleted as specified.

    • Default indicates which settings should be set to the default. The possible values are 0, 1, and 3:

      • 0 indicates nothing assumes a default value.

      • 1 indicates that only the file location assumes a default value. This is the same as checking Archive this folder using these settings and Move old items to default archive folder in the AutoArchive tab of the Properties dialog box for the folder.

      • 3 indicates all settings assume a default value. This is the same as checking Archive items in this folder using default settings in the AutoArchive tab of the Properties dialog box for the folder.

  2. The validity of the parameters is checked.

  3. If the parameters are valid, Folder.GetStorage is used to create or get an existing StorageItem object with the message class, IPC.MS.Outlook.AgingProperties.

  4. PropertyAccessor is then used to set the auto-archive properties on the StorageItem, StorageItem.Save is used to save changes to the StorageItem.

  5. The TestAgingProps procedure sets the auto-archive settings for the aging properties of the current folder so that items older than six months are moved to the default archive file.

Remarks

  1. Place the code in the built-in ThisOutlookSession module.

  2. Run the TestAgingProps procedure to set aging properties on the current folder in the active explorer.

Note Note

Whether it is implemented as a VBA macro or a COM add-in, the solution is a trusted caller and can therefore access the PropertyAccessor. To improve this example, wrap the following VBA code in a .NET class for better error trapping and enumeration for Granularity.
Copy code Copy code
Function ChangeAgingProperties(oFolder As Outlook.Folder, _
 AgeFolder As Boolean, DeleteItems As Boolean, _
 FileName As String, Granularity As Integer, _
 Period As Integer, Default As Integer) As Boolean

 '6 MAPI properties for aging items in a folder
 Const PR_AGING_AGE_FOLDER = _
 "http://schemas.microsoft.com/mapi/proptag/0x6857000B"
 Const PR_AGING_DELETE_ITEMS = _
 "http://schemas.microsoft.com/mapi/proptag/0x6855000B"
 Const PR_AGING_FILE_NAME_AFTER9 = _
 "http://schemas.microsoft.com/mapi/proptag/0x6859001E"
 Const PR_AGING_GRANULARITY = _
 "http://schemas.microsoft.com/mapi/proptag/0x36EE0003"
 Const PR_AGING_PERIOD = _
 "http://schemas.microsoft.com/mapi/proptag/0x36EC0003"
 Const PR_AGING_DEFAULT = _
 "http://schemas.microsoft.com/mapi/proptag/0x685E0003"

 Dim oStorage As StorageItem
 Dim oPA As PropertyAccessor

 ' Valid Period:
 ' 1-999
 '
 ' Valid Granularity:
 ' 0=Months, 1=Weeks, 2=Days
 '
 ' Valid Default:
 ' 0=All settings do not use a default setting
 ' 1=Only the file location is defaulted
 ' "Archive this folder using these settings" and
 ' "Move old items to default archive folder" are checked
 ' 3=All settings are defaulted
 ' "Archive items in this folder using default settings" is checked

 If (oFolder Is Nothing) Or _
 (Granularity < 0 Or Granularity > 2) Or _
 (Period < 1 Or Period > 999) Or _
 (Default < 0 Or Default = 2 Or Default > 3) _
 Then
 ChangeAgingProperties = False
 End If

 On Error GoTo Aging_ErrTrap

 'Create or get solution storage in given folder by message class
 Set oStorage = oFolder.GetStorage( _
 "IPC.MS.Outlook.AgingProperties", olIdentifyByMessageClass)
 Set oPA = oStorage.PropertyAccessor

 If Not (AgeFolder) Then
 oPA.SetProperty PR_AGING_AGE_FOLDER, False
 Else
 'Set the 6 aging properties in the solution storage
 oPA.SetProperty PR_AGING_AGE_FOLDER, True
 oPA.SetProperty PR_AGING_GRANULARITY, Granularity
 oPA.SetProperty PR_AGING_DELETE_ITEMS, DeleteItems
 oPA.SetProperty PR_AGING_PERIOD, Period
 If FileName <> "" Then
 oPA.SetProperty PR_AGING_FILE_NAME_AFTER9, FileName
 End If
 oPA.SetProperty (PR_AGING_DEFAULT), Default
 End If
 'Save changes as hidden messages to the associated portion of the folder
 oStorage.Save
 ChangeAgingProperties = True
 Exit Function

Aging_ErrTrap:
 Debug.Print Err.Number, Err.Description
 ChangeAgingProperties = False
End Function

Sub TestAgingProps()
 Dim oFolder As Outlook.Folder
 Set oFolder = Application.ActiveExplorer.CurrentFolder
 If ChangeAgingProperties(oFolder, True, False, "", 0, 6, 1) Then
 Debug.Print "ChangeAgingProperties OK"
 Else
 Debug.Print "ChangeAgingProperties Failed"
 End If
End Sub


Views (Outlook)

 Copy code hover
[image]

Views (Outlook)
Send feedback

In this section

  • Outlook Views

  • Filtering and Specifying Fields in a View

  • Sorting Fields in a View


Outlook Views

 Copy code hover
[image]

Outlook Views
Send feedback

Microsoft Outlook allows you to create customizable views that allow you to better sort, group, and ultimately view data of all different types within an explorer. There are a variety of different view types that provide the flexibility needed to create and maintain your important data. Outlook supports the following objects, derived from the View object.

Object name | Description
BusinessCardView | This object allows you to view data as a series of Electronic Business Card (EBC) images.
CalendarView | This object allows you to view data in a calendar format.
CardView | This object allows you to view data in a series of cards.
IconView | This object allows you to view data as icons, similar to a Windows folder or explorer.
TableView | This object allows you to view data in a simple, field-based table.
TimelineView | This object allows you to view data in a customizable linear time line.

While you can use the View object to interact with the properties and methods common to all views, you must cast the View object to one of the derived view objects, such as the CardView object, to access certain properties, such as the HeadingsFont property of the CardView object. You can use the ViewType property of the View object to determine which type of view is represented by that object.

You can define a new view by using the Add method of the Views collection for a Folder object. Visibility for the view can be set either at the time of creation, by specifying an OlViewSaveOption constant in the SaveOption parameter of the Add method, or any time after the view is created, by specifying an OlViewSaveOption constant for the SaveOption property of the View object. Adding a new view raises the ViewAdd event of the Views collection.

You can use the Remove method of the Views object to remove an existing custom view. Removing a view raises the ViewRemove event of the Views collection.

Once a view is defined, you can customize the view programmatically by casting the View object to one of the derived view objects, such as the BusinessCardView object, and performing whatever changes are needed. Use the Save method of the derived view object or the View object to save any changes to the view.

You can apply the view, once defined and customized, to the current Explorer object by using the Apply method of the derived view object or the View object. Applying a view raises the ViewSwitch event of the Explorer object.


Filtering and Specifying Fields in a View

 Copy code hover
[image]

Filtering and Specifying Fields in a View
Send feedback

You can specify which Outlook item properties are displayed in a view by adding one or more properties to the ViewFields collection of any of the following objects:

  • CardView

  • TableView

BusinessCardView , CalendarView, IconView, and TimelineView objects use other methods of determining which Outlook item properties are displayed within the view.The fields displayed for the BusinessCardView object, for example, are determined by the Electronic Business Card (EBC) layout associated with each displayed Outlook item.

The ViewFields collection for those views can be retrieved by calling the ViewFields property of the appropriate view object. The Add method of the ViewFields collection is used to create a ViewField object that represents the Outlook item property to be displayed in the view.

A ViewField object not only identifies an Outlook item property to display within the view, but also describes how the values for that property should be displayed. You can change how properties are displayed in a view.

Filtering Outlook Items

Outlook items can be filtered in any view derived from the View object by specifying a DAV Searching and Locating (DASL) filter expression in the Filter property of the View object. For more information about creating a DASL filter expression with which to filter Outlook items, see Filtering Items.


Sorting Fields in a View

 Copy code hover
[image]

Sorting Fields in a View
Send feedback

Outlook items can be sorted by adding one or more Outlook item properties to the OrderFields collection of any of the following objects:

  • BusinessCardView

  • CardView

  • IconView

  • TableView

Outlook items in a CalendarView or TimelineView object are displayed in chronological order, depending on the values of the Outlook item properties specified for the StartField and EndField properties of the view.

The OrderFields collection for those views can be retrieved by calling the SortFields property of the appropriate view object. The Add method of the OrderFields collection is used to create an OrderField object that represents the Outlook item property to be sorted.

Specifying Properties for Sorting

You can add either built-in or custom Outlook item properties to the OrderFields collection. The order in which the properties are included in the OrderFields collection determines the order in which the properties are sorted, while the IsDescending property of the OrderField object which represents an Outlook item property determines whether the values of that property are sorted in ascending or descending order.

Specifying Built-In Properties for Sorting

The following guidelines should be used when specifying built-in Outlook item properties:

  • Built-in properties can be specified either by property name (for example, "Subject") or by namespace (for example, "http://schemas.microsoft.com/mapi/proptag/0x0037001E").

  • Property names are not case-sensitive and cannot include spaces.

  • Namespace identifiers are case-sensitive, must follow URL encoding rules, and cannot be enclosed in square brackets ([]).

Specifying Custom Properties for Sorting

The following guidelines should be used when specifying custom properties:

  • The custom property must be available in the UserDefinedProperties collection for the parent Folder object.

  • Custom properties should be specified by property name (for example, "[Shoe Size]").

  • Custom property names are not case-sensitive, can include spaces, and should be enclosed in square brackets ([]) if they contain spaces.

For more information about property identifiers, see Properties Overview.


How do I... (Outlook 2013 developer reference)

 Copy code hover
[image]

How do I... (Outlook 2013 developer reference)
Send feedback

This topic links to how-to and walkthrough topics for common Microsoft Outlook scenarios.

"How Do I ..." is your gateway to key task-based topics about programming and application development using Outlook. The essential categories for what you can do with Outlook are listed in this topic. The links provide pointers to important, procedure-based Help topics.

The Microsoft Office Developer Documentation team welcomes your task ideas and code samples! Topics tagged by the [image] logo are contributed by Microsoft Most Valued Professionals (MVP). If we use your code samples in Outlook 2013 content, we will recognize your work with a byline and a link to your Web site. For more information, contact us at docthis@microsoft.com.

Accounts

  • How to: Create a Sendable Item for a Specific Account Based on the Current Folder

  • How to: Identify a Folder with an Account

  • How to: Obtain Information for Multiple Accounts

Add-in Administration

  • How to: Verify if Outlook is a Click-To-Run Application on a Computer

Address Books

  • How to: Display a Dialog Box for Selecting Entries from the Contacts Folder

  • How to: Display Address Entry Details for the Sender of a Message

  • How to: Identify the Global Address List or a Set of Address Lists with a Store

  • How to: List the Groups that My Manager Belongs to

  • How to: List the Name and Office Location of Each Manager Belonging to an Exchange Distribution List

  • How to: Map a Display Name to an E-mail Address

  • How to: Obtain the E-mail Address of a Recipient

  • How to: Programmatically Change the Display Format for All Contacts

Appointments

  • How to: Create an Appointment as a Meeting on the Calendar

  • How to: Create a Recurring Appointment that Occurs Every 2 Years

  • How to: Import Appointment XML Data into Outlook Appointment Objects

Attachments

  • How to: Attach a File to an Outlook Email Message

  • How to: Attach an Outlook Contact Item to an Email Message

  • How to: Limit the Size of an Attachment to an Outlook Email Message

  • How to: Modify an Attachment of an Outlook Email Message

Contact Pictures

  • How to: Specify Whether to Display a Contact's Picture in Outlook

Electronic Business Cards

  • How to: Share Contact Information Including the Business Card

Forms

  • See Forms.

Folders and Stores

  • How to: Delete All Items and Subfolders in the Deleted Items Folder

  • How to: Enumerate Folders on All Stores

  • How to: Enumerate Search Folders on All Stores

  • How-to: Enumerate the Contacts Folder and Set Custom Property for only Contact Items

  • How to: Obtain a Folder Object from a Folder Path

Mail Items

  • How to: Send an E-mail Given the SMTP Address of an Account

  • How to: Specify an Internet Encoding Scheme for the Body and Attachments of a Message

Navigation

  • How to: Add a Custom Folder to a Group and Display it in Overlay Mode by Default

  • How to: Add a Folder to the Favorite Folders Group

  • How to: Display Specific Modules in the Navigation Pane

  • How to: Enumerate Active Folders in the Calendar View

  • How to: Enumerate, Show, Hide, and Position Modules in the Navigation Pane

  • How to: Set a Module as the Currently Selected Module in the Navigation Pane

  • How to: Show or Hide the Navigation Pane

Properties

  • How to: Identify a Meeting Item as a Counter-Proposal to a Prior Meeting Request

Rules

  • How to: Create a Rule to Move Specific E-mails to a Folder

Search and Filter

  • How to: Access the Values of a Multi-valued Property in a Table

  • How-to: Enumerate the Contacts Folder and Set Custom Property for only Contact Items

  • How to: Filter Items that Do Not Have Categories

  • How to: Filter the Body of a Mail Item

  • How to: Obtain and Enumerate Selected Conversations

  • How to: Search the Inbox for Items with Subject Containing "Office"

  • How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period

  • How to: Search the Calendar for Appointments Within a Date Range that Contain a Specific Word in the Subject

  • How to: Search and Obtain Items in an Aggregated View

  • How to: Use the Table Object to Performantly Enumerate Filtered Items in a Folder

Sessions

  • How to: Obtain and Log On to an Instance of Outlook

Sharing

  • How to: Export a Calendar using Payload Sharing

  • How to: Import Saved Items using OpenSharedItem

  • How to: Send a Sharing Invitation for a Calendar

  • How to: Send a Sharing Invitation for an RSS Feed

Solution Storage

  • How to: Delete Data to Reset Solution Storage

  • How to: Save Auto-Archive Properties of a Folder in Solution Storage

  • How to: Store Data in a StorageItem for a Solution


Forms (Outlook How Do I)

 Copy code hover
[image]

Forms (Outlook How Do I)
Send feedback

This topic links to help on widely used Forms tasks. To view other categories of popular tasks covered in Help, see How Do I ... in Outlook.

Form Regions

How to: Create a Form Region

Describes at a conceptual level the considerations and steps for creating a form region.

Walkthrough: Add a Form Region to an Existing Page on a Form

A step-by-step walkthrough that describes how to add an adjoining form region to the General page of the standard Contact form.

Manipulating Controls in VBScript

How to: Accept User Input and Display the Values of Controls on a Form

Describes how to let a user select a control and have its value displayed in the control.

How to: Access a Page in a MultiPage Control

Describes how to access an individual page of a multi-page control.

How to: Access a Tab in a TabStrip Control

Describes how to access an individual tab of a tab strip control in several ways.

How to: Add a Control to a MultiPage Control

Describes how to add and remove a control to a page of a multi-page control.

How to: Add a Control to a Page

Describes how to add a control to a form at runtime.

How to: Add and Remove Items from a List Box

Describes how to add and delete the contents of a list box.

How to: Add Items To a List or Combo Box at Run Time

Describes how to add items to a single-column list box or combo box, or a multi-column list box or combo box.

How to: Add Scroll Bars to a Page and a Frame

Describes how to add scroll bars to a page of a multi-page control and to a frame control.

How to: Add, Cut, and Paste a Control on a Page

Describes how to cut and paste a control from a page of a multi-page control.

How to: Align the Caption of an Option Buttion with the Control

Describes how to align the caption of an option button with the button.

How to: Allow a Command Button to Take Focus Upon Clicking

Describes how to control whether a command button receives the focus when the user clicks on it.

How to: Allow Multiple Lines, Word Wrapping, and Scrolling in a Text Box

Describes how to control multiple lines, word-wrapping, and scrolling in a text box.

How to: Allow Multiple Selections in a List Box

Describes how to allow the user select one or more items in a list box.

How to: Allow the Null State for a Check Box and a Toggle Button

Describes how to allow Null as an acceptable value in a check box and a toggle button.

How to: Automatically Size a Text Box with User Input

Describes how to allow automatic sizing of a single-line text box and a mult-line text box upon user input.

How to: Change the Accelerator and Caption of a Command Button

Describes how to assign an accelerator key and a caption to the control.

How to: Change the Column Width of a Multi-Column List

Describes how to change the column widths of a multi-column list box.

How to: Change the Name of a Control

Describes how to change the name of a check box.

How to: Change the Order of Pages and Tabs

Describes how to change the order of the pages and tabs in a multi-page and a tab strip control.

How to: Change the Style, Size, and Effects of a Font

Describes how to manipulate font properties of an object.

How to: Control Character Matching in a Combo Box and List Box

Describes how to support character matching in a combo box and a list box.

How to: Control the Drop Button Style and When to Show the Drop Button

Demonstrates the different symbols that you can specify for a drop-down arrow in a combo box and a text box.

How to: Control the Extent of Scrolling in a Scroll Bar

Describes how to control the range of scrolling in a stand-alone scroll bar.

How to: Control the Focus When the User Cycles through Controls in a Frame or MultiPage Control on a Form

Describes how to control the focus for a frame and two page objects in a multi-page control.

How to: Control the Selection Behavior and Drag Behavior When Entering a Text Box

Demonstrates the different effects that you can provide when entering a control and when dragging information from one control to another.

How to: Control the Style and Selection Behavior of a List Box

Describes how to control the appearance of a list box.

How to: Control the Text Box' Behavior on Clicking Enter

Describes how to control the effect of ENTER in a text box.

How to: Cut Text from One Text Box and Paste it on Another

Describes how to cut text from one text box and paste it into another.

How to: Display the List Portion of a Combo Box

Describes how to display the list in a combo box.

How to: Display the Name of Each Control on a Form or a Page of a MultiPage Control

Describes how to access individual controls in a collection of controls and in a collection of pages and display the name.

How to: Display the Name of Each Control on a Page

Describes how to display of each control on a form.

How to: Display the Number of Pages and Tabs in MultiPage and TabStrip Controls on a Form

Describes how to display the number of controls in a collection of controls, and the number of pages and tabs of each multi-page and tab strip control.

How to: Enable and Lock a Text Box from User Entry

Describes how to enable and lock a text box.

How to: Enhance the Border Style, Color, and Special Effects of a Text Box Control

Demonstrates the borders and special effects available for a text box.

How to: Give a Control a 3-D Appearance Programmatically

Describes how to give special effects to a check box.

How to: Group Option Buttons

Describes how to create two groups of option button controls on the same form.

How to: Hide or Show a Control Programmatically

Describes how to hide or show a check box.

How to: Move a Text Box in Front of or Behind Another Control

Describes how to set the z-order of a text box, so the user can display the entire text box (by bringing it to the front of the z-order) or can place the text box behind other controls.

How to: Move Controls on a Page

Describes how to move all the controls on a form.

How to: Place an Image and a Caption on a Command Button

Shows the picture placement options for a control.

How to: Reference a Custom Property that Has the Same Name as a Built-in Property of the Control

Describes how to support a custom property that has the same name as a standard, built-in property of the control.

How to: Reference the Parent Object of a Control

Describes how to refer to the control, form, or other object that contains a specific control or object.

How to: Resize a Control Horizontally and Vertically with the Form

Describes how to resize a text box horizontally and vertically on a page.

How to: Set Entry Matching in a Combo Box

Demonstrates additional character matching for a combo box.

How to: Set the Item at the Top of a List and the Item that Has Focus in the List

Describes how to identify the top item displayed in a list box and the item that has the focus within the list box.

How to: Set the Height and Width of Tabs in a MultiPage and a TabStrip Control

Describes how to set the size of the tabs used in a multi-page and a tab strip control.

How to: Set the Input Style for a Combo Box

Describes how to change the style of user input of a combo box.

How to: Set the Maximum and Minimum Values for a Scroll Bar

Describes how to set the maximum and minimum values for a stand-alone scroll bar.

How to: Set the Number of Lines and the Length of Input in a Text Box

Describes how to set the characters and the number of lines of text in a text box.

How to: Set the Style of Tabs for a MultiPage and a TabStrip Control

Describes how to specify the appearance of the tabs in multi-page and tab strip control.

How to: Set the Tab Order of Controls in a Frame

Describes how to display and set the tab order for individual controls in a frame.

How to: Set the Type of Mouse Pointer for a List Box

Describes how to specify a mouse pointer that is appropriate for a specific control or scenario.

How to: Set the Width of the Drop-Down List of a Combo Box

Describes how to control the width of the drop-down list of a combo box.

How to: Simulate a Two-Dimensional Array with List Boxes

Describes how to load a two-dimensional array with data and, in turn, load two list box controls.

How to: Specify Additional Information for a Control

Describes how to store additional information about each control on a form.

How to: Specify Control Tip Text for Controls

Describes how to specify control tip text for three command button controls and two page objects in a multi-page control.

How to: Specify Possible Values for a List Box

Describes how to specify possible values that are supported by a list box.

How to: Specify Tab Support for a Control

Describes how to control whether a user can press TAB to move the focus to a particular control on a form.

How to: Specify the Column in a Multi-Column List Box to Display to the User

Describes how to identify the column of data in a multi-column list box that is to be displayed.

How to: Specify the Column in a Multi-Column List Box to Store Data for the Control

Describes how to identify the column in a multi-column list box that is to store data for the list box.

How to: Specify the Number of Rows in a Combo Box

Describes how to control the number of rows in the drop-down list of a combo box.

How to: Swap Columns of a Multicolumn List Box

Describes how to swap columns of a multi-column list box.

How to: Undo and Redo an Action in a Text Box or a Combo Box

Describes how to undo or redo text editing within a text box or within the text area of a combo box.

How to: Use the Controls Collection to Move Controls on a Page

Describes how to move controls within a controls collection on a page.


Object model (Outlook 2013 developer reference)

 Copy code hover
[image]

Object model (Outlook 2013 developer reference)
Send feedback

This section of the Outlook 2013 Developer Reference contains documentation for all of the objects, properties, methods, and events contained in the Outlook object model. You can use the table of contents to navigate through the documentation.


Account Object (Outlook)

 Copy code hover
[image]

Account Object (Outlook)
See also Send feedback

Published: July 16, 2012

The Account object represents an account that is defined for the current profile.

Version Information

Version Added: Outlook 2007

Remarks

The purpose of the Accounts collection object and the Account object is to provide the capacity to enumerate Account objects in a given profile, to identify the type of Account, and to use a specific Account object to send mail.

Helmut Obertanner provided the following code samples. Helmut is a Microsoft Most Valuable Professional with expertise in Microsoft Office development tools in Microsoft Visual Studio and Microsoft Office Outlook. Helmut maintains a professional site at X4Uelectronix.

Example

The following managed code samples are written in C# and Visual Basic. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code samples in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code samples show the DisplayAccountInformation method of the Sample class, implemented as part of an Outlook add-in project. Each project adds a reference to the Outlook PIA, which is based on the Microsoft.Office.Interop.Outlook namespace. The DisplayAccountInformation method takes as an input argument a trusted Outlook Application object, and uses the Account object to display the details of each account that is available for the current Outlook profile.

C# Copy code Copy code
using System;
using System.Text;
using Outlook = Microsoft.Office.Interop.Outlook;

namespace OutlookAddIn1
{
 class Sample
 {
 public static void DisplayAccountInformation(Outlook.Application application)
 {

 // The Namespace Object (Session) has a collection of accounts.
 Outlook.Accounts accounts = application.Session.Accounts;

 // Concatenate a message with information about all accounts.
 StringBuilder builder = new StringBuilder();

 // Loop over all accounts and print detail account information.
 // All properties of the Account object are read-only.
 foreach (Outlook.Account account in accounts)
 {

 // The DisplayName property represents the friendly name of the account.
 builder.AppendFormat("DisplayName: {0}\n", account.DisplayName);

 // The UserName property provides an account-based context to determine identity.
 builder.AppendFormat("UserName: {0}\n", account.UserName);

 // The SmtpAddress property provides the SMTP address for the account.
 builder.AppendFormat("SmtpAddress: {0}\n", account.SmtpAddress);

 // The AccountType property indicates the type of the account.
 builder.Append("AccountType: ");
 switch (account.AccountType)
 {

 case Outlook.OlAccountType.olExchange:
 builder.AppendLine("Exchange");
 break;

 case Outlook.OlAccountType.olHttp:
 builder.AppendLine("Http");
 break;

 case Outlook.OlAccountType.olImap:
 builder.AppendLine("Imap");
 break;

 case Outlook.OlAccountType.olOtherAccount:
 builder.AppendLine("Other");
 break;

 case Outlook.OlAccountType.olPop3:
 builder.AppendLine("Pop3");
 break;
 }

 builder.AppendLine();
 }

 // Display the account information.
 System.Windows.Forms.MessageBox.Show(builder.ToString());
 }
 }
}
Visual Basic Copy code Copy code
Imports Outlook = Microsoft.Office.Interop.Outlook

Namespace OutlookAddIn2
 Class Sample
 Shared Sub DisplayAccountInformation(ByVal application As Outlook.Application)

 ' The Namespace Object (Session) has a collection of accounts.
 Dim accounts As Outlook.Accounts = application.Session.Accounts

 ' Concatenate a message with information about all accounts.
 Dim builder As StringBuilder = New StringBuilder()

 ' Loop over all accounts and print detail account information.
 ' All properties of the Account object are read-only.
 Dim account As Outlook.Account
 For Each account In accounts

 ' The DisplayName property represents the friendly name of the account.
 builder.AppendFormat("DisplayName: {0}" & vbNewLine, account.DisplayName)

 ' The UserName property provides an account-based context to determine identity.
 builder.AppendFormat("UserName: {0}" & vbNewLine, account.UserName)

 ' The SmtpAddress property provides the SMTP address for the account.
 builder.AppendFormat("SmtpAddress: {0}" & vbNewLine, account.SmtpAddress)

 ' The AccountType property indicates the type of the account.
 builder.Append("AccountType: ")
 Select Case (account.AccountType)

 Case Outlook.OlAccountType.olExchange
 builder.AppendLine("Exchange")

 Case Outlook.OlAccountType.olHttp
 builder.AppendLine("Http")

 Case Outlook.OlAccountType.olImap
 builder.AppendLine("Imap")

 Case Outlook.OlAccountType.olOtherAccount
 builder.AppendLine("Other")

 Case Outlook.OlAccountType.olPop3
 builder.AppendLine("Pop3")

 End Select

 builder.AppendLine()
 Next

 ' Display the account information.
 Windows.Forms.MessageBox.Show(builder.ToString())
 End Sub

 End Class
End Namespace

See also

Concepts

How to: Send an E-mail Given the SMTP Address of an Account
Outlook Object Model Reference

Other resources

Account Object Members


Account Members (Outlook)

 Copy code hover
[image]

Account Members (Outlook)
Send feedback

Published: July 16, 2012

The Account object represents an account that is defined for the current profile.

Methods

Name | Description
GetAddressEntryFromID | Returns an AddressEntry object that represents the address entry specified by the given entry ID.
GetRecipientFromID | Returns the Recipient object that is identified by the given entry ID.

Properties

Name | Description
AccountType | Returns a constant in the OlAccountType enumeration that indicates the type of the Account. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoDiscoverConnectionMode | Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection to use for the auto-discovery service of the Microsoft Exchange server that hosts the account mailbox. Read-only.
AutoDiscoverXml | Returns a String that represents information in XML retrieved from the auto-discovery service of the Microsoft Exchange Server that is associated with the account. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentUser | Returns a Recipient object that represents the current user identity for the account. Read-only.
DeliveryStore | Returns a Store object that represents the default delivery store for the account. Read-only.
DisplayName | Returns a String representing the display name of the e-mail Account. Read-only.
ExchangeConnectionMode | Returns an OlExchangeConnectionMode constant that indicates the current connection mode for the Microsoft Exchange Server that hosts the account mailbox. Read-only
ExchangeMailboxServerName | Returns a String value that represents the name of the Microsoft Exchange Server that hosts the account mailbox. Read-only.
ExchangeMailboxServerVersion | Returns a String value that represents the full version number of the Microsoft Exchange Server that hosts the account mailbox. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SmtpAddress | Returns a String representing the Simple Mail Transfer Protocol (SMTP) address for the Account. Read-only.
UserName | Returns a String representing the user name for the Account. Read-only.


Account Properties (Outlook)

 Copy code hover
[image]

Account Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AccountType | Returns a constant in the OlAccountType enumeration that indicates the type of the Account. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoDiscoverConnectionMode | Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection to use for the auto-discovery service of the Microsoft Exchange server that hosts the account mailbox. Read-only.
AutoDiscoverXml | Returns a String that represents information in XML retrieved from the auto-discovery service of the Microsoft Exchange Server that is associated with the account. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentUser | Returns a Recipient object that represents the current user identity for the account. Read-only.
DeliveryStore | Returns a Store object that represents the default delivery store for the account. Read-only.
DisplayName | Returns a String representing the display name of the e-mail Account. Read-only.
ExchangeConnectionMode | Returns an OlExchangeConnectionMode constant that indicates the current connection mode for the Microsoft Exchange Server that hosts the account mailbox. Read-only
ExchangeMailboxServerName | Returns a String value that represents the name of the Microsoft Exchange Server that hosts the account mailbox. Read-only.
ExchangeMailboxServerVersion | Returns a String value that represents the full version number of the Microsoft Exchange Server that hosts the account mailbox. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SmtpAddress | Returns a String representing the Simple Mail Transfer Protocol (SMTP) address for the Account. Read-only.
UserName | Returns a String representing the user name for the Account. Read-only.


Account.AccountType Property (Outlook)

 Copy code hover
[image]

Account.AccountType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlAccountType enumeration that indicates the type of the Account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AccountType

expression A variable that represents an Account object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.Application Property (Outlook)

 Copy code hover
[image]

Account.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an Account object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.AutoDiscoverConnectionMode Property (Outlook)

 Copy code hover
[image]

Account.AutoDiscoverConnectionMode Property (Outlook)
See also Send feedback

Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection to use for the auto-discovery service of the Microsoft Exchange server that hosts the account mailbox. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .AutoDiscoverConnectionMode

expression A variable that represents an Account object.

Remarks

This property is similar to the AutoDiscoverConnectionMode property of the NameSpace object, except that this property applies to the account for which auto-discovery is completed and not necessarily to the primary Exchange account.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.AutoDiscoverXml Property (Outlook)

 Copy code hover
[image]

Account.AutoDiscoverXml Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents information in XML retrieved from the auto-discovery service of the Microsoft Exchange Server that is associated with the account. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .AutoDiscoverXml

expression A variable that represents an Account object.

Remarks

This property is similar to the AutoDiscoverXml property of the NameSpace object, except that this property applies to the account for which auto-discovery is completed and not necessarily to the primary Exchange account.

The returned string of XML contains information about various Web services (for example, availability service and unified messaging service) and available servers.

An error is returned if the account is not associated with an Exchange Server that is running Microsoft Exchange Server 2007 or later.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.Class Property (Outlook)

 Copy code hover
[image]

Account.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an Account object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.CurrentUser Property (Outlook)

 Copy code hover
[image]

Account.CurrentUser Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipient object that represents the current user identity for the account. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .CurrentUser

expression A variable that represents an Account object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.DeliveryStore Property (Outlook)

 Copy code hover
[image]

Account.DeliveryStore Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Store object that represents the default delivery store for the account. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .DeliveryStore

expression A variable that represents an Account object.

Remarks

Returns Null (Nothing in Visual Basic) if the account does not have a default delivery store.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.DisplayName Property (Outlook)

 Copy code hover
[image]

Account.DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the e-mail Account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayName

expression A variable that represents an Account object.

Remarks

DisplayName is the default property of the Account object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.ExchangeConnectionMode Property (Outlook)

 Copy code hover
[image]

Account.ExchangeConnectionMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlExchangeConnectionMode constant that indicates the current connection mode for the Microsoft Exchange Server that hosts the account mailbox. Read-only

Version Information

Version Added: Outlook 2010

Syntax

expression .ExchangeConnectionMode

expression A variable that represents an Account object.

Remarks

This property is similar to the ExchangeConnectionMode property of the NameSpace object, except that this property applies to the Exchange Server that hosts the account mailbox, and not necessarily to the primary Exchange account.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.ExchangeMailboxServerName Property (Outlook)

 Copy code hover
[image]

Account.ExchangeMailboxServerName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the name of the Microsoft Exchange Server that hosts the account mailbox. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ExchangeMailboxServerName

expression A variable that represents an Account object.

Remarks

This property is similar to the ExchangeMailboxServerName property of the NameSpace object, except that this property applies to the Exchange Server that hosts the account mailbox, and not necessarily to the primary Exchange account.

If an Exchange mailbox is not associated with this account, this property returns an empty string.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.ExchangeMailboxServerVersion Property (Outlook)

 Copy code hover
[image]

Account.ExchangeMailboxServerVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the full version number of the Microsoft Exchange Server that hosts the account mailbox. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ExchangeMailboxServerVersion

expression A variable that represents an Account object.

Remarks

This property is similar to the ExchangeMailboxServerVersion property of the NameSpace object, except that this property applies to the Exchange Server that hosts the account mailbox, and not necessarily to the primary Exchange account.

This property returns a string that contains the version number of the Exchange server for the account. The version number has the following four parts.

Copy code Copy code
<major version>.<minor version>.<build number>.<revision>

Not all parts may be present in the version number, depending on the version information that is supplied by the Exchange Server. For example, this property returns "6.5.7638" for Microsoft Exchange Server 2003 Service Pack 2.

If an Exchange mailbox is not associated with this account, this property returns an empty string.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.Parent Property (Outlook)

 Copy code hover
[image]

Account.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an Account object.

Remarks

The parent of the Account object is the Accounts object.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.Session Property (Outlook)

 Copy code hover
[image]

Account.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an Account object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Account Object

Other resources

Account Object Members


Account.SmtpAddress Property (Outlook)

 Copy code hover
[image]

Account.SmtpAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the Simple Mail Transfer Protocol (SMTP) address for the Account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SmtpAddress

expression A variable that represents an Account object.

Remarks

The purpose of SmtpAddress and Account.UserName is to provide an account-based context to determine identity.

If the account does not have an SMTP address, SmtpAddress returns an empty string.

See also

Concepts

Account Object
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
Account Object Members


Account.UserName Property (Outlook)

 Copy code hover
[image]

Account.UserName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the user name for the Account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .UserName

expression A variable that represents an Account object.

Remarks

The purpose of Account.SmtpAddress and UserName is to provide an account-based context to determine identity.

If the account does not have a user name defined, UserName returns an empty string.

See also

Concepts

Account Object

Other resources

Account Object Members


Account Methods (Outlook)

 Copy code hover
[image]

Account Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetAddressEntryFromID | Returns an AddressEntry object that represents the address entry specified by the given entry ID.
GetRecipientFromID | Returns the Recipient object that is identified by the given entry ID.


Account.GetAddressEntryFromID Method (Outlook)

 Copy code hover
[image]

Account.GetAddressEntryFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntry object that represents the address entry specified by the given entry ID.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetAddressEntryFromID(ID)

expression A variable that represents an Account object.

Parameters

Name | Required/Optional | Data Type | Description
ID | Required | String | Used to identify an address entry that is maintained for the session.

Return Value

An AddressEntry that has the ID property that matches the specified ID.

Remarks

This method is similar to the GetAddressEntryFromID method of the NameSpace object, but has some additional contextual information about which account to use for the look-up. If there are multiple Microsoft Exchange accounts in the current profile, use the GetAddressEntryFromID method for the corresponding account.

The ID property for an AddressEntry is a permanent, unique string identifier that the transport provider assigns when an AddressEntry is created. Outlook maintains a hierarchy of address books for a session, and the address entry that is returned must match the given ID and be in one of the address books.

GetAddressEntryFromID returns an error if no item with the given ID can be found, if no connection is available, or if the user is set to work offline.

See also

Concepts

Account Object

Other resources

Account Object Members


Account.GetRecipientFromID Method (Outlook)

 Copy code hover
[image]

Account.GetRecipientFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Recipient object that is identified by the given entry ID.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetRecipientFromID(EntryID)

expression A variable that represents an Account object.

Parameters

Name | Required/Optional | Data Type | Description
EntryID | Required | String | The EntryID of the recipient.

Return Value

A Recipient object that represents the recipient associated with the specified entry ID.

Remarks

This method is similar to the GetRecipientFromID method of the NameSpace object. If there are multiple Microsoft Exchange accounts in the current profile, use the GetRecipientFromID method for the corresponding account.

See also

Concepts

Account Object

Other resources

Account Object Members


AccountRuleCondition Object (Outlook)

 Copy code hover
[image]

AccountRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether an account was used to send a message.

Version Information

Version Added: Outlook 2007

Remarks

AccountRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has an Account property. The Account property always returns a AccountRuleCondition object. If the rule has an enabled rule condition that the message is sent using a specified account, then AccountRuleCondition.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

AccountRuleCondition Object Members


AccountRuleCondition Members (Outlook)

 Copy code hover
[image]

AccountRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether an account was used to send a message.

Properties

Name | Description
Account | Returns or sets an Account object that represents the account used to evaluate the rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionAccount, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AccountRuleCondition Properties (Outlook)

 Copy code hover
[image]

AccountRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Account | Returns or sets an Account object that represents the account used to evaluate the rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionAccount, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AccountRuleCondition.Account Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Account Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an Account object that represents the account used to evaluate the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Account

expression A variable that represents an AccountRuleCondition object.

Remarks

Returns an error if account does not represent an initialized account.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an AccountRuleCondition object.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an AccountRuleCondition object.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Returns a constant, olConditionAccount, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents an AccountRuleCondition object.

Remarks

The account rule condition is supported by rules for receiving messages and rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an AccountRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it has been saved successfully.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an AccountRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


AccountRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

AccountRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an AccountRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AccountRuleCondition Object

Other resources

AccountRuleCondition Object Members


Accounts Object (Outlook)

 Copy code hover
[image]

Accounts Object (Outlook)
See also Send feedback

Published: July 16, 2012

The Accounts collection object contains a set of Account objects representing the accounts available for the current profile.

Version Information

Version Added: Outlook 2007

Remarks

The purpose of the Accounts collection object and the Account object is to allow the enumeration of Account objects in a given profile, the identification of the type of an Account, and the use of a specific Account object to send mail.

See also

Concepts

Outlook Object Model Reference
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

Accounts Object Members


Accounts Members (Outlook)

 Copy code hover
[image]

Accounts Members (Outlook)
Send feedback

Published: July 16, 2012

The Accounts collection object contains a set of Account objects representing the accounts available for the current profile.

Events

Name | Description
AutoDiscoverComplete | Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange Server that is associated with the account, and has the related information available in the AutoDiscoverXml property of the Account object.

Methods

Name | Description
Item | Returns an Account object specified by Index.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Accounts Properties (Outlook)

 Copy code hover
[image]

Accounts Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Accounts.Application Property (Outlook)

 Copy code hover
[image]

Accounts.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an Accounts object.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts.Class Property (Outlook)

 Copy code hover
[image]

Accounts.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an Accounts object.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts.Count Property (Outlook)

 Copy code hover
[image]

Accounts.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents an Accounts object.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts.Parent Property (Outlook)

 Copy code hover
[image]

Accounts.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an Accounts object.

Remarks

The parent of the Accounts object is the NameSpace object.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts.Session Property (Outlook)

 Copy code hover
[image]

Accounts.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an Accounts object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts Methods (Outlook)

 Copy code hover
[image]

Accounts Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns an Account object specified by Index.


Accounts.Item Method (Outlook)

 Copy code hover
[image]

Accounts.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Account object specified by Index.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents an Accounts object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A one-based Long that indexes into the Accounts collection, or a String that specifies the DisplayName of an Account.

Return Value

An Account object that matches the account specified by Index.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


Accounts Events (Outlook)

 Copy code hover
[image]

Accounts Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AutoDiscoverComplete | Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange Server that is associated with the account, and has the related information available in the AutoDiscoverXml property of the Account object.


Accounts.AutoDiscoverComplete Event (Outlook)

 Copy code hover
[image]

Accounts.AutoDiscoverComplete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange Server that is associated with the account, and has the related information available in the AutoDiscoverXml property of the Account object.

Version Information

Version Added: Outlook 2010

Syntax

expression .AutoDiscoverComplete(Account)

expression A variable that represents an Accounts object.

Parameters

Name | Required/Optional | Data Type | Description
Account | Required | Account | The account whose auto-discovery of the associated Exchange Server is complete.

Remarks

This event is similar to the AutoDiscoverComplete event of the NameSpace object, except that this event applies to the account for which auto-discovery is completed and not necessarily to the primary Exchange account.

See also

Concepts

Accounts Object

Other resources

Accounts Object Members


AccountSelector Object (Outlook)

 Copy code hover
[image]

AccountSelector Object (Outlook)
See also Send feedback

Published: July 16, 2012

Provides the ability to obtain the account that is selected in the Microsoft Office Backstage view for the parent Explorer object.

Version Information

Version Added: Outlook 2010

Remarks

The AccountSelector object has the Explorer object as its parent object. You can obtain an instance of the AccountSelector object from the AccountSelector property of the Explorer object.

The AccountSelector object provides a SelectedAccount property that returns the current account that has been selected in the Backstage view. The object also provides a SelectedAccountChange event that fires when the user has changed the account in the Backstage view.

See also

Concepts

Outlook Object Model Reference

Other resources

AccountSelector Object Members


AccountSelector Members (Outlook)

 Copy code hover
[image]

AccountSelector Members (Outlook)
Send feedback

Published: July 16, 2012

Provides the ability to obtain the account that is selected in the Microsoft Office Backstage view for the parent Explorer object.

Events

Name | Description
SelectedAccountChange | Occurs when the user selects a different account in the drop-down list under Account Information on the Info tab of the Microsoft Office Backstage view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that indicates the class of the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
SelectedAccount | Returns an Account object that represents the selected account in the Microsoft Office Backstage view in Microsoft Outlook. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AccountSelector Properties (Outlook)

 Copy code hover
[image]

AccountSelector Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that indicates the class of the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
SelectedAccount | Returns an Account object that represents the selected account in the Microsoft Office Backstage view in Microsoft Outlook. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AccountSelector.Application Property (Outlook)

 Copy code hover
[image]

AccountSelector.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Application

expression A variable that represents an AccountSelector object.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


AccountSelector.Class Property (Outlook)

 Copy code hover
[image]

AccountSelector.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that indicates the class of the object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Class

expression A variable that represents an AccountSelector object.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


AccountSelector.Parent Property (Outlook)

 Copy code hover
[image]

AccountSelector.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Parent

expression A variable that represents an AccountSelector object.

Remarks

The parent of the AccountSelector object returns an Explorer object.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


AccountSelector.SelectedAccount Property (Outlook)

 Copy code hover
[image]

AccountSelector.SelectedAccount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Account object that represents the selected account in the Microsoft Office Backstage view in Microsoft Outlook. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectedAccount

expression A variable that represents an AccountSelector object.

Remarks

In the Outlook user interface, you can select an account explicitly on the Info tab of the Backstage view, or you can select an account implicitly when you select a folder in a list of folders. The SelectedAccount property represents the currently selected account in the Backstage view for a given instance of the Explorer object. To determine the account that is selected implicitly, identify the Account object that has its DefaultStore property equal to the Store property of the current folder (which is represented by Explorer.CurrentFolder).

This property returns Null (Nothing in Visual Basic) if no accounts are defined in the session's profile; that is, the Namespace.Accounts.Count property is 0.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


AccountSelector.Session Property (Outlook)

 Copy code hover
[image]

AccountSelector.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Session

expression A variable that represents an AccountSelector object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

You can use the Session property and the GetNamespace method of the Application object interchangeably to obtain the NameSpace object for the current session.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


AccountSelector Events (Outlook)

 Copy code hover
[image]

AccountSelector Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
SelectedAccountChange | Occurs when the user selects a different account in the drop-down list under Account Information on the Info tab of the Microsoft Office Backstage view.


AccountSelector.SelectedAccountChange Event (Outlook)

 Copy code hover
[image]

AccountSelector.SelectedAccountChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects a different account in the drop-down list under Account Information on the Info tab of the Microsoft Office Backstage view.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectedAccountChange(SelectedAccount)

expression A variable that represents an AccountSelector object.

Parameters

Name | Required/Optional | Data Type | Description
SelectedAccount | Required | Account | Represents the currently selected account in the Backstage view.

See also

Concepts

AccountSelector Object

Other resources

AccountSelector Object Members


Action Object (Outlook)

 Copy code hover
[image]

Action Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a specialized action (for example, the voting options response) that can be executed on an Outlook item.

Remarks

The Action object is a member of the Actions collection.

Use Actions (index), where index is the name of an available action, to return a single Action object from the Actions collection object of an Outlook item, such as MailItem.

Example

The following Visual Basic for Applications (VBA) example uses the Reply action of a particular item to send a reply.

VBA Copy code Copy code
myItem = CreateItem(olMailItem)

Set myReply = myItem.Actions("Reply").Execute

The following Visual Basic for Applications example does the same thing, using a different reply style for the reply.

VBA Copy code Copy code
myItem = CreateItem(olMailItem)

myItem.Actions("Reply").ReplyStyle = _

 olIncludeOriginalText

Set myReply = myItem.Actions("Reply").Execute

See also

Concepts

Outlook Object Model Reference

Other resources

Action Object Members


Action Members (Outlook)

 Copy code hover
[image]

Action Members (Outlook)
Send feedback

Represents a specialized action (for example, the voting options response) that can be executed on an Outlook item.

Methods

Name | Description
Delete | Deletes an object from the collection.
Execute | Executes the action for the specified item.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CopyLike | Returns or sets an OlActionCopyLike constant indicating the property inheritance style to use for the action. Read/write.
Enabled | Returns or sets a Boolean that is True if the action is enabled in the application. Read/write.
MessageClass | Returns or sets a String representing the message class for the Action. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Prefix | Returns or sets a String specifying the prefix (for example, "Re") to use with the subject of the item when the action is executed. Read/write.
ReplyStyle | Returns or sets an OlActionReplyStyle constant indicating the text formatting reply style for the specified action. Read/write.
ResponseStyle | Returns or sets an OlActionResponseStyle constant indicating the response style used when the specified action is executed. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
ShowOn | Returns or sets an OlActionShowOn constant representing the location where the action will be shown. Read/write.


Action Properties (Outlook)

 Copy code hover
[image]

Action Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CopyLike | Returns or sets an OlActionCopyLike constant indicating the property inheritance style to use for the action. Read/write.
Enabled | Returns or sets a Boolean that is True if the action is enabled in the application. Read/write.
MessageClass | Returns or sets a String representing the message class for the Action. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Prefix | Returns or sets a String specifying the prefix (for example, "Re") to use with the subject of the item when the action is executed. Read/write.
ReplyStyle | Returns or sets an OlActionReplyStyle constant indicating the text formatting reply style for the specified action. Read/write.
ResponseStyle | Returns or sets an OlActionResponseStyle constant indicating the response style used when the specified action is executed. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
ShowOn | Returns or sets an OlActionShowOn constant representing the location where the action will be shown. Read/write.


Action.Application Property (Outlook)

 Copy code hover
[image]

Action.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Class Property (Outlook)

 Copy code hover
[image]

Action.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.CopyLike Property (Outlook)

 Copy code hover
[image]

Action.CopyLike Property (Outlook)
See also Send feedback

Returns or sets an OlActionCopyLike constant indicating the property inheritance style to use for the action. Read/write.

Syntax

expression .CopyLike

expression A variable that represents an Action object.

Remarks

The inheritance style is used when the action is executed to control how properties are copied to the new item created by the action.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Enabled Property (Outlook)

 Copy code hover
[image]

Action.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that is True if the action is enabled in the application. Read/write.

Syntax

expression .Enabled

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.MessageClass Property (Outlook)

 Copy code hover
[image]

Action.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Action. Read/write.

Syntax

expression .MessageClass

expression A variable that represents an Action object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
Action Object

Other resources

Action Object Members


Action.Name Property (Outlook)

 Copy code hover
[image]

Action.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Parent Property (Outlook)

 Copy code hover
[image]

Action.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Prefix Property (Outlook)

 Copy code hover
[image]

Action.Prefix Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the prefix (for example, "Re") to use with the subject of the item when the action is executed. Read/write.

Syntax

expression .Prefix

expression A variable that represents an Action object.

Remarks

Outlook automatically adds a colon (:) to the value of the Prefix property when setting the subject of the item.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.ReplyStyle Property (Outlook)

 Copy code hover
[image]

Action.ReplyStyle Property (Outlook)
See also Send feedback

Returns or sets an OlActionReplyStyle constant indicating the text formatting reply style for the specified action. Read/write.

Syntax

expression .ReplyStyle

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.ResponseStyle Property (Outlook)

 Copy code hover
[image]

Action.ResponseStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlActionResponseStyle constant indicating the response style used when the specified action is executed. Read/write.

Syntax

expression .ResponseStyle

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Session Property (Outlook)

 Copy code hover
[image]

Action.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Action object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Action Object

Other resources

Action Object Members


Action.ShowOn Property (Outlook)

 Copy code hover
[image]

Action.ShowOn Property (Outlook)
See also Send feedback

Returns or sets an OlActionShowOn constant representing the location where the action will be shown. Read/write.

Syntax

expression .ShowOn

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action Methods (Outlook)

 Copy code hover
[image]

Action Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.
Execute | Executes the action for the specified item.


Action.Delete Method (Outlook)

 Copy code hover
[image]

Action.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents an Action object.

See also

Concepts

Action Object

Other resources

Action Object Members


Action.Execute Method (Outlook)

 Copy code hover
[image]

Action.Execute Method (Outlook)
See also Send feedback

Published: July 16, 2012

Executes the action for the specified item.

Syntax

expression .Execute

expression An expression that returns a Action object.

Return Value

An Object value that represents the Outlook item created by the action upon execution.

Example

This Visual Basic for Applications (VBA) example uses the Execute method to look through all the actions for the given e-mail message and executes the action called "Reply."

VBA Copy code Copy code
Sub SendReply()

 Dim myNameSpace As Outlook.NameSpace

 Dim MyItem As Outlook.MailItem

 Dim myItem2 As Outlook.MailItem

 Dim myAction As Outlook.Action

 Set myNameSpace = Application.GetNamespace("MAPI")

 On Error GoTo ErrorHandler

 Set MyItem = Application.ActiveInspector.CurrentItem

 For Each myAction In MyItem.Actions

 If myAction.Name = "Reply" Then

 Set myItem2 = myAction.Execute

 myItem2.Send

 Exit For

 End If

 Next myAction

 Exit Sub

ErrorHandler:

 MsgBox "There is no current item."

End Sub

See also

Concepts

Action Object

Other resources

Action Object Members


Actions Object (Outlook)

 Copy code hover
[image]

Actions Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of Action objects that represent all the specialized actions that can be executed on an Outlook item.

Remarks

Use the Actions property of any Outlook item, such as MailItem, to return the Actions object.

Use Actions(index), where index is the name of an available action, to return a single Action object.

Example

The following Visual Basic for Applications (VBA) example uses the Reply action of a particular item to send a reply.

VBA Copy code Copy code
myItem = CreateItem(olMailItem)

Set myReply = myItem.Actions("Reply").Execute

See also

Concepts

Outlook Object Model Reference

Other resources

Actions Object Members


Actions Members (Outlook)

 Copy code hover
[image]

Actions Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of Action objects that represent all the specialized actions that can be executed on an Outlook item.

Methods

Name | Description
Add | Creates a new action in the Actions collection.
Item | Returns an Action object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Actions Properties (Outlook)

 Copy code hover
[image]

Actions Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Actions.Application Property (Outlook)

 Copy code hover
[image]

Actions.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Actions object.

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Class Property (Outlook)

 Copy code hover
[image]

Actions.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Actions object.

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Count Property (Outlook)

 Copy code hover
[image]

Actions.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Actions object.

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Parent Property (Outlook)

 Copy code hover
[image]

Actions.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Actions object.

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Session Property (Outlook)

 Copy code hover
[image]

Actions.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Actions object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions Methods (Outlook)

 Copy code hover
[image]

Actions Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Add | Creates a new action in the Actions collection.
Item | Returns an Action object from the collection.
Remove | Removes an object from the collection.


Actions.Add Method (Outlook)

 Copy code hover
[image]

Actions.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new action in the Actions collection.

Syntax

expression .Add

expression A variable that represents an Actions object.

Return Value

An Action object that represents the new action.

Example

This VBA example creates a new mail message and uses the Add method to add an Action to it. To run this example without any errors, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub AddAction()

 Dim myItem As Outlook.MailItem

 Dim myAction As Outlook.Action

 Set myItem = Application.CreateItem(olMailItem)

 Set myAction = myItem.Actions.Add

 myAction.Name = "Link Original"

 myAction.ShowOn = olMenuAndToolbar

 myAction.ReplyStyle = olLinkOriginalItem

 myItem.To = "Dan Wilson"

 myItem.Send

End Sub

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Item Method (Outlook)

 Copy code hover
[image]

Actions.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Action object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an Actions object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Action object that represents the specified object.

See also

Concepts

Actions Object

Other resources

Actions Object Members


Actions.Remove Method (Outlook)

 Copy code hover
[image]

Actions.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an Actions object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

Actions Object

Other resources

Actions Object Members


AddressEntries Object (Outlook)

 Copy code hover
[image]

AddressEntries Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of addresses for an AddressList object.

Remarks

The object may contain zero or more AddressEntry objects and provides access to the entries in a transport provider's address book container.

Example

The following example sets a reference to an AddressEntries object.

VBA Copy code Copy code
Set myNameSpace = Application.GetNameSpace("MAPI")

Set myAddressList = myNameSpace.AddressLists("Personal Address Book")

Set myAddressEntries = myAddressList.AddressEntries

You can also index directly into the AddressEntries object, returning an AddressEntry object.

VBA Copy code Copy code
Set myAddressEntry = myAddressList.AddressEntries(index)

See also

Concepts

Outlook Object Model Reference

Other resources

AddressEntries Object Members


AddressEntries Members (Outlook)

 Copy code hover
[image]

AddressEntries Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of addresses for an AddressList object.

Methods

Name | Description
Add | Adds a new entry to the AddressEntries collection.
GetFirst | Returns the first object in the AddressEntries collection.
GetLast | Returns the last object in the AddressEntries collection.
GetNext | Returns the next object in the AddressEntries collection.
GetPrevious | Returns the previous object in the AddressEntries collection.
Item | Returns an AddressEntry object from the collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressEntries Properties (Outlook)

 Copy code hover
[image]

AddressEntries Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressEntries.Application Property (Outlook)

 Copy code hover
[image]

AddressEntries.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AddressEntries object.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Class Property (Outlook)

 Copy code hover
[image]

AddressEntries.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AddressEntries object.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Count Property (Outlook)

 Copy code hover
[image]

AddressEntries.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an AddressEntries object.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Parent Property (Outlook)

 Copy code hover
[image]

AddressEntries.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AddressEntries object.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Session Property (Outlook)

 Copy code hover
[image]

AddressEntries.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AddressEntries object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries Methods (Outlook)

 Copy code hover
[image]

AddressEntries Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds a new entry to the AddressEntries collection.
GetFirst | Returns the first object in the AddressEntries collection.
GetLast | Returns the last object in the AddressEntries collection.
GetNext | Returns the next object in the AddressEntries collection.
GetPrevious | Returns the previous object in the AddressEntries collection.
Item | Returns an AddressEntry object from the collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.


AddressEntries.Add Method (Outlook)

 Copy code hover
[image]

AddressEntries.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a new entry to the AddressEntries collection.

Syntax

expression .Add(Type, Name, Address)

expression An AddressEntries object that represents the new entry.

Parameters

Name | Required/Optional | Data Type | Description
Type | Required | String | The type of the new entry.
Name | Optional | Variant | The name of the new entry.
Address | Optional | Variant | The address.

Return Value

An AddressEntry object that represents the new entry.

Remarks

New entries or changes to existing entries are not persisted in the collection until after calling the Update method.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.GetFirst Method (Outlook)

 Copy code hover
[image]

AddressEntries.GetFirst Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the first object in the AddressEntries collection.

Syntax

expression .GetFirst

expression A variable that represents an AddressEntries object.

Return Value

An AddressEntry object that represents the first object contained by the collection.

Remarks

Returns Nothing if no first object exists, for example, if there are no objects in the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.GetLast Method (Outlook)

 Copy code hover
[image]

AddressEntries.GetLast Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the last object in the AddressEntries collection.

Syntax

expression .GetLast

expression A variable that represents an AddressEntries object.

Return Value

An AddressEntry object that represents the last object contained by the collection.

Remarks

It returns Nothing if no last object exists, for example, if the collection is empty. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.GetNext Method (Outlook)

 Copy code hover
[image]

AddressEntries.GetNext Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the next object in the AddressEntries collection.

Syntax

expression .GetNext

expression A variable that represents an AddressEntries object.

Return Value

An AddressEntry object that represents the next object contained by the collection.

Remarks

It returns Nothing if no next object exists, for example, if already positioned at the end of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.GetPrevious Method (Outlook)

 Copy code hover
[image]

AddressEntries.GetPrevious Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the previous object in the AddressEntries collection.

Syntax

expression .GetPrevious

expression A variable that represents an AddressEntries object.

Return Value

An AddressEntry object that represents the previous object contained by the collection.

Remarks

It returns Nothing if no previous object exists, for example, if already positioned at the beginning of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Item Method (Outlook)

 Copy code hover
[image]

AddressEntries.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntry object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an AddressEntries object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An AddressEntry object that represents the specified object.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntries.Sort Method (Outlook)

 Copy code hover
[image]

AddressEntries.Sort Method (Outlook)
See also Send feedback

Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Syntax

expression .Sort(Property, Order)

expression A variable that represents an AddressEntries object.

Parameters

Name | Required/Optional | Data Type | Description
Property | Optional | Variant | The name of the property by which to sort, which may be enclosed in brackets, for example, "[CompanyName]". May not be a user-defined field, and may not be a multi-valued property, such as a category.
Order | Optional | Variant | The order for the specified address entries. Can be one of these OlSortOrder constants: olAscending, olDescending, or olSortNone.

Remarks

Sort only affects the order of items in a collection. It does not affect the order of items in an explorer view.

See also

Concepts

AddressEntries Object

Other resources

AddressEntries Object Members


AddressEntry Object (Outlook)

 Copy code hover
[image]

AddressEntry Object (Outlook)
See also Send feedback

Represents a person, group, or public folder to which the messaging system can deliver messages.

Remarks

The AddressEntry object is an address in an AddressEntries object. Each AddressEntry object in the AddressEntries object holds information that represents a person, group, or public folder to which the messaging system can deliver messages.

Use AddressEntries(index), where index is the index number of an address entry or a value used to match the default property of an address entry, to return a single AddressEntry object.

Example

The following example sets a reference to an AddressEntry object.

Copy code Copy code
Set myAddressEntry = myRecipient.AddressEntry

See also

Concepts

Outlook Object Model Reference

Other resources

AddressEntry Object Members


AddressEntry Members (Outlook)

 Copy code hover
[image]

AddressEntry Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a person, group, or public folder to which the messaging system can deliver messages.

Methods

Name | Description
Delete | Deletes an object from the collection.
Details | Displays a modeless dialog box that provides detailed information about an AddressEntry object.
GetContact | Returns a ContactItem object that represents the AddressEntry, if the AddressEntry corresponds to a contact in an Outlook Contacts Address Book (CAB).
GetExchangeDistributionList | Returns an ExchangeDistributionList object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange distribution list.
GetExchangeUser | Returns an ExchangeUser object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange user.
GetFreeBusy | Returns a String value that represents the availability of the individual user for a period of 30 days from the start date, beginning at midnight of the date specified.
Update | Posts a change to the AddressEntry object in the messaging system.

Properties

Name | Description
Address | Returns or sets a String representing the e-mail address of the AddressEntry. Read/write.
AddressEntryUserType | Returns a constant from the OlAddressEntryUserType enumeration representing the user type of the AddressEntry. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayType | Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the AddressEntry. Read-only.
ID | Returns a String representing the unique identifier for the object. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressEntry object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns or sets a String representing the type of entry for this address such as an Internet Address, MacMail Address, or Microsoft Mail Address. Read/write.


AddressEntry Properties (Outlook)

 Copy code hover
[image]

AddressEntry Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Address | Returns or sets a String representing the e-mail address of the AddressEntry. Read/write.
AddressEntryUserType | Returns a constant from the OlAddressEntryUserType enumeration representing the user type of the AddressEntry. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayType | Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the AddressEntry. Read-only.
ID | Returns a String representing the unique identifier for the object. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressEntry object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns or sets a String representing the type of entry for this address such as an Internet Address, MacMail Address, or Microsoft Mail Address. Read/write.


AddressEntry.Address Property (Outlook)

 Copy code hover
[image]

AddressEntry.Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the e-mail address of the AddressEntry. Read/write.

Syntax

expression .Address

expression A variable that represents an AddressEntry object.

Remarks

The Address property must be set before calling the AddressEntry.Details method.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.AddressEntryUserType Property (Outlook)

 Copy code hover
[image]

AddressEntry.AddressEntryUserType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlAddressEntryUserType enumeration representing the user type of the AddressEntry. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressEntryUserType

expression A variable that represents an AddressEntry object.

Remarks

AddressEntryUserType provides a level of granularity for user types that is finer than that of AddressEntry.DisplayType. The DisplayType property does not distinguish users with different types of AddressEntry, such as an AddressEntry that has a Simple Mail Transfer Protocol (SMTP) e-mail address, a Lightweight Directory Access Protocol (LDAP) address, an Exchange user address, or an AddressEntry in the Outlook Contacts Address Book. All these entires have olUser as their AddressEntry.DisplayType.

Example

The following code sample shows how to obtain the business phone number, office location, and job title for all Exchange user entries in the Exchange Global Address List. It first uses AddressList.AddressListType to find the Global Address List. Since the Global Address List can contain multiple types of entries such as Exchange user, Exchange distribution list, and Exchange public folder, for each AddressEntry on that AddressList, the code sample uses AddressEntryUserType to verify if the AddressEntry represents an Exchange user. After it finds an Exchange user, it obtains and prints the various pieces of data for the user.

Copy code Copy code
Sub DemoAE()

 Dim colAL As Outlook.AddressLists

 Dim oAL As Outlook.AddressList

 Dim colAE As Outlook.AddressEntries

 Dim oAE As Outlook.AddressEntry

 Dim oExUser As Outlook.ExchangeUser

 Set colAL = Application.Session.AddressLists

 For Each oAL In colAL

 'Address list is an Exchange Global Address List

 If oAL.AddressListType = olExchangeGlobalAddressList Then

 Set colAE = oAL.AddressEntries

 For Each oAE In colAE

 If oAE.AddressEntryUserType = _

 olExchangeUserAddressEntry Then

 Set oExUser = oAE.GetExchangeUser

 Debug.Print(oExUser.JobTitle)

 Debug.Print(oExUser.OfficeLocation)

 Debug.Print(oExUser.BusinessTelephoneNumber)

 End If

 Next

 End If

 Next

End Sub

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Application Property (Outlook)

 Copy code hover
[image]

AddressEntry.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Class Property (Outlook)

 Copy code hover
[image]

AddressEntry.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.DisplayType Property (Outlook)

 Copy code hover
[image]

AddressEntry.DisplayType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the AddressEntry. Read-only.

Syntax

expression .DisplayType

expression A variable that represents an AddressEntry object.

Remarks

You can use the DisplayType property to filter address entries. The DisplayType property corresponds to the MAPI property PidTagDisplayType.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.ID Property (Outlook)

 Copy code hover
[image]

AddressEntry.ID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique identifier for the object. Read-only.

Syntax

expression .ID

expression A variable that represents an AddressEntry object.

Remarks

The transport provider assigns a permanent, unique string ID property when an individual member object is created. These identifiers do not change from one session to another.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Name Property (Outlook)

 Copy code hover
[image]

AddressEntry.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an AddressEntry object.

Remarks

It is necessary for the Name property to be set before calling the AddressEntry.Details method.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Parent Property (Outlook)

 Copy code hover
[image]

AddressEntry.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

AddressEntry.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressEntry object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Session Property (Outlook)

 Copy code hover
[image]

AddressEntry.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AddressEntry object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Type Property (Outlook)

 Copy code hover
[image]

AddressEntry.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the type of entry for this address such as an Internet Address, MacMail Address, or Microsoft Mail Address. Read/write.

Syntax

expression .Type

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry Methods (Outlook)

 Copy code hover
[image]

AddressEntry Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.
Details | Displays a modeless dialog box that provides detailed information about an AddressEntry object.
GetContact | Returns a ContactItem object that represents the AddressEntry, if the AddressEntry corresponds to a contact in an Outlook Contacts Address Book (CAB).
GetExchangeDistributionList | Returns an ExchangeDistributionList object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange distribution list.
GetExchangeUser | Returns an ExchangeUser object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange user.
GetFreeBusy | Returns a String value that represents the availability of the individual user for a period of 30 days from the start date, beginning at midnight of the date specified.
Update | Posts a change to the AddressEntry object in the messaging system.


AddressEntry.Delete Method (Outlook)

 Copy code hover
[image]

AddressEntry.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents an AddressEntry object.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Details Method (Outlook)

 Copy code hover
[image]

AddressEntry.Details Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a modeless dialog box that provides detailed information about an AddressEntry object.

Syntax

expression .Details(HWnd)

expression An expression that returns a AddressEntry object.

Parameters

Name | Required/Optional | Data Type | Description
HWnd | Optional | Variant | The parent window handle for the Details dialog box. A zero value (the default) specifies that the dialog is parented to Outlook.

Remarks

Note Note

The Details method fails if the Name property is empty.

You must use error handling to handle run-time errors when the user clicks Cancel in the dialog box. The Details method actually stops the code from running while the dialog box is displayed.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.GetContact Method (Outlook)

 Copy code hover
[image]

AddressEntry.GetContact Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ContactItem object that represents the AddressEntry, if the AddressEntry corresponds to a contact in an Outlook Contacts Address Book (CAB).

Version Information

Version Added: Outlook 2007

Syntax

expression .GetContact

expression A variable that represents an AddressEntry object.

Return Value

A ContactItem object that corresponds to the AddressEntry. Returns Null (Nothing in Visual Basic) if the AddressEntry object does not correspond to a contact in a Contacts Address Book.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.GetExchangeDistributionList Method (Outlook)

 Copy code hover
[image]

AddressEntry.GetExchangeDistributionList Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ExchangeDistributionList object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange distribution list.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeDistributionList

expression A variable that represents an AddressEntry object.

Return Value

An ExchangeDistributionList object that represents the AddressEntry. Returns Null (Nothing in Visual Basic) if the AddressEntry object does not correspond to an Exchange distribution list.

Remarks

You have to be connected to the Exchange server to use this method.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.GetExchangeUser Method (Outlook)

 Copy code hover
[image]

AddressEntry.GetExchangeUser Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ExchangeUser object that represents the AddressEntry if the AddressEntry belongs to an Exchange AddressList object such as the Global Address List (GAL) and corresponds to an Exchange user.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeUser

expression A variable that represents an AddressEntry object.

Return Value

An ExchangeUser object that represents the AddressEntry. Returns Null (Nothing in Visual Basic) if the AddressEntry object does not correspond to an Exchange user.

Remarks

You have to be connected to the Exchange server to use this method.

Example

The following code sample shows how to obtain the business phone number, office location, and job title for all Exchange user entries in the Exchange Global Address List. It first uses AddressList.AddressListType to find the Global Address List. For each AddressEntry on that AddressList, it uses AddressEntryUserType to verify if the AddressEntry represents an Exchange user. After it finds an Exchange user, it uses GetExchangeUser to obtain and print the various pieces of data for the user.

VBA Copy code Copy code
Sub DemoAE()

 Dim colAL As Outlook.AddressLists

 Dim oAL As Outlook.AddressList

 Dim colAE As Outlook.AddressEntries

 Dim oAE As Outlook.AddressEntry

 Dim oExUser As Outlook.ExchangeUser

 Set colAL = Application.Session.AddressLists

 For Each oAL In colAL

 'Address list is an Exchange Global Address List

 If oAL.AddressListType = olExchangeGlobalAddressList Then

 Set colAE = oAL.AddressEntries

 For Each oAE In colAE

 If oAE.AddressEntryUserType = _

 olExchangeUserAddressEntry _

 Or oAE.AddressEntryUserType = _

 olExchangeRemoteUserAddressEntry Then

 Set oExUser = oAE.GetExchangeUser

 Debug.Print (oExUser.JobTitle)

 Debug.Print (oExUser.OfficeLocation)

 Debug.Print (oExUser.BusinessTelephoneNumber)

 End If

 Next

 End If

 Next

End Sub

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.GetFreeBusy Method (Outlook)

 Copy code hover
[image]

AddressEntry.GetFreeBusy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the availability of the individual user for a period of 30 days from the start date, beginning at midnight of the date specified.

Syntax

expression .GetFreeBusy(Start, MinPerChar, CompleteFormat)

expression An expression that returns an AddressEntry object.

Parameters

Name | Required/Optional | Data Type | Description
Start | Required | Date | Specifies the date.
MinPerChar | Required | Long | Specifies the length of each time slot in minutes. The default value is 30.
CompleteFormat | Optional | Variant | Specifies a Boolean value that represents the level of information returned for each time slot. The default value is False.

Return Value

A String value that represents the availability of the user for the specified period. The string value contains one character for each time slot within the specified period.

Remarks

Note Note

If an address entry represents a distribution list, the status of its individual members cannot be returned to you with the GetFreeBusy method. A meeting request should be sent only to single messaging users. You can determine if a messaging user is a distribution list by determining if its DisplayType property is olDistList or olPrivateDistList.

The contents of the string returned by this method are determined by the CompleteFormat parameter.

If CompleteFormat is set to False, the default value, the string returned by this method contains one of the following characters for each time slot:

Character | Description
0 | The time slot represents a free period.
1 | The time slot represents a tentative, out of office (OOF), or busy period.

If CompleteFormat is set to True, the string returned by this method contains one of the following characters for each time slot:

Character | Description
0 | The time slot represents a free period.
1 | The time slot represents a tentative period.
2 | The time slot represents a busy period.
3 | The time slot represents an out of office (OOF) period.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressEntry.Update Method (Outlook)

 Copy code hover
[image]

AddressEntry.Update Method (Outlook)
See also Send feedback

Published: July 16, 2012

Posts a change to the AddressEntry object in the messaging system.

Syntax

expression .Update(MakePermanent, Refresh)

expression An expression that returns a AddressEntry object.

Parameters

Name | Required/Optional | Data Type | Description
MakePermanent | Optional | Variant | A value of True indicates that the property cache is flushed and all changes are committed in the underlying address book. A value of False indicates that the property cache is flushed but not committed to persistent storage. The default value is True.
Refresh | Optional | Variant | A value of True indicates that the property cache is reloaded from the values in the underlying address book. A value of False indicates that the property cache is not reloaded. The default value is False.

Remarks

New entries or changes to existing entries are not persisted in the collection until the Update method has been called with its MakePermanent parameter set to True.

To flush the cache and then reload the values from the address book, call Update with the MakePermanent parameter set to False and the Refresh parameter set to True.

See also

Concepts

AddressEntry Object

Other resources

AddressEntry Object Members


AddressList Object (Outlook)

 Copy code hover
[image]

AddressList Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an address book that contains a set of AddressEntry objects.

Remarks

The AddressList object is an address book that contains a set of AddressEntry objects.

The AddressList object supplies a list of address entries to which a messaging system can deliver messages. An AddressList object represents one address book container available under the transport provider's address book hierarchy for the current session. The entire hierarchy is available through the parent AddressLists object.

Example

The following example retrieves an AddressList object that represents the Personal Address List.

Copy code Copy code
Set myAddressList = Application.Session.AddressLists("Personal Address Book")

See also

Concepts

Outlook Object Model Reference

Other resources

AddressList Object Members


AddressList Members (Outlook)

 Copy code hover
[image]

AddressList Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an address book that contains a set of AddressEntry objects.

Methods

Name | Description
GetContactsFolder | Obtains a Folder object that represents the Contacts folder for the AddressList object.

Properties

Name | Description
AddressEntries | Returns the AddressEntries collection for the specified object. Read-only.
AddressListType | Returns a constant from the OlAddressListType enumeration that represents the type of the AddressList. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ID | Returns a String representing the unique identifier for the object. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
IsInitialAddressList | Returns a Boolean that indicates if the AddressList is the initial AddressList shown in the Select Names dialog. Read-only.
IsReadOnly | Returns a Boolean value that indicates that the AddressList object cannot be modified. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressList object. Read-only.
ResolutionOrder | Returns an Integer that represents the order of this AddressList in the custom scroll list in the Addressing dialog box. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressList Properties (Outlook)

 Copy code hover
[image]

AddressList Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AddressEntries | Returns the AddressEntries collection for the specified object. Read-only.
AddressListType | Returns a constant from the OlAddressListType enumeration that represents the type of the AddressList. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ID | Returns a String representing the unique identifier for the object. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
IsInitialAddressList | Returns a Boolean that indicates if the AddressList is the initial AddressList shown in the Select Names dialog. Read-only.
IsReadOnly | Returns a Boolean value that indicates that the AddressList object cannot be modified. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressList object. Read-only.
ResolutionOrder | Returns an Integer that represents the order of this AddressList in the custom scroll list in the Addressing dialog box. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressList.AddressEntries Property (Outlook)

 Copy code hover
[image]

AddressList.AddressEntries Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the AddressEntries collection for the specified object. Read-only.

Syntax

expression .AddressEntries

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.AddressListType Property (Outlook)

 Copy code hover
[image]

AddressList.AddressListType Property (Outlook)
See also Send feedback

Returns a constant from the OlAddressListType enumeration that represents the type of the AddressList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressListType

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Application Property (Outlook)

 Copy code hover
[image]

AddressList.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Class Property (Outlook)

 Copy code hover
[image]

AddressList.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.ID Property (Outlook)

 Copy code hover
[image]

AddressList.ID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique identifier for the object. Read-only.

Syntax

expression .ID

expression A variable that represents an AddressList object.

Remarks

The transport provider assigns a permanent, unique string ID property when an individual member object is created. These identifiers do not change from one session to another.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Index Property (Outlook)

 Copy code hover
[image]

AddressList.Index Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the position of the object within the collection. Read-only.

Syntax

expression .Index

expression A variable that represents an AddressList object.

Remarks

The Index property is only valid during the current session and can change as objects are added to and deleted from the collection. The first object in the collection has an Index value of 1.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.IsInitialAddressList Property (Outlook)

 Copy code hover
[image]

AddressList.IsInitialAddressList Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the AddressList is the initial AddressList shown in the Select Names dialog. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsInitialAddressList

expression A variable that represents an AddressList object.

Remarks

IsInitialAddressList corresponds to setting Show this address list first in the Addressing dialog box, which is available by clicking Tools, and then Options in the Address Book dialog box.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.IsReadOnly Property (Outlook)

 Copy code hover
[image]

AddressList.IsReadOnly Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates that the AddressList object cannot be modified. Read-only.

Syntax

expression .IsReadOnly

expression A variable that represents an AddressList object.

Remarks

The IsReadOnly property refers to adding and deleting the entries in the address book container represented by the AddressList object. The property is True if no entries can be added or deleted. The property is False if the container can be modified, that is, if address entries can be added to and deleted from the container. It refers to the address book entries in the context of the address book container. It does not indicate whether the contents of the individual entries themselves can be modified.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Name Property (Outlook)

 Copy code hover
[image]

AddressList.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Parent Property (Outlook)

 Copy code hover
[image]

AddressList.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

AddressList.PropertyAccessor Property (Outlook)
See also Send feedback

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AddressList object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an AddressList object.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.ResolutionOrder Property (Outlook)

 Copy code hover
[image]

AddressList.ResolutionOrder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Integer that represents the order of this AddressList in the custom scroll list in the Addressing dialog box. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ResolutionOrder

expression A variable that represents an AddressList object.

Remarks

The ResolutionOrder property corresponds to the position of the AddressList in the list box which is labeled When sending mail, check address lists in this order in the Addressing dialog box and is available by clicking Tools, and then Options in the Address Book dialog box. Note that this behavior is independent of whether Custom is selected in the Addressing dialog box. For example, if Start with Global Address List is selected and the scroll list displays Contacts as the first item, the ResolutionOrder property of the Contacts address list is still 1, even though when resolving recipients, Outlook uses the Global Address List first.

When Custom is selected in the Addressing dialog box, the ResolutionOrder property reflects the order that Outlook uses when resolving recipient names. The value of ResolutionOrder is one-based. In this case, the first address list to be used for resolving recipient names has a ResolutionOrder equal to 1, the second address list 2, and so forth. If an address list is not used to resolve addresses, then its ResolutionOrder has a value of -1. Programmatically, when Custom is selected in the Addressing dialog box, the ResolutionOrder property reflects the actual resolution order that Recipients.ResolveAll or Recipient.Resolve uses.

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList.Session Property (Outlook)

 Copy code hover
[image]

AddressList.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AddressList object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressList Methods (Outlook)

 Copy code hover
[image]

AddressList Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
GetContactsFolder | Obtains a Folder object that represents the Contacts folder for the AddressList object.


AddressList.GetContactsFolder Method (Outlook)

 Copy code hover
[image]

AddressList.GetContactsFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Folder object that represents the Contacts folder for the AddressList object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetContactsFolder

expression A variable that represents an AddressList object.

Return Value

A Folder object that represents the Outlook Contacts folder for the AddressList. Returns Null (Nothing in Visual Basic) if no Outlook contacts folder is found.

Remarks

This method allows you to match an AddressList for the Contacts folder that you would like to set up as the initial address list in the Select Names dialog box.

Example

The following code sample shows you how to initialize the Select Names dialog box with the AddressList for the default Contacts folder. It first obtains the Folder object for the default Contacts folder, and looks for its AddressList by comparing the Entry ID of this Folder object with the Entry ID of the Folder object assoicated with each AddressList in the current session until it finds a match. It then sets the InitialAddressList property and displays the Select Names dialog box.

Copy code Copy code
Sub SetContactsFolderAsInitialAddressList()

 Dim oMsg As MailItem

 Set oMsg = Application.CreateItem(olMailItem)

 Dim oDialog As SelectNamesDialog

 Set oDialog = Application.Session.GetSelectNamesDialog

 Dim oAL As AddressList

 Dim oContacts As Folder

 Set oContacts = _

 Application.Session.GetDefaultFolder(olFolderContacts)

 On Error GoTo HandleError

 'Look for the AddressList for the default Contacts folder

 For Each oAL In Application.Session.AddressLists

 If oAL.AddressListType = olOutlookAddressList Then

 If oAL.GetContactsFolder.EntryID = _

 oContacts.EntryID Then

 Exit For

 End If

 End If

 Next

 With oDialog

 .Caption = "Select Customer Contact"

 .ToLabel = "Customer C&ontact"

 .NumberOfRecipientSelectors = olShowTo

 .InitialAddressList = oAL

 'Let the selected names be the recipients of the new message

 .Recipients = oMsg.Recipients

 If .Display Then

 'Recipients Resolved

 End If

 End With

HandleError:

 Exit Sub

End Sub

See also

Concepts

AddressList Object

Other resources

AddressList Object Members


AddressLists Object (Outlook)

 Copy code hover
[image]

AddressLists Object (Outlook)
See also Send feedback

Contains a set of AddressList objects.

Remarks

The AddressLists collection provides access to the root of the transport provider's address book hierarchy for the current session.

Example

The following example sets a reference to the AddressLists object.

Copy code Copy code
Set myAddressLists = myNameSpace.AddressLists

See also

Concepts

Outlook Object Model Reference

Other resources

AddressLists Object Members


AddressLists Members (Outlook)

 Copy code hover
[image]

AddressLists Members (Outlook)
Send feedback

Contains a set of AddressList objects.

Methods

Name | Description
Item | Returns an AddressList object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressLists Properties (Outlook)

 Copy code hover
[image]

AddressLists Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressLists.Application Property (Outlook)

 Copy code hover
[image]

AddressLists.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AddressLists object.

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressLists.Class Property (Outlook)

 Copy code hover
[image]

AddressLists.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AddressLists object.

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressLists.Count Property (Outlook)

 Copy code hover
[image]

AddressLists.Count Property (Outlook)
See also Send feedback

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an AddressLists object.

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressLists.Parent Property (Outlook)

 Copy code hover
[image]

AddressLists.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AddressLists object.

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressLists.Session Property (Outlook)

 Copy code hover
[image]

AddressLists.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AddressLists object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressLists Methods (Outlook)

 Copy code hover
[image]

AddressLists Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Item | Returns an AddressList object from the collection.


AddressLists.Item Method (Outlook)

 Copy code hover
[image]

AddressLists.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressList object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an AddressLists object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An AddressList object that represents the specified object.

See also

Concepts

AddressLists Object

Other resources

AddressLists Object Members


AddressRuleCondition Object (Outlook)

 Copy code hover
[image]

AddressRuleCondition Object (Outlook)
See also Send feedback

Represents a rule condition that evaluates whether the address for the recipient or sender of the message is contained in the address specified in AddressRuleCondition.Address.

Version Information

Version Added: Outlook 2007

Remarks

AddressRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has a RecipientAddress property and a SenderAddress. Each of these properties always returns a AddressRuleCondition object. AddressRuleCondition.ConditionType distinguishes among these rule conditions. If the rule has any of these rule conditions enabled, then AddressRuleCondition.Enabled would be True.

For more information on specifying rule actions, see Specifying Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

AddressRuleCondition Object Members


AddressRuleCondition Members (Outlook)

 Copy code hover
[image]

AddressRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether the address for the recipient or sender of the message is contained in the address specified in AddressRuleCondition.Address.

Properties

Name | Description
Address | Returns or sets an array of String elements to evaluate the address rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressRuleCondition Properties (Outlook)

 Copy code hover
[image]

AddressRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Address | Returns or sets an array of String elements to evaluate the address rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AddressRuleCondition.Address Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an array of String elements to evaluate the address rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Address

expression A variable that represents an AddressRuleCondition object.

Remarks

You can assign an array with one element to evaluate a single address or an array of multiple strings to evaluate multiple addresses. Multiple address strings assigned in an array are evaluated using the logical OR operation.

If a string specified by Address is contained in the recipient or sender address, the condition evaluates to True.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an AddressRuleCondition object.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an AddressRuleCondition object.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents an AddressRuleCondition object.

Remarks

The AddressRuleCondition object is used by rules of types olRuleSend and olRuleReceive. If the rule is created as an olRuleSend rule, then the type of the associated AddressRuleCondition object will be olConditionSenderAddress. If the rule is created as an olRuleReceive rule, then the type of the associated AddressRuleCondition object will be olConditionRecipientAddress.

This however does not mean that the rule always has a defined rule condition for sender or recipient addresses. Regardless of whether there exists such a defined or enabled rule condition, the AddressRuleCondition.ConditionType property is always initialized once the associated rule is created. For more information on rule conditions, see Specify Rule Conditions.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an AddressRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it have been saved successfully.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an AddressRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


AddressRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

AddressRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an AddressRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AddressRuleCondition Object

Other resources

AddressRuleCondition Object Members


Application Object (Outlook)

 Copy code hover
[image]

Application Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the entire Microsoft Outlook application.

Remarks

This is the only object in the hierarchy that can be returned by using the CreateObject method or the intrinsic Visual Basic GetObject function.

The Outlook Application object has several purposes:

  • As the root object, it allows access to other objects in the Outlook hierarchy.

  • It allows direct access to a new item created by using CreateItem, without having to traverse the object hierarchy.

  • It allows access to the active interface objects (the explorer and the inspector).

When you use Automation to control Outlook from another application, you use the CreateObject method to create an Outlook Application object.

Example

The following Visual Basic for Applications (VBA) example starts Outlook (if it's not already running) and opens the default Inbox folder.

VBA Copy code Copy code
Set myNameSpace = Application.GetNameSpace("MAPI")

Set myFolder= _

 myNameSpace.GetDefaultFolder(olFolderInbox)

myFolder.Display

The following Visual Basic for Applications (VBA) example uses the Application object to create and open a new contact.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olContactItem)

myItem.Display

See also

Concepts

Outlook Object Model Reference

Other resources

Application Object Members


Application Members (Outlook)

 Copy code hover
[image]

Application Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the entire Microsoft Outlook application.

Events

Name | Description
AdvancedSearchComplete | Occurs when the AdvancedSearch method has completed.
AdvancedSearchStopped | Occurs when a specified Search object's Stop method has been executed.
BeforeFolderSharingDialog | Occurs before the Sharing dialog box is displayed for a selected Folder object.
ItemLoad | Occurs when an Outlook item is loaded into memory.
ItemSend | Occurs whenever an Microsoft Outlook item is sent, either by the user through an Inspector (before the inspector is closed, but after the user clicks the Send button) or when the Send method for an Outlook item, such as MailItem, is used in a program.
MAPILogonComplete | Occurs after the user has logged onto the system.
NewMail | Occurs when one or more new e-mail messages are received in the Inbox.
NewMailEx | Occurs when a new item is received in the Inbox.
OptionsPagesAdd | Occurs whenever the user clicks the Add-in Options button on the Add-ins tab of the Outlook Options dialog box.
Quit | Occurs when Microsoft Outlook begins to close.
Reminder | Occurs immediately before a reminder is displayed.
Startup | Occurs when Microsoft Outlook is starting, but after all add-in programs have been loaded.

Methods

Name | Description
ActiveExplorer | Returns the topmost Explorer object on the desktop.
ActiveInspector | Returns the topmost Inspector object on the desktop.
ActiveWindow | Returns an object representing the current Microsoft Outlook window on the desktop, either an Explorer or an Inspector object.
AdvancedSearch | Performs a search based on a specified DAV Searching and Locating (DASL) search string.
CopyFile | Copies a file from a specified location into a Microsoft Outlook store.
CreateItem | Creates and returns a new Microsoft Outlook item.
CreateItemFromTemplate | Creates a new Microsoft Outlook item from an Outlook template (.oft) and returns the new item.
CreateObject | Creates an automation object of the specified class.
GetNamespace | Returns a NameSpace object of the specified type.
GetObjectReference | Creates a strong or weak object reference for a specified Outlook object.
IsSearchSynchronous | Returns a Boolean indicating if a search will be synchronous or asynchronous.
Quit | Closes all currently open windows.
RefreshFormRegionDefinition | Refreshes the cache by obtaining the current definition from the Windows registry for one or all of the form regions that are defined for the local machine and the current user.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Assistance | Returns an IAssistance object used to invoke help. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
COMAddIns | Returns a COMAddIns collection that represents all the Component Object Model (COM) add-ins currently loaded in Microsoft Outlook.
DefaultProfileName | Returns a String representing the name of the default profile name. Read-only.
Explorers | Returns an Explorers collection object that contains the Explorer objects representing all open explorers. Read-only.
Inspectors | Returns an Inspectors collection object that contains the Inspector objects representing all open inspectors. Read-only.
IsTrusted | Returns a Boolean to indicate if an add-in or external caller is considered trusted by Outlook. Read-only
LanguageSettings | Returns a LanguageSettings object for the application that contains the language-specific attributes of Outlook. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PickerDialog | Returns a PickerDialog object that provides the functionality to select people or data in a dialog box. Read-only.
ProductCode | Returns a String specifying the Microsoft Outlook globally unique identifier (GUID). Read-only.
Reminders | Returns a Reminders collection that represents all current reminders. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
TimeZones | Returns a TimeZones collection that represents the set of time zones supported by Outlook. Read-only.
Version | Returns or sets a String indicating the number of the version. Read-only.


Application Properties (Outlook)

 Copy code hover
[image]

Application Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Assistance | Returns an IAssistance object used to invoke help. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
COMAddIns | Returns a COMAddIns collection that represents all the Component Object Model (COM) add-ins currently loaded in Microsoft Outlook.
DefaultProfileName | Returns a String representing the name of the default profile name. Read-only.
Explorers | Returns an Explorers collection object that contains the Explorer objects representing all open explorers. Read-only.
Inspectors | Returns an Inspectors collection object that contains the Inspector objects representing all open inspectors. Read-only.
IsTrusted | Returns a Boolean to indicate if an add-in or external caller is considered trusted by Outlook. Read-only
LanguageSettings | Returns a LanguageSettings object for the application that contains the language-specific attributes of Outlook. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PickerDialog | Returns a PickerDialog object that provides the functionality to select people or data in a dialog box. Read-only.
ProductCode | Returns a String specifying the Microsoft Outlook globally unique identifier (GUID). Read-only.
Reminders | Returns a Reminders collection that represents all current reminders. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
TimeZones | Returns a TimeZones collection that represents the set of time zones supported by Outlook. Read-only.
Version | Returns or sets a String indicating the number of the version. Read-only.


Application.Application Property (Outlook)

 Copy code hover
[image]

Application.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Assistance Property (Outlook)

 Copy code hover
[image]

Application.Assistance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an IAssistance object used to invoke help. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Assistance

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Class Property (Outlook)

 Copy code hover
[image]

Application.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.COMAddIns Property (Outlook)

 Copy code hover
[image]

Application.COMAddIns Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a COMAddIns collection that represents all the Component Object Model (COM) add-ins currently loaded in Microsoft Outlook.

Syntax

expression .COMAddIns

expression A variable that represents an Application object.

Example

This Microsoft Visual Basic for Applications (VBA) example displays the number of COM add-ins currently loaded.

VBA Copy code Copy code
Private Sub CountCOMAddins()

 MsgBox "There are " & _

 Application.COMAddIns.Count & " COM add-ins."

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.DefaultProfileName Property (Outlook)

 Copy code hover
[image]

Application.DefaultProfileName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the name of the default profile name. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultProfileName

expression A variable that represents an Application object.

Remarks

Returns an empty string if no profile has been configured or if there is no default profile for Outlook.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Explorers Property (Outlook)

 Copy code hover
[image]

Application.Explorers Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Explorers collection object that contains the Explorer objects representing all open explorers. Read-only.

Syntax

expression .Explorers

expression A variable that represents an Application object.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the number of explorer windows that are open.

VBA Copy code Copy code
Private Sub CountExplorers()

 MsgBox "There are " & _

 Application.Explorers.Count & " Explorers."

End Sub

The following VBA example uses the Count property and Item method of the Selection collection returned by the Selection property to display the senders of all mail items selected in the explorer that displays the Inbox. To run this example, you need to have at least one mail item selected in the explorer displaying the Inbox. You might receive an error if you select items other than a mail item such as task request as the SenderName property does not exist for a TaskRequestItem object.

VBA Copy code Copy code
Sub GetSelectedItems()

 Dim myOlExp As Outlook.Explorer

 Dim myOlSel As Outlook.Selection

 Dim MsgTxt As String

 Dim x As Integer

 MsgTxt = "You have selected items from: "

 Set myOlExp = Application.Explorers.Item(1)

 If myOlExp = "Inbox" Then

 Set myOlSel = myOlExp.Selection

 For x = 1 To myOlSel.Count

 MsgTxt = MsgTxt & myOlSel.Item(x).SenderName & ";"

 Next x

 MsgBox MsgTxt

End If

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Inspectors Property (Outlook)

 Copy code hover
[image]

Application.Inspectors Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspectors collection object that contains the Inspector objects representing all open inspectors. Read-only.

Syntax

expression .Inspectors

expression A variable that represents an Application object.

Example

This Microsoft Visual Basic example uses the Inspectors property and the Count property and Item method of the Inspectors object to display the captions of all inspector windows.

VBA Copy code Copy code
Private Sub CommandButton1_Click()

 Dim myInspectors As Outlook.Inspectors

 Dim x as Integer

 Dim iCount As Integer

 Set myInspectors = Application.Inspectors

 iCount = Application.Inspectors.Count

 If iCount > 0 Then

 For x = 1 To iCount

 MsgBox myInspectors.Item(x).Caption

 Next x

 Else

 MsgBox "No inspector windows are open."

 End If

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.IsTrusted Property (Outlook)

 Copy code hover
[image]

Application.IsTrusted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean to indicate if an add-in or external caller is considered trusted by Outlook. Read-only

Version Information

Version Added: Outlook 2007

Syntax

expression .IsTrusted

expression A variable that represents an Application object.

Remarks

For out-of-process callers that have instantiated the Application object, IsTrusted always returns False. For Outlook add-ins, IsTrusted returns True if and only if the add-in is considered trusted by Outlook.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.LanguageSettings Property (Outlook)

 Copy code hover
[image]

Application.LanguageSettings Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a LanguageSettings object for the application that contains the language-specific attributes of Outlook. Read-only.

Syntax

expression .LanguageSettings

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Name Property (Outlook)

 Copy code hover
[image]

Application.Name Property (Outlook)
See also Send feedback

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Parent Property (Outlook)

 Copy code hover
[image]

Application.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.PickerDialog Property (Outlook)

 Copy code hover
[image]

Application.PickerDialog Property (Outlook)
See also Send feedback

Returns a PickerDialog object that provides the functionality to select people or data in a dialog box. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .PickerDialog

expression A variable that represents an Application object.

Remarks

The PickerDialog object is available in the Microsoft Office type library. For more information, see the following objects and their members:

  • PickerDialog

  • PickerField

  • PickerFields

  • PickerProperties

  • PickerProperty

  • PickerResult

  • PickerResults

See also

Concepts

Application Object

Other resources

Application Object Members


Application.ProductCode Property (Outlook)

 Copy code hover
[image]

Application.ProductCode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String specifying the Microsoft Outlook globally unique identifier (GUID). Read-only.

Syntax

expression .ProductCode

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Reminders Property (Outlook)

 Copy code hover
[image]

Application.Reminders Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Reminders collection that represents all current reminders. Read-only.

Syntax

expression .Reminders

expression A variable that represents an Application object.

Example

The following example returns the Reminders collection and displays the captions of all reminders in the collection. If no current reminders are available, a message is displayed to the user.

VBA Copy code Copy code
Sub ViewReminderInfo()

 'Lists reminder caption information

 Dim objRem As Outlook.Reminder

 Dim objRems As Outlook.Reminders

 Dim strTitle As String

 Dim strReport As String

 Set objRems = Application.Reminders

 strTitle = "Current Reminders:"

 strReport = ""

 'If there are reminders, display message

 If Application.Reminders.Count <> 0 Then

 For Each objRem In objRems

 'Add information to string

 strReport = strReport & objRem.Caption & vbCr

 Next objRem

 'Display report in dialog

 MsgBox strTitle & vbCr & vbCr & strReport

 Else

 MsgBox "There are no reminders in the collection."

 End If

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Session Property (Outlook)

 Copy code hover
[image]

Application.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Application object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Application Object

Other resources

Application Object Members


Application.TimeZones Property (Outlook)

 Copy code hover
[image]

Application.TimeZones Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TimeZones collection that represents the set of time zones supported by Outlook. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .TimeZones

expression A variable that represents an Application object.

Remarks

The set of time zones supported by Outlook is based on the data stored in the Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Version Property (Outlook)

 Copy code hover
[image]

Application.Version Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the number of the version. Read-only.

Syntax

expression .Version

expression A variable that represents an Application object.

See also

Concepts

Application Object

Other resources

Application Object Members


Application Methods (Outlook)

 Copy code hover
[image]

Application Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
ActiveExplorer | Returns the topmost Explorer object on the desktop.
ActiveInspector | Returns the topmost Inspector object on the desktop.
ActiveWindow | Returns an object representing the current Microsoft Outlook window on the desktop, either an Explorer or an Inspector object.
AdvancedSearch | Performs a search based on a specified DAV Searching and Locating (DASL) search string.
CopyFile | Copies a file from a specified location into a Microsoft Outlook store.
CreateItem | Creates and returns a new Microsoft Outlook item.
CreateItemFromTemplate | Creates a new Microsoft Outlook item from an Outlook template (.oft) and returns the new item.
CreateObject | Creates an automation object of the specified class.
GetNamespace | Returns a NameSpace object of the specified type.
GetObjectReference | Creates a strong or weak object reference for a specified Outlook object.
IsSearchSynchronous | Returns a Boolean indicating if a search will be synchronous or asynchronous.
Quit | Closes all currently open windows.
RefreshFormRegionDefinition | Refreshes the cache by obtaining the current definition from the Windows registry for one or all of the form regions that are defined for the local machine and the current user.


Application.ActiveExplorer Method (Outlook)

 Copy code hover
[image]

Application.ActiveExplorer Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the topmost Explorer object on the desktop.

Syntax

expression .ActiveExplorer

expression A variable that represents an Application object.

Return Value

An Explorer that represents the topmost explorer on the desktop. Returns Nothing if no explorer is active.

Remarks

Use this method to return the Explorer object that the user is most likely viewing. This method is also useful for determining when there is no active explorer, so a new one can be opened.

Example

The following Microsoft Visual Basic for Applications (VBA) example uses the Count property and Item method of the Selection collection returned by the Selection property to display the senders of all mail items selected in the active explorer window. To run this example, you need to have at least one mail item selected in the active Explorer window.

Note Note

You might receive an error if you select items other than a mail item such as task request as the SenderName property does not exist for a TaskRequestItem object.

VBA Copy code Copy code
Sub GetSelectedItems()

 Dim myOlExp As Outlook.Explorer

 Dim myOlSel As Outlook.Selection

 Dim MsgTxt As String

 Dim x As Integer

 MsgTxt = "You have selected items from: "

 Set myOlExp = Application.ActiveExplorer

 Set myOlSel = myOlExp.Selection

 For x = 1 To myOlSel.Count

 MsgTxt = MsgTxt & myOlSel.Item(x).SenderName & ";"

 Next x

 MsgBox MsgTxt

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.ActiveInspector Method (Outlook)

 Copy code hover
[image]

Application.ActiveInspector Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the topmost Inspector object on the desktop.

Syntax

expression .ActiveInspector

expression A variable that represents an Application object.

Return Value

An Inspector that represents the topmost inspector on the desktop.

Remarks

Use this method to access the Inspector object that the user is most likely to be viewing.

If no inspector is active, returns Nothing.

Example

This Visual Basic for Applications (VBA) example uses the ActiveInspector method to obtain the currently active Inspector object. The example saves and closes the item displayed in the active inspector without prompting the user. To run this example, you need to have an item displayed in an inspector window.

VBA Copy code Copy code
Sub CloseItem()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Set myinspector = Application.ActiveInspector

 Set myItem = myinspector.CurrentItem

 myItem.Close olSave

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.ActiveWindow Method (Outlook)

 Copy code hover
[image]

Application.ActiveWindow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an object representing the current Microsoft Outlook window on the desktop, either an Explorer or an Inspector object.

Syntax

expression .ActiveWindow

expression A variable that represents an Application object.

Return Value

An Object that represents the current Outlook window on the desktop. Returns Nothing if no Outlook explorer or inspector is open.

Example

This Microsoft Visual Basic for Applications (VBA) example minimizes the topmost Outlook window if it is an inspector window.

VBA Copy code Copy code
Sub MinimizeActiveWindow()

 If TypeName(Application.ActiveWindow) = "Inspector" Then

 Application.ActiveWindow.WindowState = olMinimized

 End If

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.AdvancedSearch Method (Outlook)

 Copy code hover
[image]

Application.AdvancedSearch Method (Outlook)
See also Send feedback

Published: July 16, 2012

Performs a search based on a specified DAV Searching and Locating (DASL) search string.

Syntax

expression .AdvancedSearch(Scope, Filter, SearchSubFolders, Tag)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Scope | Required | String | The scope of the search. For example, the folder path of a folder. It is recommended that the folder path is enclosed within single quotes. Otherwise, the search might not return correct results if the folder path contains special characters including Unicode characters. To specify multiple folder paths, enclose each folder path in single quotes and separate the single quoted folder paths with a comma.
Filter | Optional | Variant | The DASL search filter that defines the parameters of the search.
SearchSubFolders | Optional | Variant | Determines if the search will include any of the folder's subfolders.
Tag | Optional | Variant | The name given as an identifier for the search.

Return Value

A Search object that represents the results of the search.

Remarks

You can run multiple searches simultaneously by calling the AdvancedSearch method in successive lines of code. However, you should be aware that programmatically creating a large number of search folders can result in significant simultaneous search activity that would affect the performance of Outlook, especially if Outlook conducts the search in online Exchange mode.

The AdvancedSearch method and related features in the Outlook object model do not create a Search Folder that will appear in the Outlook user interface. However, you can use the Save method of the Search object that is returned to create a Search Folder that will appear in the Search Folders list in the Outlook user interface.

Using the Scope parameter, you can specify one or more folders in the same store, but you may not specify multiple folders in multiple stores. To specify multiple folders in the same store for the Scope parameter, use a comma character between each folder path and enclose each folder path in single quotes. For default folders such as Inbox or Sent Items, you can use the simple folder name instead of the full folder path. For example, the following two lines of code represent valid Scope parameters:

VBA Copy code Copy code
Scope = "'Inbox', 'Sent Items'"
VBA Copy code Copy code
Scope = "'" & Application.Session.GetDefaultFolder(olFolderInbox).FolderPath _
    & "','" & Application.Session.GetDefaultFolder(olFolderSentMail).FolderPath & "'"

The Filter parameter can be any valid DASL query. For additional information on DASL queries, see Filtering Items and Referencing Properties by Namespace. Note that you cannot use a JET query for the Filter parameter of Advanced Search. If Instant Search is enabled on a store that contains a folder specified in the Scope parameter, you can use Instant Search keywords to improve the performance of your search. If you use Instant Search keywords and Instant Search is not enabled, Outlook will return an error and your search will fail.

Example

The following Visual Basic for Applications (VBA) example searches the Inbox for items with subject equal to Test and displays the names of the senders of the e-mail items returned by the search. The AdvancedSearchComplete event procedure sets the boolean blnSearchComp to True when the search is complete. This boolean variable is used by the TestAdvancedSearchComplete() procedure to determine when the search is complete. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAdvancedSearchComplete() procedure must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)
    Debug.Print "The AdvancedSearchComplete Event fired"
    If SearchObject.Tag = "Test" Then
        m_SearchComplete = True
    End If

End Sub

Sub TestAdvancedSearchComplete()
    Dim sch As Outlook.Search
    Dim rsts As Outlook.Results
    Dim i As Integer
    blnSearchComp = False
    Const strF As String = "urn:schemas:mailheader:subject = 'Test'"
    Const strS As String = "Inbox"
    Set sch = Application.AdvancedSearch(strS, strF, "Test")
    While blnSearchComp = False
        DoEvents
    Wend
    Set rsts = sch.Results
    For i = 1 To rsts.Count
        Debug.Print rsts.Item(i).SenderName
    Next
End Sub

The following Microsoft Visual Basic for Applications example uses the AdvancedSearch method to create a new search. The parameters of the search, as specified by the Filter argument of the AdvancedSearch method, will return all items in the Inbox and Sent Items folders where the Subject phrase-matches or contains "Office". The user's Inbox and Sent Items folders are specified as the scope of the search and the SearchSubFolders property is set to True. When the search is complete, the GetTable method is called on the Search object for performant enumeration of search results.

VBA Copy code Copy code
Public m_SearchComplete As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)
    If SearchObject.Tag = "MySearch" Then
        m_SearchComplete = True
    End If
End Sub

Sub TestSearchForMultipleFolders()
    Dim Scope As String
    Dim Filter As String
    Dim MySearch As Outlook.Search
    Dim MyTable As Outlook.Table
    Dim nextRow As Outlook.Row
    m_SearchComplete = False
    'Establish scope for multiple folders
    Scope = "'" & Application.Session.GetDefaultFolder( _
    olFolderInbox).FolderPath _
    & "','" & Application.Session.GetDefaultFolder( _
    olFolderSentMail).FolderPath & "'"
    'Establish filter
    If Application.Session.DefaultStore.IsInstantSearchEnabled Then
        Filter = Chr(34) & "urn:schemas:httpmail:subject" _
        & Chr(34) & " ci_phrasematch 'Office'"
    Else
        Filter = Chr(34) & "urn:schemas:httpmail:subject" _
        & Chr(34) & " like '%Office%'"
    End If
    Set MySearch = Application.AdvancedSearch( _
    Scope, Filter, True, "MySearch")
    While m_SearchComplete <> True
        DoEvents
    Wend
    Set MyTable = MySearch.GetTable
    Do Until MyTable.EndOfTable
        Set nextRow = MyTable.GetNextRow()
        Debug.Print nextRow("Subject")
    Loop
End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.CopyFile Method (Outlook)

 Copy code hover
[image]

Application.CopyFile Method (Outlook)
See also Send feedback

Published: July 16, 2012

Copies a file from a specified location into a Microsoft Outlook store.

Syntax

expression .CopyFile(FilePath, DestFolderPath)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
FilePath | Required | String | The path name of the object you want to copy.
DestFolderPath | Required | String | The location you want to copy the file to.

Return Value

An Object value that represents the copied file.

Example

The following Visual Basic for Applications (VBA) example creates a Microsoft Excel worksheet called 'MyExcelDoc.xlsx' and then copies it from the user's hard drive to the user's Inbox.

VBA Copy code Copy code
Sub CopyFileSample()

 Dim strPath As String

 Dim ExcelApp As Object

 Dim ExcelSheet As Object

 Dim doc As Object

 Set ExcelApp = CreateObject("Excel.Application")

 strPath = ExcelApp.DefaultFilePath & "\MyExcelDoc.xlsx"

 Set ExcelSheet = ExcelApp.Workbooks.Add

 ExcelSheet.ActiveSheet.cells(1, 1).Value = 10

 ExcelSheet.SaveAs strPath

 ExcelApp.Quit

 Set ExcelApp = Nothing

 Set doc = Application.CopyFile(strPath, "Inbox")

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.CreateItem Method (Outlook)

 Copy code hover
[image]

Application.CreateItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates and returns a new Microsoft Outlook item.

Syntax

expression .CreateItem(ItemType)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
ItemType | Required | OlItemType | The Outlook item type for the new item.

Return Value

An Object value that represents the new Outlook item.

Remarks

The CreateItem method can only create default Outlook items. To create new items using a custom form, use the Add method on the Items collection.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new MailItem object and sets the BodyFormat property to olFormatHTML. The Body text of the e-mail item will now appear in HTML format.

VBA Copy code Copy code
Sub CreateHTMLMail()

 'Creates a new e-mail item and modifies its properties

 Dim objMail As Outlook.MailItem

 'Create e-mail item

 Set objMail = Application.CreateItem(olMailItem)

 With objMail

 'Set body format to HTML

 .BodyFormat = olFormatHTML

 .HTMLBody = "<HTML><H2>The body of this message will appear in HTML.</H2><BODY> Please enter the message text here. </BODY></HTML>"

 .Display

 End With

End Sub

See also

Concepts

Application Object
How to: Import Appointment XML Data into Outlook Appointment Objects

Other resources

Application Object Members


Application.CreateItemFromTemplate Method (Outlook)

 Copy code hover
[image]

Application.CreateItemFromTemplate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new Microsoft Outlook item from an Outlook template (.oft) and returns the new item.

Syntax

expression .CreateItemFromTemplate(TemplatePath, InFolder)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
TemplatePath | Required | String | The path and file name of the Outlook template for the new item.
InFolder | Optional | Variant | The folder in which the item is to be created. If this argument is omitted, the default folder for the item type will be used.

Return Value

An Object value that represents the new Outlook item.

Remarks

New items will always open in compose mode, as opposed to read mode, regardless of the mode in which the items were saved to disk.

Example

This Visual Basic for Applications (VBA) example uses CreateItemFromTemplate to create a new item from an Outlook template and then displays it. The CreateTemplate macro shows you how to create the template that is used in the first example. To avoid errors, replace 'Dan Wilson' with a valid name in your address book.

VBA Copy code Copy code
Sub CreateFromTemplate()
 Dim MyItem As Outlook.MailItem

 Set MyItem = Application.CreateItemFromTemplate("C:\statusrep.oft")
 MyItem.Display
End Sub

Sub CreateTemplate()
 Dim MyItem As Outlook.MailItem

 Set MyItem = Application.CreateItem(olMailItem)
 MyItem.Subject = "Status Report"
 MyItem.To = "Dan Wilson"
 MyItem.Display
 MyItem.SaveAs "C:\statusrep.oft", OlSaveAsType.olTemplate
End Sub

The following Visual Basic for Applications (VBA) example shows how to use the optional InFolder parameter when calling the CreateItemFromTemplate method.

VBA Copy code Copy code
Sub CreateFromTemplate2()
 Dim MyItem As Outlook.MailItem

 Set MyItem = Application.CreateItemFromTemplate("C:\statusrep.oft", _
 Application.Session.GetDefaultFolder(olFolderDrafts))
 MyItem.Save
End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.CreateObject Method (Outlook)

 Copy code hover
[image]

Application.CreateObject Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates an automation object of the specified class.

Syntax

expression .CreateObject(ObjectName)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
ObjectName | Required | String | The class name of the object to create. For information about valid class names, see OLE Programmatic Identifiers.

Return Value

An Object value that represents the new Automation object instance. If the application is already running, CreateObject will create a new instance.

Remarks

This method is provided so that other applications can be automated from Microsoft Visual Basic Scripting Edition (VBScript) 1.0, which did not include a CreateObject method. CreateObject has been included in VBScript version 2.0 and later. This method should not be used to automate Microsoft Outlook from VBScript.

Note Note

The CreateObject methods commonly used in the example code within this Help file (available when you click "Example") are made available by Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA). These examples do not use the same CreateObject method that is implemented as part of the object model in Outlook.

Example

This VBScript example uses the Open event of the item to access Windows Internet Explorer and display the Web page.

Copy code Copy code
Sub Item_Open()

 Set Web = CreateObject("InternetExplorer.Application")

 Web.Visible = True

 Web.Navigate "www.microsoft.com"

End Sub

This VBScript example uses the Click event of a CommandButton control on the item to access Microsoft Word and open a document in the root directory named "Resume.doc".

Copy code Copy code
Sub CommandButton1_Click()

 Set Word = Application.CreateObject("Word.Application")

 Word.Visible = True

 Word.Documents.Open("C:\Resume.doc")

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.GetNamespace Method (Outlook)

 Copy code hover
[image]

Application.GetNamespace Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NameSpace object of the specified type.

Syntax

expression .GetNamespace(Type)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Type | Required | String | The type of name space to return.

Return Value

A NameSpace object that represents the specified namespace.

Remarks

The only supported name space type is "MAPI". The GetNameSpace method is functionally equivalent to the Session property.

Example

This Visual Basic for Applications (VBA) example uses the CurrentFolder property to change the displayed folder to the user's Calendar folder.

VBA Copy code Copy code
Sub ChangeCurrentFolder()

 Dim myNamespace As Outlook.NameSpace

 Set myNamespace = Application.GetNamespace("MAPI")

 Set Application.ActiveExplorer.CurrentFolder = _

 myNamespace.GetDefaultFolder(olFolderCalendar)

End Sub

See also

Concepts

How to: Obtain and Log On to an Instance of Outlook
Application Object

Other resources

Application Object Members


Application.GetObjectReference Method (Outlook)

 Copy code hover
[image]

Application.GetObjectReference Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a strong or weak object reference for a specified Outlook object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetObjectReference(Item, ReferenceType)

expression An expression that returns an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The object from which to obtain a strong or weak object reference.
ReferenceType | Required | OlReferenceType | The type of object reference.

Return Value

An Object that represents a strong or weak object reference for the specified object.

Remarks

This method returns a weak or strong object reference for the object specified in Item.

Note Note

Outlook can fail to close successfully if an add-in retains strong object references. Always dereference a strong object reference once it is no longer needed by the add-in.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.IsSearchSynchronous Method (Outlook)

 Copy code hover
[image]

Application.IsSearchSynchronous Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean indicating if a search will be synchronous or asynchronous.

Syntax

expression .IsSearchSynchronous(LookInFolders)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
LookInFolders | Required | String | The path name of the folders that the search will search through. You must enclose the folder path with single quotes.

Return Value

True if the search is synchronous; otherwise, False.

Remarks

If the search is synchronous, the AdvancedSearch method will not return until the search has completed. Conversely, if the search is asynchronous, the AdvancedSearch method will immediately return. In order to get meaningful results from an asynchronous search, use the AdvancedSearchComplete event to notify you when the search has finished.

Example

VBA Copy code Copy code
Sub TestStoresForSynchronousSearch()

 Dim folderPath As String

 Dim oStore As Outlook.Store

 For Each oStore In Outlook.Session.Stores

 folderPath = "'" & oStore.GetRootFolder.folderPath & "'"

 Debug.Print folderPath & " IsSearchSynchronous = " & _

 Application.IsSearchSynchronous(folderPath)

 Next

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Quit Method (Outlook)

 Copy code hover
[image]

Application.Quit Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes all currently open windows.

Syntax

expression .Quit

expression An expression that returns an Application object.

Remarks

The associated Outlook session is closed completely; the user is logged out of the messaging system and any changes to items not already saved are discarded.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.RefreshFormRegionDefinition Method (Outlook)

 Copy code hover
[image]

Application.RefreshFormRegionDefinition Method (Outlook)
See also Send feedback

Published: July 16, 2012

Refreshes the cache by obtaining the current definition from the Windows registry for one or all of the form regions that are defined for the local machine and the current user.

Version Information

Version Added: Outlook 2010

Syntax

expression .RefreshFormRegionDefinition(RegionName)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
RegionName | Required | String | The internal name of the form region whose definition you want to refresh in the cache. To refresh all form region definitions, specify an empty string.

Remarks

When Outlook starts, it reads the Windows registry to obtain a list of form regions and their definitions, and then caches the data. The definitions are stored in the registry under the local machine key (as HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\FormRegions) and under the current user key (as HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions). The definitions describe the layout, behavior, and other characteristics of each form region. If you register a form region or modify the definition of a form region after Outlook starts, you can use the RefreshFormRegionDefinition method to instruct Outlook to obtain the updated information.

The RegionName argument should match the InternalName property of the form region whose definition you are refreshing. The internal name of a form region supports only ASCII characters. If you specify an empty string, Outlook reads the Windows registry to obtain definitions for all of the form regions that are defined for the local machine and the current user.

For more information about registering form regions, see Specifying Form Regions in the Windows Registry.

See also

Concepts

Application Object

Other resources

Application Object Members


Application Events (Outlook)

 Copy code hover
[image]

Application Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AdvancedSearchComplete | Occurs when the AdvancedSearch method has completed.
AdvancedSearchStopped | Occurs when a specified Search object's Stop method has been executed.
BeforeFolderSharingDialog | Occurs before the Sharing dialog box is displayed for a selected Folder object.
ItemLoad | Occurs when an Outlook item is loaded into memory.
ItemSend | Occurs whenever an Microsoft Outlook item is sent, either by the user through an Inspector (before the inspector is closed, but after the user clicks the Send button) or when the Send method for an Outlook item, such as MailItem, is used in a program.
MAPILogonComplete | Occurs after the user has logged onto the system.
NewMail | Occurs when one or more new e-mail messages are received in the Inbox.
NewMailEx | Occurs when a new item is received in the Inbox.
OptionsPagesAdd | Occurs whenever the user clicks the Add-in Options button on the Add-ins tab of the Outlook Options dialog box.
Quit | Occurs when Microsoft Outlook begins to close.
Reminder | Occurs immediately before a reminder is displayed.
Startup | Occurs when Microsoft Outlook is starting, but after all add-in programs have been loaded.


Application.AdvancedSearchComplete Event (Outlook)

 Copy code hover
[image]

Application.AdvancedSearchComplete Event (Outlook)
See also Send feedback

Occurs when the AdvancedSearch method has completed.

Syntax

expression .AdvancedSearchComplete(SearchObject)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
SearchObject | Required | Search | The Search object returned by the AdvancedSearch method.

Remarks

The AdvancedSearchComplete event is used to return the object that was created by the AdvancedSearch method. This event only fires when the AdvancedSearch method is executed programmatically.

Example

The following Visual Basic for Applications (VBA) example searches the Inbox for items where the subject is equal to "Test" and displays the names of the senders of the e-mail items returned by the search. The AdvanceSearchComplete event procedure sets the boolean blnSearchComp to True when the search is complete. This boolean variable is used by the TestAdvancedSearchComplete() procedure to determine when the search is complete. The sample code must be placed in a class module such as ThisOutlookSession. The TestAdvancedSearchComplete() procedure must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired."

 blnSearchComp = True

End Sub

Sub TestAdvancedSearchComplete()

 Dim sch As Outlook.Search

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS As String = "Inbox"

 Set sch = Application.AdvancedSearch(strS, strF)

 While blnSearchComp = False

 DoEvents

 Wend

 Set rsts = sch.Results

 For i = 1 To rsts.Count

 MsgBox rsts.Item(i).SenderName

 Next

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.AdvancedSearchStopped Event (Outlook)

 Copy code hover
[image]

Application.AdvancedSearchStopped Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a specified Search object's Stop method has been executed.

Syntax

expression .AdvancedSearchStopped(SearchObject)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
SearchObject | Required | Search | The Search object returned by the AdvancedSearch method.

Remarks

After this event is fired, the Search object's Results collection will no longer be updated. This event can only be triggered programmatically.

Example

The following Visual Basic for Applications (VBA) example starts searching the Inbox for items with subject equal to "Test" and immediately stops the search. This causes the AdvanceSearchStopped event procedure to be run. The sample code must be placed in a class module such as ThisOutlookSession. The StopSearch() procedure must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Sub StopSearch()

 Dim sch As Outlook.Search

 Dim strScope As String

 Dim strFilter As String

 strScope = "Inbox"

 strFilter = "urn:schemas:httpmail:subject = 'Test'"

 Set sch = Application.AdvancedSearch(strScope, strFilter)

 sch.Stop

End Sub

Private Sub Application_AdvancedSearchStopped(ByVal SearchObject As Search)

 'Inform the user that the search has stopped.

 MsgBox "An AdvancedSearch has been interrupted and stopped. "

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.BeforeFolderSharingDialog Event (Outlook)

 Copy code hover
[image]

Application.BeforeFolderSharingDialog Event (Outlook)
See also Send feedback

Occurs before the Sharing dialog box is displayed for a selected Folder object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeFolderSharingDialog(FolderToShare, Cancel)

expression An expression that returns a Application object.

Parameters

Name | Required/Optional | Data Type | Description
FolderToShare | Required | Folder | The Folder object to be shared.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the dialog box is not displayed.

Remarks

This event provides an add-in with the capability of replacing the sharing user interface supplied by Outlook with a custom user interface. This event does not occur if a sharing message is programmatically created and displayed.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.ItemLoad Event (Outlook)

 Copy code hover
[image]

Application.ItemLoad Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an Outlook item is loaded into memory.

Version Information

Version Added: Outlook 2007

Syntax

expression .ItemLoad(Item, )

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | A weak object reference for the loaded Outlook item.

Remarks

This event occurs when the Outlook item begins to load into memory. Data for the item is not yet available, other than the values for the Class and MessageClass properties of the Outlook item, so an error occurs when calling any property other than Class or MessageClass for the Outlook item returned in Item. Similarly, an error occurs if you attempt to call any method from the Outlook item, or if you call the GetObjectReference method of the Application object on the Outlook item returned in Item.

The ItemLoad event should typically be implemented as a means to hook up item-level event handlers such as BeforeRead, Open, Send, and Write.

This event is not raised when the following conditions occur:

  • An Outlook item is synchronized with a folder.

  • A server-side rule is triggered for an Outlook item.

  • A reminder is triggered for an Outlook item.

  • A Desktop Alert is displayed for an Outlook item.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.ItemSend Event (Outlook)

 Copy code hover
[image]

Application.ItemSend Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs whenever an Microsoft Outlook item is sent, either by the user through an Inspector (before the inspector is closed, but after the user clicks the Send button) or when the Send method for an Outlook item, such as MailItem, is used in a program.

Syntax

expression .ItemSend(Item, Cancel)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being sent.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the send action is not completed and the inspector is left open.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example shows how to cancel the ItemSend event in response to user input. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myOlApp As Outlook.Application

Public Sub Initialize_handler()

 Set myOlApp = Outlook.Application

End Sub

Private Sub myOlApp_ItemSend(ByVal Item As Object, Cancel As Boolean)

 Dim prompt As String

 prompt = "Are you sure you want to send " & Item.Subject & "?"

 If MsgBox(prompt, vbYesNo + vbQuestion, "Sample") = vbNo Then

 Cancel = True

 End If

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.MAPILogonComplete Event (Outlook)

 Copy code hover
[image]

Application.MAPILogonComplete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user has logged onto the system.

Syntax

expression .MAPILogonComplete

expression A variable that represents an Application object.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays a message after the user has logged onto the system.

VBA Copy code Copy code
Private Sub Application_MAPILogonComplete()

'Occurs when a user has logged on

 MsgBox "Logon complete."

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.NewMail Event (Outlook)

 Copy code hover
[image]

Application.NewMail Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when one or more new e-mail messages are received in the Inbox.

Syntax

expression .NewMail

expression A variable that represents an Application object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

The NewMail event fires when new messages arrive in the Inbox and before client rule processing occurs. If you want to process items that arrive in the Inbox, consider using the ItemAdd event on the collection of items in the Inbox. The ItemAdd event passes a reference to each item that is added to a folder.

The NewMail event does not fire when the user is in offline mode.

Example

This Microsoft Visual Basic for Applications (VBA) example displays the Inbox folder when a new e-mail message arrives. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlApp As Outlook.Application

Sub Initialize_handler()

 Set myOlApp = Outlook.Application

End Sub

Private Sub myOlApp_NewMail()

 Dim myExplorers As Outlook.Explorers

 Dim myFolder As Outlook.Folder

 Dim x As Integer

 Set myExplorers = myOlApp.Explorers

 Set myFolder = myOlApp.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 If myExplorers.Count <> 0 Then

 For x = 1 To myExplorers.Count

 On Error GoTo skipif

 If myExplorers.Item(x).CurrentFolder.Name = "Inbox" Then

 myExplorers.Item(x).Display

 myExplorers.Item(x).Activate

 Exit Sub

 End If

skipif:

 Next x

 End If

 On Error GoTo 0

 myFolder.Display

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.NewMailEx Event (Outlook)

 Copy code hover
[image]

Application.NewMailEx Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a new item is received in the Inbox.

Syntax

expression .NewMailEx(EntryIDCollection)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
EntryIDCollection | Required | String | A string representing an Entry ID of an item received in the Inbox.

Remarks

This event fires once for every received item that is processed by Microsoft Outlook. The item can be one of several different item types, for example, MailItem, MeetingItem, or SharingItem. The EntryIDsCollection string contains the Entry ID that corresponds to that item. Note that this behavior has changed from earlier versions of the event when the EntryIDCollection contained a list of comma-delimited Entry IDs of all the items received in the Inbox since the last time the event was fired.

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

This event fires for e-mail accounts that provide notifications for received messages, such as Microsoft Exchange Server and POP3 accounts.

The NewMailEx event fires when a new message arrives in the Inbox and before client rule processing occurs. You can use the Entry ID returned in the EntryIDCollection array to call the NameSpace.GetItemFromID method and process the item. Use this method with caution to minimize the impact on Outlook performance. However, depending on the setup on the client computer, after a new message arrives in the Inbox, processes like spam filtering and client rules that move the new message from the Inbox to another folder can occur asynchronously. You should not assume that after these events fire, you will always get a one-item increase in the number of items in the Inbox.

For users with an Exchange Server account (non-Cached Exchange Mode or Cached Exchange Mode), the event will fire only for messages that arrive at the server after Outlook has started. The event will not fire for messages that are synchronized in Cached Exchange Mode immediately after Outlook starts, nor for messages that are already on the server when Outlook starts in non-Cached Exchange Mode.

For users using Cached Exchange Mode, the event will fire in all settings, provided that Outlook is running when the message is received: Download Full Items, Download Headers, and Download Headers and then Full Items.

See also

Concepts

Application Object

Other resources

Application Object Members


Application.OptionsPagesAdd Event (Outlook)

 Copy code hover
[image]

Application.OptionsPagesAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs whenever the user clicks the Add-in Options button on the Add-ins tab of the Outlook Options dialog box.

Syntax

expression .OptionsPagesAdd(Pages, Folder)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Pages | Required | PropertyPages | The collection of property pages that have been added to the dialog box. This collection includes only custom property pages. It does not include standard Microsoft Outlook property pages.
Folder | Required | PropertyPages | This argument is only used with the Folder object. The Folder object for which the Properties dialog box is being opened.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Your program handles this event to add a custom property page. The property page will be added to the Options dialog box. When the event fires, the PropertyPages collection object identified by Pages contains the property pages that have been added prior to the event handler being called. To add your property page to the collection, use the Add method of the PropertyPages collection before exiting the event handler.

Example

This Microsoft Visual Basic for Applications (VBA) example adds a new property page to the Outlook Options dialog box. The sample code must be placed in a class module of a Component Object Model (COM) add-in. For information about COM add-ins, see Customizing Outlook using COM add-ins.

VBA Copy code Copy code
Implements IDTExtensibility2
Private WithEvents OutlApp As Outlook.Application

Private Sub IDTExtensibility2_OnConnection(ByVal Application As Object, ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, ByVal AddInInst As Object, custom() As Variant)
 Set OutlApp = Outlook.Application
End Sub

Private Sub OutlApp_OptionsPagesAdd(ByVal Pages As Outlook.PropertyPages)
 Pages.Add "PPE.SimplePage", "Simple Page"
 'PPE.SimplePage is a ProgID of the registered ActiveX Control - the property page that is to be displayed in the COM add-in
End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Quit Event (Outlook)

 Copy code hover
[image]

Application.Quit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when Microsoft Outlook begins to close.

Syntax

expression .Quit

expression An expression that returns an Application object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example displays a farewell message when Outlook exits. The sample code must be placed in a class module.

VBA Copy code Copy code
Private Sub Application_Quit()

 MsgBox "Goodbye, " & Application.GetNamespace("MAPI").CurrentUser

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Reminder Event (Outlook)

 Copy code hover
[image]

Application.Reminder Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs immediately before a reminder is displayed.

Syntax

expression .Reminder(Item)

expression A variable that represents an Application object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The AppointmentItem, MailItem, ContactItem, or TaskItem associated with the reminder. If the appointment associated with the reminder is a recurring appointment, Item is the specific occurrence of the appointment that displayed the reminder, not the master appointment.

Example

This Microsoft Visual Basic for Applications (VBA) example displays the item that fired the Reminder event when the event fires. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myolapp As Outlook.Application

Sub Initialize_handler()

 Set myolapp = Outlook.Application

End Sub

Private Sub myolapp_Reminder(ByVal Item As Object)

 Item.Display

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


Application.Startup Event (Outlook)

 Copy code hover
[image]

Application.Startup Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when Microsoft Outlook is starting, but after all add-in programs have been loaded.

Syntax

expression .Startup

expression A variable that represents an Application object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

An Outlook macro can use this event procedure to initialize itself when Outlook starts.

Example

This Microsoft Visual Basic for Applications (VBA) example displays a welcome message to the user and maximizes the Outlook explorer window when Outlook starts.

VBA Copy code Copy code
Private Sub Application_Startup()

 MsgBox "Welcome, " & Application.GetNamespace("MAPI").CurrentUser

 Application.ActiveExplorer.WindowState = olMaximized

End Sub

See also

Concepts

Application Object

Other resources

Application Object Members


AppointmentItem Object (Outlook)

 Copy code hover
[image]

AppointmentItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a meeting, a one-time appointment, or a recurring appointment or meeting in the Calendar folder.

Remarks

Use the CreateItem method to create an AppointmentItem object that represents a new appointment.

Use Items (index), where index is the index number of an appointment or a value used to match the default property of an appointment, to return a single AppointmentItem object from a Calendar folder.

You can also return an AppointmentItem object from a MeetingItem object by using the GetAssociatedAppointment method.

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

The following code example in VBA shows how to release and refresh references in order to obtain up-to-date data for a recurring appointment. The example obtains a set of appointment items from the Calendar folder. It assumes that the first item in the appointment collection is part of a recurring appointment. The example shows that a reference to the appointment collection obtained before an exception is created does not reflect the exception. The example then releases this reference and other existing appointment references, after which new references that point to the appointment collection reflect the exception.

VBA Copy code Copy code
Sub TestExceptions()

 Dim oItems As Items

 Dim oItemOriginal As AppointmentItem

 Dim oItemNew As AppointmentItem

 Dim rPattern As RecurrencePattern

 Dim oEx As Exceptions

 Dim oEx2 As Exceptions

 Dim oOccurrence As AppointmentItem

 Dim i As Long

 ' This is the initial reference to an appointment collection.

 Set oItems = _

 Outlook.Application.Session.GetDefaultFolder(olFolderCalendar).Items

 ' This is the original reference to the first appointment in the

 ' collection before an exception is created.

 Set oItemOriginal = oItems.Item(1)

 ' Code example assumes that the first appointment in the collection

 ' is a recurring appointment.

 Set oOccurrence = _

 oItemOriginal.GetRecurrencePattern().GetOccurrence(#2/28/2010 8:00:00 AM#)

 ' Create an exception by changing the 2/28 occurrence to 3/3.

 oOccurrence.Start = #3/3/2010 8:00:00 AM#

 oOccurrence.Save

 Stop

 ' Preexisting reference to the first appointment in the collection

 ' does not reflect the exception.

 oItemOriginal.Save

 Set oEx = oItemOriginal.GetRecurrencePattern().Exceptions

 Debug.Print oItemOriginal.subject

 Debug.Print " Original item exceptions: " & oEx.Count

 ' Get a new reference based on the existing reference to the

 ' appointment collection created before the exception.

 ' The new reference does not reflect the exception.

 Set oItemNew = oItems.Item(1)

 oItemNew.Save

 Set oEx2 = oItemNew.GetRecurrencePattern().Exceptions

 Debug.Print " New item exceptions: " & oEx2.Count

 ' Same: preexisting reference to the first appointment in the collection

 ' does not reflect the exception.

 Set oEx = oItemOriginal.GetRecurrencePattern().Exceptions

 Debug.Print " Original item exceptions: " & oEx.Count

 ' Release all existing references to appointment items,

 ' including the appointment collection, an exception, occurrence,

 ' or any other appointment.

 Debug.Print "REFRESH ITEM COLLECTION"

 Set oItems = Nothing

 Set oItemNew = Nothing

 Set oEx = Nothing

 Set oEx2 = Nothing

 Set oOccurrence = Nothing

 Set oItemOriginal = Nothing

 Set rPattern = Nothing

 ' Get new references to appointment items, including the appointment

 ' collection, individual appointments, and exceptions.

 Set oItems = _

 Outlook.Application.Session.GetDefaultFolder(olFolderCalendar).Items

 Set oItemNew = oItems.Item(1)

 ' If no other add-ins have the same recurring appointment open,

 ' the new references reflect the current exception count.

 Set oEx2 = oItemNew.GetRecurrencePattern().Exceptions

 Debug.Print " New item exceptions: " & oEx2.Count

 Debug.Print "RE-GET ORIGINAL"

 Set oItemOriginal = oItems.Item(1)

 Set oEx = oItemOriginal.GetRecurrencePattern().Exceptions

 Debug.Print " Original item exceptions: " & oEx.Count

End Sub

Example

The following Visual Basic for Applications (VBA) example returns a new appointment.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olAppointmentItem)

See also

Concepts

Outlook Object Model Reference
How to: Import Appointment XML Data into Outlook Appointment Objects

Other resources

AppointmentItem Object Members


AppointmentItem Members (Outlook)

 Copy code hover
[image]

AppointmentItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a meeting, a one-time appointment, or a recurring appointment or meeting in the Calendar folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
ClearRecurrencePattern | Removes the recurrence settings and restores the single-occurrence state for an appointment or task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
CopyTo | Copies the AppointmentItem to the folder that is specified by the DestinationFolder parameter and returns an object that represents the item created in the destination folder by the copy operation.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
ForwardAsVcal | Forwards the AppointmentItem as a vCal; virtual calendar item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetOrganizer | Obtains the AddressEntry object that contains information from the Address Book about the organizer of the AppointmentItem.
GetRecurrencePattern | Returns a RecurrencePattern object that represents the recurrence attributes of an appointment.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Respond | Responds to a meeting request.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the appointment.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
AllDayEvent | Returns True if the appointment is an all-day event (as opposed to a specified time). Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BusyStatus | Returns or sets an OlBusyStatus constant indicating the busy status of the user for the appointment. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the AppointmentItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Duration | Returns or sets a Long indicating the duration (in minutes) of the AppointmentItem. Read/write.
End | Returns or sets a Date indicating the end date and time of an AppointmentItem. Read/write.
EndInEndTimeZone | Returns or sets a Date value that represents the end date and time of the appointment expressed in the AppointmentItem.EndTimeZone. Read/write.
EndTimeZone | Returns or sets a TimeZone value that corresponds to the end time of the appointment. Read/write.
EndUTC | Returns or sets a Date value that represents the end date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ForceUpdateToAllAttendees | Returns or sets a Boolean value that indicates whether updates to the AppointmentItem object should be sent to all attendees. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
GlobalAppointmentID | Returns a String value that represents a unique global identifier for the AppointmentItem object. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item on the local computer is different from the copy on the server. Read-only.
IsRecurring | Returns a Boolean value that is True if the appointment is a recurring appointment. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
Location | Returns or sets a String representing the specific office location (for example, Building 1 Room 1 or Suite 123) for the appointment. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MeetingStatus | Returns or sets an OlMeetingStatus constant specifying the meeting status of the appointment. Read/write.
MeetingWorkspaceURL | Returns a String value that represents the URL for the Meeting Workspace that the appointment item is linked to. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OptionalAttendees | Returns or sets a String representing the display string of optional attendees names for the appointment. Read/write.
Organizer | Returns a String representing the name of the organizer of the appointment. Read-only.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AppointmentItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
RecurrenceState | Returns an OlRecurrenceState constant indicating the recurrence property of the specified object. Read-only.
ReminderMinutesBeforeStart | Returns or sets a Long indicating the number of minutes the reminder should occur prior to the start of the appointment. Read/write.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReplyTime | Returns or sets a Date indicating the reply time for the appointment. Read/write.
RequiredAttendees | Returns a semicolon-delimited String of required attendee names for the meeting appointment. Read/write.
Resources | Returns a semicolon-delimited String of resource names for the meeting. Read/write.
ResponseRequested | Returns a Boolean that indicates True if the sender would like a response to the meeting request for the appointment. Read/write.
ResponseStatus | Returns an OlResponseStatus constant indicating the overall status of the meeting for the current user for the appointment. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the AppointmentItem is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Start | Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.
StartInStartTimeZone | Returns or sets a Date value that represents the start date and time of the appointment expressed in the AppointmentItem.StartTimeZone. Read/write.
StartTimeZone | Returns or sets a TimeZone value that corresponds to the time zone for the start time of the appointment. Read/write.
StartUTC | Returns or sets a Date value that represents the start date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


AppointmentItem Properties (Outlook)

 Copy code hover
[image]

AppointmentItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
AllDayEvent | Returns True if the appointment is an all-day event (as opposed to a specified time). Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BusyStatus | Returns or sets an OlBusyStatus constant indicating the busy status of the user for the appointment. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the AppointmentItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Duration | Returns or sets a Long indicating the duration (in minutes) of the AppointmentItem. Read/write.
End | Returns or sets a Date indicating the end date and time of an AppointmentItem. Read/write.
EndInEndTimeZone | Returns or sets a Date value that represents the end date and time of the appointment expressed in the AppointmentItem.EndTimeZone. Read/write.
EndTimeZone | Returns or sets a TimeZone value that corresponds to the end time of the appointment. Read/write.
EndUTC | Returns or sets a Date value that represents the end date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ForceUpdateToAllAttendees | Returns or sets a Boolean value that indicates whether updates to the AppointmentItem object should be sent to all attendees. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
GlobalAppointmentID | Returns a String value that represents a unique global identifier for the AppointmentItem object. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item on the local computer is different from the copy on the server. Read-only.
IsRecurring | Returns a Boolean value that is True if the appointment is a recurring appointment. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
Location | Returns or sets a String representing the specific office location (for example, Building 1 Room 1 or Suite 123) for the appointment. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MeetingStatus | Returns or sets an OlMeetingStatus constant specifying the meeting status of the appointment. Read/write.
MeetingWorkspaceURL | Returns a String value that represents the URL for the Meeting Workspace that the appointment item is linked to. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OptionalAttendees | Returns or sets a String representing the display string of optional attendees names for the appointment. Read/write.
Organizer | Returns a String representing the name of the organizer of the appointment. Read-only.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AppointmentItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
RecurrenceState | Returns an OlRecurrenceState constant indicating the recurrence property of the specified object. Read-only.
ReminderMinutesBeforeStart | Returns or sets a Long indicating the number of minutes the reminder should occur prior to the start of the appointment. Read/write.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReplyTime | Returns or sets a Date indicating the reply time for the appointment. Read/write.
RequiredAttendees | Returns a semicolon-delimited String of required attendee names for the meeting appointment. Read/write.
Resources | Returns a semicolon-delimited String of resource names for the meeting. Read/write.
ResponseRequested | Returns a Boolean that indicates True if the sender would like a response to the meeting request for the appointment. Read/write.
ResponseStatus | Returns an OlResponseStatus constant indicating the overall status of the meeting for the current user for the appointment. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the AppointmentItem is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Start | Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.
StartInStartTimeZone | Returns or sets a Date value that represents the start date and time of the appointment expressed in the AppointmentItem.StartTimeZone. Read/write.
StartTimeZone | Returns or sets a TimeZone value that corresponds to the time zone for the start time of the appointment. Read/write.
StartUTC | Returns or sets a Date value that represents the start date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


AppointmentItem.Actions Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.AllDayEvent Property (Outlook)

 Copy code hover
[image]

AppointmentItem.AllDayEvent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns True if the appointment is an all-day event (as opposed to a specified time). Read/write.

Syntax

expression .AllDayEvent

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Application Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Attachments Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

AppointmentItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents an AppointmentItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its AppointmentItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

AppointmentItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents an AppointmentItem object.

Remarks

This is a free-form text field.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Body Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object
How to: Import Appointment XML Data into Outlook Appointment Objects

Other resources

AppointmentItem Object Members


AppointmentItem.BusyStatus Property (Outlook)

 Copy code hover
[image]

AppointmentItem.BusyStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBusyStatus constant indicating the busy status of the user for the appointment. Read/write.

Syntax

expression .BusyStatus

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Categories Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents an AppointmentItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new appointment, displays the appointment on the screen, and opens the Show Categories dialog box. Finally, it displays the categories that the user assigned using AppointmentItem.ShowCategoriesDialog. Replace 'Dan Wilson' with a valid recipient name before running the example.

VBA Copy code Copy code
Sub Appointment()

 'Creates an appointment to access ShowCategoriesDialog

 Dim olApptItem As Outlook.AppointmentItem

 'Creates appointment item

 Set olApptItem = Application.CreateItem(olAppointmentItem)

 olApptItem.Body = "Please meet with me regarding these sales figures."

 olApptItem.Recipients.Add ("Dan Wilson")

 olApptItem.Subject = "Sales Reports"

 'Display the appointment

 olApptItem.Display

 'Display the Show Categories dialog box

 olApptItem.ShowCategoriesDialog

 MsgBox olApptItem.Categories

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Class Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Companies Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents an AppointmentItem object.

Remarks

This is a free-form text field.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Conflicts Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ConversationID Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the AppointmentItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents an AppointmentItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the AppointmentItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ConversationTopic Property (Outlook)
See also Send feedback

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.CreationTime Property (Outlook)

 Copy code hover
[image]

AppointmentItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.DownloadState Property (Outlook)

 Copy code hover
[image]

AppointmentItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents an AppointmentItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Duration Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Duration Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the duration (in minutes) of the AppointmentItem. Read/write.

Syntax

expression .Duration

expression A variable that represents an AppointmentItem object.

Example

This Visual Basic for Applications example uses Application.CreateItem to create an appointment and uses AppointmentItem.MeetingStatus to set the meeting status to "Meeting" to turn it into a meeting request with both a required and an optional attendee.

VBA Copy code Copy code
Sub ScheduleMeeting()

 Dim myItem as AppointmentItem

 Dim myRequiredAttendee As Recipient

 Dim myOptionalAttendee As Recipient

 Dim myResourceAttendee As Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)

 myItem.MeetingStatus = olMeeting

 myItem.Subject = "Strategy Meeting"

 myItem.Location = "Conference Room B"

 myItem.Start = #9/24/2002 1:30:00 PM#

 myItem.Duration = 90

 Set myRequiredAttendee = myItem.Recipients.Add ("Nate Sun")

 myRequiredAttendee.Type = olRequired

 Set myOptionalAttendee = myItem.Recipients.Add ("Kevin Kennedy")

 myOptionalAttendee.Type = olOptional

 Set myResourceAttendee = myItem.Recipients.Add("Conference Room B")

 myResourceAttendee.Type = olResource

 myItem.Display

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.End Property (Outlook)

 Copy code hover
[image]

AppointmentItem.End Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the end date and time of an AppointmentItem. Read/write.

Syntax

expression .End

expression A variable that represents an AppointmentItem object.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the AppointmentItem.GetRecurrencePattern method. By setting the RecurrencePattern properties, RecurrenceType, PatternStartDate, and PatternEndDate, the appointments are now a recurring series that occur on a daily basis for the period of one year.

An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original AppointmentItem.Subject and Exception.OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

How to: Import Appointment XML Data into Outlook Appointment Objects
AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.EndInEndTimeZone Property (Outlook)

 Copy code hover
[image]

AppointmentItem.EndInEndTimeZone Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the end date and time of the appointment expressed in the AppointmentItem.EndTimeZone. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndInEndTimeZone

expression A variable that represents an AppointmentItem object.

Remarks

This is the value displayed as End time in the appointment inspector user interface.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.EndTimeZone Property (Outlook)

 Copy code hover
[image]

AppointmentItem.EndTimeZone Property (Outlook)
See also Send feedback

Returns or sets a TimeZone value that corresponds to the end time of the appointment. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndTimeZone

expression A variable that represents an AppointmentItem object.

Remarks

The time zone information is used to map the appointment to the correct UTC time when the appointment is saved, and into the correct local time when the item is displayed in the calendar.

Changing EndTimeZone affects the value of AppointmentItem.End which is always represented in the local time zone, Application.TimeZones.CurrentTimeZone.

Depending on the circumstances, changing the EndTimeZone may or may not cause Outlook to recalculate and update the AppointmentItem.EndInEndTimeZone.

As an example, in the appointment inspector, if you are the organizer of an appointment with a start time at 1 P.M. EST and end time at 3 P.M. EST, changing the appointment to have an EndTimeZone of PST will result in an appointment lasting from 1 P.M. EST to 3 P.M. PST, with the EndInEndTimeZone remaining as 3 P.M. However, if you are not the organizer, then changing the EndTimeZone from EST to PST will cause Outlook to recalculate and update the EndInEndTimeZone, and the appointment will last from 1 P.M. EST to 12 P.M. PST.

Another example is changing the EndTimeZone resulting in an appointment end time that occurs before a previously set appointment start time, in which case Outlook will recalculate and update the EndInEndTimeZone. For example, an appointment with a start time at 1 P.M. PST and end time at 3 P.M. PST has its EndTimeZone changed to EST. If Outlook did not recalculate the EndInEndTimeZone, the appointment would have an end time at 3 P.M. EST, which is equivalent to 12 P.M. PST, and which would occur before the start time of 1 P.M. PST. In practice, however, changing the EndTimeZone would result in Outlook recalculating and updating the EndInEndTimeZone to 6 P.M. (in the EndTimeZone EST).

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.EndUTC Property (Outlook)

 Copy code hover
[image]

AppointmentItem.EndUTC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the end date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndUTC

expression A variable that represents an AppointmentItem object.

Remarks

Changing the value for the AppointmentItem.End property or the AppointmentItem.EndTimeZone property will cause Outlook to recalculate the EndUTC.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.EntryID Property (Outlook)

 Copy code hover
[image]

AppointmentItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

Furthermore, when you call the AppointmentItem.Respond method with the olMeetingAccepted or olMeetingTentative parameter, Outlook will create a new appointment item that duplicates the original appointment item. The new item will have a different Entry ID. Outlook will then remove the original item. You should no longer use the Entry ID of the original item, but instead use AppointmentItem.EntryID to obtain the Entry ID for the new item for any subsequent needs. This is to ensure that this appointment item will be properly synchronized on your calendar if more than one client computer accesses your calendar but may be offline using the cache mode occasionally.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ForceUpdateToAllAttendees Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ForceUpdateToAllAttendees Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether updates to the AppointmentItem object should be sent to all attendees. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForceUpdateToAllAttendees

expression An expression that returns an AppointmentItem object.

Remarks

Normally, updates are sent to attendees only if the time or location of an appointment item is changed. Setting this property to True forces an update to be sent to all attendees, even if no changes to the time or location have occurred.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.FormDescription Property (Outlook)

 Copy code hover
[image]

AppointmentItem.FormDescription Property (Outlook)
See also Send feedback

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.GetInspector Property (Outlook)

 Copy code hover
[image]

AppointmentItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents an AppointmentItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.GlobalAppointmentID Property (Outlook)

 Copy code hover
[image]

AppointmentItem.GlobalAppointmentID Property (Outlook)
See also Send feedback

Returns a String value that represents a unique global identifier for the AppointmentItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GlobalAppointmentID

expression An expression that returns an AppointmentItem object.

Remarks

There are situations where the entry ID of AppointmentItem objects may change, such as when an item is moved to a different folder or to a different store. Entry IDs can also change when a user performs certain functions in Outlook, such as exporting and then reimporting data.

Therefore, each Outlook appointment item is assigned a Global Object ID, a unique global identifier which does not change during those situations. The Global Object ID is a MAPI property that Outlook uses to correlate meeting updates and responses with a particular meeting on the calendar. The Global Object ID is the same across all copies of the item.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Importance Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.InternetCodepage Property (Outlook)

 Copy code hover
[image]

AppointmentItem.InternetCodepage Property (Outlook)
See also Send feedback

Returns or sets a Long that determines the Internet code page used by the item. Read/write.

Syntax

expression .InternetCodepage

expression A variable that represents an AppointmentItem object.

Remarks

The Internet code page defines the text encoding scheme used by the item.

The following table lists the values that are supported by the InternetCodePage property.

Name | Character Set | Code Page
Arabic (ISO) | iso-8859-6 | 28596
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Baltic (Windows) | windows-1257 | 1257
Central European (ISO) | iso-8859-2 | 28592
Central European (Windows) | windows-1250 | 1250
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Simplified (HZ) | hz-gb-2312 | 52936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (ISO) | iso-8859-5 | 28595
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (KOI8-U) | koi8-u | 21866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Greek (Windows) | windows-1253 | 1253
Hebrew (ISO-Logical) | iso-8859-8-i | 38598
Hebrew (Windows) | windows-1255 | 1255
Japanese (EUC) | euc-jp | 51932
Japanese (JIS) | iso-2022-jp | 50220
Japanese (JIS-Allow 1 byte Kana) | csISO2022JP | 50221
Japanese (Shift-JIS) | iso-2022-jp | 932
Korean | ks_c_5601-1987 | 949
Korean (EUC) | euc-kr | 51949
Latin 3 (ISO) | iso-8859-3 | 28593
Latin 9 (ISO) | iso-8859-15 | 28605
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Turkish (Windows) | windows-1254 | 1254
Unicode (UTF-7) | utf-7 | 65000
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591
Western European (Windows) | Windows-1252 | 1252

The following table lists the code pages Microsoft recommends that you use for the best compatiblity with older e-mail systems.

Name | Character Set | Code Page
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Central European (ISO) | iso-8859-2 | 28592
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Hebrew (Windows) | windows-1255 | 1255
Japanese (JIS) | iso-2022-jp | 50220
Korean | ks_c_5601-1987 | 949
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.IsConflict Property (Outlook)

 Copy code hover
[image]

AppointmentItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item on the local computer is different from the copy on the server. Read-only.

Syntax

expression .IsConflict

expression A variable that represents an AppointmentItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

This property does not indicate whether the appointment item has a time conflict with another appointment in the calendar.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.IsRecurring Property (Outlook)

 Copy code hover
[image]

AppointmentItem.IsRecurring Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the appointment is a recurring appointment. Read-only.

Syntax

expression .IsRecurring

expression A variable that represents an AppointmentItem object.

Remarks

When the GetRecurrencePattern method is used with an AppointmentItem object, this property is set to True.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents an AppointmentItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

AppointmentItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Location Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Location Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the specific office location (for example, Building 1 Room 1 or Suite 123) for the appointment. Read/write.

Syntax

expression .Location

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagOfficeLocation.

Example

This Visual Basic for Applications example uses CreateItem to create an appointment and uses MeetingStatus to set the meeting status to "Meeting" to turn it into a meeting request with both a required and an optional attendee.

VBA Copy code Copy code
Sub ScheduleMeeting()

 Dim myItem as AppointmentItem

 Dim myRequiredAttendee As Recipient

 Dim myOptionalAttendee As Recipient

 Dim myResourceAttendee As Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)

 myItem.MeetingStatus = olMeeting

 myItem.Subject = "Strategy Meeting"

 myItem.Location = "Conference Room B"

 myItem.Start = #9/24/2002 1:30:00 PM#

 myItem.Duration = 90

 Set myRequiredAttendee = myItem.Recipients.Add ("Nate Sun")

 myRequiredAttendee.Type = olRequired

 Set myOptionalAttendee = myItem.Recipients.Add ("Kevin Kennedy")

 myOptionalAttendee.Type = olOptional

 Set myResourceAttendee = myItem.Recipients.Add("Conference Room B")

 myResourceAttendee.Type = olResource

 myItem.Display

End Sub

See also

Concepts

AppointmentItem Object
How to: Import Appointment XML Data into Outlook Appointment Objects

Other resources

AppointmentItem Object Members


AppointmentItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

AppointmentItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents an AppointmentItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.MeetingStatus Property (Outlook)

 Copy code hover
[image]

AppointmentItem.MeetingStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMeetingStatus constant specifying the meeting status of the appointment. Read/write.

Syntax

expression .MeetingStatus

expression A variable that represents an AppointmentItem object.

Remarks

Use this property to make a MeetingItem object available for the appointment.

Example

This Visual Basic for Applications example uses CreateItem to create an appointment and uses MeetingStatus to set the meeting status to "Meeting" to turn it into a meeting request with both a required and an optional attendee.

VBA Copy code Copy code
Sub CreateAppt()

 Dim myItem As Object

 Dim myRequiredAttendee, myOptionalAttendee, myResourceAttendee As Outlook.Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)

 myItem.MeetingStatus = olMeeting

 myItem.Subject = "Strategy Meeting"

 myItem.Location = "Conference Room B"

 myItem.Start = #9/24/1997 1:30:00 PM#

 myItem.Duration = 90

 Set myRequiredAttendee = myItem.Recipients.Add("Nate Sun")

 myRequiredAttendee.Type = olRequired

 Set myOptionalAttendee = myItem.Recipients.Add("Kevin Kennedy")

 myOptionalAttendee.Type = olOptional

 Set myResourceAttendee = myItem.Recipients.Add("Conference Room B")

 myResourceAttendee.Type = olResource

 myItem.Display

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.MeetingWorkspaceURL Property (Outlook)

 Copy code hover
[image]

AppointmentItem.MeetingWorkspaceURL Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the URL for the Meeting Workspace that the appointment item is linked to. Read-only.

Syntax

expression .MeetingWorkspaceURL

expression A variable that represents an AppointmentItem object.

Remarks

A Meeting Workspace is a shared Web site for planning the meeting and tracking the results.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.MessageClass Property (Outlook)

 Copy code hover
[image]

AppointmentItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

AppointmentItem Object
Item Types and Message Classes

Other resources

AppointmentItem Object Members


AppointmentItem.Mileage Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents an AppointmentItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.NoAging Property (Outlook)

 Copy code hover
[image]

AppointmentItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.OptionalAttendees Property (Outlook)

 Copy code hover
[image]

AppointmentItem.OptionalAttendees Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the display string of optional attendees names for the appointment. Read/write.

Syntax

expression .OptionalAttendees

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagDisplayCc.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Organizer Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Organizer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the name of the organizer of the appointment. Read-only.

Syntax

expression .Organizer

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

AppointmentItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

AppointmentItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Parent Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

AppointmentItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent AppointmentItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Recipients Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.

Syntax

expression .Recipients

expression A variable that represents an AppointmentItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.RecurrenceState Property (Outlook)

 Copy code hover
[image]

AppointmentItem.RecurrenceState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlRecurrenceState constant indicating the recurrence property of the specified object. Read-only.

Syntax

expression .RecurrenceState

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReminderMinutesBeforeStart Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReminderMinutesBeforeStart Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the number of minutes the reminder should occur prior to the start of the appointment. Read/write.

Syntax

expression .ReminderMinutesBeforeStart

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents an AppointmentItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents an AppointmentItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents an AppointmentItem object.

Example

This example creates an appointment item and sets the ReminderSet property before saving it.

VBA Copy code Copy code
Sub AddAppointment()

 Dim apti As Outlook.AppointmentItem

 Set apti = Application.CreateItem(olAppointmentItem)

 apti.Subject = "Car Servicing"

 apti.Start = DateAdd("n", 16, Now)

 apti.End = DateAdd("n", 60, apti.Start)

 apti.ReminderSet = True

 apti.ReminderMinutesBeforeStart = 60

 apti.Save

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents an AppointmentItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReplyTime Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ReplyTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the reply time for the appointment. Read/write.

Syntax

expression .ReplyTime

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.RequiredAttendees Property (Outlook)

 Copy code hover
[image]

AppointmentItem.RequiredAttendees Property (Outlook)
See also Send feedback

Returns a semicolon-delimited String of required attendee names for the meeting appointment. Read/write.

Syntax

expression .RequiredAttendees

expression A variable that represents an AppointmentItem object.

Remarks

This property only contains the display names for the required attendees. The attendee list should be set by using the Recipients collection.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Resources Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Resources Property (Outlook)
See also Send feedback

Returns a semicolon-delimited String of resource names for the meeting. Read/write.

Syntax

expression .Resources

expression A variable that represents an AppointmentItem object.

Remarks

This property contains the display names only. The Recipients collection should be used to modify the resource recipients. Resources are added as BCC recipients to the collection.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ResponseRequested Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ResponseRequested Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the sender would like a response to the meeting request for the appointment. Read/write.

Syntax

expression .ResponseRequested

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ResponseStatus Property (Outlook)

 Copy code hover
[image]

AppointmentItem.ResponseStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlResponseStatus constant indicating the overall status of the meeting for the current user for the appointment. Read-only.

Syntax

expression .ResponseStatus

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.RTFBody Property (Outlook)

 Copy code hover
[image]

AppointmentItem.RTFBody Property (Outlook)
See also Send feedback

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents an AppointmentItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

Example

The following code samples in Microsoft Visual Basic for Applications (VBA) and C# displays the Rich Text Format body of the appointment in the active inspector. An AppointmentItem must be the active inspector for this code to work.

VBA Copy code Copy code
Sub GetRTFBodyForMeeting()

 Dim oAppt As Outlook.AppointmentItem

 Dim strRTF As String

 If Application.ActiveInspector.CurrentItem.Class = olAppointment Then

 Set oAppt = Application.ActiveInspector.CurrentItem

 strRTF = StrConv(oAppt.RTFBody, vbUnicode)

 Debug.Print strRTF

 End If

End Sub
Copy code Copy code
private void GetRTFBodyForAppt()

{

 if (Application.ActiveInspector().CurrentItem is Outlook.AppointmentItem)

 {

 Outlook.AppointmentItem appt =

 Application.ActiveInspector().CurrentItem as Outlook.AppointmentItem;

 byte[] byteArray = appt.RTFBody as byte[];

 System.Text.Encoding encoding = new System.Text.ASCIIEncoding();

 string RTF = encoding.GetString(byteArray);

 Debug.WriteLine(RTF);

 }

}

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Saved Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.SendUsingAccount Property (Outlook)

 Copy code hover
[image]

AppointmentItem.SendUsingAccount Property (Outlook)
See also Send feedback

Returns or sets an Account object that represents the account under which the AppointmentItem is to be sent. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SendUsingAccount

expression An expression that returns a AppointmentItem object.

Remarks

The SendUsingAccount property can be used to specify the account that should be used to send the AppointmentItem when the Send method is called. This property returns Null (Nothing in Visual Basic) if the account specified for the AppointmentItem no longer exists.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Session Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AppointmentItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Size Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Start Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Start Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.

Syntax

expression .Start

expression A variable that represents an AppointmentItem object.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an appointment and uses MeetingStatus to set the meeting status to "Meeting" and to make it a meeting request with both a required and an optional attendee.

VBA Copy code Copy code
Sub ScheduleMeeting()

 Dim myItem as Outlook.AppointmentItem

 Dim myRequiredAttendee As Outlook.Recipient

 Dim myOptionalAttendee As Outlook.Recipient

 Dim myResourceAttendee As Outlook.Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)

 myItem.MeetingStatus = olMeeting

 myItem.Subject = "Strategy Meeting"

 myItem.Location = "Conference Room B"

 myItem.Start = #9/24/2003 1:30:00 PM#

 myItem.Duration = 90

 Set myRequiredAttendee = myItem.Recipients.Add ("Nate Sun")

 myRequiredAttendee.Type = olRequired

 Set myOptionalAttendee = myItem.Recipients.Add ("Kevin Kennedy")

 myOptionalAttendee.Type = olOptional

 Set myResourceAttendee = myItem.Recipients.Add("Conference Room B")

 myResourceAttendee.Type = olResource

 myItem.Display

End Sub

See also

Concepts

AppointmentItem Object
How to: Import Appointment XML Data into Outlook Appointment Objects

Other resources

AppointmentItem Object Members


AppointmentItem.StartInStartTimeZone Property (Outlook)

 Copy code hover
[image]

AppointmentItem.StartInStartTimeZone Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date and time of the appointment expressed in the AppointmentItem.StartTimeZone. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartInStartTimeZone

expression A variable that represents an AppointmentItem object.

Remarks

This is the value displayed as Start time in the appointment inspector user interface.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.StartTimeZone Property (Outlook)

 Copy code hover
[image]

AppointmentItem.StartTimeZone Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a TimeZone value that corresponds to the time zone for the start time of the appointment. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartTimeZone

expression A variable that represents an AppointmentItem object.

Remarks

The time zone information is used to map the appointment to the correct UTC time when the appointment is saved, and into the correct local time when the item is displayed in the calendar.

Changing StartTimeZone affects the value of AppointmentItem.Start which is always represented in the local time zone, Application.TimeZones.CurrentTimeZone.

Depending on the circumstances, changing the StartTimeZone may or may not cause Outlook to recalculate and update the AppointmentItem.StartInStartTimeZone.

As an example, in the appointment inspector, if you are the organizer of an appointment with a start time at 1 P.M. PST and end time at 3 P.M. PST, changing the appointment to have an StartTimeZone of EST will result in an appointment lasting from 1 P.M. EST to 3 P.M. PST, with the StartInStartTimeZone remaining as 1 P.M. However, if you are not the organizer, then changing the StartTimeZone from PST to EST will cause Outlook to recalculate and update the StartInStartTimeZone, and the appointment will last from 4 P.M. EST to 3 P.M. PST.

Another example is changing the StartTimeZone resulting in an appointment end time that occurs before a previously set appointment start time, in which case Outlook will recalculate and update the StartInStartTimeZone. For example, an appointment with a start time at 1 P.M. EST and end time at 3 P.M. EST has its StartTimeZone changed to PST. If Outlook did not recalculate the StartInStartTimeZone, the appointment would have a start time at 1 P.M. PST, which is equivalent to 4 P.M. EST, and which would occur before the end time of 3 P.M. EST. In practice, however, changing the StartTimeZone would result in Outlook recalculating and updating the StartInStartTimeZone to 10 A.M. (in the StartTimeZone PST).

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.StartUTC Property (Outlook)

 Copy code hover
[image]

AppointmentItem.StartUTC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date and time of the appointment expressed in the Coordinated Univeral Time (UTC) standard. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartUTC

expression A variable that represents an AppointmentItem object.

Remarks

Changing the value for the AppointmentItem.Start property or the AppointmentItem.StartTimeZone property will cause Outlook to recalculate the value of StartUTC.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Subject Property (Outlook)

 Copy code hover
[image]

AppointmentItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents an AppointmentItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

How to: Import Appointment XML Data into Outlook Appointment Objects
AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.UnRead Property (Outlook)

 Copy code hover
[image]

AppointmentItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.UserProperties Property (Outlook)

 Copy code hover
[image]

AppointmentItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem Methods (Outlook)

 Copy code hover
[image]

AppointmentItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
ClearRecurrencePattern | Removes the recurrence settings and restores the single-occurrence state for an appointment or task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
CopyTo | Copies the AppointmentItem to the folder that is specified by the DestinationFolder parameter and returns an object that represents the item created in the destination folder by the copy operation.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
ForwardAsVcal | Forwards the AppointmentItem as a vCal; virtual calendar item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetOrganizer | Obtains the AddressEntry object that contains information from the Address Book about the organizer of the AppointmentItem.
GetRecurrencePattern | Returns a RecurrencePattern object that represents the recurrence attributes of an appointment.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Respond | Responds to a meeting request.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the appointment.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


AppointmentItem.ClearRecurrencePattern Method (Outlook)

 Copy code hover
[image]

AppointmentItem.ClearRecurrencePattern Method (Outlook)
See also Send feedback

Removes the recurrence settings and restores the single-occurrence state for an appointment or task.

Syntax

expression .ClearRecurrencePattern

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Close Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Close Method (Outlook)
See also Send feedback

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Copy Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents an AppointmentItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.CopyTo Method (Outlook)

 Copy code hover
[image]

AppointmentItem.CopyTo Method (Outlook)
See also Send feedback

Published: July 16, 2012

Copies the AppointmentItem to the folder that is specified by the DestinationFolder parameter and returns an object that represents the item created in the destination folder by the copy operation.

Version Information

Version Added: Outlook 2010

Syntax

expression .CopyTo(DestinationFolder, CopyOptions)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestinationFolder | Required | Folder | Specifies the folder to which the AppointmentItem object is copied.
CopyOptions | Required | OlAppointmentCopyOptions | Specifies the user experience of the copy operation.

Return Value

Returns an AppointmentItem that represents the object created in the destination folder as a result of the copy operation.

Remarks

If no argument is specified for the CopyOptions parameter, CopyTo assumes that the value is olCreateAppointment.

CopyTo returns an error if the destination folder is not an appropriate folder type for an AppointmentItem object, or if the user does not have the necessary permissions to create items in the specified destination folder.

Setting the REG_MULTI_SZ value, DisableCrossAccountCopy, in HKCU\Software\Microsoft\Office\15.0\Outlook in the Windows registry has the side effect of disabling this method.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Delete Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents an AppointmentItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

AppointmentItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

AppointmentItem Object Members


AppointmentItem.Display Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ForwardAsVcal Method (Outlook)

 Copy code hover
[image]

AppointmentItem.ForwardAsVcal Method (Outlook)
See also Send feedback

Published: July 16, 2012

Forwards the AppointmentItem as a vCal; virtual calendar item.

Syntax

expression .ForwardAsVcal

expression A variable that represents an AppointmentItem object.

Return Value

A MailItem object that represents the new mail item to which the calendar information is attached.

Remarks

The ForwardAsVcal method returns a MailItem with the vCal file attached.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.GetConversation Method (Outlook)

 Copy code hover
[image]

AppointmentItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents an AppointmentItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.GetOrganizer Method (Outlook)

 Copy code hover
[image]

AppointmentItem.GetOrganizer Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains the AddressEntry object that contains information from the Address Book about the organizer of the AppointmentItem.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetOrganizer

expression A variable that represents an AppointmentItem object.

Return Value

An AddressEntry object that represents the organizer of the AppointmentItem.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.GetRecurrencePattern Method (Outlook)

 Copy code hover
[image]

AppointmentItem.GetRecurrencePattern Method (Outlook)
See also Send feedback

Returns a RecurrencePattern object that represents the recurrence attributes of an appointment.

Syntax

expression .GetRecurrencePattern

expression A variable that represents an AppointmentItem object.

Return Value

A RecurrencePattern object that represents the recurrence attributes of an appointment.

Remarks

If there is no existing recurrence pattern, a new empty RecurrencePattern object is returned.

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the GetRecurrencePattern method. By setting the RecurrencePattern properties, RecurrenceType, PatternStartDate, and PatternEndDate, the appointments are now a recurring series that occur on a daily basis for the period of one year.

An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original Subject and OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Release references to the appointment series

 Set myApptItem = Nothing

 Set myRecurrPatt = Nothing

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.Item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Move Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.PrintOut Method (Outlook)

 Copy code hover
[image]

AppointmentItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents an AppointmentItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Respond Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Respond Method (Outlook)
See also Send feedback

Responds to a meeting request.

Syntax

expression .Respond(Response, fNoUI, fAdditionalTextDialog)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | OlMeetingResponse | The response to the request.
fNoUI | Optional | Variant | True to not display a dialog box; the response is sent automatically. False to display the dialog box for responding.
fAdditionalTextDialog | Optional | Variant | False to not prompt the user for input; the response is displayed in the inspector for editing. True to prompt the user to either send or send with comments. This argument is valid only if fNoUI is False.

Return Value

A MeetingItem object that represents the response to the meeting request.

Remarks

When you call the Respond method with the olMeetingAccepted or olMeetingTentative parameter, Outlook will create a new appointment item that duplicates the original appointment item. The new item will have a different Entry ID. Outlook will then remove the original item. You should no longer use the Entry ID of the original item, but instead call the EntryID property to obtain the Entry ID for the new item for any subsequent needs. This is to ensure that this appointment item will be properly synchronized on your calendar if more than one client computer accesses your calendar but may be offline using the cache mode occasionally.

The following table describes the behavior of the Respond method depending on the parent object, and the fNoUI and fAdditionalTextDialog parameters.

fNoUI, fAdditionalTextDialog | Result
True, True | Response item is returned with no user interface. To send the response, you must call the Send method.
True, False | Same result as with True, True .
False, True | Prompts user to Send or Edit before sending the response.
False, False | New response item appears in the user interface, but no prompt is displayed.

Example

This Visual Basic for Applications (VBA) example finds a MeetingItem in the default Inbox folder and adds the associated appointment to the Calendar folder. It then responds to the sender by accepting the meeting.

VBA Copy code Copy code
Sub AcceptMeeting()
 Dim myNameSpace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myMtgReq As Outlook.MeetingItem
 Dim myAppt As Outlook.AppointmentItem
 Dim myMtg As Outlook.MeetingItem

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)
 Set myMtgReq = myFolder.Items.Find("[MessageClass] = 'IPM.Schedule.Meeting.Request'")
 If TypeName(myMtgReq) <> "Nothing" Then
 Set myAppt = myMtgReq.GetAssociatedAppointment(True)
 Set myMtg = myAppt.Respond(olResponseAccepted, True)
 myMtg.Send
 End If
End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Save Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents an AppointmentItem object.

Example

This Microsoft Visual Basic for Applications (VBA) example creates an appointment item and sets the AppointmentItem.ReminderSet property before saving it.

VBA Copy code Copy code
Sub AddAppointment()
 Dim apti As Outlook.AppointmentItem

 Set apti = Application.CreateItem(olAppointmentItem)
 apti.Subject = "Car Servicing"
 apti.Start = DateAdd("n", 16, Now)
 apti.End = DateAdd("n", 60, apti.Start)
 apti.ReminderSet = True
 apti.ReminderMinutesBeforeStart = 60
 apti.Save
End Sub

See also

Concepts

How to: Import Appointment XML Data into Outlook Appointment Objects
AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.SaveAs Method (Outlook)

 Copy code hover
[image]

AppointmentItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the first attachment " & _
 "in the current item to the Documents folder? If a file with the " & _
 "same name already exists in the destination folder, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.AppointmentItem

 Set MyItem = Application.CreateItem(olAppointmentItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Send Method (Outlook)

 Copy code hover
[image]

AppointmentItem.Send Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends the appointment.

Syntax

expression .Send

expression A variable that represents an AppointmentItem object.

Remarks

The Send method sends an item using the default account specified for the session. In a session where multiple Microsoft Exchange accounts are defined in the profile, the first Exchange account added to the profile is the primary Exchange account, and is also the default account for the session. To specify a different account to send an item, set the SendUsingAccount property to the desired Account object and then call the Send method.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an appointment. The example sets the MeetingStatus property to olMeeting to indicate the appointment as a meeting request, and sets a required attendee, an optional attendee, and a meeting location as a resource. The example then displays and sends the appointment item.

VBA Copy code Copy code
Sub CreateAppt()
 Dim myItem As Object
 Dim myRequiredAttendee, myOptionalAttendee, myResourceAttendee As Outlook.Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)
 myItem.MeetingStatus = olMeeting
 myItem.Subject = "Strategy Meeting"
 myItem.Location = "Conf Rm All Stars"
 myItem.Start = #9/24/2009 1:30:00 PM#
 myItem.Duration = 90
 Set myRequiredAttendee = myItem.Recipients.Add("Nate Sun")
 myRequiredAttendee.Type = olRequired
 Set myOptionalAttendee = myItem.Recipients.Add("Kevin Kennedy")
 myOptionalAttendee.Type = olOptional
 Set myResourceAttendee = myItem.Recipients.Add("Conf Rm All Stars")
 myResourceAttendee.Type = olResource
 myItem.Display
 myItem.Send
End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

AppointmentItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents an AppointmentItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new appointment item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub Appointment()

'Creates an appointment item to access ShowCategoriesDialog

 Dim olApptItem As Outlook.AppointmentItem

 'Create appointment item

 Set olApptItem = Application.CreateItem(olAppointmentItem)

 olApptItem.Body = "Please meet with me regarding these sales figures."

 olApptItem.Recipients.Add ("Jeff Smith")

 olApptItem.Subject = "Sales Reports"

 'Display the item

 olApptItem.Display

 'Display the Show categories dialog

 olApptItem.ShowCategoriesDialog

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem Events (Outlook)

 Copy code hover
[image]

AppointmentItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


AppointmentItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

AppointmentItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents an AppointmentItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

AppointmentItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

AppointmentItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

AppointmentItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel, )

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the AppointmentItem to be saved.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

AppointmentItem.BeforeRead Event (Outlook)
See also Send feedback

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents an AppointmentItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Close Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.CustomAction Event (Outlook)

 Copy code hover
[image]

AppointmentItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

AppointmentItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Forward Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Open Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Open Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

AppointmentItem.PropertyChange Event (Outlook)
See also Send feedback

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

Example

This Visual Basic for Applications (VBA) example uses the PropertyChange event to prevent someone from disabling a reminder on an item.

Copy code Copy code
Public WithEvents myItem As Outlook.AppointmentItem

Sub Initialize_handler()

 Set myItem = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderCalendar).Items("Status Meeting")

End Sub

Private Sub myItem_PropertyChange(ByVal Name As String)

 Select Case Name

 Case "ReminderSet"

 MsgBox "You may not remove a reminder on this item."

 myItem.ReminderSet = True

 Case Else

 End Select

End Sub

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Read Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents an AppointmentItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

AppointmentItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Reply Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Reply Event (Outlook)
See also Send feedback

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

AppointmentItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Send Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.

Syntax

expression .Send(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Unload Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents an AppointmentItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AppointmentItem.Write Event (Outlook)

 Copy code hover
[image]

AppointmentItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents an AppointmentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

AppointmentItem Object

Other resources

AppointmentItem Object Members


AssignToCategoryRuleAction Object (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction Object (Outlook)
See also Send feedback

Represents an action that assigns categories to a message.

Version Information

Version Added: Outlook 2007

Remarks

AssignToCategoryRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has an AssignToCategory property. The AssignToCategory property always returns an AssignToCategoryRuleAction object. If the rule has an enabled rule action that assigns a message with some specified categories, then AssignToCategoryRuleAction.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction Members (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction Members (Outlook)
Send feedback

Represents an action that assigns categories to a message.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionAssignToCategory, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns or sets an array of strings representing the categories assigned to the message. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AssignToCategoryRuleAction Properties (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionAssignToCategory, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns or sets an array of strings representing the categories assigned to the message. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AssignToCategoryRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.ActionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olRuleActionAssignToCategory, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents an AssignToCategoryRuleAction object.

Remarks

The category assigning rule action is supported by rules for receiving messages and rules for sending messages. For more information, see Specifying Rule Actions.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Application Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an AssignToCategoryRuleAction object.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Categories Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an array of strings representing the categories assigned to the message. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Categories

expression A variable that represents an AssignToCategoryRuleAction object.

Remarks

You can assign an array with one element for a single category or an array of strings for multiple categories. Outlook does not check to determine if the Categories property contains category names that are in the master category list.

This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Class Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an AssignToCategoryRuleAction object.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an AssignToCategoryRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an AssignToCategoryRuleAction object.

Remarks

The parent of the AssignToCategoryRuleAction object is the RuleAction object.

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


AssignToCategoryRuleAction.Session Property (Outlook)

 Copy code hover
[image]

AssignToCategoryRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an AssignToCategoryRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AssignToCategoryRuleAction Object

Other resources

AssignToCategoryRuleAction Object Members


Attachment Object (Outlook)

 Copy code hover
[image]

Attachment Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a document or link to a document contained in an Outlook item.

Remarks

Use Attachments (index), where index is the index number, to return a single Attachment object.

Use the Add method to add an attachment to an item.

Example

The following Visual Basic for Applications (VBA) example creates a new mail message, attaches Q496.xlsx as an attachment (not a link), assigns the attachment a descriptive caption, and displays the mail message with this attachment. This example assumes that the specified spreadsheet, Q496.xlsx, exists in the specified path, D:\Documents.

VBA Copy code Copy code
Sub AddAttachment()

 Dim myItem As Outlook.MailItem

 Dim myAttachments As Outlook.Attachments

 Set myItem = Application.CreateItem(olMailItem)

 Set myAttachments = myItem.Attachments

 myAttachments.Add "D:\Documents\Q496.xlsx", _

 olByValue, 1, "4th Quarter 1996 Results Chart"

 myItem.Display

End Sub

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message
Outlook Object Model Reference

Other resources

Attachment Object Members


Attachment Members (Outlook)

 Copy code hover
[image]

Attachment Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a document or link to a document contained in an Outlook item.

Methods

Name | Description
Delete | Deletes an object from the collection.
GetTemporaryFilePath | Returns the full path to the attached file that is in a temporary files folder. Read-only.
SaveAsFile | Saves the attachment to the specified path.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
BlockLevel | Returns an OlAttachmentBlockLevel constant that specifies if there is any restriction on the attachment based on its file extension. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns or sets a String representing the name, which does not need to be the actual file name, displayed below the icon representing the embedded attachment. Read/write.
FileName | Returns a String representing the file name of the attachment. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PathName | Returns a String representing the full path to the linked attached file. Read-only.
Position | Returns or sets a Long indicating the position of the attachment within the body of the item. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Attachment object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the attachment. Read-only.
Type | Returns an OlAttachmentType constant indicating the type of the specified object. Read-only.


Attachment Properties (Outlook)

 Copy code hover
[image]

Attachment Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
BlockLevel | Returns an OlAttachmentBlockLevel constant that specifies if there is any restriction on the attachment based on its file extension. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns or sets a String representing the name, which does not need to be the actual file name, displayed below the icon representing the embedded attachment. Read/write.
FileName | Returns a String representing the file name of the attachment. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PathName | Returns a String representing the full path to the linked attached file. Read-only.
Position | Returns or sets a Long indicating the position of the attachment within the body of the item. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Attachment object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the attachment. Read-only.
Type | Returns an OlAttachmentType constant indicating the type of the specified object. Read-only.


Attachment.Application Property (Outlook)

 Copy code hover
[image]

Attachment.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.BlockLevel Property (Outlook)

 Copy code hover
[image]

Attachment.BlockLevel Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlAttachmentBlockLevel constant that specifies if there is any restriction on the attachment based on its file extension. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .BlockLevel

expression A variable that represents an Attachment object.

Remarks

This value of this property reflects whether an attachment is blocked based on its file extension and how attachment security has been set up on the client computer. For more information on attachment security in Outlook, see the Office Resource Kit Web site.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Class Property (Outlook)

 Copy code hover
[image]

Attachment.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.DisplayName Property (Outlook)

 Copy code hover
[image]

Attachment.DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the name, which does not need to be the actual file name, displayed below the icon representing the embedded attachment. Read/write.

Syntax

expression .DisplayName

expression A variable that represents an Attachment object.

Remarks

This property corresponds to the MAPI property PidTagDisplayName.

Example

This Visual Basic for Applications (VBA) example uses the Attachment.SaveAsFile method to save the first attachment of the currently open item as a file in the Documents folder, using the attachment's display name as the file name.

VBA Copy code Copy code
Sub SaveAttachment()

 Dim myInspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Dim myAttachments As Outlook.Attachments

 Set myInspector = Application.ActiveInspector

 If Not TypeName(myInspector) = "Nothing" Then

 If TypeName(myInspector.CurrentItem) = "MailItem" Then

 Set myItem = myInspector.CurrentItem

 Set myAttachments = myItem.Attachments

 'Prompt the user for confirmation

 Dim strPrompt As String

 strPrompt = "Are you sure you want to save the first attachment " & _

 "in the current item to the Documents folder? If a file with the " & _

 "same name already exists in the destination folder, " & _

 "it will be overwritten with this copy of the file."

 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then

 myAttachments.Item(1).SaveAsFile Environ("HOMEPATH") & "\My Documents\" & _

 myAttachments.Item(1).DisplayName

 End If

 Else

 MsgBox "The item is of the wrong type."

 End If

 End If

End Sub

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.FileName Property (Outlook)

 Copy code hover
[image]

Attachment.FileName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the file name of the attachment. Read-only.

Syntax

expression .FileName

expression A variable that represents an Attachment object.

Remarks

Use this property in conjunction with the PathName property.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Index Property (Outlook)

 Copy code hover
[image]

Attachment.Index Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the position of the object within the collection. Read-only.

Syntax

expression .Index

expression A variable that represents an Attachment object.

Remarks

The Index property is only valid during the current session and can change as objects are added to and deleted from the collection. The first object in the collection has an Index value of 1.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Parent Property (Outlook)

 Copy code hover
[image]

Attachment.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.PathName Property (Outlook)

 Copy code hover
[image]

Attachment.PathName Property (Outlook)
See also Send feedback

Returns a String representing the full path to the linked attached file. Read-only.

Syntax

expression .PathName

expression A variable that represents an Attachment object.

Remarks

This property is only valid for linked files.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Position Property (Outlook)

 Copy code hover
[image]

Attachment.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the position of the attachment within the body of the item. Read/write.

Syntax

expression .Position

expression A variable that represents an Attachment object.

Remarks

The Position property only works on an attachment for an item where the body format is Rich Text (RTF). If the body format is not RTF, the Position property is ignored for a set operation and always returns zero (0) for a get operation.

If you set the Position property to 0 for an item where the body format is RTF, the attachment will be hidden in Outlook's user interface. The attachment is not visible in a view, and the user cannot remove the attachment from the body of the item. The attachment can still be accessed through the Attachments collection on the item.

The only item that allows programmatic setting of the BodyFormat property is a MailItem. Other item types such as Appointment, Contact, and Task are RTF by default.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

Attachment.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Attachment object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Session Property (Outlook)

 Copy code hover
[image]

Attachment.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Attachment object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Size Property (Outlook)

 Copy code hover
[image]

Attachment.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the attachment. Read-only.

Syntax

expression .Size

expression A variable that represents an Attachment object.

Remarks

This information may not always be available for attachments. For example, on an S/MIME message, the actual attachment sizes are unknown until the attachment is extracted. In cases where the attachment size cannot be determined, this property returns 0.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.Type Property (Outlook)

 Copy code hover
[image]

Attachment.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlAttachmentType constant indicating the type of the specified object. Read-only.

Syntax

expression .Type

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment Methods (Outlook)

 Copy code hover
[image]

Attachment Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.
GetTemporaryFilePath | Returns the full path to the attached file that is in a temporary files folder. Read-only.
SaveAsFile | Saves the attachment to the specified path.


Attachment.Delete Method (Outlook)

 Copy code hover
[image]

Attachment.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents an Attachment object.

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.GetTemporaryFilePath Method (Outlook)

 Copy code hover
[image]

Attachment.GetTemporaryFilePath Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the full path to the attached file that is in a temporary files folder. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetTemporaryFilePath

expression A variable that represents an Attachment object.

Return Value

Returns a String that represents the full path to the temporary attachment file.

Remarks

The GetTemporaryFilePath method is only valid for those attachments whose Type property is OlAttachmentType.olByValue. That means that the attachment is a copy and that the copy can be accessed even if the original file is removed. For other attachment types, the GetTemporaryFilePath method returns an error.

GetTemporaryFilePath also returns an error when accessing an Attachment object in an Attachments collection or in the AttachmentSelection object. Use GetTemporaryFilePath only in attachment event callbacks listed below for various Microsoft Outlook items:

  • AttachmentAdd

  • AttachmentRead

  • AttachmentRemove

  • BeforeAttachmentAdd

  • BeforeAttachmentPreview

  • BeforeAttachmentRead

  • BeforeAttachmentSave

  • BeforeAttachmentWriteToTempFile

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachment.SaveAsFile Method (Outlook)

 Copy code hover
[image]

Attachment.SaveAsFile Method (Outlook)
See also Send feedback

Saves the attachment to the specified path.

Syntax

expression .SaveAsFile(Path)

expression A variable that represents an Attachment object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The location at which to save the attachment.

Example

This Visual Basic for Applications (VBA) example uses the SaveAsFile method to save the first attachment of the currently open item as a file in the Documents folder, using the attachment's display name as the file name.

VBA Copy code Copy code
Sub SaveAttachment()

 Dim myInspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Dim myAttachments As Outlook.Attachments

 Set myInspector = Application.ActiveInspector

 If Not TypeName(myInspector) = "Nothing" Then

 If TypeName(myInspector.CurrentItem) = "MailItem" Then

 Set myItem = myInspector.CurrentItem

 Set myAttachments = myItem.Attachments

 'Prompt the user for confirmation

 Dim strPrompt As String

 strPrompt = "Are you sure you want to save the first attachment in the current item to the Documents folder? If a file with the same name already exists in the destination folder, it will be overwritten with this copy of the file."

 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then

 myAttachments.Item(1).SaveAsFile Environ("HOMEPATH") & "\My Documents\" & _

 myAttachments.Item(1).DisplayName

 End If

 Else

 MsgBox "The item is of the wrong type."

 End If

 End If

End Sub

See also

Concepts

Attachment Object

Other resources

Attachment Object Members


Attachments Object (Outlook)

 Copy code hover
[image]

Attachments Object (Outlook)
See also Send feedback

Contains a set of Attachment objects that represent the attachments in an Outlook item.

Remarks

Use the Attachments property to return the Attachments collection for any Outlook item (except notes).

Use the Add method to add an attachment to an item.

To ensure consistent results, always save an item before adding or removing objects in the Attachments collection of the item.

Example

The following Visual Basic for Applications (VBA) example creates a new mail message, attaches a Q496.xls as an attachment (not a link), and gives the attachment a descriptive caption.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olMailItem)

myItem.Save

Set myAttachments = myItem.Attachments

myAttachments.Add "C:\My Documents\Q496.xls", _

 olByValue, 1, "4th Quarter 1996 Results Chart"

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message
Outlook Object Model Reference

Other resources

Attachments Object Members


Attachments Members (Outlook)

 Copy code hover
[image]

Attachments Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of Attachment objects that represent the attachments in an Outlook item.

Methods

Name | Description
Add | Creates a new attachment in the Attachments collection.
Item | Returns an Attachment object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Attachments Properties (Outlook)

 Copy code hover
[image]

Attachments Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Attachments.Application Property (Outlook)

 Copy code hover
[image]

Attachments.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Attachments object.

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments.Class Property (Outlook)

 Copy code hover
[image]

Attachments.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Attachments object.

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments.Count Property (Outlook)

 Copy code hover
[image]

Attachments.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Attachments object.

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments.Parent Property (Outlook)

 Copy code hover
[image]

Attachments.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Attachments object.

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments.Session Property (Outlook)

 Copy code hover
[image]

Attachments.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Attachments object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments Methods (Outlook)

 Copy code hover
[image]

Attachments Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new attachment in the Attachments collection.
Item | Returns an Attachment object from the collection.
Remove | Removes an object from the collection.


Attachments.Add Method (Outlook)

 Copy code hover
[image]

Attachments.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new attachment in the Attachments collection.

Syntax

expression .Add(Source, Type, Position, DisplayName)

expression A variable that represents an Attachments object.

Parameters

Name | Required/Optional | Data Type | Description
Source | Required | Variant | The source of the attachment. This can be a file (represented by the full file system path with a file name) or an Outlook item that constitutes the attachment.
Type | Optional | Long | The type of the attachment. Can be one of the OlAttachmentType constants.
Position | Optional | Long | This parameter applies only to e-mail messages using the Rich Text format: it is the position where the attachment should be placed within the body text of the message. A value of 1 for the Position parameter specifies that the attachment should be positioned at the beginning of the message body. A value 'n' greater than the number of characters in the body of the e-mail item specifies that the attachment should be placed at the end. A value of 0 makes the attachment hidden.
DisplayName | Optional | String | This parameter applies only if the mail item is in Rich Text format and Type is set to olByValue: the name is displayed in an Inspector object for the attachment or when viewing the properties of the attachment. If the mail item is in Plain Text or HTML format, then the attachment is displayed using the file name in the Source parameter.

Return Value

An Attachment object that represents the new attachment.

Remarks

When an Attachment is added to the Attachments collection of an item, the Type property of the Attachment will always return olOLE (6) until the item is saved. To ensure consistent results, always save an item before adding or removing objects in the Attachments collection.

Example

The following Microsoft Visual Basic /Visual Basic for Applications (VBA) example creates a mail item, adds an attachment by embedding it at the beginning of the message body, and displays it. To run this example, make sure the attachment which is a file called Test.Doc exists in the C:\ folder.

VBA Copy code Copy code
Sub AddAttachment()
 Dim myItem As Outlook.MailItem
 Dim myAttachments As Outlook.Attachments

 Set myItem = Application.CreateItem(olMailItem)
 Set myAttachments = myItem.Attachments
 myAttachments.Add "C:\Test.doc", _
 olByValue, 1, "Test"
 myItem.Display
End Sub

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message
Attachments Object

Other resources

Attachments Object Members


Attachments.Item Method (Outlook)

 Copy code hover
[image]

Attachments.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachment object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an Attachments object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Attachment object that represents the specified object.

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


Attachments.Remove Method (Outlook)

 Copy code hover
[image]

Attachments.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an Attachments object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

Example

This Visual Basic for Applications (VBA) example uses the Remove method to remove all attachments from a forwarded message before sending it on to Dan Wilson. Before running this example, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub RemoveAttachmentBeforeForwarding()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Dim myattachments As Outlook.Attachments

 Set myinspector = Application.ActiveInspector

 If Not TypeName(myinspector) = "Nothing" Then

 Set myItem = myinspector.CurrentItem.Forward

 Set myattachments = myItem.Attachments

 While myattachments.Count > 0

 myattachments.Remove 1

 Wend

 myItem.Display

 myItem.Recipients.Add "Dan Wilson"

 myItem.Send

 Else

 MsgBox "There is no active inspector."

 End If

End Sub

See also

Concepts

Attachments Object

Other resources

Attachments Object Members


AttachmentSelection Object (Outlook)

 Copy code hover
[image]

AttachmentSelection Object (Outlook)
See also Send feedback

Contains a set of Attachment objects that represent the selected attachments in an Outlook item.

Version Information

Version Added: Outlook 2007

Remarks

The AttachmentSelection object contains a read-only collection of attachments that are selected in an item that is in the active inspector or the active explorer.

To customize the attachment shortcut menu by using Microsoft Office Fluent ribbon extensibility, use the Context property of the IRibbonControl to obtain an AttachmentSelection object.

See also

Concepts

Outlook Object Model Reference

Other resources

AttachmentSelection Object Members


AttachmentSelection Members (Outlook)

 Copy code hover
[image]

AttachmentSelection Members (Outlook)
Send feedback

Contains a set of Attachment objects that represent the selected attachments in an Outlook item.

Methods

Name | Description
GetSelection | Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer where the parent item of the AttachmentSelection object is.
Item | Returns an Attachment object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Location | Returns a OlSelectionLocation constant that specifies where the attachment selection is in the Microsoft Outlook user interface. Read-only
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AttachmentSelection Properties (Outlook)

 Copy code hover
[image]

AttachmentSelection Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Location | Returns a OlSelectionLocation constant that specifies where the attachment selection is in the Microsoft Outlook user interface. Read-only
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AttachmentSelection.Application Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AttachmentSelection object.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Class Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AttachmentSelection object.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Count Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an AttachmentSelection object.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Location Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Location Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a OlSelectionLocation constant that specifies where the attachment selection is in the Microsoft Outlook user interface. Read-only

Version Information

Version Added: Outlook 2010

Syntax

expression .Location

expression A variable that represents an AttachmentSelection object.

Remarks

This property always returns the constant olAttachmentWell.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Parent Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AttachmentSelection object.

Remarks

The Parent property of an AttachmentSelection object represents the Microsoft Outlook item that contains the selected attachments.

If the item is in an explorer, the value of the Parent property is the same as the first item in the selection that is returned by the Explorer.Selection property, which is Explorer.Selection.Item(1).

If the item is in an inspector, the value of the Parent property is the same as the value of the Inspector.CurrentItem property.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Session Property (Outlook)

 Copy code hover
[image]

AttachmentSelection.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AttachmentSelection object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection Methods (Outlook)

 Copy code hover
[image]

AttachmentSelection Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
GetSelection | Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer where the parent item of the AttachmentSelection object is.
Item | Returns an Attachment object from the collection.


AttachmentSelection.GetSelection Method (Outlook)

 Copy code hover
[image]

AttachmentSelection.GetSelection Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer where the parent item of the AttachmentSelection object is.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetSelection(SelectionContents)

expression A variable that represents an AttachmentSelection object.

Parameters

Name | Required/Optional | Data Type | Description
SelectionContents | Required | OlSelectionContents | Specifies the kind of objects in the selection to return.

Return Value

A Selection object that contains the specified kind of objects that are selected in the active explorer.

Remarks

The only reason that this method is exposed on the AttachmentSelection object is because the AttachmentSelection inherits from the Selection object. This method is not intended to be called on the AttachmentSelection object.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AttachmentSelection.Item Method (Outlook)

 Copy code hover
[image]

AttachmentSelection.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachment object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression An expression that returns an AttachmentSelection object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or the value used to match the default property of an object in the collection.

Return Value

An Attachment object that represents the specified object.

See also

Concepts

AttachmentSelection Object

Other resources

AttachmentSelection Object Members


AutoFormatRule Object (Outlook)

 Copy code hover
[image]

AutoFormatRule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a formatting rule used by a View object to determine how to format Outlook items displayed within that view.

Version Information

Version Added: Outlook 2007

Remarks

Use the Add method or the Insert method of the AutoFormatRules collection to create a new formatting rule for the following objects:

  • CalendarView

  • CardView

  • TableView

Built-In and Custom Formatting Rules

Microsoft Outlook provides a set of built-in formatting rules that can be disabled but cannot be removed or reordered. Custom formatting rules, defined either programmatically or by user action, cannot be moved above or between built-in formatting rules. Use the Standard property to determine whether a formatting rule is built-in or custom.

Applying Formatting Rules

Formatting rules are checked and applied against each Outlook item, in the order in which they are contained within the AutoFormatRules collection. Use the Enabled property to enable or disable a formatting rule, the Filter property to define the conditions an Outlook item must meet to be formatted by the formatting rule, and the Font property to specify the format to be applied by the formatting rule.

Example

The following Visual Basic for Applications (VBA) example enumerates the AutoFormatRules collection for the current TableView object, disabling any custom formatting rule contained by the collection.

VBA Copy code Copy code
Private Sub DisableCustomAutoFormatRules()

 Dim objTableView As TableView

 Dim objRule As AutoFormatRule

 ' Check if the current view is a table view.

 If Application.ActiveExplorer.CurrentView.ViewType = olTableView Then

 ' Obtain a TableView object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Enumerate the AutoFormatRules collection for

 ' the table view, disabling any custom formatting

 ' rule defined for the view.

 For Each objRule In objView.AutoFormatRules

 If Not objRule.Standard Then

 objRule.Enabled = False

 End If

 Next

 ' Save and apply the table view.

 objView.Save

 objView.Apply

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

AutoFormatRule Object Members


AutoFormatRule Members (Outlook)

 Copy code hover
[image]

AutoFormatRule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a formatting rule used by a View object to determine how to format Outlook items displayed within that view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean value that indicates whether the formatting rule represented by the AutoFormatRule object is enabled. Read/write.
Filter | Returns or sets a String value that represents the filter for a custom formatting rule. Read/write.
Font | Returns a ViewFont object that represents the font used to display Outlook items that satisfy the conditions for the formatting rule in the view. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean value that indicates whether the AutoFormatRule object represents a built-in Outlook formatting rule. Read-only.


AutoFormatRule Properties (Outlook)

 Copy code hover
[image]

AutoFormatRule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean value that indicates whether the formatting rule represented by the AutoFormatRule object is enabled. Read/write.
Filter | Returns or sets a String value that represents the filter for a custom formatting rule. Read/write.
Font | Returns a ViewFont object that represents the font used to display Outlook items that satisfy the conditions for the formatting rule in the view. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean value that indicates whether the AutoFormatRule object represents a built-in Outlook formatting rule. Read-only.


AutoFormatRule.Application Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AutoFormatRule object.

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Class Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AutoFormatRule object.

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Enabled Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether the formatting rule represented by the AutoFormatRule object is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an AutoFormatRule object.

Example

The following Visual Basic for Applications (VBA) example enumerates the AutoFormatRules collection for the current TableView object, disabling any custom formatting rule contained by the collection.

Copy code Copy code
Private Sub DisableCustomAutoFormatRules()

 Dim objTableView As TableView

 Dim objRule As AutoFormatRule

 ' Check if the current view is a table view.

 If Application.ActiveExplorer.CurrentView.ViewType = olTableView Then

 ' Obtain a TableView object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Enumerate the AutoFormatRules collection for

 ' the table view, disabling any custom formatting

 ' rule defined for the view.

 For Each objRule In objView.AutoFormatRules

 If Not objRule.Standard Then

 objRule.Enabled = False

 End If

 Next

 ' Save and apply the table view.

 objView.Save

 objView.Apply

 End If

End Sub

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Filter Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the filter for a custom formatting rule. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents an AutoFormatRule object.

Remarks

The value of this property is a DAV Searching and Locating (DASL) string that represents the current filter for the custom formatting rule. For more information about using DASL to filter items formatted by the formatting rule, see Filtering Items. Setting this property to an empty string applies the custom formatting rule to all items displayed by the view.

Note Note

This property returns an empty string for a standard formatting rule (an AutoFormatRule object with a Standard property value set to True). An error occurs if you attempt to assign a value to this property for a standard formatting rule.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, and then creates a new AutoFormatRule named "Handoff Messages." The Filter property of the AutoFormatRule object is set so that the formatting rule applies to any message in which the Subject property value starts with "HANDOFF". The sample then sets the properties of the Font object for the AutoFormatRule object the so that messages to which the formatting rule applies are displayed in blue, bold, 8 point Courier New text.

VBA Copy code Copy code
Private Sub FormatHandoffMessages()

 Dim objView As TableView

 Dim objRule As AutoFormatRule

 ' Check if the current view is a table view.

 If Application.ActiveExplorer.CurrentView.ViewType = olTableView Then

 ' Obtain a TableView object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Create a new rule that displays any message with a

 ' subject line that starts with "HANDOFF" in

 ' blue, bold, 8 point Courier New text.

 Set objRule = objView.AutoFormatRules.Add("Handoff Messages")

 With objRule

 .Filter = """http://schemas.microsoft.com/mapi/proptag/0x0037001f""" & _

 " CI_STARTSWITH 'HANDOFF'"

 With .Font

 .Name = "Courier New"

 .Size = "8"

 .Bold = True

 .Color = olColorBlue

 End With

 End With

 ' Save and apply the table view.

 objView.Save

 objView.Apply

 End If

End Sub

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Font Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display Outlook items that satisfy the conditions for the formatting rule in the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an AutoFormatRule object.

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Name Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an AutoFormatRule object.

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Parent Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AutoFormatRule object.

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Session Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AutoFormatRule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRule.Standard Property (Outlook)

 Copy code hover
[image]

AutoFormatRule.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the AutoFormatRule object represents a built-in Outlook formatting rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression A variable that represents an AutoFormatRule object.

Remarks

If the value of this property is set to True, then the Filter and Name properties of the AutoFormatRule object cannot be changed. Similarly, you cannot use the Remove method of the AutoFormatRules collection to delete a built-in Outlook formatting rule, nor can you use the Insert method of the AutoFormatRules collection to insert a custom formatting rule above or between the built-in Outlook formatting rules contained by that collection.

Example

The following Visual Basic for Applications (VBA) example enumerates the AutoFormatRules collection for the current TableView object, disabling any custom formatting rule contained by the collection.

Copy code Copy code
Private Sub DisableCustomAutoFormatRules()

 Dim objTableView As TableView

 Dim objRule As AutoFormatRule

 ' Check if the current view is a table view.

 If Application.ActiveExplorer.CurrentView.ViewType = olTableView Then

 ' Obtain a TableView object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Enumerate the AutoFormatRules collection for

 ' the table view, disabling any custom formatting

 ' rule defined for the view.

 For Each objRule In objView.AutoFormatRules

 If Not objRule.Standard Then

 objRule.Enabled = False

 End If

 Next

 ' Save and apply the table view.

 objView.Save

 objView.Apply

 End If

End Sub

See also

Concepts

AutoFormatRule Object

Other resources

AutoFormatRule Object Members


AutoFormatRules Object (Outlook)

 Copy code hover
[image]

AutoFormatRules Object (Outlook)
See also Send feedback

Represents the collection of AutoFormatRule objects in a view.

Version Information

Version Added: Outlook 2007

Remarks

Use the Add method or the Insert method of the AutoFormatRules collection to create a new formatting rule for the following objects derived from the View object:

  • BusinessCardView

  • CalendarView

  • CardView

  • IconView

  • TableView

  • TimelineView Object

AutoFormatRule objects contained in an AutoFormatRules collection are applied to each Outlook item in the order in which they are contained in the collection. Changes to AutoFormatRule objects are persisted only if the Save method of the AutoFormatRules collection is called.

Example

The following Visual Basic for Applications (VBA) example enumerates the AutoFormatRules collection for the current TableView object, disabling any custom formatting rule contained by the collection.

Copy code Copy code
Private Sub DisableCustomAutoFormatRules()

 Dim objTableView As TableView

 Dim objRule As AutoFormatRule

 ' Check if the current view is a table view.

 If Application.ActiveExplorer.CurrentView.ViewType = olTableView Then

 ' Obtain a TableView object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Enumerate the AutoFormatRules collection for

 ' the table view, disabling any custom formatting

 ' rule defined for the view.

 For Each objRule In objView.AutoFormatRules

 If Not objRule.Standard Then

 objRule.Enabled = False

 End If

 Next

 ' Save and apply the table view.

 objView.Save

 objView.Apply

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

AutoFormatRules Object Members


AutoFormatRules Members (Outlook)

 Copy code hover
[image]

AutoFormatRules Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the collection of AutoFormatRule objects in a view.

Methods

Name | Description
Add | Creates a new AutoFormatRule object and appends it to the AutoFormatRules collection.
Insert | Creates a new AutoFormatRule object and inserts it at the specified index within the AutoFormatRules collection.
Item | Returns an AutoFormatRule object from the collection.
Remove | Removes an object from the collection.
RemoveAll | Removes all custom formatting rules from the AutoFormatRules collection.
Save | Save all changes to AutoFormatRule objects within the AutoFormatRules collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of AutoFormatRule objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AutoFormatRules Properties (Outlook)

 Copy code hover
[image]

AutoFormatRules Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of AutoFormatRule objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


AutoFormatRules.Application Property (Outlook)

 Copy code hover
[image]

AutoFormatRules.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an AutoFormatRules object.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Class Property (Outlook)

 Copy code hover
[image]

AutoFormatRules.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an AutoFormatRules object.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Count Property (Outlook)

 Copy code hover
[image]

AutoFormatRules.Count Property (Outlook)
See also Send feedback

Returns a Long value indicating the count of AutoFormatRule objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an AutoFormatRules object.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Parent Property (Outlook)

 Copy code hover
[image]

AutoFormatRules.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an AutoFormatRules object.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Session Property (Outlook)

 Copy code hover
[image]

AutoFormatRules.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an AutoFormatRules object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules Methods (Outlook)

 Copy code hover
[image]

AutoFormatRules Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new AutoFormatRule object and appends it to the AutoFormatRules collection.
Insert | Creates a new AutoFormatRule object and inserts it at the specified index within the AutoFormatRules collection.
Item | Returns an AutoFormatRule object from the collection.
Remove | Removes an object from the collection.
RemoveAll | Removes all custom formatting rules from the AutoFormatRules collection.
Save | Save all changes to AutoFormatRule objects within the AutoFormatRules collection.


AutoFormatRules.Add Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new AutoFormatRule object and appends it to the AutoFormatRules collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(Name)

expression A variable that represents an AutoFormatRules object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new formatting rule.

Return Value

An AutoFormatRule object that represents the new formatting rule.

Remarks

Duplicate names for AutoFormatRule objects are allowed in the AutoFormatRules collection. A maximum of 25 custom formatting rules can be added to the collection. Built-in formatting rules are not counted against that limit.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Insert Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.Insert Method (Outlook)
See also Send feedback

Creates a new AutoFormatRule object and inserts it at the specified index within the AutoFormatRules collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Insert(Name, Index)

expression A variable that represents an AutoFormatRules object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new object.
Index | Required | Variant | Either the index number at which to insert the new object, or a value used to match the Name property value of an object in the collection at where the new object is to be inserted.

Return Value

An AutoFormatRule object that represents the new formatting rule.

Remarks

This method cannot be used to insert custom formatting rules between or ahead of built-in formatting rules.

Duplicate names for AutoFormatRule objects are allowed in the AutoFormatRules collection. A maximum of 25 custom formatting rules can be added to the collection. Built-in formatting rules are not counted against that limit.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Item Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AutoFormatRule object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents an AutoFormatRules object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the Name property value of an object in the collection.

Return Value

An AutoFormatRule object that represents the specified object.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Remove Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents an AutoFormatRules object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the Name property value of an object in the collection.

Remarks

If the name of a formatting rule to be removed is specified in Index, this method removes the first AutoFormatRule object that matches the specified name.

Built-in formatting rules cannot be removed from the collection.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.RemoveAll Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.RemoveAll Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes all custom formatting rules from the AutoFormatRules collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoveAll

expression A variable that represents an AutoFormatRules object.

Remarks

This method removes every AutoFormatRule object with a Standard property value set to False.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


AutoFormatRules.Save Method (Outlook)

 Copy code hover
[image]

AutoFormatRules.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Save all changes to AutoFormatRule objects within the AutoFormatRules collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents an AutoFormatRules object.

Remarks

Any changes made to the AutoFormatRules collection, such as adding or removing AutoFormatRule objects, or to an AutoFormatRule object within the collection, are persisted only if this method is called.

See also

Concepts

AutoFormatRules Object

Other resources

AutoFormatRules Object Members


BusinessCardView Object (Outlook)

 Copy code hover
[image]

BusinessCardView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays data as a series of Electronic Business Card (EBC) images.

Version Information

Version Added: Outlook 2007

Remarks

The BusinessCardView object, derived from the View object, allows you to create customizable views that allow you to better sort, group and ultimately view contact items in Outlook as a series of Electronic Business Cards, each of which displays the contact information for an Outlook contact item based on the EBC design associated with the contact item.

Use the Add method of the Views collection to add a new BusinessCardView to a Folder object.

Use the Filter property to determine which Outlook contact items to display in the view, the CardSize property to specify the size of each Electronic Business Card in the view, and the HeadingsFont to retrieve the ViewFont object for the view. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

Example

The following Visual Basic for Applications (VBA) example creates, saves, and applies a new BusinessCardView object.

Copy code Copy code
Sub CreateBusinessCardView()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As BusinessCardView

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Create the new view.

 Set objView = objViews.Add( _

 "Card View", _

 olBusinessCardView, _

 olViewSaveOptionAllFoldersOfType)

 ' Save and apply the new view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

BusinessCardView Object Members


BusinessCardView Members (Outlook)

 Copy code hover
[image]

BusinessCardView Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view that displays data as a series of Electronic Business Card (EBC) images.

Methods

Name | Description
Apply | Applies the BusinessCardView object to the current view.
Copy | Creates a new View object based on the existing BusinessCardView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CardSize | Returns or sets a Long value that represents the size, as a percentage, of an Electronic Business Card (EBC) in the view. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
HeadingsFont | Returns a ViewFont object that represents the font used to display headings for each Electronic Business Card (EBC) in the view. Read-only.
Language | Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields collection object that represents all the fields by which the view is sorted. Read-only.
Standard | Returns a Boolean value that indicates whether the BusinessCardView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that represents the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the current view. Read/write.


BusinessCardView Properties (Outlook)

 Copy code hover
[image]

BusinessCardView Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CardSize | Returns or sets a Long value that represents the size, as a percentage, of an Electronic Business Card (EBC) in the view. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
HeadingsFont | Returns a ViewFont object that represents the font used to display headings for each Electronic Business Card (EBC) in the view. Read-only.
Language | Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields collection object that represents all the fields by which the view is sorted. Read-only.
Standard | Returns a Boolean value that indicates whether the BusinessCardView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that represents the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the current view. Read/write.


BusinessCardView.Application Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.CardSize Property (Outlook)

 Copy code hover
[image]

BusinessCardView.CardSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the size, as a percentage, of an Electronic Business Card (EBC) in the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CardSize

expression An expression that returns a BusinessCardView object.

Remarks

This property can be set to a value between 20 and 100. If this property is set to a value less than 20, the property is set to 20. If this property is set to a value greater than 100, the property is set to 100.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Class Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a BusinessCardView object.

Remarks

This property returns olBusinessCardView for the BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Filter Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression An expression that returns a BusinessCardView object.

Remarks

The value of this property is a DAV Search and Locating (DASL) string that represents the current filter for the view.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.HeadingsFont Property (Outlook)

 Copy code hover
[image]

BusinessCardView.HeadingsFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display headings for each Electronic Business Card (EBC) in the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .HeadingsFont

expression An expression that returns a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Language Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.

Syntax

expression .Language

expression A variable that represents a BusinessCardView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Visual Basic for Applications (VBA) example sets the language type of all View objects of type olBusinessCArdView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olBusinessCardVIew then set language.

 If objView.ViewType = olBusinessCardView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

BusinessCardView.LockUserChanges Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression An expression that returns a BusinessCardView object.

Remarks

If True, the user can modify the settings of the current view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Name Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Parent Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.SaveOption Property (Outlook)

 Copy code hover
[image]

BusinessCardView.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression An expression that returns a BusinessCardView object.

Remarks

The value of the SaveOption property is set when the BusinessCardView object is created by using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Session Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a BusinessCardView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.SortFields Property (Outlook)

 Copy code hover
[image]

BusinessCardView.SortFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields collection object that represents all the fields by which the view is sorted. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SortFields

expression An expression that returns a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Standard Property (Outlook)

 Copy code hover
[image]

BusinessCardView.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the BusinessCardView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression An expression that returns a BusinessCardView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object, using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.ViewType Property (Outlook)

 Copy code hover
[image]

BusinessCardView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that represents the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression An expression that returns a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.XML Property (Outlook)

 Copy code hover
[image]

BusinessCardView.XML Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that specifies the XML definition of the current view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression An expression that returns a BusinessCardView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, create a view by using the Outlook user interface and then retrieve the XML property for that view.

Example

The following Visual Basic for Applications (VBA) example enumerates the Views collection of the Contacts default folder and displays the XML definition of a BusinessCardView object named "Card View".

VBA Copy code Copy code
Sub DisplayBusinessCardViewDef()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As BusinessCardView

 ' Get the Views collection of the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Return a view called "Card View." If the view

 ' doesn't already exist, create it.

 Set objView = objViews.Item("Card View")

 If objView Is Nothing Then

 Set objView = objViews.Add( _

 "Card View", _

 olBusinessCardView, _

 olViewSaveOptionAllFoldersOfType)

 End If

 ' Display the XML definition for the view.

 ' Note that the definition may be truncated

 ' due to the display limitations of the

 ' MsgBox function.

 MsgBox objView.XML

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView Methods (Outlook)

 Copy code hover
[image]

BusinessCardView Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the BusinessCardView object to the current view.
Copy | Creates a new View object based on the existing BusinessCardView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


BusinessCardView.Apply Method (Outlook)

 Copy code hover
[image]

BusinessCardView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the BusinessCardView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression An expression that returns a BusinessCardView object.

Example

The following Visual Basic for Applications (VBA) example creates, saves, and applies a new BusinessCardView object.

Copy code Copy code
Sub CreateBusinessCardView()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As BusinessCardView

 ' Get the Views collection of the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Create the new view.

 Set objView = objViews.Add( _

 "Card View", _

 olBusinessCardView, _

 olViewSaveOptionAllFoldersOfType)

 ' Save and apply the new view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Copy Method (Outlook)

 Copy code hover
[image]

BusinessCardView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing BusinessCardView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression An expression that returns a BusinessCardView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

Example

The following Visual Basic for Applications (VBA) example creates a copy of a BusinessCardView object, named "New Card View", and saves it in the Contacts default folder. To run this example, you need to first create a BusinessCardView object named "Card View" either programmatically or by using the Microsoft Outlook user interface.

VBA Copy code Copy code
Sub CopyBusinessCardView()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objNewView As BusinessCardView

 ' Get the Views collection of the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Copy the existing view.

 Set objNewView = objViews("Card View").Copy( _

 "New Card View", _

 olViewSaveOptionThisFolderEveryone)

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Delete Method (Outlook)

 Copy code hover
[image]

BusinessCardView.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression An expression that returns a BusinessCardView object.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.GoToDate Method (Outlook)

 Copy code hover
[image]

BusinessCardView.GoToDate Method (Outlook)
See also Send feedback

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression An expression that returns a BusinessCardView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Reset Method (Outlook)

 Copy code hover
[image]

BusinessCardView.Reset Method (Outlook)
See also Send feedback

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression An expression that returns a BusinessCardView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


BusinessCardView.Save Method (Outlook)

 Copy code hover
[image]

BusinessCardView.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression An expression that returns a BusinessCardView object.

Example

The following Visual Basic for Applications (VBA) example creates, saves, and applies a new BusinessCardView object.

Copy code Copy code
Sub CreateBusinessCardView()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As BusinessCardView

 ' Get the Views collection of the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Create the new view.

 Set objView = objViews.Add( _

 "Card View", _

 olBusinessCardView, _

 olViewSaveOptionAllFoldersOfType)

 ' Save and apply the new view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

BusinessCardView Object

Other resources

BusinessCardView Object Members


CalendarModule Object (Outlook)

 Copy code hover
[image]

CalendarModule Object (Outlook)
See also Send feedback

Represents the Calendar navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The CalendarModule object, derived from the NavigationModule object, provides access to the navigation groups contained in the Calendar navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the Modules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the navigation module type. If the NavigationModuleType property is set to olModuleCalendar, you can then cast the NavigationModule object reference as a CalendarModule object to access the NavigationGroups property for that navigation module.

You can use the Visible property to determine if the navigation module is visible and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Calendar navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

CalendarModule Object Members


CalendarModule Members (Outlook)

 Copy code hover
[image]

CalendarModule Members (Outlook)
Send feedback

Represents the Calendar navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the CalendarModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the CalendarModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the CalendarModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the CalendarModule object is displayed in the Navigation Pane. Read/write.


CalendarModule Properties (Outlook)

 Copy code hover
[image]

CalendarModule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the CalendarModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the CalendarModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the CalendarModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the CalendarModule object is displayed in the Navigation Pane. Read/write.


CalendarModule.Application Property (Outlook)

 Copy code hover
[image]

CalendarModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Class Property (Outlook)

 Copy code hover
[image]

CalendarModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a CalendarModule object.

Remarks

This property returns olCalendarModule for the CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Name Property (Outlook)

 Copy code hover
[image]

CalendarModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the CalendarModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

CalendarModule.NavigationGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroups object that contains the set of navigation groups associated with the CalendarModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

CalendarModule.NavigationModuleType Property (Outlook)
See also Send feedback

Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a CalendarModule object.

Remarks

This property returns olModuleCalendar for the CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Parent Property (Outlook)

 Copy code hover
[image]

CalendarModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Position Property (Outlook)

 Copy code hover
[image]

CalendarModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the CalendarModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a CalendarModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set it to a value outside of that range.

Changing the value of this property for a given CalendarModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified CalendarModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified CalendarModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

Example

The following Visual Basic for Applications (VBA) sample code attempts to retrieve the Calendar navigation module from the Navigation Pane. If it successfully retrieves the module, the code sets the Position property of the CalendarModule object to '1,' which moves it to the top of the Navigation Pane. Finally, the code sets the CurrentModule property of the NavigationPane object to the retrieved Calendar module, which selects it in the Navigation Pane.

VBA Copy code Copy code
Sub MoveCalendarModuleFirst()

 Dim objPane As NavigationPane

 Dim objModule As CalendarModule

 On Error GoTo ErrRoutine

 ' Get the current NavigationPane object.

 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Get the Calendar navigation module

 ' from the Navigation Pane.

 Set objModule = objPane.Modules.GetNavigationModule( _

 olModuleCalendar)

 ' If a CalendarModule object is present,

 ' make it the first navigation module displayed in the

 ' Navigation Pane.

 If Not (objModule Is Nothing) Then

 objModule.Position = 1

 End If

 ' Select the Calendar navigation module in the

 ' Navigation Pane.

 Set objPane.CurrentModule = objModule

EndRoutine:

 On Error GoTo 0

 Set objModule = Nothing

 Set objPane = Nothing

 Exit Sub

ErrRoutine:

 Debug.Print Err.Number & " (&H" & Hex(Err.Number) & ")"

 Select Case Err.Number

 Case -2147024809 '&H80070057

 ' Typically occurs if you set the Position

 ' property less than 1 or greater than 9.

 MsgBox Err.Number & " - " & Err.Description, _

 vbOKOnly Or vbCritical, _

 "MoveCalendarModuleFirst"

 End Select

 GoTo EndRoutine

End Sub

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Session Property (Outlook)

 Copy code hover
[image]

CalendarModule.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a CalendarModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarModule.Visible Property (Outlook)

 Copy code hover
[image]

CalendarModule.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the CalendarModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a CalendarModule object.

See also

Concepts

CalendarModule Object

Other resources

CalendarModule Object Members


CalendarSharing Object (Outlook)

 Copy code hover
[image]

CalendarSharing Object (Outlook)
See also Send feedback

Represents a set of utilities for sharing calendar information.

Version Information

Version Added: Outlook 2007

Remarks

You can use the GetCalendarExporter method of a Folder object that represents a calendar folder to create a CalendarSharing object. The GetCalendarExporter method can only be used on calendar folders. An error occurs if you use the method on Folder objects that represent other folder types.

You can use the SaveAsICal method to save calendar information in an iCalendar (.ics) file for sharing a calendar as a URL, or use the ForwardAsICal method to create a MailItem for sharing a calendar as a payload.

Note Note

The CalendarSharing object only supports exporting the iCalendar format.

Example

The following Visual Basic for Applications (VBA) example creates a CalendarSharing object for the Calendar folder, then exports the contents of the entire folder (including attachments and private items) to an iCalendar calendar (.ics) file.

VBA Copy code Copy code
Public Sub ExportEntireCalendar()

 Dim oNamespace As NameSpace

 Dim oFolder As Folder

 Dim oCalendarSharing As CalendarSharing

 On Error GoTo ErrRoutine

 ' Get a reference to the Calendar default folder

 Set oNamespace = Application.GetNamespace("MAPI")

 Set oFolder = oNamespace.GetDefaultFolder(olFolderCalendar)

 ' Get a CalendarSharing object for the Calendar default folder.

 Set oCalendarSharing = oFolder.GetCalendarExporter

 ' Set the CalendarSharing object to export the contents of

 ' the entire Calendar folder, including attachments and

 ' private items, in full detail.

 With oCalendarSharing

 .CalendarDetail = olFullDetails

 .IncludeAttachments = True

 .IncludePrivateDetails = True

 .IncludeWholeCalendar = True

 End With

 ' Export calendar to an iCalendar calendar (.ics) file.

 oCalendarSharing.SaveAsICal "C:\SampleCalendar.ics"

EndRoutine:

 On Error GoTo 0

 Set oCalendarSharing = Nothing

 Set oFolder = Nothing

 Set oNamespace = Nothing

Exit Sub

ErrRoutine:

 Select Case Err.Number

 Case 287 ' &H0000011F

 ' The user denied access to the Address Book.

 ' This error occurs if the code is run by an

 ' untrusted application, and the user chose not to

 ' allow access.

 MsgBox "Access to Outlook was denied by the user.", _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case -2147467259 ' &H80004005

 ' Export failed.

 ' This error typically occurs if the CalendarSharing

 ' method cannot export the calendar information because

 ' of conflicting property settings.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case -2147221233 ' &H8004010F

 ' Operation failed.

 ' This error typically occurs if the GetCalendarExporter method

 ' is called on a folder that doesn't contain calendar items.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case Else

 ' Any other error that may occur.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 End Select

 GoTo EndRoutine

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

CalendarSharing Object Members


CalendarSharing Members (Outlook)

 Copy code hover
[image]

CalendarSharing Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a set of utilities for sharing calendar information.

Methods

Name | Description
ForwardAsICal | Forwards calendar information from the parent Folder of the CalendarSharing object as the payload of a MailItem.
SaveAsICal | Exports calendar information from the parent Folder of the CalendarSharing object as an iCalendar calendar (.ics) file.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CalendarDetail | Returns or sets an OlCalendarDetail value indicating the level of detail for calendar items included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
EndDate | Returns or sets a Date value that represents the inclusive end date of the range of calendar items to be shared by the CalendarSharing object. Read/write.
Folder | Returns the Folder containing the calendar items to be shared by the CalendarSharing object. Read-only.
IncludeAttachments | Returns or sets a Boolean value that indicates whether attachments for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
IncludePrivateDetails | Returns or sets a Boolean value that indicates whether private details for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
IncludeWholeCalendar | Returns or sets a Boolean value that indicates whether all calendar items in the folder should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RestrictToWorkingHours | Returns or sets a Boolean value that indicates whether calendar items that do not occur within working hours should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
StartDate | Returns or sets a Date that represents the inclusive start date of the range of calendar items to be shared by the CalendarSharing object. Read/write.


CalendarSharing Properties (Outlook)

 Copy code hover
[image]

CalendarSharing Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CalendarDetail | Returns or sets an OlCalendarDetail value indicating the level of detail for calendar items included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
EndDate | Returns or sets a Date value that represents the inclusive end date of the range of calendar items to be shared by the CalendarSharing object. Read/write.
Folder | Returns the Folder containing the calendar items to be shared by the CalendarSharing object. Read-only.
IncludeAttachments | Returns or sets a Boolean value that indicates whether attachments for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
IncludePrivateDetails | Returns or sets a Boolean value that indicates whether private details for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
IncludeWholeCalendar | Returns or sets a Boolean value that indicates whether all calendar items in the folder should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RestrictToWorkingHours | Returns or sets a Boolean value that indicates whether calendar items that do not occur within working hours should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
StartDate | Returns or sets a Date that represents the inclusive start date of the range of calendar items to be shared by the CalendarSharing object. Read/write.


CalendarSharing.Application Property (Outlook)

 Copy code hover
[image]

CalendarSharing.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a CalendarSharing object.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.CalendarDetail Property (Outlook)

 Copy code hover
[image]

CalendarSharing.CalendarDetail Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlCalendarDetail value indicating the level of detail for calendar items included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CalendarDetail

expression An expression that returns a CalendarSharing object.

Return Value

A OlCalendarDetail value that indicates the level of detail for calendar items.

Remarks

The value of this property determines the allowable values for the following properties of the CalendarSharing object:

  • IncludeAttachments must be set to False if CalendarDetail is set to olFreeBusyOnly or olFreeBusyAndSubject.

  • IncludePrivateDetails must be set to False if CalendarDetail is set to olFreeBusyOnly.

  • RestrictToWorkingHours must be set to False if CalendarDetail is set to olFreeBusyAndSubject or olFullDetails.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.Class Property (Outlook)

 Copy code hover
[image]

CalendarSharing.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a CalendarSharing object.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.EndDate Property (Outlook)

 Copy code hover
[image]

CalendarSharing.EndDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the inclusive end date of the range of calendar items to be shared by the CalendarSharing object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndDate

expression An expression that returns a CalendarSharing object.

Return Value

A Date value representing the inclusive end date of the range of calendar items to be shared.

Remarks

This property is ignored if the IncludeWholeCalendar property of the CalendarSharing object is set to true.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.Folder Property (Outlook)

 Copy code hover
[image]

CalendarSharing.Folder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Folder containing the calendar items to be shared by the CalendarSharing object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Folder

expression An expression that returns a CalendarSharing object.

Return Value

The Folder containing the calendar items to be shared.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.IncludeAttachments Property (Outlook)

 Copy code hover
[image]

CalendarSharing.IncludeAttachments Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether attachments for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IncludeAttachments

expression An expression that returns a CalendarSharing object.

Return Value

True if attachments for calendar items should be included; otherwise, False.

Remarks

This property must be set to false if the CalendarDetail property of the CalendarSharing object is set to olFreeBusyOnly or olFreeBusyAndSubject.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.IncludePrivateDetails Property (Outlook)

 Copy code hover
[image]

CalendarSharing.IncludePrivateDetails Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether private details for calendar items should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.

Version Information

Version Added: Office System 2003

Syntax

expression .IncludePrivateDetails

expression An expression that returns a CalendarSharing object.

Return Value

True if private details for calendar items should be included; otherwise, False.

Remarks

This property must be set to false if the CalendarDetail property of the CalendarSharing object is set to olFreeBusyOnly.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.IncludeWholeCalendar Property (Outlook)

 Copy code hover
[image]

CalendarSharing.IncludeWholeCalendar Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether all calendar items in the folder should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.

Version Information

Version Added: Office System 2003

Syntax

expression .IncludeWholeCalendar

expression An expression that returns a CalendarSharing object.

Return Value

True if all calendar items in the folder should be included; otherwise, False.

Remarks

If this property is set to true, the StartDate and EndDate properties of the CalendarSharing object are ignored and all calendar items in the folder are included.

If this property is set to false, the StartDate and EndDate properties determine the range of calendar items to be included.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.Parent Property (Outlook)

 Copy code hover
[image]

CalendarSharing.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a CalendarSharing object.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.RestrictToWorkingHours Property (Outlook)

 Copy code hover
[image]

CalendarSharing.RestrictToWorkingHours Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether calendar items that do not occur within working hours should be included in the iCalendar (.ics) file created by the ForwardAsICal or SaveAsICal methods of the CalendarSharing object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .RestrictToWorkingHours

expression An expression that returns a CalendarSharing object.

Return Value

True if calendar items that do not occur within working hours should be included; otherwise, False.

Remarks

This property must be set to False if the CalendarDetail property of the CalendarSharing object is set to olFreeBusyOnly or olFullDetails..

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.Session Property (Outlook)

 Copy code hover
[image]

CalendarSharing.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a CalendarSharing object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.StartDate Property (Outlook)

 Copy code hover
[image]

CalendarSharing.StartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date that represents the inclusive start date of the range of calendar items to be shared by the CalendarSharing object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartDate

expression An expression that returns a CalendarSharing object.

Return Value

Date

Remarks

This property is ignored if the IncludeWholeCalendar property of the CalendarSharing object is set to True.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing Methods (Outlook)

 Copy code hover
[image]

CalendarSharing Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
ForwardAsICal | Forwards calendar information from the parent Folder of the CalendarSharing object as the payload of a MailItem.
SaveAsICal | Exports calendar information from the parent Folder of the CalendarSharing object as an iCalendar calendar (.ics) file.


CalendarSharing.ForwardAsICal Method (Outlook)

 Copy code hover
[image]

CalendarSharing.ForwardAsICal Method (Outlook)
See also Send feedback

Forwards calendar information from the parent Folder of the CalendarSharing object as the payload of a MailItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForwardAsICal(MailFormat)

expression An expression that returns a CalendarSharing object.

Parameters

Name | Required/Optional | Data Type | Description
MailFormat | Required | OlCalendarMailFormat | Determines the format of the calendar information in the body of the MailItem created by this method.

Return Value

A MailItem object that represents the new mail item to which the calendar information is attached.

Remarks

The ForwardAsICal method provides a single method by which you can use payload sharing to share a calendar with other users. The method:

  • Creates a MailItem object and provides a presentation of calendar information in the body of the mail item.

  • Creates an iCalendar (.ics) file containing the calendar information and attaches the file to the MailItem.

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarSharing.SaveAsICal Method (Outlook)

 Copy code hover
[image]

CalendarSharing.SaveAsICal Method (Outlook)
See also Send feedback

Published: July 16, 2012

Exports calendar information from the parent Folder of the CalendarSharing object as an iCalendar calendar (.ics) file.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveAsICal(Path)

expression An expression that returns a CalendarSharing object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path and file name of the iCalendar file.

Remarks

The level of detail provided in the iCalendar file is determined by a combination of values in the following CalendarSharing properties:

  • CalendarDetail

  • IncludeAttachments

  • IncludePrivateDetails

  • RestrictToWorkingHours

You can set the IncludeWholeCalendar property to True to export all items contained in the folder, or you can set the StartDate and EndDate properties to limit the exported items to a date range between a specified start date and end date, respectively.

Example

The following Visual Basic for Applications (VBA) example creates a CalendarSharing object for the Calendar folder, then exports the contents of the entire folder (including attachments and private items) to an iCalendar calendar (.ics) file.

VBA Copy code Copy code
Public Sub ExportEntireCalendar()

 Dim oNamespace As NameSpace

 Dim oFolder As Folder

 Dim oCalendarSharing As CalendarSharing

 On Error GoTo ErrRoutine

 ' Get a reference to the Calendar default folder

 Set oNamespace = Application.GetNamespace("MAPI")

 Set oFolder = oNamespace.GetDefaultFolder(olFolderCalendar)

 ' Get a CalendarSharing object for the Calendar default folder.

 Set oCalendarSharing = oFolder.GetCalendarExporter

 ' Set the CalendarSharing object to export the contents of

 ' the entire Calendar folder, including attachments and

 ' private items, in full detail.

 With oCalendarSharing

 .CalendarDetail = olFullDetails

 .IncludeWholeCalendar = True

 .IncludeAttachments = True

 .IncludePrivateDetails = True

 .RestrictToWorkingHours = False

 End With

 ' Export calendar to an iCalendar calendar (.ics) file.

 oCalendarSharing.SaveAsICal "C:\SampleCalendar.ics"

EndRoutine:

 On Error GoTo 0

 Set oCalendarSharing = Nothing

 Set oFolder = Nothing

 Set oNamespace = Nothing

Exit Sub

ErrRoutine:

 Select Case Err.Number

 Case 287 ' &H0000011F

 ' The user denied access to the Address Book.

 ' This error occurs if the code is run by an

 ' untrusted application, and the user chose not to

 ' allow access.

 MsgBox "Access to Outlook was denied by the user.", _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case -2147467259 ' &H80004005

 ' Export failed.

 ' This error typically occurs if the CalendarSharing

 ' method cannot export the calendar information because

 ' of conflicting property settings.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case -2147221233 ' &H8004010F

 ' Operation failed.

 ' This error typically occurs if the GetCalendarExporter method

 ' is called on a folder that doesn't contain calendar items.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 Case Else

 ' Any other error that may occur.

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 End Select

 GoTo EndRoutine

End Sub

See also

Concepts

CalendarSharing Object

Other resources

CalendarSharing Object Members


CalendarView Object (Outlook)

 Copy code hover
[image]

CalendarView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items in a calendar format.

Version Information

Version Added: Outlook 2007

Remarks

The CalendarView object, derived from the View object, allows you to create customizable views that allow you to display Outlook items within a calendar, in one of several different modes.

Outlook provides several built-in CalendarView objects, and you can also create custom CalendarView objects. Use the Add method of the Views collection to add a new CalendarView to a Folder object. Use the Standard property to determine if an existing CalendarView object is built-in or custom.

The CalendarView object supports several different view modes, depending on the desired layout and time period in which to display Outlook items. Use the CalendarViewMode property to set the view mode, the StartField property to specify the Outlook item property that contains the start date, and the EndField property to specify the Outlook item property that contains the end date for Outlook items to be displayed.

If you set the CalendarViewMode property to any value other than olCalendarViewMonth, you can use the DayWeekFont and DayWeekTimeFont properties to configure the fonts used to display the day, date, and time labels in the view. Use the DayWeekTimeScale to configure the time scale used to display Outlook items within the view. If you set the CalendarViewMode to olCalendarViewMultiDay, you can use the DaysInMultiDayMode property to determine the number of days to display in the view.

If you set the CalendarViewMode to olCalendarViewMonth, you can use the MonthFont property to configure the fonts used to display the month and day labels and the MonthShowEndTime to indicate whether the end time for is displayed in the view.

You can also configure how Outlook items appear within the CalendarView object. Use the BoldSubjects property to indicate whether subjects for Outlook items are displayed in bold and the BoldDatesWithItems property to indicate whether dates in the Date Navigator that contain Outlook items are displayed in bold. Use the Filter property to determine which Outlook items to display in the view.

The definition for each CalendarView object is stored in Extensible Markup Language (XML) format. Use the XML property to work with the XML definition for the CalendarView object.

Use the Apply method to apply any changes made to the CalendarView object to the current view. Use the Save method to persist any changes made to the CalendarView object. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

You can change built-in CalendarView objects, but you cannot delete them. Use the Delete method to delete a custom CalendarView object. Use the Reset method to reset the properties of a built-in CalendarView object to their default values.

Example

The following Visual Basic for Applications (VBA) example configures the current CalendarView object to show a single day, using an 8-point Verdana font to display items and a 16-point Verdana font to display time values and the Tasks header within the view.

Copy code Copy code
Sub ConfigureDayViewFonts()
 Dim objView As CalendarView

 ' Check if the current view is a calendar view.
 If Application.ActiveExplorer.CurrentView.ViewType = _
 olCalendarView Then

 ' Obtain a CalendarView object reference for the
 ' current calendar view.
 Set objView = _
 Application.ActiveExplorer.CurrentView

 With objView
 ' Set the calendar view to show a
 ' single day.
 .CalendarViewMode = olCalendarViewDay

 ' Set the DayWeekFont to 8-point Verdana.
 .DayWeekFont.Name = "Verdana"
 .DayWeekFont.Size = 8

 ' Set the DayWeekTimeFont to 16-point Verdana.
 .DayWeekTimeFont.Name = "Verdana"
 .DayWeekTimeFont.Size = 16

 ' Save the calendar view.
 .Save
 End With
 End If
End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

CalendarView Object Members


CalendarView Members (Outlook)

 Copy code hover
[image]

CalendarView Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items in a calendar format.

Methods

Name | Description
Apply | Applies the CalendarView object to the current view.
Copy | Creates a new View object based on the existing CalendarView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CalendarView object. Read-only.
BoldDatesWithItems | Returns or sets a Boolean value that indicates whether days that contain Outlook items should be displayed in bold within the Date Navigator for the CalendarView object. Read/write.
BoldSubjects | Returns or sets a Boolean value that indicates whether the subject information for Outlook items is displayed in bold within a CalendarView object. Read/write
CalendarViewMode | Returns or sets an OlCalendarViewMode that determines the current view mode of the CalendarView object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DaysInMultiDayMode | Returns or sets a Long value that represents the number of consecutive days displayed in the CalendarView object. Read/write
DayWeekTimeScale | Returns or sets an OlDayWeekTimeScale constant that represents the scale used to represent time periods in a CalendarView object. Read/write.
DisplayedDates | Returns a Variant array containing strings that represent the days displayed in a CalendarView object. Read-only.
EndField | Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the CalendarView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MonthShowEndTime | Returns or sets a Boolean value that indicates whether end times for Outlook items are displayed in the CalendarView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
SelectedEndTime | Returns a Date that represents the end time of a selection in the CalendarView object. Read-only.
SelectedStartTime | Returns a Date that represents the start time of a selection in the CalendarView object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean value that indicates whether the CalendarView object is a built-in Outlook view. Read-only.
StartField | Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the CalendarView object. Read/write.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


CalendarView Properties (Outlook)

 Copy code hover
[image]

CalendarView Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CalendarView object. Read-only.
BoldDatesWithItems | Returns or sets a Boolean value that indicates whether days that contain Outlook items should be displayed in bold within the Date Navigator for the CalendarView object. Read/write.
BoldSubjects | Returns or sets a Boolean value that indicates whether the subject information for Outlook items is displayed in bold within a CalendarView object. Read/write
CalendarViewMode | Returns or sets an OlCalendarViewMode that determines the current view mode of the CalendarView object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DaysInMultiDayMode | Returns or sets a Long value that represents the number of consecutive days displayed in the CalendarView object. Read/write
DayWeekTimeScale | Returns or sets an OlDayWeekTimeScale constant that represents the scale used to represent time periods in a CalendarView object. Read/write.
DisplayedDates | Returns a Variant array containing strings that represent the days displayed in a CalendarView object. Read-only.
EndField | Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the CalendarView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MonthShowEndTime | Returns or sets a Boolean value that indicates whether end times for Outlook items are displayed in the CalendarView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
SelectedEndTime | Returns a Date that represents the end time of a selection in the CalendarView object. Read-only.
SelectedStartTime | Returns a Date that represents the start time of a selection in the CalendarView object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean value that indicates whether the CalendarView object is a built-in Outlook view. Read-only.
StartField | Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the CalendarView object. Read/write.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


CalendarView.Application Property (Outlook)

 Copy code hover
[image]

CalendarView.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.AutoFormatRules Property (Outlook)

 Copy code hover
[image]

CalendarView.AutoFormatRules Property (Outlook)
See also Send feedback

Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CalendarView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoFormatRules

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.BoldDatesWithItems Property (Outlook)

 Copy code hover
[image]

CalendarView.BoldDatesWithItems Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether days that contain Outlook items should be displayed in bold within the Date Navigator for the CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BoldDatesWithItems

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.BoldSubjects Property (Outlook)

 Copy code hover
[image]

CalendarView.BoldSubjects Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the subject information for Outlook items is displayed in bold within a CalendarView object. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .BoldSubjects

expression An expression that returns a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.CalendarViewMode Property (Outlook)

 Copy code hover
[image]

CalendarView.CalendarViewMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlCalendarViewMode that determines the current view mode of the CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CalendarViewMode

expression A variable that represents a CalendarView object.

Example

The following Visual Basic for Applications (VBA) example configures the current CalendarView object to show a single day, using an 8-point Verdana font to display items and a 16-point Verdana font to display time values and the Tasks header within the view.

Copy code Copy code
Sub ConfigureDayViewFonts()

 Dim objView As CalendarView

 ' Check if the current view is a calendar view.

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olCalendarView Then

 ' Obtain a CalendarView object reference for the

 ' current calendar view.

 Set objView = _

 Application.ActiveExplorer.CurrentView

 With objView

 ' Set the calendar view to show a

 ' single day.

 .CalendarViewMode = olCalendarViewDay

 ' Set the DayWeekFont to 8-point Verdana.

 .DayWeekFont.Name = "Verdana"

 .DayWeekFont.Size = 8

 ' Set the DayWeekTimeFont to 16-point Verdana.

 .DayWeekTimeFont.Name = "Verdana"

 .DayWeekTimeFont.Size = 16

 ' Save the calendar view.

 .Save

 End With

 End If

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Class Property (Outlook)

 Copy code hover
[image]

CalendarView.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.DaysInMultiDayMode Property (Outlook)

 Copy code hover
[image]

CalendarView.DaysInMultiDayMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the number of consecutive days displayed in the CalendarView object. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .DaysInMultiDayMode

expression A variable that represents a CalendarView object.

Remarks

This property can be set to a value between 2 and 14. If this property is set to a value less than 2, the property is set to 2. If the this property is set to a value greater than 14, the property is set to 14. The default value for this property is 5.

Example

The following Visual Basic for Applications (VBA) example creates a new CalendarView object in the Calendar default folder, and then configures it to display 14 consecutive days in multi-day mode, with Outlook items displayed within an hourly time scale.

Copy code Copy code
Sub CreateTwoWeekView()

 Dim objNamespace As NameSpace

 Dim objFolder As Folder

 Dim objView As CalendarView

 ' Obtain Folder object reference to the Calendar default folder.

 Set objNamespace = Application.GetNamespace("MAPI")

 Set objFolder = objNamespace.GetDefaultFolder(olFolderCalendar)

 ' Create a new CalendarView object named "Two Weeks".

 Set objView = objFolder.Views.Add("Two Weeks", _

 olCalendarView, _

 olViewSaveOptionAllFoldersOfType)

 ' Configure the new CalendarView object.

 With objView

 ' Display the view in multi-day mode.

 .CalendarViewMode = olCalendarViewMultiDay

 ' Display 14 consecutive days in multi-day

 ' mode.

 .DaysInMultiDayMode = 14

 ' Set the time scale for the view in one-hour

 ' intervals.

 .DayWeekTimeScale = olTimeScale60Minutes

 ' Save and apply the new CalendarView object.

 .Save

 .Apply

 End With

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.DayWeekTimeScale Property (Outlook)

 Copy code hover
[image]

CalendarView.DayWeekTimeScale Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDayWeekTimeScale constant that represents the scale used to represent time periods in a CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DayWeekTimeScale

expression A variable that represents a CalendarView object.

Example

The following Visual Basic for Applications (VBA) example creates a new CalendarView object in the Calendar default folder, and then configures it to display 14 consecutive days in multi-day mode, with Outlook items displayed within an hourly time scale.

Copy code Copy code
Sub CreateTwoWeekView()

 Dim objNamespace As NameSpace

 Dim objFolder As Folder

 Dim objView As CalendarView

 ' Obtain Folder object reference to the Calendar default folder.

 Set objNamespace = Application.GetNamespace("MAPI")

 Set objFolder = objNamespace.GetDefaultFolder(olFolderCalendar)

 ' Create a new CalendarView object named "Two Weeks".

 Set objView = objFolder.Views.Add("Two Weeks", _

 olCalendarView, _

 olViewSaveOptionAllFoldersOfType)

 ' Configure the new CalendarView object.

 With objView

 ' Display the view in multi-day mode.

 .CalendarViewMode = olCalendarViewMultiDay

 ' Display 14 consecutive days in multi-day

 ' mode.

 .DaysInMultiDayMode = 14

 ' Set the time scale for the view in one-hour

 ' intervals.

 .DayWeekTimeScale = olTimeScale60Minutes

 ' Save and apply the new CalendarView object.

 .Save

 .Apply

 End With

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.DisplayedDates Property (Outlook)

 Copy code hover
[image]

CalendarView.DisplayedDates Property (Outlook)
See also Send feedback

Returns a Variant array containing strings that represent the days displayed in a CalendarView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayedDates

expression A variable that represents a CalendarView object.

Remarks

This property returns an array of date strings, in which each date string represents a day displayed in the CalendarView object. The date strings are formatted using the short date format settings for the operating system.

Example

The following Visual Basic for Applications (VBA) example obtains the value of the DisplayedDates property from the current CalendarView object, then displays a dialog box with a summary of that property value.

VBA Copy code Copy code
Sub DisplayDayRange()

 Dim objView As CalendarView

 Dim varArray As Variant

 ' Check if the current view is a calendar view.

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olCalendarView Then

 ' Obtain a CalendarView object reference for the

 ' current calendar view.

 Set objView = _

 Application.ActiveExplorer.CurrentView

 ' Obtain the DisplayedDates value, a string

 ' array of dates representing the dates displayed

 ' in the calendar view.

 varArray = objView.DisplayedDates

 ' If the example obtained a valid array, display

 ' a dialog box with a summary of its contents.

 If IsArray(varArray) Then

 MsgBox "There are " & _

 (UBound(varArray) - LBound(varArray)) + 1 & _

 " days displayed, from " & _

 varArray(LBound(varArray)) & _

 " to " & _

 varArray(UBound(varArray))

 End If

 End If

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.EndField Property (Outlook)

 Copy code hover
[image]

CalendarView.EndField Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndField

expression A variable that represents a CalendarView object.

Remarks

The values of the StartField and EndField properties indicate which Outlook item properties are used by the CalendarView object to represent the duration of an Outlook item. Both custom and built-in properties can be specified, but only date/time properties are allowed.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Filter Property (Outlook)

 Copy code hover
[image]

CalendarView.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents a CalendarView object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Language Property (Outlook)

 Copy code hover
[image]

CalendarView.Language Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the language setting for the view. Read/write.

Syntax

expression .Language

expression A variable that represents a CalendarView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the language type of all View objects of type olTableView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olTableVIew then set language.

 If objView.ViewType = olTableView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

CalendarView.LockUserChanges Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression A variable that represents a CalendarView object.

Remarks

If True, the user can modify the settings of the specified view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.MonthShowEndTime Property (Outlook)

 Copy code hover
[image]

CalendarView.MonthShowEndTime Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether end times for Outlook items are displayed in the CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MonthShowEndTime

expression A variable that represents a CalendarView object.

Remarks

The value of this property is applicable only when the CalendarViewMode property of the CalendarView object is set to olCalendarViewMonth.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Name Property (Outlook)

 Copy code hover
[image]

CalendarView.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Parent Property (Outlook)

 Copy code hover
[image]

CalendarView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.SaveOption Property (Outlook)

 Copy code hover
[image]

CalendarView.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression A variable that represents a CalendarView object.

Remarks

The value of the SaveOption property is set when the CalendarView object is created by using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = _

 olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.SelectedEndTime Property (Outlook)

 Copy code hover
[image]

CalendarView.SelectedEndTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that represents the end time of a selection in the CalendarView object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectedEndTime

expression A variable that represents a CalendarView object.

Remarks

The intent of the SelectedStartTime and the SelectedEndTime properties is to replicate, programmatically, the way that users create an appointment in the Microsoft Outlook user interface. Typically, a user selects a time range in the calendar view and then creates a new appointment by double clicking the selection or by clicking New Appointment in the Home tab of the ribbon. With these two properties of the CalendarView object, you can obtain the start time and the end time of any selection in that view programmatically. You can then programmatically create the AppointmentItem object, setting the Start and End properties of the AppointmentItem object to the SelectedStartTime and SelectedEndTime properties respectively to reflect any user selection in the calendar view.

If the selection in the calendar view is a time range and is not an item, SelectedEndTime returns a Date value equal to the end time of the selection.

If one or more items are selected in the calendar view, SelectedEndTime returns a Date value equal to the end time of the first item in the selection of the explorer that displays the calendar view. That selection is specified by the Selection property of the Explorer object.

To use this property on a CalendarView object, obtain the CalendarView object from the CurrentView property of the active Explorer object (which can be returned by the Application.ActiveExplorer method). There is a known issue with using this property on an CalendarView object obtained otherwise - using the CurrentView property of the current Folder object (returned by the Application.ActiveExplorer.CurrentFolder property).

Example

The following code samples, in Visual Basic for Applications (VBA) and C#, show how to use the SelectedStartTime and SelectedEndTime properties of the calendar view of the active explorer to initialize the start and end times of a new appointment. The following code sample is in VBA.

VBA Copy code Copy code
Sub CreateAppointmentUsingSelectedTime()
 Dim datStart As Date
 Dim datEnd As Date
 Dim oView As Outlook.view
 Dim oCalView As Outlook.CalendarView
 Dim oExpl As Outlook.Explorer
 Dim oFolder As Outlook.folder
 Dim oAppt As Outlook.AppointmentItem
 Const datNull As Date = #1/1/4501#

 ' Obtain the calendar view using
 ' Application.ActiveExplorer.CurrentFolder.CurrentView.
 ' If you use oExpl.CurrentFolder.CurrentView,
 ' this code will not operate as expected.
 Set oExpl = Application.ActiveExplorer
 Set oFolder = Application.ActiveExplorer.CurrentFolder
 Set oView = oExpl.CurrentView

 ' Check whether the active explorer is displaying a calendar view.
 If oView.ViewType = olCalendarView Then
 Set oCalView = oExpl.currentView
 ' Create the appointment using the values in
 ' the SelectedStartTime and SelectedEndTime properties as
 ' appointment start and end times.
 datStart = oCalView.SelectedStartTime
 datEnd = oCalView.SelectedEndTime
 Set oAppt = oFolder.items.Add("IPM.Appointment")
 If datStart <> datNull And datEnd <> datNull Then
 oAppt.Start = datStart
 oAppt.End = datEnd
 End If
 oAppt.Display
 End If
End Sub

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void CreateAppointmentUsingSelectedTime()
{
 DateTime dateNull =
 new DateTime(4501, 1, 1, 0, 0, 0);
 Outlook.Explorer expl = Application.ActiveExplorer();
 Outlook.Folder folder = expl.CurrentFolder as Outlook.Folder;
 Outlook.View view = expl.CurrentView as Outlook.View;
 if (view.ViewType == Outlook.OlViewType.olCalendarView)
 {
 Outlook.CalendarView calView = view as Outlook.CalendarView;
 DateTime dateStart = calView.SelectedStartTime;
 DateTime dateEnd = calView.SelectedEndTime;
 Outlook.AppointmentItem appt =
 folder.Items.Add("IPM.Appointment")
 as Outlook.AppointmentItem;
 if (dateStart != dateNull && dateEnd != dateNull)
 {
 appt.Start = dateStart;
 appt.End = dateEnd;
 }
 appt.Display(false);
 }
}

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.SelectedStartTime Property (Outlook)

 Copy code hover
[image]

CalendarView.SelectedStartTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that represents the start time of a selection in the CalendarView object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectedStartTime

expression A variable that represents a CalendarView object.

Remarks

The intent of the SelectedStartTime and SelectedEndTime properties is to replicate, programmatically, the way that users create an appointment in the Microsoft Outlook user interface. Typically, a user selects a time range in the calendar view and then creates a new appointment by either double clicking the selection or clicking New Appointment in the Home tab of the ribbon. With these two properties of the CalendarView object, you can obtain the start time and the end time of any selection in that view programmatically. You can then programmatically create the AppointmentItem object, setting the Start and End properties of the AppointmentItem object to the SelectedStartTime and SelectedEndTime properties respectively to reflect any user selection in the calendar view.

If the selection in the calendar view is a time range and is not an item, SelectedStartTime returns a Date value equal to the start time of the selection.

If one or more items are selected in the calendar view, SelectedStartTime returns a Date value equal to the start time of the first item in the selection of the explorer that displays the calendar view. That selection is specified by the Selection property of the Explorer object.

To use this property on a CalendarView object, obtain the CalendarView object from the CurrentView property of the active Explorer object (which can be returned by the Application.ActiveExplorer method). There is a known issue with using this property on an CalendarView object obtained otherwise - using the CurrentView property of the current Folder object (returned by the Application.ActiveExplorer.CurrentFolder property).

Example

The following code samples, in Visual Basic for Applications (VBA) and C#, show how to use the SelectedStartTime and SelectedEndTime properties of the calendar view of the active explorer to initialize the start and end times of a new appointment. The following code sample is in VBA.

VBA Copy code Copy code
Sub CreateAppointmentUsingSelectedTime()
 Dim datStart As Date
 Dim datEnd As Date
 Dim oView As Outlook.view
 Dim oCalView As Outlook.CalendarView
 Dim oExpl As Outlook.Explorer
 Dim oFolder As Outlook.folder
 Dim oAppt As Outlook.AppointmentItem
 Const datNull As Date = #1/1/4501#

 ' Obtain the calendar view using
 ' Application.ActiveExplorer.CurrentFolder.CurrentView.
 ' If you use oExpl.CurrentFolder.CurrentView,
 ' this code will not operate as expected.
 Set oExpl = Application.ActiveExplorer
 Set oFolder = Application.ActiveExplorer.CurrentFolder
 Set oView = oExpl.CurrentView

 ' Check whether the active explorer is displaying a calendar view.
 If oView.ViewType = olCalendarView Then
 Set oCalView = oExpl.currentView
 ' Create the appointment using the values in
 ' the SelectedStartTime and SelectedEndTime properties as
 ' appointment start and end times.
 datStart = oCalView.SelectedStartTime
 datEnd = oCalView.SelectedEndTime
 Set oAppt = oFolder.items.Add("IPM.Appointment")
 If datStart <> datNull And datEnd <> datNull Then
 oAppt.Start = datStart
 oAppt.End = datEnd
 End If
 oAppt.Display
 End If
End Sub

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

C# Copy code Copy code
private void CreateAppointmentUsingSelectedTime()
{
 DateTime dateNull =
 new DateTime(4501, 1, 1, 0, 0, 0);
 Outlook.Explorer expl = Application.ActiveExplorer();
 Outlook.Folder folder = expl.CurrentFolder as Outlook.Folder;
 Outlook.View view = expl.CurrentView as Outlook.View;
 if (view.ViewType == Outlook.OlViewType.olCalendarView)
 {
 Outlook.CalendarView calView = view as Outlook.CalendarView;
 DateTime dateStart = calView.SelectedStartTime;
 DateTime dateEnd = calView.SelectedEndTime;
 Outlook.AppointmentItem appt =
 folder.Items.Add("IPM.Appointment")
 as Outlook.AppointmentItem;
 if (dateStart != dateNull && dateEnd != dateNull)
 {
 appt.Start = dateStart;
 appt.End = dateEnd;
 }
 appt.Display(false);
 }
}

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Session Property (Outlook)

 Copy code hover
[image]

CalendarView.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a CalendarView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Standard Property (Outlook)

 Copy code hover
[image]

CalendarView.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the CalendarView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression An expression that returns a CalendarView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.StartField Property (Outlook)

 Copy code hover
[image]

CalendarView.StartField Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the CalendarView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartField

expression A variable that represents a CalendarView object.

Remarks

The values of the StartField and EndField properties indicate which Outlook item properties are used by the CalendarView object to represent the duration of an Outlook item. Both custom and built-in properties can be specified, but only date/time properties are allowed.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.ViewType Property (Outlook)

 Copy code hover
[image]

CalendarView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.XML Property (Outlook)

 Copy code hover
[image]

CalendarView.XML Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression A variable that represents a CalendarView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView Methods (Outlook)

 Copy code hover
[image]

CalendarView Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the CalendarView object to the current view.
Copy | Creates a new View object based on the existing CalendarView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


CalendarView.Apply Method (Outlook)

 Copy code hover
[image]

CalendarView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the CalendarView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Copy Method (Outlook)

 Copy code hover
[image]

CalendarView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing CalendarView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents a CalendarView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Delete Method (Outlook)

 Copy code hover
[image]

CalendarView.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.GoToDate Method (Outlook)

 Copy code hover
[image]

CalendarView.GoToDate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents a CalendarView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Reset Method (Outlook)

 Copy code hover
[image]

CalendarView.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression A variable that represents a CalendarView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CalendarView.Save Method (Outlook)

 Copy code hover
[image]

CalendarView.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a CalendarView object.

See also

Concepts

CalendarView Object

Other resources

CalendarView Object Members


CardView Object (Outlook)

 Copy code hover
[image]

CardView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items as a series of index cards.

Version Information

Version Added: Outlook 2007

Remarks

The CardView object, derived from the View object, allows you to create customizable views that allow you to display Outlook items as index cards.

Outlook provides several built-in CardView objects, and you can also create custom CardView objects. Use the Add method of the Views collection to add a new CardView to a Folder object. Use the Standard property to determine if an existing CardView object is built-in or custom.

You can configure how Outlook items appear within the CardView object. Use the MultiLineFieldHeight property to specify the number of lines used to display multi-line text in each card, the HeadingsFont property to specify the font used to display heading text on each card, and the BodyFont property to specify the font used to display body text on each card. Use the AllowInCellEditing property to allow editing of Outlook item property values in the view, and the ShowEmptyFields property to display empty Outlook item properties in the view. Use the Filter property to determine which Outlook items to display in the view, the ViewFields collection to specify the Outlook item properties to display in each card, and the SortFields collection to specify the Outlook item properties by which Outlook items are sorted in the view.

The definition for each CardView object is stored in Extensible Markup Language (XML) format. Use the XML property to work with the XML definition for the CardView object.

Use the Apply method to apply any changes made to the CardView object to the current view. Use the Save method to persist any changes made to the CardView object. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

You can change built-in CardView objects, but you cannot delete them. Use the Delete method to delete a custom CardView object. Use the Reset method to reset the properties of a built-in CardView object to their default values.

See also

Concepts

Outlook Object Model Reference

Other resources

CardView Object Members


CardView Members (Outlook)

 Copy code hover
[image]

CardView Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items as a series of index cards.

Methods

Name | Description
Apply | Applies the CardView object to the current view.
Copy | Creates a new View object based on the existing CardView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
AllowInCellEditing | Returns or sets a Boolean value that determines whether in-cell editing is allowed in the CardView object. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CardView object. Read-only.
BodyFont | Returns a ViewFont object that represents the font used to display the body of each card in the CardView object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
HeadingsFont | Returns a ViewFont object that represents the font used to display the heading of each card in the CardView object. Read-only.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MultiLineFieldHeight | Returns or sets a Long value that determines the minimum number of lines for multiline fields displayed in the CardView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowEmptyFields | Returns or sets a Boolean value that determines if empty fields are displayed for cards in the CardView object. Read/write.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the CardView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the CardView object is a built-in Outlook view. Read-only.
ViewFields | Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the CardView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
Width | Returns or sets a Long value indicating the width (in characters) of cards in the CardView object. Read/write.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


CardView Properties (Outlook)

 Copy code hover
[image]

CardView Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AllowInCellEditing | Returns or sets a Boolean value that determines whether in-cell editing is allowed in the CardView object. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CardView object. Read-only.
BodyFont | Returns a ViewFont object that represents the font used to display the body of each card in the CardView object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
HeadingsFont | Returns a ViewFont object that represents the font used to display the heading of each card in the CardView object. Read-only.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MultiLineFieldHeight | Returns or sets a Long value that determines the minimum number of lines for multiline fields displayed in the CardView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowEmptyFields | Returns or sets a Boolean value that determines if empty fields are displayed for cards in the CardView object. Read/write.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the CardView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the CardView object is a built-in Outlook view. Read-only.
ViewFields | Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the CardView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
Width | Returns or sets a Long value indicating the width (in characters) of cards in the CardView object. Read/write.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


CardView.AllowInCellEditing Property (Outlook)

 Copy code hover
[image]

CardView.AllowInCellEditing Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that determines whether in-cell editing is allowed in the CardView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AllowInCellEditing

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Application Property (Outlook)

 Copy code hover
[image]

CardView.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.AutoFormatRules Property (Outlook)

 Copy code hover
[image]

CardView.AutoFormatRules Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AutoFormatRules object that represents the set of formatting rules applicable to the CardView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoFormatRules

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.BodyFont Property (Outlook)

 Copy code hover
[image]

CardView.BodyFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display the body of each card in the CardView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .BodyFont

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Class Property (Outlook)

 Copy code hover
[image]

CardView.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Filter Property (Outlook)

 Copy code hover
[image]

CardView.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents a CardView object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.HeadingsFont Property (Outlook)

 Copy code hover
[image]

CardView.HeadingsFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display the heading of each card in the CardView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .HeadingsFont

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Language Property (Outlook)

 Copy code hover
[image]

CardView.Language Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the language setting for the view. Read/write.

Syntax

expression .Language

expression A variable that represents a CardView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the language type of all View objects of type olTableView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olTableVIew then set language.

 If objView.ViewType = olTableView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

CardView.LockUserChanges Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression A variable that represents a CardView object.

Remarks

If True, the user can modify the settings of the specified view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.MultiLineFieldHeight Property (Outlook)

 Copy code hover
[image]

CardView.MultiLineFieldHeight Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that determines the minimum number of lines for multiline fields displayed in the CardView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MultiLineFieldHeight

expression A variable that represents a CardView object.

Remarks

This property can be set to a value between 1 and 20. If this property is set to a value less than 1, the property is set to 1. If this property is set to a value greater than 20, the property is set to 20. The default value for this property is 1.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Name Property (Outlook)

 Copy code hover
[image]

CardView.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Parent Property (Outlook)

 Copy code hover
[image]

CardView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.SaveOption Property (Outlook)

 Copy code hover
[image]

CardView.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression A variable that represents a CardView object.

Remarks

The value of the SaveOption property is set when the CardView object is created by using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = _

 olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Session Property (Outlook)

 Copy code hover
[image]

CardView.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a CardView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.ShowEmptyFields Property (Outlook)

 Copy code hover
[image]

CardView.ShowEmptyFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines if empty fields are displayed for cards in the CardView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowEmptyFields

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.SortFields Property (Outlook)

 Copy code hover
[image]

CardView.SortFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields object that represents the set of fields by which the items displayed in the CardView object are ordered. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SortFields

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Standard Property (Outlook)

 Copy code hover
[image]

CardView.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the CardView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression A variable that represents a CardView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.ViewFields Property (Outlook)

 Copy code hover
[image]

CardView.ViewFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the CardView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewFields

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.ViewType Property (Outlook)

 Copy code hover
[image]

CardView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Width Property (Outlook)

 Copy code hover
[image]

CardView.Width Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value indicating the width (in characters) of cards in the CardView object. Read/write.

Syntax

expression .Width

expression A variable that represents a CardView object.

Remarks

This property can be set to a value between 20 and 1000. If this property is set to a value less than 20, the property is set to 20. If this property is set to a value greater than 1000, the property is set to 1000.

The default value for this property depends on the DefaultItemType property value of the Folder object displayed by the view:

DefaultItemType value | Default value
olAppointmentItem | 40
olContactItem, olDistributionListItem | 36
olJournalItem, olMailItem, olNoteItem, olPostItem | 32
olTaskItem | 50

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.XML Property (Outlook)

 Copy code hover
[image]

CardView.XML Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression A variable that represents a CardView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView Methods (Outlook)

 Copy code hover
[image]

CardView Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the CardView object to the current view.
Copy | Creates a new View object based on the existing CardView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


CardView.Apply Method (Outlook)

 Copy code hover
[image]

CardView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the CardView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Copy Method (Outlook)

 Copy code hover
[image]

CardView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing CardView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents a CardView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Delete Method (Outlook)

 Copy code hover
[image]

CardView.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.GoToDate Method (Outlook)

 Copy code hover
[image]

CardView.GoToDate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents a CardView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Reset Method (Outlook)

 Copy code hover
[image]

CardView.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression A variable that represents a CardView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

CardView Object

Other resources

CardView Object Members


CardView.Save Method (Outlook)

 Copy code hover
[image]

CardView.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a CardView object.

See also

Concepts

CardView Object

Other resources

CardView Object Members


Categories Object (Outlook)

 Copy code hover
[image]

Categories Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the collection of Category objects that define the Master Category List for a namespace.

Version Information

Version Added: Outlook 2007

Remarks

Microsoft Outlook provides a categorization system by which Outlook items can be easily identified and grouped into user-defined categories. The Categories object represents the set of user-defined categories available to the user of a given mailbox.

Use the Categories property of the NameSpace object to obtain a Categories object reference, representing the Master Category List for that namespace.

Use the Add method to create a new Category object and append it to the collection. Use the Item method to obtain a Category object reference for an existing category, and the Remove method to remove a Category object from the collection. Use the Count property to return the number of categories contained in the collection.

Example

The following Visual Basic for Applications (VBA) example displays a dialog box containing the names and identifiers for each Category object contained in the Categories collection associated with the default NameSpace object.

VBA Copy code Copy code
Private Sub ListCategoryIDs()
 Dim objNameSpace As NameSpace
 Dim objCategory As Category
 Dim strOutput As String

 ' Obtain a NameSpace object reference.
 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check if the Categories collection for the Namespace
 ' contains one or more Category objects.
 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection.
 For Each objCategory In objNameSpace.Categories

 ' Add the name and ID of the Category object to
 ' the output string.
 strOutput = strOutput & objCategory.Name & _
 ": " & objCategory.CategoryID & vbCrLf
 Next
 End If

 ' Display the output string.
 MsgBox strOutput

 ' Clean up.
 Set objCategory = Nothing
 Set objNameSpace = Nothing

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Categories Object Members


Categories Members (Outlook)

 Copy code hover
[image]

Categories Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the collection of Category objects that define the Master Category List for a namespace.

Methods

Name | Description
Add | Creates a new Category object and appends it to the Categories collection.
Item | Returns a Category object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of Category objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Categories Properties (Outlook)

 Copy code hover
[image]

Categories Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of Category objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Categories.Application Property (Outlook)

 Copy code hover
[image]

Categories.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Categories object.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Class Property (Outlook)

 Copy code hover
[image]

Categories.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Categories object.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Count Property (Outlook)

 Copy code hover
[image]

Categories.Count Property (Outlook)
See also Send feedback

Returns a Long value indicating the count of Category objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Categories object.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Parent Property (Outlook)

 Copy code hover
[image]

Categories.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Categories object.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Session Property (Outlook)

 Copy code hover
[image]

Categories.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Categories object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories Methods (Outlook)

 Copy code hover
[image]

Categories Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Add | Creates a new Category object and appends it to the Categories collection.
Item | Returns a Category object from the collection.
Remove | Removes an object from the collection.


Categories.Add Method (Outlook)

 Copy code hover
[image]

Categories.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new Category object and appends it to the Categories collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(Name, Color, ShortcutKey)

expression A variable that represents a Categories object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new category.
Color | Optional | OlCategoryColor | The color for the new category. If no value is specified, the new category is set to the first color (as specified in the order of the OlCategoryColor enumeration) that is the least used, That is, if there are unused colors, the new category is set to the first unused color in the OlCategoryColor enumeration. If all colors in the OlCategoryColor enumeration have been used, then the new category is set to the first color that is used least in the OlCategoryColor enumeration.
ShortcutKey | Optional | OlCategoryShortcutKey | The shortcut key for the new category. If no value is specified, the default value is OlCategoryShortcutKeyNone.

Return Value

A Category object that represents the new category.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Item Method (Outlook)

 Copy code hover
[image]

Categories.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Category object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a Categories object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either a Long value representing the index number of the object, or a String value representing either the Name or CategoryID property value of an object in the collection.

Return Value

A Category object that represents the specified object.

Remarks

If the name of a category is specified in Index, this method returns the first Category object that matches the specified value. If a match cannot be found, the method returns Null (Nothing in Visual Basic.)

See also

Concepts

Categories Object

Other resources

Categories Object Members


Categories.Remove Method (Outlook)

 Copy code hover
[image]

Categories.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents a Categories object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either a Long value representing the index number of the object, or a String value representing either the Name or CategoryID property value of an object in the collection.

Remarks

If the name of a category is specified in Index, this method removes the first Category object that matches the specified value.

See also

Concepts

Categories Object

Other resources

Categories Object Members


Category Object (Outlook)

 Copy code hover
[image]

Category Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a user-defined category by which Outlook items can be grouped.

Version Information

Version Added: Outlook 2007

Remarks

Microsoft Outlook provides a categorization system with which Outlook items can be easily identified and grouped into user-defined categories. The Category object represents a user-defined category.

Use the Add method of the Categories property for the NameSpace object to create a new Category object, adding the category to the Master Category List for that namespace.

Use the Name property to specify the name of the category, the Color property to specify the color displayed for that category, and the ShortcutKey property to specify the shortcut key used to assign that category to an Outlook item in the Outlook user interface. Use the CategoryID property to retrieve the unique identifer for a category.

Assigning Categories to Items

Categories can be assigned to Outlook items by specifying the names of the appropriate Category objects in a comma-delimited string in the Categories property of the following objects:

AppointmentItem | RemoteItem
ContactItem | ReportItem
DistListItem | SharingItem
DocumentItem | TaskItem
JournalItem | TaskRequestAcceptItem
MailItem | TaskRequestDeclineItem
MeetingItem | TaskRequestItem
NoteItem | TaskRequestUpdateItem
PostItem |

Example

The following Visual Basic for Applications (VBA) example displays a dialog box containing the names and identifiers for each Category object contained in the Categories collection associated with the default NameSpace object.

VBA Copy code Copy code
Private Sub ListCategoryIDs()

 Dim objNameSpace As NameSpace

 Dim objCategory As Category

 Dim strOutput As String

 ' Obtain a NameSpace object reference.

 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check if the Categories collection for the Namespace

 ' contains one or more Category objects.

 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection.

 For Each objCategory In objNameSpace.Categories

 ' Add the name and ID of the Category object to

 ' the output string.

 strOutput = strOutput & objCategory.Name & _

 ": " & objCategory.CategoryID & vbCrLf

 Next

 End If

 ' Display the output string.

 MsgBox strOutput

 ' Clean up.

 Set objCategory = Nothing

 Set objNameSpace = Nothing

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Category Object Members


Category Members (Outlook)

 Copy code hover
[image]

Category Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a user-defined category by which Outlook items can be grouped.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CategoryBorderColor | Returns an OLE_COLOR value that represents the border color of the color swatch displayed for a Category object. Read-only.
CategoryGradientBottomColor | Returns an OLE_COLOR value that represents the bottom gradient color of the color swatch displayed for a Category object. Read-only.
CategoryGradientTopColor | Returns an OLE_COLOR value that represents the top gradient color of the color swatch displayed for a Category object. Read-only.
CategoryID | Returns a String value that represents the unique identifier for the Category object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Color | Returns or sets an OlCategoryColor constant that indicates the color used by the Category object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShortcutKey | Returns or sets an OlCategoryShortcutKey constant that specifies the shortcut key used by the Category object. Read/write.


Category Properties (Outlook)

 Copy code hover
[image]

Category Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
CategoryBorderColor | Returns an OLE_COLOR value that represents the border color of the color swatch displayed for a Category object. Read-only.
CategoryGradientBottomColor | Returns an OLE_COLOR value that represents the bottom gradient color of the color swatch displayed for a Category object. Read-only.
CategoryGradientTopColor | Returns an OLE_COLOR value that represents the top gradient color of the color swatch displayed for a Category object. Read-only.
CategoryID | Returns a String value that represents the unique identifier for the Category object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Color | Returns or sets an OlCategoryColor constant that indicates the color used by the Category object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShortcutKey | Returns or sets an OlCategoryShortcutKey constant that specifies the shortcut key used by the Category object. Read/write.


Category.Application Property (Outlook)

 Copy code hover
[image]

Category.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.CategoryBorderColor Property (Outlook)

 Copy code hover
[image]

Category.CategoryBorderColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OLE_COLOR value that represents the border color of the color swatch displayed for a Category object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CategoryBorderColor

expression A variable that represents a Category object.

Remarks

Setting the Color property of the Category object to an OlCategoryColor constant changes the value of this property, as well as the value of the CategoryGradientBottomColor and CategoryGradientTopColor properties.

This color should be used to display the border of a gradient-shaded color swatch for the Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.CategoryGradientBottomColor Property (Outlook)

 Copy code hover
[image]

Category.CategoryGradientBottomColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OLE_COLOR value that represents the bottom gradient color of the color swatch displayed for a Category object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CategoryGradientBottomColor

expression A variable that represents a Category object.

Remarks

Setting the Color property of the Category object to an OlCategoryColor constant changes the value of this property, as well as the value of the CategoryGradientTopColor and CategoryBorderColor properties.

This color should be used to display a gradient-shaded color swatch for the Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.CategoryGradientTopColor Property (Outlook)

 Copy code hover
[image]

Category.CategoryGradientTopColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OLE_COLOR value that represents the top gradient color of the color swatch displayed for a Category object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CategoryGradientTopColor

expression A variable that represents a Category object.

Remarks

Setting the Color property of the Category object to an OlCategoryColor constant changes the value of this property, as well as the value of the CategoryGradientBottomColor and CategoryBorderColor properties.

This color should be used to display a gradient-shaded color swatch for the Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.CategoryID Property (Outlook)

 Copy code hover
[image]

Category.CategoryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the unique identifier for the Category object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CategoryID

expression A variable that represents a Category object.

Remarks

Because the Name property of a Category object can be changed either programmatically or by user action, each Category object is uniquely identified by a globally unique identifier (GUID), assigned to the object, that can be retrieved using this property. The GUID is presented as a string using the following format:

Copy code Copy code
{00000000-0000-0000-0000-000000000000}

Example

The following Visual Basic for Applications (VBA) example displays a dialog box containing the names and identifiers for each Category object contained in the Categories collection associated with the default NameSpace object.

Copy code Copy code
Private Sub ListCategoryIDs()

 Dim objNameSpace As NameSpace

 Dim objCategory As Category

 Dim strOutput As String

 ' Obtain a NameSpace object reference.

 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check if the Categories collection for the Namespace

 ' contains one or more Category objects.

 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection.

 For Each objCategory In objNameSpace.Categories

 ' Add the name and ID of the Category object to

 ' the output string.

 strOutput = strOutput & objCategory.Name & _

 ": " & objCategory.CategoryID & vbCrLf

 Next

 End If

 ' Display the output string.

 MsgBox strOutput

 ' Clean up.

 Set objCategory = Nothing

 Set objNameSpace = Nothing

End Sub

See also

Concepts

Category Object

Other resources

Category Object Members


Category.Class Property (Outlook)

 Copy code hover
[image]

Category.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.Color Property (Outlook)

 Copy code hover
[image]

Category.Color Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlCategoryColor constant that indicates the color used by the Category object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Color

expression A variable that represents a Category object.

Remarks

You can share the same color for multiple categories, by specifying the same constant that represents the category color in the OlCategoryColor enumeration for those Category objects.

Example

The following Visual Basic for Applications (VBA) example displays a dialog box containing color assignments for each Category object contained in the Categories collection associated with the default NameSpace object.

Copy code Copy code
Private Sub ListCategoryColors()
 Dim objNameSpace As NameSpace
 Dim objCategory As Category
 Dim strOutput As String

 ' Obtain a NameSpace object reference.
 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check if the Categories collection for the Namespace
 ' contains one or more Category objects.
 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection, checking
 ' the value of the Color property for
 ' each Category object.
 For Each objCategory In objNameSpace.Categories

 ' Add the name of the Category object to
 ' the output string.
 strOutput = strOutput & objCategory.Name

 ' Add information about the assigned color
 ' to the output string.
 Select Case objCategory.Color
 Case OlCategoryColor.olCategoryColorNone
 strOutput = strOutput & ": No color" & vbCrLf
 Case OlCategoryColor.olCategoryColorBlack
 strOutput = strOutput & ": Black " & vbCrLf
 Case OlCategoryColor.olCategoryColorBlue
 strOutput = strOutput & ": Blue" & vbCrLf
 Case OlCategoryColor.olCategoryColorGray
 strOutput = strOutput & ": Gray" & vbCrLf
 Case OlCategoryColor.olCategoryColorGreen
 strOutput = strOutput & ": Green" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightBlue
 strOutput = strOutput & ": Light blue" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightGray
 strOutput = strOutput & ": Light gray" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightGreen
 strOutput = strOutput & ": Light green" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightMaroon
 strOutput = strOutput & ": Light maroon" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightOlive
 strOutput = strOutput & ": Light olive" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightOrange
 strOutput = strOutput & ": Light orange" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightPeach
 strOutput = strOutput & ": Light peach" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightPurple
 strOutput = strOutput & ": Light purple" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightRed
 strOutput = strOutput & ": Light red" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightSteel
 strOutput = strOutput & ": Light steel" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightTeal
 strOutput = strOutput & ": Light teal" & vbCrLf
 Case OlCategoryColor.olCategoryColorLightYellow
 strOutput = strOutput & ": Light yellow" & vbCrLf
 Case OlCategoryColor.olCategoryColorMaroon
 strOutput = strOutput & ": Maroon" & vbCrLf
 Case OlCategoryColor.olCategoryColorOlive
 strOutput = strOutput & ": Olive" & vbCrLf
 Case OlCategoryColor.olCategoryColorOrange
 strOutput = strOutput & ": Orange" & vbCrLf
 Case OlCategoryColor.olCategoryColorPeach
 strOutput = strOutput & ": Peach" & vbCrLf
 Case OlCategoryColor.olCategoryColorPurple
 strOutput = strOutput & ": Purple" & vbCrLf
 Case OlCategoryColor.olCategoryColorRed
 strOutput = strOutput & ": Red" & vbCrLf
 Case OlCategoryColor.olCategoryColorSteel
 strOutput = strOutput & ": Steel" & vbCrLf
 Case OlCategoryColor.olCategoryColorTeal
 strOutput = strOutput & ": Teal" & vbCrLf
 Case OlCategoryColor.olCategoryColorYellow
 strOutput = strOutput & ": Yellow" & vbCrLf
 Case Else
 strOutput = strOutput & ": Unknown" & vbCrLf
 End Select
 Next
 End If

 ' Display the output string.
 MsgBox strOutput

 ' Clean up.
 Set objCategory = Nothing
 Set objNameSpace = Nothing

End Sub

See also

Concepts

Category Object

Other resources

Category Object Members


Category.Name Property (Outlook)

 Copy code hover
[image]

Category.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.Parent Property (Outlook)

 Copy code hover
[image]

Category.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Category object.

See also

Concepts

Category Object

Other resources

Category Object Members


Category.Session Property (Outlook)

 Copy code hover
[image]

Category.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Category object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Category Object

Other resources

Category Object Members


Category.ShortcutKey Property (Outlook)

 Copy code hover
[image]

Category.ShortcutKey Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlCategoryShortcutKey constant that specifies the shortcut key used by the Category object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShortcutKey

expression A variable that represents a Category object.

Remarks

Any OlCategoryShortcutKey constant other than olCategoryShortcutKeyNone can only be used by one Category object at any given time. Setting the value of this property to an OlCategoryShortcutKey constant already in use sets the ShortcutKey property of the Category object already using the specified value to olCategoryShortcutKeyNone.

Example

The following Visual Basic for Applications (VBA) example displays a dialog box containing shortcut key assignments for each Category object contained in the Categories collection associated with the default NameSpace object.

Copy code Copy code
Private Sub ListShortcutKeys()

 Dim objNameSpace As NameSpace

 Dim objCategory As Category

 Dim strOutput As String

 ' Obtain a NameSpace object reference.

 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check if the Categories collection for the Namespace

 ' contains one or more Category objects.

 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection, checking

 ' the value of the ShortcutKey property for

 ' each Category object.

 For Each objCategory In objNameSpace.Categories

 ' Add the name of the Category object to

 ' the output string.

 strOutput = strOutput & objCategory.Name

 ' Add information about the assigned shortcut key

 ' to the output string.

 Select Case objCategory.ShortcutKey

 Case OlCategoryShortcutKey.olCategoryShortcutKeyNone

 strOutput = strOutput & ": No shortcut key" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF2

 strOutput = strOutput & ": Ctrl+F2" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF3

 strOutput = strOutput & ": Ctrl+F3" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF4

 strOutput = strOutput & ": Ctrl+F4" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF5

 strOutput = strOutput & ": Ctrl+F5" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF6

 strOutput = strOutput & ": Ctrl+F6" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF7

 strOutput = strOutput & ": Ctrl+F7" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF8

 strOutput = strOutput & ": Ctrl+F8" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF9

 strOutput = strOutput & ": Ctrl+F9" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF10

 strOutput = strOutput & ": Ctrl+F10" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF11

 strOutput = strOutput & ": Ctrl+F11" & vbCrLf

 Case OlCategoryShortcutKey.olCategoryShortcutKeyCtrlF12

 strOutput = strOutput & ": Ctrl+F12" & vbCrLf

 Case Else

 strOutput = strOutput & ": Unknown" & vbCrLf

 End Select

 Next

 End If

 ' Display the output string.

 MsgBox strOutput

 ' Clean up.

 Set objCategory = Nothing

 Set objNameSpace = Nothing

End Sub

See also

Concepts

Category Object

Other resources

Category Object Members


CategoryRuleCondition Object (Outlook)

 Copy code hover
[image]

CategoryRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates categories on a message as compared with CategoryRuleCondition.Categories.

Version Information

Version Added: Outlook 2007

Remarks

CategoryRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has a RuleConditions.Category property. The Category property always returns a CategoryRuleCondition object. If the rule has any of these rule conditions enabled, then CategoryRuleCondition.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition Members (Outlook)

 Copy code hover
[image]

CategoryRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates categories on a message as compared with CategoryRuleCondition.Categories.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns or sets an array of String elements that represents the categories evaluated by the rule condition. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionCategory, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


CategoryRuleCondition Properties (Outlook)

 Copy code hover
[image]

CategoryRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns or sets an array of String elements that represents the categories evaluated by the rule condition. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionCategory, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


CategoryRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a CategoryRuleCondition object.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.Categories Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Categories Property (Outlook)
See also Send feedback

Returns or sets an array of String elements that represents the categories evaluated by the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Categories

expression A variable that represents a CategoryRuleCondition object.

Remarks

You can assign an array with one element to evaluate a single category or an array of multiple strings to evaluate multiple categories. Multiple category strings assigned in an array are evaluated using the logical OR operation.

This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories.

If a string specified by Categories matches a category of the message, the condition evaluates to True.

Outlook does not check to determine if the Categories property contains category names that are in the master category list.

Returns an error if Categories contains one or more empty strings.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a CategoryRuleCondition object.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olConditionCategory, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a CategoryRuleCondition object.

Remarks

The category rule condition is supported by rules for receiving messages and rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a CategoryRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it has been saved successfully.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a CategoryRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


CategoryRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

CategoryRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a CategoryRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

CategoryRuleCondition Object

Other resources

CategoryRuleCondition Object Members


Column Object (Outlook)

 Copy code hover
[image]

Column Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a column of data in a Table object.

Version Information

Version Added: Outlook 2007

Remarks

A Table is composed of rows and columns. It represents a read-only dynamic rowset of data in a Folder or Search object. You can regard each row of a Table as an item in the folder, each column as a property of the item. By default, a Table contains only a subset of properties for items in the folder. This makes the Table an in-memory lightweight rowset that allows fast enumeration and filtering of items in the folder.

To obtain the value of a property (column) for a specific item (row) in a Table, you can either use the Table.GetArray method and index into the returned array, or use the Row.Item method, specifying the Name of the column.

See also

Concepts

Outlook Object Model Reference

Other resources

Column Object Members


Column Members (Outlook)

 Copy code hover
[image]

Column Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a column of data in a Table object.

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Column object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Column object. Read-only.
Name | Returns a String value that represents the name of the Column. Read-only.
Parent | Returns the parent object of the Column object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Column Properties (Outlook)

 Copy code hover
[image]

Column Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Column object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Column object. Read-only.
Name | Returns a String value that represents the name of the Column. Read-only.
Parent | Returns the parent object of the Column object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Column.Application Property (Outlook)

 Copy code hover
[image]

Column.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent application (Outlook) for the Column object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Column object.

See also

Concepts

Column Object

Other resources

Column Object Members


Column.Class Property (Outlook)

 Copy code hover
[image]

Column.Class Property (Outlook)
See also Send feedback

Returns a constant in the OlObjectClass enumeration indicating the class of the Column object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Column object.

See also

Concepts

Column Object

Other resources

Column Object Members


Column.Name Property (Outlook)

 Copy code hover
[image]

Column.Name Property (Outlook)
See also Send feedback

Returns a String value that represents the name of the Column. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a Column object.

Remarks

The Name property is the default member of the Column object.

If the Column is a default column in the Table, or if it has been added to the Table with the explicit built-in name for the property, the value of Name is the explicit built-in name (without any enclosing brackets) for the property. If the Column has been added to the Table with a property name referencing a namespace, the value of Name will be the property name referenced by namespace. For more information on referencing properties by namespace, see Referencing Properties by Namespace.

See also

Concepts

Column Object

Other resources

Column Object Members


Column.Parent Property (Outlook)

 Copy code hover
[image]

Column.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent object of the Column object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Column object.

See also

Concepts

Column Object

Other resources

Column Object Members


Column.Session Property (Outlook)

 Copy code hover
[image]

Column.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Column object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Column Object

Other resources

Column Object Members


ColumnFormat Object (Outlook)

 Copy code hover
[image]

ColumnFormat Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the display properties of an order field or view field in a view.

Version Information

Version Added: Outlook 2007

Remarks

The ColumnFormat object represents the display properties, such as the alignment or field type, of an OrderField or ViewField object. Use the ColumnFormat property of the ViewField object to access the display properties of a view field.

Use the Label property to obtain or change the text used to label the field, or the Align property to determine the alignment of the contents within the field.

Use the FieldType property to determine the type and form of the data displayed for that field, and the FieldFormat property to determine how to format the data for that field.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

VBA Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ColumnFormat Object Members


ColumnFormat Members (Outlook)

 Copy code hover
[image]

ColumnFormat Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the display properties of an order field or view field in a view.

Properties

Name | Description
Align | Returns or sets an OlAlign constant that indicates the alignment of the column label for the property to which the ColumnFormat object is associated. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
FieldFormat | Returns or sets a Long value that represents the display format of the property to which the ColumnFormat object is associated. Read/write.
FieldType | Returns an OlUserPropertyType constant which represents the field type of the property to which the ColumnFormat object is associated. Read-only.
Label | Returns or sets a String value that represents the column label and tooltip displayed for the property to which the ColumnFormat object is associated. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Width | Returns or sets a Long value indicating the approximate width (in characters) of the column. Read/write.


ColumnFormat Properties (Outlook)

 Copy code hover
[image]

ColumnFormat Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Align | Returns or sets an OlAlign constant that indicates the alignment of the column label for the property to which the ColumnFormat object is associated. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
FieldFormat | Returns or sets a Long value that represents the display format of the property to which the ColumnFormat object is associated. Read/write.
FieldType | Returns an OlUserPropertyType constant which represents the field type of the property to which the ColumnFormat object is associated. Read-only.
Label | Returns or sets a String value that represents the column label and tooltip displayed for the property to which the ColumnFormat object is associated. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Width | Returns or sets a Long value indicating the approximate width (in characters) of the column. Read/write.


ColumnFormat.Align Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Align Property (Outlook)
See also Send feedback

Returns or sets an OlAlign constant that indicates the alignment of the column label for the property to which the ColumnFormat object is associated. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Align

expression A variable that represents a ColumnFormat object.

Remarks

The value of this property is ignored for properties in which the column label is displayed as an icon.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Application Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ColumnFormat object.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Class Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ColumnFormat object.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.FieldFormat Property (Outlook)

 Copy code hover
[image]

ColumnFormat.FieldFormat Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the display format of the property to which the ColumnFormat object is associated. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FieldFormat

expression A variable that represents a ColumnFormat object.

Remarks

The value of this property is a constant from an enumeration, where the enumeration is dependent on the value of the FieldType property for the ColumnFormat object:

FieldType value | FieldFormat enumeration
olCurrency | OlFormatCurrency
olFormatDateTime | OlFormatDateTime
olDuration | OlFormatDuration
olInteger | OlFormatInteger
olKeywords | OlFormatKeywords
olNumber | OlFormatNumber
olPercent | OlFormatPercent
olText | OlFormatText
olYesNo | OlFormatYesNo
olEnumeration | OlFormatEnumeration
olSmartFrom | OlFormatSmartFrom

For field types not listed in the above table, the value of this property is ignored.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.FieldType Property (Outlook)

 Copy code hover
[image]

ColumnFormat.FieldType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlUserPropertyType constant which represents the field type of the property to which the ColumnFormat object is associated. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FieldType

expression A variable that represents a ColumnFormat object.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Label Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Label Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the column label and tooltip displayed for the property to which the ColumnFormat object is associated. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Label

expression A variable that represents a ColumnFormat object.

Remarks

For built-in Outlook properties, the default value for this property is the localized name of the property. For custom Outlook properties, the default value for this property is the name of the property.

The value of this property applies only to the tooltip for Outlook properties in which the column header is represented as an icon.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Parent Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ColumnFormat object.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Session Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ColumnFormat object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


ColumnFormat.Width Property (Outlook)

 Copy code hover
[image]

ColumnFormat.Width Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value indicating the approximate width (in characters) of the column. Read/write.

Syntax

expression .Width

expression A variable that represents a ColumnFormat object.

Remarks

This property can be set to a value between 2 and 1024. If this property is set to a value less than 2, the property is set to 2. If this property is set to a value greater than 1024, the property is set to 1024.

If the value of this property for every column in a view is less than the total width of the view, then the Width property of the ColumnFormat object for the last ViewField in the view is increased to match the total width of the view.

See also

Concepts

ColumnFormat Object

Other resources

ColumnFormat Object Members


Columns Object (Outlook)

 Copy code hover
[image]

Columns Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the collection of Column objects in a Table object.

Version Information

Version Added: Outlook 2007

Remarks

The Columns object supports enumerating Column objects in the Columns collection object. It supports the COM interface, IEnumerable .

Example

The following code sample illustrates how to obtain a Table object based on the LastModificationTime of items in the Inbox. It also shows how to remove the default columns of the Table, add specific columns, and print the values of the corresponding properties of these items.

Copy code Copy code
Sub RemoveAllAndAddColumns()

 'Declarations

 Dim Filter As String

 Dim oRow As Outlook.Row

 Dim oTable As Outlook.Table

 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox

 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005

 Filter = "[LastModificationTime] > '5/1/2005'"

 'Restrict with Filter

 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set

 oTable.Columns.RemoveAll

 'Specify desired properties

 With oTable.Columns

 .Add ("Subject")

 .Add ("LastModificationTime")

 'PR_ATTR_HIDDEN referenced by the MAPI proptag namespace

 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")

 End With

 'Enumerate the table using test for EndOfTable

 Do Until (oTable.EndOfTable)

 Set oRow = oTable.GetNextRow()

 Debug.Print (oRow("Subject"))

 Debug.Print (oRow("LastModificationTime"))

 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))

 Loop

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Columns Object Members


Columns Members (Outlook)

 Copy code hover
[image]

Columns Members (Outlook)
Send feedback

Represents the collection of Column objects in a Table object.

Methods

Name | Description
Add | Adds the Column specified by Name to the Columns collection and resets the Table.
Item | Obtains a Column object specified by Index.
Remove | Removes the Column object specified by Index and resets the Table.
RemoveAll | Removes all the columns from the Columns collection and resets the Table.

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Columns object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Columns object. Read-only.
Count | Returns a Long representing the number of Column objects in the collection. Read-only.
Parent | Returns the parent object of the Columns object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Columns Properties (Outlook)

 Copy code hover
[image]

Columns Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Columns object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Columns object. Read-only.
Count | Returns a Long representing the number of Column objects in the collection. Read-only.
Parent | Returns the parent object of the Columns object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Columns.Application Property (Outlook)

 Copy code hover
[image]

Columns.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent application (Outlook) for the Columns object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Columns object.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Class Property (Outlook)

 Copy code hover
[image]

Columns.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlObjectClass enumeration indicating the class of the Columns object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Columns object.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Count Property (Outlook)

 Copy code hover
[image]

Columns.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the number of Column objects in the collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a Columns object.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Parent Property (Outlook)

 Copy code hover
[image]

Columns.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent object of the Columns object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Columns object.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Session Property (Outlook)

 Copy code hover
[image]

Columns.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Columns object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns Methods (Outlook)

 Copy code hover
[image]

Columns Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds the Column specified by Name to the Columns collection and resets the Table.
Item | Obtains a Column object specified by Index.
Remove | Removes the Column object specified by Index and resets the Table.
RemoveAll | Removes all the columns from the Columns collection and resets the Table.


Columns.Add Method (Outlook)

 Copy code hover
[image]

Columns.Add Method (Outlook)
See also Send feedback

Adds the Column specified by Name to the Columns collection and resets the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(Name)

expression A variable that represents a Columns object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that is being added as a column.

Return Value

A Column object that represents the new column.

Remarks

Columns.Add adds the specified Column to the end of the Columns collection for the Table, and resets the Table by moving the current row to just before the first row of the Table. If Columns.Add returns an error, it will not change the current row.

Name can be an explicit built-in property name, or a property name referenced by namespace. It must be referenced as the name in the English locale. For more information on referencing properties by namespace, see Referencing Properties by Namespace.

If you are adding a property which is an explicit built-in property in the object model, for example, Contact.FirstName, you must specify Name as the explicit built-in property name in English. For certain types of properties, the format used when adding these properties as columns affects how their values are expressed in the Table. For more information on property value representation in a Table, see Factors Affecting Property Value Representation in the Table and View Classes.

If you are adding a custom property to a Table, referencing the property by the MAPI string namespace, you will have to explicitly append the type of the property to the end of the property reference. For example, to add the custom property MyCustomProperty, which has the type Unicode string, you will have to explicitly append the type 001f to the reference, resulting in: http://schemas.microsoft.com/mapi/string/{HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH}/MyCustomProperty/0x0000001f, where {HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH} represents the namespace GUID.

Certain properties cannot be added to a Table using Columns.Add, including binary properties, computed properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter.

While Items.SetColumns can be used to facilitate caching certain properties for extremely fast access to those properties of an Items collection, some properties are restricted from SetColumns. Since these restrictions do not apply to Columns.Add, the Table object is a less restrictive alternative than Items.

Example

The following code sample illustrates how to obtain a Table object based on the LastModificationTime of items in the Inbox. It also shows how to remove the default columns of the Table, add specific columns, and print the values of the corresponding properties of these items.

VBA Copy code Copy code
Sub AddColumns()

 'Declarations

 Dim Filter As String

 Dim oRow As Outlook.Row

 Dim oTable As Outlook.Table

 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox

 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005

 Filter = "[LastModificationTime] > '5/1/2005'"

 'Restrict with Filter

 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set

 oTable.Columns.RemoveAll

 'Specify desired properties

 With oTable.Columns

 .Add ("Subject")

 .Add ("LastModificationTime")

 'PR_ATTR_HIDDEN referenced by the MAPI proptag namespace

 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")

 End With

 'Enumerate the table using test for EndOfTable

 Do Until (oTable.EndOfTable)

 Set oRow = oTable.GetNextRow()

 Debug.Print (oRow("Subject"))

 Debug.Print (oRow("LastModificationTime"))

 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))

 Loop

End Sub

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Item Method (Outlook)

 Copy code hover
[image]

Columns.Item Method (Outlook)
See also Send feedback

Obtains a Column object specified by Index.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a Columns object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Return Value

A Column object that represents the column matching the Index in the Table. Returns the error, "Array index out of bounds" if Index is an invalid Long integer. Returns Null (Nothing in Visual Basic) if Index is a String representing a column name that cannot be found in the Table.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.Remove Method (Outlook)

 Copy code hover
[image]

Columns.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the Column object specified by Index and resets the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents a Columns object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Remarks

The Remove method resets the Table by moving the current row to just before the first row of the Table. If, however, an invalid Index has been specified, then it will not remove any column or reset the Table.

Returns an error message if an invalid Index has been specified.

See also

Concepts

Columns Object

Other resources

Columns Object Members


Columns.RemoveAll Method (Outlook)

 Copy code hover
[image]

Columns.RemoveAll Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes all the columns from the Columns collection and resets the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoveAll

expression A variable that represents a Columns object.

Remarks

RemoveAll resets the Table by moving the current row to just before the first row of the Table. After a call to RemoveAll, Columns.Count becomes zero (0).

Example

The following code sample illustrates how to obtain a Table object based on the LastModificationTime of items in the Inbox. It also shows how to remove the default columns of the Table, add specific columns, and print the values of the corresponding properties of these items.

Copy code Copy code
Sub RemoveAllAndAddColumns()

 'Declarations

 Dim Filter As String

 Dim oRow As Outlook.Row

 Dim oTable As Outlook.Table

 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox

 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005

 Filter = "[LastModificationTime] > '5/1/2005'"

 'Restrict with Filter

 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set

 oTable.Columns.RemoveAll

 'Specify desired properties

 With oTable.Columns

 .Add ("Subject")

 .Add ("LastModificationTime")

 'PR_ATTR_HIDDEN referenced by the MAPI proptag namespace

 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")

 End With

 'Enumerate the table using test for EndOfTable

 Do Until (oTable.EndOfTable)

 Set oRow = oTable.GetNextRow()

 Debug.Print (oRow("Subject"))

 Debug.Print (oRow("LastModificationTime"))

 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))

 Loop

End Sub

See also

Concepts

Columns Object

Other resources

Columns Object Members


Conflict Object (Outlook)

 Copy code hover
[image]

Conflict Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an Outlook item that is in conflict with another Outlook item.

Remarks

Each Outlook item has a Conflicts collection object associated with it that represents all the items that are in conflict with that item.

Use the Item method to retrieve a particular Conflict object from the Conflicts collection object, for example:

Example

The following Visual Basic for Applications (VBA) example retrieves a Conflict object from the Conflicts collection object.

Copy code Copy code
Set myConflictItem = myConflicts.Item(1)

See also

Concepts

Outlook Object Model Reference

Other resources

Conflict Object Members


Conflict Members (Outlook)

 Copy code hover
[image]

Conflict Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an Outlook item that is in conflict with another Outlook item.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Item | Returns an Object corresponding to the specified Outlook item. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlObjectClass constant indicating the type of item represented by the Conflict object. Read-only.


Conflict Properties (Outlook)

 Copy code hover
[image]

Conflict Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Item | Returns an Object corresponding to the specified Outlook item. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlObjectClass constant indicating the type of item represented by the Conflict object. Read-only.


Conflict.Application Property (Outlook)

 Copy code hover
[image]

Conflict.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Class Property (Outlook)

 Copy code hover
[image]

Conflict.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Item Property (Outlook)

 Copy code hover
[image]

Conflict.Item Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object corresponding to the specified Outlook item. Read-only.

Syntax

expression .Item

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Name Property (Outlook)

 Copy code hover
[image]

Conflict.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Parent Property (Outlook)

 Copy code hover
[image]

Conflict.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Session Property (Outlook)

 Copy code hover
[image]

Conflict.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Conflict object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflict.Type Property (Outlook)

 Copy code hover
[image]

Conflict.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the type of item represented by the Conflict object. Read-only.

Syntax

expression .Type

expression A variable that represents a Conflict object.

See also

Concepts

Conflict Object

Other resources

Conflict Object Members


Conflicts Object (Outlook)

 Copy code hover
[image]

Conflicts Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of Conflict objects that represent all Microsoft Outlook items that are in conflict with a particular Outlook item.

Remarks

Use the Conflictsproperty of any Outlook item, such as MailItem, to return the Conflicts object.

Use the Count property of the Conflicts object to determine if the item is invloved in a conflict. A non-zero value indicates conflict.

Use the Item method to retrieve a particular conflict item from the Conflicts collection object.

Use the GetFirst, GetNext, GetPrevious, and GetLast methods to traverse the Conflicts collection.

Example

The following Microsoft Visual Basic for Applications (VBA) example uses the Count property of the Conflicts object to determine if the item is involved in any conflict. To run this example, make sure an e-mail item is open in the active window.

VBA Copy code Copy code
Sub CheckConflicts()

 Dim myItem As Outlook.MailItem

 Dim myConflicts As Outlook.Conflicts

 Set myItem = Application.ActiveInspector.CurrentItem

 Set myConflicts = myItem.Conflicts

 If (myConflicts.Count > 0) Then

 MsgBox ("This item is involved in a conflict.")

 Else

 MsgBox ("This item is not involved in any conflicts.")

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Conflicts Object Members


Conflicts Members (Outlook)

 Copy code hover
[image]

Conflicts Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of Conflict objects that represent all Microsoft Outlook items that are in conflict with a particular Outlook item.

Methods

Name | Description
GetFirst | Returns the first object in the Conflicts collection.
GetLast | Returns the last object in the Conflicts collection.
GetNext | Returns the next object in the Conflicts collection.
GetPrevious | Returns the previous object in the Conflicts collection.
Item | Returns an Conflict object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Conflicts Properties (Outlook)

 Copy code hover
[image]

Conflicts Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Conflicts.Application Property (Outlook)

 Copy code hover
[image]

Conflicts.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Conflicts object.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.Class Property (Outlook)

 Copy code hover
[image]

Conflicts.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Conflicts object.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.Count Property (Outlook)

 Copy code hover
[image]

Conflicts.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Conflicts object.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.Parent Property (Outlook)

 Copy code hover
[image]

Conflicts.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Conflicts object.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.Session Property (Outlook)

 Copy code hover
[image]

Conflicts.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Conflicts object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts Methods (Outlook)

 Copy code hover
[image]

Conflicts Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetFirst | Returns the first object in the Conflicts collection.
GetLast | Returns the last object in the Conflicts collection.
GetNext | Returns the next object in the Conflicts collection.
GetPrevious | Returns the previous object in the Conflicts collection.
Item | Returns an Conflict object from the collection.


Conflicts.GetFirst Method (Outlook)

 Copy code hover
[image]

Conflicts.GetFirst Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the first object in the Conflicts collection.

Syntax

expression .GetFirst

expression A variable that represents a Conflicts object.

Return Value

A Conflict object that represents the first object contained by the collection.

Remarks

Returns Nothing if no first object exists, for example, if there are no objects in the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.GetLast Method (Outlook)

 Copy code hover
[image]

Conflicts.GetLast Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the last object in the Conflicts collection.

Syntax

expression .GetLast

expression A variable that represents a Conflicts object.

Return Value

A Conflict object that represents the last object contained by the collection.

Remarks

It returns Nothing if no last object exists, for example, if the collection is empty. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.GetNext Method (Outlook)

 Copy code hover
[image]

Conflicts.GetNext Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the next object in the Conflicts collection.

Syntax

expression .GetNext

expression A variable that represents a Conflicts object.

Return Value

A Conflict object that represents the next object contained by the collection.

Remarks

It returns Nothing if no next object exists, for example, if already positioned at the end of the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.GetPrevious Method (Outlook)

 Copy code hover
[image]

Conflicts.GetPrevious Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the previous object in the Conflicts collection.

Syntax

expression .GetPrevious

expression A variable that represents a Conflicts object.

Return Value

A Conflict object that represents the previous object contained by the collection.

Remarks

It returns Nothing if no previous object exists, for example, if already positioned at the beginning of the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


Conflicts.Item Method (Outlook)

 Copy code hover
[image]

Conflicts.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Conflict object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a Conflicts object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A Conflict object that represents the specified object.

See also

Concepts

Conflicts Object

Other resources

Conflicts Object Members


ContactItem Object (Outlook)

 Copy code hover
[image]

ContactItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a contact in a Contacts folder.

Remarks

A contact can represent any person with whom you have any personal or professional contact.

Use the CreateItem method to create a ContactItem object that represents a new contact.

Use Items (index), where index is the index number of a contact or a value used to match the default property of a contact, to return a single ContactItem object from a Contacts folder.

Example

The following Visual Basic for Applications (VBA) example returns a new contact.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olContactItem)

See also

Concepts

Outlook Object Model Reference

Other resources

ContactItem Object Members


ContactItem Members (Outlook)

 Copy code hover
[image]

ContactItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a contact in a Contacts folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
AddBusinessCardLogoPicture | Adds a logo picture to the current Electronic Business Card of the contact item.
AddPicture | Adds a picture to a contact item.
ClearTaskFlag | Clears the ContactItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
ForwardAsBusinessCard | Creates a new MailItem object containing contact information and, optionally, an Electronic Business Card (EBC) image based on the specified ContactItem object.
ForwardAsVcard | Creates a MailItem and attaches the contact information in vCard format.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a ContactItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
RemovePicture | Removes a picture from a Contacts item.
ResetBusinessCard | Resets the Electronic Business Card on the contact item to the default business card, deleting any custom layout and logo on the Electronic Business Card.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
SaveBusinessCardImage | Saves an image of the business card generated from the specified ContactItem object.
ShowBusinessCardEditor | Displays the electronic business card (EBC) editor dialog box for the ContactItem object.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
ShowCheckAddressDialog | Displays the Check Address dialog box to verify address details of the contact.
ShowCheckFullNameDialog | Displays the Check Full Name dialog box to verify name details of the contact.
ShowCheckPhoneDialog | Displays the Check Phone Number dialog box for a specified telephone number contained by a ContactItem object.

Properties

Name | Description
Account | Returns or sets a String representing the account for the contact. Read/write.
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Anniversary | Returns or sets a Date indicating the anniversary date for the contact. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AssistantName | Returns or sets a String representing the name of the person who is the assistant for the contact. Read/write.
AssistantTelephoneNumber | Returns or sets a String representing the telephone number of the person who is the assistant for the contact. Read/write.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Birthday | Returns or sets a Date indicating the birthday for the contact. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Business2TelephoneNumber | Returns or sets a String representing the second business telephone number for the contact. Read/write.
BusinessAddress | Returns or sets a String representing the whole, unparsed business address for the contact. Read/write.
BusinessAddressCity | Returns or sets a String representing the city name portion of the business address for the contact. Read/write.
BusinessAddressCountry | Returns or sets a String representing the country/region code portion of the business address for the contact. Read/write.
BusinessAddressPostalCode | Returns or sets a String representing the postal code (zip code) portion of the business address for the contact. Read/write.
BusinessAddressPostOfficeBox | Returns or sets a String representing the post office box number portion of the business address for the contact. Read/write.
BusinessAddressState | Returns or sets a String representing the state code portion of the business address for the contact. Read/write.
BusinessAddressStreet | Returns or sets a String representing the street address portion of the business address for the contact. Read/write.
BusinessCardLayoutXml | Returns or sets a String that represents the XML markup for the layout of the Electronic Business Card. Read/write.
BusinessCardType | Returns an OlBusinessCardType constant that specifies the type of Electronic Business Card used by this contact. Read-only.
BusinessFaxNumber | Returns or sets a String representing the business fax number for the contact. Read/write.
BusinessHomePage | Returns or sets a String representing the URL of the business Web page for the contact. Read/write.
BusinessTelephoneNumber | Returns or sets a String representing the first business telephone number for the contact. Read/write.
CallbackTelephoneNumber | Returns or sets a String representing the callback telephone number for the contact. Read/write.
CarTelephoneNumber | Returns or sets a String representing the car telephone number for the contact. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Children | Returns or sets a String representing the names of the children of the contact. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
CompanyAndFullName | Returns a String representing the concatenated company name and full name for the contact. Read-only.
CompanyLastFirstNoSpace | Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with no space between the last and first names. Read-only.
CompanyLastFirstSpaceOnly | Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with spaces between the last, first, and middle names. Read-only.
CompanyMainTelephoneNumber | Returns or sets a String representing the company main telephone number for the contact. Read/write.
CompanyName | Returns or sets a String representing the company name for the contact. Read/write.
ComputerNetworkName | Returns or sets a String representing the name of the computer network for the contact. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the ContactItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
CustomerID | Returns or sets a String representing the customer ID for the contact. Read/write.
Department | Returns or sets a String representing the department name for the contact. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Email1Address | Returns or sets a String representing the e-mail address of the first e-mail entry for the contact. Read/write.
Email1AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the first e-mail entry for the contact. Read/write.
Email1DisplayName | Returns a String representing the display name of the first e-mail address for the contact. Read/write.
Email1EntryID | Returns a String representing the entry ID of the first e-mail address for the contact. Read-only.
Email2Address | Returns or sets a String representing the e-mail address of the second e-mail entry for the contact. Read/write.
Email2AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the second e-mail entry for the contact. Read/write.
Email2DisplayName | Returns a String representing the display name of the second e-mail entry for the contact. Read/write.
Email2EntryID | Returns a String representing the entry ID of the second e-mail entry for the contact. Read-only.
Email3Address | Returns or sets a String representing the e-mail address of the third e-mail entry for the contact. Read/write.
Email3AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the third e-mail entry for the contact. Read/write.
Email3DisplayName | Returns a String representing the display name of the third e-mail entry for the contact. Read/write.
Email3EntryID | Returns a String representing the entry ID of the third e-mail entry for the contact. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FileAs | Returns or sets a String indicating the default keyword string assigned to the contact when it is filed. Read/write.
FirstName | Returns or sets a String representing the first name for the contact. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
FTPSite | Returns or sets a String representing the FTP site entry for the contact. Read/write.
FullName | Returns or sets a String specifying the whole, unparsed full name for the contact. Read/write.
FullNameAndCompany | Returns a String representing the full name and company of the contact by concatenating the values of the FullName and CompanyName properties. Read-only.
Gender | Returns or sets an OlGender constant indicating the gender of the contact. Read/write.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
GovernmentIDNumber | Returns or sets a String representing the government ID number for the contact. Read/write.
HasPicture | Returns a Boolean value that is True if a Contacts item has a picture associated with it. Read-only
Hobby | Returns or sets a String representing the hobby for the contact. Read/write.
Home2TelephoneNumber | Returns or sets a String representing the second home telephone number for the contact. Read/write.
HomeAddress | Returns or sets a String representing the full, unparsed text of the home address for the contact. Read/write.
HomeAddressCity | Returns or sets a String representing the city portion of the home address for the contact. Read/write.
HomeAddressCountry | Returns or sets a String representing the country/region portion of the home address for the contact. Read/write.
HomeAddressPostalCode | Returns or sets a String representing the postal code portion of the home address for the contact. Read/write.
HomeAddressPostOfficeBox | Returns or sets a String the post office box number portion of the home address for the contact. Read/write.
HomeAddressState | Returns or sets a String representing the state portion of the home address for the contact. Read/write.
HomeAddressStreet | Returns or sets a String representing the street portion of the home address for the contact. Read/write.
HomeFaxNumber | Returns or sets a String representing the home fax number for the contact. Read/write.
HomeTelephoneNumber | Returns or sets a String representing the first home telephone number for the contact. Read/write.
IMAddress | Returns or sets a String that represents a contact's Microsoft Instant Messenger address. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
Initials | Returns or sets a String representing the initials for the contact. Read/write.
InternetFreeBusyAddress | Returns or sets a String corresponding to the Address box on the Details tab for a contact. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ISDNNumber | Returns or sets a String representing the ISDN number for the contact. Read/write.
IsMarkedAsTask | Returns a Boolean value that indicates whether the ContactItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
JobTitle | Returns or sets a String representing the job title for the contact. Read/write.
Journal | Returns a Boolean that indicates True if the transaction of the contact will be journalized. Read/write.
Language | Returns or sets a String that represents the language in which the contact writes messages. Read/write.
LastFirstAndSuffix | Returns a String representing the last name, first name, middle name, and suffix of the contact. Read-only.
LastFirstNoSpace | Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.
LastFirstNoSpaceAndSuffix | Returns a String that contains the last name, first name, and suffix of the user without a space. Read-only
LastFirstNoSpaceCompany | Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.
LastFirstSpaceOnly | Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.
LastFirstSpaceOnlyCompany | Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
LastName | Returns or sets a String representing the last name for the contact. Read/write.
LastNameAndFirstName | Returns a String representing the concatenated last name and first name for the contact. Read-only.
MailingAddress | Returns or sets a String representing the full, unparsed selected mailing address for the contact. Read/write.
MailingAddressCity | Returns or sets a String representing the city name portion of the selected mailing address of the contact. Read/write.
MailingAddressCountry | Returns or sets a String representing the country/region code portion of the selected mailing address of the contact. Read/write.
MailingAddressPostalCode | Returns or sets a String representing the postal code (zip code) portion of the selected mailing address of the contact. Read/write.
MailingAddressPostOfficeBox | Returns or sets a String representing the post office box number portion of the selected mailing address of the contact. Read/write.
MailingAddressState | Returns or sets a String representing the state code portion for the selected mailing address of the contact. Read/write.
MailingAddressStreet | Returns or sets a String representing the street address portion of the selected mailing address of the contact. Read/write.
ManagerName | Returns or sets a String representing the manager name for the contact. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
MiddleName | Returns or sets a String representing the middle name for the contact. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
MobileTelephoneNumber | Returns or sets a String representing the mobile telephone number for the contact. Read/write.
NetMeetingAlias | Returns or sets a String indicating the user's Microsoft NetMeeting ID, or alias. Read/write.
NetMeetingServer | Returns or sets a String specifying the name of the Microsoft NetMeeting server being used for an online meeting. Read/write.
NickName | Returns or sets a String representing the nickname for the contact. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OfficeLocation | Returns or sets a String specifying the specific office location (for example, Building 1 Room 1 or Suite 123) for the contact. Read/write.
OrganizationalIDNumber | Returns or sets a String representing the organizational ID number for the contact. Read/write.
OtherAddress | Returns or sets a String representing the other address for the contact. Read/write.
OtherAddressCity | Returns or sets a String representing the city portion of the other address for the contact. Read/write.
OtherAddressCountry | Returns or sets a String representing the country/region portion of the other address for the contact. Read/write.
OtherAddressPostalCode | Returns or sets a String representing the postal code portion of the other address for the contact. Read/write.
OtherAddressPostOfficeBox | Returns or sets a String representing the post office box portion of the other address for the contact. Read/write.
OtherAddressState | Returns or sets a String representing the state portion of the other address for the contact. Read/write.
OtherAddressStreet | Returns or sets a String representing the street portion of the other address for the contact. Read/write.
OtherFaxNumber | Returns or sets a String representing the other fax number for the contact. Read/write.
OtherTelephoneNumber | Returns or sets a String representing the other telephone number for the contact. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
PagerNumber | Returns or sets a String representing the pager number for the contact. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PersonalHomePage | Returns or sets a String representing the URL of the personal Web page for the contact. Read/write.
PrimaryTelephoneNumber | Returns or sets a String specifying the primary telephone number for the contact. Read/write.
Profession | Returns or sets a String indicating the profession for the contact. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ContactItem object. Read-only.
RadioTelephoneNumber | Returns or sets a String indicating the radio telephone number for the contact. Read/write.
ReferredBy | Returns or sets a String specifying the referral name entry for the contact. Read/write.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SelectedMailingAddress | Returns or sets an OlMailingAddress constant indicating the type of the mailing address for the contact. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Spouse | Returns or sets a String indicating the spouse/partner name entry for the contact. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Suffix | Returns or sets a String indicating the name suffix (such as Jr., III, or Ph.D.) for the specified contact. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this ContactItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this ContactItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this ContactItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the ContactItem object. Read/write.
TelexNumber | Returns or sets a String indicating the telex number for the contact. Read/write.
Title | Returns or sets a String indicating the title for the contact. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the ContactItem. Read/write.
TTYTDDTelephoneNumber | Returns or sets a String specifying the TTY/TDD telephone number for the contact. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
User1 | Returns or sets a String specifying the first field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User2 | Returns or sets a String specifying the second field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User3 | Returns or sets a String specifying the third field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User4 | Returns or sets a String specifying the fourth field on the Contacts form intended for miscellaneous use for the contact. Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.
WebPage | Returns or sets a String indicating the URL of the Web page for the contact. Read/write.
YomiCompanyName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the company name for the contact. Read/write.
YomiFirstName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the first name for the contact. Read/write.
YomiLastName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the last name for the contact. Read/write.


ContactItem Properties (Outlook)

 Copy code hover
[image]

ContactItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Account | Returns or sets a String representing the account for the contact. Read/write.
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Anniversary | Returns or sets a Date indicating the anniversary date for the contact. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AssistantName | Returns or sets a String representing the name of the person who is the assistant for the contact. Read/write.
AssistantTelephoneNumber | Returns or sets a String representing the telephone number of the person who is the assistant for the contact. Read/write.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Birthday | Returns or sets a Date indicating the birthday for the contact. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Business2TelephoneNumber | Returns or sets a String representing the second business telephone number for the contact. Read/write.
BusinessAddress | Returns or sets a String representing the whole, unparsed business address for the contact. Read/write.
BusinessAddressCity | Returns or sets a String representing the city name portion of the business address for the contact. Read/write.
BusinessAddressCountry | Returns or sets a String representing the country/region code portion of the business address for the contact. Read/write.
BusinessAddressPostalCode | Returns or sets a String representing the postal code (zip code) portion of the business address for the contact. Read/write.
BusinessAddressPostOfficeBox | Returns or sets a String representing the post office box number portion of the business address for the contact. Read/write.
BusinessAddressState | Returns or sets a String representing the state code portion of the business address for the contact. Read/write.
BusinessAddressStreet | Returns or sets a String representing the street address portion of the business address for the contact. Read/write.
BusinessCardLayoutXml | Returns or sets a String that represents the XML markup for the layout of the Electronic Business Card. Read/write.
BusinessCardType | Returns an OlBusinessCardType constant that specifies the type of Electronic Business Card used by this contact. Read-only.
BusinessFaxNumber | Returns or sets a String representing the business fax number for the contact. Read/write.
BusinessHomePage | Returns or sets a String representing the URL of the business Web page for the contact. Read/write.
BusinessTelephoneNumber | Returns or sets a String representing the first business telephone number for the contact. Read/write.
CallbackTelephoneNumber | Returns or sets a String representing the callback telephone number for the contact. Read/write.
CarTelephoneNumber | Returns or sets a String representing the car telephone number for the contact. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Children | Returns or sets a String representing the names of the children of the contact. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
CompanyAndFullName | Returns a String representing the concatenated company name and full name for the contact. Read-only.
CompanyLastFirstNoSpace | Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with no space between the last and first names. Read-only.
CompanyLastFirstSpaceOnly | Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with spaces between the last, first, and middle names. Read-only.
CompanyMainTelephoneNumber | Returns or sets a String representing the company main telephone number for the contact. Read/write.
CompanyName | Returns or sets a String representing the company name for the contact. Read/write.
ComputerNetworkName | Returns or sets a String representing the name of the computer network for the contact. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the ContactItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
CustomerID | Returns or sets a String representing the customer ID for the contact. Read/write.
Department | Returns or sets a String representing the department name for the contact. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Email1Address | Returns or sets a String representing the e-mail address of the first e-mail entry for the contact. Read/write.
Email1AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the first e-mail entry for the contact. Read/write.
Email1DisplayName | Returns a String representing the display name of the first e-mail address for the contact. Read/write.
Email1EntryID | Returns a String representing the entry ID of the first e-mail address for the contact. Read-only.
Email2Address | Returns or sets a String representing the e-mail address of the second e-mail entry for the contact. Read/write.
Email2AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the second e-mail entry for the contact. Read/write.
Email2DisplayName | Returns a String representing the display name of the second e-mail entry for the contact. Read/write.
Email2EntryID | Returns a String representing the entry ID of the second e-mail entry for the contact. Read-only.
Email3Address | Returns or sets a String representing the e-mail address of the third e-mail entry for the contact. Read/write.
Email3AddressType | Returns or sets a String representing the address type (such as EX or SMTP) of the third e-mail entry for the contact. Read/write.
Email3DisplayName | Returns a String representing the display name of the third e-mail entry for the contact. Read/write.
Email3EntryID | Returns a String representing the entry ID of the third e-mail entry for the contact. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FileAs | Returns or sets a String indicating the default keyword string assigned to the contact when it is filed. Read/write.
FirstName | Returns or sets a String representing the first name for the contact. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
FTPSite | Returns or sets a String representing the FTP site entry for the contact. Read/write.
FullName | Returns or sets a String specifying the whole, unparsed full name for the contact. Read/write.
FullNameAndCompany | Returns a String representing the full name and company of the contact by concatenating the values of the FullName and CompanyName properties. Read-only.
Gender | Returns or sets an OlGender constant indicating the gender of the contact. Read/write.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
GovernmentIDNumber | Returns or sets a String representing the government ID number for the contact. Read/write.
HasPicture | Returns a Boolean value that is True if a Contacts item has a picture associated with it. Read-only
Hobby | Returns or sets a String representing the hobby for the contact. Read/write.
Home2TelephoneNumber | Returns or sets a String representing the second home telephone number for the contact. Read/write.
HomeAddress | Returns or sets a String representing the full, unparsed text of the home address for the contact. Read/write.
HomeAddressCity | Returns or sets a String representing the city portion of the home address for the contact. Read/write.
HomeAddressCountry | Returns or sets a String representing the country/region portion of the home address for the contact. Read/write.
HomeAddressPostalCode | Returns or sets a String representing the postal code portion of the home address for the contact. Read/write.
HomeAddressPostOfficeBox | Returns or sets a String the post office box number portion of the home address for the contact. Read/write.
HomeAddressState | Returns or sets a String representing the state portion of the home address for the contact. Read/write.
HomeAddressStreet | Returns or sets a String representing the street portion of the home address for the contact. Read/write.
HomeFaxNumber | Returns or sets a String representing the home fax number for the contact. Read/write.
HomeTelephoneNumber | Returns or sets a String representing the first home telephone number for the contact. Read/write.
IMAddress | Returns or sets a String that represents a contact's Microsoft Instant Messenger address. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
Initials | Returns or sets a String representing the initials for the contact. Read/write.
InternetFreeBusyAddress | Returns or sets a String corresponding to the Address box on the Details tab for a contact. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ISDNNumber | Returns or sets a String representing the ISDN number for the contact. Read/write.
IsMarkedAsTask | Returns a Boolean value that indicates whether the ContactItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
JobTitle | Returns or sets a String representing the job title for the contact. Read/write.
Journal | Returns a Boolean that indicates True if the transaction of the contact will be journalized. Read/write.
Language | Returns or sets a String that represents the language in which the contact writes messages. Read/write.
LastFirstAndSuffix | Returns a String representing the last name, first name, middle name, and suffix of the contact. Read-only.
LastFirstNoSpace | Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.
LastFirstNoSpaceAndSuffix | Returns a String that contains the last name, first name, and suffix of the user without a space. Read-only
LastFirstNoSpaceCompany | Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.
LastFirstSpaceOnly | Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.
LastFirstSpaceOnlyCompany | Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
LastName | Returns or sets a String representing the last name for the contact. Read/write.
LastNameAndFirstName | Returns a String representing the concatenated last name and first name for the contact. Read-only.
MailingAddress | Returns or sets a String representing the full, unparsed selected mailing address for the contact. Read/write.
MailingAddressCity | Returns or sets a String representing the city name portion of the selected mailing address of the contact. Read/write.
MailingAddressCountry | Returns or sets a String representing the country/region code portion of the selected mailing address of the contact. Read/write.
MailingAddressPostalCode | Returns or sets a String representing the postal code (zip code) portion of the selected mailing address of the contact. Read/write.
MailingAddressPostOfficeBox | Returns or sets a String representing the post office box number portion of the selected mailing address of the contact. Read/write.
MailingAddressState | Returns or sets a String representing the state code portion for the selected mailing address of the contact. Read/write.
MailingAddressStreet | Returns or sets a String representing the street address portion of the selected mailing address of the contact. Read/write.
ManagerName | Returns or sets a String representing the manager name for the contact. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
MiddleName | Returns or sets a String representing the middle name for the contact. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
MobileTelephoneNumber | Returns or sets a String representing the mobile telephone number for the contact. Read/write.
NetMeetingAlias | Returns or sets a String indicating the user's Microsoft NetMeeting ID, or alias. Read/write.
NetMeetingServer | Returns or sets a String specifying the name of the Microsoft NetMeeting server being used for an online meeting. Read/write.
NickName | Returns or sets a String representing the nickname for the contact. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OfficeLocation | Returns or sets a String specifying the specific office location (for example, Building 1 Room 1 or Suite 123) for the contact. Read/write.
OrganizationalIDNumber | Returns or sets a String representing the organizational ID number for the contact. Read/write.
OtherAddress | Returns or sets a String representing the other address for the contact. Read/write.
OtherAddressCity | Returns or sets a String representing the city portion of the other address for the contact. Read/write.
OtherAddressCountry | Returns or sets a String representing the country/region portion of the other address for the contact. Read/write.
OtherAddressPostalCode | Returns or sets a String representing the postal code portion of the other address for the contact. Read/write.
OtherAddressPostOfficeBox | Returns or sets a String representing the post office box portion of the other address for the contact. Read/write.
OtherAddressState | Returns or sets a String representing the state portion of the other address for the contact. Read/write.
OtherAddressStreet | Returns or sets a String representing the street portion of the other address for the contact. Read/write.
OtherFaxNumber | Returns or sets a String representing the other fax number for the contact. Read/write.
OtherTelephoneNumber | Returns or sets a String representing the other telephone number for the contact. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
PagerNumber | Returns or sets a String representing the pager number for the contact. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PersonalHomePage | Returns or sets a String representing the URL of the personal Web page for the contact. Read/write.
PrimaryTelephoneNumber | Returns or sets a String specifying the primary telephone number for the contact. Read/write.
Profession | Returns or sets a String indicating the profession for the contact. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ContactItem object. Read-only.
RadioTelephoneNumber | Returns or sets a String indicating the radio telephone number for the contact. Read/write.
ReferredBy | Returns or sets a String specifying the referral name entry for the contact. Read/write.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SelectedMailingAddress | Returns or sets an OlMailingAddress constant indicating the type of the mailing address for the contact. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Spouse | Returns or sets a String indicating the spouse/partner name entry for the contact. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Suffix | Returns or sets a String indicating the name suffix (such as Jr., III, or Ph.D.) for the specified contact. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this ContactItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this ContactItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this ContactItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the ContactItem object. Read/write.
TelexNumber | Returns or sets a String indicating the telex number for the contact. Read/write.
Title | Returns or sets a String indicating the title for the contact. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the ContactItem. Read/write.
TTYTDDTelephoneNumber | Returns or sets a String specifying the TTY/TDD telephone number for the contact. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
User1 | Returns or sets a String specifying the first field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User2 | Returns or sets a String specifying the second field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User3 | Returns or sets a String specifying the third field on the Contacts form intended for miscellaneous use for the contact. Read/write.
User4 | Returns or sets a String specifying the fourth field on the Contacts form intended for miscellaneous use for the contact. Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.
WebPage | Returns or sets a String indicating the URL of the Web page for the contact. Read/write.
YomiCompanyName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the company name for the contact. Read/write.
YomiFirstName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the first name for the contact. Read/write.
YomiLastName | Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the last name for the contact. Read/write.


ContactItem.Account Property (Outlook)

 Copy code hover
[image]

ContactItem.Account Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the account for the contact. Read/write.

Syntax

expression .Account

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Actions Property (Outlook)

 Copy code hover
[image]

ContactItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Anniversary Property (Outlook)

 Copy code hover
[image]

ContactItem.Anniversary Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the anniversary date for the contact. Read/write.

Syntax

expression .Anniversary

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Application Property (Outlook)

 Copy code hover
[image]

ContactItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AssistantName Property (Outlook)

 Copy code hover
[image]

ContactItem.AssistantName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the name of the person who is the assistant for the contact. Read/write.

Syntax

expression .AssistantName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AssistantTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.AssistantTelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String representing the telephone number of the person who is the assistant for the contact. Read/write.

Syntax

expression .AssistantTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Attachments Property (Outlook)

 Copy code hover
[image]

ContactItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

ContactItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a ContactItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its ContactItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

ContactItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a ContactItem object.

Remarks

This is a free-form text field.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Birthday Property (Outlook)

 Copy code hover
[image]

ContactItem.Birthday Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the birthday for the contact. Read/write.

Syntax

expression .Birthday

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Body Property (Outlook)

 Copy code hover
[image]

ContactItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Business2TelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.Business2TelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String representing the second business telephone number for the contact. Read/write.

Syntax

expression .Business2TelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the whole, unparsed business address for the contact. Read/write.

Syntax

expression .BusinessAddress

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressCity Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressCity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the city name portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressCity

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressCountry Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressCountry Property (Outlook)
See also Send feedback

Returns or sets a String representing the country/region code portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressCountry

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressPostalCode Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressPostalCode Property (Outlook)
See also Send feedback

Returns or sets a String representing the postal code (zip code) portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressPostalCode

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressPostOfficeBox Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressPostOfficeBox Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the post office box number portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressPostOfficeBox

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressState Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the state code portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressState

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessAddressStreet Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessAddressStreet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the street address portion of the business address for the contact. Read/write.

Syntax

expression .BusinessAddressStreet

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the BusinessAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to the BusinessAddress property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessCardLayoutXml Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessCardLayoutXml Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents the XML markup for the layout of the Electronic Business Card. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BusinessCardLayoutXml

expression A variable that represents a ContactItem object.

Remarks

For more information on the XML schema for Electronic Business Cards, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessCardType Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessCardType Property (Outlook)
See also Send feedback

Returns an OlBusinessCardType constant that specifies the type of Electronic Business Card used by this contact. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .BusinessCardType

expression A variable that represents a ContactItem object.

Remarks

The Electronic Business Card can be either in Microsoft Office InterConnect format or Outlook format. An Electronic Business Card in InterConnect format cannot be modifed through the Outlook object model.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessFaxNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessFaxNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the business fax number for the contact. Read/write.

Syntax

expression .BusinessFaxNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessHomePage Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessHomePage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the URL of the business Web page for the contact. Read/write.

Syntax

expression .BusinessHomePage

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BusinessTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.BusinessTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the first business telephone number for the contact. Read/write.

Syntax

expression .BusinessTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CallbackTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.CallbackTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the callback telephone number for the contact. Read/write.

Syntax

expression .CallbackTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CarTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.CarTelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String representing the car telephone number for the contact. Read/write.

Syntax

expression .CarTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Categories Property (Outlook)

 Copy code hover
[image]

ContactItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a ContactItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Children Property (Outlook)

 Copy code hover
[image]

ContactItem.Children Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the children of the contact. Read/write.

Syntax

expression .Children

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Class Property (Outlook)

 Copy code hover
[image]

ContactItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Companies Property (Outlook)

 Copy code hover
[image]

ContactItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a ContactItem object.

Remarks

This is a free-form text field.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CompanyAndFullName Property (Outlook)

 Copy code hover
[image]

ContactItem.CompanyAndFullName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the concatenated company name and full name for the contact. Read-only.

Syntax

expression .CompanyAndFullName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CompanyLastFirstNoSpace Property (Outlook)

 Copy code hover
[image]

ContactItem.CompanyLastFirstNoSpace Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with no space between the last and first names. Read-only.

Syntax

expression .CompanyLastFirstNoSpace

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the CompanyName, LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CompanyLastFirstSpaceOnly Property (Outlook)

 Copy code hover
[image]

ContactItem.CompanyLastFirstSpaceOnly Property (Outlook)
See also Send feedback

Returns a String representing the company name for the contact followed by the concatenated last name, first name, and middle name with spaces between the last, first, and middle names. Read-only.

Syntax

expression .CompanyLastFirstSpaceOnly

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the CompanyName, LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CompanyMainTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.CompanyMainTelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String representing the company main telephone number for the contact. Read/write.

Syntax

expression .CompanyMainTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CompanyName Property (Outlook)

 Copy code hover
[image]

ContactItem.CompanyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the company name for the contact. Read/write.

Syntax

expression .CompanyName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ComputerNetworkName Property (Outlook)

 Copy code hover
[image]

ContactItem.ComputerNetworkName Property (Outlook)
See also Send feedback

Returns or sets a String representing the name of the computer network for the contact. Read/write.

Syntax

expression .ComputerNetworkName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Conflicts Property (Outlook)

 Copy code hover
[image]

ContactItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ConversationID Property (Outlook)

 Copy code hover
[image]

ContactItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the ContactItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a ContactItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the ContactItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

ContactItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

ContactItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CreationTime Property (Outlook)

 Copy code hover
[image]

ContactItem.CreationTime Property (Outlook)
See also Send feedback

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CustomerID Property (Outlook)

 Copy code hover
[image]

ContactItem.CustomerID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the customer ID for the contact. Read/write.

Syntax

expression .CustomerID

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Department Property (Outlook)

 Copy code hover
[image]

ContactItem.Department Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the department name for the contact. Read/write.

Syntax

expression .Department

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.DownloadState Property (Outlook)

 Copy code hover
[image]

ContactItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a ContactItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email1Address Property (Outlook)

 Copy code hover
[image]

ContactItem.Email1Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the e-mail address of the first e-mail entry for the contact. Read/write.

Syntax

expression .Email1Address

expression A variable that represents a ContactItem object.

Example

This Visual Basic for Applications (VBA) example sets "someone@example.com" as the e-mail address for the first e-mail entry of a contact.

VBA Copy code Copy code
Sub CreatePeerContact()

 Dim myItem As Outlook.ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email1Address = "someone@example.com"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email1AddressType Property (Outlook)

 Copy code hover
[image]

ContactItem.Email1AddressType Property (Outlook)
See also Send feedback

Returns or sets a String representing the address type (such as EX or SMTP) of the first e-mail entry for the contact. Read/write.

Syntax

expression .Email1AddressType

expression A variable that represents a ContactItem object.

Remarks

This is a free-form text field, but it must match the actual type of an existing e-mail transport.

Example

This Visual Basic for Applications (VBA) example sets "SMTP" as the address type for the first e-mail entry of a contact.

VBA Copy code Copy code
Sub SetType()

 Dim myItem As Outlook.ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email1Address = "someone@example.com"

 myItem.Email1AddressType = "SMTP"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email1DisplayName Property (Outlook)

 Copy code hover
[image]

ContactItem.Email1DisplayName Property (Outlook)
See also Send feedback

Returns a String representing the display name of the first e-mail address for the contact. Read/write.

Syntax

expression .Email1DisplayName

expression A variable that represents a ContactItem object.

Remarks

This property is set to the value of the FullName property by default.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email1EntryID Property (Outlook)

 Copy code hover
[image]

ContactItem.Email1EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the entry ID of the first e-mail address for the contact. Read-only.

Syntax

expression .Email1EntryID

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI named property dispidEmail1OriginalEntryID.

If you are getting this property in a Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) solution, owing to some type issues, instead of directly referencing Email1EntryID, you should get the property through the PropertyAccessor object returned by the ContactItem.PropertyAccessor property, specifying the MAPI property PidLidEmail1OriginalEntryId property and its MAPI id namespace. The following code sample in VBA shows the workaround.

VBA Copy code Copy code
Public Sub GetEmail1EntryID()

 Dim objContactFolder As Outlook.Folder

 Dim objContactItem As Outlook.ContactItem

 Dim objRec As Outlook.Recipient

 Dim strEntryID As String

 Dim oPA As Outlook.PropertyAccessor

 Const EMAIL1_ENTRYID As String = "http://schemas.microsoft.com/mapi/id/{00062004-0000-0000-C000-000000000046}/80850102"

 Set objContactFolder = Application.Session.GetDefaultFolder(olFolderContacts)

 Set objContactItem = objContactFolder.Items(1)

 Set oPA = objContactItem.PropertyAccessor

 strEntryID = oPA.BinaryToString(oPA.GetProperty(EMAIL1_ENTRYID))

 Debug.Print strEntryID

 Set objRec = Application.Session.GetRecipientFromID(strEntryID)

 If objRec Is Nothing Then

 Debug.Print "GetRecipientFromID failed"

 Else

 Debug.Print objRec.Name

 Debug.Print objRec.EntryID

 End If

 'Cleanup

 Set objContactItem = Nothing

 Set objContactFolder = Nothing

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email2Address Property (Outlook)

 Copy code hover
[image]

ContactItem.Email2Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the e-mail address of the second e-mail entry for the contact. Read/write.

Syntax

expression .Email2Address

expression A variable that represents a ContactItem object.

Example

This Visual Basic for Applications (VBA) example sets "someone@example.com" as the e-mail address for the second e-mail entry of a contact.

VBA Copy code Copy code
Sub CreatePeerContact()

 Dim myItem As Outlook.ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email2Address = "someone@example.com"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email2AddressType Property (Outlook)

 Copy code hover
[image]

ContactItem.Email2AddressType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the address type (such as EX or SMTP) of the second e-mail entry for the contact. Read/write.

Syntax

expression .Email2AddressType

expression A variable that represents a ContactItem object.

Remarks

This is a free-form text field, but it must match the actual type of an existing e-mail transport.

Example

This Visual Basic for Applications (VBA) example sets "SMTP" as the address type for the second e-mail entry of a contact.

VBA Copy code Copy code
Sub SetType()

 Dim myItem As Outlook.ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email2Address = "someone@example.com"

 myItem.Email2AddressType = "SMTP"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email2DisplayName Property (Outlook)

 Copy code hover
[image]

ContactItem.Email2DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the second e-mail entry for the contact. Read/write.

Syntax

expression .Email2DisplayName

expression A variable that represents a ContactItem object.

Remarks

This property is set to the value of the FullName property by default.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email2EntryID Property (Outlook)

 Copy code hover
[image]

ContactItem.Email2EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the entry ID of the second e-mail entry for the contact. Read-only.

Syntax

expression .Email2EntryID

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI named property dispidEmail2OriginalEntryID.

If you are getting this property in a Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) solution, owing to some type issues, instead of directly referencing Email2EntryID, you should get the property through the PropertyAccessor object returned by the ContactItem.PropertyAccessor property, specifying the MAPI property PidLidEmail2OriginalEntryId property and its MAPI id namespace. The following code sample in VBA shows the workaround.

VBA Copy code Copy code
Public Sub GetEmail2EntryID()

 Dim objContactFolder As Outlook.Folder

 Dim objContactItem As Outlook.ContactItem

 Dim objRec As Outlook.Recipient

 Dim strEntryID As String

 Dim oPA As Outlook.PropertyAccessor

 Const EMAIL2_ENTRYID As String = "http://schemas.microsoft.com/mapi/id/{00062004-0000-0000-C000-000000000046}/80950102"

 Set objContactFolder = Application.Session.GetDefaultFolder(olFolderContacts)

 Set objContactItem = objContactFolder.Items(1)

 Set oPA = objContactItem.PropertyAccessor

 strEntryID = oPA.BinaryToString(oPA.GetProperty(EMAIL2_ENTRYID))

 Debug.Print strEntryID

 Set objRec = Application.Session.GetRecipientFromID(strEntryID)

 If objRec Is Nothing Then

 Debug.Print "GetRecipientFromID failed"

 Else

 Debug.Print objRec.Name

 Debug.Print objRec.EntryID

 End If

 'Cleanup

 Set objContactItem = Nothing

 Set objContactFolder = Nothing

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email3Address Property (Outlook)

 Copy code hover
[image]

ContactItem.Email3Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the e-mail address of the third e-mail entry for the contact. Read/write.

Syntax

expression .Email3Address

expression A variable that represents a ContactItem object.

Example

This Visual Basic for Applications (VBA) example sets "someone@example.com" as the e-mail address for the third e-mail entry of a contact.

VBA Copy code Copy code
Sub CreatePeerContact()

 Dim myItem As Outlook.ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email3Address = "someone@example.com"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email3AddressType Property (Outlook)

 Copy code hover
[image]

ContactItem.Email3AddressType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the address type (such as EX or SMTP) of the third e-mail entry for the contact. Read/write.

Syntax

expression .Email3AddressType

expression A variable that represents a ContactItem object.

Remarks

This is a free-form text field, but it must match the actual type of an existing e-mail transport.

Example

This Visual Basic for Applications (VBA) example sets "SMTP" as the address type for the third e-mail entry of a contact.

VBA Copy code Copy code
Sub SetType()

 Dim myItem As ContactItem

 Set myItem = Application.CreateItem(olContactItem)

 myItem.Email3Address = "someone@example.com"

 myItem.Email3AddressType = "SMTP"

 myItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email3DisplayName Property (Outlook)

 Copy code hover
[image]

ContactItem.Email3DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the third e-mail entry for the contact. Read/write.

Syntax

expression .Email3DisplayName

expression A variable that represents a ContactItem object.

Remarks

This property is set to the value of the FullName property by default.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Email3EntryID Property (Outlook)

 Copy code hover
[image]

ContactItem.Email3EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the entry ID of the third e-mail entry for the contact. Read-only.

Syntax

expression .Email3EntryID

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI named property dispidEmail3OriginalEntryID.

If you are getting this property in a Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) solution, owing to some type issues, instead of directly referencing Email3EntryID, you should get the property through the PropertyAccessor object returned by the ContactItem.PropertyAccessor property, specifying the MAPI property PidLidEmail3OriginalEntryId property and its MAPI id namespace. The following code sample in VBA shows the workaround.

VBA Copy code Copy code
Public Sub GetEmail3EntryID()

 Dim objContactFolder As Outlook.Folder

 Dim objContactItem As Outlook.ContactItem

 Dim objRec As Outlook.Recipient

 Dim strEntryID As String

 Dim oPA As Outlook.PropertyAccessor

 Const EMAIL3_ENTRYID As String = "http://schemas.microsoft.com/mapi/id/{00062004-0000-0000-C000-000000000046}/80A50102"

 Set objContactFolder = Application.Session.GetDefaultFolder(olFolderContacts)

 Set objContactItem = objContactFolder.Items(1)

 Set oPA = objContactItem.PropertyAccessor

 strEntryID = oPA.BinaryToString(oPA.GetProperty(EMAIL3_ENTRYID))

 Debug.Print strEntryID

 Set objRec = Application.Session.GetRecipientFromID(strEntryID)

 If objRec Is Nothing Then

 Debug.Print "GetRecipientFromID failed"

 Else

 Debug.Print objRec.Name

 Debug.Print objRec.EntryID

 End If

 'Cleanup

 Set objContactItem = Nothing

 Set objContactFolder = Nothing

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.EntryID Property (Outlook)

 Copy code hover
[image]

ContactItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

Example

This Visual Basic for Applications (VBA) example uses the EntryID property to compare the Entry ID of one contact to the Entry ID of a contact returned by a search operation to determine whether the objects represent the same contact. Replace the name with a valid contact name in your Contacts folder before running this example.

VBA Copy code Copy code
Sub UseEntryID()
 Dim myNamespace As Outlook.NameSpace
 Dim myContacts As Outlook.Folder
 Dim myItem1 As Outlook.ContactItem
 Dim myItem2 As Outlook.ContactItem

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts)
 Set myItem1 = myContacts.Items.Find("[FirstName] = ""Dan""")
 Set myitem2 = myContacts.Items.Find("[FileAs] = ""Wil"" and [FirstName] = ""Dan""")
 If Not TypeName(myitem2) = "Nothing" Then
 If myItem1.EntryID = myitem2.EntryID Then
 MsgBox "These two contact items refer to the same contact."
 End If
 Else
 MsgBox "The contact items were not found."
 End If
End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FileAs Property (Outlook)

 Copy code hover
[image]

ContactItem.FileAs Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the default keyword string assigned to the contact when it is filed. Read/write.

Syntax

expression .FileAs

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FirstName Property (Outlook)

 Copy code hover
[image]

ContactItem.FirstName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the first name for the contact. Read/write.

Syntax

expression .FirstName

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the FullName property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes of entries to FullName.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FormDescription Property (Outlook)

 Copy code hover
[image]

ContactItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FTPSite Property (Outlook)

 Copy code hover
[image]

ContactItem.FTPSite Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the FTP site entry for the contact. Read/write.

Syntax

expression .FTPSite

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FullName Property (Outlook)

 Copy code hover
[image]

ContactItem.FullName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the whole, unparsed full name for the contact. Read/write.

Syntax

expression .FullName

expression A variable that represents a ContactItem object.

Remarks

This property is parsed into the FirstName , MiddleName , LastName, and Suffix properties, which may be changed or typed independently if they are parsed incorrectly. Any changes or entries to the FirstName, LastName, MiddleName, or Suffix properties will be overwritten by any subsequent changes or entries to FullName.

Example

This Visual Basic for Applications (VBA) example uses the Restrict method to apply a filter to the contact items based on the item's LastModificationTime property, and then it displays the full name of the contacts returned by the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.FullNameAndCompany Property (Outlook)

 Copy code hover
[image]

ContactItem.FullNameAndCompany Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the full name and company of the contact by concatenating the values of the FullName and CompanyName properties. Read-only.

Syntax

expression .FullNameAndCompany

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Gender Property (Outlook)

 Copy code hover
[image]

ContactItem.Gender Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlGender constant indicating the gender of the contact. Read/write.

Syntax

expression .Gender

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.GetInspector Property (Outlook)

 Copy code hover
[image]

ContactItem.GetInspector Property (Outlook)
See also Send feedback

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a ContactItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.GovernmentIDNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.GovernmentIDNumber Property (Outlook)
See also Send feedback

Returns or sets a String representing the government ID number for the contact. Read/write.

Syntax

expression .GovernmentIDNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HasPicture Property (Outlook)

 Copy code hover
[image]

ContactItem.HasPicture Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if a Contacts item has a picture associated with it. Read-only

Syntax

expression .HasPicture

expression A variable that represents a ContactItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user to specify the name of a contact and the file name containing a picture of the contact, and then adds the picture to the contact item. If a picture already exists for the contact item, the example prompts the user to specify if the existing picture should be overwritten by the new file.

VBA Copy code Copy code
Sub AddPictureToAContact()

 Dim myNms As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myContactItem As Outlook.ContactItem

 Dim strName As String

 Dim strPath As String

 Dim strPrompt As String

 Set myNms = Application.GetNamespace("MAPI")

 Set myFolder = myNms.GetDefaultFolder(olFolderContacts)

 strName = InputBox("Type the name of the contact: ")

 Set myContactItem = myFolder.Items(strName)

 If myContactItem.HasPicture = True Then

 strPrompt = MsgBox("The contact already has a picture associated with it. Do you want to overwrite the existing picture?", vbYesNo)

 If strPrompt = vbNo Then

 Exit Sub

 End If

 End If

 strPath = InputBox("Type the file name for the contact: ")

 myContactItem.AddPicture (strPath)

 myContactItem.Save

 myContactItem.Display

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Hobby Property (Outlook)

 Copy code hover
[image]

ContactItem.Hobby Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the hobby for the contact. Read/write.

Syntax

expression .Hobby

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Home2TelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.Home2TelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the second home telephone number for the contact. Read/write.

Syntax

expression .Home2TelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddress Property (Outlook)
See also Send feedback

Returns or sets a String representing the full, unparsed text of the home address for the contact. Read/write.

Syntax

expression .HomeAddress

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressCity Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressCity Property (Outlook)
See also Send feedback

Returns or sets a String representing the city portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressCity

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressCountry Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressCountry Property (Outlook)
See also Send feedback

Returns or sets a String representing the country/region portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressCountry

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressPostalCode Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressPostalCode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the postal code portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressPostalCode

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressPostOfficeBox Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressPostOfficeBox Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String the post office box number portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressPostOfficeBox

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressState Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the state portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressState

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeAddressStreet Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeAddressStreet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the street portion of the home address for the contact. Read/write.

Syntax

expression .HomeAddressStreet

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the HomeAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to HomeAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeFaxNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeFaxNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the home fax number for the contact. Read/write.

Syntax

expression .HomeFaxNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.HomeTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.HomeTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the first home telephone number for the contact. Read/write.

Syntax

expression .HomeTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.IMAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.IMAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents a contact's Microsoft Instant Messenger address. Read/write.

Syntax

expression .IMAddress

expression A variable that represents a ContactItem object.

Remarks

Unlike the Recipients or To properties, there is no way to verify that the IMAddress property contains a valid address.

Example

The following example creates a new contact and prompts the user to enter an Instant Messenger address for the contact.

VBA Copy code Copy code
Sub SetImAddress()

 'Sets a new IM Address

 Dim objNewContact As ContactItem

 Set objNewContact = Application.CreateItem(olContactItem)

 objNewContact.IMAddress = _

 InputBox("Enter the new contact's Microsoft Instant Messenger address")

 objNewContact.Save

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Importance Property (Outlook)

 Copy code hover
[image]

ContactItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Initials Property (Outlook)

 Copy code hover
[image]

ContactItem.Initials Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the initials for the contact. Read/write.

Syntax

expression .Initials

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.InternetFreeBusyAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.InternetFreeBusyAddress Property (Outlook)
See also Send feedback

Returns or sets a String corresponding to the Address box on the Details tab for a contact. Read/write.

Syntax

expression .InternetFreeBusyAddress

expression A variable that represents a ContactItem object.

Remarks

The Address box on the Details tab can contain the URL location of the user's free-busy information in vCard Free-Busy standard format.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.IsConflict Property (Outlook)

 Copy code hover
[image]

ContactItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a ContactItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ISDNNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.ISDNNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the ISDN number for the contact. Read/write.

Syntax

expression .ISDNNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.IsMarkedAsTask Property (Outlook)

 Copy code hover
[image]

ContactItem.IsMarkedAsTask Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the ContactItem is marked as a task. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsMarkedAsTask

expression An expression that returns a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

ContactItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a ContactItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.JobTitle Property (Outlook)

 Copy code hover
[image]

ContactItem.JobTitle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the job title for the contact. Read/write.

Syntax

expression .JobTitle

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Journal Property (Outlook)

 Copy code hover
[image]

ContactItem.Journal Property (Outlook)
See also Send feedback

Returns a Boolean that indicates True if the transaction of the contact will be journalized. Read/write.

Syntax

expression .Journal

expression A variable that represents a ContactItem object.

Remarks

The default value is False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Language Property (Outlook)

 Copy code hover
[image]

ContactItem.Language Property (Outlook)
See also Send feedback

Returns or sets a String that represents the language in which the contact writes messages. Read/write.

Syntax

expression .Language

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagLanguage.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstAndSuffix Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstAndSuffix Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the last name, first name, middle name, and suffix of the contact. Read-only.

Syntax

expression .LastFirstAndSuffix

expression A variable that represents a ContactItem object.

Remarks

There is a comma between the last and first names and spaces between all the names and the suffix. This property is parsed from the LastName, FirstName, MiddleName and Suffix properties. The LastName, FirstName, and Suffix properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstNoSpace Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstNoSpace Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.

Syntax

expression .LastFirstNoSpace

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstNoSpaceAndSuffix Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstNoSpaceAndSuffix Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that contains the last name, first name, and suffix of the user without a space. Read-only

Syntax

expression .LastFirstNoSpaceAndSuffix

expression A variable that represents a ContactItem object.

Remarks

This property is used only when the FirstName, LastName, and Suffix properties (the fields that define this property) contain Asian (DBCS) characters. Note that any such changes or entries to the FirstName, LastName, or Suffix properties will be overwritten by any subsequent changes or entries to FullName.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstNoSpaceCompany Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstNoSpaceCompany Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the concatenated last name, first name, and middle name of the contact with no space between the last name and the first name. Read-only.

Syntax

expression .LastFirstNoSpaceCompany

expression A variable that represents a ContactItem object.

Remarks

The company name for the contact is included after the middle name. This property is parsed from the CompanyName, LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstSpaceOnly Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstSpaceOnly Property (Outlook)
See also Send feedback

Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.

Syntax

expression .LastFirstSpaceOnly

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastFirstSpaceOnlyCompany Property (Outlook)

 Copy code hover
[image]

ContactItem.LastFirstSpaceOnlyCompany Property (Outlook)
See also Send feedback

Returns a String representing the concatenated last name, first name, and middle name of the contact with spaces between them. Read-only.

Syntax

expression .LastFirstSpaceOnlyCompany

expression A variable that represents a ContactItem object.

Remarks

The company name for the contact is included after the middle name. This property is parsed from the CompanyName, LastName, FirstName, and MiddleName properties. The LastName, FirstName, and MiddleName properties are themselves parsed from the FullName property. The value of this property is only filled when its associated property (FirstName, LastName, MiddleName, CompanyName, and Suffix) contain Asian (DBCS) characters. If the corresponding field does not contain Asian characters, the property will be empty.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

ContactItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastName Property (Outlook)

 Copy code hover
[image]

ContactItem.LastName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the last name for the contact. Read/write.

Syntax

expression .LastName

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the FullName property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes of entries to FullName.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.LastNameAndFirstName Property (Outlook)

 Copy code hover
[image]

ContactItem.LastNameAndFirstName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the concatenated last name and first name for the contact. Read-only.

Syntax

expression .LastNameAndFirstName

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the FirstName and LastName properties for the contact, which are themselves parsed from the FullName property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the full, unparsed selected mailing address for the contact. Read/write.

Syntax

expression .MailingAddress

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressCity Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressCity Property (Outlook)
See also Send feedback

Returns or sets a String representing the city name portion of the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressCity

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressCountry Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressCountry Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the country/region code portion of the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressCountry

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressPostalCode Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressPostalCode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the postal code (zip code) portion of the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressPostalCode

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressPostOfficeBox Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressPostOfficeBox Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the post office box number portion of the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressPostOfficeBox

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressState Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the state code portion for the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressState

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MailingAddressStreet Property (Outlook)

 Copy code hover
[image]

ContactItem.MailingAddressStreet Property (Outlook)
See also Send feedback

Returns or sets a String representing the street address portion of the selected mailing address of the contact. Read/write.

Syntax

expression .MailingAddressStreet

expression A variable that represents a ContactItem object.

Remarks

This property replicates the property indicated by the SelectedMailingAddress property, which is one of the following OlMailingAddress constants: olBusiness, olHome, olNone, or olOther. While it can be changed or entered independently, any such changes or entries to this property will be overwritten by any subsequent changes or entries to the property indicated by SelectedMailingAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ManagerName Property (Outlook)

 Copy code hover
[image]

ContactItem.ManagerName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the manager name for the contact. Read/write.

Syntax

expression .ManagerName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

ContactItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a ContactItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MessageClass Property (Outlook)

 Copy code hover
[image]

ContactItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

ContactItem Object
Item Types and Message Classes

Other resources

ContactItem Object Members


ContactItem.MiddleName Property (Outlook)

 Copy code hover
[image]

ContactItem.MiddleName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the middle name for the contact. Read/write.

Syntax

expression .MiddleName

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the FullName property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes of entries to FullName.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Mileage Property (Outlook)

 Copy code hover
[image]

ContactItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a ContactItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MobileTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.MobileTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mobile telephone number for the contact. Read/write.

Syntax

expression .MobileTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.NetMeetingAlias Property (Outlook)

 Copy code hover
[image]

ContactItem.NetMeetingAlias Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the user's Microsoft NetMeeting ID, or alias. Read/write.

Syntax

expression .NetMeetingAlias

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.NetMeetingServer Property (Outlook)

 Copy code hover
[image]

ContactItem.NetMeetingServer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the name of the Microsoft NetMeeting server being used for an online meeting. Read/write.

Syntax

expression .NetMeetingServer

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.NickName Property (Outlook)

 Copy code hover
[image]

ContactItem.NickName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the nickname for the contact. Read/write.

Syntax

expression .NickName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.NoAging Property (Outlook)

 Copy code hover
[image]

ContactItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OfficeLocation Property (Outlook)

 Copy code hover
[image]

ContactItem.OfficeLocation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the specific office location (for example, Building 1 Room 1 or Suite 123) for the contact. Read/write.

Syntax

expression .OfficeLocation

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagOfficeLocation.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OrganizationalIDNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.OrganizationalIDNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the organizational ID number for the contact. Read/write.

Syntax

expression .OrganizationalIDNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the other address for the contact. Read/write.

Syntax

expression .OtherAddress

expression A variable that represents a ContactItem object.

Remarks

This property contains the full, unparsed other address for the contact.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressCity Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressCity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the city portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressCity

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressCountry Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressCountry Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the country/region portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressCountry

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressPostalCode Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressPostalCode Property (Outlook)
See also Send feedback

Returns or sets a String representing the postal code portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressPostalCode

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressPostOfficeBox Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressPostOfficeBox Property (Outlook)
See also Send feedback

Returns or sets a String representing the post office box portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressPostOfficeBox

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressState Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressState Property (Outlook)
See also Send feedback

Returns or sets a String representing the state portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressState

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherAddressStreet Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherAddressStreet Property (Outlook)
See also Send feedback

Returns or sets a String representing the street portion of the other address for the contact. Read/write.

Syntax

expression .OtherAddressStreet

expression A variable that represents a ContactItem object.

Remarks

This property is parsed from the OtherAddress property, but may be changed or entered independently should it be parsed incorrectly. Note that any such changes or entries to this property will be overwritten by any subsequent changes or entries to OtherAddress.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherFaxNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherFaxNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the other fax number for the contact. Read/write.

Syntax

expression .OtherFaxNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OtherTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.OtherTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the other telephone number for the contact. Read/write.

Syntax

expression .OtherTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

ContactItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

ContactItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PagerNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.PagerNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the pager number for the contact. Read/write.

Syntax

expression .PagerNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Parent Property (Outlook)

 Copy code hover
[image]

ContactItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PersonalHomePage Property (Outlook)

 Copy code hover
[image]

ContactItem.PersonalHomePage Property (Outlook)
See also Send feedback

Returns or sets a String representing the URL of the personal Web page for the contact. Read/write.

Syntax

expression .PersonalHomePage

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PrimaryTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.PrimaryTelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String specifying the primary telephone number for the contact. Read/write.

Syntax

expression .PrimaryTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Profession Property (Outlook)

 Copy code hover
[image]

ContactItem.Profession Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the profession for the contact. Read/write.

Syntax

expression .Profession

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

ContactItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ContactItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.RadioTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.RadioTelephoneNumber Property (Outlook)
See also Send feedback

Returns or sets a String indicating the radio telephone number for the contact. Read/write.

Syntax

expression .RadioTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReferredBy Property (Outlook)

 Copy code hover
[image]

ContactItem.ReferredBy Property (Outlook)
See also Send feedback

Returns or sets a String specifying the referral name entry for the contact. Read/write.

Syntax

expression .ReferredBy

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

ContactItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a ContactItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

ContactItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents a ContactItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

ContactItem.ReminderSet Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

ContactItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents a ContactItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

ContactItem.ReminderTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.RTFBody Property (Outlook)

 Copy code hover
[image]

ContactItem.RTFBody Property (Outlook)
See also Send feedback

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a ContactItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Saved Property (Outlook)

 Copy code hover
[image]

ContactItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.SelectedMailingAddress Property (Outlook)

 Copy code hover
[image]

ContactItem.SelectedMailingAddress Property (Outlook)
See also Send feedback

Returns or sets an OlMailingAddress constant indicating the type of the mailing address for the contact. Read/write.

Syntax

expression .SelectedMailingAddress

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

ContactItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Session Property (Outlook)

 Copy code hover
[image]

ContactItem.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ContactItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Size Property (Outlook)

 Copy code hover
[image]

ContactItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Spouse Property (Outlook)

 Copy code hover
[image]

ContactItem.Spouse Property (Outlook)
See also Send feedback

Returns or sets a String indicating the spouse/partner name entry for the contact. Read/write.

Syntax

expression .Spouse

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Subject Property (Outlook)

 Copy code hover
[image]

ContactItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a ContactItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Suffix Property (Outlook)

 Copy code hover
[image]

ContactItem.Suffix Property (Outlook)
See also Send feedback

Returns or sets a String indicating the name suffix (such as Jr., III, or Ph.D.) for the specified contact. Read/write.

Syntax

expression .Suffix

expression A variable that represents a ContactItem object.

Remarks

The LastName , FirstName , MiddleName , and Suffix properties are parsed from the FullName property.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TaskCompletedDate Property (Outlook)

 Copy code hover
[image]

ContactItem.TaskCompletedDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the completion date of the task for this ContactItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskCompletedDate

expression An expression that returns a ContactItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TaskDueDate Property (Outlook)

 Copy code hover
[image]

ContactItem.TaskDueDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the due date of the task for this ContactItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskDueDate

expression An expression that returns a ContactItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TaskStartDate Property (Outlook)

 Copy code hover
[image]

ContactItem.TaskStartDate Property (Outlook)
See also Send feedback

Returns or sets a Date value that represents the start date of the task for this ContactItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskStartDate

expression An expression that returns a ContactItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TaskSubject Property (Outlook)

 Copy code hover
[image]

ContactItem.TaskSubject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the subject of the task for the ContactItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskSubject

expression An expression that returns a ContactItem object.

Remarks

This property returns the value of the Subject property if the IsMarkedAsTask property is set to False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TelexNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.TelexNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the telex number for the contact. Read/write.

Syntax

expression .TelexNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Title Property (Outlook)

 Copy code hover
[image]

ContactItem.Title Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the title for the contact. Read/write.

Syntax

expression .Title

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

ContactItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the ordinal value of the task for the ContactItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a ContactItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar. The value used in this property does not have any relation to the values of the TaskStartDate, TaskDueDate, or TaskCompletedDate properties.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.TTYTDDTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ContactItem.TTYTDDTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the TTY/TDD telephone number for the contact. Read/write.

Syntax

expression .TTYTDDTelephoneNumber

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.UnRead Property (Outlook)

 Copy code hover
[image]

ContactItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.User1 Property (Outlook)

 Copy code hover
[image]

ContactItem.User1 Property (Outlook)
See also Send feedback

Returns or sets a String specifying the first field on the Contacts form intended for miscellaneous use for the contact. Read/write.

Syntax

expression .User1

expression A variable that represents a ContactItem object.

Remarks

The properties ContactItem.User1, ContactItem.User2, ContactItem.User3, and ContactItem.User4 map to the fields User Field 1, User Field 2, User Field 3, and User Field 4 on the Contacts form respectively. These properties are explicit built-in String properties; users can use these fields for miscellaneous purposes for the contact.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.User2 Property (Outlook)

 Copy code hover
[image]

ContactItem.User2 Property (Outlook)
See also Send feedback

Returns or sets a String specifying the second field on the Contacts form intended for miscellaneous use for the contact. Read/write.

Syntax

expression .User2

expression A variable that represents a ContactItem object.

Remarks

The properties ContactItem.User1, ContactItem.User2, ContactItem.User3, and ContactItem.User4 map to the fields User Field 1, User Field 2, User Field 3, and User Field 4 on the Contacts form respectively. These properties are explicit built-in String properties; users can use these fields for miscellaneous purposes for the contact.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.User3 Property (Outlook)

 Copy code hover
[image]

ContactItem.User3 Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the third field on the Contacts form intended for miscellaneous use for the contact. Read/write.

Syntax

expression .User3

expression A variable that represents a ContactItem object.

Remarks

The properties ContactItem.User1, ContactItem.User2, ContactItem.User3, and ContactItem.User4 map to the fields User Field 1, User Field 2, User Field 3, and User Field 4 on the Contacts form respectively. These properties are explicit built-in String properties; users can use these fields for miscellaneous purposes for the contact.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.User4 Property (Outlook)

 Copy code hover
[image]

ContactItem.User4 Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the fourth field on the Contacts form intended for miscellaneous use for the contact. Read/write.

Syntax

expression .User4

expression A variable that represents a ContactItem object.

Remarks

The properties ContactItem.User1, ContactItem.User2, ContactItem.User3, and ContactItem.User4 map to the fields User Field 1, User Field 2, User Field 3, and User Field 4 on the Contacts form respectively. These properties are explicit built-in String properties; users can use these fields for miscellaneous purposes for the contact.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.UserProperties Property (Outlook)

 Copy code hover
[image]

ContactItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a ContactItem object.

Example

This Visual Basic for Applications (VBA) example finds a custom property named LastDateContacted for the contact 'Jeff Smith' and displays it to the user. To run this example, you need to replace 'Jeff Smith' with a valid contact name and create a user-defined property called LastDateContacted for the contact.

VBA Copy code Copy code
Sub FindContact()

 'Finds and displays last contacted info for a contact

 Dim objContact As Outlook.ContactItem

 Dim objContacts As Outlook.Folder

 Dim objNameSpace As Outlook.NameSpace

 Dim objProperty As Outlook.UserProperty

 Set objNameSpace = Application.GetNamespace("MAPI")

 Set objContacts = objNameSpace.GetDefaultFolder(olFolderContacts)

 Set objContact = objContacts.Items.Find( _

 "[FileAs] = ""Smith, Jeff"" and [FirstName] = ""Jeff""")

 If Not TypeName(objContact) = "Nothing" Then

 Set objProperty = _

 objContact.UserProperties.Find("LastDateContacted")

 If TypeName(objProperty) <> "Nothing" Then

 MsgBox "Last Date Contacted: " & objProperty.Value

 End If

 Else

 MsgBox "The contact was not found."

 End If

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.WebPage Property (Outlook)

 Copy code hover
[image]

ContactItem.WebPage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the URL of the Web page for the contact. Read/write.

Syntax

expression .WebPage

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.YomiCompanyName Property (Outlook)

 Copy code hover
[image]

ContactItem.YomiCompanyName Property (Outlook)
See also Send feedback

Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the company name for the contact. Read/write.

Syntax

expression .YomiCompanyName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.YomiFirstName Property (Outlook)

 Copy code hover
[image]

ContactItem.YomiFirstName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the first name for the contact. Read/write.

Syntax

expression .YomiFirstName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.YomiLastName Property (Outlook)

 Copy code hover
[image]

ContactItem.YomiLastName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the Japanese phonetic rendering (yomigana) of the last name for the contact. Read/write.

Syntax

expression .YomiLastName

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem Methods (Outlook)

 Copy code hover
[image]

ContactItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddBusinessCardLogoPicture | Adds a logo picture to the current Electronic Business Card of the contact item.
AddPicture | Adds a picture to a contact item.
ClearTaskFlag | Clears the ContactItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
ForwardAsBusinessCard | Creates a new MailItem object containing contact information and, optionally, an Electronic Business Card (EBC) image based on the specified ContactItem object.
ForwardAsVcard | Creates a MailItem and attaches the contact information in vCard format.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a ContactItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
RemovePicture | Removes a picture from a Contacts item.
ResetBusinessCard | Resets the Electronic Business Card on the contact item to the default business card, deleting any custom layout and logo on the Electronic Business Card.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
SaveBusinessCardImage | Saves an image of the business card generated from the specified ContactItem object.
ShowBusinessCardEditor | Displays the electronic business card (EBC) editor dialog box for the ContactItem object.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
ShowCheckAddressDialog | Displays the Check Address dialog box to verify address details of the contact.
ShowCheckFullNameDialog | Displays the Check Full Name dialog box to verify name details of the contact.
ShowCheckPhoneDialog | Displays the Check Phone Number dialog box for a specified telephone number contained by a ContactItem object.


ContactItem.AddBusinessCardLogoPicture Method (Outlook)

 Copy code hover
[image]

ContactItem.AddBusinessCardLogoPicture Method (Outlook)
See also Send feedback

Adds a logo picture to the current Electronic Business Card of the contact item.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddBusinessCardLogoPicture(Path)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The full path name that specifies the picture file to load.

Remarks

An Electronic Business Card can only have one logo picture, so any existing logo pictures will be replaced. Standard graphic formats are supported, including .BMP, .GIF, .JPG, and .PNG.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AddPicture Method (Outlook)

 Copy code hover
[image]

ContactItem.AddPicture Method (Outlook)
See also Send feedback

Adds a picture to a contact item.

Syntax

expression .AddPicture(Path)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | A string containing the complete path and filename of the picture to be added to the contact item.

Remarks

If the contact item already has a picture attached to it, this method will overwrite the existing picture.

The picture can be an icon, GIF, JPEG, BMP, TIFF, WMF, EMF, or PNG file. Microsoft Outlook will automatically perform the necessary resizing of the picture.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user to specify the name of a contact and the file name containing a picture of the contact, and then adds the picture to the contact item. If a picture already exists for the contact item, the example prompts the user to specify if the existing picture should be overwritten by the new file.

VBA Copy code Copy code
Sub AddPictureToAContact()

 Dim myNms As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myContactItem As Outlook.ContactItem

 Dim strName As String

 Dim strPath As String

 Dim strPrompt As String

 Set myNms = Application.GetNamespace("MAPI")

 Set myFolder = myNms.GetDefaultFolder(olFolderContacts)

 strName = InputBox("Type the name of the contact: ")

 Set myContactItem = myFolder.Items(strName)

 If myContactItem.HasPicture = True Then

 strPrompt = MsgBox("The contact already has a picture associated with it. Do you want to overwrite the existing picture?", vbYesNo)

 If strPrompt = vbNo Then

 Exit Sub

 End If

 End If

 strPath = InputBox("Type the file name for the contact: ")

 myContactItem.AddPicture (strPath)

 myContactItem.Save

 myContactItem.Display

 End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ClearTaskFlag Method (Outlook)

 Copy code hover
[image]

ContactItem.ClearTaskFlag Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the ContactItem object as a task.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearTaskFlag

expression An expression that returns a ContactItem object.

Remarks

Calling this method sets the IsMarkedAsTask property to False.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Close Method (Outlook)

 Copy code hover
[image]

ContactItem.Close Method (Outlook)
See also Send feedback

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Copy Method (Outlook)

 Copy code hover
[image]

ContactItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a ContactItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Delete Method (Outlook)

 Copy code hover
[image]

ContactItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a ContactItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

ContactItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

ContactItemMembers


ContactItem.Display Method (Outlook)

 Copy code hover
[image]

ContactItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ForwardAsBusinessCard Method (Outlook)

 Copy code hover
[image]

ContactItem.ForwardAsBusinessCard Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new MailItem object containing contact information and, optionally, an Electronic Business Card (EBC) image based on the specified ContactItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForwardAsBusinessCard

expression An expression that returns a ContactItem object.

Return Value

A MailItem object that represents the new e-mail item containing the business card information.

Remarks

This method creates a new Outlook mail item based on the information stored in the ContactItem object. The information included in the Outlook mail item depends on the value of the BodyFormat property for the MailItem object:

Property value | Result
olFormatPlain | A vCard (.vcf) file is created and added to the Attachments collection of the MailItem object.
olFormatRichText | A vCard file is created and added to the Attachments collection of the MailItem object.
olFormatHTML | An image of the Electronic Business Card is generated and included in the Body property of the MailItem object, and a vCard file is created and added to the Attachments collection of the MailItem object.
Note Note

The attached vCard file contains only the contact information included in the Electronic Business Card associated with the ContactItem object. Any contact information not displayed in the Electronic Business Card is excluded from the vCard file.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ForwardAsVcard Method (Outlook)

 Copy code hover
[image]

ContactItem.ForwardAsVcard Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a MailItem and attaches the contact information in vCard format.

Syntax

expression .ForwardAsVcard

expression A variable that represents a ContactItem object.

Return Value

A MailItem object that represents the new mail item to which the contact information is attached.

Remarks

vCard is the Internet standard for creating and sharing virtual business cards.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.GetConversation Method (Outlook)

 Copy code hover
[image]

ContactItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a ContactItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.MarkAsTask Method (Outlook)

 Copy code hover
[image]

ContactItem.MarkAsTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks a ContactItem object as a task and assigns a task interval for the object.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask(MarkInterval)

expression An expression that returns a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
MarkInterval | Required | OlMarkInterval | The task interval for the ContactItem.

Remarks

Calling this method sets the value of several other properties, depending on the value provided in MarkInterval. For more information about the properties set by specifying MarkInterval, see OlMarkInterval Enumeration.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Move Method (Outlook)

 Copy code hover
[image]

ContactItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PrintOut Method (Outlook)

 Copy code hover
[image]

ContactItem.PrintOut Method (Outlook)
See also Send feedback

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.RemovePicture Method (Outlook)

 Copy code hover
[image]

ContactItem.RemovePicture Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes a picture from a Contacts item.

Syntax

expression .RemovePicture

expression A variable that represents a ContactItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user to specify a name of a contact and removes the picture from the contact item. If a picture does not exist for the contact, the example displays a message to the user.

VBA Copy code Copy code
Sub RemovePictureFromContact()

 Dim myNms As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myContactItem As Outlook.ContactItem

 Dim strName As String

 Dim strPath As String

 Dim strPrompt As String

 Set myNms = Application.GetNamespace("MAPI")

 Set myFolder = myNms.GetDefaultFolder(olFolderContacts)

 strName = InputBox("Type the name of the contact: ")

 Set myContactItem = myFolder.Items(strName)

 If myContactItem.HasPicture = False Then

 MsgBox "The contact does not have a picture associated with it."

 Else

 myContactItem.RemovePicture

 myContactItem.Save

 myContactItem.Display

 End If

End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ResetBusinessCard Method (Outlook)

 Copy code hover
[image]

ContactItem.ResetBusinessCard Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets the Electronic Business Card on the contact item to the default business card, deleting any custom layout and logo on the Electronic Business Card.

Version Information

Version Added: Outlook 2007

Syntax

expression .ResetBusinessCard

expression A variable that represents a ContactItem object.

Remarks

For contacts with a Microsoft Office InterConnect card type, this will reset the contact to using an Outlook card type.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Save Method (Outlook)

 Copy code hover
[image]

ContactItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.SaveAs Method (Outlook)

 Copy code hover
[image]

ContactItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object
 Set myItem = myOlApp.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.ContactItem

 Set MyItem = Application.CreateItem(olContactItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.SaveBusinessCardImage Method (Outlook)

 Copy code hover
[image]

ContactItem.SaveBusinessCardImage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves an image of the business card generated from the specified ContactItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveBusinessCardImage(Path)

expression An expression that returns a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The fully qualified path and file name of the image to be saved.

Remarks

This method generates an image, as a Portable Network Graphics (.png) file, of the business card generated from the specified ContactItem object. If the path and file name specified in Path cannot be resolved, an error occurs.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ShowBusinessCardEditor Method (Outlook)

 Copy code hover
[image]

ContactItem.ShowBusinessCardEditor Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the electronic business card (EBC) editor dialog box for the ContactItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowBusinessCardEditor

expression An expression that returns a ContactItem object.

Remarks

Calling this method retrieves the data for the specified ContactItem object and then modally displays that data in the EBC editor dialog box. An error occurs if the data cannot be retrieved.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

ContactItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ShowCheckAddressDialog Method (Outlook)

 Copy code hover
[image]

ContactItem.ShowCheckAddressDialog Method (Outlook)
See also Send feedback

Displays the Check Address dialog box to verify address details of the contact.

Version information

Version Added: Outlook 2013

Syntax

expression .ShowCheckAddressDialog(MailingAddress)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data type | Description
MailingAddress | Required | OlMailingAddress | The type of address to be checked.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ShowCheckFullNameDialog Method (Outlook)

 Copy code hover
[image]

ContactItem.ShowCheckFullNameDialog Method (Outlook)
See also Send feedback

Displays the Check Full Name dialog box to verify name details of the contact.

Version information

Version Added: Outlook 2013

Syntax

expression .ShowCheckFullNameDialog

expression A variable that represents a ContactItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ShowCheckPhoneDialog Method (Outlook)

 Copy code hover
[image]

ContactItem.ShowCheckPhoneDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Check Phone Number dialog box for a specified telephone number contained by a ContactItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowCheckPhoneDialog(PhoneNumber)

expression An expression that returns a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
PhoneNumber | Required | OlContactPhoneNumber | The type of telephone number to be checked.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem Events (Outlook)

 Copy code hover
[image]

ContactItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


ContactItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

ContactItem.AfterWrite Event (Outlook)
See also Send feedback

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a ContactItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

ContactItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

ContactItem.AttachmentRead Event (Outlook)
See also Send feedback

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

ContactItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment, )

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel, )

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the ContactItem to be saved.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

ContactItem.BeforeRead Event (Outlook)
See also Send feedback

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a ContactItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Close Event (Outlook)

 Copy code hover
[image]

ContactItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CustomAction Event (Outlook)

 Copy code hover
[image]

ContactItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

ContactItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Forward Event (Outlook)

 Copy code hover
[image]

ContactItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Open Event (Outlook)

 Copy code hover
[image]

ContactItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

ContactItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Read Event (Outlook)

 Copy code hover
[image]

ContactItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a ContactItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

ContactItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Reply Event (Outlook)

 Copy code hover
[image]

ContactItem.Reply Event (Outlook)
See also Send feedback

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

ContactItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Send Event (Outlook)

 Copy code hover
[image]

ContactItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Unload Event (Outlook)

 Copy code hover
[image]

ContactItem.Unload Event (Outlook)
See also Send feedback

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a ContactItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactItem.Write Event (Outlook)

 Copy code hover
[image]

ContactItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a ContactItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

ContactItem Object

Other resources

ContactItem Object Members


ContactsModule Object (Outlook)

 Copy code hover
[image]

ContactsModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the Contacts navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The ContactsModule object, derived from the NavigationModule object, provides access to the navigation groups contained in the Contacts navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the Modules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the navigation module type. If the NavigationModuleType property is set to olModuleContacts, you can then cast the NavigationModule object reference as a ContactsModule object to access the NavigationGroups property for that navigation module.

You can use the Visible property to determine if the navigation module is visible and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Contacts navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

ContactsModule Object Members


ContactsModule Members (Outlook)

 Copy code hover
[image]

ContactsModule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Contacts navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the ContactsModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the ContactsModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the ContactsModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the ContactsModule object is displayed in the Navigation Pane. Read/write.


ContactsModule Properties (Outlook)

 Copy code hover
[image]

ContactsModule Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the ContactsModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the ContactsModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the ContactsModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the ContactsModule object is displayed in the Navigation Pane. Read/write.


ContactsModule.Application Property (Outlook)

 Copy code hover
[image]

ContactsModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Class Property (Outlook)

 Copy code hover
[image]

ContactsModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a ContactsModule object.

Remarks

This property returns olContactsModule for the ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Name Property (Outlook)

 Copy code hover
[image]

ContactsModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the ContactsModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

ContactsModule.NavigationGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroups object that contains the set of navigation groups associated with the ContactsModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

ContactsModule.NavigationModuleType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a ContactsModule object.

Remarks

This property returns olModuleContacts for the ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Parent Property (Outlook)

 Copy code hover
[image]

ContactsModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Position Property (Outlook)

 Copy code hover
[image]

ContactsModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the ContactsModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a ContactsModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a given ContactsModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified ContactsModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified ContactsModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Session Property (Outlook)

 Copy code hover
[image]

ContactsModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a ContactsModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


ContactsModule.Visible Property (Outlook)

 Copy code hover
[image]

ContactsModule.Visible Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that determines whether the ContactsModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a ContactsModule object.

See also

Concepts

ContactsModule Object

Other resources

ContactsModule Object Members


Conversation Object (Outlook)

 Copy code hover
[image]

Conversation Object (Outlook)
See also Send feedback

Represents a conversation that includes one or more items stored in one or more folders and stores.

Version Information

Version Added: Outlook 2010

Remarks

The Conversation object is an abstract, aggregated object. Although a conversation can include items of different types, the Conversation object does not correspond to a particular underlying MAPI IMessage object.

A conversation represents one or more items in one or more folders and stores. If you move an item in a conversation to the Deleted Items folder and subsequently enumerate the conversation by using the GetChildren, GetRootItems, or GetTable method, the item will not be included in the returned object.

To obtain a Conversation object for an existing conversation, use the GetConversation method of the item.

There are actions that you can apply to items in a conversation by calling the SetAlwaysAssignCategories, SetAlwaysDelete, or SetAlwaysMoveToFolder method. Each of these actions is applied to all items in the conversation automatically when the method is called; the action is also applied to future items in the conversation as long as the action is still applicable to the conversation. There is no explicit save method on the Conversation object.

Also, when you apply an action to items in a conversation, the corresponding event occurs. For example, the ItemChange event of the Items object occurs when you call SetAlwaysAssignCategories, and the BeforeItemMove event of the Folder object occurs when you call SetAlwaysMoveToFolder.

Example

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code example assumes that the selected item in the explorer window is a mail item. The code example gets the conversation that the selected mail item is associated with, and enumerates each item in that conversation, displaying the subject of the item. The DemoConversation method calls the GetConversation method of the selected mail item to get the associated Conversation object. DemoConversation then calls the GetTable and GetRootItems methods of the Conversation object to get a Table object and SimpleItems collection, respectively. DemoConversation calls the recurrent method EnumerateConversation to enumerate and display the subject of each item in that conversation.

C# Copy code Copy code
void DemoConversation()
{
 object selectedItem =
 Application.ActiveExplorer().Selection[1];
 // This example uses only
 // MailItem. Other item types such as
 // MeetingItem and PostItem can participate
 // in the conversation.
 if (selectedItem is Outlook.MailItem)
 {
 // Cast selectedItem to MailItem.
 Outlook.MailItem mailItem =
 selectedItem as Outlook.MailItem;
 // Determine the store of the mail item.
 Outlook.Folder folder = mailItem.Parent
 as Outlook.Folder;
 Outlook.Store store = folder.Store;
 if (store.IsConversationEnabled == true)
 {
 // Obtain a Conversation object.
 Outlook.Conversation conv =
 mailItem.GetConversation();
 // Check for null Conversation.
 if (conv != null)
 {
 // Obtain Table that contains rows
 // for each item in the conversation.
 Outlook.Table table = conv.GetTable();
 Debug.WriteLine("Conversation Items Count: " +
 table.GetRowCount().ToString());
 Debug.WriteLine("Conversation Items from Table:");
 while (!table.EndOfTable)
 {
 Outlook.Row nextRow = table.GetNextRow();
 Debug.WriteLine(nextRow["Subject"]
 + " Modified: "
 + nextRow["LastModificationTime"]);
 }
 Debug.WriteLine("Conversation Items from Root:");
 // Obtain root items and enumerate the conversation.
 Outlook.SimpleItems simpleItems
 = conv.GetRootItems();
 foreach (object item in simpleItems)
 {
 // In this example, only enumerate MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (item is Outlook.MailItem)
 {
 Outlook.MailItem mail = item
 as Outlook.MailItem;
 Outlook.Folder inFolder =
 mail.Parent as Outlook.Folder;
 string msg = mail.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Call EnumerateConversation
 // to access child nodes of root items.
 EnumerateConversation(item, conv);
 }
 }
 }
 }
}

void EnumerateConversation(object item,
 Outlook.Conversation conversation)
{
 Outlook.SimpleItems items =
 conversation.GetChildren(item);
 if (items.Count > 0)
 {
 foreach (object myItem in items)
 {
 // In this example, only enumerate MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (myItem is Outlook.MailItem)
 {
 Outlook.MailItem mailItem =
 myItem as Outlook.MailItem;
 Outlook.Folder inFolder =
 mailItem.Parent as Outlook.Folder;
 string msg = mailItem.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Continue recursion.
 EnumerateConversation(myItem, conversation);
 }
 }
}

See also

Concepts

Outlook Object Model Reference

Other resources

Conversation Object Members


Conversation Members (Outlook)

 Copy code hover
[image]

Conversation Members (Outlook)
Send feedback

Represents a conversation that includes one or more items stored in one or more folders and stores.

Methods

Name | Description
ClearAlwaysAssignCategories | Removes all categories from all items in the conversation and stops the action of always assigning categories to items in the conversation.
GetAlwaysAssignCategories | Returns a String that indicates the category or categories that are assigned to all new items that arrive in the conversation.
GetAlwaysDelete | Returns a constant in the OlAlwaysDeleteConversation enumeration that indicates whether all new items that join the conversation are always moved to the Deleted Items folder in the specified delivery store.
GetAlwaysMoveToFolder | Returns a Folder object that indicates the folder in the specified delivery store to which new items that arrive in the conversation are always moved.
GetChildren | Returns a SimpleItems collection that contains all items under the specified conversation node.
GetParent | Returns the parent item of the specified node in the conversation.
GetRootItems | Returns a SimpleItems collection that contains all root items in the conversation.
GetTable | Returns a Table object that contains rows that represent all items in the conversation.
MarkAsRead | Marks all items in the conversation as read.
MarkAsUnread | Marks all items in the conversation as unread.
SetAlwaysAssignCategories | Applies one or more categories to all existing items and future items of the conversation.
SetAlwaysDelete | Specifies a setting for the specified delivery store that indicates whether all existing items and all new items that arrive in the conversation are always moved to the Deleted Items folder in the specified delivery store.
SetAlwaysMoveToFolder | Sets a Folder object that indicates the folder to which all existing conversation items and new items that arrive in the conversation are always moved.
StopAlwaysDelete | Stops the action of always moving conversation items in the specified store to the Deleted Items folder in that store.
StopAlwaysMoveToFolder | Stops the action of always moving conversation items in the specified store to a specific folder.

Properties

Name | Description
Application | Returns an Application object that represents the parent Microsoft Outlook application for the Conversation object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object. Read-only.
Parent | Returns the parent Object of the specified Conversation object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Conversation Properties (Outlook)

 Copy code hover
[image]

Conversation Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Microsoft Outlook application for the Conversation object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object. Read-only.
Parent | Returns the parent Object of the specified Conversation object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Conversation.Application Property (Outlook)

 Copy code hover
[image]

Conversation.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Microsoft Outlook application for the Conversation object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Application

expression A variable that represents a Conversation object.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.Class Property (Outlook)

 Copy code hover
[image]

Conversation.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that indicates the object's class. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Class

expression A variable that represents a Conversation object.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.ConversationID Property (Outlook)

 Copy code hover
[image]

Conversation.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a Conversation object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.Parent Property (Outlook)

 Copy code hover
[image]

Conversation.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified Conversation object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Parent

expression A variable that represents a Conversation object.

Remarks

The parent of a Conversation object is the first item in the conversation.

If all items in the conversation are deleted after the Conversation object has been obtained, the Parent property returns Null (Nothing in Visual Basic).

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.Session Property (Outlook)

 Copy code hover
[image]

Conversation.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Session

expression A variable that represents a Conversation object.

Remarks

This property returns Null (Nothing in Visual Basic) if there is no logged-on session.

You can use the Session property and the GetNamespace method interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation Methods (Outlook)

 Copy code hover
[image]

Conversation Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
ClearAlwaysAssignCategories | Removes all categories from all items in the conversation and stops the action of always assigning categories to items in the conversation.
GetAlwaysAssignCategories | Returns a String that indicates the category or categories that are assigned to all new items that arrive in the conversation.
GetAlwaysDelete | Returns a constant in the OlAlwaysDeleteConversation enumeration that indicates whether all new items that join the conversation are always moved to the Deleted Items folder in the specified delivery store.
GetAlwaysMoveToFolder | Returns a Folder object that indicates the folder in the specified delivery store to which new items that arrive in the conversation are always moved.
GetChildren | Returns a SimpleItems collection that contains all items under the specified conversation node.
GetParent | Returns the parent item of the specified node in the conversation.
GetRootItems | Returns a SimpleItems collection that contains all root items in the conversation.
GetTable | Returns a Table object that contains rows that represent all items in the conversation.
MarkAsRead | Marks all items in the conversation as read.
MarkAsUnread | Marks all items in the conversation as unread.
SetAlwaysAssignCategories | Applies one or more categories to all existing items and future items of the conversation.
SetAlwaysDelete | Specifies a setting for the specified delivery store that indicates whether all existing items and all new items that arrive in the conversation are always moved to the Deleted Items folder in the specified delivery store.
SetAlwaysMoveToFolder | Sets a Folder object that indicates the folder to which all existing conversation items and new items that arrive in the conversation are always moved.
StopAlwaysDelete | Stops the action of always moving conversation items in the specified store to the Deleted Items folder in that store.
StopAlwaysMoveToFolder | Stops the action of always moving conversation items in the specified store to a specific folder.


Conversation.ClearAlwaysAssignCategories Method (Outlook)

 Copy code hover
[image]

Conversation.ClearAlwaysAssignCategories Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes all categories from all items in the conversation and stops the action of always assigning categories to items in the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .ClearAlwaysAssignCategories(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | Specifies the store from which categories of items that belong to the conversation should be removed.

Remarks

If the store specified by the Store parameter represents a non-delivery store such as an archive .pst store, the category removal action will apply to items of the conversation in the default delivery store.

After you apply the ClearAlwaysAssignCategories method on a conversation, the GetAlwaysAssignCategories method will return Null (Nothing in Visual Basic) for that conversation. Categories on existing items are cleared, and no categories are assigned to new items in the conversation.

If the SetAlwaysAssignCategories method has not been applied to a conversation, ClearAlwaysAssignCategories does not remove any categories.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetAlwaysAssignCategories Method (Outlook)

 Copy code hover
[image]

Conversation.GetAlwaysAssignCategories Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the category or categories that are assigned to all new items that arrive in the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetAlwaysAssignCategories(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | Specifies the store to which categories of items that belong to the conversation should be returned.

Return Value

A String that contains one or more categories that are assigned to items in the conversation.

Remarks

Multiple categories are delimited by commas in the string of category names that this property returns. To convert the string of category names to an array of category names, use the Microsoft Visual Basic Split function.

If the store specified by the Store parameter represents a non-delivery store such as an archive .pst store, the method returns a string of categories that are applied to conversation items in the default delivery store.

If the SetAlwaysAssignCategories method has not been applied to a conversation, GetAlwaysAssignCategories returns Null (Nothing in Visual Basic).

To stop the action of always assigning categories, use the ClearAlwaysAssignCategories method. After the ClearAlwaysAssignCategories method has been called, GetAlwaysAssignCategories returns an empty string.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetAlwaysDelete Method (Outlook)

 Copy code hover
[image]

Conversation.GetAlwaysDelete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlAlwaysDeleteConversation enumeration that indicates whether all new items that join the conversation are always moved to the Deleted Items folder in the specified delivery store.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetAlwaysDelete(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | Specifies the store that holds the Deleted Items folder to which items of the conversation are moved.

Return Value

A constant from the OlAlwaysDeleteConversation enumeration that indicates whether all new items of the conversation are always moved to the Deleted Items folder of the specified delivey store.

Remarks

If the Store parameter specifies a non-delivery store such as an archive .pst store, the GetAlwaysDelete method returns a constant from OlAlwaysDeleteConversation that applies to conversation items in the default delivery store. Items on a non-delivery store are not moved to the Deleted Items folder for the default delivery store.

If GetAlwaysDelete returns olAlwaysDelete, items of the conversation are always moved to the Deleted Items folder for the store that contains the items. In a cross-store conversation, items are moved to the Deleted Items folder for the store that contains the items. When GetAlwaysDelete returns olAlwaysDelete, the GetAlwaysMoveToFolder method returns a folder object that represents the Deleted Items folder for the default store.

If GetAlwaysDelete returns olAlwaysDeleteUnsupported, the specified store does not support the action of always moving items to the Deleted Items folder of that store.

If GetAlwaysDelete returns olDoNotDelete, new items that arrive in the conversation are not moved to the Deleted Items folder on the specified delivery store, and existing conversation items in the Deleted Items folder are moved to the Inbox.

Example

The following Microsoft Visual Basic for Application (VBA) example shows how to verify the always-delete setting of the conversation of a selected mail item. The code example, DemoGetAlwaysDelete, verifies that conversations are enabled in the default store, obtains the conversation that involves the first mail item displayed in the Reading Pane if a conversation exists, uses GetAlwaysDelete to obtain the always-delete setting, and displays the setting.

VBA Copy code Copy code
Sub DemoGetAlwaysDelete()

 Dim oMail As Outlook.MailItem

 Dim oConv As Outlook.Conversation

 Dim oStore As Outlook.Store

 Dim intValue As Integer

 ' Get the item displayed in Reading Pane.

 Set oMail = ActiveExplorer.Selection(1)

 If Application.Session.DefaultStore.IsConversationEnabled Then

 Set oConv = oMail.GetConversation

 If Not (oConv Is Nothing) Then

 intValue = _

 oConv.GetAlwaysDelete(Application.session.DefaultStore)

 If intValue = _

 Outlook.OlAlwaysDeleteConversation.olAlwaysDelete Then

 Debug.Print "olAlwaysDelete"

 ElseIf intValue = _

 Outlook.OlAlwaysDeleteConversation.olAlwaysDeleteUnsupported Then

 Debug.Print "olAlwaysDeleteUnsupported"

 ElseIf intValue = _

 Outlook.OlAlwaysDeleteConversation.olDoNotDelete Then

 Debug.Print "olDoNotDelete"

 End If

 End If

 End If

End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetAlwaysMoveToFolder Method (Outlook)

 Copy code hover
[image]

Conversation.GetAlwaysMoveToFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object that indicates the folder in the specified delivery store to which new items that arrive in the conversation are always moved.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetAlwaysMoveToFolder(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | The store where the folder to which conversation items are moved resides.

Return Value

A Folder object in the specified store to which all new items that arrive in the conversation are always moved.

Remarks

If the Store parameter represents a non-delivery store such as an archive .pst store, the GetAlwaysMoveToFolder method returns a Folder object that applies to conversation items on the default delivery store.

If no folder, other than the Deleted Items folder, has been specified to always move conversation items into, the GetAlwaysMoveToFolder method returns Null (Nothing in Visual Basic).

Example

The following Microsoft Visual Basic for Application (VBA) example shows how to find the folder into which new items that arrive in the conversation of the first mail item displayed in the Reading Pane are always moved. The code example, DemoGetAlwaysMoveToFolder, verifies that conversations are enabled in the store for the selected mail item, obtains the conversation object for that mail item if a conversation exists, uses GetAlwaysMoveToFolder to obtain the folder, and displays the folder name.

VBA Copy code Copy code
Sub DemoGetAlwaysMoveToFolder()

 Dim oMail As Outlook.MailItem

 Dim oConv As Outlook.Conversation

 Dim oStore As Outlook.Store

 ' Get Item displayed in Reading Pane.

 Set oMail = ActiveExplorer.Selection(1)

 Set oStore = oMail.Parent.Store

 If oStore.IsConversationEnabled Then

 Set oConv = oMail.GetConversation

 If Not (oConv Is Nothing) Then

 Dim oFolder As Outlook.folder

 Set oFolder = _

 oConv.GetAlwaysMoveToFolder(oStore)

 If Not (oFolder Is Nothing) Then

 Debug.Print "MoveToFolder: " & oFolder.name

 Else

 Debug.Print "MoveToFolder action not set"

 End If

 End If

 End If

End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetChildren Method (Outlook)

 Copy code hover
[image]

Conversation.GetChildren Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SimpleItems collection that contains all items under the specified conversation node.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetChildren(Item)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | A conversation node that is part of a conversation.

Return Value

A SimpleItems collection that represents the set of child items in the conversation under the node specified by the Item parameter.

Remarks

The returned SimpleItems collection contains immediate child items of the conversation node specified by the Item parameter. If the specified node does not exist in the conversation, the GetChildren method returns an error.

If no child items exist under that node, the GetChildren method returns a SimpleItems collection with zero objects, in which case the Count property of the SimpleItems collection returns 0.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetParent Method (Outlook)

 Copy code hover
[image]

Conversation.GetParent Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent item of the specified node in the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetParent(Item)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | A conversation node that is part of a conversation.

Return Value

An Object that represents the parent conversation item of the node specified by the Item parameter.

Remarks

If the node specified by the Item parameter does not exist in the conversation, the GetParent method returns an error.

If the node specified by the Item parameter does not have a parent item in the conversation, the GetParent method returns Null (Nothing in Visual Basic).

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetRootItems Method (Outlook)

 Copy code hover
[image]

Conversation.GetRootItems Method (Outlook)
See also Send feedback

Returns a SimpleItems collection that contains all root items in the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetRootItems

expression A variable that represents a Conversation object.

Return Value

A SimpleItems collection that includes the root item or all root items of the conversation.

Remarks

A conversation can have one or more root items. For example, if the root item of the conversation has three child items and the root item is permanently deleted, all three child items become root items.

If all items are deleted from the conversation after the Conversation object has been obtained, GetRootItems returns a SimpleItems collection with zero objects. In this case, the Count property of the SimpleItems collection returns 0.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.GetTable Method (Outlook)

 Copy code hover
[image]

Conversation.GetTable Method (Outlook)
See also Send feedback

Returns a Table object that contains rows that represent all items in the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetTable

expression A variable that represents a Conversation object.

Return Value

A Table object that contains rows that represent all items in the conversation.

Remarks

The GetTable method returns a Table that has all items of the conversation as the rows. The default set of columns is shown in the following table.

Column | Property
1 | EntryID
2 | Subject
3 | CreationTime
4 | LastModificationTime
5 | MessageClass

By default, the rows in the table are sorted by the ConversationIndex property of the items.

To modify the default column set, use the Add, Remove, or RemoveAll methods of the Columns collection object.

The Table object returned by this GetTable method does not include items in the conversation that have been moved to the Deleted Items folder.

Example

The following Visual Basic for Applications (VBA) code example, DemoConversationTable, assumes that there is a mail item opened in an inspector. DemoConversationTable gets a Conversation object based on this mail item, and calls the GetTable method to get a Table of all the conversation items. To get specific information for each item in the conversation, which can span across stores, DemoConversationTable adds the store entry ID property, http://schemas.microsoft.com/mapi/proptag/0x0FFB0102, as a column to the table. As DemoConversationTable enumerates each item (represented by a row) in the table, it uses the store entry ID property that corresponds to that item to call the GetItemFromID method of the NameSpace object to obtain the item object. The example then displays the subject and the number of attachments for that item.

Note Note

Enumerating the conversation works only if the Outlook account is connected to a Microsoft Exchange Server that is running at least Microsoft Exchange Server 2010, or Outlook is running in cached mode against Microsoft Exchange Server 2007.
VBA Copy code Copy code
Sub DemoConversationTable()
 Dim oConv As Outlook.Conversation
 Dim oTable As Outlook.Table
 Dim oRow As Outlook.Row
 Dim oMail As Outlook.MailItem
 Dim oItem As Outlook.MailItem
 Const PR_STORE_ENTRYID As String = _
 "http://schemas.microsoft.com/mapi/proptag/0x0FFB0102"

 On Error Resume Next
 ' Obtain the current item for the active inspector.
 Set oMail = Application.ActiveInspector.CurrentItem

 If Not (oMail Is Nothing) Then
 ' Obtain the Conversation object.
 Set oConv = oMail.GetConversation
 If Not (oConv Is Nothing) Then
 Set oTable = oConv.GetTable
 oTable.Columns.Add (PR_STORE_ENTRYID)
 Do Until oTable.EndOfTable
 Set oRow = oTable.GetNextRow
 ' Use EntryID and StoreID to open the item.
 Set oItem = Application.session.GetItemFromID( _
 oRow("EntryID"), _
 oRow.BinaryToString(PR_STORE_ENTRYID))
 Debug.Print oItem.Subject, _
 "Attachments.Count=" & oItem.Attachments.count
 Loop
 End If
 End If
End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.MarkAsRead Method (Outlook)

 Copy code hover
[image]

Conversation.MarkAsRead Method (Outlook)
See also Send feedback

Marks all items in the conversation as read.

Version Information

Version Added: Outlook 2010

Syntax

expression .MarkAsRead

expression A variable that represents a Conversation object.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.MarkAsUnread Method (Outlook)

 Copy code hover
[image]

Conversation.MarkAsUnread Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks all items in the conversation as unread.

Version Information

Version Added: Outlook 2010

Syntax

expression .MarkAsUnread

expression A variable that represents a Conversation object.

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.SetAlwaysAssignCategories Method (Outlook)

 Copy code hover
[image]

Conversation.SetAlwaysAssignCategories Method (Outlook)
See also Send feedback

Applies one or more categories to all existing items and future items of the conversation.

Version Information

Version Added: Outlook 2010

Syntax

expression .SetAlwaysAssignCategories(Categories, Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Categories | Required | String | A comma-delimited string of one or more category names that are always assigned to all items in the conversation.
Store | Required | Store | The store in which items of the conversation should always be assigned the categories specified by the Categories parameter.

Remarks

If the store specified by the Store parameter represents a non-delivery store such as an archive .pst store, the method returns a string of categories that are applied to conversation items in the default delivery store.

The ItemChange event of the Items object occurs when you call the SetAlwaysAssignCategories method on a conversation.

To determine existing master categories for the current user, examine the Categories property of the Store object that is specified by the Store parameter. If one or more categories specified by the Categories parameter do not exist in the master categories collection, the categories will be assigned to the conversation but will not be added to the master categories collection.

To determine the existing categories that are always assigned to items of the conversation in the specified store, use the GetAlwaysAssignCategories method.

If SetAlwaysAssignCategories is called more than once, the result is cumulative. For example, if you call SetAlwaysAssignCategories specifying the category "Important" and then call SetAlwaysAssignCategories again specifying the categories "Business" and "Social", the categories that are always assigned are "Important", "Business", and "Social".

To stop the action of always assigning categories, use the ClearAlwaysAssignCategories method. After the ClearAlwaysAssignCategories method has been called, GetAlwaysAssignCategories returns an empty string.

The SetAlwaysAssignToCategories method ignores any category names that are empty strings. For example, if the Categories parameter is set to the string "Work,,Play", "Work" and "Play" are assigned to the conversation and the empty string category is ignored.

Example

The following Visual Basic for Applications (VBA) example shows how to assign categories to all existing and new items that arrive in the conversation of a specific mail item. The code example, DemoSetAlwaysAssignCategories, chooses the first mail item displayed in the Reading Pane as the specific mail item. DemoSetAlwaysAssignCategories verifies that conversations are enabled in the store for the selected mail item, obtains the conversation object for that mail item if a conversation exists, and uses SetAlwaysAssignToCategories to set the two categories "Best Practices" and "OOM" to all existing items and future items of that conversation.

VBA Copy code Copy code
Sub DemoSetAlwaysAssignCategories()
 Dim oMail As Outlook.MailItem
 Dim oConv As Outlook.Conversation
 Dim oStore As Outlook.Store
 ' Get the item displayed in the Reading Pane.
 Set oMail = ActiveExplorer.Selection(1)
 Set oStore = oMail.Parent.Store
 If oStore.IsConversationEnabled Then
 Set oConv = oMail.GetConversation
 If Not (oConv Is Nothing) Then
 Dim oFolder As Outlook.folder
 oConv.SetAlwaysAssignCategories "Best Practices; OOM", oStore
 End If
 End If
End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.SetAlwaysDelete Method (Outlook)

 Copy code hover
[image]

Conversation.SetAlwaysDelete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Specifies a setting for the specified delivery store that indicates whether all existing items and all new items that arrive in the conversation are always moved to the Deleted Items folder in the specified delivery store.

Version Information

Version Added: Outlook 2010

Syntax

expression .SetAlwaysDelete(AlwaysDelete, Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
AlwaysDelete | Required | OlAlwaysDeleteConversation | A constant that indicates whether all existing and new items that arrive in the conversation are always moved to the Deleted Folder of the store specified by the Store parameter.
Store | Required | Store | Specifies the store that contains the Deleted Items folder to which existing and new items of the conversation are to be moved.

Remarks

The SetAlwaysDelete method operates on conversation items in the delivery store specified by the Store parameter. If the store specified by the Store parameter represents a non-delivery store such as an archive .pst store, the action is applied to conversation items in the default delivery store.

If the AlwaysDelete parameter is olAlwaysDelete, conversation items are moved to the Deleted Items folder for the specfied store. In this case, the items are not permanently deleted, unless the user has specified a separate option to permanently delete items when Microsoft Outlook shuts down.

If SetAlwaysDelete returns olDoNotDelete, existing conversation items and new items that arrive in the conversation are not moved to the Deleted Items folder in the specified delivery store, and existing conversation items in the Deleted Items folder are moved to the Inbox.

Example

The following Visual Basic for Applications (VBA) example shows how to set the always-delete setting for the conversation of a specific mail item. The code example, DemoSetAlwaysDelete, chooses the first mail item displayed in the Reading Pane as the specific mail item. DemoSetAlwaysDelete verifies that conversations are enabled in the store for the mail item, obtains the conversation that involves that mail item if a conversation exists, and uses SetAlwaysDelete to always move existing and new items for that conversation to the Deleted Items folder in the same store.

VBA Copy code Copy code
Sub DemoSetAlwaysDelete()
 Dim oMail As Outlook.MailItem
 Dim oConv As Outlook.Conversation
 Dim oStore As Outlook.Store

 ' Get the item displayed in the Reading Pane.
 Set oMail = ActiveExplorer.Selection(1)
 Set oStore = oMail.Parent.Store
 If oStore.IsConversationEnabled Then
 Set oConv = oMail.GetConversation
 If Not (oConv Is Nothing) Then
 oConv.SetAlwaysDelete _
 olAlwaysDelete, oStore
 End If
 End If
End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.SetAlwaysMoveToFolder Method (Outlook)

 Copy code hover
[image]

Conversation.SetAlwaysMoveToFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets a Folder object that indicates the folder to which all existing conversation items and new items that arrive in the conversation are always moved.

Version Information

Version Added: Outlook 2010

Syntax

expression .SetAlwaysMoveToFolder(MoveToFolder, Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
MoveToFolder | Required | Folder | Specifies the folder to which all existing items and new items that arrive in the conversation are always moved.
Store | Required | Store | Specifies the store that contains the folder to which items of the conversation are moved.

Remarks

The SetAlwaysMoveToFolder method operates on conversation items in the delivery store specified by the Store parameter. If the Store parameter represents a non-delivery store such as an archive .pst store, the move action will apply to conversation items in the default delivery store.

If the MoveToFolder parameter specifies an invalid folder that does not exist, has been moved, or is read-only, Outlook will raise an error.

To stop the always-move-to-folder action for conversations items in a store, call the StopAlwaysMoveToFolder method.

Note Note

Setting the Deleted Items folder as the MoveToFolder parameter in SetAlwaysMoveToFolder is not equivalent to calling SetAlwaysDelete on the same store and conversation. Setting the MoveToFolder parameter to the Deleted Items folder results in the GetAlwaysDelete method returning the value olDoNotDelete.

The BeforeItemMove event of the Folder object occurs when you call SetAlwaysMoveToFolder.

Example

The following Visual Basic for Applications (VBA) example shows how to set the folder to which existing conversation items and new items that arrive in the conversation of a specific mail item are always moved. The code example, DemoSetAlwaysMoveToFolder, chooses the first mail item displayed in the Reading Pane as the specific mail item, and the folder named "1-Reference" under the Inbox folder as the folder to move the conversation items to. DemoSetAlwaysMoveToFolder verifies that conversations are enabled in the store for the selected mail item, obtains the conversation object for that mail item if a conversation exists, and uses SetAlwaysMoveToFolder to always move all existing conversation items and new items that arrive in the conversation to the specified folder.

VBA Copy code Copy code
Sub DemoSetAlwaysMoveToFolder()
 Dim oMail As Outlook.MailItem
 Dim oConv As Outlook.Conversation
 Dim oStore As Outlook.Store
 Dim oFolder As Outlook.Folder

 ' Obtain a reference to the folder where conversation items will be moved.
 Set oFolder = _
 Application.Session.GetDefaultFolder(olFolderInbox).Folders("1-Reference")
 ' Get the Item displayed in the Reading Pane.
 Set oMail = ActiveExplorer.Selection(1)
 Set oStore = oFolder.Store
 If oStore.IsConversationEnabled Then
 Set oConv = oMail.GetConversation
 If Not (oConv Is Nothing) Then
 oConv.SetAlwaysMoveToFolder oFolder, oStore
 End If
 End If
End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.StopAlwaysDelete Method (Outlook)

 Copy code hover
[image]

Conversation.StopAlwaysDelete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Stops the action of always moving conversation items in the specified store to the Deleted Items folder in that store.

Version Information

Version Added: Outlook 2010

Syntax

expression .StopAlwaysDelete(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | Specifies the store to which the stop-always-delete action applies.

Remarks

If the always-delete action has not been turned on, StopAlwaysDelete does not carry out any action.

If the always-delete action has been turned on (by calling the SetAlwaysDelete method, StopAlwaysDelete moves existing conversation items in the Deleted Items folder to the Inbox.

After calling the StopAlwaysDelete method for a conversation in a store, calling the GetAlwaysDelete method on that conversation and store returns the constant olDoNotDelete.

If the store specified by the Store parameter represents a non-delivery store such as an archive .pst store, the stop-always-delete action is applied to conversation items in the default delivery store.

Calling this method on a conversation that is already in the Deleted Items folder in the specified store returns an error.

Example

The following Visual Basic for Applications (VBA) example shows how to stop the always-delete action for the conversation of a specific mail item. The code example, DemoStopAlwaysDelete, chooses the first mail item displayed in the Reading Pane as the specific mail item. DemoStopAlwaysDelete verifies that conversations are enabled on the store for the mail item, obtains the conversation that involves that mail item if a conversation exists, and uses SetAlwaysDelete to stop the always-delete action for that conversation on that store.

VBA Copy code Copy code
Sub DemoStopAlwaysDelete()
 Dim oMail As Outlook.MailItem
 Dim oConv As Outlook.Conversation
 Dim oStore As Outlook.Store

 ' Get the item displayed in the Reading Pane.
 Set oMail = ActiveExplorer.Selection(1)
 Set oStore = oMail.Parent.Store
 If oStore.IsConversationEnabled Then
 Set oConv = oMail.GetConversation
 If Not (oConv Is Nothing) Then
 oConv.StopAlwaysDelete oStore
 End If
 End If
End Sub

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


Conversation.StopAlwaysMoveToFolder Method (Outlook)

 Copy code hover
[image]

Conversation.StopAlwaysMoveToFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Stops the action of always moving conversation items in the specified store to a specific folder.

Version Information

Version Added: Outlook 2010

Syntax

expression .StopAlwaysMoveToFolder(Store)

expression A variable that represents a Conversation object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | The store where the conversation items to be cleaned up reside.

Remarks

If the always-move action has not been turned on, StopAlwaysMoveToFolder does not carry out any action.

If the Store parameter represents a non-delivery store such as an archive .pst store, the stop-always-move action will apply to conversation items in the default delivery store.

After you call the StopAlwaysMoveToFolder method, calling the GetAlwaysMoveToFolder method returns Null (Nothing in Visual Basic).

See also

Concepts

Conversation Object

Other resources

Conversation Object Members


ConversationHeader Object (Outlook)

 Copy code hover
[image]

ConversationHeader Object (Outlook)
See also Send feedback

Represents a Microsoft Outlook conversation header in a Conversation view.

Version Information

Version Added: Outlook 2010

Remarks

In Outlook, a conversation groups messages that share the same subject and belong to the same thread. A conversation can also include branches, such as when a message gets two or more responses and discussions grow independently from each response. The Conversation view relates all items in the same conversation across folders and stores. A conversation header can be an item or a group header in one of the following forms:

  • An item in a thread that contains only a single item.

  • A group header for a conversation that contains multiple items.

  • The first item in a conversation that contains a single thread.

  • The first item in a split conversation.

See also

Concepts

Outlook Object Model Reference

Other resources

ConversationHeader Object Members


ConversationHeader Members (Outlook)

 Copy code hover
[image]

ConversationHeader Members (Outlook)
Send feedback

Represents a Microsoft Outlook conversation header in a Conversation view.

Methods

Name | Description
GetConversation | Obtains a Conversation object that represents the conversation to which this conversation header belongs.
GetItems | Obtains a SimpleItems collection that contains all of the items in the conversation that reside in the same folder as the selected conversation header.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the ConversationHeader object. Read-only.
Class | Returns an OlObjectClass constant that indicates the class of the object. Read-only.
ConversationID | Returns a String that uniquely identifies the Conversation object to which this conversation header belongs. Read-only.
ConversationTopic | Returns a String value that represents the topic of the conversation thread of the conversation header. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ConversationHeader Properties (Outlook)

 Copy code hover
[image]

ConversationHeader Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the ConversationHeader object. Read-only.
Class | Returns an OlObjectClass constant that indicates the class of the object. Read-only.
ConversationID | Returns a String that uniquely identifies the Conversation object to which this conversation header belongs. Read-only.
ConversationTopic | Returns a String value that represents the topic of the conversation thread of the conversation header. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ConversationHeader.Application Property (Outlook)

 Copy code hover
[image]

ConversationHeader.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the ConversationHeader object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Application

expression A variable that represents a ConversationHeader object.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.Class Property (Outlook)

 Copy code hover
[image]

ConversationHeader.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that indicates the class of the object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Class

expression A variable that represents a ConversationHeader object.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.ConversationID Property (Outlook)

 Copy code hover
[image]

ConversationHeader.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies the Conversation object to which this conversation header belongs. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a ConversationHeader object.

Remarks

This property associates the conversation header with other items in the same conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.ConversationTopic Property (Outlook)

 Copy code hover
[image]

ConversationHeader.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the topic of the conversation thread of the conversation header. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationTopic

expression A variable that represents a ConversationHeader object.

Remarks

Corresponds to the MAPI property PidTagConversationTopic.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.Parent Property (Outlook)

 Copy code hover
[image]

ConversationHeader.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Parent

expression A variable that represents a ConversationHeader object.

Remarks

The parent of the ConversationHeader object returns a Selection object.

The returned Selection object contains only ConversationHeader objects. Getting the Parent property is equivalent to calling the Selection.GetSelection method with the olConversationHeaders argument.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.Session Property (Outlook)

 Copy code hover
[image]

ConversationHeader.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Session

expression A variable that represents a ConversationHeader object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

You can use the Session property and the GetNamespace method interchangeably to obtain the NameSpace object for the current session.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader Methods (Outlook)

 Copy code hover
[image]

ConversationHeader Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetConversation | Obtains a Conversation object that represents the conversation to which this conversation header belongs.
GetItems | Obtains a SimpleItems collection that contains all of the items in the conversation that reside in the same folder as the selected conversation header.


ConversationHeader.GetConversation Method (Outlook)

 Copy code hover
[image]

ConversationHeader.GetConversation Method (Outlook)
See also Send feedback

Obtains a Conversation object that represents the conversation to which this conversation header belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a ConversationHeader object.

Return Value

A Conversation object that represents the conversation to which this conversation header belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations are disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange that is earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

ConversationHeader Object

Other resources

ConversationHeader Object Members


ConversationHeader.GetItems Method (Outlook)

 Copy code hover
[image]

ConversationHeader.GetItems Method (Outlook)
See also Send feedback

Obtains a SimpleItems collection that contains all of the items in the conversation that reside in the same folder as the selected conversation header.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetItems

expression A variable that represents a ConversationHeader object.

Return Value

A SimpleItems collection of items that belong to the same conversation and reside in the same folder as the conversation header.

Remarks

The SimpleItems collection only contains conversation items in the folder that contains the conversation header. The SimpleItems collection does not return cross-folder conversation items. If you must access cross-folder content, use the Conversation object.

If no conversation items exist in the same folder as the conversation header, GetItems returns a SimpleItems collection with the SimpleItems.Count property equal to 0.

See also

Concepts

How to: Obtain and Enumerate Selected Conversations
ConversationHeader Object

Other resources

ConversationHeader Object Members


DistListItem Object (Outlook)

 Copy code hover
[image]

DistListItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a distribution list in a Contacts folder.

Remarks

A distribution list can contain multiple recipients and is used to send messages to everyone in the list.

Use the CreateItem method to create a DistListItem object that represents a new distribution list.

Use Items(index), where index is the index number of an item in a contacts folder or a value used to match the default property of an item in the folder, to return a single DistListItem object from a contacts folder (that is, a folder whose default item type is olContactItem).

Example

The following Microsoft Visual Basic for Applications (VBA) example creates and displays a new distribution list.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olDistributionListItem)

myItem.Display

The following Visual Basic for Applications example sets the current folder as the contacts folder and displays an existing distribution list named Project Team in the folder.

VBA Copy code Copy code
Set myNamespace = Application.GetNamespace("MAPI")

Set myFolder = myNamespace.GetDefaultFolder(olFolderContacts)

myFolder.Display

Set myItem = myFolder.Items("Project Team")

myItem.Display

See also

Concepts

Outlook Object Model Reference

Other resources

DistListItem Object Members


DistListItem Members (Outlook)

 Copy code hover
[image]

DistListItem Members (Outlook)
Send feedback

Represents a distribution list in a Contacts folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
AddMember | Adds a new member to the specified distribution list. The distribution list contains Recipient objects that represent valid e-mail addresses.
AddMembers | Adds new members to a distribution list.
ClearTaskFlag | Clears the DistListItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetMember | Returns a Recipient object representing a member in a distribution list.
MarkAsTask | Marks a DistListItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
RemoveMember | Removes an individual member from a given distribution list.
RemoveMembers | Removes members from a distribution list.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the DistListItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DLName | Returns or sets a String representing the display name of a distribution list. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the DistListItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MemberCount | Returns a Long indicating the number of members in a distribution list. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DistListItem object. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this DistListItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this DistListItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this DistListItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the DistListItem object. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the DistListItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


DistListItem Properties (Outlook)

 Copy code hover
[image]

DistListItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the DistListItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DLName | Returns or sets a String representing the display name of a distribution list. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the DistListItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MemberCount | Returns a Long indicating the number of members in a distribution list. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DistListItem object. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this DistListItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this DistListItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this DistListItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the DistListItem object. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the DistListItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


DistListItem.Actions Property (Outlook)

 Copy code hover
[image]

DistListItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Application Property (Outlook)

 Copy code hover
[image]

DistListItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Attachments Property (Outlook)

 Copy code hover
[image]

DistListItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

DistListItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a DistListItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its DistListItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

DistListItem.BillingInformation Property (Outlook)
See also Send feedback

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a DistListItem object.

Remarks

This is a free-form text field.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Body Property (Outlook)

 Copy code hover
[image]

DistListItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Categories Property (Outlook)

 Copy code hover
[image]

DistListItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a DistListItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Class Property (Outlook)

 Copy code hover
[image]

DistListItem.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Companies Property (Outlook)

 Copy code hover
[image]

DistListItem.Companies Property (Outlook)
See also Send feedback

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a DistListItem object.

Remarks

This is a free-form text field.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Conflicts Property (Outlook)

 Copy code hover
[image]

DistListItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ConversationID Property (Outlook)

 Copy code hover
[image]

DistListItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the DistListItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a DistListItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the DistListItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

DistListItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

DistListItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.CreationTime Property (Outlook)

 Copy code hover
[image]

DistListItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.DLName Property (Outlook)

 Copy code hover
[image]

DistListItem.DLName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the display name of a distribution list. Read/write.

Syntax

expression .DLName

expression A variable that represents a DistListItem object.

Example

This Microsoft Visual Basic for Applications (VBA) example creates a new distribution list and then prompts the user for a name.

VBA Copy code Copy code
Sub CreateDL()

 Dim myDistList As Outlook.DistListItem

 Set myDistList = Application.CreateItem(olDistributionListItem)

 myDistList.DLName = InputBox("Type the name of the new distribution list.")

 myDistList.Save

 myDistList.Display

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.DownloadState Property (Outlook)

 Copy code hover
[image]

DistListItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a DistListItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.EntryID Property (Outlook)

 Copy code hover
[image]

DistListItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.FormDescription Property (Outlook)

 Copy code hover
[image]

DistListItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.GetInspector Property (Outlook)

 Copy code hover
[image]

DistListItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a DistListItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Importance Property (Outlook)

 Copy code hover
[image]

DistListItem.Importance Property (Outlook)
See also Send feedback

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.IsConflict Property (Outlook)

 Copy code hover
[image]

DistListItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a DistListItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.IsMarkedAsTask Property (Outlook)

 Copy code hover
[image]

DistListItem.IsMarkedAsTask Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the DistListItem is marked as a task. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsMarkedAsTask

expression An expression that returns a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

DistListItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a DistListItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

DistListItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

DistListItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a DistListItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.MemberCount Property (Outlook)

 Copy code hover
[image]

DistListItem.MemberCount Property (Outlook)
See also Send feedback

Returns a Long indicating the number of members in a distribution list. Read-only.

Syntax

expression .MemberCount

expression A variable that represents a DistListItem object.

Remarks

The value returned represents all members of the distribution list, including member distribution lists. Each member distribution list is counted as a single member. That is, MemberCount is not an aggregate sum of the recipients in the distribution list plus recipients in member distribution lists. For example, if a distribution list contains 10 recipients plus one distribution list containing 15 recipients, MemberCount returns 11.

Example

This Microsoft Visual Basic for Applications example steps through the default Contacts folder, and if it finds a distribution list with more than 20 members it displays the item.

VBA Copy code Copy code
Sub CheckDLs()

 Dim myOlFolder As Outlook.Folder

 Dim myOlItems As Outlook.Items

 Dim myOlDistList As Outlook.DistListItem

 Dim x as Integer

 Set myOlFolder = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts)

 Set myOlItems = myOlFolder.Items

 For x = 1 To myOlItems.Count

 If TypeName(myOlItems.Item(x)) = "DistListItem" Then

 Set myOlDistList = myOlItems.Item(x)

 If myOlDistList.MemberCount > 20 Then

 MsgBox myOlDistList.DLName & " has more than 20 members."

 myOlDistList.Display

 End If

 End If

 Next x

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.MessageClass Property (Outlook)

 Copy code hover
[image]

DistListItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

DistListItem Object
Item Types and Message Classes

Other resources

DistListItem Object Members


DistListItem.Mileage Property (Outlook)

 Copy code hover
[image]

DistListItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a DistListItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.NoAging Property (Outlook)

 Copy code hover
[image]

DistListItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

DistListItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

DistListItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Parent Property (Outlook)

 Copy code hover
[image]

DistListItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

DistListItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DistListItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

DistListItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a DistListItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

DistListItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents a DistListItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

DistListItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

DistListItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents a DistListItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

DistListItem.ReminderTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.RTFBody Property (Outlook)

 Copy code hover
[image]

DistListItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a DistListItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Saved Property (Outlook)

 Copy code hover
[image]

DistListItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

DistListItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Session Property (Outlook)

 Copy code hover
[image]

DistListItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a DistListItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Size Property (Outlook)

 Copy code hover
[image]

DistListItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Subject Property (Outlook)

 Copy code hover
[image]

DistListItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a DistListItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.TaskCompletedDate Property (Outlook)

 Copy code hover
[image]

DistListItem.TaskCompletedDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the completion date of the task for this DistListItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskCompletedDate

expression An expression that returns a DistListItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.TaskDueDate Property (Outlook)

 Copy code hover
[image]

DistListItem.TaskDueDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the due date of the task for this DistListItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskDueDate

expression An expression that returns a DistListItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.TaskStartDate Property (Outlook)

 Copy code hover
[image]

DistListItem.TaskStartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date of the task for this DistListItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskStartDate

expression An expression that returns a DistListItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.TaskSubject Property (Outlook)

 Copy code hover
[image]

DistListItem.TaskSubject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the subject of the task for the DistListItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskSubject

expression An expression that returns a DistListItem object.

Remarks

This property returns the value of the Subject property if the IsMarkedAsTask property is set to False.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

DistListItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the ordinal value of the task for the DistListItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a DistListItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar. The value used in this property does not have any relation to the values of the TaskStartDate, TaskDueDate, or TaskCompletedDate properties.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.UnRead Property (Outlook)

 Copy code hover
[image]

DistListItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.UserProperties Property (Outlook)

 Copy code hover
[image]

DistListItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem Methods (Outlook)

 Copy code hover
[image]

DistListItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddMember | Adds a new member to the specified distribution list. The distribution list contains Recipient objects that represent valid e-mail addresses.
AddMembers | Adds new members to a distribution list.
ClearTaskFlag | Clears the DistListItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetMember | Returns a Recipient object representing a member in a distribution list.
MarkAsTask | Marks a DistListItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
RemoveMember | Removes an individual member from a given distribution list.
RemoveMembers | Removes members from a distribution list.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


DistListItem.AddMember Method (Outlook)

 Copy code hover
[image]

DistListItem.AddMember Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a new member to the specified distribution list. The distribution list contains Recipient objects that represent valid e-mail addresses.

Syntax

expression .AddMember(Recipient)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Recipient | Required | Recipient | The recipient to be added to the list.

Remarks

Use the AddMembers method to add multiple members to a given distribution list.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new DistributionList object and adds a recipient to it. If the specified recipient is not valid, the AddMember method will fail. To run this example, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub AddNewMember()

 'Adds a member to a new distribution list

 Dim objItem As Outlook.DistListItem

 Dim objMail As Outlook.MailItem

 Dim objRcpnt As Outlook.Recipient

 Set objMail = Application.CreateItem(olMailItem)

 Set objItem = Application.CreateItem(olDistributionListItem)

 'Create recipient for distlist

 Set objRcpnt = Application.Session.CreateRecipient("Dan Wilson")

 objRcpnt.Resolve

 objItem.AddMember objRcpnt

 'Add note to list and display

 objItem.DLName = "Northwest Sales Manager"

 objItem.Body = "Regional Sales Manager - NorthWest"

 objItem.Save

 objItem.Display

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.AddMembers Method (Outlook)

 Copy code hover
[image]

DistListItem.AddMembers Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds new members to a distribution list.

Syntax

expression .AddMembers(Recipients)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Recipients | Required | Recipients | The members to be added to the distribution list.

Example

This Microsoft Visual Basic for Applications (VBA) example creates a new distribution list and adds the current user and 'Dan Wilson' to the list. If the specified recipient is not valid, the AddMember method will fail. Therefore, to run this example, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub AddNewMembers()

 Dim myNameSpace As Outlook.NameSpace

 Dim myDistList As Outlook.DistListItem

 Dim myTempItem As Outlook.MailItem

 Dim myRecipients As Outlook.Recipients

 Set myNameSpace = Application.GetNamespace("MAPI

 Set myDistList = Application.CreateItem(olDistributionListItem

 Set myTempItem = Application.CreateItem(olMailItem

 Set myRecipients = myTempItem.Recipients

 myDistList.DLName = _

 InputBox("Enter the name of the new distribution list

 myRecipients.Add myNameSpace.CurrentUser.Name

 myRecipients.Add "Dan Wilson

 myRecipients.ResolveAll

 myDistList.AddMembers myRecipients

 myDistList.Save

 myDistList.Display

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ClearTaskFlag Method (Outlook)

 Copy code hover
[image]

DistListItem.ClearTaskFlag Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the DistListItem object as a task.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearTaskFlag

expression An expression that returns a DistListItem object.

Remarks

Calling this method sets the IsMarkedAsTask property to False.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Close Method (Outlook)

 Copy code hover
[image]

DistListItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Copy Method (Outlook)

 Copy code hover
[image]

DistListItem.Copy Method (Outlook)
See also Send feedback

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a DistListItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Delete Method (Outlook)

 Copy code hover
[image]

DistListItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a DistListItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

DistListItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

DistListItemMembers


DistListItem.Display Method (Outlook)

 Copy code hover
[image]

DistListItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.GetConversation Method (Outlook)

 Copy code hover
[image]

DistListItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a DistListItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.GetMember Method (Outlook)

 Copy code hover
[image]

DistListItem.GetMember Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipient object representing a member in a distribution list.

Syntax

expression .GetMember(Index)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The index number of the member to be retrieved.

Return Value

A Recipient object representing the specified member.

Example

This Microsoft Visual Basic for Applications (VBA) example locates every distribution list in the default Contacts folder and determines whether the list contains the current user.

VBA Copy code Copy code
Sub DisplayYourDLNames()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myDistList As Outlook.DistListItem

 Dim myFolderItems As Outlook.Items

 Dim x As Integer

 Dim y As Integer

 Dim iCount As Integer

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderContacts)

 Set myFolderItems = myFolder.Items

 iCount = myFolderItems.Count

 For x = 1 To iCount

 If TypeName(myFolderItems.Item(x)) = "DistListItem" Then

 Set myDistList = myFolderItems.Item(x)

 For y = 1 To myDistList.MemberCount

 If myDistList.GetMember(y).Name = myNameSpace.CurrentUser.Name Then

 MsgBox "Your are a member of " & myDistList.DLName

 End If

 Next y

 End If

 Next x

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.MarkAsTask Method (Outlook)

 Copy code hover
[image]

DistListItem.MarkAsTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks a DistListItem object as a task and assigns a task interval for the object.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask(MarkInterval)

expression An expression that returns a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
MarkInterval | Required | OlMarkInterval | The task interval for the DistListItem.

Remarks

Calling this method sets the value of several other properties, depending on the value provided in MarkInterval. For more information about the properties set by specifying MarkInterval, see OlMarkInterval Enumeration.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Move Method (Outlook)

 Copy code hover
[image]

DistListItem.Move Method (Outlook)
See also Send feedback

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.PrintOut Method (Outlook)

 Copy code hover
[image]

DistListItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.RemoveMember Method (Outlook)

 Copy code hover
[image]

DistListItem.RemoveMember Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an individual member from a given distribution list.

Syntax

expression .RemoveMember(Recipient)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Recipient | Required | Recipient | The Recipient to be removed from the distribution list.

Example

The following Microsoft Visual Basic for Applications (VBA) example removes a member from the distribution list called Group List. The RemoveMember method will fail if the specified recipient is not valid. Before running the example, create or make sure a distribution list called 'Group List' exists in your default Contacts folder.

VBA Copy code Copy code
Sub RemoveRec()

 'Remove a recipient from the list, and displays new list.

 Dim objDstList As Outlook.DistListItem

 Dim objName As Outlook.NameSpace

 Dim objRcpnt As Outlook.Recipient

 Dim objMail As Outlook.MailItem

 Set objName = Application.GetNamespace("MAPI")

 Set objDstList = objName.GetDefaultFolder(olFolderContacts).Items("Group List")

 Set objMail = Application.CreateItem(olMailItem)

 Set objRcpnt = objMail.Recipients.Add(Name:="someone@example.com")

 objRcpnt.Resolve

 objDstList.RemoveMember Recipient:=objRcpnt

 objDstList.Display

 objDstList.Body = "Last Modified: " & Now

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.RemoveMembers Method (Outlook)

 Copy code hover
[image]

DistListItem.RemoveMembers Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes members from a distribution list.

Syntax

expression .RemoveMembers(Recipients)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Recipients | Required | Recipients | The members to be removed from the distribution list.

Example

The following Microsoft Visual Basic for Applications (VBA) example removes two members from the distribution list called Group List. The RemoveMembers method will fail if the specified recipients are not valid. Before running the example, create or make sure a distribution list called 'Group List' exists in your default Contacts folder.

VBA Copy code Copy code
Sub RemoveRecs()

 'Remove a recipient from the list and displays new list.

 Dim objDstList As Outlook.DistListItem

 Dim objName As Outlook.NameSpace

 Dim objRcpnt As Outlook.Recipient

 Dim objRcpnt2 As Outlook.Recipient

 Dim objMail As Outlook.MailItem

 Dim objRcpnts As Outlook.Recipients

 Set objName = Application.GetNamespace("MAPI")

 Set objDstList = objName.GetDefaultFolder(olFolderContacts).Items("Group List")

 Set objMail = Application.CreateItem(olMailItem)

 Set objRcpnts = objMail.Recipients

 Set objRcpnt = objRcpnts.Add(Name:="someone@example.com")

 Set objRcpnt2 = objRcpnts.Add(Name:="someone@example.org")

 objRcpnts.ResolveAll

 objDstList.RemoveMembers objRcpnts

 objDstList.Display

 objDstList.Body = "Last Modified: " & Now

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Save Method (Outlook)

 Copy code hover
[image]

DistListItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a DistListItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.SaveAs Method (Outlook)

 Copy code hover
[image]

DistListItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.DistListItem

 Set MyItem = Application.CreateItem(olDistributionListItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

DistListItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a DistListItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new distribution list item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub Appointment()

 'Creates an distribution list item to access ShowCategoriesDialog

 Dim olDistListItem As Outlook.DistListItem

 'Create distribution list item

 Set olDistListItem = Application.CreateItem(olDistributionListItem)

 'Display the item

 olDistListItem.Display

 'Display the Show categories dialog

 olDistListItem.ShowCategoriesDialog

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem Events (Outlook)

 Copy code hover
[image]

DistListItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


DistListItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

DistListItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a DistListItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

DistListItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

DistListItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

DistListItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment )

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the DistListItem to be saved.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

DistListItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a DistListItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Close Event (Outlook)

 Copy code hover
[image]

DistListItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Closemethod to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.CustomAction Event (Outlook)

 Copy code hover
[image]

DistListItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

DistListItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Forward Event (Outlook)

 Copy code hover
[image]

DistListItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Open Event (Outlook)

 Copy code hover
[image]

DistListItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

DistListItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Read Event (Outlook)

 Copy code hover
[image]

DistListItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a DistListItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

DistListItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Reply Event (Outlook)

 Copy code hover
[image]

DistListItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

DistListItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Send Event (Outlook)

 Copy code hover
[image]

DistListItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Unload Event (Outlook)

 Copy code hover
[image]

DistListItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a DistListItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DistListItem.Write Event (Outlook)

 Copy code hover
[image]

DistListItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a DistListItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

DistListItem Object

Other resources

DistListItem Object Members


DocumentItem Object (Outlook)

 Copy code hover
[image]

DocumentItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents any document other than a Microsoft Outlook item as an item in an Outlook folder.

Remarks

A DocumentItem object is any document other than an Outlook item as an item in an Outlook folder. In common usage, this will be an Office document but may be any type of document or executable file.

Unlike other Outlook objects, you cannot create this object.

Note Note

When you try to programmatically add a user-defined property to a DocumentItem object, you receive the following error message: "Property is read-only." This is because the Outlook object model does not support this functionality.

See also

Concepts

Outlook Object Model Reference

Other resources

DocumentItem Object Members


DocumentItem Members (Outlook)

 Copy code hover
[image]

DocumentItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents any document other than a Microsoft Outlook item as an item in an Outlook folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DocumentItem object. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


DocumentItem Properties (Outlook)

 Copy code hover
[image]

DocumentItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DocumentItem object. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


DocumentItem.Actions Property (Outlook)

 Copy code hover
[image]

DocumentItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Application Property (Outlook)

 Copy code hover
[image]

DocumentItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Attachments Property (Outlook)

 Copy code hover
[image]

DocumentItem.Attachments Property (Outlook)
See also Send feedback

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

DocumentItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a DocumentItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its DocumentItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

DocumentItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a DocumentItem object.

Remarks

This is a free-form text field.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Body Property (Outlook)

 Copy code hover
[image]

DocumentItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

This object, member, or enumeration will be deprecated and is not intended to be used in your code.

Syntax

expression .Body

expression A variable that represents a DocumentItem object.

Remarks

Attempting to set this property returns an error.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Categories Property (Outlook)

 Copy code hover
[image]

DocumentItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a DocumentItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Class Property (Outlook)

 Copy code hover
[image]

DocumentItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Companies Property (Outlook)

 Copy code hover
[image]

DocumentItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a DocumentItem object.

Remarks

This is a free-form text field.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Conflicts Property (Outlook)

 Copy code hover
[image]

DocumentItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

DocumentItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

DocumentItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.CreationTime Property (Outlook)

 Copy code hover
[image]

DocumentItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.DownloadState Property (Outlook)

 Copy code hover
[image]

DocumentItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a DocumentItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.EntryID Property (Outlook)

 Copy code hover
[image]

DocumentItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.FormDescription Property (Outlook)

 Copy code hover
[image]

DocumentItem.FormDescription Property (Outlook)
See also Send feedback

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.GetInspector Property (Outlook)

 Copy code hover
[image]

DocumentItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

This object, member, or enumeration will be deprecated and is not intended to be used in your code.

Syntax

expression .GetInspector

expression A variable that represents a DocumentItem object.

Remarks

To display an item, you can use DocumentItem.Display.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Importance Property (Outlook)

 Copy code hover
[image]

DocumentItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.IsConflict Property (Outlook)

 Copy code hover
[image]

DocumentItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a DocumentItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

DocumentItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a DocumentItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

DocumentItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

DocumentItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

This object, member, or enumeration will be deprecated and is not intended to be used in your code.

Syntax

expression .MarkForDownload

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.MessageClass Property (Outlook)

 Copy code hover
[image]

DocumentItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Mileage Property (Outlook)

 Copy code hover
[image]

DocumentItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a DocumentItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.NoAging Property (Outlook)

 Copy code hover
[image]

DocumentItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

DocumentItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

DocumentItem.OutlookVersion Property (Outlook)
See also Send feedback

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Parent Property (Outlook)

 Copy code hover
[image]

DocumentItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

DocumentItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent DocumentItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Saved Property (Outlook)

 Copy code hover
[image]

DocumentItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

DocumentItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Session Property (Outlook)

 Copy code hover
[image]

DocumentItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a DocumentItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Size Property (Outlook)

 Copy code hover
[image]

DocumentItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Subject Property (Outlook)

 Copy code hover
[image]

DocumentItem.Subject Property (Outlook)
See also Send feedback

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a DocumentItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.UnRead Property (Outlook)

 Copy code hover
[image]

DocumentItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.UserProperties Property (Outlook)

 Copy code hover
[image]

DocumentItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a DocumentItem object.

Remarks

Even though olWordDocumentItem is a valid constant in the OlItemType enumeration, user-defined fields cannot to be added to a DocumentItem object and you will receive an error when you try to programmatically add a user-defined field to a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem Methods (Outlook)

 Copy code hover
[image]

DocumentItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | This object, member, or enumeration will be deprecated and is not intended to be used in your code.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


DocumentItem.Close Method (Outlook)

 Copy code hover
[image]

DocumentItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

This object, member, or enumeration will be deprecated and is not intended to be used in your code.

Syntax

expression .Close(SaveMode)

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Copy Method (Outlook)

 Copy code hover
[image]

DocumentItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Delete Method (Outlook)

 Copy code hover
[image]

DocumentItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a DocumentItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

DocumentItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

DocumentItem Object Members


DocumentItem.Display Method (Outlook)

 Copy code hover
[image]

DocumentItem.Display Method (Outlook)
See also Send feedback

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Move Method (Outlook)

 Copy code hover
[image]

DocumentItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | The destination folder.

Return Value

An Object that represents the item which has been moved to the designated folder.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.PrintOut Method (Outlook)

 Copy code hover
[image]

DocumentItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Save Method (Outlook)

 Copy code hover
[image]

DocumentItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.SaveAs Method (Outlook)

 Copy code hover
[image]

DocumentItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

DocumentItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a DocumentItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem Events (Outlook)

 Copy code hover
[image]

DocumentItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


DocumentItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

DocumentItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a DocumentItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

DocumentItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

DocumentItem.AttachmentRead Event (Outlook)
See also Send feedback

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

DocumentItem.AttachmentRemove Event (Outlook)
See also Send feedback

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment )

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel )

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the DocumentItem to be saved.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeDelete Event (Outlook)
See also Send feedback

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

DocumentItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a DocumentItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Close Event (Outlook)

 Copy code hover
[image]

DocumentItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.CustomAction Event (Outlook)

 Copy code hover
[image]

DocumentItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

DocumentItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Forward Event (Outlook)

 Copy code hover
[image]

DocumentItem.Forward Event (Outlook)
See also Send feedback

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Open Event (Outlook)

 Copy code hover
[image]

DocumentItem.Open Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

DocumentItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Read Event (Outlook)

 Copy code hover
[image]

DocumentItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a DocumentItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

DocumentItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Reply Event (Outlook)

 Copy code hover
[image]

DocumentItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

DocumentItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Send Event (Outlook)

 Copy code hover
[image]

DocumentItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Unload Event (Outlook)

 Copy code hover
[image]

DocumentItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a DocumentItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


DocumentItem.Write Event (Outlook)

 Copy code hover
[image]

DocumentItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a DocumentItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

DocumentItem Object

Other resources

DocumentItem Object Members


Exception Object (Outlook)

 Copy code hover
[image]

Exception Object (Outlook)
See also Send feedback

Represents information about one instance of an AppointmentItem object which is an exception to a recurring series.

Remarks

Unlike most of the other Microsoft Outlook objects, the Exception object is a read-only object. This means that you cannot create an Exception object but, rather, the object is created when a property of an AppointmentItem is altered. For example, if you change the Start property of one AppointmentItem, you have created an Exception in AppointmentItem.RecurrencePattern.Exceptions.

Note Note

The Exceptions object is on the RecurrencePattern, not the AppointmentItem object itself.

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

Example

The following Visual Basic for Applications (VBA) example retrieves the first Exception object from the Exceptions collection object associated with a RecurrencePattern object.

VBA Copy code Copy code
Sub GetException()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrencePattern As Outlook.RecurrencePattern

 Dim myException As Outlook.Exception

 Set myNameSpace = Application.GetNameSpace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Daily Meeting")

 Set myRecurrencePattern = myApptItem.GetRecurrencePattern

 Set myException = myRecurrencePattern.Exceptions.Item(1)

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Exception Object Members


Exception Members (Outlook)

 Copy code hover
[image]

Exception Members (Outlook)
Send feedback

Published: July 16, 2012

Represents information about one instance of an AppointmentItem object which is an exception to a recurring series.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AppointmentItem | Returns the AppointmentItem object that is the exception. Not valid for deleted appointments. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Deleted | Returns a Boolean value that indicates whether the AppointmentItem was deleted from the recurring pattern. Read-only
OriginalDate | Returns a Date indicating the original date and time of an AppointmentItem before it was altered. This property will return the original date even if the AppointmentItem has been deleted. However, it will not return the original time if deletion has occurred. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Exception Properties (Outlook)

 Copy code hover
[image]

Exception Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AppointmentItem | Returns the AppointmentItem object that is the exception. Not valid for deleted appointments. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Deleted | Returns a Boolean value that indicates whether the AppointmentItem was deleted from the recurring pattern. Read-only
OriginalDate | Returns a Date indicating the original date and time of an AppointmentItem before it was altered. This property will return the original date even if the AppointmentItem has been deleted. However, it will not return the original time if deletion has occurred. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Exception.Application Property (Outlook)

 Copy code hover
[image]

Exception.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Exception object.

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.AppointmentItem Property (Outlook)

 Copy code hover
[image]

Exception.AppointmentItem Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the AppointmentItem object that is the exception. Not valid for deleted appointments. Read-only.

Syntax

expression .AppointmentItem

expression A variable that represents an Exception object.

Remarks

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the GetRecurrencePattern method. By setting the these properties: RecurrenceType, PatternStartDate, and PatternEndDate, the appointments are now a recurring series that occur on a daily basis for the period of one year. An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original Subject and OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Release references to the appointment series

 Set myApptItem = Nothing

 Set myRecurrPatt = Nothing

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.Item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.Class Property (Outlook)

 Copy code hover
[image]

Exception.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Exception object.

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.Deleted Property (Outlook)

 Copy code hover
[image]

Exception.Deleted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the AppointmentItem was deleted from the recurring pattern. Read-only

Syntax

expression .Deleted

expression A variable that represents an Exception object.

Remarks

If this property returns True, then the AppointmentItem was deleted from the recurring pattern.

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.OriginalDate Property (Outlook)

 Copy code hover
[image]

Exception.OriginalDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the original date and time of an AppointmentItem before it was altered. This property will return the original date even if the AppointmentItem has been deleted. However, it will not return the original time if deletion has occurred. Read-only.

Syntax

expression .OriginalDate

expression A variable that represents an Exception object.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the GetRecurrencePattern method. By setting the these properties: RecurrenceType, PatternStartDate, and PatternEndDate, the appointments are now a recurring series that occur on a daily basis for the period of one year. An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original Subject and OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.Parent Property (Outlook)

 Copy code hover
[image]

Exception.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Exception object.

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exception.Session Property (Outlook)

 Copy code hover
[image]

Exception.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Exception object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Exception Object

Other resources

Exception Object Members


Exceptions Object (Outlook)

 Copy code hover
[image]

Exceptions Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a group of Exception objects.

Remarks

If you have a recurring AppointmentItem , the RecurrencePattern object defines the recurrence of these appointments. The Exceptions object contains the group of Exception objects that define the exceptions to that series of appointments.

Exception objects are added to the Exceptions object whenever a property in the corresponding AppointmentItem object is altered.

Example

The following example sets a reference to the Exceptions object.

Copy code Copy code
Set myExceptions = myRecurrencePattern.Exceptions

See also

Concepts

Outlook Object Model Reference

Other resources

Exceptions Object Members


Exceptions Members (Outlook)

 Copy code hover
[image]

Exceptions Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a group of Exception objects.

Methods

Name | Description
Item | Returns an Exception object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Exceptions Properties (Outlook)

 Copy code hover
[image]

Exceptions Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Exceptions.Application Property (Outlook)

 Copy code hover
[image]

Exceptions.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Exceptions object.

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


Exceptions.Class Property (Outlook)

 Copy code hover
[image]

Exceptions.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Exceptions object.

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


Exceptions.Count Property (Outlook)

 Copy code hover
[image]

Exceptions.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Exceptions object.

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


Exceptions.Parent Property (Outlook)

 Copy code hover
[image]

Exceptions.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Exceptions object.

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


Exceptions.Session Property (Outlook)

 Copy code hover
[image]

Exceptions.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Exceptions object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


Exceptions Methods (Outlook)

 Copy code hover
[image]

Exceptions Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns an Exception object from the collection.


Exceptions.Item Method (Outlook)

 Copy code hover
[image]

Exceptions.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Exception object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an Exceptions object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Exception object that represents the specified object.

See also

Concepts

Exceptions Object

Other resources

Exceptions Object Members


ExchangeDistributionList Object (Outlook)

 Copy code hover
[image]

ExchangeDistributionList Object (Outlook)
See also Send feedback

Published: July 16, 2012

The ExchangeDistributionList object provides detailed information about an AddressEntry that represents an Exchange distribution list.

Version Information

Version Added: Outlook 2007

Remarks

ExchangeDistributionList is a derived class of AddressEntry, and is returned instead of an AddressEntry when the caller performs a QueryInterface on the AddressEntry.

The AddressEntry.Members property supports enumerating members of a distribution list. ExchangeDistributionList adds the first-class properties for Alias, Comments, and PrimarySmtpAddress. You can also access other properties specific to the Exchange distribution list that are not exposed in the object model through the PropertyAccessor object.

Some properties such as Comments are read-write properties. Setting these properties requires the code to be running under an appropriate Exchange administrator account; without sufficient permissions, calling the ExchangeUser.Update method will result in a "permission denied" error.

Example

The following code sample shows how to obtain the names of the Exchange distribution lists that the current user's manager belongs to. It uses the ExchangeUser.GetExchangeUserManager method to obtain information about the user's manager, and uses ExchangeUser.GetMemberOfList to obtain the distribution lists (represented by ExchangeDistributionList objects) that the manager has joined.

VBA Copy code Copy code
Sub ShowManagerDistLists()
 Dim oAE As Outlook.AddressEntry
 Dim oExUser As Outlook.ExchangeUser
 Dim oDistListEntries As Outlook.AddressEntries

 'Obtain the AddressEntry for CurrentUser
 Set oExUser = _
 Application.Session.CurrentUser.AddressEntry.GetExchangeUser

 'Obtain distribution lists that the user's manager has joined
 Set oDistListEntries = oExUser.GetExchangeUserManager.GetMemberOfList
 For Each oAE In oDistListEntries
 If oAE.AddressEntryUserType = _
 olExchangeDistributionListAddressEntry Then
 Debug.Print (oAE.name)
 End If
 Next
End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList Members (Outlook)

 Copy code hover
[image]

ExchangeDistributionList Members (Outlook)
Send feedback

Published: July 16, 2012

The ExchangeDistributionList object provides detailed information about an AddressEntry that represents an Exchange distribution list.

Methods

Name | Description
Delete | Deletes the ExchangeDistributionList object from the AddressEntries collection object to which it belongs.
Details | Displays a modal dialog box that provides detailed information about an ExchangeDistributionList object.
GetContact | Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to a contact in a Contacts Address Book.
GetExchangeDistributionList | Returns the ExchangeDistributionList object.
GetExchangeDistributionListMembers | Returns an AddressEntries collection that represents the members of the Exchange distribution list.
GetExchangeUser | Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to an ExchangeUser object.
GetFreeBusy | Returns Null (Nothing in Visual Basic) because free-busy information is available only to individual users and not ExchangeDistributionList objects.
GetMemberOfList | Returns an AddressEntries collection object that contains all the AddressEntry objects representing Exchange Distribution Lists of which the ExchangeDistributionList is a member.
GetOwners | Returns an AddressEntries collection object that contains all the owners of the ExchangeDistributionList.
Update | Posts a change to the ExchangeDistributionList object in the messaging system.

Properties

Name | Description
Address | Returns or sets a String representing the X400 e-mail address of the ExchangeDistributionList. Read/write.
AddressEntryUserType | Returns olExchangeDistributionListAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeDistributionList. Read-only.
Alias | Returns a String representing the alias for the ExchangeDistributionList. Read-only.
Application | Returns an Application object that represents the parent application (Outlook) for the ExchangeDistributionList object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeDistributionList object. Read-only.
Comments | Returns a String representing the comments for the ExchangeDistributionList. Read/write.
DisplayType | Returns olDistList which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeDistributionList. Read-only.
ID | Returns a String representing the unique identifier for the ExchangeDistributionList. Read-only.
Name | Returns or sets a String value that represents the display name for the ExchangeDistributionList object. Read/write.
Parent | Returns the parent Object of the ExchangeDistributionList object. Read-only.
PrimarySmtpAddress | Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeDistributionList. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeDistributionList object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns a String representing the type of entry for the ExchangeDistributionList. Read/write.


ExchangeDistributionList Properties (Outlook)

 Copy code hover
[image]

ExchangeDistributionList Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Address | Returns or sets a String representing the X400 e-mail address of the ExchangeDistributionList. Read/write.
AddressEntryUserType | Returns olExchangeDistributionListAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeDistributionList. Read-only.
Alias | Returns a String representing the alias for the ExchangeDistributionList. Read-only.
Application | Returns an Application object that represents the parent application (Outlook) for the ExchangeDistributionList object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeDistributionList object. Read-only.
Comments | Returns a String representing the comments for the ExchangeDistributionList. Read/write.
DisplayType | Returns olDistList which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeDistributionList. Read-only.
ID | Returns a String representing the unique identifier for the ExchangeDistributionList. Read-only.
Name | Returns or sets a String value that represents the display name for the ExchangeDistributionList object. Read/write.
Parent | Returns the parent Object of the ExchangeDistributionList object. Read-only.
PrimarySmtpAddress | Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeDistributionList. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeDistributionList object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns a String representing the type of entry for the ExchangeDistributionList. Read/write.


ExchangeDistributionList.Address Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the X400 e-mail address of the ExchangeDistributionList. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Address

expression A variable that represents an ExchangeDistributionList object.

Remarks

This property assumes the X400 address of the distribution list. To determine the primary Internet address, use the ExchangeDistributionList.PrimarySmtpAddress property.

The Address property must be set before calling the ExchangeDistributionList.Details method.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.AddressEntryUserType Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.AddressEntryUserType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns olExchangeDistributionListAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeDistributionList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressEntryUserType

expression A variable that represents an ExchangeDistributionList object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the AddressEntryUserType property from the AddressEntry object. In the case of ExchangeDistributionList, AddressEntryUserType should always return olExchangeDistributionListAddressEntry.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Alias Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Alias Property (Outlook)
See also Send feedback

Returns a String representing the alias for the ExchangeDistributionList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Alias

expression A variable that represents an ExchangeDistributionList object.

Remarks

This property corresponds to the MAPI property PidTagAccount.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Application Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent application (Outlook) for the ExchangeDistributionList object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Class Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Class Property (Outlook)
See also Send feedback

Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeDistributionList object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Comments Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Comments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the comments for the ExchangeDistributionList. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Comments

expression A variable that represents an ExchangeDistributionList object.

Remarks

This property corresponds to the MAPI property, PidTagComment.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.DisplayType Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.DisplayType Property (Outlook)
See also Send feedback

Returns olDistList which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeDistributionList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayType

expression A variable that represents an ExchangeDistributionList object.

Remarks

This property corresponds to the MAPI property PidTagDisplayType.

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the DisplayType property from the AddressEntry object. In the case of ExchangeDistributionList, DisplayType should always return olDistList.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.ID Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.ID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique identifier for the ExchangeDistributionList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ID

expression A variable that represents an ExchangeDistributionList object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the ID property from the AddressEntry object. The transport provider assigns a permanent, unique string ID when an AddressEntry object is created. These identifiers do not change from one session to another.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Name Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the ExchangeDistributionList object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents an ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Parent Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the ExchangeDistributionList object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.PrimarySmtpAddress Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.PrimarySmtpAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeDistributionList. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PrimarySmtpAddress

expression A variable that represents an ExchangeDistributionList object.

Remarks

This property corresponds to the MAPI property PidTagEmailAddress.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object
How to: Obtain the E-mail Address of a Recipient

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeDistributionList object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Session Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an ExchangeDistributionList object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Type Property (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the type of entry for the ExchangeDistributionList. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Type

expression A variable that represents an ExchangeDistributionList object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the Type property from the AddressEntry object. In the case of ExchangeDistributionList, the type is always the string "EX".

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList Methods (Outlook)

 Copy code hover
[image]

ExchangeDistributionList Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes the ExchangeDistributionList object from the AddressEntries collection object to which it belongs.
Details | Displays a modal dialog box that provides detailed information about an ExchangeDistributionList object.
GetContact | Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to a contact in a Contacts Address Book.
GetExchangeDistributionList | Returns the ExchangeDistributionList object.
GetExchangeDistributionListMembers | Returns an AddressEntries collection that represents the members of the Exchange distribution list.
GetExchangeUser | Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to an ExchangeUser object.
GetFreeBusy | Returns Null (Nothing in Visual Basic) because free-busy information is available only to individual users and not ExchangeDistributionList objects.
GetMemberOfList | Returns an AddressEntries collection object that contains all the AddressEntry objects representing Exchange Distribution Lists of which the ExchangeDistributionList is a member.
GetOwners | Returns an AddressEntries collection object that contains all the owners of the ExchangeDistributionList.
Update | Posts a change to the ExchangeDistributionList object in the messaging system.


ExchangeDistributionList.Delete Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes the ExchangeDistributionList object from the AddressEntries collection object to which it belongs.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents an ExchangeDistributionList object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. An ExchangeDistributionList object is an AddressEntry object that has olExchangeDistributionListAddressEntry as the AddressEntry.AddressEntryUserType; calling AddressEntry.GetExchangeDistributionList returns the corresponding ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Details Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Details Method (Outlook)
See also Send feedback

Displays a modal dialog box that provides detailed information about an ExchangeDistributionList object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Details(HWnd)

expression A variable that represents an ExchangeDistributionList object.

Parameters

Name | Required/Optional | Data Type | Description
HWnd | Optional | Variant | The parent window handle for the Details dialog box. A zero value (the default) specifies a modal dialog box.

Remarks

The Details method fails if the ExchangeDistributionList.Name property is empty. You must use error handling to handle run-time errors, and when the user clicks Cancel in the dialog box.

The Details method actually stops the code from running while the dialog box is displayed.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetContact Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetContact Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to a contact in a Contacts Address Book.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetContact

expression A variable that represents an ExchangeDistributionList object.

Return Value

Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to a contact in a Contacts Address Book.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the GetContact method from the AddressEntry object, and in the case of ExchangeDistributionList, this method always returns Null.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetExchangeDistributionList Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetExchangeDistributionList Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the ExchangeDistributionList object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeDistributionList

expression A variable that represents an ExchangeDistributionList object.

Return Value

The parent ExchangeDistributionList object.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetExchangeDistributionListMembers Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetExchangeDistributionListMembers Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntries collection that represents the members of the Exchange distribution list.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeDistributionListMembers

expression A variable that represents an ExchangeDistributionList object.

Return Value

An AddressEntries collection that contains AddressEntry objects that represent members belonging to the distribution list.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetExchangeUser Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetExchangeUser Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to an ExchangeUser object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeUser

expression A variable that represents an ExchangeDistributionList object.

Return Value

Null (Nothing in Visual Basic) because the ExchangeDistributionList object does not correspond to an ExchangeUser object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the GetExchangeUser method from the AddressEntry object, and in the case of ExchangeDistributionList, this method always returns Null.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetFreeBusy Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetFreeBusy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns Null (Nothing in Visual Basic) because free-busy information is available only to individual users and not ExchangeDistributionList objects.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetFreeBusy(Start, MinPerChar, CompleteFormat)

expression An expression that returns an ExchangeDistributionList object.

Remarks

The ExchangeDistributionList object is derived from the AddressEntry object. It inherits the GetFreeBusy method from the AddressEntry object, and in the case of ExchangeDistributionList, regardless of the values of the parameters, this method always returns Null.

This method does not return the free-busy information of individual members of an ExchangeDistributionList. To obtain free-busy information for a meeting request, send the request to individual users. Use the AddressEntry.AddressEntryUserType property of the AddressEntry object obtained from Recipient.AddressEntry to determine if a Recipient represents an ExchangeDistributionList.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetMemberOfList Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetMemberOfList Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntries collection object that contains all the AddressEntry objects representing Exchange Distribution Lists of which the ExchangeDistributionList is a member.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetMemberOfList

expression A variable that represents an ExchangeDistributionList object.

Return Value

An AddressEntries collection object that represents the distribution lists of which this ExchangeDistributionList object is a member. Returns an AddressEntries object with a count of zero (0) if the ExchangeDistributionList is not a member of any Exchange distribution list.

Remarks

GetMemberOfList is an expensive operation in terms of performance if there is a slow connection to Exchange Server.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.GetOwners Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.GetOwners Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntries collection object that contains all the owners of the ExchangeDistributionList.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetOwners

expression A variable that represents an ExchangeDistributionList object.

Return Value

An AddressEntries collection object that contains AddressEntry objects representing all the owners of the ExchangeDistributionList. Returns an AddressEntries object with a count of zero (0) if no owners can be found for the ExchangeDistributionList in the current session.

Remarks

GetOwners is an expensive operation in terms of performance if there is a slow connection to Exchange Server.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeDistributionList.Update Method (Outlook)

 Copy code hover
[image]

ExchangeDistributionList.Update Method (Outlook)
See also Send feedback

Published: July 16, 2012

Posts a change to the ExchangeDistributionList object in the messaging system.

Version Information

Version Added: Outlook 2007

Syntax

expression .Update(MakePermanent, Refresh)

expression A variable that represents an ExchangeDistributionList object.

Parameters

Name | Required/Optional | Data Type | Description
MakePermanent | Optional | Variant | A value of True indicates that the property cache is flushed and all changes are committed in the underlying address book. A value of False indicates that the property cache is flushed but not committed to persistent storage. The default value is True.
Refresh | Optional | Variant | A value of True indicates that the property cache is reloaded from the values in the underlying address book. A value of False indicates that the property cache is not reloaded. The default value is False.

Remarks

New entries or changes to existing entries are not persisted in the collection until the Update method has been called with its MakePermanent parameter set to True.

To flush the cache and then reload the values from the address book, call Update with the MakePermanent parameter set to False and the Refresh parameter set to True.

See also

Concepts

ExchangeDistributionList Object

Other resources

ExchangeDistributionList Object Members


ExchangeUser Object (Outlook)

 Copy code hover
[image]

ExchangeUser Object (Outlook)
See also Send feedback

Published: July 16, 2012

Provides detailed information about an AddressEntry that represents a Microsoft Exchange mailbox user.

Version Information

Version Added: Outlook 2007

Remarks

ExchangeUser is derived from the AddressEntry object, and is returned instead of an AddressEntry when the caller performs a query interface on the AddressEntry object.

This object provides first-class access to properties applicable to Exchange users such as FirstName, JobTitle, LastName, and OfficeLocation. You can also access other properties specific to the Exchange user that are not exposed in the object model through the PropertyAccessor object. Note that some of the explicit built-in properties are read-write properties. Setting these properties requires the code to be running under an appropriate Exchange administrator account; without sufficient permissions, calling the ExchangeUser.Update method will result in a "permission denied" error.

Example

The following code sample shows how to obtain the business phone number, office location, and job title for all entries in the Exchange Global Address List.

Copy code Copy code
Sub DemoAE()

 Dim colAL As Outlook.AddressLists

 Dim oAL As Outlook.AddressList

 Dim colAE As Outlook.AddressEntries

 Dim oAE As Outlook.AddressEntry

 Dim oExUser As Outlook.ExchangeUser

 Set colAL = Application.Session.AddressLists

 For Each oAL In colAL

 'Address list is an Exchange Global Address List

 If oAL.AddressListType = olExchangeGlobalAddressList Then

 Set colAE = oAL.AddressEntries

 For Each oAE In colAE

 If oAE.AddressEntryUserType = _

 olExchangeUserAddressEntry Then

 Set oExUser = oAE.GetExchangeUser

 Debug.Print(oExUser.JobTitle)

 Debug.Print(oExUser.OfficeLocation)

 Debug.Print(oExUser.BusinessTelephoneNumber)

 End If

 Next

 End If

 Next

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ExchangeUser Object Members


ExchangeUser Members (Outlook)

 Copy code hover
[image]

ExchangeUser Members (Outlook)
Send feedback

Published: July 16, 2012

Provides detailed information about an AddressEntry that represents a Microsoft Exchange mailbox user.

Methods

Name | Description
Delete | Deletes the ExchangeUser object from the AddressEntries collection object to which it belongs.
Details | Displays a modal dialog box that provides detailed information about an ExchangeUser object.
GetContact | Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to a contact in a Contacts Address Book.
GetDirectReports | Obtains an AddressEntries collection object that contains all the users directly reporting to the Exchange user.
GetExchangeDistributionList | Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to an ExchangeDistributionList object.
GetExchangeUser | Returns the ExchangeUser object.
GetExchangeUserManager | Returns an ExchangeUser object that represents the manager of the Exchange user.
GetFreeBusy | Obtains a String representing the availability of the ExchangeUser for a period of 30 days from the start date, beginning at midnight of the date specified.
GetMemberOfList | Returns an AddressEntries collection object that contains the AddressEntry objects representing all the Exchange distribution lists to which the user belongs.
GetPicture | Obtains an IPictureDisp object that represents the picture of the Microsoft Exchange user that is displayed in Microsoft Outlook.
Update | Posts a change to the ExchangeUser object in the messaging system.

Properties

Name | Description
Address | Returns or sets a String representing the X400 e-mail address of the ExchangeUser. Read/write.
AddressEntryUserType | Returns olExchangeUserAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeUser. Read-only.
Alias | Returns a String representing the alias for the ExchangeUser. Read-only.
Application | Returns an Application object that represents the parent application (Outlook) for the ExchangeUser object. Read-only.
AssistantName | Returns a String representing the name of the assistant for the ExchangeUser. Read/write.
BusinessTelephoneNumber | Returns a String representing the business telephone number for the ExchangeUser. Read/write.
City | Returns a String representing the city for the ExchangeUser. Read/write.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeUser object. Read-only.
Comments | Returns a String representing the comments for the ExchangeUser. Read/write.
CompanyName | Returns a String representing the name of the company for the ExchangeUser. Read/write.
Department | Returns a String representing the department for the ExchangeUser. Read/write.
DisplayType | Returns olUser which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeUser. Read-only.
FirstName | Returns a String representing the first name of the ExchangeUser. Read/write.
ID | Returns a String representing the unique identifier for the ExchangeUser. Read-only.
JobTitle | Returns a String representing the job title of the ExchangeUser. Read/write.
LastName | Returns a String representing the last name of the ExchangeUser. Read/write.
MobileTelephoneNumber | Returns a String representing the mobile telephone number for the ExchangeUser. Read/write.
Name | Returns or sets a String value that represents the display name for the ExchangeUser object. Read/write.
OfficeLocation | Returns a String representing the office location for the ExchangeUser. Read/write.
Parent | Returns the parent Object of the ExchangeUser object. Read-only.
PostalCode | Returns a String representing the postal code for the ExchangeUser. Read/write.
PrimarySmtpAddress | Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeUser. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeUser object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StateOrProvince | Returns a String representing the state or province for the ExchangeUser. Read/write.
StreetAddress | Returns a String representing the street address for the ExchangeUser. Read/write.
Type | Returns a String representing the type of entry for the ExchangeUser. Read/write.
YomiCompanyName | Returns a String representing the Japanese phonetic rendering (yomigana) of the company name for the ExchangeUser. Read/write.
YomiDepartment | Returns a String representing the Japanese phonetic rendering (yomigana) of the department name for the ExchangeUser. Read/write.
YomiDisplayName | Returns a String representing the Japanese phonetic rendering (yomigana) of the Exchange display name for the ExchangeUser. Read/write.
YomiFirstName | Returns a String representing the Japanese phonetic rendering (yomigana) of the first name for the ExchangeUser. Read/write.
YomiLastName | Returns a String representing the Japanese phonetic rendering (yomigana) of the last name for the ExchangeUser. Read/write.


ExchangeUser Properties (Outlook)

 Copy code hover
[image]

ExchangeUser Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Address | Returns or sets a String representing the X400 e-mail address of the ExchangeUser. Read/write.
AddressEntryUserType | Returns olExchangeUserAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeUser. Read-only.
Alias | Returns a String representing the alias for the ExchangeUser. Read-only.
Application | Returns an Application object that represents the parent application (Outlook) for the ExchangeUser object. Read-only.
AssistantName | Returns a String representing the name of the assistant for the ExchangeUser. Read/write.
BusinessTelephoneNumber | Returns a String representing the business telephone number for the ExchangeUser. Read/write.
City | Returns a String representing the city for the ExchangeUser. Read/write.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeUser object. Read-only.
Comments | Returns a String representing the comments for the ExchangeUser. Read/write.
CompanyName | Returns a String representing the name of the company for the ExchangeUser. Read/write.
Department | Returns a String representing the department for the ExchangeUser. Read/write.
DisplayType | Returns olUser which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeUser. Read-only.
FirstName | Returns a String representing the first name of the ExchangeUser. Read/write.
ID | Returns a String representing the unique identifier for the ExchangeUser. Read-only.
JobTitle | Returns a String representing the job title of the ExchangeUser. Read/write.
LastName | Returns a String representing the last name of the ExchangeUser. Read/write.
MobileTelephoneNumber | Returns a String representing the mobile telephone number for the ExchangeUser. Read/write.
Name | Returns or sets a String value that represents the display name for the ExchangeUser object. Read/write.
OfficeLocation | Returns a String representing the office location for the ExchangeUser. Read/write.
Parent | Returns the parent Object of the ExchangeUser object. Read-only.
PostalCode | Returns a String representing the postal code for the ExchangeUser. Read/write.
PrimarySmtpAddress | Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeUser. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeUser object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StateOrProvince | Returns a String representing the state or province for the ExchangeUser. Read/write.
StreetAddress | Returns a String representing the street address for the ExchangeUser. Read/write.
Type | Returns a String representing the type of entry for the ExchangeUser. Read/write.
YomiCompanyName | Returns a String representing the Japanese phonetic rendering (yomigana) of the company name for the ExchangeUser. Read/write.
YomiDepartment | Returns a String representing the Japanese phonetic rendering (yomigana) of the department name for the ExchangeUser. Read/write.
YomiDisplayName | Returns a String representing the Japanese phonetic rendering (yomigana) of the Exchange display name for the ExchangeUser. Read/write.
YomiFirstName | Returns a String representing the Japanese phonetic rendering (yomigana) of the first name for the ExchangeUser. Read/write.
YomiLastName | Returns a String representing the Japanese phonetic rendering (yomigana) of the last name for the ExchangeUser. Read/write.


ExchangeUser.Address Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the X400 e-mail address of the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Address

expression A variable that represents an ExchangeUser object.

Remarks

This property assumes the X400 address of the user. To determine the primary Internet address, use the ExchangeUser.PrimarySmtpAddress property.

The Address property must be set before calling the ExchangeUser.Details method.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.AddressEntryUserType Property (Outlook)

 Copy code hover
[image]

ExchangeUser.AddressEntryUserType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns olExchangeUserAddressEntry which is a constant from the OlAddressEntryUserType enumeration representing the user type of the ExchangeUser. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressEntryUserType

expression A variable that represents an ExchangeUser object.

Remarks

The ExchangeUser object is derived from the AddressEntry object. It inherits the AddressEntryUserType property from the AddressEntry object. In the case of ExchangeUser, AddressEntryUserType should always return olExchangeUserAddressEntry.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Alias Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Alias Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the alias for the ExchangeUser. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Alias

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to MAPI property PidTagAccount.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Application Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent application (Outlook) for the ExchangeUser object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.AssistantName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.AssistantName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the name of the assistant for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AssistantName

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to MAPI property PidTagAssistant.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.BusinessTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ExchangeUser.BusinessTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the business telephone number for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BusinessTelephoneNumber

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagBusinessTelephoneNumber.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.City Property (Outlook)

 Copy code hover
[image]

ExchangeUser.City Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the city for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .City

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagLocality.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Class Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Class Property (Outlook)
See also Send feedback

Returns a constant in the OlObjectClass enumeration indicating the class of the ExchangeUser object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Comments Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Comments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the comments for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Comments

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagComment.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.CompanyName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.CompanyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the name of the company for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CompanyName

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagCompanyName.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Department Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Department Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the department for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Department

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagDepartmentName.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.DisplayType Property (Outlook)

 Copy code hover
[image]

ExchangeUser.DisplayType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns olUser which is a constant from the OlDisplayType enumeration representing the nature of the ExchangeUser. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayType

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagDisplayType.

The ExchangeUser object is derived from the AddressEntry object. It inherits the DisplayType property from the AddressEntry object. In the case of ExchangeUser, DisplayType should always return olUser.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.FirstName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.FirstName Property (Outlook)
See also Send feedback

Returns a String representing the first name of the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FirstName

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagGivenName.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.ID Property (Outlook)

 Copy code hover
[image]

ExchangeUser.ID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique identifier for the ExchangeUser. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ID

expression A variable that represents an ExchangeUser object.

Remarks

The ExchangeUser object is derived from the AddressEntry object. It inherits the ID property from the AddressEntry object. The transport provider assigns a permanent, unique string ID when an AddressEntry object is created. These identifiers do not change from one session to another.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.JobTitle Property (Outlook)

 Copy code hover
[image]

ExchangeUser.JobTitle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the job title of the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .JobTitle

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagTitle.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.LastName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.LastName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the last name of the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LastName

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to MAPI property, PidTagSurname.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.MobileTelephoneNumber Property (Outlook)

 Copy code hover
[image]

ExchangeUser.MobileTelephoneNumber Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the mobile telephone number for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MobileTelephoneNumber

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to MAPI property, PidTagMobileTelephoneNumber.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Name Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the ExchangeUser object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.OfficeLocation Property (Outlook)

 Copy code hover
[image]

ExchangeUser.OfficeLocation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the office location for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .OfficeLocation

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagOfficeLocation.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Parent Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the ExchangeUser object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.PostalCode Property (Outlook)

 Copy code hover
[image]

ExchangeUser.PostalCode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the postal code for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .PostalCode

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagPostalCode.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.PrimarySmtpAddress Property (Outlook)

 Copy code hover
[image]

ExchangeUser.PrimarySmtpAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the primary Simple Mail Transfer Protocol (SMTP) address for the ExchangeUser. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PrimarySmtpAddress

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagEmailAddress.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

How to: Obtain the E-mail Address of a Recipient
ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

ExchangeUser.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ExchangeUser object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Session Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an ExchangeUser object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.StateOrProvince Property (Outlook)

 Copy code hover
[image]

ExchangeUser.StateOrProvince Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the state or province for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StateOrProvince

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagStateOrProvince.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.StreetAddress Property (Outlook)

 Copy code hover
[image]

ExchangeUser.StreetAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the street address for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StreetAddress

expression A variable that represents an ExchangeUser object.

Remarks

This property corresponds to the MAPI property, PidTagStreetAddress.

Returns an empty string if this property has not been implemented or does not exist for the ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Type Property (Outlook)

 Copy code hover
[image]

ExchangeUser.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the type of entry for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Type

expression A variable that represents an ExchangeUser object.

Remarks

The ExchangeUser object is derived from the AddressEntry object. It inherits the Type property from the AddressEntry object. In the case of ExchangeUser, the type is always the string "EX".

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.YomiCompanyName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.YomiCompanyName Property (Outlook)
See also Send feedback

Returns a String representing the Japanese phonetic rendering (yomigana) of the company name for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .YomiCompanyName

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.YomiDepartment Property (Outlook)

 Copy code hover
[image]

ExchangeUser.YomiDepartment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the Japanese phonetic rendering (yomigana) of the department name for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .YomiDepartment

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.YomiDisplayName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.YomiDisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the Japanese phonetic rendering (yomigana) of the Exchange display name for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .YomiDisplayName

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.YomiFirstName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.YomiFirstName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the Japanese phonetic rendering (yomigana) of the first name for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .YomiFirstName

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.YomiLastName Property (Outlook)

 Copy code hover
[image]

ExchangeUser.YomiLastName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the Japanese phonetic rendering (yomigana) of the last name for the ExchangeUser. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .YomiLastName

expression A variable that represents an ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser Methods (Outlook)

 Copy code hover
[image]

ExchangeUser Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes the ExchangeUser object from the AddressEntries collection object to which it belongs.
Details | Displays a modal dialog box that provides detailed information about an ExchangeUser object.
GetContact | Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to a contact in a Contacts Address Book.
GetDirectReports | Obtains an AddressEntries collection object that contains all the users directly reporting to the Exchange user.
GetExchangeDistributionList | Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to an ExchangeDistributionList object.
GetExchangeUser | Returns the ExchangeUser object.
GetExchangeUserManager | Returns an ExchangeUser object that represents the manager of the Exchange user.
GetFreeBusy | Obtains a String representing the availability of the ExchangeUser for a period of 30 days from the start date, beginning at midnight of the date specified.
GetMemberOfList | Returns an AddressEntries collection object that contains the AddressEntry objects representing all the Exchange distribution lists to which the user belongs.
GetPicture | Obtains an IPictureDisp object that represents the picture of the Microsoft Exchange user that is displayed in Microsoft Outlook.
Update | Posts a change to the ExchangeUser object in the messaging system.


ExchangeUser.Delete Method (Outlook)

 Copy code hover
[image]

ExchangeUser.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes the ExchangeUser object from the AddressEntries collection object to which it belongs.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents an ExchangeUser object.

Remarks

The ExchangeUser object is derived from the AddressEntry object. An ExchangeUser object is an AddressEntry object that has olExchangeUserAddressEntry as the AddressEntry.AddressEntryUserType; calling AddressEntry.GetExchangeUser returns the corresponding ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Details Method (Outlook)

 Copy code hover
[image]

ExchangeUser.Details Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a modal dialog box that provides detailed information about an ExchangeUser object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Details(HWnd)

expression A variable that represents an ExchangeUser object.

Parameters

Name | Required/Optional | Data Type | Description
HWnd | Optional | Variant | The parent window handle for the Details dialog box. A zero value (the default) specifies a modal dialog box.

Remarks

The Details method fails if the ExchangeUser.Name property is empty. You must use error handling to handle run-time errors, and when the user clicks Cancel in the dialog box.

The Details method actually stops the code from running while the dialog box is displayed.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetContact Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetContact Method (Outlook)
See also Send feedback

Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to a contact in a Contacts Address Book.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetContact

expression A variable that represents an ExchangeUser object.

Return Value

Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to a contact in a Contacts Address Book.

Remarks

The ExchangeUser object is derived from the AddressEntry object. It inherits the GetContact method from the AddressEntry object, and in the case of ExchangeUser, this method always returns Null.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetDirectReports Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetDirectReports Method (Outlook)
See also Send feedback

Obtains an AddressEntries collection object that contains all the users directly reporting to the Exchange user.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetDirectReports

expression A variable that represents an ExchangeUser object.

Return Value

An AddressEntries collection object that contains the users directly reporting to the Exchange user. The AddressEntries object will have a count of zero (0) if there is no direct report represented by an AddressEntry in the current session, or if direct reports have not been implemented in the Exchange directory.

Remarks

GetDirectReports is an expensive operation in terms of performance if there is a slow connection to the Exchange server.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetExchangeDistributionList Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetExchangeDistributionList Method (Outlook)
See also Send feedback

Returns Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to an ExchangeDistributionList object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeDistributionList

expression A variable that represents an ExchangeUser object.

Return Value

Null (Nothing in Visual Basic) because the ExchangeUser object does not correspond to an ExchangeDistributionList object.

Remarks

The ExchangeUser object is derived from the AddressEntry object. It inherits the GetExchangeDistributionList method from the AddressEntry object, and in the case of ExchangeUser, this method always returns Null.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetExchangeUser Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetExchangeUser Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the ExchangeUser object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeUser

expression A variable that represents an ExchangeUser object.

Return Value

The parent ExchangeUser object.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetExchangeUserManager Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetExchangeUserManager Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ExchangeUser object that represents the manager of the Exchange user.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExchangeUserManager

expression A variable that represents an ExchangeUser object.

Return Value

An ExchangeUser object that represents the manager of the Exchange user.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetFreeBusy Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetFreeBusy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a String representing the availability of the ExchangeUser for a period of 30 days from the start date, beginning at midnight of the date specified.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetFreeBusy(Start, MinPerChar, CompleteFormat)

expression A variable that represents an ExchangeUser object.

Parameters

Name | Required/Optional | Data Type | Description
Start | Required | Date | The date of availability, starting at midnight.
MinPerChar | Required | Long | Specifies the length of each time slot in minutes. Default is 30 minutes.
CompleteFormat | Optional | Variant | A value of True indicates that a finer granularity of busy time is returned in the free/busy string. A value of False indicates that a distinction between only the available and busy times is returned.

Return Value

A String that represents the availability of the Exchange user for a period of 30 days from the start date, beginning at midnight of the date specified. Each character in the String is a value indicating if the user is available (0), and optionally, whether a busy time is marked tentative (1), out of office (3), or other (2).

Example

The following Visual Basic for Applications (VBA) example uses the GetFreeBusy method to retrieve the free/busy information, with each time slot representing a 60 minute period, for the manager assigned to the current user. The example then uses that information to calculate the date and time on which the first free period occurs, and displays that information in the Debug window.

VBA Copy code Copy code
Sub GetManagerOpenInterval()
 Dim oManager As ExchangeUser
 Dim oCurrentUser As ExchangeUser
 Dim FreeBusy As String
 Dim BusySlot As Long
 Dim DateBusySlot As Date
 Dim i As Long
 Const SlotLength = 60
 'Get ExchangeUser for CurrentUser
 If Application.Session.CurrentUser.AddressEntry.Type = "EX" Then
 Set oCurrentUser = _
 Application.Session.CurrentUser.AddressEntry.GetExchangeUser
 'Get Manager
 Set oManager = oManager.GetExchangeUserManager
 If oManager Is Nothing Then
 Exit Sub
 End If
 FreeBusy = oManager.GetFreeBusy(Now, SlotLength)
 For i = 1 To Len(FreeBusy)
 If CLng(Mid(FreeBusy, i, 1)) = 0 Then
 'get the number of minutes into the day for free interval
 BusySlot = (i - 1) * SlotLength
 'get an actual date/time
 DateBusySlot = DateAdd("n", BusySlot, Date)
 'To refine this function, substitute actual
 'workdays and working hours in date/time comparison
 If TimeValue(DateBusySlot) >= TimeValue(#8:00:00 AM#) And _
 TimeValue(DateBusySlot) <= TimeValue(#5:00:00 PM#) And _
 Not (Weekday(DateBusySlot) = vbSaturday Or _
 Weekday(DateBusySlot) = vbSunday) Then
 Debug.Print oManager.name & " first open interval:" & _
 vbCrLf & _
 Format$(DateBusySlot, "dddd, mmm d yyyy hh:mm AMPM")
 Exit For
 End If
 End If
 Next
 End If
End Sub

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetMemberOfList Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetMemberOfList Method (Outlook)
See also Send feedback

Returns an AddressEntries collection object that contains the AddressEntry objects representing all the Exchange distribution lists to which the user belongs.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetMemberOfList

expression A variable that represents an ExchangeUser object.

Return Value

An AddressEntries collection object that represents the Exchange distribution lists to which the ExchangeUser belongs. Returns an AddressEntries collection object with a count of zero (0) if the ExchangeUser is not a member of any Exchange distribution list.

Remarks

GetMemberOfList is an expensive operation in terms of performance if there is a slow connection to Exchange Server.

Example

The following code sample shows how to obtain the names of the Exchange distribution lists to which the manager of the current user belongs. It uses the ExchangeUser object to obtain specific Exchange user information such as the user's Exchange account alias, details about the user's manager, and the distribution lists that the user's manager has joined.

VBA Copy code Copy code
Sub ShowManagerDistLists()

 Dim oAE As Outlook.AddressEntry

 Dim oExUser As Outlook.ExchangeUser

 Dim oDistListEntries As Outlook.AddressEntries

 'Obtain the AddressEntry for CurrentUser

 Set oExUser = _

 Application.Session.CurrentUser.AddressEntry.GetExchangeUser

 'Obtain distribution lists that the user's manager has joined

 Set oDistListEntries = oExUser.GetExchangeUserManager.GetMemberOfList

 For Each oAE In oDistListEntries

 If oAE.AddressEntryUserType = _

 olExchangeDistributionListAddressEntry Then

 Debug.Print (oAE.name)

 End If

 Next

End Sub

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.GetPicture Method (Outlook)

 Copy code hover
[image]

ExchangeUser.GetPicture Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains an IPictureDisp object that represents the picture of the Microsoft Exchange user that is displayed in Microsoft Outlook.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetPicture

expression A variable that represents an ExchangeUser object.

Return Value

An IPictureDisp object that represents the picture of the Exchange user that is displayed in Outlook.

Remarks

The picture of the Exchange user is stored in Active Directory and displayed in various places in Outlook, including the dialog box for Outlook Properties and Contact Card.

If the picture does not exist for the user, GetPicture returns Null (Nothing for Visual Basic).

You can only call GetPicture from code that runs in-process as Outlook. An StdPicture object cannot be marshaled across process boundaries. If you attempt to call GetPicture from out-of-process code, an exception occurs. For more information, see An automation server cannot pass a pointer to the picture object's IPictureDisp implementation across process boundaries.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


ExchangeUser.Update Method (Outlook)

 Copy code hover
[image]

ExchangeUser.Update Method (Outlook)
See also Send feedback

Published: July 16, 2012

Posts a change to the ExchangeUser object in the messaging system.

Version Information

Version Added: Outlook 2007

Syntax

expression .Update(MakePermanent, Refresh)

expression A variable that represents an ExchangeUser object.

Parameters

Name | Required/Optional | Data Type | Description
MakePermanent | Optional | Variant | A value of True indicates that the property cache is flushed and all changes are committed in the underlying address book. A value of False indicates that the property cache is flushed but not committed to persistent storage. The default value is True.
Refresh | Optional | Variant | A value of True indicates that the property cache is reloaded from the values in the underlying address book. A value of False indicates that the property cache is not reloaded. The default value is False.

Remarks

New entries or changes to existing entries are not persisted in the collection until the Update method has been called with its MakePermanent parameter set to True.

To flush the cache and then reload the values from the address book, call Update with the MakePermanent parameter set to False and the Refresh parameter set to True.

See also

Concepts

ExchangeUser Object

Other resources

ExchangeUser Object Members


Explorer Object (Outlook)

 Copy code hover
[image]

Explorer Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the window in which the contents of a folder are displayed.

Remarks

  • Use the Item method of the Explorers object to return the object representing a specific explorer.

  • Use the ActiveExplorer method to return the object representing the currently active explorer (if there is one).

  • Use the GetExplorer method to return the Explorer object associated with a folder.

  • Use the Display method of a Folder object to display a folder in its associated explorer.

See also

Concepts

Outlook Object Model Reference

Other resources

Explorer Object Members


Explorer Members (Outlook)

 Copy code hover
[image]

Explorer Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the window in which the contents of a folder are displayed.

Events

Name | Description
Activate | Occurs when an explorer becomes the active window, either as a result of user action or through program code.
AttachmentSelectionChange | Occurs when the user selects a different or additional attachment in the active explorer programmatically or by interacting with the user interface.
BeforeFolderSwitch | Occurs before the explorer goes to a new folder, either as a result of user action or through program code.
BeforeItemCopy | Occurs when an Outlook item is copied.
BeforeItemCut | Occurs when an Outlook item is cut from a folder.
BeforeItemPaste | Occurs when an Outlook item is pasted.
BeforeMaximize | Occurs when an explorer is maximized by the user.
BeforeMinimize | Occurs when the active explorer is minimized by the user.
BeforeMove | Occurs when the Explorer is moved by the user.
BeforeSize | Occurs when the user sizes the current Explorer.
BeforeViewSwitch | Occurs before the explorer changes to a new view, either as a result of user action or through program code.
Close | Occurs when an explorer is being closed.
Deactivate | Occurs when an explorer stops being the active window, either as a result of user action or through program code.
FolderSwitch | Occurs when the explorer goes to a new folder, either as a result of user action or through program code.
InlineResponse | Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.
InlineResponseClose | Occurs when the user performs an action that causes the active inline response to close in the Reading Pane.
SelectionChange | Occurs when the user selects a different or additional Microsoft Outlook item programmatically or by interacting with the user interface.
ViewSwitch | Occurs when the view in the explorer changes, either as a result of user action or through program code.

Methods

Name | Description
Activate | Activates an explorer window by bringing it to the foreground and setting keyboard focus.
AddToSelection | Adds the specified Microsoft Outlook item to the selection in the active explorer.
ClearSearch | Clears results from a Microsoft Instant Search in an Explorer if results are displayed in the Explorer.
ClearSelection | Cancels any selection in the active explorer.
Close | Closes the Explorer object.
Display | Displays a new Explorer object for the folder.
IsItemSelectableInView | Returns a value that indicates whether the specified Microsoft Outlook item can be selected in the current view of the active explorer.
IsPaneVisible | Returns a Boolean indicating whether a specific explorer pane is visible.
RemoveFromSelection | Cancels the selection of the specified Microsoft Outlook item in the active explorer.
Search | Performs a Microsoft Instant Search on the current folder displayed in the Explorer using the given Query.
SelectAllItems | Selects all items that are contained in the current view of the active explorer.
ShowPane | Displays or hides a specific pane in the explorer.

Properties

Name | Description
AccountSelector | Returns an AccountSelector object that represents the Microsoft Office Backstage view for the Explorer object. Read-only.
ActiveInlineResponse | Returns an item object representing the active inline response item in the explorer reading pane. Read-only.
ActiveInlineResponseWordEditor | Returns the Word Document object of the active inline response that is displayed in the explorer Reading Pane. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AttachmentSelection | Returns an AttachmentSelection object consisting of one or more attachments that are selected in the current view of the explorer. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentFolder | Returns or sets a Folder object that represents the current folder displayed in the explorer. Read/write.
CurrentView | Returns or sets a Variant representing the current view. Read/write.
Height | Returns or sets a Long specifying the height (in pixels) of the explorer window. Read/write.
HTMLDocument | Returns an HTMLDocument object that specifies the HTML object model associated with the HTML document in the current view (assuming one exists). Read-only.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an explorer window from the edge of the screen. Read/write.
NavigationPane | Returns a NavigationPane object that represents the Navigation Pane for an Explorer object. Read-only.
Panes | Returns a Panes collection object representing the panes displayed by the specified explorer.
Parent | Returns the parent Object of the specified object. Read-only.
Selection | Returns a Selection object that contains the item or items that are selected in the explorer window. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an explorer window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.
WindowState | Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.


Explorer Properties (Outlook)

 Copy code hover
[image]

Explorer Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AccountSelector | Returns an AccountSelector object that represents the Microsoft Office Backstage view for the Explorer object. Read-only.
ActiveInlineResponse | Returns an item object representing the active inline response item in the explorer reading pane. Read-only.
ActiveInlineResponseWordEditor | Returns the Word Document object of the active inline response that is displayed in the explorer Reading Pane. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AttachmentSelection | Returns an AttachmentSelection object consisting of one or more attachments that are selected in the current view of the explorer. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentFolder | Returns or sets a Folder object that represents the current folder displayed in the explorer. Read/write.
CurrentView | Returns or sets a Variant representing the current view. Read/write.
Height | Returns or sets a Long specifying the height (in pixels) of the explorer window. Read/write.
HTMLDocument | Returns an HTMLDocument object that specifies the HTML object model associated with the HTML document in the current view (assuming one exists). Read-only.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an explorer window from the edge of the screen. Read/write.
NavigationPane | Returns a NavigationPane object that represents the Navigation Pane for an Explorer object. Read-only.
Panes | Returns a Panes collection object representing the panes displayed by the specified explorer.
Parent | Returns the parent Object of the specified object. Read-only.
Selection | Returns a Selection object that contains the item or items that are selected in the explorer window. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an explorer window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.
WindowState | Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.


Explorer.AccountSelector Property (Outlook)

 Copy code hover
[image]

Explorer.AccountSelector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AccountSelector object that represents the Microsoft Office Backstage view for the Explorer object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .AccountSelector

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ActiveInlineResponse Property (Outlook)

 Copy code hover
[image]

Explorer.ActiveInlineResponse Property (Outlook)
See also Send feedback

Returns an item object representing the active inline response item in the explorer reading pane. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .ActiveInlineResponse

expression A variable that represents an Explorer object.

Remarks

You can use the same properties and methods of the MailItem object on this item, except for the following:

  • MailItem.Actions property

  • MailItem.Close method

  • MailItem.Copy method

  • MailItem.Delete method

  • MailItem.Forward method

  • MailItem.Move method

  • MailItem.Reply method

  • MailItem.ReplyAll method

  • MailItem.Send method

This property returns Null (Nothing in Visual Basic) if no inline response is visible in the Reading Pane.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ActiveInlineResponseWordEditor Property (Outlook)

 Copy code hover
[image]

Explorer.ActiveInlineResponseWordEditor Property (Outlook)
See also Send feedback

Returns the Word Document object of the active inline response that is displayed in the explorer Reading Pane. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .ActiveInlineResponseWordEditor

expression A variable that represents an Explorer object.

Remarks

This property returns Null (Nothing in Visual Basic) if no inline response is visible in the Reading Pane. The returned Word Document object provides access to most of the Word object model except for the following members:

  • InlineShapes.AddChart2

  • Range.ConvertToTable

  • Range.ImportFragment

  • Range.InsertXML

  • Shapes.AddChart2

  • Selection.InsertXML

  • Tables.Add

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Application Property (Outlook)

 Copy code hover
[image]

Explorer.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.AttachmentSelection Property (Outlook)

 Copy code hover
[image]

Explorer.AttachmentSelection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AttachmentSelection object consisting of one or more attachments that are selected in the current view of the explorer. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .AttachmentSelection

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Caption Property (Outlook)

 Copy code hover
[image]

Explorer.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the title. Read-only.

Syntax

expression .Caption

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Class Property (Outlook)

 Copy code hover
[image]

Explorer.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.CurrentFolder Property (Outlook)

 Copy code hover
[image]

Explorer.CurrentFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Folder object that represents the current folder displayed in the explorer. Read/write.

Syntax

expression .CurrentFolder

expression A variable that represents an Explorer object.

Remarks

Use this property to change the folder the user is viewing.

Example

This Visual Basic for Applications (VBA) example uses the CurrentFolder property to change the displayed folder to the user's Calendar folder.

VBA Copy code Copy code
Sub ChangeCurrentFolder()

 Dim myNamespace As Outlook.NameSpace

 Set myNamespace = Application.GetNamespace("MAPI")

 Set Application.ActiveExplorer.CurrentFolder = _

 myNamespace.GetDefaultFolder(olFolderCalendar)

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.CurrentView Property (Outlook)

 Copy code hover
[image]

Explorer.CurrentView Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant representing the current view. Read/write.

Syntax

expression .CurrentView

expression A variable that represents an Explorer object.

Remarks

To obtain a View object for the view of the current Explorer, use Explorer.CurrentView instead of the CurrentView property of the current Folder object returned by Explorer.CurrentFolder.

You must save a reference to the View object returned by CurrentView before you proceed to use it for any purpose.

To properly reset the current view, you must do a View.Reset and then a View.Apply. The code sample below illustrates the order of the calls:

VBA Copy code Copy code
Sub ResetView()

 Dim v as Outlook.View

 ' Save a reference to the current view object

 Set v = Application.ActiveExplorer.CurrentView

 ' Reset and then apply the current view

 v.Reset

 v.Apply

End Sub

When this property is set, two events occur: BeforeViewSwitch occurs before the actual view change takes place and can be used to cancel the change and ViewSwitch takes place after the change is effective.

Example

The following Visual Basic for Applications (VBA) example sets the current view in the active explorer to messages if the Inbox is displayed.

VBA Copy code Copy code
Sub ChangeCurrentView()

 Dim myOlExp As Outlook.Explorer

 Set myOlExp = Application.ActiveExplorer

 If myOlExp.CurrentFolder = "Inbox" Then

 myOlExp.CurrentView = "Messages"

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Height Property (Outlook)

 Copy code hover
[image]

Explorer.Height Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the height (in pixels) of the explorer window. Read/write.

Syntax

expression .Height

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.HTMLDocument Property (Outlook)

 Copy code hover
[image]

Explorer.HTMLDocument Property (Outlook)
See also Send feedback

Returns an HTMLDocument object that specifies the HTML object model associated with the HTML document in the current view (assuming one exists). Read-only.

Syntax

expression .HTMLDocument

expression A variable that represents an Explorer object.

Remarks

In order to use this property, a folder must be using a folder home page, or you can set the WebViewURL property of the Folder object to a Web page.

Example

The following Microsoft Visual Basic for Applications (VBA) example accesses the Microsoft Outlook View Control.

VBA Copy code Copy code
 Sub GetHTML()

'Returns the Outlook View Control

 Dim objVC As OLXLib.ViewCtl

 Dim objExp As Outlook.Explorer

 Dim HTMLDoc As MSHTML.HTMLDocument

 'Reference the current folder

 Set objExp = Application.ActiveExplorer

 'Reference the HTML file that is the home page

 Set HTMLDoc = objExp.HTMLDocument

 'Reference an Outlook View Control that is on the HTML page

 Set objVC = HTMLDoc.all.tags("object").Item(0).Object

 'Have the control display an address book window

 objVC.AddressBook

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Left Property (Outlook)

 Copy code hover
[image]

Explorer.Left Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an explorer window from the edge of the screen. Read/write.

Syntax

expression .Left

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.NavigationPane Property (Outlook)

 Copy code hover
[image]

Explorer.NavigationPane Property (Outlook)
See also Send feedback

Returns a NavigationPane object that represents the Navigation Pane for an Explorer object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationPane

expression A variable that represents an Explorer object.

Remarks

Some Explorer objects may not have an associated NavigationPane object. In such cases, this property returns Null (Nothing in Visual Basic.)

Example

The following Visual Basic for Applications (VBA) sample retrieves the NavigationPane object from the active Explorer object and then displays information about the number of navigation modules contained and displayed by the object.

Copy code Copy code
Sub DisplayModuleCounts()

 Dim objPane As NavigationPane

 ' Get the NavigationPane object for the

 ' currently displayed Explorer object.

 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Display information about modules contained

 ' by the NavigationPane object.

 MsgBox "The Navigation Pane currently contains " & _

 objPane.Modules.Count & _

 " modules, of which " & _

 objPane.DisplayedModuleCount & _

 " are displayed."

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Panes Property (Outlook)

 Copy code hover
[image]

Explorer.Panes Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Panes collection object representing the panes displayed by the specified explorer.

Syntax

expression .Panes

expression A variable that represents an Explorer object.

Example

This Microsoft Visual Basic for Applications (VBA) example adds a group named "Marketing" as the second group in the Shortcuts pane.

VBA Copy code Copy code
Sub AddGroup()
 Dim myolBar As Outlook.OutlookBarPane

 Set myolBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 myolBar.Contents.Groups.Add "Sales", myolBar.Contents.Groups.Count + 1
End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Parent Property (Outlook)

 Copy code hover
[image]

Explorer.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Selection Property (Outlook)

 Copy code hover
[image]

Explorer.Selection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Selection object that contains the item or items that are selected in the explorer window. Read-only.

Syntax

expression .Selection

expression A variable that represents an Explorer object.

Remarks

The location of a selection in the explorer can be in the view list, the appointment list or task list in the To-Do Bar, or the daily tasks list in a calendar view. For more information, see the Location property.

The Selection property does not include any conversation header objects. Call the Selection.GetSelection method, providing olConversationHeaders as the argument, to obtain conversation header objects that are selected in the explorer.

If the current folder displays a folder home page, this property returns an empty collection. Also, if a group header such as Today, or a conversation group header is selected, the Count property on the returned Selection object is zero.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the sender of each selected item in the active explorer. It uses the Count property and the Item method of the Selection object that is returned by the Explorer.Selection property to display the senders of all messages that are selected in the active explorer.

VBA Copy code Copy code
Sub GetSelectedItems()

 Dim myOlExp As Outlook.Explorer

 Dim myOlSel As Outlook.Selection

 Dim mySender As Outlook.AddressEntry

 Dim oMail As Outlook.MailItem

 Dim oAppt As Outlook.AppointmentItem

 Dim oPA As Outlook.PropertyAccessor

 Dim strSenderID As String

 Const PR_SENT_REPRESENTING_ENTRYID As String = _

 "http://schemas.microsoft.com/mapi/proptag/0x00410102"

 Dim MsgTxt As String

 Dim x As Long

 MsgTxt = "Senders of selected items:"

 Set myOlExp = Application.ActiveExplorer

 Set myOlSel = myOlExp.Selection

 For x = 1 To myOlSel.Count

 If myOlSel.Item(x).Class = OlObjectClass.olMail Then

 ' For mail item, use the SenderName property.

 Set oMail = myOlSel.Item(x)

 MsgTxt = MsgTxt & oMail.SenderName & ";"

 ElseIf myOlSel.Item(x).Class = OlObjectClass.olAppointment Then

 ' For appointment item, use the Organizser property.

 Set oAppt = myOlSel.Item(x)

 MsgTxt = MsgTxt & oAppt.Organizer & ";"

 Else

 ' For other items, use the property accessor to get the sender ID,

 ' then get the address entry to display the sender name.

 Set oPA = myOlSel.Item(x).PropertyAccessor

 strSenderID = oPA.GetProperty(PR_SENT_REPRESENTING_ENTRYID)

 Set mySender = Application.Session.GetAddressEntryFromID(strSenderID)

 MsgTxt = MsgTxt & mySender.Name & ";"

 End If

 Next x

 Debug.Print MsgTxt

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Session Property (Outlook)

 Copy code hover
[image]

Explorer.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Explorer object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Top Property (Outlook)

 Copy code hover
[image]

Explorer.Top Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an explorer window from the edge of the screen. Read/write.

Syntax

expression .Top

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Width Property (Outlook)

 Copy code hover
[image]

Explorer.Width Property (Outlook)
See also Send feedback

Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.

Syntax

expression .Width

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.WindowState Property (Outlook)

 Copy code hover
[image]

Explorer.WindowState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.

Syntax

expression .WindowState

expression A variable that represents an Explorer object.

Example

This Microsoft Visual Basic for Applications example minimizes all open explorer windows. It uses the Count property and Item method of the Explorers collection to enumerate the open explorer windows.

VBA Copy code Copy code
Sub MinimizeWindows()

 Dim myOlExp As Outlook.Explorer

 Dim myOlExps As Outlook.Explorers

 Set myOlExps = Application.Explorers

 For x = 1 To myOlExps.Count

 myOlExps.Item(x).WindowState = olMinimized

 Next x

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer Methods (Outlook)

 Copy code hover
[image]

Explorer Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Activate | Activates an explorer window by bringing it to the foreground and setting keyboard focus.
AddToSelection | Adds the specified Microsoft Outlook item to the selection in the active explorer.
ClearSearch | Clears results from a Microsoft Instant Search in an Explorer if results are displayed in the Explorer.
ClearSelection | Cancels any selection in the active explorer.
Close | Closes the Explorer object.
Display | Displays a new Explorer object for the folder.
IsItemSelectableInView | Returns a value that indicates whether the specified Microsoft Outlook item can be selected in the current view of the active explorer.
IsPaneVisible | Returns a Boolean indicating whether a specific explorer pane is visible.
RemoveFromSelection | Cancels the selection of the specified Microsoft Outlook item in the active explorer.
Search | Performs a Microsoft Instant Search on the current folder displayed in the Explorer using the given Query.
SelectAllItems | Selects all items that are contained in the current view of the active explorer.
ShowPane | Displays or hides a specific pane in the explorer.


Explorer.Activate Method (Outlook)

 Copy code hover
[image]

Explorer.Activate Method (Outlook)
See also Send feedback

Activates an explorer window by bringing it to the foreground and setting keyboard focus.

Syntax

expression .Activate

expression A variable that represents an Explorer object.

Example

This Microsoft Visual Basic for Applications example responds to the NewMail event by activating the explorer window. The sample code must be placed in a class module, and the Initialize_handlers routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handlers()
 Set myOlExp = Application.ActiveExplorer
End Sub

Private Sub NewMail()
 myOlExp.Activate
End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.AddToSelection Method (Outlook)

 Copy code hover
[image]

Explorer.AddToSelection Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds the specified Microsoft Outlook item to the selection in the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .AddToSelection(Item)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item to add to the selection in the active explorer.

Remarks

The selection in the active explore is represented by the Selection object that is returned by the Explorer.Selection property.

To be selected, the item must be selectable in the current view of the active explorer. Use the IsItemSelectableInView method to determine whether the item can be selected in the view. The item does not have to be visible in the view.

Under the following conditions, Outlook returns an error when you call the AddToSelection method:

  • The specified item is not in the current view of the active explorer.

  • The specified item is being edited in the current view of the active explorer.

  • The current view has been filtered and the application of the filter removed the item from the view.

  • The specified item has not been saved.

  • The specified item represents a StorageItem.

  • No current view exists for the active explorer.

If the item is not selected and is selectable in the current view, calling AddToSelection causes the SelectionChange event to fire.

Calling AddToSelection does not scroll the view to make the selected item visible in the view and does not expand or collapse groups in the view.

The following table illustrates the results of calling AddToSelection, taking into consideration any current selection (the Selection.Count property) and whether the Reading Pane is displayed.

ExistingSelection.Count

Reading Pane Displayed

Results

0

Yes

  • The item is added to the selection.

  • SelectionChange fires.

  • Reading Pane displays the item.

0

No

  • The item is added to the selection.

  • SelectionChange fires.

>=1

Yes

  • The item is added to the selection.

  • SelectionChange fires.

  • Reading Pane does not change the item it displays unless the view is a Calendar view, in which case, calling AddToSelection can cause the Reading Pane to display a different item.

>=1

No

  • The item is added to the selection.

  • SelectionChange fires.

If the specified item is already selected in the active explorer, calling AddToSelection does not result in any change to the selection and the SelectionChange event does not fire.

When you specify an item in a recurring appointment or task as an argument to the AddToSelection method, make sure that before you pass the argument, you obtain an instance of the occurrence by first expanding the recurrences, using the IncludeRecurrences property and the Items collection. If you do not expand the recurrences and obtain an occurrence in the series, you pass an instance variable that represents the appointment or task series, and the AddToSelection method operates on the series instead of the occurrence.

Note that you can use AddToSelection to add items to a selection, but you cannot add conversation headers to a selection.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ClearSearch Method (Outlook)

 Copy code hover
[image]

Explorer.ClearSearch Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears results from a Microsoft Instant Search in an Explorer if results are displayed in the Explorer.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearSearch

expression A variable that represents an Explorer object.

Remarks

The functionality of this method is analogous to the Clear button in Instant Search.

If no search results are displayed in the Explorer, ClearSearch will not take any action. If the current view of the Explorer does not present a search view, ClearSearch will not raise an error.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ClearSelection Method (Outlook)

 Copy code hover
[image]

Explorer.ClearSelection Method (Outlook)
See also Send feedback

Cancels any selection in the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .ClearSelection

expression A variable that represents an Explorer object.

Remarks

After the ClearSelection method is called, the Count property of the Selection object that the Explorer.Selection property returns is zero. Then, the SelectionChange event fires unless prior to calling of ClearSelection, the current view did not contain any items, the current folder was empty, or the Count property was already zero.

If the Reading Pane is visible and the current view is a table view, calling ClearSelection renders the Reading Pane blank.

If the current view or current folder does not contain any items, calling ClearSelection does not result in any change to the selection and does not fire the SelectionChange event.

ClearSelection returns an error if the item is being edited in the current view.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Close Method (Outlook)

 Copy code hover
[image]

Explorer.Close Method (Outlook)
See also Send feedback

Closes the Explorer object.

Syntax

expression .Close()

expression A variable that represents an Explorer object.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Display Method (Outlook)

 Copy code hover
[image]

Explorer.Display Method (Outlook)
See also Send feedback

Displays a new Explorer object for the folder.

Syntax

expression .Display()

expression A variable that represents an Explorer object.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.IsItemSelectableInView Method (Outlook)

 Copy code hover
[image]

Explorer.IsItemSelectableInView Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a value that indicates whether the specified Microsoft Outlook item can be selected in the current view of the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .IsItemSelectableInView(Item)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item that is being considered for selection.

Return Value

A Boolean value that indicates whether the specified item can be selected in the current view.

Remarks

Returns True if the item can be selected in the current view; otherwise returns False.

The method returns True or False depending on whether the item is selectable in the view. It does not indicate whether the item is visible in the view. If the item is contained within a collapsed group in the view, the method returns False.

If in-cell editing is turned on for the current view for the active explorer and in-cell editing is in progress on the item, the method returns False. If the current view is a table view, you can check for in-cell editing by using the AllowInCellEditing property of the TableView object. Similarly, if the current view is a card view, you can use the AllowInCellEditing property of the CardView object.

When you specify an item in a recurring appointment or task as argument to the IsItemSelectableInView method, make sure that before you pass the argument, you obtain an instance of the occurrence by first expanding the recurrences, using the IncludeRecurrences property and the Items collection. If you do not expand the recurrences and obtain an occurrence in the series, you would be passing an instance variable that represents the appointment or task series, and the IsItemSelectableInView method would be operating on the series instead of the occurrence.

The IsItemSelectableInView method raises an error if the current view is a conversation view.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.IsPaneVisible Method (Outlook)

 Copy code hover
[image]

Explorer.IsPaneVisible Method (Outlook)
See also Send feedback

Returns a Boolean indicating whether a specific explorer pane is visible.

Syntax

expression .IsPaneVisible(Pane)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Pane | Required | OlPane | The pane to check.

Return Value

True if the specified pane is displayed in the explorer; otherwise, False.

Remarks

You can also use the Visible property of the OutlookBarPane object to determine whether the Shortcuts pane is visible.

Example

This Microsoft Visual Basic for Applications (VBA) sample uses the IsPaneVisible method to determine whether the preview pane is visible and uses the ShowPane method to display it if it is not visible. Use the olNavigationPane constant to hide or display the Navigation Pane.

VBA Copy code Copy code
Sub HidePreviewPane()

 Dim myOlExp As Outlook.Explorer

 Set myOlExp = Application.ActiveExplorer

 If myOlExp.IsPaneVisible(olPreview) = False Then

 myOlExp.ShowPane olPreview, True

 End If

 Set myOlExp = Nothing

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.RemoveFromSelection Method (Outlook)

 Copy code hover
[image]

Explorer.RemoveFromSelection Method (Outlook)
See also Send feedback

Published: July 16, 2012

Cancels the selection of the specified Microsoft Outlook item in the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .RemoveFromSelection(Item)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item to be removed from the selection.

Remarks

The selection in the active explore is represented by the Selection object returned by the Explorer.Selection property.

To be removed from a selection, an item must be selectable in the current view of the active explorer. However, the item does not have to be visible in the view.

Outlook will return an error when you call the RemoveFromSelection method under the following conditions:

  • The specified item is not in the current view of the active explorer.

  • The specified item is being edited in the current view of the active explorer.

  • The current view has been filtered and the application of the filter removed the item from the view.

  • The specified item has not been saved.

  • The specified item represents a StorageItem.

  • The current view is a conversation view.

  • No current view exists for the active explorer.

If the specified item is selected, calling RemoveFromSelection will cause the SelectionChange event to fire. If the item is not selected, calling RemoveFromSelection will not cause the SelectionChange event to fire.

Calling RemoveFromSelection does not scroll the view to make the specified item visible in the view and does not expand or collapse groups in the view.

The following table illustrates the results of calling RemoveFromSelection, taking into consideration any current selection (the Selection.Count property), whether the Reading Pane is displayed, and whether the specified item is displayed in the Reading Pane.

ExistingSelection.Count

Reading Pane Displayed

Specified Item Displayed in Reading Pane

Results

1

Yes

Yes

  • The selection is cleared.

  • SelectionChange fires.

  • Reading Pane is empty.

>1

Yes

No

  • The item is removed from the selection.

  • SelectionChange fires.

  • Reading Pane does not change.

>1

Yes

Yes

  • The item is removed from the selection.

  • SelectionChange fires.

  • Reading Pane displays the next item or adjacent item in the selection.

>=1

No

N/A

  • The item is removed from the selection.

  • SelectionChange fires.

If the specified item exists in the current view but is not selected in that view, calling RemoveFromSelection does not result in any change to the selection and does not fire the SelectionChange event.

When you specify an item in a recurring appointment or task as an argument to the RemoveFromSelection method, make sure that before you pass the argument, you obtain an instance of the occurrence by first expanding the recurrences, using the IncludeRecurrences property and the Items collection. If you do not expand the recurrences and obtain an occurrence in the series, you would be passing an instance variable that represents the appointment or task series, and the RemoveFromSelection method would be operating on the series instead of the occurrence.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Search Method (Outlook)

 Copy code hover
[image]

Explorer.Search Method (Outlook)
See also Send feedback

Performs a Microsoft Instant Search on the current folder displayed in the Explorer using the given Query.

Version Information

Version Added: Outlook 2007

Syntax

expression .Search(Query, SearchScope)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Query | Required | String | A search string that can contain any valid keywords supported in Instant Search.
SearchScope | Optional | OlSearchScope | Specifies the scope in terms of folders for the search.

Remarks

The functionality of Explorer.Search is analogous to the Search button in Instant Search. It behaves as if the user has typed the query string in the Instant Search user interface and then clicked Search. When calling Search, the query is run in the user interface, and there is no programmatic mechanism to obtain the search results. For more information on Instant Search, query for "Instant Search" in the Outlook Help.

The Search method does not provide a callback to enable the developer to determine when the search is complete.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.SelectAllItems Method (Outlook)

 Copy code hover
[image]

Explorer.SelectAllItems Method (Outlook)
See also Send feedback

Published: July 16, 2012

Selects all items that are contained in the current view of the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectAllItems

expression A variable that represents an Explorer object.

Remarks

If one or more groups are collapsed in the current view, calling SelectAllItems does not select items in the collapsed groups. Only items in expanded groups are selected.

If the current view is a calendar view, calling SelectAllItems selects all appointments and all-day events in the view. Calling SelectAllItems on a calendar view does not select items in the Daily Task List.

The SelectionChange event fires only once after the SelectAllItems method is called.

If the current view or current folder does not contain any items, calling SelectAllItems does not result in any change to the selection and does not fire the SelectionChange event.

SelectAllItems raises an error if the item is being edited in the current view, or the current view is a conversation view.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ShowPane Method (Outlook)

 Copy code hover
[image]

Explorer.ShowPane Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays or hides a specific pane in the explorer.

Syntax

expression .ShowPane(Pane, Visible)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Pane | Required | OlPane | The pane to display.
Visible | Required | Boolean | True to make the pane visible, False to hide the pane.

Remarks

Note Note

You can also use the Visible property of the OutlookBarPane object to display or hide the Outlook Bar.

Example

This Microsoft Visual Basic for Applications (VBA) example uses the ShowPane and IsPaneVisible methods to hide the preview pane if it is visible or to display it if it is hidden.

VBA Copy code Copy code
Sub ShowHidePreviewPane()

 Dim myOlExp As Outlook.Explorer

 Set myOlExp = Application.ActiveExplorer

 myOlExp.ShowPane olPreview, _

 Not myOlExp.IsPaneVisible(olPreview)

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer Events (Outlook)

 Copy code hover
[image]

Explorer Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
Activate | Occurs when an explorer becomes the active window, either as a result of user action or through program code.
AttachmentSelectionChange | Occurs when the user selects a different or additional attachment in the active explorer programmatically or by interacting with the user interface.
BeforeFolderSwitch | Occurs before the explorer goes to a new folder, either as a result of user action or through program code.
BeforeItemCopy | Occurs when an Outlook item is copied.
BeforeItemCut | Occurs when an Outlook item is cut from a folder.
BeforeItemPaste | Occurs when an Outlook item is pasted.
BeforeMaximize | Occurs when an explorer is maximized by the user.
BeforeMinimize | Occurs when the active explorer is minimized by the user.
BeforeMove | Occurs when the Explorer is moved by the user.
BeforeSize | Occurs when the user sizes the current Explorer.
BeforeViewSwitch | Occurs before the explorer changes to a new view, either as a result of user action or through program code.
Close | Occurs when an explorer is being closed.
Deactivate | Occurs when an explorer stops being the active window, either as a result of user action or through program code.
FolderSwitch | Occurs when the explorer goes to a new folder, either as a result of user action or through program code.
SelectionChange | Occurs when the user selects a different or additional Microsoft Outlook item programmatically or by interacting with the user interface.
ViewSwitch | Occurs when the view in the explorer changes, either as a result of user action or through program code.
InlineResponse | Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.
InlineResponseClose | Occurs when the user performs an action that causes the active inline response to close in the Reading Pane.


Explorer.Activate Event (Outlook)

 Copy code hover
[image]

Explorer.Activate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explorer becomes the active window, either as a result of user action or through program code.

Syntax

expression .Activate

expression A variable that represents an Explorer object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This code example uses the WindowState property to maximize the topmost explorer window when the Activate event occurs. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_Activate()

 If myOlExp.WindowState = olNormalWindow Then _

 myOlExp.WindowState = olMaximized

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.AttachmentSelectionChange Event (Outlook)

 Copy code hover
[image]

Explorer.AttachmentSelectionChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects a different or additional attachment in the active explorer programmatically or by interacting with the user interface.

Version Information

Version Added: Outlook 2010

Syntax

expression .AttachmentSelectionChange

expression A variable that represents an Explorer object.

Remarks

The AttachmentSelectionChange event fires when a different or additional attachment of any item is selected in the active explorer.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeFolderSwitch Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeFolderSwitch Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the explorer goes to a new folder, either as a result of user action or through program code.

Syntax

expression .BeforeFolderSwitch(NewFolder, Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
NewFolder | Required | Object | The Folder object the explorer is switching to.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, navigation is cancelled, and the current folder is not changed.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

If the folder being switched to is in a namespace that doesn't support automation (such as the file system), NewFolder is Nothing.

Example

This sample prevents a user from switching to a folder named "Off Limits". The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook. To run this example without errors, make sure a folder by the name 'Off Limits' exists in the folder displayed in the active explorer.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeFolderSwitch(ByVal NewFolder As Object, Cancel As Boolean)

 If NewFolder.Name = "Off Limits" Then

 MsgBox "You do not have permission to access this folder."

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeItemCopy Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeItemCopy Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an Outlook item is copied.

Syntax

expression .BeforeItemCopy(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not copied.

Remarks

This event can be cancelled after it has started.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user before an item is copied. A message is displayed to the user verifying that the item should be copied. If the user clicks Yes, the item is copied to the Clipboard. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()

Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeItemCopy(Cancel As Boolean)

'Prompts the user before copying an item

 Dim lngAns As Long 'user answer

 'Display question to user

 lngAns = MsgBox("Are you sure you want to copy the item?", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 'Set Cancel argument based on answer

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeItemCut Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeItemCut Event (Outlook)
See also Send feedback

Occurs when an Outlook item is cut from a folder.

Syntax

expression .BeforeItemCut(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

This event can be cancelled after it has started. If the event is canceled, then the item will not be removed.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a warning message before the item is cut from the folder. If the user clicks Yes, the item is cut from the folder. If the user clicks No, the item will not be removed from the folder. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()
Set myOlExp = Application.ActiveExplorer
End Sub

Private Sub myOlExp_BeforeItemCut(Cancel As Boolean)
'Prompts the user before cutting an item

 Dim lngAns As Long
 'Display question to user
 lngAns = MsgBox("Are you sure you want to cut the item?", vbYesNo)
 'Set cancel argument based on user's answer
 If lngAns = vbYes Then
 Cancel = False
 ElseIf lngAns = vbNo Then
 Cancel = True
 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeItemPaste Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeItemPaste Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an Outlook item is pasted.

Syntax

expression .BeforeItemPaste(ClipboardContent, Target, Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
ClipboardContent | Required | Variant | The content to be pasted.
Target | Required | Folder | The destination of the paste.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

This event can be cancelled after it has started.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user before pasting the contents of the Clipboard to the specified target. If the user clicks Yes, the current content in the Clipboard is copied to the specified target destination. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeItemPaste(ClipboardContent As Variant, ByVal Target As Folder, Cancel As Boolean)

 Dim lngAns As Integer 'users' answer

 'Prompt user about paste

 lngAns = MsgBox("Are you sure you want to paste the contents of the clipboard into the " _

 & Target.Name & "?", vbYesNo)

 If lngAns = vbNo Then

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeMaximize Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeMaximize Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explorer is maximized by the user.

Syntax

expression .BeforeMaximize(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the explorer is not maximized.

Remarks

This event can be cancelled after it has started.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a warning message before maximizing the current window. If the user clicks Yes, the explorer will maximize. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeMaximize(Cancel As Boolean)

'Prompts the user before maximizing the explorer

 Dim lngAns As Long

 lngAns = MsgBox("Are you sure you want to maximize the current window?", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeMinimize Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeMinimize Event (Outlook)
See also Send feedback

Occurs when the active explorer is minimized by the user.

Syntax

expression .BeforeMinimize(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the explorer is not minimized.

Remarks

This event can be cancelled after it has started.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a message before the window is minimized. If the user clicks Yes, the explorer is minimized. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeMinimize(Cancel As Boolean)

'Prompts the user before minimizing the Explorer

 Dim lngAns As Long

 lngAns = MsgBox("Are you sure you want to minimize the current window?", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeMove Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Explorer is moved by the user.

Syntax

expression .BeforeMove(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the explorer or inspector is not moved.

Remarks

This event can be cancelled after it has started.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a message before the explorer is moved by the user. If the user clicks Yes, the explorer can be moved by the user. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Sub Initalize_Handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeMove(Cancel As Boolean)

'Prompts the user before moving the window

 Dim lngAns As Long

 lngAns = MsgBox("Are you sure you want to move the current window? Use your keyboard to make your selection.", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeSize Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeSize Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user sizes the current Explorer.

Syntax

expression .BeforeSize(Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the Explorer is not sized.

Remarks

This event can be cancelled after it has started. If the event is cancelled, the window is not sized.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a warning message before the Inspector is sized. If the user clicks Yes, the inspector can be sized. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myIns As Outlook.Inspector

Public Sub Initalize_Handler()

 Set myIns = Application.ActiveInspector

End Sub

Private Sub myIns_BeforeSize(Cancel As Boolean)

 'Prompts the user before resizing the window

 Dim lngAns As Long

 lngAns = MsgBox("Are you sure you want to resize the current window? Use your keyboard to make your selection.", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 Cancel = True

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.BeforeViewSwitch Event (Outlook)

 Copy code hover
[image]

Explorer.BeforeViewSwitch Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the explorer changes to a new view, either as a result of user action or through program code.

Syntax

expression .BeforeViewSwitch(NewView, Cancel)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data Type | Description
NewView | Required | Variant | The name of the view the explorer is switching to.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the switch is cancelled and the current view is not changed.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example confirms that the user wants to switch views and cancels the switch if the user answers No. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_BeforeViewSwitch(ByVal NewView As Variant, Cancel As Boolean)

 Dim Prompt As String

 Prompt = "Are you sure you want to switch to the " & NewView & " view?"

 If MsgBox(Prompt, vbYesNo + vbQuestion) = vbNo Then Cancel = True

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Close Event (Outlook)

 Copy code hover
[image]

Explorer.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explorer is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents an Explorer object.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open. This event cannot be cancelled.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.Deactivate Event (Outlook)

 Copy code hover
[image]

Explorer.Deactivate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explorer stops being the active window, either as a result of user action or through program code.

Syntax

expression .Deactivate

expression A variable that represents an Explorer object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Visual Basic for Applications (VBA) example uses the WindowState property to minimize the topmost explorer window when it is not active. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_Deactivate()

 myOlExp.WindowState = olMinimized

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.FolderSwitch Event (Outlook)

 Copy code hover
[image]

Explorer.FolderSwitch Event (Outlook)
See also Send feedback

Occurs when the explorer goes to a new folder, either as a result of user action or through program code.

Syntax

expression .FolderSwitch

expression A variable that represents an Explorer object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the Inbox folder in "Messages" view whenever the user switches to the Inbox folder. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_FolderSwitch()

 Select Case myOlExp.CurrentFolder.Name

 Case "Inbox"

 myOlExp.CurrentView = "Messages"

 Case Else

 End Select

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.InlineResponse Event (Outlook)

 Copy code hover
[image]

Explorer.InlineResponse Event (Outlook)
See also Send feedback

Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.

Version information

Version Added: Outlook 2013

Syntax

expression .InlineResponse(Item)

expression A variable that represents an Explorer object.

Parameters

Name | Required/Optional | Data type | Description
Item | Required | Object | Represents the inline response item.
Item | Required | OBJECT |

Remarks

This event returns an item object representing the inline response item.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.InlineResponseClose Event (Outlook)

 Copy code hover
[image]

Explorer.InlineResponseClose Event (Outlook)
See also Send feedback

Occurs when the user performs an action that causes the active inline response to close in the Reading Pane.

Version information

Version Added: Outlook 2013

Syntax

expression .InlineResponseClose(Item)

expression A variable that represents an Explorer object.

Remarks

This event fires when a new inline response or draft inline response is closed for the following reasons:

  • The user selects the Pop Out command.

    The user selects the Discard command.

    The user sends the inline response.

    The user navigates to a different message in the message list.

    The user navigates to a different folder.

    The user switches modules, for example from the mail module to the Calendar module.

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.SelectionChange Event (Outlook)

 Copy code hover
[image]

Explorer.SelectionChange Event (Outlook)
See also Send feedback

Occurs when the user selects a different or additional Microsoft Outlook item programmatically or by interacting with the user interface.

Syntax

expression .SelectionChange

expression A variable that represents an Explorer object.

Remarks

This event also occurs when the user (either programmatically or via the user interface) clicks or switches to a different folder that contains items, because Outlook automatically selects the first item in that folder. However, this event does not occur if the folder is a file-system folder or if any folder with a current Web view is displayed. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the number of items that are selected in the active explorer window whenever the selection changes. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExp As Outlook.Explorer

Public Sub Initialize_handler()

 Set myOlExp = Application.ActiveExplorer

End Sub

Private Sub myOlExp_SelectionChange()

 MsgBox myOlExp.Selection.Count & " items selected."

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorer.ViewSwitch Event (Outlook)

 Copy code hover
[image]

Explorer.ViewSwitch Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the view in the explorer changes, either as a result of user action or through program code.

Syntax

expression .ViewSwitch

expression A variable that represents an Explorer object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Visual Basic for Applications (VBA) example hides the preview pane if it is visible when the user switches to Messages with AutoPreview view. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myOlExpl As Outlook.Explorer

Sub Initialize_handler()

 Set myOlExpl = Application.ActiveExplorer

End Sub

Private Sub myOlExpl_ViewSwitch()

 If myOlExpl.CurrentView = "Messages with AutoPreview" And myOlExpl.IsPaneVisible(olPreview) = True Then

 myOlExpl.ShowPane olPreview, False

 End If

End Sub

See also

Concepts

Explorer Object

Other resources

Explorer Object Members


Explorers Object (Outlook)

 Copy code hover
[image]

Explorers Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of Explorer objects representing all explorers.

Remarks

An explorer need not be visible to be included in the Explorers collection.

Use the Explorers property to return the Explorers object from the Application object.

Example

The following example shows how to retrieve the Explorers object in Microsoft Visual Basic and Microsoft Visual Basic for Applications (VBA).

VBA Copy code Copy code
Set myExplorers = Application.Explorers

See also

Concepts

Outlook Object Model Reference

Other resources

Explorers Object Members


Explorers Members (Outlook)

 Copy code hover
[image]

Explorers Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of Explorer objects representing all explorers.

Events

Name | Description
NewExplorer | Occurs whenever a new explorer window is opened, either as a result of user action or through program code.

Methods

Name | Description
Add | Creates a new instance of the explorer window.
Item | Returns an Explorer object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Explorers Properties (Outlook)

 Copy code hover
[image]

Explorers Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Explorers.Application Property (Outlook)

 Copy code hover
[image]

Explorers.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Explorers object.

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers.Class Property (Outlook)

 Copy code hover
[image]

Explorers.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Explorers object.

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers.Count Property (Outlook)

 Copy code hover
[image]

Explorers.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Explorers object.

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers.Parent Property (Outlook)

 Copy code hover
[image]

Explorers.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Explorers object.

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers.Session Property (Outlook)

 Copy code hover
[image]

Explorers.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Explorers object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers Methods (Outlook)

 Copy code hover
[image]

Explorers Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new instance of the explorer window.
Item | Returns an Explorer object from the collection.


Explorers.Add Method (Outlook)

 Copy code hover
[image]

Explorers.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new instance of the explorer window.

Syntax

expression .Add(Folder, DisplayMode)

expression A variable that represents an Explorers object.

Parameters

Name | Required/Optional | Data Type | Description
Folder | Required | Variant | The Variant object to display in the explorer window when it is created.
DisplayMode | Optional | Long | The display mode of the folder. Can be one of the OlFolderDisplayMode constants.

Return Value

An Explorer object that represents a new instance of the window.

Remarks

The Folder argument can represent either a Folder object or the URL to that folder.

The explorer window is initially hidden. You must call the Display method of the Explorer object to make it visible.

Example

The following VBA example displays the Drafts folder in an explorer window without a Navigation Pane or Folder List.

VBA Copy code Copy code
Sub DisplayDrafts()

 Dim myExplorers As Outlook.Explorers

 Dim myOlExpl As Outlook.Explorer

 Dim myFolder As Outlook.Folder

 Set myExplorers = Application.Explorers

 Set myFolder = Application.GetNamespace("MAPI").GetDefaultFolder _

 (olFolderDrafts)

 Set myOlExpl = myExplorers.Add _

 (myFolder, olFolderDisplayNoNavigation)

 myOlExpl.Display

End Sub

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers.Item Method (Outlook)

 Copy code hover
[image]

Explorers.Item Method (Outlook)
See also Send feedback

Returns an Explorer object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an Explorers object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Explorer object that represents the specified object.

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Explorers Events (Outlook)

 Copy code hover
[image]

Explorers Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
NewExplorer | Occurs whenever a new explorer window is opened, either as a result of user action or through program code.


Explorers.NewExplorer Event (Outlook)

 Copy code hover
[image]

Explorers.NewExplorer Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs whenever a new explorer window is opened, either as a result of user action or through program code.

Syntax

expression .NewExplorer(Explorer)

expression A variable that represents an Explorers object.

Parameters

Name | Required/Optional | Data Type | Description
Explorer | Required | Explorer | The explorer that was opened.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

The event occurs after the new Explorer object is created but before the explorer window appears.

Example

This Microsoft Visual Basic for Applications (VBA) example minimizes the currently active explorer window when a new explorer is about to appear. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlExplorers As Outlook.Explorers

Public Sub Initialize_handler()

 Set myOlExplorers = Application.Explorers

End Sub

Private Sub myOlExplorers_NewExplorer(ByVal Explorer As Outlook.Explorer)

 If TypeName(Application.ActiveExplorer) <> "Nothing" Then

 Application.ActiveExplorer.WindowState = olMinimized

 End If

End Sub

See also

Concepts

Explorers Object

Other resources

Explorers Object Members


Folder Object (Outlook)

 Copy code hover
[image]

Folder Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an Outlook folder.

Version Information

Version Added: Outlook 2007

Remarks

A Folder object can contain other Folder objects, as well as Outlook items. Use the Folders property of a NameSpace object or another Folder object to return the set of folders in a NameSpace or under a folder. You can navigate nested folders by starting from a top-level folder, say the Inbox, and using a combination of the Folder.Folders property, which returns the set of folders underneath a Folder object in the hierarchy, and the Folders.Item method, which returns a folder within the Folders collection.

There is a set of folders within an Outlook data store that supports the default functionality of Outlook. Use NameSpace.GetDefaultFolder, specifying an index that is one of the constants in the OlDefaultFolders enumeration to return one of the default Outlook folders in the Outlook NameSpace object.

While generally it is a good practice to place items that serve the same functionality in the same folder, a folder can contain items of different types. For example, by default, the Calendar folder can contain AppointmentItem and MeetingItem objects, and the Contacts folder can contain ContactItem and DistListItem objects. In general, when enumerating items in a folder, do not assume the type of an item in the folder; check the message class of the item before accessing properties that are applicable to the item.

Use the Folders.Add method to add a folder to the Folders object. The Add method has an optional argument that can be used to specify the type of items that can be stored in that folder. By default, folders created inside another folder inherit the type of the parent folder.

Note that when items of a specific type are saved, they are saved directly into their corresponding default folder. For example, when the MeetingItem.GetAssociatedAppointment method is applied to a MeetingItem in the Inbox folder, the appointment that is returned will be saved to the default Calendar folder.

See also

Concepts

Outlook Object Model Reference

Other resources

Folder Object Members


Folder Members (Outlook)

 Copy code hover
[image]

Folder Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an Outlook folder.

Events

Name | Description
BeforeFolderMove | Occurs when a folder is about to be moved or deleted, either as a result of user action or through program code.
BeforeItemMove | Occurs when an item is about to be moved or deleted from a folder, either as a result of user action or through program code.

Methods

Name | Description
AddToPFFavorites | Adds a Microsoft Exchange public folder to the public folder's Favorites folder.
CopyTo | Copies the current folder in its entirety to the destination folder.
Delete | Deletes an object from the collection.
Display | Displays a new Explorer object for the folder.
GetCalendarExporter | Creates a CalendarSharing object for the specified Folder.
GetCustomIcon | Returns an IPictureDisp object that represents the custom icon for the folder.
GetExplorer | Returns an Explorer object that represents a new, inactive Explorer object initialized with the specified folder as the current folder.
GetStorage | Gets a StorageItem object on the parent Folder to store data for an Outlook solution.
GetTable | Obtains a Table object that contains items filtered by Filter.
MoveTo | Moves a folder to the specified destination folder.
SetCustomIcon | Sets a custom icon that is specified by Picture for the folder.

Properties

Name | Description
AddressBookName | Returns or sets a String that indicates the Address Book name for the Folder object representing a Contacts folder. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentView | Returns a View object representing the current view. Read-only.
CustomViewsOnly | Returns or sets a Boolean that determines which views are displayed on the View menu for a given folder. Read/write.
DefaultItemType | Returns a constant from the OlItemType enumeration indicating the default Outlook item type contained in the folder. Read-only.
DefaultMessageClass | Returns a String representing the default message class for items in the folder. Read-only.
Description | Returns or sets a String representing the description of the folder. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FolderPath | Returns a String that indicates the path of the current folder. Read-only.
Folders | Returns the Folders collection that represents all the folders contained in the specified Folder. Read-only.
InAppFolderSyncObject | Returns or sets a Boolean that determines if the specified folder will be synchronized with the e-mail server. Read/write.
IsSharePointFolder | Returns a Boolean that determines if the folder is a Microsoft SharePoint Foundation folder. Read-only.
Items | Returns an Items collection object as a collection of Outlook items in the specified folder. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Folder object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowAsOutlookAB | Returns or sets a Boolean variable that specifies whether the contact items folder will be displayed as an address list in the Outlook Address Book. Read/write.
ShowItemCount | Sets or returns a constant in the OlShowItemCount enumeration that indicates whether to display the number of unread messages in the folder or the total number of items in the folder in the Navigation Pane. Read/write.
Store | Returns a Store object representing the store that contains the Folder object. Read-only.
StoreID | Returns a String indicating the store ID for the folder. Read-only.
UnReadItemCount | Returns a Long indicating the number of unread items in the folder. Read-only.
UserDefinedProperties | Returns a UserDefinedProperties object that represents the user-defined custom properties for the Folder object. Read-only.
Views | Returns the Views collection object of the Folder object. Read-only.
WebViewOn | Returns or sets a Boolean indicating the Web view state for a folder. Read/write.
WebViewURL | Returns or sets a String indicating the URL of the Web page that is assigned to a folder. Read/write.


Folder Properties (Outlook)

 Copy code hover
[image]

Folder Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AddressBookName | Returns or sets a String that indicates the Address Book name for the Folder object representing a Contacts folder. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentView | Returns a View object representing the current view. Read-only.
CustomViewsOnly | Returns or sets a Boolean that determines which views are displayed on the View menu for a given folder. Read/write.
DefaultItemType | Returns a constant from the OlItemType enumeration indicating the default Outlook item type contained in the folder. Read-only.
DefaultMessageClass | Returns a String representing the default message class for items in the folder. Read-only.
Description | Returns or sets a String representing the description of the folder. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FolderPath | Returns a String that indicates the path of the current folder. Read-only.
Folders | Returns the Folders collection that represents all the folders contained in the specified Folder. Read-only.
InAppFolderSyncObject | Returns or sets a Boolean that determines if the specified folder will be synchronized with the e-mail server. Read/write.
IsSharePointFolder | Returns a Boolean that determines if the folder is a Microsoft SharePoint Foundation folder. Read-only.
Items | Returns an Items collection object as a collection of Outlook items in the specified folder. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Folder object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowAsOutlookAB | Returns or sets a Boolean variable that specifies whether the contact items folder will be displayed as an address list in the Outlook Address Book. Read/write.
ShowItemCount | Sets or returns a constant in the OlShowItemCount enumeration that indicates whether to display the number of unread messages in the folder or the total number of items in the folder in the Navigation Pane. Read/write.
Store | Returns a Store object representing the store that contains the Folder object. Read-only.
StoreID | Returns a String indicating the store ID for the folder. Read-only.
UnReadItemCount | Returns a Long indicating the number of unread items in the folder. Read-only.
UserDefinedProperties | Returns a UserDefinedProperties object that represents the user-defined custom properties for the Folder object. Read-only.
Views | Returns the Views collection object of the Folder object. Read-only.
WebViewOn | Returns or sets a Boolean indicating the Web view state for a folder. Read/write.
WebViewURL | Returns or sets a String indicating the URL of the Web page that is assigned to a folder. Read/write.


Folder.AddressBookName Property (Outlook)

 Copy code hover
[image]

Folder.AddressBookName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that indicates the Address Book name for the Folder object representing a Contacts folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressBookName

expression A variable that represents a Folder object.

Remarks

If you try to set the AddressBookName property in a non-Contacts folder, an error will be returned.

Example

The following example changes the Address Book name for the default Contacts folder and displays the new name to the user. The subroutine accepts the folder object and a string representing the new address book name.

VBA Copy code Copy code
Sub BookName()

 Dim nmsName As Outlook.NameSpace

 Dim fldFolder As Outlook.Folder

 Dim strAns As String

 'Create a reference to namepsace

 Set nmsName = Application.GetNamespace("MAPI")

 'Create an instance of the Contacts folder

 Set fldFolder = nmsName.GetDefaultFolder(olFolderContacts)

 'Prompt user for input

 strAns = InputBox("Type the name of the new address book")

 'Call Sub procedure

 Call Changebook(fldFolder, strAns)

End Sub

Sub Changebook(ByRef fldFolder As Folder, ByVal strName As String)

 'Changes the name of the address book for a given folder

 'Set address book name to user input

 fldFolder.AddressBookName = strName

 'Display message to user

 MsgBox ("The new address book name for the " & fldFolder.Name & " folder is " _

 & strName & ".")

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Application Property (Outlook)

 Copy code hover
[image]

Folder.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Class Property (Outlook)

 Copy code hover
[image]

Folder.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.CurrentView Property (Outlook)

 Copy code hover
[image]

Folder.CurrentView Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a View object representing the current view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CurrentView

expression A variable that represents a Folder object.

Remarks

To obtain a View object for the view of the current Explorer, use Explorer.CurrentView instead of the CurrentView property of the current Folder object returned by Explorer.CurrentFolder.

You must save a reference to the View object returned by CurrentView before you proceed to use it for any purpose.

To properly reset the current view, you must do a View.Reset and then a View.Apply. The code sample below illustrates the order of the calls:

VBA Copy code Copy code
Sub ResetView()

 Dim v as Outlook.View

 ' Save a reference to the current view object

 Set v = Application.ActiveExplorer.CurrentView

 ' Reset and then apply the current view

 v.Reset

 v.Apply

End Sub

Example

The following VBA example displays the current view of the Inbox folder.

Copy code Copy code
Sub TestFolderCurrentView()

 Dim nsp As Outlook.NameSpace

 Dim mpFolder As Outlook.Folder

 Dim vw As Outlook.View

 Dim strView As String

 Set nsp = Application.Session

 Set mpFolder = nsp.GetDefaultFolder(olFolderInbox)

 ' Save a reference to the current view

 Set vw = mpFolder.CurrentView

 MsgBox "The Current View is: " & vw.Name

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.CustomViewsOnly Property (Outlook)

 Copy code hover
[image]

Folder.CustomViewsOnly Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines which views are displayed on the View menu for a given folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CustomViewsOnly

expression A variable that represents a Folder object.

Remarks

If set to the True, only user-created views will appear on the menu.

This property has an effect only on the View menu. It does not affect the display of views in the Navigation Pane.

Example

The following example prompts the user to select a view option. If the user chooses to view all views, the CustomViewsOnly property is set to False. If the user chooses to view only custom views, the CustomViewsOnly property is set to True. Once the property is changed, the outcome of the change can be seen in the user interface.

VBA Copy code Copy code
Sub SetCusView()

 'Sets the CustomViewsOnly property depending on the user's response

 Dim nmsName As Outlook.NameSpace

 Dim fldFolder As Outlook.Folder

 Dim lngAns As Long

 Set nmsName = Application.GetNamespace("MAPI")

 Set fldFolder = nmsName.GetDefaultFolder(olFolderInbox)

 'Prompt user for input

 lngAns = MsgBox( _

 "Would you like to view only custom views in the View menu?", vbYesNo)

 Call SetVal(fldFolder, lngAns)

End Sub

Sub SetVal(ByRef fldFolder As Folder, ByVal lngAns As Long)

 'Modifies the CustomViewsOnly property to display views on the View menu

 If lngAns = vbYes Then

 fldFolder.CustomViewsOnly = True

 Else

 fldFolder.CustomViewsOnly = False

 End If

 'Display only custom views

 If lngAns = vbYes Then

 MsgBox "The View menu for the " _

 & fldFolder.Name & " folder will now display only custom views."

 'Display all views

 Else

 MsgBox "The View menu for the " _

 & fldFolder.Name & " folder will now display all views."

 End If

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.DefaultItemType Property (Outlook)

 Copy code hover
[image]

Folder.DefaultItemType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlItemType enumeration indicating the default Outlook item type contained in the folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultItemType

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.DefaultMessageClass Property (Outlook)

 Copy code hover
[image]

Folder.DefaultMessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the default message class for items in the folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultMessageClass

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Description Property (Outlook)

 Copy code hover
[image]

Folder.Description Property (Outlook)
See also Send feedback

Returns or sets a String representing the description of the folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Description

expression A variable that represents a Folder object.

Remarks

This property corresponds to the MAPI property PidTagComment.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.EntryID Property (Outlook)

 Copy code hover
[image]

Folder.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .EntryID

expression A variable that represents a Folder object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.FolderPath Property (Outlook)

 Copy code hover
[image]

Folder.FolderPath Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the path of the current folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FolderPath

expression A variable that represents a Folder object.

Example

The following example displays information about the default Contacts folder. The subroutine accepts a Folder object and displays the folder's name, path, and address book information.

VBA Copy code Copy code
Sub Folderpaths()

 Dim nmsName As NameSpace

 Dim fldFolder As Folder

 'Create namespace reference

 Set nmsName = Application.GetNamespace("MAPI")

 'create folder instance

 Set fldFolder = nmsName.GetDefaultFolder(olFolderContacts)

 'call sub program

 Call FolderInfo(fldFolder)

End Sub

Sub FolderInfo(ByVal fldFolder As Folder)

 'Displays information about a given folder

 MsgBox fldFolder.Name & "'s current path is " & _

 fldFolder.FolderPath & _

 ". The current address book name is " & fldFolder.AddressBookName & "."

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Folders Property (Outlook)

 Copy code hover
[image]

Folder.Folders Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Folders collection that represents all the folders contained in the specified Folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Folders

expression A variable that represents a Folder object.

Remarks

The NameSpace object is the root of all the folders for the given name space.

Example

This Visual Basic for Applications (VBA) example uses the Folders.Add method to add the new folder named "My Personal Contacts" to the default Contacts folder.

VBA Copy code Copy code
Sub CreatePersonalContacts()

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderContacts)

 Set myNewFolder = myFolder.Folders.Add("My Personal Contacts")

End Sub

This VBA example uses the Folders.Add method to add two new folders in the Tasks folder. The first folder, "My Notes Folder", will contain note items. The second folder, "My Contacts Folder", will contain contact items. If the folders already exist, a message box will inform the user.

VBA Copy code Copy code
Sub CreateFolders()

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNotesFolder As Outlook.Folder

 Dim myContactFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderTasks)

 On Error GoTo ErrorHandler

 Set myNotesFolder = _

 myFolder.Folders.Add("My Notes Folder", olFolderNotes)

 Set myContactFolder = _

 myFolder.Folders.Add("My Contacts Folder", olFolderContacts)

 Exit Sub

ErrorHandler:

 MsgBox "Error creating the folder. The folder may already exist."

 Resume Next

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.InAppFolderSyncObject Property (Outlook)

 Copy code hover
[image]

Folder.InAppFolderSyncObject Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if the specified folder will be synchronized with the e-mail server. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .InAppFolderSyncObject

expression A variable that represents a Folder object.

Remarks

If True, this folder will be synchronized when the "Application Folders" SyncObject is synchronized. If False, the folder will not synchronize.

This is equivalent to selecting the check box for this folder in the Application Folders group on the Send/Receive dialog box.

If this property is set to True, and the "Application Folders" SyncObject does not already exist, a SyncObject will be automatically created. The "Application Folders" SyncObject is the only Send/Receive group that can be programmatically modified.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the Inbox folder to be synchronized when the "Application Folders" SyncObject object is synchronized. The InAppFolderSyncObject property is used in conjunction with the AppFolders property of the SyncObjects collection.

VBA Copy code Copy code
Public Sub appfolders()
 Dim nsp As Outlook.NameSpace
 Dim sycs As Outlook.SyncObjects
 Dim syc As Outlook.SyncObject
 Dim mpfInbox As Outlook.Folder

 Set nsp = Application.GetNamespace("MAPI")
 Set sycs = nsp.SyncObjects
 'Return the Application Folder SyncObject.
 Set syc = sycs.AppFolders
 'Get the Inbox folder.
 Set mpfInbox = nsp.GetDefaultFolder(olFolderInbox)
 'Set the Inbox folder to be synchronized when the Application
 'Folder's SyncObject is synchronized.
 mpfInbox.InAppFolderSyncObject = True
 'Start the synchronization.
 syc.Start
End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.IsSharePointFolder Property (Outlook)

 Copy code hover
[image]

Folder.IsSharePointFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the folder is a Microsoft SharePoint Foundation folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsSharePointFolder

expression A variable that represents a Folder object.

Remarks

A SharePoint Foundation folder is a custom folder in Outlook that contains a live copy of the contact list or event list that lives on a SharePoint Foundation Web site. The contact list maps to a Contacts folder in Outlook and the event list maps to a Calendar folder.

SharePoint Foundation folders are automatically created under the SharePoint Folders node in the Navigation Pane when a contact list or an event list is exported from the SharePoint Foundation Web site.

Though SharePoint Foundation folders work the same way as other folders, there are a few exceptions. SharePoint Foundation folders are read-only and any attempt to edit folder properties or add, edit, or remove existing items will fail.

A folder in the user's Microsoft Exchange server folder will never be a SharePoint Foundation folder, and no folder in the user's default Personal Folders file (.pst) will ever be a SharePoint Foundation folder. Typically the SharePoint Foundation folders will be under the node SharePoint Folders in the Navigation Pane.

Example

The following Microsoft Visual Basic for Applications (VBA) example changes the Subject line of the appointment item displayed in the active inspector and saves the item. If the item is contained in a SharePoint Foundation folder, it displays a message to the user that the item cannot be modified. To run this example, make sure that an appointment item is displayed in the active inspector window. This example will modify the subject of the appointment item.

VBA Copy code Copy code
Sub ChangeItem()

'Checks if the item is contained in a SharePoint folder. If it is not, it changes the Subject line, and then saves the item.

 Dim myItem As Outlook.AppointmentItem

 Dim fldFolder As Outlook.Folder

 Set myItem = Application.ActiveInspector.CurrentItem

 Set fldFolder = myItem.Parent

 If fldFolder.IsSharePointFolder = True Then

 MsgBox _

 "The item is contained in a SharePoint Foundation folder and cannot be modified."

 Else

 myItem.Subject = myItem.Subject + " Changed by VBA"

 myItem.Save

 MsgBox "The item has been changed."

 End If

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Items Property (Outlook)

 Copy code hover
[image]

Folder.Items Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Items collection object as a collection of Outlook items in the specified folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Items

expression A variable that represents a Folder object.

Remarks

The index for the Items collection starts at 1, and the items in the Items collection object are not guaranteed to be in any particular order.

Example

This Visual Basic for Applications (VBA) example uses the Items property to obtain the collection of ContactItem objects from the default Contacts folder.

VBA Copy code Copy code
Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Name Property (Outlook)

 Copy code hover
[image]

Folder.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a Folder object.

Example

This Visual Basic for Applications (VBA) example uses the Name property to obtain the name of the folder displayed in the active explorer.

VBA Copy code Copy code
Sub DisplayCurrentFolderName()

 Dim myExplorer As Outlook.Explorer

 Dim myFolder As Outlook.Folder

 Set myExplorer = Application.ActiveExplorer

 Set myFolder = myExplorer.CurrentFolder

 MsgBox myFolder.Name

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Parent Property (Outlook)

 Copy code hover
[image]

Folder.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Folder object.

Remarks

The parent of the Folder object is the Folders collection object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

Folder.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Folder object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Session Property (Outlook)

 Copy code hover
[image]

Folder.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Folder object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.ShowAsOutlookAB Property (Outlook)

 Copy code hover
[image]

Folder.ShowAsOutlookAB Property (Outlook)
See also Send feedback

Returns or sets a Boolean variable that specifies whether the contact items folder will be displayed as an address list in the Outlook Address Book. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowAsOutlookAB

expression A variable that represents a Folder object.

Remarks

If you set the ShowAsOutlookAB property of a contact items folder to False, it will not be available in the drop-down list under Address Book in the Address Book dialog box.

ShowAsOutlookAB does not support folders on another Exchange user's mailbox, for example, a Contacts folder that is shared by another user. Getting or setting this property on a such a folder will not produce any desired results.

Example

The following Visual Basic for Applications (VBA) example creates a reference to the default Contacts folder and modifies its ShowAsOutlookAB property to be displayed as an Address Book.

VBA Copy code Copy code
Sub ShowAsAddressBookChange()

 Dim nmsName As Outlook.Namespace

 Dim fldFolder As Outlook.Folder

 'Create instance of namespace

 Set nmsName = Application.GetNamespace("Mapi")

 Set fldFolder = nmsName.GetDefaultFolder(olFolderContacts)

 'Display the folder as Outlook Address Book

 fldFolder.ShowAsOutlookAB = True

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.ShowItemCount Property (Outlook)

 Copy code hover
[image]

Folder.ShowItemCount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Sets or returns a constant in the OlShowItemCount enumeration that indicates whether to display the number of unread messages in the folder or the total number of items in the folder in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowItemCount

expression A variable that represents a Folder object.

Remarks

The ShowItemCount property does not work with Public Folders.

Example

This Microsoft Visual Basic for Applications (VBA) example displays the unread count for the Inbox in the Navigation Pane.

VBA Copy code Copy code
Sub ShowTotalItemCount()

 Dim nmsName As Outlook.NameSpace

 Dim fldFolder As Outlook.Folder

 Set nmsName = Application.GetNamespace("MAPI")

 Set fldFolder = nmsName.GetDefaultFolder(olFolderInbox)

 fldFolder.ShowItemCount = olShowUnreadItemCount

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Store Property (Outlook)

 Copy code hover
[image]

Folder.Store Property (Outlook)
See also Send feedback

Returns a Store object representing the store that contains the Folder object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Store

expression A variable that represents a Folder object.

Remarks

This property returns a Store object except in the case where the Folder is a shared folder (returned by NameSpace.GetSharedDefaultFolder). In this case, one user has delegated access to a default folder to another user; a call to Folder.Store will return Null.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.StoreID Property (Outlook)

 Copy code hover
[image]

Folder.StoreID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the store ID for the folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .StoreID

expression A variable that represents a Folder object.

Example

This Visual Basic for Applications (VBA) example obtains the EntryID and StoreID for the default Tasks folder and then calls the NameSpace.GetFolderFromID method using these values to obtain the same folder. The folder is then displayed.

VBA Copy code Copy code
Sub GetWithID()

 Dim myFolder As Outlook.Folder

 Dim myEntryID As String

 Dim myStoreID As String

 Dim myNewFolder As Outlook.Folder

 Set myFolder = Application.Session.GetDefaultFolder(olFolderTasks)

 myEntryID = myFolder.EntryID

 myStoreID = myFolder.StoreID

 Set myNewFolder = Application.Session.GetFolderFromID(myEntryID, myStoreID)

 myNewFolder.Display

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.UnReadItemCount Property (Outlook)

 Copy code hover
[image]

Folder.UnReadItemCount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the number of unread items in the folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .UnReadItemCount

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.UserDefinedProperties Property (Outlook)

 Copy code hover
[image]

Folder.UserDefinedProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a UserDefinedProperties object that represents the user-defined custom properties for the Folder object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .UserDefinedProperties

expression A variable that represents a Folder object.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Views Property (Outlook)

 Copy code hover
[image]

Folder.Views Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Views collection object of the Folder object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Views

expression A variable that represents a Folder object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates an instance of the Views collection and displays the XML definition of a view called "Table View". If the view does not exist, it creates one.

VBA Copy code Copy code
Sub DisplayViewDef()

 'Displays the XML definition of a View object

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 'Return a view called Table View if it already exists, else create one

 Set objView = objViews.Item("Table View")

 If objView Is Nothing Then

 Set objView = objViews.Add("Table View", olTableView, _

 olViewSaveOptionAllFoldersOfType)

 End If

 MsgBox objView.XML

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.WebViewOn Property (Outlook)

 Copy code hover
[image]

Folder.WebViewOn Property (Outlook)
See also Send feedback

Returns or sets a Boolean indicating the Web view state for a folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WebViewOn

expression A variable that represents a Folder object.

Remarks

Returns True to display the Web page specified by the WebViewURL property of the Folder object.

Microsoft Outlook uses the rendering engine of the version Windows Internet Explorer installed on the client computer to display the web page. If Internet Explorer is not installed on the client computer, Outlook will not display the web page.

This property is always False if the value of the WebViewURL property is empty.

Also, setting the WebViewOn property to True before setting the WebViewURL property will not display the home page specified in the WebViewURL property.

Example

The following Visual Basic for Applications (VBA) example creates a subfolder under the Inbox folder and assigns a home page to it.

VBA Copy code Copy code
Sub SetupFolderHomePage()

 Dim nsp As Outlook.NameSpace

 Dim mpfInbox As Outlook.Folder

 Dim mpfNew As Outlook.Folder

 Set nsp = Application.GetNamespace("MAPI")

 Set mpfInbox = nsp.GetDefaultFolder(olFolderInbox)

 Set mpfNew = mpfInbox.Folders.Add("MyFolderHomePage")

 mpfNew.WebViewURL = "http://www.microsoft.com"

 mpfNew.WebViewOn = True

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.WebViewURL Property (Outlook)

 Copy code hover
[image]

Folder.WebViewURL Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the URL of the Web page that is assigned to a folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WebViewURL

expression A variable that represents a Folder object.

Example

The following Visual Basic for Applications (VBA) example creates a subfolder under the Inbox folder and assigns a home page to it.

VBA Copy code Copy code
Sub SetupFolderHomePage()

 Dim nsp As Outlook.NameSpace

 Dim mpfInbox As Outlook.Folder

 Dim mpfNew As Outlook.Folder

 Set nsp = Application.GetNamespace("MAPI")

 Set mpfInbox = nsp.GetDefaultFolder(olFolderInbox)

 Set mpfNew = mpfInbox.Folders.Add("MyFolderHomePage")

 mpfNew.WebViewURL = "http://www.microsoft.com"

 mpfNew.WebViewOn = True

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder Methods (Outlook)

 Copy code hover
[image]

Folder Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddToPFFavorites | Adds a Microsoft Exchange public folder to the public folder's Favorites folder.
CopyTo | Copies the current folder in its entirety to the destination folder.
Delete | Deletes an object from the collection.
Display | Displays a new Explorer object for the folder.
GetCalendarExporter | Creates a CalendarSharing object for the specified Folder.
GetCustomIcon | Returns an IPictureDisp object that represents the custom icon for the folder.
GetExplorer | Returns an Explorer object that represents a new, inactive Explorer object initialized with the specified folder as the current folder.
GetStorage | Gets a StorageItem object on the parent Folder to store data for an Outlook solution.
GetTable | Obtains a Table object that contains items filtered by Filter.
MoveTo | Moves a folder to the specified destination folder.
SetCustomIcon | Sets a custom icon that is specified by Picture for the folder.


Folder.AddToPFFavorites Method (Outlook)

 Copy code hover
[image]

Folder.AddToPFFavorites Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a Microsoft Exchange public folder to the public folder's Favorites folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddToPFFavorites

expression A variable that represents a Folder object.

Example

The following Visual Basic for Applications (VBA) example adds the public folder GroupDiscussion to the user's Favorites folder by using the AddToPFFavorites method. To run this example, you need to replace 'GroupDiscussion' with a valid public folder name.

VBA Copy code Copy code
Sub AddToFavorites()

 'Adds a Public Folder to the list of favorites

 Dim objFolder As Outlook.Folder

 Set objFolder = Application.Session.GetDefaultFolder _

 (olPublicFoldersAllPublicFolders).Folders.Item("GroupDiscussion")

 objFolder.AddToPFFavorites

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.CopyTo Method (Outlook)

 Copy code hover
[image]

Folder.CopyTo Method (Outlook)
See also Send feedback

Published: July 16, 2012

Copies the current folder in its entirety to the destination folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .CopyTo(DestinationFolder)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
DestinationFolder | Required | Folder | Required Folder object that represents the destination folder.

Return Value

A Folder object that represents the new copy of the current folder.

Remarks

Setting the REG_MULTI_SZ value, DisableCrossAccountCopy, in HKCU\Software\Microsoft\Office\14.0\Outlook in the Windows registry has the side effect of disabling this method.

Example

This Visual Basic for Applications (VBA) example uses the CopyTo method to copy the default Contacts folder to the default Inbox folder.

VBA Copy code Copy code
Sub CopyFolder()
 Dim myNameSpace As Outlook.NameSpace
 Dim myInboxFolder As Outlook.Folder
 Dim myContactsFolder As Outlook.Folder
 Dim myNewFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myInboxFolder = myNameSpace.GetDefaultFolder(olFolderInbox)
 Set myContactsFolder = myNameSpace.GetDefaultFolder(olFolderContacts)
 Set myNewFolder = myContactsFolder.CopyTo(myInboxFolder)
End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Delete Method (Outlook)

 Copy code hover
[image]

Folder.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a Folder object.

Remarks

The Delete method deletes a single folder.

In general, deleting a folder does not require first deleting the items in the folder. Deleting the folder also deletes all items in the folder. An exception would be if the folder is an Outlook folder that cannot be deleted, such as the Inbox and the Deleted Items folder. In such cases, you can delete only the items of the folder but not the folder itself. To delete all items in the Items collection of the folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.Display Method (Outlook)

 Copy code hover
[image]

Folder.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Explorer object for the folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .Display()

expression A variable that represents a Folder object.

Example

This Visual Basic for Applications (VBA) example uses the Display method to display the default Inbox folder. This example will not return an error, even if there are no items in the Inbox, because you are not asking for the display of a specific item.

VBA Copy code Copy code
Sub DisplayInbox()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 myFolder.Display

End Sub

This Visual Basic for Applications example displays the first item in the Inbox folder. This example will return an error if the Inbox is empty, because you are trying to display a specific item. If there are no items in the folder, a message box will be displayed to inform the user.

Note Note

The items in the Items collection object are not guaranteed to be in any particular order.

VBA Copy code Copy code
Sub DisplayFirstItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 On Error GoTo ErrorHandler

 myFolder.Items(1).Display

 Exit Sub

ErrorHandler:

 MsgBox "There are no items to display."

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.GetCalendarExporter Method (Outlook)

 Copy code hover
[image]

Folder.GetCalendarExporter Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a CalendarSharing object for the specified Folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetCalendarExporter

expression An expression that returns a Folder object.

Return Value

A CalendarSharing object for the specified folder.

Remarks

The GetCalendarExporter method automatically sets the defaults for the CalendarSharing class to the standard default options used by the Folder object. The GetCalendarExporter method can only be used on calendar folders. An error occurs if you use the method on Folder objects that represent other folder types.

Note Note

The CalendarSharing object only supports exporting the iCalendar (.ics) file format.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.GetCustomIcon Method (Outlook)

 Copy code hover
[image]

Folder.GetCustomIcon Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an IPictureDisp object that represents the custom icon for the folder.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetCustomIcon

expression A variable that represents a Folder object.

Return Value

An IPictureDisp object that represents a custom icon for the folder.

Remarks

The returned IPictureDisp object has its Type property equal to PICTYPE_ICON or PICTYPE_BITMAP.

GetCustomIcon returns Null (Nothing in Visual Basic) if the folder does not have a custom folder icon, or if the folder belongs to one of the following groups of folders:

  • Default folders (as listed by the OlDefaultFolders enumeration)

  • Special folders (as listed by the OlSpecialFolders enumeration)

  • Exchange public folders

  • Root folder of any Exchange mailbox

  • Hidden folders

You can only call GetCustomIcon from code that runs in-process as Outlook. An IPictureDisp object cannot be marshaled across process boundaries. If you attempt to call GetCustomIcon from out-of-process code, an exception occurs. For more information, see An automation server cannot pass a pointer to the picture object's IPictureDisp implementation across process boundaries.

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.GetExplorer Method (Outlook)

 Copy code hover
[image]

Folder.GetExplorer Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Explorer object that represents a new, inactive Explorer object initialized with the specified folder as the current folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetExplorer(DisplayMode)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
DisplayMode | Optional | Variant | The display mode of the folder. Can be one of the constants in the OlFolderDisplayMode enumeration.

Return Value

An Explorer object that represents a new, inactive Explorer initialized with the specified folder as the current folder.

Remarks

This method is useful for returning a new Explorer object in which to display the folder, as opposed to using the ActiveExplorer method and setting the CurrentFolder property.

The Explorer.Display method can be used to activate or show the Explorer.

The GetExplorer method takes an optional argument of an OlFolderDisplayMode constant.

By default, the new Explorer will be displayed in the Normal mode (olFolderDisplayNormal) with all interface elements displayed: a message panel on the right and the Navigation Pane on the left. The exception to this rule is when you are calling GetExplorer on delegated folders that are in No-Navigation mode (olFolderDisplayNoNavigation ) by default. You can apply more restrictions to a default mode, but you cannot lessen the restrictions by changing the OlFolderDisplayMode.

The explorer can also be displayed in Folder-Only mode (olFolderDisplayFolderOnly). This mode is essentially the same as the Normal mode (olFolderDisplayNormal ) in that it too displays the Navigation Pane on the left.

The most restrictive mode you can use is No-Navigation mode (olFolderDisplayNoNavigation). In this mode, the Explorer will display with no folder list, no drop-down folder list, and any "Go"-type menu/command bar options should be disabled. Basically, the user should not be able to navigate to any other folder within that Explorer window. By default, a delegated (shared) folder appears in No-Navigation mode.

Example

This Visual Basic for Applications (VBA) example uses the GetExplorer method to return a new, inactive explorer for the default Contacts folder and then displays the explorer in the default mode of olFolderDisplayNormal.

VBA Copy code Copy code
Sub ActivateContactExplorer()

 Dim nsp As Outlook.NameSpace

 Dim mpfContacts As Outlook.Folder

 Dim expContacts As Outlook.Explorer

 Set nsp = Application.GetNamespace("MAPI")

 Set mpfContacts = nsp.GetDefaultFolder(olFolderContacts)

 Set expContacts = mpfContacts.GetExplorer

 expContacts.Activate

End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.GetStorage Method (Outlook)

 Copy code hover
[image]

Folder.GetStorage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Gets a StorageItem object on the parent Folder to store data for an Outlook solution.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetStorage(StorageIdentifier, StorageIdentifierType)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
StorageIdentifier | Required | String | An identifier for the StorageItem object; depending on the identifier type, the value can represent an Entry ID, a message class, or a subject.
StorageIdentifierType | Required | OlStorageIdentifierType | Specifies the type of identifier for the StorageItem object.

Return Value

A StorageItem object that is used to store data for a solution.

Remarks

The GetStorage method obtains a StorageItem on a Folder object using the identifier specified by StorageIdentifier and has the identifier type specified by StorageIdentifierType. The StorageItem is a hidden item in the Folder, which roams with the account and is available online and offline.

If you specify the EntryID for the StorageItem by using the olIdentifyByEntryID value for StorageIdentifierType, then the GetStorage method will return the StorageItem with the specified EntryID. If no StorageItem can be found using that EntryID or if the StorageItem does not exist, then the GetStorage method will raise an error.

If you specify the message class for the StorageItem by using the olIdentifyByMessageClass value for StorageIdentifierType, then the GetStorage method will return the StorageItem with the specified message class. If there are multiple items with the same message class, then the GetStorage method returns the item with the most recent PR_LAST_MODIFICATION_TIME. If no StorageItem exists with the specified message class, then the GetStorage method creates a new StorageItem with the message class specified by StorageIdentifier.

If you specify the Subject of the StorageItem, then the GetStorage method will return the StorageItem with the Subject specified in the GetStorage call. If there are multiple items with the same Subject, then the GetStorage method will return the item with the most recent PR_LAST_MODIFICATION_TIME. If no StorageItem exists with the specified Subject, then the GetStorage method will create a new StorageItem with the Subject specified by StorageIdentifier.

GetStorage returns an error if the store type of the folder is not supported. The following stores return an error when GetStorage is called:

  • Hotmail store

  • Internet Message Access Protocol (IMAP) stores

  • Delegate stores

  • Public folder stores

The Size of a StorageItem that is newly created is zero (0) until you make an explicit call on the Save method of the item.

For more information on storing data for a solution, see Storing Data for Solutions.

Example

The following code sample in Visual Basic for Applications shows how to use the StorageItem object to store private solution data. It saves the data in a custom property of a StorageItem object in the Inbox folder. The following describes the steps:

  1. The code sample calls GetStorage to obtain an existing StorageItem object that has the subject "My Private Storage" in the Inbox. If no StorageItem with that subject already exists, GetStorage creates a StorageItem object with that subject.

  2. If the StorageItem is newly created, the code sample creates a custom property "Order Number" for the object. Note that "Order Number" is a property of a hidden item in the Inbox.

  3. The code sample then assigns a value to "Order Number" and saves the StorageItem object.

VBA Copy code Copy code
Sub AssignStorageData()
 Dim oInbox As Outlook.Folder
 Dim myStorage As Outlook.StorageItem

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)
 ' Get an existing instance of StorageItem, or create new if it doesn't exist
 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)
 ' If StorageItem is new, add a custom property for Order Number
 If myStorage.Size = 0 Then
 myStorage.UserProperties.Add "Order Number", olNumber
 End If
 ' Assign a value to the custom property
 myStorage.UserProperties("Order Number").Value = 100
 myStorage.Save
End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.GetTable Method (Outlook)

 Copy code hover
[image]

Folder.GetTable Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Table object that contains items filtered by Filter.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetTable(Filter, TableContents)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
Filter | Optional | String | A filter in Microsft Jet or DAV Searching and Locating (DASL) syntax that specifies the criteria for items in the parent Folder.
TableContents | Optional | OlTableContents | Specifies the type of items in the folder that GetTable returns. The default is olUserItems.

Return Value

A Table that contains items in the parent Folder that meet the criteria in Filter. By default, TableContents is olUserItems and the returned Table contains only the filtered items that are not hidden.

Remarks

If Filter is a blank string or the Filter parameter is omitted, GetTable returns a Table with rows representing all the items in the Folder. If Filter is a blank string or the Filter parameter is omitted and TableContents is olHiddenItems, GetTable returns a Table with rows representing all the hidden items in the Folder.

For more information on filters, see Filtering Items and Referencing Properties by Namespace.

GetTable returns a Table with the default column set for the folder type of the parent Folder. To modify the default column set, use the Add, Remove, or RemoveAll methods of the Columns collection object. When TableContents is olHiddenItems, the default column set is always the default column set for a mail folder even though the parent Folder might be, for example, a Contacts folder. For more information on default column sets, see Default Properties Displayed in a Table Object.

You can use Table.Restrict to apply subsequent filters to a Table that is based on the Folder object.

Example

The following code sample illustrates how to use Folder.GetTable to obtain a Table object based on the LastModificationTime of items in the Inbox. It then enumerates and prints the values of a couple of default properties of these items.

VBA Copy code Copy code
Sub DemoTable()
    'Declarations
    Dim Filter As String
    Dim oRow As Outlook.Row
    Dim oTable As Outlook.Table
    Dim oFolder As Outlook.Folder

    'Get a Folder object for the Inbox
    Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

    'Define Filter to obtain items last modified after May 1, 2005
    Filter = "[LastModificationTime] > '5/1/2005'"
    'Restrict with Filter
    Set oTable = oFolder.GetTable(Filter)

    'Enumerate the table using test for EndOfTable
    Do Until (oTable.EndOfTable)
        Set oRow = oTable.GetNextRow()
        Debug.Print (oRow("Subject"))
        Debug.Print (oRow("LastModificationTime"))
    Loop
End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.MoveTo Method (Outlook)

 Copy code hover
[image]

Folder.MoveTo Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a folder to the specified destination folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .MoveTo(DestinationFolder)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
DestinationFolder | Required | Folder | The destination Folder for the Folder that is being moved.

Remarks

Setting the REG_MULTI_SZ value, DisableCrossAccountCopy, in HKCU\Software\Microsoft\Office\14.0\Outlook in the Windows registry has the side effect of disabling this method.

Example

This Visual Basic for Applications (VBA) example uses the MoveTo method to move the "My Test Contacts" folder in the default Contacts folder to the Inbox folder.

VBA Copy code Copy code
Sub MoveFolder()
 Dim myNameSpace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myNewFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(olFolderContacts)
 Set myNewFolder = myFolder.Folders.Add("My Test Contacts")
 myNewFolder.MoveTo myNameSpace.GetDefaultFolder _
 (olFolderInbox)
End Sub

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.SetCustomIcon Method (Outlook)

 Copy code hover
[image]

Folder.SetCustomIcon Method (Outlook)
See also Send feedback

Sets a custom icon that is specified by Picture for the folder.

Version Information

Version Added: Outlook 2010

Syntax

expression .SetCustomIcon(Picture)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
Picture | Required | IPictureDisp | Specifies the custom icon for the folder.

Remarks

The IPictureDisp object specified by Picture must have its Type property equal to PICTYPE_ICON or PICTYPE_BITMAP. The icon or bitmap resource can have a maximum size of 32x32. Icons that are 16x16 or 24x24 are also supported, and Microsoft Outlook can scale up a 16x16 icon if Outlook is running in high Dots Per Inch (DPI) mode. Icons of other sizes cause SetCustomIcon to return an error.

You can set a custom icon for a search folder and for all folders that do not represent a default or a special folder. If you attempt to set a custom icon for a folder that belongs to one of the following groups of folders, SetCustomIcon will return an error:

  • Default folders (as listed by the OlDefaultFolders enumeration)

  • Special folders (as listed by the OlSpecialFolders enumeration)

  • Exchange public folders

  • Root folder of any Exchange mailbox

  • Hidden folders

You can only call SetCustomIcon from code that runs in-process as Outlook. An IPictureDisp object cannot be marshaled across process boundaries. If you attempt to call SetCustomIcon from out-of-process code, an exception will occur. For more details, see An automation server cannot pass a pointer to the picture object's IPictureDisp implementation across process boundaries.

The custom folder icon that this method provides does not persist beyond the running Outlook session. Add-ins therefore must set the custom folder icon every time that Outlook boots.

The custom folder icon does not appear in other Exchange clients such as Outlook Web Access, nor does it appear in Outlook running on a Windows Mobile device.

Example

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code fragment in C# sets the icons for folders that appear in the Solutions module. The code fragment depends on the PictureDispConverter class that is also illustrated below.

C# Copy code Copy code
//Get the icons for the solution
stdole.StdPicture rootPict =
 PictureDispConverter.ToIPictureDisp(
 Properties.Resources.BRIDGE)
 as stdole.StdPicture;
stdole.StdPicture calPict =
 PictureDispConverter.ToIPictureDisp(
 Properties.Resources.umbrella)
 as stdole.StdPicture;
stdole.StdPicture contactsPict =
 PictureDispConverter.ToIPictureDisp(
 Properties.Resources.group)
 as stdole.StdPicture;
stdole.StdPicture tasksPict =
 PictureDispConverter.ToIPictureDisp(
 Properties.Resources.SUN)
 as stdole.StdPicture;

//Set the icons for solution folders
solutionRoot.SetCustomIcon(rootPict);
solutionCalendar.SetCustomIcon(calPict);
solutionContacts.SetCustomIcon(contactsPict);
solutionTasks.SetCustomIcon(tasksPict);

The following is the definition of the PictureDispConverter class.

C# Copy code Copy code
using System;
using System.Drawing;
using System.Collections.Generic;
using System.Runtime.InteropServices;

public static class PictureDispConverter
{
 //IPictureDisp GUID.
 public static Guid iPictureDispGuid = typeof(stdole.IPictureDisp).GUID;

 // Converts an Icon into an IPictureDisp.
 public static stdole.IPictureDisp ToIPictureDisp(Icon icon)
 {
 PICTDESC.Icon pictIcon = new PICTDESC.Icon(icon);
 return PictureDispConverter.OleCreatePictureIndirect(pictIcon, ref iPictureDispGuid, true);
 }

 // Converts an image into an IPictureDisp.
 public static stdole.IPictureDisp ToIPictureDisp(Image image)
 {
 Bitmap bitmap = (image is Bitmap) ? (Bitmap)image : new Bitmap(image);
 PICTDESC.Bitmap pictBit = new PICTDESC.Bitmap(bitmap);
 return PictureDispConverter.OleCreatePictureIndirect(pictBit, ref iPictureDispGuid, true);
 }

 [DllImport("OleAut32.dll", EntryPoint = "OleCreatePictureIndirect", ExactSpelling = true,
 PreserveSig = false)]
 private static extern stdole.IPictureDisp OleCreatePictureIndirect(
 [MarshalAs(UnmanagedType.AsAny)] object picdesc, ref Guid iid, bool fOwn);

 private readonly static HandleCollector handleCollector =
 new HandleCollector("Icon handles", 1000);

 // WINFORMS COMMENT:
 // PICTDESC is a union in native, so we'll just
 // define different ones for the different types
 // the "unused" fields are there to make it the right
 // size, since the struct in native is as big as the biggest
 // union.
 private static class PICTDESC
 {
 //Picture Types
 public const short PICTYPE_UNINITIALIZED = -1;
 public const short PICTYPE_NONE = 0;
 public const short PICTYPE_BITMAP = 1;
 public const short PICTYPE_METAFILE = 2;
 public const short PICTYPE_ICON = 3;
 public const short PICTYPE_ENHMETAFILE = 4;

 [StructLayout(LayoutKind.Sequential)]
 public class Icon
 {
 internal int cbSizeOfStruct = Marshal.SizeOf(typeof(PICTDESC.Icon));
 internal int picType = PICTDESC.PICTYPE_ICON;
 internal IntPtr hicon = IntPtr.Zero;
 internal int unused1 = 0;
 internal int unused2 = 0;

 internal Icon(System.Drawing.Icon icon)
 {
 this.hicon = icon.ToBitmap().GetHicon();
 }
 }

 [StructLayout(LayoutKind.Sequential)]
 public class Bitmap
 {
 internal int cbSizeOfStruct = Marshal.SizeOf(typeof(PICTDESC.Bitmap));
 internal int picType = PICTDESC.PICTYPE_BITMAP;
 internal IntPtr hbitmap = IntPtr.Zero;
 internal IntPtr hpal = IntPtr.Zero;
 internal int unused = 0;
 internal Bitmap(System.Drawing.Bitmap bitmap)
 {
 this.hbitmap = bitmap.GetHbitmap();
 }
 }
 }
}

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder Events (Outlook)

 Copy code hover
[image]

Folder Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeFolderMove | Occurs when a folder is about to be moved or deleted, either as a result of user action or through program code.
BeforeItemMove | Occurs when an item is about to be moved or deleted from a folder, either as a result of user action or through program code.


Folder.BeforeFolderMove Event (Outlook)

 Copy code hover
[image]

Folder.BeforeFolderMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a folder is about to be moved or deleted, either as a result of user action or through program code.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeFolderMove(MoveTo, Cancel)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
MoveTo | Required | Folder | Represents the folder to which the item is being moved.
Cancel | Required | Boolean | Set this to True to cancel the move or delete action.

Remarks

This event fires when the folder is about to be moved to another folder (including the Deleted Items folder) or when the folder is about to be permanently deleted. It does not fire during auto-archiving or synchronizing operations.

If the action is a permanent delete, the MoveTo folder returned in the event will be Null (Nothing in Visual Basic).

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folder.BeforeItemMove Event (Outlook)

 Copy code hover
[image]

Folder.BeforeItemMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an item is about to be moved or deleted from a folder, either as a result of user action or through program code.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeItemMove(Item, MoveTo, Cancel)

expression A variable that represents a Folder object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | Represents the Outlook item that is to be moved or deleted.
MoveTo | Required | Folder | Represents the folder to which the item is being moved.
Cancel | Required | Boolean | Set this to True to cancel the move or delete action.

Remarks

This event fires when the item is about to be moved to another folder (including the Deleted Items folder) or when the item is about to be permanently deleted. It does not fire during auto-archiving or synchronizing operations.

If the action is a permanent delete, the MoveTo folder returned in the event will be Null (Nothing in Visual Basic).

See also

Concepts

Folder Object

Other resources

Folder Object Members


Folders Object (Outlook)

 Copy code hover
[image]

Folders Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of Folder objects that represent all the available Outlook folders in a specific subset at one level of the folder tree.

Remarks

Use the Folders property to return the Folders object from a NameSpace object or another Folder object.

Use Folders(index), where index is the name or index number, to return a single Folder object. Folder names are case-sensitive.

Example

The following Visual Basic for Applications (VBA) example returns the folder named Old Contacts.

VBA Copy code Copy code
Set myNameSpace = Application.GetNameSpace("MAPI")

Set myFolder = _

 myNameSpace.GetDefaultFolder(olFolderContacts)

Set myNewFolder = myFolder.Folders("Old Contacts")

The following Visual Basic for Applications example returns the first folder.

VBA Copy code Copy code
Set myNewFolder = myFolder.Folders(1)

See also

Concepts

Outlook Object Model Reference

Other resources

Folders Object Members


Folders Members (Outlook)

 Copy code hover
[image]

Folders Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of Folder objects that represent all the available Outlook folders in a specific subset at one level of the folder tree.

Events

Name | Description
FolderAdd | Occurs when a folder is added to the specified Folders collection.
FolderChange | Occurs when a folder in the specified Folders collection is changed.
FolderRemove | Occurs when a folder is removed from the specified Folders collection.

Methods

Name | Description
Add | Creates a new folder in the Folders collection.
GetFirst | Returns the first object in the Folders collection.
GetLast | Returns the last object in the Folders collection.
GetNext | Returns the next object in the Folders collection.
GetPrevious | Returns the previous object in the Folders collection.
Item | Returns a Folder object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Folders Properties (Outlook)

 Copy code hover
[image]

Folders Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Folders.Application Property (Outlook)

 Copy code hover
[image]

Folders.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Folders object.

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Class Property (Outlook)

 Copy code hover
[image]

Folders.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Folders object.

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Count Property (Outlook)

 Copy code hover
[image]

Folders.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Folders object.

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Parent Property (Outlook)

 Copy code hover
[image]

Folders.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Folders object.

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Session Property (Outlook)

 Copy code hover
[image]

Folders.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Folders object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders Methods (Outlook)

 Copy code hover
[image]

Folders Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new folder in the Folders collection.
GetFirst | Returns the first object in the Folders collection.
GetLast | Returns the last object in the Folders collection.
GetNext | Returns the next object in the Folders collection.
GetPrevious | Returns the previous object in the Folders collection.
Item | Returns a Folder object from the collection.
Remove | Removes an object from the collection.


Folders.Add Method (Outlook)

 Copy code hover
[image]

Folders.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new folder in the Folders collection.

Syntax

expression .Add(Name, Type)

expression A variable that represents a Folders object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The display name for the new folder.
Type | Optional | Long | The Outlook folder type for the new folder. If the folder type is not specified, the new folder will default to the same type as the folder in which it is created. Can be one of the following OlDefaultFolders constants: olFolderCalendar, olFolderContacts, olFolderDrafts, olFolderInbox, olFolderJournal, olFolderNotes, or olFolderTasks. The constants olFolderConflicts, olFolderDeletedItems, olFolderJunk, olFolderLocalFailures, olFolderManagedEmail, olFolderOutbox, olFolderRssSubscriptions, olFolderSentMail, olFolderServerFailures, olFolderSyncIssues, olFolderToDo, and olPublicFoldersAllPublicFolders cannot be specified for this argument.

Return Value

A Folder object that represents the new folder.

Example

This VBA example uses the Add method to add the new folder named "My Contacts" to the current (default) Contacts folder.

VBA Copy code Copy code
Sub AddContactsFolder()
 Dim myNameSpace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myNewFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(olFolderContacts)
 Set myNewFolder = myFolder.Folders.Add("My Contacts")
End Sub

This VBA example uses the Add method to add three new folders in the Tasks folder. The first folder, "Notes Folder", will contain note items. The second folder, "Contacts Folder", will contain contact items. The third folder, "Public Folder" will be a public folder. If the folders already exist, a message box will inform the user.

VBA Copy code Copy code
Sub AddFolders()
 Dim myNameSpace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myNotesFolder As Outlook.Folder
 Dim myContactsFolder As Outlook.Folder
 Dim myPublicFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(olFolderTasks)
 On Error GoTo ErrorHandler
 Set myNotesFolder = myFolder.Folders.Add("Notes Folder", olFolderNotes)
 Set myContactsFolder = myFolder.Folders.Add("Contacts Folder", olFolderContacts)
 Set myPublicFolder = myFolder.Folders.Add("Public Folder", olPublicFoldersAllPublicFolders)
 Exit Sub
ErrorHandler:
 MsgBox "This folder already exists!"
 Resume Next
End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.GetFirst Method (Outlook)

 Copy code hover
[image]

Folders.GetFirst Method (Outlook)
See also Send feedback

Returns the first object in the Folders collection.

Syntax

expression .GetFirst

expression A variable that represents a Folders object.

Return Value

A Folder object that represents the first object contained by the collection.

Remarks

Returns Nothing if no first object exists, for example, if there are no objects in the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

Example

This Visual Basic for Applications (VBA) example uses the GetFirst method to locate the first folder in the Contacts folder and then copies the folder to the Test folder. Before running this example, you need to make sure the necessary folders exist in the default Contacts and Inbox folders.

VBA Copy code Copy code
Sub CopyItems()

 Dim myNameSpace As Outlook.NameSpace

 Dim myDestFolder As Outlook.Folder

 Dim mySourceFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myDestFolder = myNameSpace.GetDefaultFolder(olFolderInbox).Folders("Test")

 Set mySourceFolder = myNameSpace.GetDefaultFolder(olFolderContacts).Folders.GetFirst

 Set myNewFolder = mySourceFolder.CopyTo(myDestFolder)

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.GetLast Method (Outlook)

 Copy code hover
[image]

Folders.GetLast Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the last object in the Folders collection.

Syntax

expression .GetLast

expression A variable that represents a Folders object.

Return Value

A Folder object that represents the last object contained by the collection.

Remarks

It returns Nothing if no last object exists, for example, if the collection is empty.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

Example

The following Visual Basic for Applications example searches the subfolders of Inbox for a folder called MyPersonalEmails and displays a message to the user. If you do not have a subfolder called MyPersonalEmails in your Inbox folder, the example will display nothing.

VBA Copy code Copy code
Sub TestGetLast()

 Dim nsp As Outlook.NameSpace

 Dim mpf As Outlook.Folder

 Dim mpfSubFolder As Outlook.Folder

 Dim flds As Outlook.Folders

 Dim idx As Integer

 Set nsp = Application.GetNamespace("MAPI")

 Set mpf = nsp.GetDefaultFolder(olFolderInbox)

 Set flds = mpf.Folders

 Set mpfSubFolder = flds.GetLast

 Do While Not mpfSubFolder Is Nothing

 If mpfSubFolder.Name = "MyPersonalEmails" Then

 MsgBox "The folder was found."

 Exit Do

 End If

 Set mpfSubFolder = flds.GetPrevious

 Loop

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.GetNext Method (Outlook)

 Copy code hover
[image]

Folders.GetNext Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the next object in the Folders collection.

Syntax

expression .GetNext

expression A variable that represents a Folders object.

Return Value

A Folder object that represents the next object contained by the collection.

Remarks

It returns Nothing if no next object exists, for example, if already positioned at the end of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

Example

The following Visual Basic for Applications example searches the subfolders of Inbox for a folder called MyPersonalEmails and displays a message to the user. If you do not have a subfolder called MyPersonalEmails in your Inbox folder, the example will display nothing.

VBA Copy code Copy code
Sub TestGetNext()

 Dim nsp As Outlook.NameSpace

 Dim mpf As Outlook.Folder

 Dim mpfSubFolder As Outlook.Folder

 Dim flds As Outlook.Folders

 Dim idx As Integer

 Set nsp = Application.GetNamespace("MAPI")

 Set mpf = nsp.GetDefaultFolder(olFolderInbox)

 Set flds = mpf.Folders

 Set mpfSubFolder = flds.GetFirst

 Do While Not mpfSubFolder Is Nothing

 If mpfSubFolder.Name = "MyPersonalEmails" Then

 MsgBox "The folder was found."

 Exit Do

 End If

 Set mpfSubFolder = flds.GetNext

 Loop

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.GetPrevious Method (Outlook)

 Copy code hover
[image]

Folders.GetPrevious Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the previous object in the Folders collection.

Syntax

expression .GetPrevious

expression A variable that represents a Folders object.

Return Value

A Folder object that represents the previous object contained by the collection.

Remarks

It returns Nothing if no previous object exists, for example, if already positioned at the beginning of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

Example

The following Visual Basic for Applications example searches the subfolders of Inbox for a folder called MyPersonalEmails and displays a message to the user. If you do not have a subfolder called MyPersonalEmails in your Inbox folder, the example will display nothing.

VBA Copy code Copy code
Sub TestGetPrevious()

 Dim nsp As Outlook.NameSpace

 Dim mpf As Outlook.Folder

 Dim mpfSubFolder As Outlook.Folder

 Dim flds As Outlook.Folders

 Dim idx As Integer

 Set nsp = Application.GetNamespace("MAPI")

 Set mpf = nsp.GetDefaultFolder(olFolderInbox)

 Set flds = mpf.Folders

 Set mpfSubFolder = flds.GetLast

 Do While Not mpfSubFolder Is Nothing

 If mpfSubFolder.Name = "MyPersonalEmails" Then

 MsgBox "The folder was found."

 Exit Do

 End If

 Set mpfSubFolder = flds.GetPrevious

 Loop

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Item Method (Outlook)

 Copy code hover
[image]

Folders.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a Folders object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A Folder object that represents the specified object.

Example

The following example adds the public folder Internal to the user's Favorites folder by using the AddToPFFavorites method.

VBA Copy code Copy code
Sub AddToFavorites()

 'Adds a Public Folder to the List of favorites

 Dim objFolder As Outlook.Folder

 Set objFolder = Application.Session.GetDefaultFolder(olPublicFoldersAllPublicFolders).Folders.Item("GroupDiscussion").Folders.Item("Standards").Folders.Item("Internal")

 objFolder.AddToPFFavorites

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.Remove Method (Outlook)

 Copy code hover
[image]

Folders.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents a Folders object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders Events (Outlook)

 Copy code hover
[image]

Folders Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
FolderAdd | Occurs when a folder is added to the specified Folders collection.
FolderChange | Occurs when a folder in the specified Folders collection is changed.
FolderRemove | Occurs when a folder is removed from the specified Folders collection.


Folders.FolderAdd Event (Outlook)

 Copy code hover
[image]

Folders.FolderAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a folder is added to the specified Folders collection.

Syntax

expression .FolderAdd(Folder)

expression A variable that represents a Folders object.

Parameters

Name | Required/Optional | Data Type | Description
Folder | Required | Folder | The Folder that is added.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example displays a new folder created in the user's Inbox folder.

VBA Copy code Copy code
Public WithEvents myOlFolders As Outlook.Folders

Public Sub Initialize_handler()

 Set myOlFolders = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Folders

End Sub

Private Sub myOlFolders_FolderAdd(ByVal Folder As Outlook.Folder)

 Folder.Display

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.FolderChange Event (Outlook)

 Copy code hover
[image]

Folders.FolderChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a folder in the specified Folders collection is changed.

Syntax

expression .FolderChange(Folder)

expression A variable that represents a Folders object.

Parameters

Name | Required/Optional | Data Type | Description
Folder | Required | Folder | The folder that has been changed.

Remarks

The FolderChange event fires when a folder in a Folders collection object is changed, either through user action or program code. The change can be a user or program code renaming the folder, or adding, changing, or removing an item in the folder. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example prompts the user to remove a folder from the Deleted Items folder if the folder is empty. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myFolders As Outlook.Folders

Sub Initialize_handler()

 Set myNS = Application.GetNamespace("MAPI")

 Set myFolders = myNS.GetDefaultFolder(olFolderDeletedItems).Folders

End Sub

Private Sub myFolders_FolderChange(ByVal Folder As Outlook.Folder)

 If Folder.Items.Count = 0 Then

 MyPrompt = Folder.Name & " is empty. Do you want to delete it?"

 If MsgBox(MyPrompt, vbYesNo + vbQuestion) = vbYes Then

 Folder.Delete

 End If

 End If

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


Folders.FolderRemove Event (Outlook)

 Copy code hover
[image]

Folders.FolderRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a folder is removed from the specified Folders collection.

Syntax

expression .FolderRemove

expression A variable that represents a Folders object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example displays a warning message when the user tries to a delete a folder in the Inbox. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim myNS As Outlook.NameSpace

Dim WithEvents myFolders As Outlook.Folders

Sub Initialize_handler()

 Set myNS = Application.GetNamespace("MAPI")

 Set myFolders = myNS.GetDefaultFolder(olFolderInbox).Folders

End Sub

Private Sub myFolders_FolderRemove()

 MsgBox ("All the items in the folder are deleted as well.")

End Sub

See also

Concepts

Folders Object

Other resources

Folders Object Members


FormDescription Object (Outlook)

 Copy code hover
[image]

FormDescription Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the general properties of a Outlook form.

Remarks

The properties of an Outlook form are displayed on the Properties page of a form in design time.

To see the Properties page in design time, open the Outlook item, on the Developer tab of the Microsoft Office Fluent ribbon, click Design This Form, and then click the Properties tab in the item's window.

Use the FormDescription property to return the FormDescription object associated with an Outlook item.

See also

Concepts

Outlook Object Model Reference

Other resources

FormDescription Object Members


FormDescription Members (Outlook)

 Copy code hover
[image]

FormDescription Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the general properties of a Outlook form.

Methods

Name | Description
PublishForm | Saves the definition of the FormDescription object in the specified form registry (library).

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Category | Returns or sets a String representing the category assigned to the form description. Read/write.
CategorySub | Returns or sets a String representing the subcategory assigned to the form description. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Comment | Returns or sets a String representing the text of a comment assigned to the form description. Read/write.
ContactName | Returns or sets a String representing the name of the person to contact for information regarding the custom form for this FormDescription object. Read/write.
DisplayName | Returns or sets a String representing the name of the form, which is displayed in the Choose Forms dialog box. Read/write.
Hidden | Returns a Boolean value that indicates True to cause the specified custom form to be hidden. Read/write.
Icon | Returns or sets a String representing the file name of the icon to be displayed for the form. Read/write.
Locked | Returns a Boolean value that indicates True if the form cannot be modified. Read/write.
MessageClass | Returns a String representing the message class for the FormDescription object. Read-only.
MiniIcon | Returns or sets a String representing the file name of the mini-icon to be displayed for the form. Read/write.
Name | Returns or sets a String value that represents the display name for a form. Read/write.
Number | Returns or sets a String corresponding to the number for the specified form. Read/write.
OneOff | Returns a Boolean value that indicates True if the form will be discarded after using once (one-off), and False if the form is retained as a custom form. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
ScriptText | Returns a String containing all the VBScript code in the form's Script Editor. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Template | Returns or sets a String indicating the name of the template for the form. Read/write.
UseWordMail | Returns a Boolean that indicates True to use Microsoft Office Word as the default editor for the form. Read/write.
Version | Returns or sets a String indicating the number of the version. Read/write.


FormDescription Properties (Outlook)

 Copy code hover
[image]

FormDescription Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Category | Returns or sets a String representing the category assigned to the form description. Read/write.
CategorySub | Returns or sets a String representing the subcategory assigned to the form description. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Comment | Returns or sets a String representing the text of a comment assigned to the form description. Read/write.
ContactName | Returns or sets a String representing the name of the person to contact for information regarding the custom form for this FormDescription object. Read/write.
DisplayName | Returns or sets a String representing the name of the form, which is displayed in the Choose Forms dialog box. Read/write.
Hidden | Returns a Boolean value that indicates True to cause the specified custom form to be hidden. Read/write.
Icon | Returns or sets a String representing the file name of the icon to be displayed for the form. Read/write.
Locked | Returns a Boolean value that indicates True if the form cannot be modified. Read/write.
MessageClass | Returns a String representing the message class for the FormDescription object. Read-only.
MiniIcon | Returns or sets a String representing the file name of the mini-icon to be displayed for the form. Read/write.
Name | Returns or sets a String value that represents the display name for a form. Read/write.
Number | Returns or sets a String corresponding to the number for the specified form. Read/write.
OneOff | Returns a Boolean value that indicates True if the form will be discarded after using once (one-off), and False if the form is retained as a custom form. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
ScriptText | Returns a String containing all the VBScript code in the form's Script Editor. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Template | Returns or sets a String indicating the name of the template for the form. Read/write.
UseWordMail | Returns a Boolean that indicates True to use Microsoft Office Word as the default editor for the form. Read/write.
Version | Returns or sets a String indicating the number of the version. Read/write.


FormDescription.Application Property (Outlook)

 Copy code hover
[image]

FormDescription.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Category Property (Outlook)

 Copy code hover
[image]

FormDescription.Category Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the category assigned to the form description. Read/write.

Syntax

expression .Category

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.CategorySub Property (Outlook)

 Copy code hover
[image]

FormDescription.CategorySub Property (Outlook)
See also Send feedback

Returns or sets a String representing the subcategory assigned to the form description. Read/write.

Syntax

expression .CategorySub

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Class Property (Outlook)

 Copy code hover
[image]

FormDescription.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Comment Property (Outlook)

 Copy code hover
[image]

FormDescription.Comment Property (Outlook)
See also Send feedback

Returns or sets a String representing the text of a comment assigned to the form description. Read/write.

Syntax

expression .Comment

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.ContactName Property (Outlook)

 Copy code hover
[image]

FormDescription.ContactName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the name of the person to contact for information regarding the custom form for this FormDescription object. Read/write.

Syntax

expression .ContactName

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.DisplayName Property (Outlook)

 Copy code hover
[image]

FormDescription.DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the name of the form, which is displayed in the Choose Forms dialog box. Read/write.

Syntax

expression .DisplayName

expression A variable that represents a FormDescription object.

Remarks

If both the FormDescription.Name and FormDescription.DisplayName properties are empty, setting one will set the other. If one has been previously set, setting the other will not change the value.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Hidden Property (Outlook)

 Copy code hover
[image]

FormDescription.Hidden Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates True to cause the specified custom form to be hidden. Read/write.

Syntax

expression .Hidden

expression A variable that represents a FormDescription object.

Remarks

The custom form will not appear on the menu or in the Choose Form dialog box and will be used only if it is designated as the response form from another custom form. The default value is False.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Icon Property (Outlook)

 Copy code hover
[image]

FormDescription.Icon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the file name of the icon to be displayed for the form. Read/write.

Syntax

expression .Icon

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Locked Property (Outlook)

 Copy code hover
[image]

FormDescription.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates True if the form cannot be modified. Read/write.

Syntax

expression .Locked

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.MessageClass Property (Outlook)

 Copy code hover
[image]

FormDescription.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the message class for the FormDescription object. Read-only.

Syntax

expression .MessageClass

expression A variable that represents a FormDescription object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
FormDescription Object

Other resources

FormDescription Object Members


FormDescription.MiniIcon Property (Outlook)

 Copy code hover
[image]

FormDescription.MiniIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the file name of the mini-icon to be displayed for the form. Read/write.

Syntax

expression .MiniIcon

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Name Property (Outlook)

 Copy code hover
[image]

FormDescription.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for a form. Read/write.

Syntax

expression .Name

expression A variable that represents a FormDescription object.

Remarks

The Name is also the caption for a form. This property must be set before you can use the FormDescription.PublishForm method.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Number Property (Outlook)

 Copy code hover
[image]

FormDescription.Number Property (Outlook)
See also Send feedback

Returns or sets a String corresponding to the number for the specified form. Read/write.

Syntax

expression .Number

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.OneOff Property (Outlook)

 Copy code hover
[image]

FormDescription.OneOff Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates True if the form will be discarded after using once (one-off), and False if the form is retained as a custom form. Read/write.

Syntax

expression .OneOff

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Parent Property (Outlook)

 Copy code hover
[image]

FormDescription.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.ScriptText Property (Outlook)

 Copy code hover
[image]

FormDescription.ScriptText Property (Outlook)
See also Send feedback

Returns a String containing all the VBScript code in the form's Script Editor. Read-only.

Syntax

expression .ScriptText

expression A variable that represents a FormDescription object.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the Open event to access the HTMLBody property of a MailItem. This sets the EditorType property of the MailItem's Inspector to olEditorHTML. When the MailItem's Body property is set, the EditorType property is changed to the default. For example, if the default e-mail editor is set to RTF, the EditorType is set to olEditorRTF. If this code is placed in the Script Editor of a form in design mode, the message boxes during run time will reflect the change in the EditorType as the body of the form changes. The final message box uses the Script Text property to display all the VBScript code in the Script Editor.

Copy code Copy code
Function Item_Open()

 'Set the HTMLBody of the item.

 Item.HTMLBody = "<HTML><H2>My HTML page.</H2><BODY>My body.</BODY></HTML>"

 'Item displays HTML message.

 Item.Display

 'MsgBox shows EditorType is 2.

 MsgBox "HTMLBody EditorType is " & Item.GetInspector.EditorType

 'Access the Body and show

 'the text of the Body.

 MsgBox "This is the Body: " & Item.Body

 'After accessing, EditorType

 'is still 2.

 MsgBox "After accessing, the EditorType is " & Item.GetInspector.EditorType

 'Set the item's Body property.

 Item.Body = "Back to default body."

 'After setting, EditorType is

 'now back to the default.

 MsgBox "After setting, the EditorType is " & Item.GetInspector.EditorType

 'Access the items's

 'FormDescription object.

 Set myForm = Item.FormDescription

 'Display all the code

 'in the Script Editor.

 MsgBox myForm.ScriptText

End Function

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Session Property (Outlook)

 Copy code hover
[image]

FormDescription.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a FormDescription object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Template Property (Outlook)

 Copy code hover
[image]

FormDescription.Template Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the name of the template for the form. Read/write.

Syntax

expression .Template

expression A variable that represents a FormDescription object.

Remarks

This property refers to a Microsoft Office Word .DOT template file, and so is applicable for forms with UseWordMail = True.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.UseWordMail Property (Outlook)

 Copy code hover
[image]

FormDescription.UseWordMail Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True to use Microsoft Office Word as the default editor for the form. Read/write.

Syntax

expression .UseWordMail

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription.Version Property (Outlook)

 Copy code hover
[image]

FormDescription.Version Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the number of the version. Read/write.

Syntax

expression .Version

expression A variable that represents a FormDescription object.

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormDescription Methods (Outlook)

 Copy code hover
[image]

FormDescription Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
PublishForm | Saves the definition of the FormDescription object in the specified form registry (library).


FormDescription.PublishForm Method (Outlook)

 Copy code hover
[image]

FormDescription.PublishForm Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the definition of the FormDescription object in the specified form registry (library).

Syntax

expression .PublishForm(Registry, Folder)

expression A variable that represents a FormDescription object.

Parameters

Name | Required/Optional | Data Type | Description
Registry | Required | OlFormRegistry | The form class.
Folder | Optional | Variant | Expression that returns a Folder object. Used only with Folder form registry. The folder object from which the forms must be accessed.

Remarks

Note Note

The Name property must be set before you can use the PublishForm method.

Forms are registered as one of three classes: Folder, Organization, or Personal. The Folder form registry holds a set of forms that are only accessible from that specific folder, whether public or private. The Organization form registry holds forms that are shared across an entire enterprise and are accessible to everyone. The Personal form registry holds forms that are accessible only to the current store user.

Example

This Visual Basic for Applications (VBA) example creates a contact, obtains its FormDescription object, and saves it in the Folder form registry of the default Contacts folder.

Note Note

The PublishForm method will return an error if the caption (Name) for the form is not set first.

VBA Copy code Copy code
Sub PublishToFolder()

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItem As Outlook.ContactItem

 Dim myForm As Outlook.FormDescription

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = _

 myNamespace.GetDefaultFolder(olFolderContacts)

 Set myItem = Application.CreateItem(olContactItem)

 Set myForm = myItem.FormDescription

 myForm.Name = "My Contact"

 myForm.PublishForm olFolderRegistry, myFolder

End Sub

This VBA example creates an appointment, obtains its FormDescription object, and saves it in the user's Personal form registry.

To view the form after you have published it, on the File menu, point to New, and click Choose Form. In the Look in box, click Personal Forms Library. To open your new form, double-click Interview Scheduler.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olAppointmentItem)

Set myForm = myItem.FormDescription

myForm.Name = "Interview Scheduler"

myForm.PublishForm olPersonalRegistry

See also

Concepts

FormDescription Object

Other resources

FormDescription Object Members


FormNameRuleCondition Object (Outlook)

 Copy code hover
[image]

FormNameRuleCondition Object (Outlook)
See also Send feedback

Represents a rule condition that evaluates whether a form name was used to send or receive an item.

Version Information

Version Added: Outlook 2007

Remarks

FormNameRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has a FormName property. The FormName property always returns a FormNameRuleCondition object. If the rule has any of these rule conditions enabled, then FormNameRuleCondition.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition Members (Outlook)

 Copy code hover
[image]

FormNameRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether a form name was used to send or receive an item.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionFormName, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
FormName | Returns or sets an Object that represents an array of form identifiers to be evaluated by the rule condition. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


FormNameRuleCondition Properties (Outlook)

 Copy code hover
[image]

FormNameRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionFormName, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
FormName | Returns or sets an Object that represents an array of form identifiers to be evaluated by the rule condition. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


FormNameRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a FormNameRuleCondition object.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a FormNameRuleCondition object.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Returns a constant, olConditionFormName, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a FormNameRuleCondition object.

Remarks

The form name rule condition is supported by rules for receiving messages and rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a FormNameRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it has been saved successfully.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.FormName Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.FormName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an Object that represents an array of form identifiers to be evaluated by the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FormName

expression A variable that represents a FormNameRuleCondition object.

Remarks

Even though the Rules and Alerts Wizard uses the display name of a form as an identifier, programmatically, FormName uses the message class of the form as an identifier.

You can assign an array with one string or an array of multiple strings to the FormName property. Multiple form identifiers assigned in an array are evaluated using the logical OR operation.

FormName returns an error if it contains one or more empty strings.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a FormNameRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormNameRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

FormNameRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a FormNameRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

FormNameRuleCondition Object

Other resources

FormNameRuleCondition Object Members


FormRegion Object (Outlook)

 Copy code hover
[image]

FormRegion Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a form region in an Outlook form.

Version Information

Version Added: Outlook 2007

Remarks

The FormRegion object allows an add-in to add code behind a form region in a custom form to modify the appearance and behavior of the form region.

To obtain an instance of the FormRegion object, an add-in must implement the FormRegionStartup interface. Outlook allocates storage for the form region, instantiates an instance of the FormRegion object, and returns the FormRegion object in the GetFormRegionStorage method.

When the add-in closes the frame for the form region, the add-in must release the object for the form region.

For more infomation on programming a form region, see Extending a Form Region with an Add-in.

See also

Concepts

Outlook Object Model Reference

Other resources

FormRegion Object Members


FormRegion Members (Outlook)

 Copy code hover
[image]

FormRegion Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a form region in an Outlook form.

Events

Name | Description
Close | Represents the closing of the frame for a form region, which occurs just before the Close event of the Inspector associated with the Outlook item.
Expanded | Occurs when the form region expands or collapses

Methods

Name | Description
Reflow | Causes Outlook to recalculate the height of an adjoining form region to display all the visible controls in the form region.
Select | Makes the form region the active form region such that it becomes visible.
SetControlItemProperty | Binds an explicit built-in property or a custom property to a control in the form region.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Detail | Returns or sets a String representing the text displayed at runtime in the header after the display name of an adjoining form region. Read/write.
DisplayName | Returns a String representing the display name of the form region. Read-only.
EnableAutoLayout | Returns or sets a Boolean that specifies whether to use the automatic layout resizing feature when designing form regions in the forms designer. Read/write
Form | Returns an Object representing the MSForms.UserForm object. Read-only.
FormRegionMode | Returns an OlFormRegionMode constant that indicates whether the form region is in a read page, compose page, or Reading Pane. Read-only.
Inspector | Returns an Inspector object representing the Inspector that hosts the form region. Read-only.
InternalName | Returns a String that represents the internal programmatic name of the form region as defined in the manifest for the form region. Read-only.
IsExpanded | Returns a Boolean that indicates if the form region is expanded. Read-only.
Item | Returns an Object corresponding to the Outlook item bound to the form region. Read-only.
Language | Returns a Long that indicates the LCID for the current language. Read-only.
Parent | Returns the parent Object of the form region. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SuppressControlReplacement | Returns or sets a Boolean that disables Outlook from automatically replacing a Forms 2.0 control by a themed Outlook control at design time and runtime. Read/write.
Visible | Returns or sets a Boolean value that indicates whether the form region is visible or hidden. Read/write.


FormRegion Properties (Outlook)

 Copy code hover
[image]

FormRegion Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Detail | Returns or sets a String representing the text displayed at runtime in the header after the display name of an adjoining form region. Read/write.
DisplayName | Returns a String representing the display name of the form region. Read-only.
EnableAutoLayout | Returns or sets a Boolean that specifies whether to use the automatic layout resizing feature when designing form regions in the forms designer. Read/write
Form | Returns an Object representing the MSForms.UserForm object. Read-only.
FormRegionMode | Returns an OlFormRegionMode constant that indicates whether the form region is in a read page, compose page, or Reading Pane. Read-only.
Inspector | Returns an Inspector object representing the Inspector that hosts the form region. Read-only.
InternalName | Returns a String that represents the internal programmatic name of the form region as defined in the manifest for the form region. Read-only.
IsExpanded | Returns a Boolean that indicates if the form region is expanded. Read-only.
Item | Returns an Object corresponding to the Outlook item bound to the form region. Read-only.
Language | Returns a Long that indicates the LCID for the current language. Read-only.
Parent | Returns the parent Object of the form region. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SuppressControlReplacement | Returns or sets a Boolean that disables Outlook from automatically replacing a Forms 2.0 control by a themed Outlook control at design time and runtime. Read/write.
Visible | Returns or sets a Boolean value that indicates whether the form region is visible or hidden. Read/write.


FormRegion.Application Property (Outlook)

 Copy code hover
[image]

FormRegion.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Class Property (Outlook)

 Copy code hover
[image]

FormRegion.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Detail Property (Outlook)

 Copy code hover
[image]

FormRegion.Detail Property (Outlook)
See also Send feedback

Returns or sets a String representing the text displayed at runtime in the header after the display name of an adjoining form region. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Detail

expression A variable that represents a FormRegion object.

Remarks

The Detail property is displayed for adjoining form regions only. It is ignored for separate form regions.

The Detail property is optional for an adjoining form region.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.DisplayName Property (Outlook)

 Copy code hover
[image]

FormRegion.DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the form region. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayName

expression A variable that represents a FormRegion object.

Remarks

The display name is optional for a form region. If you have defined a value for the <formRegionName> tag in the corresponding form region manifest XML file, this value will map to the value of the DisplayName property. For more information on the XML schema for form regions, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

The value of the DisplayName property is displayed at runtime in the Show tab of the ribbon for a separate form region, or in the header of an adjoining form region. It is used for the default locale, and can be overridden by the <stringOverride> tag in the corresponding form region manifest XML file. The string is case-insensitive, and its maximum length is 256 characters.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.EnableAutoLayout Property (Outlook)

 Copy code hover
[image]

FormRegion.EnableAutoLayout Property (Outlook)
See also Send feedback

Returns or sets a Boolean that specifies whether to use the automatic layout resizing feature when designing form regions in the forms designer. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .EnableAutoLayout

expression A variable that represents a FormRegion object.

Remarks

The automatic layout resizing feature in the forms designer recalculates the form layout dynamically as the form is resized. This feature is only available to form regions in the forms designer.

When this property is True, the forms designer performs automatic layout resizing. When this property is False, the forms designer does not perform automatic layout resizing. The default value is True.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Form Property (Outlook)

 Copy code hover
[image]

FormRegion.Form Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object representing the MSForms.UserForm object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Form

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.FormRegionMode Property (Outlook)

 Copy code hover
[image]

FormRegion.FormRegionMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlFormRegionMode constant that indicates whether the form region is in a read page, compose page, or Reading Pane. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FormRegionMode

expression A variable that represents a FormRegion object.

Remarks

If the user has a mail item in the Reading Pane, you can use the MailItem.Sent property to further determine if the user is in the edit mode or the read mode of the Reading Pane. A mail item is displayed differently in the Reading Pane if it is in the edit mode (the mail item is in the Draft folder) than if it is in the read mode (the mail item is in the Inbox or Sent folder).

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Inspector Property (Outlook)

 Copy code hover
[image]

FormRegion.Inspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object representing the Inspector that hosts the form region. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Inspector

expression A variable that represents a FormRegion object.

Remarks

Returns Null (Nothing in Visual Basic) if the form region is displayed in the Reading Pane.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.InternalName Property (Outlook)

 Copy code hover
[image]

FormRegion.InternalName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the internal programmatic name of the form region as defined in the manifest for the form region. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .InternalName

expression A variable that represents a FormRegion object.

Remarks

The internal name is required for a form region. The <name> tag in the corresponding form region manifest XML file maps to the value of the InternalName property. For more information on the XML schema for form regions, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

The value of the InternalName property is used by the add-in or Microsoft Outlook to refer to the form region, for example, to determine which form region is being loaded or to load strings from the localized string resources. The InternalName property supports only ASCII characters. The string is case-insensitive, and its maximum length is 256 characters.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.IsExpanded Property (Outlook)

 Copy code hover
[image]

FormRegion.IsExpanded Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the form region is expanded. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsExpanded

expression A variable that represents a FormRegion object.

Remarks

This property applies to adjoining form regions only and is ignored for separate form regions.

Outlook always first loads a form region in an expanded state and sets IsExpanded to True. If the initial state of the form region is to be collapsed, then Outlook immediately closes the form region, fires the Expanded event with the Expand parameter being False, and sets IsExpanded to False.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Item Property (Outlook)

 Copy code hover
[image]

FormRegion.Item Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object corresponding to the Outlook item bound to the form region. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Language Property (Outlook)

 Copy code hover
[image]

FormRegion.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long that indicates the LCID for the current language. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Language

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Parent Property (Outlook)

 Copy code hover
[image]

FormRegion.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the form region. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Session Property (Outlook)

 Copy code hover
[image]

FormRegion.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a FormRegion object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.SuppressControlReplacement Property (Outlook)

 Copy code hover
[image]

FormRegion.SuppressControlReplacement Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that disables Outlook from automatically replacing a Forms 2.0 control by a themed Outlook control at design time and runtime. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SuppressControlReplacement

expression A variable that represents a FormRegion object.

Remarks

For more information on Outlook automatically replacing a Forms 2.0 control by a themed Outlook counterpart control, see Controls in a Custom Form.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Visible Property (Outlook)

 Copy code hover
[image]

FormRegion.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the form region is visible or hidden. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Visible

expression A variable that represents a FormRegion object.

Remarks

True if the form region is visible; False if it is hidden. The default is True.

Use the Visible property to control access to information without displaying it in a form region.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion Methods (Outlook)

 Copy code hover
[image]

FormRegion Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Reflow | Causes Outlook to recalculate the height of an adjoining form region to display all the visible controls in the form region.
Select | Makes the form region the active form region such that it becomes visible.
SetControlItemProperty | Binds an explicit built-in property or a custom property to a control in the form region.


FormRegion.Reflow Method (Outlook)

 Copy code hover
[image]

FormRegion.Reflow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Causes Outlook to recalculate the height of an adjoining form region to display all the visible controls in the form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reflow

expression A variable that represents a FormRegion object.

Remarks

The Reflow method only applies to adjoining form regions. No action occurs for separate form regions.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Select Method (Outlook)

 Copy code hover
[image]

FormRegion.Select Method (Outlook)
See also Send feedback

Published: July 16, 2012

Makes the form region the active form region such that it becomes visible.

Version Information

Version Added: Outlook 2007

Syntax

expression .Select

expression A variable that represents a FormRegion object.

Remarks

If the form region is an adjoining form region, then Select will expand the form region (if it is not already expanded) and set focus on the first control on that page. If the form region is a separate form region and is not already the active page, then Select will swtich to the form region page and set focus on the first control on that page. If the form region is a separate form region and is already the active page, then nothing happens.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.SetControlItemProperty Method (Outlook)

 Copy code hover
[image]

FormRegion.SetControlItemProperty Method (Outlook)
See also Send feedback

Published: July 16, 2012

Binds an explicit built-in property or a custom property to a control in the form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetControlItemProperty(Control, PropertyName)

expression A variable that represents a FormRegion object.

Parameters

Name | Required/Optional | Data Type | Description
Control | Required | Object | A control in the form region to which the property specified by PropertyName will be bound.
PropertyName | Required | String | The name of the property that will be bound to the control.

Remarks

You can use this method to bind an explicit built-in property or a custom property to a control. You must reference the property by its string name, for example, Subject, and not by namespace, for example, http://schemas.microsoft.com/mapi/proptag/0x0037001E.

The PropertyName parameter is not case-sensitive. For example, SetControlItemProperty interprets an argument, CustomerId, to be the same as CustomerID and binds the specified control to the built-in ContactItem.CustomerID property.

Other than using the SetControlItemProperty method of a FormRegion object, you can also use code similar to the following to bind a property such as the Subject property to a control:

Copy code Copy code
myPage.Controls("bar").ItemProperty = "subject"

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion Events (Outlook)

 Copy code hover
[image]

FormRegion Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
Close | Represents the closing of the frame for a form region, which occurs just before the Close event of the Inspector associated with the Outlook item.
Expanded | Occurs when the form region expands or collapses


FormRegion.Close Event (Outlook)

 Copy code hover
[image]

FormRegion.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the closing of the frame for a form region, which occurs just before the Close event of the Inspector associated with the Outlook item.

Version Information

Version Added: Outlook 2007

Syntax

expression .Close

expression A variable that represents a FormRegion object.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegion.Expanded Event (Outlook)

 Copy code hover
[image]

FormRegion.Expanded Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the form region expands or collapses

Version Information

Version Added: Outlook 2007

Syntax

expression .Expanded(Expand)

expression A variable that represents a FormRegion object.

Parameters

Name | Required/Optional | Data Type | Description
Expand | Required | Boolean | True if the form region is expanding; False if the form region is collapsing.

Remarks

This event cannot be cancelled.

Outlook always first loads a form region in an expanded state and sets IsExpanded to True. If the initial state of the form region is to be collapsed, then Outlook immediately closes the form region, fires the Expanded event with the Expand parameter being False, and sets IsExpanded to False.

See also

Concepts

FormRegion Object

Other resources

FormRegion Object Members


FormRegionStartup Object (Outlook)

 Copy code hover
[image]

FormRegionStartup Object (Outlook)
See also Send feedback

Defines an interface that allows an add-in to specify the storage and the user interface of a form region, obtains an object for that form region, and determines when the form region is about to be displayed in a form or in the Reading Pane.

Version Information

Version Added: Outlook 2007

Remarks

The FormRegionStartup interface is an abstract class, which means that it cannot be instantiated directly. In Visual Basic, you can use the Implements keyword to provide the methods of FormRegionStartup in your add-in class as follows:

Copy code Copy code
Implements Outlook.FormRegionStartup

An add-in deploying a form region in an Outlook form on a client computer must implement the FormRegionStartup interface which consists of the two methods, BeforeFormRegionShow and GetFormRegionStorage. When Outlook loads the add-in, Outlook queries the IDTExtensibility2 interface for FormRegionStartup.

The add-in indicates the storage and layout file for the form region in GetFormRegionStorage. By calling GetFormRegionStorage, Outlook allocates storage and calculates the layout for the form region, instantiates an object for the form region, and returns a value representing the storage allocated to the add-in. If GetFormRegionStorage is successful, just before the form region is displayed in an Inspector window or in the Reading Pane, Outlook will call BeforeFormRegionShow and pass the FormRegion object of the form region to the add-in. The add-in uses this opportunity before the form region is displayed to update any controls in the form region.

When the add-in closes the frame for the form region, the add-in must release the object for the form region.

For more information on writing add-ins for form regions, see Extending a Form Region with an Add-in. For examples of add-ins in C# and Visual Basic .NET that implement FormRegionStartup, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

FormRegionStartup Object Members


FormRegionStartup Members (Outlook)

 Copy code hover
[image]

FormRegionStartup Members (Outlook)
Send feedback

Defines an interface that allows an add-in to specify the storage and the user interface of a form region, obtains an object for that form region, and determines when the form region is about to be displayed in a form or in the Reading Pane.

Methods

Name | Description
BeforeFormRegionShow | Allows an add-in to update the user interface of a form region before it is displayed.
GetFormRegionIcon | Obtains an icon image that will be displayed for a particular type of icon for the form region.
GetFormRegionManifest | Obtains the XML manifest for a form region.
GetFormRegionStorage | Obtains appropriate storage for a form region based on the specified information.


FormRegionStartup Methods (Outlook)

 Copy code hover
[image]

FormRegionStartup Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
BeforeFormRegionShow | Allows an add-in to update the user interface of a form region before it is displayed.
GetFormRegionIcon | Obtains an icon image that will be displayed for a particular type of icon for the form region.
GetFormRegionManifest | Obtains the XML manifest for a form region.
GetFormRegionStorage | Obtains appropriate storage for a form region based on the specified information.


FormRegionStartup.BeforeFormRegionShow Method (Outlook)

 Copy code hover
[image]

FormRegionStartup.BeforeFormRegionShow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Allows an add-in to update the user interface of a form region before it is displayed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeFormRegionShow(FormRegion)

expression A variable that represents a FormRegionStartup object.

Parameters

Name | Required/Optional | Data Type | Description
FormRegion | Required | FormRegion | The FormRegion object representing the form region that is to be displayed.

Remarks

This method lets Outlook pass the FormRegion object to the add-in, and allows an add-in to update the user interface of the form region before it is displayed so that, for instance, the text of labels can be changed or irrelevant content can be suppressed. It is called after the controls are instantiated and the layout is calculated, but before the form region is made visible.

When implementing this method, keep in mind that the item obtained from the FormRegion parameter (that is, the Item property of the FormRegion object) is read-only.

For examples of add-ins in C# and Visual Basic .NET that implement FormRegionStartup, see code sample downloads on MSDN.

See also

Concepts

FormRegionStartup Interface

Other resources

FormRegionStartup Object Members


FormRegionStartup.GetFormRegionIcon Method (Outlook)

 Copy code hover
[image]

FormRegionStartup.GetFormRegionIcon Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains an icon image that will be displayed for a particular type of icon for the form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetFormRegionIcon(FormRegionName, LCID, Icon)

expression A variable that represents a FormRegionStartup object.

Parameters

Name | Required/Optional | Data Type | Description
FormRegionName | Required | String | The name of the form region which is the name used when registering the form region in the Windows registry.
LCID | Required | Long | The locale ID that identifies the language that Outlook is currently using. This value is used to obtain the localization strings corresponding to this language for the form region.
Icon | Required | OlFormRegionIcon | A constant that identifies the type of icon.

Return Value

A Variant that is either a byte-array that represents the original bytes of the image file or an IPictureDisp object.

Remarks

This method is intended to be implemented by an add-in and called by Outlook. As part of the FormRegionStartup interface, this method and the GetFormRegionManifest method provide a mechanism through which an add-in can register a form region and provide Outlook with the XML manifest and the icons for the form region.

If you would like an add-in to provide icons for a form region, specify the ProgID of the add-in when you register the form region in the Windows registry. For more information on registering a form region, see Specifying Form Regions in the Windows Registry. The add-in must implement the GetFormRegionManifest and the GetFormRegionIcon methods of the FormRegionStartup interface.

In the XML manifest for the form region, under the icons element, specify the value addin for each of the child elements where you would like to use a custom icon. Implement GetFormRegionIcon such that when Outlook passes that type of icon as an argument for Icon, GetFormRegionIcon returns the image of the custom icon. If you want Outlook to display the default icon, implement GetFormRegionIcon such that it returns null (Nothing in Visual Basic) for that type of icon. GetFormRegionIcon should also return null (Nothing in Visual Basic) when Icon is olFormRegionIconDefault.

When Outlook starts, it reads the list of form regions from the Windows registry and caches the data associated with the form regions. If a form region has been registered with a ProgID, Outlook will resort to the corresponding add-in by calling its implementation of GetFormRegionIcon for any icon in the XML manifest that has addin as the value of a child element of the icons element. Note that if you do not specify any ProgID in the Windows registry, Outlook will not call the GetFormRegionManifest and GetFormRegionIcon methods.

See also

Concepts

FormRegionStartup Interface

Other resources

FormRegionStartup Object Members


FormRegionStartup.GetFormRegionManifest Method (Outlook)

 Copy code hover
[image]

FormRegionStartup.GetFormRegionManifest Method (Outlook)
See also Send feedback

Obtains the XML manifest for a form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetFormRegionManifest(FormRegionName, LCID)

expression A variable that represents a FormRegionStartup object.

Parameters

Name | Required/Optional | Data Type | Description
FormRegionName | Required | String | The name of the form region which is the name used when registering the form region in the Windows registry.
LCID | Required | Long | The locale ID that identifies the language that Outlook is currently using. This value is used to obtain the localization strings corresponding to this language for the form region.

Return Value

A Variant that represents the XML manifest for a form region. This XML string includes characteristics of the form region such as the display name (as specified by the title element), any associated layout file or add-in, any supported user actions, and any localization strings. The XML must follow the form region XML schema. For more information on the form region XML schema, see the Microsoft Outlook 2010 XML Schema Reference in the MSDN Library.

Remarks

This method is intended to be implemented by an add-in and called by Outlook. As part of the FormRegionStartup interface, this method and the GetFormRegionIcon method provide a mechanism through which an add-in can register a form region and provide Outlook the XML manifest and the icons for the form region.

If you would like an add-in to provide the XML manifest for a form region, specify the ProgID of the add-in when you register the form region in the Windows registry. For more information on registering a form region, see Specifying Form Regions in the Windows Registry. The add-in must implement the GetFormRegionManifest method of the FormRegionStartup interface. Note that if you do not specify any ProgID in the Windows registry, Outlook will not call this method.

Relying on an add-in to provide the XML manifest for a form region also means you are allowing the add-in to provide any icons for the form region. The add-in must also implement the GetFormRegionIcon of the FormRegionStartup interface. Outlook will call GetFormRegionIcon to obtain any add-in specified icons for the form region. For more information on using an add-in to specify icons, see How to: Use an Add-in to Specify Icons for a Form Region.

When Outlook starts, it reads the list of form regions from the Windows registry and caches the data. Based on this data, if Outlook notices that an add-in has been specified to provide the XML manifest for a form region, Outlook will use the ProgID provided in the cached data and call the GetFormRegionManifest method implemented by this add-in to obtain the XML it needs to display the form region. If the XML manifest is not valid and does not conform to the form region XML schema, Outlook will not be able to load the form region. Also, if you do not specify any ProgID in the Windows registry, Outlook will not call the GetFormRegionManifest and GetFormRegionIcon methods.

Outlook ignores the following elements when the add-in provides the XML manifest:

  • name: Outlook ignores the value specified for this element and will use the name specified for the form region in the registry.

  • layoutFile: Outlook ignores this element because an add-in is extending this form region.

  • addin: Outlook uses the value that is preceded by an equal sign (=) in the registry as the ProgID of the add-in.

  • file attribute of stringOverride: Outlook ignores any secondary localization file specified by the stringOverride element. The add-in can implement GetFormRegionManifest to return inline the XML manifest for string localization for the specified LCID, or manage string localization in another way, for example, using .NET Framework localization, and then return the appropriate XML manifest for the specified LCID.

See also

Concepts

FormRegionStartup Interface

Other resources

FormRegionStartup Object Members


FormRegionStartup.GetFormRegionStorage Method (Outlook)

 Copy code hover
[image]

FormRegionStartup.GetFormRegionStorage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains appropriate storage for a form region based on the specified information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetFormRegionStorage(FormRegionName, Item, LCID, FormRegionMode, FormRegionSize)

expression A variable that represents an object that implements the FormRegionStartup interface.

Parameters

Name | Required/Optional | Data Type | Description
FormRegionName | Required | String | The internal name of the form region. This can be indicated by the <name> tag in the corresponding form region XML manifest.
Item | Required | Object | The Outlook item object that caused the loading of the form region.
LCID | Required | Long | The current locale ID.
FormRegionMode | Required | OlFormRegionMode | The mode that the form region is being loaded into.
FormRegionSize | Required | OlFormRegionSize | The type of form region being loaded, either adjoining or separate.

Return Value

A Variant object representing the storage that Outlook has allocated for the form region. The type of the return value can be: String representing that the return value is a local path to an Outlook Form Storage (.OFS) file; Byte() representing that the return value is an array of bytes that contains the contents of the .OFS file; IStorage representing that the return value is a COM storage object IStorage (for C++ only); Nothing or Null, representing that Outlook could not allocate storage for this form region and will not load the form region.

Remarks

The add-in must check for the return value of GetFormRegionStorage. A form region will not load if any of the following is true of the returned storage:

  • The returned storage is a .OFS file specified with a non-local path.

  • The returned storage is a file but is not an .OFS file saved from the forms designer.

For examples of add-ins in C# and Visual Basic .NET that implement the FormRegionStartup interface, see code sample downloads on MSDN.

See also

Concepts

FormRegionStartup Interface

Other resources

FormRegionStartup Object Members


FromRssFeedRuleCondition Object (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether an item is from a specified RSS subscription.

Version Information

Version Added: Outlook 2007

Remarks

FromRssFeedRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object, which has a RuleConditions.FromRssFeed property. The FromRssFeed property always returns a FromRssFeedRuleCondition object. If the rule has any of these rule conditions enabled, then FromRssFeedRuleCondition.Enabled is True.

For more information about specifying rule actions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition Members (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates whether an item is from a specified RSS subscription.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionFromRssFeed, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
FromRssFeed | Returns or sets an array of String elements that represent the RSS subscriptions that are being evaluated by the rule condition. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


FromRssFeedRuleCondition Properties (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionFromRssFeed, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
FromRssFeed | Returns or sets an array of String elements that represent the RSS subscriptions that are being evaluated by the rule condition. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


FromRssFeedRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a FromRssFeedRuleCondition object.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a FromRssFeedRuleCondition object.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olConditionFromRssFeed, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a FromRssFeedRuleCondition object.

Remarks

This rule condition is supported by rules for receiving messages. For more information, see Specifying Rule Conditions.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a FromRssFeedRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is enabled only after it has been saved successfully.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.FromRssFeed Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.FromRssFeed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an array of String elements that represent the RSS subscriptions that are being evaluated by the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FromRssFeed

expression A variable that represents a FromRssFeedRuleCondition object.

Remarks

Each element of the array is a single RSS subscription. Multiple RSS subscriptions are evaluated as logical OR conditions.

You cannot obtain a list of valid RSS subscription names through the Outlook object model. You can obtain a list of valid RSS subscription names from the XML file Outlook.Sharing.xml.obi, which is located in the folder [drive]\Documents and Settings\[UserName]\Local Settings\Application Data\Microsoft\Outlook\. The name attribute of the <local> tag contains the name of the RSS subscription that must be supplied in the array of strings for FromRssFeed. To enumerate all RSS subscriptions, examine the <bindings> tag where <binding prov="{0006F0AF-0000-0000-C000-000000000046}">.

Returns an error if one or more elements in the array contains an empty string or an invalid RSS subscription.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a FromRssFeedRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


FromRssFeedRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

FromRssFeedRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a FromRssFeedRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

FromRssFeedRuleCondition Object

Other resources

FromRssFeedRuleCondition Object Members


IconView Object (Outlook)

 Copy code hover
[image]

IconView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items as a series of labeled icons.

Version Information

Version Added: Outlook 2007

Remarks

The IconView object, derived from the View object, allows you to create customizable views that allow you to display Outlook items as large or small icons, with labels.

Outlook provides several built-in views, and you can also create custom IconView objects. Use the Add method of the Views collection to add a new IconView to a Folder object. Use the Standard property to determine if an existing IconView object is built-in or custom.

The IconView object supports several different view types, depending on the desired layout in which to display Outlook items. Use the IconViewType property to set the view type.

You can also configure how Outlook items appear within the IconView object. Use the IconPlacement property to determine how the icons for Outlook items are arranged within the view. Use the Filter property to determine which Outlook items to display in the view and the SortFields collection to specify the Outlook item properties by which Outlook items are sorted in the view.

The definition for each IconView object is stored in Extensible Markup Language (XML) format. Use the XML property to work with the XML definition for the IconView object.

Use the Apply method to apply any changes made to the IconView object to the current view. Use the Save method to persist any changes made to the IconView object. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

You can change built-in IconView objects, but you cannot delete them. Use the Delete method to delete a custom IconView object. Use the Reset method to reset the properties of a built-in IconView object to their default values.

See also

Concepts

Outlook Object Model Reference

Other resources

IconView Object Members


IconView Members (Outlook)

 Copy code hover
[image]

IconView Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items as a series of labeled icons.

Methods

Name | Description
Apply | Applies the IconView object to the current view.
Copy | Creates a new View object based on the existing IconView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
IconPlacement | Returns or sets an OlIconViewPlacement value that determines how icons are placed within the IconView object. Read/write.
IconViewType | Returns or sets an OlIconViewType constant that determines how Outlook items are displayed in the IconView object. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the IconView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the IconView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


IconView Properties (Outlook)

 Copy code hover
[image]

IconView Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
IconPlacement | Returns or sets an OlIconViewPlacement value that determines how icons are placed within the IconView object. Read/write.
IconViewType | Returns or sets an OlIconViewType constant that determines how Outlook items are displayed in the IconView object. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the IconView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the IconView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


IconView.Application Property (Outlook)

 Copy code hover
[image]

IconView.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Class Property (Outlook)

 Copy code hover
[image]

IconView.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Filter Property (Outlook)

 Copy code hover
[image]

IconView.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents an IconView object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.IconPlacement Property (Outlook)

 Copy code hover
[image]

IconView.IconPlacement Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlIconViewPlacement value that determines how icons are placed within the IconView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IconPlacement

expression A variable that represents an IconView object.

Remarks

If the value of the IconViewType property is set to olIconViewList, the value of this property is automatically set to olIconSortAndAutoArrange.

Example

The following Visual Basic for Applications (VBA) example configures the current IconView object to display Outlook items as a sorted, auto-arranged set of large icons.

Copy code Copy code
Sub ConfigureIconView()
 Dim objIconView As IconView

 ' Check if the current view is an icon view.
 If Application.ActiveExplorer.CurrentView.ViewType = _
 olIconView Then

 ' Obtain a IconView object reference for the
 ' current icon view.
 Set objIconView = _
 Application.ActiveExplorer.CurrentView

 With objIconView
 ' Display items in the icon view as a
 ' set of large icons.
 .IconViewType = olIconLarge

 ' Sort and auto arrange the items
 ' within the icon view.
 .IconPlacement = olIconSortAndAutoArrange

 ' Save the icon view.
 .Save
 End With
 End If

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.IconViewType Property (Outlook)

 Copy code hover
[image]

IconView.IconViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlIconViewType constant that determines how Outlook items are displayed in the IconView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IconViewType

expression A variable that represents an IconView object.

Remarks

If the value of this property is set to olIconSortAndAutoArrange, the value of the IconPlacement property is automatically set to olIconSortAndAutoArrange.

Example

The following Visual Basic for Applications (VBA) example configures the current IconView object to display Outlook items as a sorted, auto-arranged set of large icons.

Copy code Copy code
Sub ConfigureIconView()

 Dim objIconView As IconView

 ' Check if the current view is an icon view.

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olIconView Then

 ' Obtain a IconView object reference for the

 ' current icon view.

 Set objIconView = _

 Application.ActiveExplorer.CurrentView

 With objIconView

 ' Display items in the icon view as a

 ' set of large icons.

 .IconViewType = olIconLarge

 ' Sort and auto arrange the items

 ' within the icon view.

 .IconPlacement = olIconSortAndAutoArrange

 ' Save the icon view.

 .Save

 End With

 End If

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Language Property (Outlook)

 Copy code hover
[image]

IconView.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the language setting for the view. Read/write.

Syntax

expression .Language

expression A variable that represents an IconView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the language type of all View objects of type olTableView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olTableVIew then set language.

 If objView.ViewType = olTableView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

IconView.LockUserChanges Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression A variable that represents an IconView object.

Remarks

If True, the user can modify the settings of the current view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Name Property (Outlook)

 Copy code hover
[image]

IconView.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Parent Property (Outlook)

 Copy code hover
[image]

IconView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.SaveOption Property (Outlook)

 Copy code hover
[image]

IconView.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression A variable that represents an IconView object.

Remarks

The value of the SaveOption property is set when the IconView object is created by using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = _

 olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Session Property (Outlook)

 Copy code hover
[image]

IconView.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an IconView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.SortFields Property (Outlook)

 Copy code hover
[image]

IconView.SortFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields object that represents the set of fields by which the items displayed in the IconView object are ordered. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SortFields

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Standard Property (Outlook)

 Copy code hover
[image]

IconView.Standard Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the IconView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression A variable that represents an IconView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object, using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.ViewType Property (Outlook)

 Copy code hover
[image]

IconView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.XML Property (Outlook)

 Copy code hover
[image]

IconView.XML Property (Outlook)
See also Send feedback

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression A variable that represents an IconView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView Methods (Outlook)

 Copy code hover
[image]

IconView Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the IconView object to the current view.
Copy | Creates a new View object based on the existing IconView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


IconView.Apply Method (Outlook)

 Copy code hover
[image]

IconView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the IconView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Copy Method (Outlook)

 Copy code hover
[image]

IconView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing IconView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents an IconView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Delete Method (Outlook)

 Copy code hover
[image]

IconView.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.GoToDate Method (Outlook)

 Copy code hover
[image]

IconView.GoToDate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents an IconView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Reset Method (Outlook)

 Copy code hover
[image]

IconView.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression A variable that represents an IconView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

IconView Object

Other resources

IconView Object Members


IconView.Save Method (Outlook)

 Copy code hover
[image]

IconView.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents an IconView object.

See also

Concepts

IconView Object

Other resources

IconView Object Members


ImportanceRuleCondition Object (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that evaluates the importance of a message.

Version Information

Version Added: Outlook 2007

Remarks

ImportanceRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has an Importance property. The Importance property always returns a ImportanceRuleCondition object. If the rule has any of these rule conditions enabled, then ImportanceRuleCondition.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition Members (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition Members (Outlook)
Send feedback

Represents a rule condition that evaluates the importance of a message.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionImportance, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative level of importance for the message. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ImportanceRuleCondition Properties (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionImportance, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative level of importance for the message. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ImportanceRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents an ImportanceRuleCondition object.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents an ImportanceRuleCondition object.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olConditionImportance, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents an ImportanceRuleCondition object.

Remarks

The form name rule condition is supported by rules for receiving messages and rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an ImportanceRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it have been saved successfully.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.Importance Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative level of importance for the message. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Importance

expression A variable that represents an ImportanceRuleCondition object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents an ImportanceRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


ImportanceRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

ImportanceRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents an ImportanceRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ImportanceRuleCondition Object

Other resources

ImportanceRuleCondition Object Members


Inspector Object (Outlook)

 Copy code hover
[image]

Inspector Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the window in which an Outlook item is displayed.

Remarks

  • Use the ActiveInspector method to return the object representing the currently active inspector (if there is one).

  • Use the GetInspector property to return the Inspector object associated with an item.

  • Use the Display method to display an item in its associated inspector.

See also

Concepts

Outlook Object Model Reference

Other resources

Inspector Object Members


Inspector Members (Outlook)

 Copy code hover
[image]

Inspector Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the window in which an Outlook item is displayed.

Events

Name | Description
Activate | Occurs when an inspector becomes the active window, either as a result of user action or through program code.
AttachmentSelectionChange | Occurs when the user selects a different or additional attachment of an item in the active inspector programmatically or by interacting with the user interface.
BeforeMaximize | Occurs when an inspector is maximized by the user.
BeforeMinimize | Occurs when the active inspector is minimized by the user.
BeforeMove | Occurs when the Inspector is moved by the user.
BeforeSize | Occurs when the user sizes the current Inspector.
Close | Occurs when the inspector associated with a Microsoft Outlook item is being closed.
Deactivate | Occurs when an inspector stops being the active window, either as a result of user action or through program code.
PageChange | Occurs when the active form page changes, either programmatically or by user action, on an Inspector object.

Methods

Name | Description
Activate | Activates an inspector window by bringing it to the foreground and setting keyboard focus.
Close | Closes the Inspector and optionally saves changes to the displayed Outlook item.
Display | Displays a new Inspector object for the item.
HideFormPage | Hides a form page or a form region in the inspector.
IsWordMail | Determines whether the mail message associated with an inspector is displayed in an Outlook Inspector or in Microsoft Word.
NewFormRegion | Opens a new page in design mode in the inspector for a new form region.
OpenFormRegion | Opens a page in design mode in the inspector for the specified form region.
SaveFormRegion | Saves the specified page in design mode in the inspector to the specified file.
SetControlItemProperty | Binds a built-in property or custom property to a control in an inspector.
SetCurrentFormPage | Displays the specified form page or form region in the inspector.
SetSchedulingStartTime | Sets the start time for a meeting item in the free/busy grid on the Scheduling Assistant tab of the inspector.
ShowFormPage | Displays a button in the Show group of the Microsoft Office Fluent ribbon for the inspector, clicking which shows the page or form region specified by PageName.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AttachmentSelection | Returns an AttachmentSelection object consisting of one or more attachments that are selected in the inspector. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentItem | Returns an Object representing the current item being displayed in the inspector. Read-only.
EditorType | Returns an OlEditorType constant indicating the type of editor. Read-only.
Height | Returns or sets a Long specifying the height (in pixels) of the inspector window. Read/write.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an inspector window from the edge of the screen. Read/write.
ModifiedFormPages | Returns the Pages collection that represents all the pages for the item in the inspector. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an inspector window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.
WindowState | Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.
WordEditor | Returns the Microsoft Word Document Object Model of the message being displayed. Read-only.


Inspector Properties (Outlook)

 Copy code hover
[image]

Inspector Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AttachmentSelection | Returns an AttachmentSelection object consisting of one or more attachments that are selected in the inspector. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentItem | Returns an Object representing the current item being displayed in the inspector. Read-only.
EditorType | Returns an OlEditorType constant indicating the type of editor. Read-only.
Height | Returns or sets a Long specifying the height (in pixels) of the inspector window. Read/write.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an inspector window from the edge of the screen. Read/write.
ModifiedFormPages | Returns the Pages collection that represents all the pages for the item in the inspector. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an inspector window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.
WindowState | Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.
WordEditor | Returns the Microsoft Word Document Object Model of the message being displayed. Read-only.


Inspector.Application Property (Outlook)

 Copy code hover
[image]

Inspector.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.AttachmentSelection Property (Outlook)

 Copy code hover
[image]

Inspector.AttachmentSelection Property (Outlook)
See also Send feedback

Returns an AttachmentSelection object consisting of one or more attachments that are selected in the inspector. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .AttachmentSelection

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Caption Property (Outlook)

 Copy code hover
[image]

Inspector.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the title. Read-only.

Syntax

expression .Caption

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Class Property (Outlook)

 Copy code hover
[image]

Inspector.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.CurrentItem Property (Outlook)

 Copy code hover
[image]

Inspector.CurrentItem Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object representing the current item being displayed in the inspector. Read-only.

Syntax

expression .CurrentItem

expression A variable that represents an Inspector object.

Remarks

If no item is currently open, an error message will be returned.

Example

This Visual Basic for Applications (VBA) example uses the CurrentItem property to obtain the current item that the user is viewing and closes it. If no item is currently open, an error message will be returned.

VBA Copy code Copy code
Sub CloseItem()

 Dim myItem As Object

 Set myItem = Application.ActiveInspector.CurrentItem

 myItem.Close olSave

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.EditorType Property (Outlook)

 Copy code hover
[image]

Inspector.EditorType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlEditorType constant indicating the type of editor. Read-only.

Syntax

expression .EditorType

expression A variable that represents an Inspector object.

Remarks

Since Microsoft Office Outlook 2007, the EditorType property always returns olEditorWord.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the Open event to access the HTMLBody property of an item. This sets the EditorType property of the item's Inspector to olEditorHTML. If this code is placed in the Script Editor of a form in design mode, the message boxes during run time will reflect the change in the EditorType as the body of the form changes. The final message box utilizes the ScriptText property to display all the VBScript code in the Script Editor.

Copy code Copy code
Function Item_Open()
 'Set the HTMLBody of the item.
 Item.HTMLBody = "<HTML><H2>My HTML page.</H2><BODY>My body.</BODY></HTML>"
 'Item displays HTML message.
 Item.Display
 'MsgBox shows EditorType is 2 which represents the HTML editor type
 MsgBox "HTMLBody EditorType is " & Item.GetInspector.EditorType
 'Access the Body and show
 'the text of the Body.
 MsgBox "This is the Body: " & Item.Body
 'After accessing, EditorType
 'is still 2.
 MsgBox "After accessing, the EditorType is " & Item.GetInspector.EditorType
 'Set the item's Body property.
 Item.Body = "Back to default body."
 'After setting the Body, EditorType is
 'still the same.
 MsgBox "After setting, the EditorType is " & Item.GetInspector.EditorType
End Function

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Height Property (Outlook)

 Copy code hover
[image]

Inspector.Height Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the height (in pixels) of the inspector window. Read/write.

Syntax

expression .Height

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Left Property (Outlook)

 Copy code hover
[image]

Inspector.Left Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the position (in pixels) of the left vertical edge of an inspector window from the edge of the screen. Read/write.

Syntax

expression .Left

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.ModifiedFormPages Property (Outlook)

 Copy code hover
[image]

Inspector.ModifiedFormPages Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Pages collection that represents all the pages for the item in the inspector. Read-only.

Syntax

expression .ModifiedFormPages

expression A variable that represents an Inspector object.

Remarks

The main page and up to five customizable pages can be obtained using the Add method.

Example

This Visual Basic for Applications (VBA) displays the count of pages in the ModifiedFormPages collection. To run this example without any errors, display a contact item in the active window.

VBA Copy code Copy code
Sub CountModifiedFormPages()

 Dim myItem As Outlook.ContactItem

 Dim myPages As Outlook.Pages

 Set myItem = Application.ActiveInspector.CurrentItem

 Set myPages = myItem.GetInspector.ModifiedFormPages

 MsgBox myPages.Count

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Parent Property (Outlook)

 Copy code hover
[image]

Inspector.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Session Property (Outlook)

 Copy code hover
[image]

Inspector.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Inspector object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Top Property (Outlook)

 Copy code hover
[image]

Inspector.Top Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of an inspector window from the edge of the screen. Read/write.

Syntax

expression .Top

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Width Property (Outlook)

 Copy code hover
[image]

Inspector.Width Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.

Syntax

expression .Width

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.WindowState Property (Outlook)

 Copy code hover
[image]

Inspector.WindowState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets the property with a constant in the OlWindowState enumeration specifying the window state of an explorer or inspector window. Read/write.

Syntax

expression .WindowState

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.WordEditor Property (Outlook)

 Copy code hover
[image]

Inspector.WordEditor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Microsoft Word Document Object Model of the message being displayed. Read-only.

Syntax

expression .WordEditor

expression A variable that represents an Inspector object.

Remarks

The WordEditor property is only valid if the IsWordMail method returns True and the EditorType property is olEditorWord. The returned WordDocument object provides access to most of the Word object model except for the following members:

  • Tables.Add

  • Range.ConvertToTable

  • InlineShapes.AddChart

  • Shapes.AddChart

  • Range.InsertXML

  • Selection.InsertXML

  • Range.ImportFragment

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector Methods (Outlook)

 Copy code hover
[image]

Inspector Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Activate | Activates an inspector window by bringing it to the foreground and setting keyboard focus.
Close | Closes the Inspector and optionally saves changes to the displayed Outlook item.
Display | Displays a new Inspector object for the item.
HideFormPage | Hides a form page or a form region in the inspector.
IsWordMail | Determines whether the mail message associated with an inspector is displayed in an Outlook Inspector or in Microsoft Word.
NewFormRegion | Opens a new page in design mode in the inspector for a new form region.
OpenFormRegion | Opens a page in design mode in the inspector for the specified form region.
SaveFormRegion | Saves the specified page in design mode in the inspector to the specified file.
SetControlItemProperty | Binds a built-in property or custom property to a control in an inspector.
SetCurrentFormPage | Displays the specified form page or form region in the inspector.
SetSchedulingStartTime | Sets the start time for a meeting item in the free/busy grid on the Scheduling Assistant tab of the inspector.
ShowFormPage | Displays a button in the Show group of the Microsoft Office Fluent ribbon for the inspector, clicking which shows the page or form region specified by PageName.


Inspector.Activate Method (Outlook)

 Copy code hover
[image]

Inspector.Activate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Activates an inspector window by bringing it to the foreground and setting keyboard focus.

Syntax

expression .Activate

expression A variable that represents an Inspector object.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Close Method (Outlook)

 Copy code hover
[image]

Inspector.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes the Inspector and optionally saves changes to the displayed Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

Example

This Visual Basic for Applications (VBA) example saves and closes the item displayed in the active inspector without prompting the user. To run this example, you need to have an item displayed in an inspector window.

VBA Copy code Copy code
Sub CloseItem()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Set myinspector = Application.ActiveInspector

 Set myItem = myinspector.CurrentItem

 myItem.Close olSave

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Display Method (Outlook)

 Copy code hover
[image]

Inspector.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.HideFormPage Method (Outlook)

 Copy code hover
[image]

Inspector.HideFormPage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Hides a form page or a form region in the inspector.

Syntax

expression .HideFormPage(PageName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
PageName | Required | String | The display name of the form page, or the internal name of a form region to be hidden.

Remarks

You can use HideFormRegion to hide a form region by specifying the InternalName property of the form region, if the form region is an adjoining or separate form region. Only the add-in that implements the form region can hide the form region.

Example

This Visual Basic for Applications (VBA) example uses HideFormPage to hide the "General" page of a newly-created ContactItem and displays the item.

VBA Copy code Copy code
Sub HidePage()

 Dim MyItem As Outlook.ContactItem

 Dim myPages As Outlook.Pages

 Dim myinspector As Outlook.Inspector

 Set MyItem = Application.CreateItem(olContactItem)

 Set myPages = MyItem.GetInspector.ModifiedFormPages

 myPages.Add "General"

 Set myinspector = Application.ActiveInspector

 myinspector.HideFormPage "General"

 MyItem.Display

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.IsWordMail Method (Outlook)

 Copy code hover
[image]

Inspector.IsWordMail Method (Outlook)
See also Send feedback

Published: July 16, 2012

Determines whether the mail message associated with an inspector is displayed in an Outlook Inspector or in Microsoft Word.

Syntax

expression .IsWordMail

expression A variable that represents an Inspector object.

Return Value

True if the mail message is displayed in Microsoft Word (that is, if Word Mail is in use); otherwise, False.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.NewFormRegion Method (Outlook)

 Copy code hover
[image]

Inspector.NewFormRegion Method (Outlook)
See also Send feedback

Published: July 16, 2012

Opens a new page in design mode in the inspector for a new form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .NewFormRegion

expression A variable that represents an Inspector object.

Return Value

An Object that represents the page displaying the form region in the inspector.

Remarks

If the inspector is not already in design mode, NewFormRegion will put it in design mode.

This method only opens a page for a new form region in design mode. This method is not intended for creating a form region at runtime.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.OpenFormRegion Method (Outlook)

 Copy code hover
[image]

Inspector.OpenFormRegion Method (Outlook)
See also Send feedback

Opens a page in design mode in the inspector for the specified form region.

Version Information

Version Added: Outlook 2007

Syntax

expression .OpenFormRegion(Path)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | A full local file path to the Outlook Form Storage (.OFS) file for the form region that is to be opened in the inspector.

Return Value

An Object that represents the page displaying the form region in the inspector.

Remarks

If the inspector is not already in design mode, OpenFormRegion will put it in design mode.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.SaveFormRegion Method (Outlook)

 Copy code hover
[image]

Inspector.SaveFormRegion Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the specified page in design mode in the inspector to the specified file.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveFormRegion(Page, FileName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Page | Required | Object | The page displaying the form region in the inspector.
FileName | Required | String | The full local file path to an Outlook Form Storage (.OFS) file that the form region is being saved to.

Remarks

In order for SaveFormRegion to save the form region, the form region must have been loaded in design mode in the inspector.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.SetControlItemProperty Method (Outlook)

 Copy code hover
[image]

Inspector.SetControlItemProperty Method (Outlook)
See also Send feedback

Published: July 16, 2012

Binds a built-in property or custom property to a control in an inspector.

Syntax

expression .SetControlItemProperty(Control, PropertyName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Control | Required | Object | The control that will be bound to a property.
PropertyName | Required | String | The name of the property that will be bound to the control.

Remarks

You can use this method to bind an explicit built-in property or a custom property to a control. You must reference the property by its string name, for example, Subject, and not by namespace, for example, http://schemas.microsoft.com/mapi/proptag/0x0037001E.

The PropertyName parameter is not case-sensitive. For example, SetControlItemProperty interprets an argument, CustomerId, to be the same as CustomerID and binds the specified control to the built-in ContactItem.CustomerID property.

You can also use the following line of code myPage.Controls("bar").ItemProperty = "subject" to bind the subject property to a control. However, note that untrusted code using this will trigger a security warning if the property is protected by the object model security guard such as To, and the client computer is running Microsoft Office Outlook 2007 or later but does not have an appropriately set up antivirus software. You can use the SetControlItemProperty method to avoid security warnings with trusted applications.

Example

The following Visual Basic for Applications (VBA) code adds a custom page to an appointment item, adds a custom textbox control, and binds that control to Subject property.

VBA Copy code Copy code
Sub Example()
 Dim myIns As Outlook.Inspector
 Dim myAppt As Outlook.AppointmentItem
 Dim ctrl As Object
 Dim ctrls As Object
 Dim myPages As Outlook.Pages
 Dim myPage As Object

 Set myAppt = Application.CreateItem(olAppointmentItem)
 Set myIns = myAppt.GetInspector

 Set myPages = myIns.ModifiedFormPages
 Set myPage = myPages.Add("New Page")
 myIns.ShowFormPage ("New Page")
 Set ctrls = myPage.Controls
 Set ctrl = ctrls.Add("Forms.TextBox.1")

 myIns.SetControlItemProperty ctrl, "Subject"

 myAppt.Display
End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.SetCurrentFormPage Method (Outlook)

 Copy code hover
[image]

Inspector.SetCurrentFormPage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the specified form page or form region in the inspector.

Syntax

expression .SetCurrentFormPage(PageName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
PageName | Required | String | The display name of the form page, or the internal name of a form region.

Remarks

You can use SetCurrentFormPage to display a form region by specifying the InternalName property of the form region, if the form region is an a separate, replace, or replace-all form region.

Example

This Visual Basic for Applications (VBA) example uses the SetCurrentFormPage method to show the All Fields page of the currently open item. If an error occurs, Outlook will display a message box to the user.

VBA Copy code Copy code
Sub ShowAllFieldsPage()

 On Error GoTo ErrorHandler

 Dim myInspector As Inspector

 Dim myItem As Object

 Set myInspector = Application.ActiveInspector

 myInspector.SetCurrentFormPage ("All Fields")

 Set myItem = myInspector.CurrentItem

 myItem.Display

Exit Sub

ErrorHandler:

 MsgBox Err.Description, vbInformation

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.SetSchedulingStartTime Method (Outlook)

 Copy code hover
[image]

Inspector.SetSchedulingStartTime Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the start time for a meeting item in the free/busy grid on the Scheduling Assistant tab of the inspector.

Version Information

Version Added: Outlook 2010

Syntax

expression .SetSchedulingStartTime(Start)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Start | Required | Date | The beginning of the time range that the Scheduling Assistant tab of the inspector displays free/busy times for meeting attendees.

Remarks

The object specified by the CurrentItem property of the parent Inspector object must be an AppointmentItem or MeetingItem. The Scheduling Assistant tab must be displayed in the inspector, otherwise Microsoft Outlook raises an error. If Outlook cannot display the Scheduling Assistant tab for that item type, Outlook displays the following error: The scheduling start time can only be set when the Scheduling Assistant is displayed on a meeting item.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) shows how to use the SetSchedulingStartTime method to set the scheduling start time on the Scheduling Assistant tab of an AppointmentItem. The appointment start time is set to one month from now, and the scheduling start time is also set to one month from now.

VBA Copy code Copy code
Sub DemoSetSchedulingStartTime()

 Dim oAppt As Outlook.AppointmentItem

 Dim oInsp As Outlook.inspector

 ' Create and display appointment.

 Set oAppt = Application.CreateItem(olAppointmentItem)

 oAppt.MeetingStatus = olMeeting

 oAppt.Subject = "Test Appointment"

 oAppt.Start = DateAdd("m", 1, Now)

 ' Display the appointment in the Appointment tab of the inspector.

 oAppt.Display

 Set oInsp = oAppt.GetInspector

 ' Switch to the Scheduling Assistant tab in that inspector.

 oInsp.SetCurrentFormPage ("Scheduling Assistant")

 ' Set the appointment start time in the Scheduling Assistant.

 oInsp.SetSchedulingStartTime (DateAdd("m", 1, Now))

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.ShowFormPage Method (Outlook)

 Copy code hover
[image]

Inspector.ShowFormPage Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a button in the Show group of the Microsoft Office Fluent ribbon for the inspector, clicking which shows the page or form region specified by PageName.

Syntax

expression .ShowFormPage(PageName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
PageName | Required | String | The display name of the form page, or the internal name of a form region to be shown.

Remarks

For form regions, you can use ShowFormRegion to display the button by specifying the InternalName property of the form region, if the form region is an adjoining or separate form region. Only the add-in that implements the form region can use ShowFormRegion to display the button.

Example

This Visual Basic for Applications (VBA) example uses the ShowFormPage method to show a button, labeled All Fields, in the Show group of the ribbon of the active inspector. Clicking the All Fields button displays the All Fields page of the currently open item. If an error occurs, Outlook will display a message box to the user.

VBA Copy code Copy code
Sub ShowAllFieldsPage()

 On Error GoTo ErrorHandler

 Dim myInspector As Outlook.Inspector

 Dim myItem As Object

 Set myInspector = Application.ActiveInspector

 myInspector.ShowFormPage ("All Fields")

 Set myItem = myInspector.CurrentItem

 myItem.Display

 Exit Sub

ErrorHandler:

 MsgBox Err.Description, vbInformation

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector Events (Outlook)

 Copy code hover
[image]

Inspector Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
Activate | Occurs when an inspector becomes the active window, either as a result of user action or through program code.
AttachmentSelectionChange | Occurs when the user selects a different or additional attachment of an item in the active inspector programmatically or by interacting with the user interface.
BeforeMaximize | Occurs when an inspector is maximized by the user.
BeforeMinimize | Occurs when the active inspector is minimized by the user.
BeforeMove | Occurs when the Inspector is moved by the user.
BeforeSize | Occurs when the user sizes the current Inspector.
Close | Occurs when the inspector associated with a Microsoft Outlook item is being closed.
Deactivate | Occurs when an inspector stops being the active window, either as a result of user action or through program code.
PageChange | Occurs when the active form page changes, either programmatically or by user action, on an Inspector object.


Inspector.Activate Event (Outlook)

 Copy code hover
[image]

Inspector.Activate Event (Outlook)
See also Send feedback

Occurs when an inspector becomes the active window, either as a result of user action or through program code.

Syntax

expression .Activate

expression A variable that represents an Inspector object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.AttachmentSelectionChange Event (Outlook)

 Copy code hover
[image]

Inspector.AttachmentSelectionChange Event (Outlook)
See also Send feedback

Occurs when the user selects a different or additional attachment of an item in the active inspector programmatically or by interacting with the user interface.

Version Information

Version Added: Outlook 2010

Syntax

expression .AttachmentSelectionChange

expression A variable that represents an Inspector object.

Remarks

The AttachmentSelectionChange event fires when a different or additional attachment of the item is selected in the inspector.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.BeforeMaximize Event (Outlook)

 Copy code hover
[image]

Inspector.BeforeMaximize Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an inspector is maximized by the user.

Syntax

expression .BeforeMaximize(Cancel)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the explorer or inspector is not maximized.

Remarks

This event can be cancelled after it has started.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.BeforeMinimize Event (Outlook)

 Copy code hover
[image]

Inspector.BeforeMinimize Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the active inspector is minimized by the user.

Syntax

expression .BeforeMinimize(Cancel)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the explorer or inspector is not minimized.

Remarks

This event can be cancelled after it has started.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.BeforeMove Event (Outlook)

 Copy code hover
[image]

Inspector.BeforeMove Event (Outlook)
See also Send feedback

Occurs when the Inspector is moved by the user.

Syntax

expression .BeforeMove(Cancel)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the inspector is not moved.

Remarks

This event can be cancelled after it has started.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.BeforeSize Event (Outlook)

 Copy code hover
[image]

Inspector.BeforeSize Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user sizes the current Inspector.

Syntax

expression .BeforeSize(Cancel)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the Inspector is not sized.

Remarks

This event can be cancelled after it has started. If the event is cancelled, the window is not sized.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a warning message before the inspector is sized. If the user clicks Yes, the inspector can be sized. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myIns As Outlook.Inspector

Public Sub Initalize_Handler()

 Set myIns = Application.ActiveInspector

End Sub

Private Sub myIns_BeforeSize(Cancel As Boolean)

 'Prompts the user before resizing the window

 Dim lngAns As Long

 lngAns = MsgBox("Are you sure you want to resize the current window? Use your keyboard to make your selection.", vbYesNo)

 If lngAns = vbYes Then

 Cancel = False

 Else

 Cancel = True

 End If

End Sub

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Close Event (Outlook)

 Copy code hover
[image]

Inspector.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with a Microsoft Outlook item is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents an Inspector object.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open. This event cannot be canceled.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.Deactivate Event (Outlook)

 Copy code hover
[image]

Inspector.Deactivate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an inspector stops being the active window, either as a result of user action or through program code.

Syntax

expression .Deactivate

expression A variable that represents an Inspector object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspector.PageChange Event (Outlook)

 Copy code hover
[image]

Inspector.PageChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the active form page changes, either programmatically or by user action, on an Inspector object.

Version Information

Version Added: Outlook 2007

Syntax

expression .PageChange(ActivePageName)

expression A variable that represents an Inspector object.

Parameters

Name | Required/Optional | Data Type | Description
ActivePageName | Required | String | The name of the active page.

Remarks

An error occurs if the event handler for this event calls either the Close or SetCurrentFormPage methods.

See also

Concepts

Inspector Object

Other resources

Inspector Object Members


Inspectors Object (Outlook)

 Copy code hover
[image]

Inspectors Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of Inspector objects representing all inspectors.

Remarks

An inspector need not be visible to be included in the collection.

Use the Inspectors property to return the Inspectors object from the Application object.

Example

The following example shows how to retrieve the Inspectors object in Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA).

VBA Copy code Copy code
Set myInspectors = Application.Inspectors

See also

Concepts

Outlook Object Model Reference

Other resources

Inspectors Object Members


Inspectors Members (Outlook)

 Copy code hover
[image]

Inspectors Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of Inspector objects representing all inspectors.

Events

Name | Description
NewInspector | Occurs whenever a new inspector window is opened, either as a result of user action or through program code.

Methods

Name | Description
Add | Creates a new inspector window.
Item | Returns an Inspector object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Inspectors Properties (Outlook)

 Copy code hover
[image]

Inspectors Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Inspectors.Application Property (Outlook)

 Copy code hover
[image]

Inspectors.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Inspectors object.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors.Class Property (Outlook)

 Copy code hover
[image]

Inspectors.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Inspectors object.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors.Count Property (Outlook)

 Copy code hover
[image]

Inspectors.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Inspectors object.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors.Parent Property (Outlook)

 Copy code hover
[image]

Inspectors.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Inspectors object.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors.Session Property (Outlook)

 Copy code hover
[image]

Inspectors.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Inspectors object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors Methods (Outlook)

 Copy code hover
[image]

Inspectors Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new inspector window.
Item | Returns an Inspector object from the collection.


Inspectors.Add Method (Outlook)

 Copy code hover
[image]

Inspectors.Add Method (Outlook)
See also Send feedback

Creates a new inspector window.

Syntax

expression .Add Item

expression A variable that represents an Inspectors object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item to display in the inspector window when it is created.

Return Value

An Inspector object that represents a new inspector window.

Remarks

This method is essentially identical to the GetInspector property of an Outlook item, such as MailItem.

Example

This Microsoft Visual Basic for Applications (VBA) example prompts the user for a company name, uses the Restrict method to locate all contact items in the Contacts folder with that name, and displays each one.

VBA Copy code Copy code
Sub DisplayMyContacts()

 Dim myFolder As Folder

 Dim myItems As Items

 Dim myRestrictItems As Items

 Dim answer As String

 Dim filter As String

 Dim myInspector As Inspector

 Dim x As Integer

 answer = InputBox("Enter the company name")

 Set myFolder = Application.GetNamespace("MAPI") _

 .GetDefaultFolder(olFolderContacts)

 filter = "[MessageClass] = 'IPM.Contact' AND [CompanyName] = '" & answer & "'"

 Set myItems = myFolder.Items

 Set myRestrictItems = myItems.Restrict(filter)

 For x = 1 To myRestrictItems.Count

 Set myInspector = Application.Inspectors.Add(myRestrictItems.Item(x))

 myInspector.Display

 Next x

End Sub

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors.Item Method (Outlook)

 Copy code hover
[image]

Inspectors.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an Inspectors object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Inspector object that represents the specified object.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


Inspectors Events (Outlook)

 Copy code hover
[image]

Inspectors Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
NewInspector | Occurs whenever a new inspector window is opened, either as a result of user action or through program code.


Inspectors.NewInspector Event (Outlook)

 Copy code hover
[image]

Inspectors.NewInspector Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs whenever a new inspector window is opened, either as a result of user action or through program code.

Syntax

expression .NewInspector(Inspector)

expression A variable that represents an Inspectors object.

Parameters

Name | Required/Optional | Data Type | Description
Inspector | Required | Inspector | The inspector that was opened.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

The event occurs after the new Inspector object is created but before the inspector window appears.

See also

Concepts

Inspectors Object

Other resources

Inspectors Object Members


ItemProperties Object (Outlook)

 Copy code hover
[image]

ItemProperties Object (Outlook)
See also Send feedback

Published: July 16, 2012

A collection of all properties associated with the item.

Remarks

Use the ItemProperties property to return the ItemProperties collection. Use ItemProperties.Item(index), where index is the name of the object or the numeric position of the item within the collection, to return a single ItemProperty object.

Note Note

The ItemProperties collection is zero-based, meaning that the first item in the collection is referenced by 0.

Use the Add method to add a new item property to the ItemProperties collection. Use the Remove method to remove an item property from the ItemProperties collection.

Note Note

You can only add or remove custom properties. Custom properties are denoted by the IsUserProperty.

Example

The following example creates a new MailItem object and stores its ItemProperties collection in a variable called objItems.

VBA Copy code Copy code
Sub ItemProperty()

 'Creates a new MailItem and access its properties

 Dim objMail As MailItem

 Dim objItems As ItemProperties

 Dim objItem As ItemProperty

 'Create the mail item

 Set objMail = Application.CreateItem(olMailItem)

 'Create a reference to the item properties collection

 Set objItems = objMail.ItemProperties

 'Create a reference to the item property page

 Set objItem = objItems.item(0)

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ItemProperties Object Members


ItemProperties Members (Outlook)

 Copy code hover
[image]

ItemProperties Members (Outlook)
Send feedback

Published: July 16, 2012

A collection of all properties associated with the item.

Methods

Name | Description
Add | Adds an ItemProperty object to the ItemProperties collection.
Item | Returns an ItemProperty object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ItemProperties Properties (Outlook)

 Copy code hover
[image]

ItemProperties Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ItemProperties.Application Property (Outlook)

 Copy code hover
[image]

ItemProperties.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an ItemProperties object.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Class Property (Outlook)

 Copy code hover
[image]

ItemProperties.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an ItemProperties object.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Count Property (Outlook)

 Copy code hover
[image]

ItemProperties.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an ItemProperties object.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Parent Property (Outlook)

 Copy code hover
[image]

ItemProperties.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an ItemProperties object.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Session Property (Outlook)

 Copy code hover
[image]

ItemProperties.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an ItemProperties object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties Methods (Outlook)

 Copy code hover
[image]

ItemProperties Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Add | Adds an ItemProperty object to the ItemProperties collection.
Item | Returns an ItemProperty object from the collection.
Remove | Removes an object from the collection.


ItemProperties.Add Method (Outlook)

 Copy code hover
[image]

ItemProperties.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds an ItemProperty object to the ItemProperties collection.

Syntax

expression .Add(Name, Type, AddToFolderFields, DisplayFormat)

expression A variable that represents an ItemProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new item property object.
Type | Required | OlUserPropertyType | The type of the new ItemProperty.
AddToFolderFields | Optional | Variant | Determines if the item property will be added to the folder fields.
DisplayFormat | Optional | Variant | Defines the format of the field as it appears in a given folder.

Remarks

You can create a property of a type that is defined by the OlUserPropertyType enumeration, except for the following types: olEnumeration, olOutlookInternal, and olSmartFrom.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Item Method (Outlook)

 Copy code hover
[image]

ItemProperties.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperty object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an ItemProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the zero-based index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An ItemProperty object that represents the specified object.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) assumes that you have opened a mail item in an Inspector. It shows how to loop from zero (0) to the total number of properties associated with the item minus one to display the name of each property.

VBA Copy code Copy code
Sub EnumerateItemProperties()

 Dim oM As Outlook.MailItem

 Dim i As Integer

 Set oM = Application.ActiveInspector.CurrentItem

 If Not (oM Is Nothing) Then

 For i = 0 To oM.ItemProperties.count - 1

 Debug.Print oM.ItemProperties(i).name

 Next

 End If

End Sub

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperties.Remove Method (Outlook)

 Copy code hover
[image]

ItemProperties.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an ItemProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The zero-based index value of the object within the collection.

See also

Concepts

ItemProperties Object

Other resources

ItemProperties Object Members


ItemProperty Object (Outlook)

 Copy code hover
[image]

ItemProperty Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents information about a given item property for a Microsoft Outlook item object.

Remarks

Each item property defines a certain attribute of the item, such as the name, type, or value of the item. The ItemProperty object is a member of the ItemProperties collection.

Use ItemProperties.Item(index), where index is the object's numeric position within the collection or it's name to return a single ItemProperty object.

Example

The following example creates a reference to the first ItemProperty object in the ItemProperties collection.

VBA Copy code Copy code
Sub NewMail()

 'Creates a new MailItem and references the ItemProperties collection.

 Dim objMail As MailItem

 Dim objitems As ItemProperties

 Dim objitem As ItemProperty

 'Create a new mail item

 Set objMail = Application.CreateItem(olMailItem)

 'Create a reference to the ItemProperties collection

 Set objitems = objMail.ItemProperties

 'Create reference to the first object in the collection

 Set objitem = objitems.item(0)

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ItemProperty Object Members


ItemProperty Members (Outlook)

 Copy code hover
[image]

ItemProperty Members (Outlook)
Send feedback

Published: July 16, 2012

Represents information about a given item property for a Microsoft Outlook item object.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsUserProperty | Returns a Boolean value that indicates if the item property is a custom property created by the user. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.
Value | Returns or sets a Variant indicating the value for the specified custom or explicit built-in property. Read/write.


ItemProperty Properties (Outlook)

 Copy code hover
[image]

ItemProperty Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsUserProperty | Returns a Boolean value that indicates if the item property is a custom property created by the user. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.
Value | Returns or sets a Variant indicating the value for the specified custom or explicit built-in property. Read/write.


ItemProperty.Application Property (Outlook)

 Copy code hover
[image]

ItemProperty.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an ItemProperty object.

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Class Property (Outlook)

 Copy code hover
[image]

ItemProperty.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an ItemProperty object.

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.IsUserProperty Property (Outlook)

 Copy code hover
[image]

ItemProperty.IsUserProperty Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates if the item property is a custom property created by the user. Read-only.

Syntax

expression .IsUserProperty

expression A variable that represents an ItemProperty object.

Example

The following example displays the names of all properties created by the user. The subroutine DisplayUserProps accepts an ItemProperties collection and searches through it, displaying the names of all ItemProperty objects where the IsUserProperty value is True. The ItemProperties collection is zero-based. In other words, the first object in the collection is accessed with an index value of zero (0).

VBA Copy code Copy code
Sub ItemProperty()
 'Creates a new mail item and access it's properties
 Dim objMail As MailItem
 Dim objitems As ItemProperties

 'Create the mail item
 Set objMail = Application.CreateItem(olMailItem)
 'Create a reference to the item properties collection
 Set objitems = objMail.ItemProperties
 'Create a reference to the item property page
 Call DisplayUserProps(objitems)
End Sub

Sub DisplayUserProps(ByVal objitems As ItemProperties)
 'Displays the names of all user-created item properties in the collection
 For i = 0 To objitems.Count - 1
 'Display name of property if it was created by the user
 If objitems.Item(i).IsUserProperty = True Then
 MsgBox "The property " & objitems(i).Name & " was created by the user."
 End If
 Next i
End Sub

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Name Property (Outlook)

 Copy code hover
[image]

ItemProperty.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents an ItemProperty object.

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Parent Property (Outlook)

 Copy code hover
[image]

ItemProperty.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an ItemProperty object.

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Session Property (Outlook)

 Copy code hover
[image]

ItemProperty.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an ItemProperty object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Type Property (Outlook)

 Copy code hover
[image]

ItemProperty.Type Property (Outlook)
See also Send feedback

Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.

Syntax

expression .Type

expression A variable that represents an ItemProperty object.

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


ItemProperty.Value Property (Outlook)

 Copy code hover
[image]

ItemProperty.Value Property (Outlook)
See also Send feedback

Returns or sets a Variant indicating the value for the specified custom or explicit built-in property. Read/write.

Syntax

expression .Value

expression A variable that represents an ItemProperty object.

Remarks

Even though ItemProperty.Value allows you to get or set an explicit built-in property or a custom property, you can reference explicit built-in properties directly from the parent object, for example, ContactItem.Body. For more information on accessing properties in Outlook, see Properties Overview.

Example

The following Visual Basic for Applications (VBA) example creates a contact item and sets its Body property

VBA Copy code Copy code
Sub ValueItemProperty()

 Dim cti As Outlook.ContactItem

 Dim itms As Outlook.ItemProperties

 Dim itm As Outlook.ItemProperty

 Set cti = Application.CreateItem(olContactItem)

 cti.FullName = "Dan Wilson"

 Set itms = cti.ItemProperties

 Set itm = itms.Item("Body")

 itm.Value = "My friend from school"

 cti.Save

 cti.Display

End Sub

See also

Concepts

ItemProperty Object

Other resources

ItemProperty Object Members


Items Object (Outlook)

 Copy code hover
[image]

Items Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of Outlook item objects in a folder.

Remarks

Use the Items property to return the Items object of a Folder object.

Use Items(index), where index is the name or index number, to return a single Outlook item.

Note Note

The index for the Items collection starts at 1, and the items in the Items collection object are not guaranteed to be in any particular order.

Example

The following Microsoft Visual Basic for Applications (VBA) example returns the first item in the Inbox with the Subject "Need your advice."

VBA Copy code Copy code
Sub GetItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItem As Object

 Set myNameSpace = Application.GetNameSpace("MAPI")

 Set myFolder = _

 myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myItem = myFolder.Items("Need your advice")

 myItem.Display

End sub

The following VBA example returns the first item in the Inbox. In Microsoft Office Outlook 2003 or later, the Items object returns the items in an Offline Folders file (.ost) in the reverse order.

VBA Copy code Copy code
Sub GetItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItem As Object

 Set myNameSpace = Application.GetNameSpace("MAPI")

 Set myFolder = _

 myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myItem = myFolder.Items(1)

 myItem.Display

End sub

See also

Concepts

Outlook Object Model Reference

Other resources

Items Object Members


Items Members (Outlook)

 Copy code hover
[image]

Items Members (Outlook)
Send feedback

Contains a collection of Outlook item objects in a folder.

Events

Name | Description
ItemAdd | Occurs when one or more items are added to the specified collection. This event does not run when a large number of items are added to the folder at once. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).
ItemChange | Occurs when an item in the specified collection is changed. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).
ItemRemove | Occurs when an item is deleted from the specified collection.

Methods

Name | Description
Add | Creates a new Outlook item in the Items collection for the folder.
Find | Locates and returns a Microsoft Outlook item object that satisfies the given Filter.
FindNext | After the Find method runs, this method finds and returns the next Outlook item in the specified collection.
GetFirst | Returns the first object in the collection.
GetLast | Returns the last object in the collection.
GetNext | Returns the next object in the collection.
GetPrevious | Returns the previous object in the collection.
Item | Returns an Outlook item from a collection.
Remove | Removes an object from the collection.
ResetColumns | Clears the properties that have been cached with the SetColumns method.
Restrict | Applies a filter to the Items collection, returning a new collection containing all of the items from the original that match the filter.
SetColumns | Caches certain properties for extremely fast access to those particular properties of each item in an Items collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
IncludeRecurrences | Returns a Boolean that indicates True if the Items collection should include recurrence patterns. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Items Properties (Outlook)

 Copy code hover
[image]

Items Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
IncludeRecurrences | Returns a Boolean that indicates True if the Items collection should include recurrence patterns. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Items.Application Property (Outlook)

 Copy code hover
[image]

Items.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an Items object.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Class Property (Outlook)

 Copy code hover
[image]

Items.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an Items object.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Count Property (Outlook)

 Copy code hover
[image]

Items.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an Items object.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.IncludeRecurrences Property (Outlook)

 Copy code hover
[image]

Items.IncludeRecurrences Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the Items collection should include recurrence patterns. Read/write.

Syntax

expression .IncludeRecurrences

expression A variable that represents an Items object.

Remarks

This property only has an effect if the Items collection contains appointments and is not sorted by any property other than Start in ascending order. The default value is False. Use this property when you want to retrieve all appointments for a given date, where recurring appointments would not normally appear because they are not associated with any specific date. If you need to sort and filter on appointment items that contain recurring appointments, you must do so in this order: sort the items in ascending order, set IncludeRecurrences to True, and then filter the items. For a code sample showing this order, see the second example below. If the collection includes recurring appointments with no end date, setting the property to True may cause the collection to be of infinite count. Be sure to include a test for this in any loop. You should not use Count property of Items collection when iterating Items collection with IncludeRecurrence property set to True. The value of Count will be an undefined value.

Example

The following Visual Basic for Applications (VBA) example displays the subject of the appointments that occur between today and tomorrow including recurring appointments.

VBA Copy code Copy code
Sub DemoFindNext()

 Dim myNameSpace As Outlook.NameSpace

 Dim tdystart As Date

 Dim tdyend As Date

 Dim myAppointments As Outlook.Items

 Dim currentAppointment As Outlook.AppointmentItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 tdystart = VBA.Format(Now, "Short Date")

 tdyend = VBA.Format(Now + 1, "Short Date")

 Set myAppointments = myNameSpace.GetDefaultFolder(olFolderCalendar).Items

 myAppointments.Sort "[Start]"

 myAppointments.IncludeRecurrences = True

 Set currentAppointment = myAppointments.Find("[Start] >= """ & _

 tdystart & """ and [Start] <= """ & tdyend & """")

 While TypeName(currentAppointment) <> "Nothing"

 MsgBox currentAppointment.Subject

 Set currentAppointment = myAppointments.FindNext

 Wend

End Sub

The example below shows the order to sort and filter on appointment items that contain recurring appointments.

VBA Copy code Copy code
Sub SortAndFilterAppointments()

 Dim myNameSpace As Outlook.NameSpace

 Dim myAppointments As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set calendarItems = myNameSpace.GetDefaultFolder(olFolderCalendar).Items

 calendarItems.Sort "[Start]"

 calendarItems.IncludeRecurrences = True

 Set restrictedItems = calendarItems.Restrict("[Organizer]='Dan Wilson'")

End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Parent Property (Outlook)

 Copy code hover
[image]

Items.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an Items object.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Session Property (Outlook)

 Copy code hover
[image]

Items.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an Items object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Items Object

Other resources

Items Object Members


Items Methods (Outlook)

 Copy code hover
[image]

Items Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new Outlook item in the Items collection for the folder.
Find | Locates and returns a Microsoft Outlook item object that satisfies the given Filter.
FindNext | After the Find method runs, this method finds and returns the next Outlook item in the specified collection.
GetFirst | Returns the first object in the collection.
GetLast | Returns the last object in the collection.
GetNext | Returns the next object in the collection.
GetPrevious | Returns the previous object in the collection.
Item | Returns an Outlook item from a collection.
Remove | Removes an object from the collection.
ResetColumns | Clears the properties that have been cached with the SetColumns method.
Restrict | Applies a filter to the Items collection, returning a new collection containing all of the items from the original that match the filter.
SetColumns | Caches certain properties for extremely fast access to those particular properties of each item in an Items collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.


Items.Add Method (Outlook)

 Copy code hover
[image]

Items.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new Outlook item in the Items collection for the folder.

Syntax

expression .Add Type

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Type | Optional | Variant | The Outlook item type for the new item. Specifies a MessageClass to create custom forms. Can be one of the following OlItemType constants: olAppointmentItem, olContactItem, olJournalItem, olMailItem, olNoteItem, olPostItem, or olTaskItem,, or any valid message class.

Return Value

An Object value that represents the new Outlook item.

Remarks

If not specified, the Type property of the Outlook item defaults to the type of the folder or to MailItem if the parent folder is not typed.

Example

This VBA example gets the current Contacts folder and adds a new ContactItem object to it and sets some initial values in the fields based on another contact. To run this example without any error, replace 'Dan Wilson' with a valid contact name that exists in your Contacts folder.

VBA Copy code Copy code
Sub AddContact()
 Dim myNamespace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myItem As Outlook.ContactItem
 Dim myOtherItem As Outlook.ContactItem

 Set myNamespace = Application.GetNamespace("MAPI")
 Set myFolder = myNamespace.GetDefaultFolder(olFolderContacts)
 Set myOtherItem = myFolder.Items("Dan Wilson")
 Set myItem = myFolder.Items.Add
 myItem.CompanyName = myOtherItem.CompanyName
 myItem.BusinessAddress = myOtherItem.BusinessAddress
 myItem.BusinessTelephoneNumber = myOtherItem.BusinessTelephoneNumber
 myItem.Display
End Sub

This VBA example adds a custom form to the default Tasks folder.

VBA Copy code Copy code
Sub AddForm()
 Dim myNamespace As outlook.NameSpace
 Dim myItems As outlook.Items
 Dim myFolder As outlook.Folder
 Dim myItem As outlook.TaskItem

 Set myNamespace = Application.GetNamespace("MAPI")
 Set myFolder = _
 myNamespace.GetDefaultFolder(olFolderTasks)
 Set myItems = myFolder.Items
 Set myItem = myItems.Add("IPM.Task.myTask")
End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Find Method (Outlook)

 Copy code hover
[image]

Items.Find Method (Outlook)
See also Send feedback

Published: July 16, 2012

Locates and returns a Microsoft Outlook item object that satisfies the given Filter.

Syntax

expression .Find(Filter)

expression An expression that returns a Items object.

Parameters

Name | Required/Optional | Data Type | Description
Filter | Required | String | A string that specifies the criteria that the returned object must satisfy.

Return Value

An Object value that represents an Outlook item if the call succeeds; returns Null (or Nothing in Visual Basic) if it fails.

Remarks

To use content indexing search in the Items collection, use the Restrict method. FindRow will return an error if Filter contains content indexing keywords. For more information on content indexing keywords, see Filtering Items Using Query Keywords.

The method will return an error with the following properties in the Filter:

Body | LastFirstNoSpaceCompany
Categories | LastFirstSpaceOnly
Children | LastFirstSpaceOnlyCompany
Class | LastFirstNoSpaceAndSuffix
Companies | MemberCount
CompanyLastFirstNoSpace | NetMeetingAlias
CompanyLastFirstSpaceOnly | NetMeetingAutoStart
ContactNames | NetMeetingOrganizerAlias
Contacts | NetMeetingServer
ConversationIndex | NetMeetingType
DLName | RecurrenceState
Email1EntryID | ReplyRecipients
Email2EntryID | ReceivedByEntryID
Email3EntryID | RecevedOnBehalfOfEntryID
EntryID | ResponseState
HTMLBody | Saved
IsOnlineMeeting | Sent
LastFirstAndSuffix | Submitted
LastFirstNoSpace | VotingOptions
AutoResolvedWinner | DownloadState
BodyFormat | IsConflict
InternetCodePage | MeetingWorkspaceURL
Permission |

Creating Filters for the Find and Restrict Methods

The syntax for the filter varies depending on the type of field you are filtering on.

String (for Text fields)

When filtering text fields, you can use either a pair of single quotes (') or a pair of double quotes (") to delimit the values that are part of the filter. For example, all of the following lines function correctly when the field is of type String:

Copy code Copy code
sFilter = "[CompanyName] = 'Microsoft'"
sFilter = "[CompanyName] = ""Microsoft"""
sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

In specifying a filter in a Jet or DASL query, if you use a pair of single quotes to delimit a string that is part of the filter, and the string contains another single quote or apostrophe, then add a single quote as an escape character before the single quote or apostrophe. Use a similar approach if you use a pair of double quotes to delimit a string. If the string contains a double quote, then add a double quote as an escape character before the double quote.

For example, in the DASL filter string that filters for the Subject property being equal to the word can't, the entire filter string is delimited by a pair of double quotes, and the embedded string can't is delimited by a pair of single quotes. There are three characters that you need to escape in this filter string: the starting double quote and the ending double quote for the property reference of http://schemas.microsoft.com/mapi/proptag/0x0037001f, and the apostrophe in the value condition for the word can't. Applying the appropriate escape characters, you can express the filter string as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'can''t'"

Alternatively, you can use the chr(34) function to represent the double quote (whose ASCII character value is 34) that is used as an escape character. Using the chr(34) substitution for a double-quote escape character, you can express the last example as follows:

Copy code Copy code
filter = "@SQL= " & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001f" _& Chr(34) & " = " & "'can''t'"

Escaping single and double quote characters is also required for DASL queries with the ci_startswith or ci_phrasematch operators. For example, the following query performs a phrase match query for can't in the message subject:

Copy code Copy code
filter = "@SQL=" & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001E" _& Chr(34) & " ci_phrasematch " & "'can''t'"

Another example is a DASL filter string that filters for the Subject property being equal to the words the right stuff, where the word stuff is enclosed by double quotes. In this case, you must escape the enclosing double quotes as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'the right ""stuff""'"

A different set of escaping rules apply to a property reference for named properties that contain the space, single quote, double quote, or percent character. For more information, see Referencing Properties by Namespace.

Date

Although dates and times are typically stored with a Date format, the Find and Restrict methods require that the date and time be converted to a string representation. To make sure that the date is formatted as Outlook expects, use the Format function. The following example creates a filter to find all contacts that have been modified after January 15, 1999 at 3:30 P.M.

Copy code Copy code
sFilter = "[LastModificationTime] > '" & Format("1/15/99 3:30pm", "ddddd h:nn AMPM") & "'"

Boolean Operators

Boolean operators, TRUE/FALSE, YES/NO, ON/OFF, and so on, should not be converted to a string. For example, to determine whether journaling is enabled for contacts, you can use this filter:

Copy code Copy code
sFilter = "[Journal] = True"
Note Note

If you use quotation marks as delimiters with Boolean fields, then an empty string will find items whose fields are False and all non-empty strings will find items whose fields are True.

Keywords (or Categories)

The Categories field is of type keywords, which is designed to hold multiple values. When accessing it programmatically, the Categories field behaves like a Text field, and the string must match exactly. Values in the text string are separated by a comma and a space. This typically means that you cannot use the Find and Restrict methods on a keywords field if it contains more than one value. For example, if you have one contact in the Business category and one contact in the Business and Social categories, you cannot easily use the Find and Restrict methods to retrieve all items that are in the Business category. Instead, you can loop through all contacts in the folder and use the Instr function to test whether the string "Business" is contained within the entire keywords field.

Note Note

A possible exception is if you limit the Categories field to two, or a low number of values. Then you can use the Find and Restrict methods with the OR logical operator to retrieve all Business contacts. For example (in pseudocode): "Business" OR "Business, Personal" OR "Personal, Business." Category strings are not case sensitive.

Integer

You can search for Integer fields with or without quotation marks as delimiters. The following filters will find contacts that were created with Outlook 2000:

Copy code Copy code
sFilter = "[OutlookInternalVersion] = 92711"
sFilter = "[OutlookInternalVersion] = '92711'"

Using Variables as Part of the Filter

As the Restrict method example illustrates, you can use values from variables as part of the filter. The following Microsoft Visual Basic Scripting Edition (VBScript) code sample illustrates syntax that uses variables as part of the filter.

Copy code Copy code
sFullName = "Dan Wilson"

This approach uses Chr(34) to delimit the value:

Copy code Copy code
sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)

This approach uses double quotation marks to delimit the value:

Copy code Copy code
sFilter = "[FullName] = """ & sFullName & """"

Using Logical Operators as Part of the Filter

Logical operators that are allowed are AND, OR, and NOT. The following are variations of the clause for the Restrict method, so you can specify multiple criteria.

OR: The following code returns all contact items that have either Business or Personal as their category.

Copy code Copy code
sFilter = "[Categories] = 'Personal' Or [Categories] = 'Business'"

AND: The following code retrieves all personal contacts who work at Microsoft.

Copy code Copy code
sFilter = "[Categories] = 'Personal' And [CompanyName] = 'Microsoft'"

NOT: The following code retrieves all personal contacts who don't work at Microsoft.

Copy code Copy code
sFilter = "[Categories] = 'Personal' And Not([CompanyName] = 'Microsoft')"

Additional Notes

If you are trying to use the Find or Restrict methods with user-defined fields, the fields must be defined in the folder, otherwise an error will occur. There is no way to perform a "contains" operation. For example, you cannot use Find or Restrict to search for items that have a particular word in the Subject field. Instead, you can use the AdvancedSearch method, or you can loop through all of the items in the folder and use the InStr function to perform a search within a field. You can use the Restrict method to search for items that begin within a certain range of characters. For example, to search for all contacts with a last name beginning with the letter M, use this filter:

Copy code Copy code
sFilter = "[LastName] > 'LZZZ' And [LastName] < 'N'"

See also

Concepts

Items Object

Other resources

Items Object Members


Items.FindNext Method (Outlook)

 Copy code hover
[image]

Items.FindNext Method (Outlook)
See also Send feedback

Published: July 16, 2012

After the Find method runs, this method finds and returns the next Outlook item in the specified collection.

Syntax

expression .FindNext

expression A variable that represents an Items object.

Return Value

An Object value that represents the next Outlook item found in the collection.

Remarks

The search operation begins from the current position, which matches the expression previously set through the Find method.

The method returns an Outlook item object if the call succeeds; it returns Null (or Nothing in Visual Basic) if it fails.

Example

This Visual Basic for Applications (VBA) example uses the GetDefaultFolder method to return the Folder object that represents the default Calendar folder for the current user. It then uses the Find and FindNext methods to locate all the appointments that occur today and display them in a series of message boxes.

VBA Copy code Copy code
Sub DemoFindNext()
 Dim myNameSpace As Outlook.NameSpace
 Dim tdystart As Date
 Dim tdyend As Date
 Dim myAppointments As Outlook.Items
 Dim currentAppointment As Outlook.AppointmentItem

 Set myNameSpace = Application.GetNamespace("MAPI")
 tdystart = VBA.Format(Now, "Short Date")
 tdyend = VBA.Format(Now + 1, "Short Date")
 Set myAppointments = myNameSpace.GetDefaultFolder(olFolderCalendar).Items
 Set currentAppointment = myAppointments.Find("[Start] >= """ & tdystart & """ and [Start] <= """ & tdyend & """")
 While TypeName(currentAppointment) <> "Nothing"
 MsgBox currentAppointment.Subject
 Set currentAppointment = myAppointments.FindNext
Wend
End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.GetFirst Method (Outlook)

 Copy code hover
[image]

Items.GetFirst Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the first object in the collection.

Syntax

expression .GetFirst

expression A variable that represents an Items object.

Return Value

An Object value that represents the first object contained by the collection.

Remarks

Returns Nothing if no first object exists, for example, if there are no objects in the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.GetLast Method (Outlook)

 Copy code hover
[image]

Items.GetLast Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the last object in the collection.

Syntax

expression .GetLast

expression A variable that represents an Items object.

Return Value

An Object value that represents the last object contained by the collection.

Remarks

It returns Nothing if no last object exists, for example, if the collection is empty. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.GetNext Method (Outlook)

 Copy code hover
[image]

Items.GetNext Method (Outlook)
See also Send feedback

Returns the next object in the collection.

Syntax

expression .GetNext

expression A variable that represents an Items object.

Return Value

An Object value that represents the next object contained by the collection.

Remarks

It returns Nothing if no next object exists, for example, if already positioned at the end of the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.GetPrevious Method (Outlook)

 Copy code hover
[image]

Items.GetPrevious Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the previous object in the collection.

Syntax

expression .GetPrevious

expression A variable that represents an Items object.

Return Value

An Object value that represents the previous object contained by the collection.

Remarks

It returns Nothing if no previous object exists, for example, if already positioned at the beginning of the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Item Method (Outlook)

 Copy code hover
[image]

Items.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Outlook item from a collection.

Syntax

expression .Item(Index)

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object value that represents the specified object.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Remove Method (Outlook)

 Copy code hover
[image]

Items.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.ResetColumns Method (Outlook)

 Copy code hover
[image]

Items.ResetColumns Method (Outlook)
See also Send feedback

Clears the properties that have been cached with the SetColumns method.

Syntax

expression .ResetColumns

expression A variable that represents an Items object.

Remarks

All properties are accessible after calling the ResetColumns method. SetColumns should be reused to store new properties again. ResetColumns does nothing if SetColumns has not been called first.

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Restrict Method (Outlook)

 Copy code hover
[image]

Items.Restrict Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies a filter to the Items collection, returning a new collection containing all of the items from the original that match the filter.

Syntax

expression .Restrict(Filter)

expression An expression that returns a Items object.

Parameters

Name | Required/Optional | Data Type | Description
Filter | Required | String | A filter string expression to be applied. For details, see the Find method.

Return Value

An Items collection that represents the items from the original Items collection which match the filter.

Remarks

This method is an alternative to using the Find method or FindNext method to iterate over specific items within a collection. The Find or FindNext methods are faster than filtering if there are a small number of items. The Restrict method is significantly faster if there is a large number of items in the collection, especially if only a few items in a large collection are expected to be found.

Note Note

If you are using user-defined fields as part of a Find or Restrict clause, the user-defined fields must exist in the folder. Otherwise the code will generate an error stating that the field is unknown. You can add a field to a folder by displaying the Field Chooser and clicking New.

This method cannot be used and will cause an error with the following properties:

Body | LastFirstNoSpaceCompany
Categories | LastFirstSpaceOnly
Children | LastFirstSpaceOnlyCompany
Class | LastFirstNoSpaceAndSuffix
Companies | MemberCount
CompanyLastFirstNoSpace | NetMeetingAlias
CompanyLastFirstSpaceOnly | NetMeetingAutoStart
ContactNames | NetMeetingOrganizerAlias
Contacts | NetMeetingServer
ConversationIndex | NetMeetingType
DLName | RecurrenceState
Email1EntryID | ReceivedByEntryID
Email2EntryID | RecevedOnBehalfOfEntryID
Email3EntryID | ReplyRecipients
EntryID | ResponseState
HTMLBody | Saved
IsOnlineMeeting | Sent
LastFirstAndSuffix | Submitted
LastFirstNoSpace | VotingOptions
AutoResolvedWinner | DownloadState
BodyFormat | IsConflict
InternetCodePage | MeetingWorkspaceURL
Permission |

Creating Filters for the Find and Restrict Methods

The syntax for the filter varies depending on the type of field you are filtering on.

String (for Text fields)

When filtering text fields, you can use either a pair of single quotes (') or a pair of double quotes ("), to delimit the values that are part of the filter. For example, all of the following lines function correctly when the field is of type String:

Copy code Copy code
sFilter = "[CompanyName] = 'Microsoft'" sFilter = "[CompanyName] = ""Microsoft"""
sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

In specifying a filter in a Jet or DASL query, if you use a pair of single quotes to delimit a string that is part of the filter, and the string contains another single quote or apostrophe, then add a single quote as an escape character before the single quote or apostrophe. Use a similar approach if you use a pair of double quotes to delimit a string. If the string contains a double quote, then add a double quote as an escape character before the double quote.

For example, in the DASL filter string that filters for the Subject property being equal to the word can't, the entire filter string is delimited by a pair of double quotes, and the embedded string can't is delimited by a pair of single quotes. There are three characters that you need to escape in this filter string: the starting double quote and the ending double quote for the property reference of http://schemas.microsoft.com/mapi/proptag/0x0037001f, and the apostrophe in the value condition for the word can't. Applying the appropriate escape characters, you can express the filter string as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'can''t'"

Alternatively, you can use the chr(34) function to represent the double quote (whose ASCII character value is 34) that is used as an escape character. Using the chr(34) substitution for a double-quote escape character, you can express the last example as follows:

Copy code Copy code
filter = "@SQL= " & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001f" _
    & Chr(34) & " = " & "'can''t'"

Escaping single and double quote characters is also required for DASL queries with the ci_startswith or ci_phrasematch operators. For example, the following query performs a phrase match query for can't in the message subject:

Copy code Copy code
filter = "@SQL=" & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001E" _
    & Chr(34) & " ci_phrasematch " & "'can''t'"

Another example is a DASL filter string that filters for the Subject property being equal to the words the right stuff, where the word stuff is enclosed by double quotes. In this case, you must escape the enclosing double quotes as follows:

Copy code Copy code
filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'the right ""stuff""'"

A different set of escaping rules apply to a property reference for named properties that contain the space, single quote, double quote, or percent character. For more information, see Referencing Properties by Namespace.

Date

Although dates and times are typically stored with a Date format, the Find and Restrict methods require that the date and time be converted to a string representation. To make sure that the date is formatted as Microsoft Outlook expects, use the Format function. The following example creates a filter to find all contacts that have been modified after January 15, 1999 at 3:30 P.M.

Copy code Copy code
sFilter = "[LastModificationTime] > '" & Format("1/15/99 3:30pm", "ddddd h:nn AMPM") & "'"

Boolean Operators

Boolean operators, TRUE/FALSE, YES/NO, ON/OFF, and so on, should not be converted to a string. For example, to determine whether journaling is enabled for contacts, you can use this filter:

Copy code Copy code
sFilter = "[Journal] = True"
Note Note

If you use quotation marks as delimiters with Boolean fields, then an empty string will find items whose fields are False and all non-empty strings will find items whose fields are True.

Keywords (or Categories)

The Categories field is of type keywords, which is designed to hold multiple values. When accessing it programmatically, the Categories field behaves like a Text field, and the string must match exactly. Values in the text string are separated by a comma and a space. This typically means that you cannot use the Find and Restrict methods on a keywords field if it contains more than one value. For example, if you have one contact in the Business category and one contact in the Business and Social categories, you cannot easily use the Find and Restrict methods to retrieve all items that are in the Business category. Instead, you can loop through all contacts in the folder and use the Instr function to test whether the string "Business" is contained within the entire keywords field.

Note Note

A possible exception is if you limit the Categories field to two, or a low number of values. Then you can use the Find and Restrict methods with the OR logical operator to retrieve all Business contacts. For example (in pseudocode): "Business" OR "Business, Personal" OR "Personal, Business." Category strings are not case sensitive.

Integer

You can search for Integer fields with, or without quotation marks as delimiters. The following filters will find contacts that were created by using Outlook 2000:

Copy code Copy code
sFilter = "[OutlookInternalVersion] = 92711" sFilter = "[OutlookInternalVersion] = '92711'"

Using Variables as Part of the Filter

As the Restrict method example illustrates, you can use values from variables as part of the filter. The following Microsoft Visual Basic Scripting Edition (VBScript) code sample illustrates syntax that uses variables as part of the filter.

Copy code Copy code
sFullName = "Dan Wilson"
' This approach uses Chr(34) to delimit the value.
sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)
' This approach uses double quotation marks to delimit the value. sFilter = "[FullName] = """ & sFullName & """"

Using Logical Operators as Part of the Filter

Logical operators that are allowed are AND, OR, and NOT. The following are variations of the clause for the Restrict method so you can specify multiple criteria.

OR: The following code returns all contact items that have either Business or Personal as their category.

Copy code Copy code
sFilter = "[Categories] = 'Personal' Or [Categories] = 'Business'"

AND: The following code retrieves all personal contacts who work at Microsoft.

Copy code Copy code
sFilter = "[Categories] = 'Personal' And [CompanyName] = 'Microsoft'"

NOT: The following code retrieves all personal contacts who don't work at Microsoft.

Copy code Copy code
sFilter = "[Categories] = 'Personal' And Not([CompanyName] = 'Microsoft')"

Additional Notes

If you are trying to use the Find or Restrict methods with user-defined fields, the fields must be defined in the folder, otherwise an error will occur. There is no way to perform a "contains" operation. For example, you cannot use Find or Restrict to search for items that have a particular word in the Subject field. Instead, you can use the AdvancedSearch method, or you can loop through all of the items in the folder and use the InStr function to perform a search within a field. You can use the Restrict method to search for items that begin within a certain range of characters. For example, to search for all contacts with a last name beginning with the letter M, use this filter:

Copy code Copy code
sFilter = "[LastName] > 'LZZZ' And [LastName] < 'N'"

Example

This Visual Basic for Applications (VBA) example uses the Restrict method to get all Inbox items of Business category and moves them to the Business folder. To run this example, create or make sure a subfolder called 'Business' exists under Inbox.

VBA Copy code Copy code
Sub MoveItems()
    Dim myNamespace As Outlook.NameSpace
    Dim myFolder As Outlook.Folder
    Dim myItems As Outlook.Items
    Dim myRestrictItems As Outlook.Items
    Dim myItem As Outlook.MailItem

    Set myNamespace = Application.GetNamespace("MAPI")
    Set myFolder = _
        myNamespace.GetDefaultFolder(olFolderInbox)
    Set myItems = myFolder.Items
    Set myRestrictItems = myItems.Restrict("[Categories] = 'Business'")
    For i =  myRestrictItems.Count To 1 Step -1
        myRestrictItems(i).Move myFolder.Folders("Business")
    Next
End Sub

This Visual Basic for Applications example uses the Restrict method to apply a filter to contact items based on the item's LastModificationTime property.

VBA Copy code Copy code
Public Sub ContactDateCheck()
    Dim myNamespace As Outlook.NameSpace
    Dim myContacts As Outlook.Items
    Dim myItems As Outlook.Items
    Dim myItem As Object

    Set myNamespace = Application.GetNamespace("MAPI")
    Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items
    Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")
    For Each myItem In myItems
        If (myItem.Class = olContact) Then
            MsgBox myItem.FullName & ": " & myItem.LastModificationTime
        End If
    Next
End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()
    Dim myNamespace As Outlook.NameSpace
    Dim myContacts As Outlook.Items
    Dim myItem As Object
    Dim DateStart As Date
    Dim DateToCheck As String
    Dim myRestrictItems As Outlook.Items

    Set myNameSpace = Application.GetNamespace("MAPI")
    Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items
    DateStart = #01/1/2003#
    DateToCheck = "[LastModificationTime] >= """ & DateStart & """"
    Set myRestrictItems = myContacts.Restrict(DateToCheck)
    For Each myItem In myRestrictItems
        If (myItem.Class = olContact) Then
            MsgBox myItem.FullName & ": " & myItem.LastModificationTime
        End If
    Next
End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.SetColumns Method (Outlook)

 Copy code hover
[image]

Items.SetColumns Method (Outlook)
See also Send feedback

Caches certain properties for extremely fast access to those particular properties of each item in an Items collection.

Syntax

expression .SetColumns(Columns)

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Columns | Required | String | A string that contains the names of the properties to cache. The property names are delimited by commas in this string.

Remarks

The SetColumns method is useful for iterating through an Items collection. If you don't use this method, Microsoft Outlook must open each item to access the property. With the SetColumns method, Outlook only checks the properties that you have cached, and provides fast, read-only access to these properties.

After applying the SetColumns method on specific properties of the collection, you cannot read other properties of that collection; properties which are not cached are returned empty. You cannot write to any of the properties of that collection either. Alternatively, if you require read-write, fast access to a set of items, use the Table object.

SetColumns cannot be used, and will cause an error, with any property that returns an object. It cannot be used with the following properties:

AutoResolvedWinner | InternetCodePage
Body | MeetingWorkspaceURL
BodyFormat | MemberCount
Categories | ReceivedByEntryID
Children | ReceivedOnBehalfOfEntryID
Class | RecurrenceState
Companies | ReplyRecipients
DLName | ResponseState
DownloadState | Saved
EntryID | Sent
HTMLBody | Submitted
IsConflict | VotingOptions

The ConversationIndex property cannot be cached using the SetColumns method. However, this property will not result in an error like the other properties listed above.

Example

The following Visual Basic for Applications (VBA) example uses the Items collection to get the items in default Tasks folder, caches the Subject and DueDate properties and then displays the subject and due dates each in turn.

VBA Copy code Copy code
Sub SortByDueDate()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItem As Object

 Dim myItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderTasks)

 Set myItems = myFolder.Items

 myItems.SetColumns ("Subject, DueDate")

 For Each myItem In myItems

 MsgBox myItem.Subject & " " & myItem.DueDate

 Next myItem

End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.Sort Method (Outlook)

 Copy code hover
[image]

Items.Sort Method (Outlook)
See also Send feedback

Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Syntax

expression .Sort(Property, Descending)

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Property | Required | String | The name of the property by which to sort, which may be enclosed in brackets, for example, "[CompanyName]". User-defined properties that contain spaces must be enclosed in brackets. May not be a user-defined property of type keywords, and may not be a multi-valued property, such as a category. For user-defined properties, the property must exist in the UserDefinedProperties collection for Items.Parent, which represents the Folder object that contains the items.
Descending | Optional | Variant | True to sort in descending order. The default value is False (ascending).

Remarks

Sort only affects the order of items in a collection. It does not affect the order of items in an explorer view.

Sort cannot be used and will cause an error if the Property paramater is one of the following properties:

Categories | LastFirstSpaceOnly
Children | LastFirstSpaceOnlyCompany
Class | MemberCount
CompanyLastFirstNoSpace | NetMeetingAlias
CompanyLastFirstSpaceOnly | RecurrenceState
DLName | ResponseState
LastFirstAndSuffix | Saved
LastFirstNoSpace | Sent
LastFirstNoSpaceCompany |

Example

The following Visual Basic for Applications (VBA) example uses the Sort method to sort the Items collection for the default Tasks folder by the "DueDate" property and displays the due dates each in turn.

VBA Copy code Copy code
Sub SortByDueDate()
 Dim myNameSpace As Outlook.NameSpace
 Dim myFolder As Outlook.Folder
 Dim myItem As Outlook.TaskItem
 Dim myItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(olFolderTasks)
 Set myItems = myFolder.Items
 myItems.Sort "[DueDate]", False
 For Each myItem In myItems
 MsgBox myItem.Subject & "-- " & myItem.DueDate
 Next myItem
End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items Events (Outlook)

 Copy code hover
[image]

Items Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
ItemAdd | Occurs when one or more items are added to the specified collection. This event does not run when a large number of items are added to the folder at once. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).
ItemChange | Occurs when an item in the specified collection is changed. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).
ItemRemove | Occurs when an item is deleted from the specified collection.


Items.ItemAdd Event (Outlook)

 Copy code hover
[image]

Items.ItemAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when one or more items are added to the specified collection. This event does not run when a large number of items are added to the folder at once. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Syntax

expression .ItemAdd(Item)

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item that was added.

Example

In this Visual Basic for Applications (VBA) example, when a new contact is added to the Contacts folder, the contact item is attached to an e-mail message and sent to a distribution list named "Sales Team". The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts).Items

End Sub

Private Sub myOlItems_ItemAdd(ByVal Item As Object)

 Dim myOlMItem As Outlook.MailItem

 Dim myOlAtts As Outlook.Attachments

 Set myOlMItem = myOlApp.CreateItem(olMailItem)

 myOlMItem.Save

 Set myOlAtts = myOlMItem.Attachments

 ' Add new contact to attachments in mail message

 myOlAtts.Add Item, olByValue

 myOlMItem.To = "Sales Team"

 myOlMItem.Subject = "New contact"

 myOlMItem.Send

End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.ItemChange Event (Outlook)

 Copy code hover
[image]

Items.ItemChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an item in the specified collection is changed. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Syntax

expression .ItemChange(Item)

expression A variable that represents an Items object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item that was changed.

Example

This example uses the Start property of the AppointmentItem object to determine if the appointment starts after normal business hours. If it does, and if the Sensitivity property of the AppointmentItem object is not already set to olPrivate, the example offers to mark the appointment as private.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderCalendar).Items

End Sub

Private Sub myOlItems_ItemChange(ByVal Item As Object)

Dim prompt As String

 If VBA.Format(Item.Start, "h") >= "17" And Item.Sensitivity <> olPrivate Then

 prompt = "Appointment occurs after hours. Mark it private?"

 If MsgBox(prompt, vbYesNo + vbQuestion) = vbYes Then

 Item.Sensitivity = olPrivate

 Item.Display

 End If

 End If

End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


Items.ItemRemove Event (Outlook)

 Copy code hover
[image]

Items.ItemRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an item is deleted from the specified collection.

Syntax

expression .ItemRemove

expression A variable that represents an Items object.

Remarks

This event does not run when the last item in a Personal Folders file (.pst) is deleted, or if 16 or more items are deleted at once from a PST file, Microsoft Exchange mailbox, or an Exchange public folder. This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example optionally sends a notification message to a workgroup when the user removes a contact from the default Contacts folder. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts).Items

End Sub

Private Sub myOlItems_ItemRemove()

 Dim myOlMItem As Outlook.MailItem

 If MsgBox("Do you want to notify the Sales Team?", vbYesNo + vbQuestion) = vbYes Then

 Set myOlMItem = Application.CreateItem(olMailItem)

 myOlMItem.To = "Sales Team"

 myOlMItem.Subject = "Remove Contact"

 myOlMItem.Body = "Remove the following contact from your list:"

 myOlMItem.Display

 End If

End Sub

See also

Concepts

Items Object

Other resources

Items Object Members


JournalItem Object (Outlook)

 Copy code hover
[image]

JournalItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a journal entry in a Journal folder.

Remarks

A journal entry represents a record of all Outlook-moderated transactions for any given period.

Use the CreateItem method to create a JournalItem object that represents a new journal entry.

Use Items(index), where index is the index number of a journal entry or a value used to match the default property of a journal entry, to return a single JournalItem object from a Journal folder.

Example

The following Visual Basic for Applications (VBA) example returns a new journal entry.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olJournalItem)

See also

Concepts

Outlook Object Model Reference

Other resources

JournalItem Object Members


JournalItem Members (Outlook)

 Copy code hover
[image]

JournalItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a journal entry in a Journal folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings. The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
StartTimer | Starts the timer on the journal entry. This method allows programmatic control of the timer function.
StopTimer | Stops the timer on the journal entry. This method allows programmatic control of the timer function.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Returns the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ContactNames | Returns or sets a String representing the contact names associated with the Outlook item. Read/write.
ConversationID | Returns a String that uniquely identifies a Conversation object that the JournalItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DocPosted | Returns a Boolean value that indicates whether the journalized item was posted as part of the journalized session. Read/write.
DocPrinted | Returns a Boolean value that indicates wheter the journalized item was printed as part of the journalized session. Read/write.
DocRouted | Returns a Boolean value that indicates whether the journalized item was routed as part of the journalized session. Read/write.
DocSaved | Returns a Boolean value that indicates whether the journalized item was saved as part of the journalized session. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Duration | Returns or sets a Long indicating the duration (in minutes) of the JournalItem Read/write.
End | Returns or sets a Date indicating the end date and time of a Journal entry. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent JournalItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Start | Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Type | Returns or sets a String representing a free-form field, usually containing the display name of the journalizing application (for example, "MSWord".) Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


JournalItem Properties (Outlook)

 Copy code hover
[image]

JournalItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Returns the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ContactNames | Returns or sets a String representing the contact names associated with the Outlook item. Read/write.
ConversationID | Returns a String that uniquely identifies a Conversation object that the JournalItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DocPosted | Returns a Boolean value that indicates whether the journalized item was posted as part of the journalized session. Read/write.
DocPrinted | Returns a Boolean value that indicates wheter the journalized item was printed as part of the journalized session. Read/write.
DocRouted | Returns a Boolean value that indicates whether the journalized item was routed as part of the journalized session. Read/write.
DocSaved | Returns a Boolean value that indicates whether the journalized item was saved as part of the journalized session. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
Duration | Returns or sets a Long indicating the duration (in minutes) of the JournalItem Read/write.
End | Returns or sets a Date indicating the end date and time of a Journal entry. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent JournalItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Start | Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Type | Returns or sets a String representing a free-form field, usually containing the display name of the journalizing application (for example, "MSWord".) Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


JournalItem.Actions Property (Outlook)

 Copy code hover
[image]

JournalItem.Actions Property (Outlook)
See also Send feedback

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Application Property (Outlook)

 Copy code hover
[image]

JournalItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Attachments Property (Outlook)

 Copy code hover
[image]

JournalItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

JournalItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a JournalItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its JournalItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

JournalItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a JournalItem object.

Remarks

This is a free-form text field.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Body Property (Outlook)

 Copy code hover
[image]

JournalItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Categories Property (Outlook)

 Copy code hover
[image]

JournalItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a JournalItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Class Property (Outlook)

 Copy code hover
[image]

JournalItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Companies Property (Outlook)

 Copy code hover
[image]

JournalItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a JournalItem object.

Remarks

This is a free-form text field.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Conflicts Property (Outlook)

 Copy code hover
[image]

JournalItem.Conflicts Property (Outlook)
See also Send feedback

Returns the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ContactNames Property (Outlook)

 Copy code hover
[image]

JournalItem.ContactNames Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the contact names associated with the Outlook item. Read/write.

Syntax

expression .ContactNames

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ConversationID Property (Outlook)

 Copy code hover
[image]

JournalItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the JournalItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a JournalItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the JournalItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

JournalItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

JournalItem.ConversationTopic Property (Outlook)
See also Send feedback

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.CreationTime Property (Outlook)

 Copy code hover
[image]

JournalItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.DocPosted Property (Outlook)

 Copy code hover
[image]

JournalItem.DocPosted Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the journalized item was posted as part of the journalized session. Read/write.

Syntax

expression .DocPosted

expression A variable that represents a JournalItem object.

Remarks

If this property returns True, then the journalized item was posted as part of the journalized session.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.DocPrinted Property (Outlook)

 Copy code hover
[image]

JournalItem.DocPrinted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates wheter the journalized item was printed as part of the journalized session. Read/write.

Syntax

expression .DocPrinted

expression A variable that represents a JournalItem object.

Remarks

If this property returns True, then the journalized item was printed as part of the journalized session.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.DocRouted Property (Outlook)

 Copy code hover
[image]

JournalItem.DocRouted Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the journalized item was routed as part of the journalized session. Read/write.

Syntax

expression .DocRouted

expression A variable that represents a JournalItem object.

Remarks

If this property returns True, then the journalized item was routed as part of the journalized session.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.DocSaved Property (Outlook)

 Copy code hover
[image]

JournalItem.DocSaved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the journalized item was saved as part of the journalized session. Read/write.

Syntax

expression .DocSaved

expression A variable that represents a JournalItem object.

Remarks

If this property returns True, then the journalized item was saved as part of the journalized session.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.DownloadState Property (Outlook)

 Copy code hover
[image]

JournalItem.DownloadState Property (Outlook)
See also Send feedback

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a JournalItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Duration Property (Outlook)

 Copy code hover
[image]

JournalItem.Duration Property (Outlook)
See also Send feedback

Returns or sets a Long indicating the duration (in minutes) of the JournalItem Read/write.

Syntax

expression .Duration

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.End Property (Outlook)

 Copy code hover
[image]

JournalItem.End Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the end date and time of a Journal entry. Read/write.

Syntax

expression .End

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.EntryID Property (Outlook)

 Copy code hover
[image]

JournalItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search MSDN for PidTagEntryId.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.FormDescription Property (Outlook)

 Copy code hover
[image]

JournalItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.GetInspector Property (Outlook)

 Copy code hover
[image]

JournalItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a JournalItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Importance Property (Outlook)

 Copy code hover
[image]

JournalItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.IsConflict Property (Outlook)

 Copy code hover
[image]

JournalItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a JournalItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

JournalItem.ItemProperties Property (Outlook)
See also Send feedback

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a JournalItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

JournalItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

JournalItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a JournalItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.MessageClass Property (Outlook)

 Copy code hover
[image]

JournalItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

JournalItem Object
Item Types and Message Classes

Other resources

JournalItem Object Members


JournalItem.Mileage Property (Outlook)

 Copy code hover
[image]

JournalItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a JournalItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.NoAging Property (Outlook)

 Copy code hover
[image]

JournalItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

JournalItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

JournalItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Parent Property (Outlook)

 Copy code hover
[image]

JournalItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

JournalItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent JournalItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Recipients Property (Outlook)

 Copy code hover
[image]

JournalItem.Recipients Property (Outlook)
See also Send feedback

Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.

Syntax

expression .Recipients

expression A variable that represents a JournalItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Saved Property (Outlook)

 Copy code hover
[image]

JournalItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

JournalItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Session Property (Outlook)

 Copy code hover
[image]

JournalItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a JournalItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Size Property (Outlook)

 Copy code hover
[image]

JournalItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Start Property (Outlook)

 Copy code hover
[image]

JournalItem.Start Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the starting date and time for the Outlook item. Read/write.

Syntax

expression .Start

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Subject Property (Outlook)

 Copy code hover
[image]

JournalItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a JournalItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Type Property (Outlook)

 Copy code hover
[image]

JournalItem.Type Property (Outlook)
See also Send feedback

Returns or sets a String representing a free-form field, usually containing the display name of the journalizing application (for example, "MSWord".) Read/write.

Syntax

expression .Type

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.UnRead Property (Outlook)

 Copy code hover
[image]

JournalItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.UserProperties Property (Outlook)

 Copy code hover
[image]

JournalItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem Methods (Outlook)

 Copy code hover
[image]

JournalItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings. The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
StartTimer | Starts the timer on the journal entry. This method allows programmatic control of the timer function.
StopTimer | Stops the timer on the journal entry. This method allows programmatic control of the timer function.


JournalItem.Close Method (Outlook)

 Copy code hover
[image]

JournalItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Copy Method (Outlook)

 Copy code hover
[image]

JournalItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a JournalItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Delete Method (Outlook)

 Copy code hover
[image]

JournalItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a JournalItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

JournalItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

JournalItemMembers


JournalItem.Display Method (Outlook)

 Copy code hover
[image]

JournalItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Forward Method (Outlook)

 Copy code hover
[image]

JournalItem.Forward Method (Outlook)
See also Send feedback

Published: July 16, 2012

Executes the Forward action for an item and returns the resulting copy as a MailItem object.

Syntax

expression .Forward

expression A variable that represents a JournalItem object.

Return Value

A MailItem object that represents the new mail item.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.GetConversation Method (Outlook)

 Copy code hover
[image]

JournalItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a JournalItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Move Method (Outlook)

 Copy code hover
[image]

JournalItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.PrintOut Method (Outlook)

 Copy code hover
[image]

JournalItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings. The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Reply Method (Outlook)

 Copy code hover
[image]

JournalItem.Reply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a reply, pre-addressed to the original sender, from the original message.

Syntax

expression .Reply

expression A variable that represents a JournalItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ReplyAll Method (Outlook)

 Copy code hover
[image]

JournalItem.ReplyAll Method (Outlook)
See also Send feedback

Creates a reply to all original recipients from the original message.

Syntax

expression .ReplyAll

expression A variable that represents a JournalItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Save Method (Outlook)

 Copy code hover
[image]

JournalItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a JournalItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.SaveAs Method (Outlook)

 Copy code hover
[image]

JournalItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.JournalItem

 Set MyItem = Application.CreateItem(olJournalItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

JournalItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a JournalItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new journal item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub JournalItem()

 'Creates a journal item to access ShowCategoriesDialog

 Dim olmyJournalItem As Outlook.JournalItem

 'Create journal item

 Set olmyJournalItem = Application.CreateItem(olJournalItem)

 olmyJournalItem.Body = "Sales figure notes."

 olmyJournalItem.Subject = "Sales Reports"

 'Display the item

 olmyJournalItem.Display

 'Display the Show categories dialog

 olmyJournalItem.ShowCategoriesDialog

End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.StartTimer Method (Outlook)

 Copy code hover
[image]

JournalItem.StartTimer Method (Outlook)
See also Send feedback

Starts the timer on the journal entry. This method allows programmatic control of the timer function.

Syntax

expression .StartTimer

expression A variable that represents a JournalItem object.

Remarks

The Duration, End and Start properties are automatically updated when the timer is stopped.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.StopTimer Method (Outlook)

 Copy code hover
[image]

JournalItem.StopTimer Method (Outlook)
See also Send feedback

Published: July 16, 2012

Stops the timer on the journal entry. This method allows programmatic control of the timer function.

Syntax

expression .StopTimer

expression A variable that represents a JournalItem object.

Remarks

The Duration, End and Start properties are automatically updated when the timer is stopped.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem Events (Outlook)

 Copy code hover
[image]

JournalItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


JournalItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

JournalItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a JournalItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

JournalItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

JournalItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

JournalItem.AttachmentRemove Event (Outlook)
See also Send feedback

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel, )

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the JournalItem to be saved.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

JournalItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a JournalItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Close Event (Outlook)

 Copy code hover
[image]

JournalItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.CustomAction Event (Outlook)

 Copy code hover
[image]

JournalItem.CustomAction Event (Outlook)
See also Send feedback

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

JournalItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Forward Event (Outlook)

 Copy code hover
[image]

JournalItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Open Event (Outlook)

 Copy code hover
[image]

JournalItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

JournalItem.PropertyChange Event (Outlook)
See also Send feedback

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Read Event (Outlook)

 Copy code hover
[image]

JournalItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a JournalItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

JournalItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Reply Event (Outlook)

 Copy code hover
[image]

JournalItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

JournalItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Send Event (Outlook)

 Copy code hover
[image]

JournalItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Unload Event (Outlook)

 Copy code hover
[image]

JournalItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a JournalItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalItem.Write Event (Outlook)

 Copy code hover
[image]

JournalItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a JournalItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

JournalItem Object

Other resources

JournalItem Object Members


JournalModule Object (Outlook)

 Copy code hover
[image]

JournalModule Object (Outlook)
See also Send feedback

Represents the Journal navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The JournalModule object, derived from the NavigationModule object, provides access to the navigation groups contained in the Journal navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the Modules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the module type. If the NavigationModuleType property is set to olModuleJournal, you can then cast the NavigationModule object reference as a JournalModule object to access the NavigationGroups property for that navigation module.

You can use the Visible property to determine if the navigation module is visible and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Journal navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

JournalModule Object Members


JournalModule Members (Outlook)

 Copy code hover
[image]

JournalModule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Journal navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the JournalModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the JournalModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the JournalModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the JournalModule object is displayed in the Navigation Pane. Read/write.


JournalModule Properties (Outlook)

 Copy code hover
[image]

JournalModule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the JournalModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the JournalModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the JournalModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the JournalModule object is displayed in the Navigation Pane. Read/write.


JournalModule.Application Property (Outlook)

 Copy code hover
[image]

JournalModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Class Property (Outlook)

 Copy code hover
[image]

JournalModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a JournalModule object.

Remarks

This property returns olJournalModule for the JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Name Property (Outlook)

 Copy code hover
[image]

JournalModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the JournalModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

JournalModule.NavigationGroups Property (Outlook)
See also Send feedback

Returns a NavigationGroups object that contains the set of navigation groups associated with the JournalModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

JournalModule.NavigationModuleType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a JournalModule object.

Remarks

This property returns olModuleJournal for the JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Parent Property (Outlook)

 Copy code hover
[image]

JournalModule.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Position Property (Outlook)

 Copy code hover
[image]

JournalModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the JournalModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a JournalModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a given JournalModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified JournalModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified JournalModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Session Property (Outlook)

 Copy code hover
[image]

JournalModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a JournalModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


JournalModule.Visible Property (Outlook)

 Copy code hover
[image]

JournalModule.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the JournalModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a JournalModule object.

See also

Concepts

JournalModule Object

Other resources

JournalModule Object Members


MailItem Object (Outlook)

 Copy code hover
[image]

MailItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a mail message.

Remarks

Use the CreateItem method to create a MailItem object that represents a new mail message.

Use the Folder.Items property to obtain an Items collection representing the mail items in a folder, and the Items.Item (index) method, where index is the index number of a mail message or a value used to match the default property of a message, to return a single MailItem object from the specified folder.

Example

The following Visual Basic for Applications (VBA) example creates and displays a new mail message.

VBA Copy code Copy code
Sub CreateMail()

 Dim myItem As Object

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Mail to myself"

 myItem.Display

End Sub

The following VBA example sets the current folder as the Inbox and displays the second mail message in the folder. In general, the order of mail messages in a folder is not guaranteed to be in a particular order.

VBA Copy code Copy code
Sub DisplayMail()

 Dim myItem As Object

 Dim myFolder As Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderInbox)

 myFolder.Display

 Set myItem = myFolder.Items(2)

 myItem.Display

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem Members (Outlook)

 Copy code hover
[image]

MailItem Members (Outlook)
Send feedback

Represents a mail message.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
AddBusinessCard | Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the MailItem object.
ClearConversationIndex | Clears the index of the conversation thread for the mail message.
ClearTaskFlag | Clears the MailItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a MailItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the e-mail message.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
AlternateRecipientAllowed | Returns a Boolean value that indicates whether the mail message can be forwarded. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoForwarded | A Boolean value that returns True if the item was automatically forwarded. Read/write.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BCC | Returns a String representing the display list of blind carbon copy (BCC) names for a MailItem. Read/write.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
CC | Returns a String representing the display list of carbon copy (CC) names for a MailItem. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the MailItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FlagRequest | Returns or sets a String that indicates the requested action for a mail item. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified item. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the MailItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Permission | Sets or returns an OlPermission constant that determines what permissions to grant to the recipients of the e-mail item. Read/write.
PermissionService | Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a message protected by Information Rights Management (IRM). Read/write.
PermissionTemplateGuid | Returns or sets a String value that represents the GUID of the template file to apply to the MailItem in order to specify Information Rights Management (IRM) permissions. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MailItem object. Read-only.
ReadReceiptRequested | Returns a Boolean value that indicates True if a read receipt has been requested by the sender.
ReceivedByEntryID | Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the mail message. Read-only.
ReceivedByName | Returns a String representing the display name of the true recipient for the mail message. Read-only.
ReceivedOnBehalfOfEntryID | Returns a String representing the EntryID of the user delegated to represent the recipient for the mail message. Read-only.
ReceivedOnBehalfOfName | Returns a String representing the display name of the user delegated to represent the recipient for the mail message. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the item was received. Read-only.
RecipientReassignmentProhibited | Returns a Boolean that indicates True if the recipient cannot forward the mail message. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RemoteStatus | Returns or sets an OlRemoteStatus constant specifying the remote status of the mail message. Read/write.
ReplyRecipientNames | Returns a semicolon-delimited String list of reply recipients for the mail message. Read-only.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the MailItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.
Sender | Returns or sets an AddressEntry object that corresponds to the user of the account from which the MailItem is sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the MailItem is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Sent | Returns a Boolean value that indicates if a message has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
SentOnBehalfOfName | Returns a String indicating the display name for the intended sender of the mail message. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Submitted | Returns a Boolean value that is True if the item has been submitted. Read-only.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this MailItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this MailItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this MailItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the MailItem object. Read/write.
To | Returns or sets a semicolon-delimited String list of display names for the To recipients for the Outlook item. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the MailItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.
VotingOptions | Returns or sets a String specifying a delimited string containing the voting options for the mail message. Read/write.
VotingResponse | Returns or sets a String specifying the voting response for the mail message. Read/write.


MailItem Properties (Outlook)

 Copy code hover
[image]

MailItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
AlternateRecipientAllowed | Returns a Boolean value that indicates whether the mail message can be forwarded. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoForwarded | A Boolean value that returns True if the item was automatically forwarded. Read/write.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BCC | Returns a String representing the display list of blind carbon copy (BCC) names for a MailItem. Read/write.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
CC | Returns a String representing the display list of carbon copy (CC) names for a MailItem. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the MailItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FlagRequest | Returns or sets a String that indicates the requested action for a mail item. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified item. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the MailItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Permission | Sets or returns an OlPermission constant that determines what permissions to grant to the recipients of the e-mail item. Read/write.
PermissionService | Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a message protected by Information Rights Management (IRM). Read/write.
PermissionTemplateGuid | Returns or sets a String value that represents the GUID of the template file to apply to the MailItem in order to specify Information Rights Management (IRM) permissions. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MailItem object. Read-only.
ReadReceiptRequested | Returns a Boolean value that indicates True if a read receipt has been requested by the sender.
ReceivedByEntryID | Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the mail message. Read-only.
ReceivedByName | Returns a String representing the display name of the true recipient for the mail message. Read-only.
ReceivedOnBehalfOfEntryID | Returns a String representing the EntryID of the user delegated to represent the recipient for the mail message. Read-only.
ReceivedOnBehalfOfName | Returns a String representing the display name of the user delegated to represent the recipient for the mail message. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the item was received. Read-only.
RecipientReassignmentProhibited | Returns a Boolean that indicates True if the recipient cannot forward the mail message. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RemoteStatus | Returns or sets an OlRemoteStatus constant specifying the remote status of the mail message. Read/write.
ReplyRecipientNames | Returns a semicolon-delimited String list of reply recipients for the mail message. Read-only.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the MailItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.
Sender | Returns or sets an AddressEntry object that corresponds to the user of the account from which the MailItem is sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the MailItem is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Sent | Returns a Boolean value that indicates if a message has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
SentOnBehalfOfName | Returns a String indicating the display name for the intended sender of the mail message. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Submitted | Returns a Boolean value that is True if the item has been submitted. Read-only.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this MailItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this MailItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this MailItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the MailItem object. Read/write.
To | Returns or sets a semicolon-delimited String list of display names for the To recipients for the Outlook item. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the MailItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.
VotingOptions | Returns or sets a String specifying a delimited string containing the voting options for the mail message. Read/write.
VotingResponse | Returns or sets a String specifying the voting response for the mail message. Read/write.


MailItem.Actions Property (Outlook)

 Copy code hover
[image]

MailItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications (VBA) example creates a new mail item and uses the Actions.Add method to add an Action to it. Then it sends the mail item to the current user. The mail item received will have the Agree action in addition to the standard actions such as Reply and Reply All.

VBA Copy code Copy code
Sub AddAction()

 Dim myItem As Outlook.MailItem

 Dim myAction As Outlook.Action

 Set myItem = Application.CreateItem(olMailItem)

 Set myAction = myItem.Actions.Add

 myAction.Name = "Agree"

 myItem.To = Application.GetNamespace("MAPI").CurrentUser

 myItem.Send

End Sub

The following Visual Basic for Applications example creates a new mail item and uses the Actions.Add method to add an Action called Link Original to it. Executing this action will insert a link to the original mail item.

VBA Copy code Copy code
Sub AddAction2()

 Dim myItem As Outlook.MailItem

 Dim myAction As Outlook.Action

 Set myItem = Application.CreateItem(olMailItem)

 Set myAction = myItem.Actions.Add

 myAction.Name = "Link Original"

 myAction.ShowOn = olMenuAndToolbar

 myAction.ReplyStyle = olLinkOriginalItem

 myItem.To = "Dan Wilson"

 myItem.Send

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AlternateRecipientAllowed Property (Outlook)

 Copy code hover
[image]

MailItem.AlternateRecipientAllowed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the mail message can be forwarded. Read/write.

Syntax

expression .AlternateRecipientAllowed

expression A variable that represents a MailItem object.

Remarks

If this property returns True, then the mail message can be forwarded.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Application Property (Outlook)

 Copy code hover
[image]

MailItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications (VBA) example uses the Application property to access Outlook, creates a new MailItem and displays the version of Outlook used to create the item.

VBA Copy code Copy code
Sub CreateMailItem()

 Dim myItem As Outlook.MailItem

 Set myItem = Application.CreateItem(olMailItem)

 MsgBox myItem.Application.Version

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Attachments Property (Outlook)

 Copy code hover
[image]

MailItem.Attachments Property (Outlook)
See also Send feedback

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications (VBA) example uses the Attachments.Remove method to remove all attachments from a forwarded mail message before sending it on to 'Dan Wilson'. To run this example, replace 'Dan Wilson' with a valid recipient's name and keep an item with attachments open in an inspector window.

VBA Copy code Copy code
Sub RemoveAttachmentBeforeForwarding()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Dim myattachments As Outlook.Attachments

 Set myinspector = Application.ActiveInspector

 If Not TypeName(myinspector) = "Nothing" Then

 Set myItem = myinspector.CurrentItem.Forward

 Set myattachments = myItem.Attachments

 While myattachments.Count > 0

 myattachments.Remove 1

 Wend

 myItem.Display

 myItem.Recipients.Add "Dan Wilson"

 myItem.Send

 Else

 MsgBox "There is no active inspector."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AutoForwarded Property (Outlook)

 Copy code hover
[image]

MailItem.AutoForwarded Property (Outlook)
See also Send feedback

Published: July 16, 2012

A Boolean value that returns True if the item was automatically forwarded. Read/write.

Syntax

expression .AutoForwarded

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

MailItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a MailItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its MailItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

Example

The following Microsoft Visual Basic for Applications (VBA) example used the AutoResolvedWinner property to determine if an item is a winner or loser in an automatic conflict resolution. To run this example, make sure an e-mail item is open in the active window.

VBA Copy code Copy code
Sub ConflictStatus()

 Dim mail As Outlook.MailItem

 Set mail = Application.ActiveInspector.CurrentItem

 If mail.Conflicts.Count > 0 Then

 If mail.AutoResolvedWinner = True Then

 MsgBox "This item is a winner in an automatic conflict resolution."

 Else

 MsgBox "This item is a loser in an automatic conflict resolution."

 End If

 Else

 MsgBox "This item is not in conflict with any item."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BCC Property (Outlook)

 Copy code hover
[image]

MailItem.BCC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display list of blind carbon copy (BCC) names for a MailItem. Read/write.

Syntax

expression .BCC

expression A variable that represents a MailItem object.

Remarks

This property contains the display names only. The Recipients collection should be used to modify the BCC recipients.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

MailItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a MailItem object.

Remarks

This is a free-form text field.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Body Property (Outlook)

 Copy code hover
[image]

MailItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a MailItem object.

Remarks

The MailItem.BodyFormat property allows you to programmatically change the editor that is used for the body of an item.

See also

Concepts

MailItem Object
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem.BodyFormat Property (Outlook)

 Copy code hover
[image]

MailItem.BodyFormat Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.

Syntax

expression .BodyFormat

expression A variable that represents a MailItem object.

Remarks

The body text format determines the standard used to display the text of the message. Microsoft Outlook provides three body text format options: Plain Text, Rich Text (RTF), and HTML.

All text formatting will be lost when the BodyFormat property is switched from RTF to HTML and vice-versa.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new MailItem object and sets the BodyFormat property to olFormatHTML. The body text of the e-mail item will now appear in HTML format.

VBA Copy code Copy code
Sub CreateHTMLMail()

 'Creates a new e-mail item and modifies its properties.

 Dim objMail As MailItem

 'Create mail item

 Set objMail = Application.CreateItem(olMailItem)

 With objMail

 'Set body format to HTML

 .BodyFormat = olFormatHTML

 .HTMLBody = "<HTML><H2>The body of this message will appear in HTML.</H2><BODY>Type the message text here. </BODY></HTML>"

 .Display

 End With

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Categories Property (Outlook)

 Copy code hover
[image]

MailItem.Categories Property (Outlook)
See also Send feedback

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a MailItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.CC Property (Outlook)

 Copy code hover
[image]

MailItem.CC Property (Outlook)
See also Send feedback

Returns a String representing the display list of carbon copy (CC) names for a MailItem. Read/write.

Syntax

expression .CC

expression A variable that represents a MailItem object.

Remarks

This property contains the display names only. The Recipients collection should be used to modify the CC recipients.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Class Property (Outlook)

 Copy code hover
[image]

MailItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Companies Property (Outlook)

 Copy code hover
[image]

MailItem.Companies Property (Outlook)
See also Send feedback

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a MailItem object.

Remarks

This is a free-form text field.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Conflicts Property (Outlook)

 Copy code hover
[image]

MailItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a MailItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example uses the Count property of the Conflicts object to determine if the item is involved in any conflict. To run this example, make sure a mail item is open in the active window.

VBA Copy code Copy code
Sub CheckConflicts()

 Dim myItem As Outlook.MailItem

 Dim myConflicts As Outlook.Conflicts

 Set myItem = Application.ActiveInspector.CurrentItem

 Set myConflicts = myItem.Conflicts

 If (myConflicts.Count > 0) Then

 MsgBox ("This item is involved in a conflict.")

 Else

 MsgBox ("This item is not involved in any conflicts.")

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ConversationID Property (Outlook)

 Copy code hover
[image]

MailItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the MailItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a MailItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the MailItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

MailItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

MailItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.CreationTime Property (Outlook)

 Copy code hover
[image]

MailItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.DeferredDeliveryTime Property (Outlook)

 Copy code hover
[image]

MailItem.DeferredDeliveryTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.

Syntax

expression .DeferredDeliveryTime

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagDeferredDeliveryTime.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.DeleteAfterSubmit Property (Outlook)

 Copy code hover
[image]

MailItem.DeleteAfterSubmit Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.

Syntax

expression .DeleteAfterSubmit

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.DownloadState Property (Outlook)

 Copy code hover
[image]

MailItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a MailItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.EntryID Property (Outlook)

 Copy code hover
[image]

MailItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search MSDN for PidTagEntryId.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ExpiryTime Property (Outlook)

 Copy code hover
[image]

MailItem.ExpiryTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.

Syntax

expression .ExpiryTime

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications (VBA) example uses the MailItem.Send event and sends an item with an automatic expiration date.

VBA Copy code Copy code
Public WithEvents myItem As MailItem

Sub SendMyMail()

 Set myItem = Outlook.CreateItem(olMailItem)

 myItem.To = "Laura Jennings"

 myItem.Subject = "Data files information"

 myItem.Send

End Sub

Private Sub myItem_Send(Cancel As Boolean)

 myItem.ExpiryTime = #2/2/2003 4:00:00 PM#

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.FlagRequest Property (Outlook)

 Copy code hover
[image]

MailItem.FlagRequest Property (Outlook)
See also Send feedback

Returns or sets a String that indicates the requested action for a mail item. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FlagRequest

expression A variable that represents a MailItem object.

Remarks

By default, a mail item is not marked with any flag and the default value for this property is the empty string. You can set the value of FlagRequest either through the user interface or programmatically. When you mark a mail item with a flag through the user interface, the default value of FlagRequest is "Follow up".

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.FormDescription Property (Outlook)

 Copy code hover
[image]

MailItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.GetInspector Property (Outlook)

 Copy code hover
[image]

MailItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a MailItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

Example

This Visual Basic for Applications (VBA) example shows a function InsertBodyTextInWordEditor that creates a mail item, assigns it a title and adds text for the body. The function sets the Subject property to assign the title "Testing...". It then calls the Display method to open the mail item in an inspector. To insert text in a Word editor as the body of the mail item, the function uses the Document object and Range object in the Word object model. The function uses the item's GetInspector property to get the existing Inspector object, and then uses the Inspector.WordEditor property to obtain a Word.Document object for the item. Using the Word.Document object, the function accesses the Word.Range object and inserts text into the body of the item.

Since this example accesses the Word object model, you must first add a reference to the Microsoft Word Object Library to compile the example successfully.

VBA Copy code Copy code
Sub InsertBodyTextInWordEditor()
 Dim myItem As Outlook.MailItem
 Dim myInspector As Outlook.Inspector
 'You must add a reference to the Microsoft Word Object Library
 'before this sample will compile
 Dim wdDoc As Word.Document
 Dim wdRange As Word.Range

 On Error Resume Next
 Set myItem = Application.CreateItem(olMailItem)
 myItem.Subject = "Testing..."
 myItem.Display
 'GetInspector property returns Inspector
 Set myInspector = myItem.GetInspector
 'Obtain the Word.Document for the Inspector
 Set wdDoc = myInspector.WordEditor
 If Not (wdDoc Is Nothing) Then
 'Use the Range object to insert text
 Set wdRange = wdDoc.Range(0, wdDoc.Characters.Count)
 wdRange.InsertAfter ("Hello world!")
 End If
End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.HTMLBody Property (Outlook)

 Copy code hover
[image]

MailItem.HTMLBody Property (Outlook)
See also Send feedback

Returns or sets a String representing the HTML body of the specified item. Read/write.

Syntax

expression .HTMLBody

expression A variable that represents a MailItem object.

Remarks

The HTMLBody property should be an HTML syntax string.

Setting the HTMLBody property will always update the Body property immediately.

Example

The following Visual Basic for Applications (VBA) example creates a new MailItem object and sets the BodyFormat property to olFormatHTML. The body text of the e-mail item will now appear in HTML format.

VBA Copy code Copy code
Sub CreateHTMLMail()

 'Creates a new e-mail item and modifies its properties.

 Dim objMail As Outlook.MailItem

 'Create e-mail item

 Set objMail = Application.CreateItem(olMailItem)

 With objMail

 'Set body format to HTML

 .BodyFormat = olFormatHTML

 .HTMLBody = _

 "<HTML><BODY>Enter the message text here. </BODY></HTML>"

 .Display

 End With

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Importance Property (Outlook)

 Copy code hover
[image]

MailItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

Example

This Visual Basic for Applications (VBA) example checks if the item displayed in the topmost inspector is sent by 'Dan Wilson' with 'High' importance. If it is, then it displays a message box to the user. Before running this example, replace 'Dan Wilson' with a valid name in your address book.

VBA Copy code Copy code
Sub CheckSenderName

 Dim myItem As Outlook.MailItem

 Set myItem = Application.ActiveInspector.CurrentItem

 If myItem.Importance = 2 And _

 myItem.SenderName = "Dan Wilson" Then

 MsgBox "This message is sent by your manager with High importance."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.InternetCodepage Property (Outlook)

 Copy code hover
[image]

MailItem.InternetCodepage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that determines the Internet code page used by the item. Read/write.

Syntax

expression .InternetCodepage

expression A variable that represents a MailItem object.

Remarks

The Internet code page defines the text encoding scheme used by the item.

The following table lists the values that are supported by the InternetCodePage property.

Name | Character Set | Code Page
Arabic (ISO) | iso-8859-6 | 28596
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Baltic (Windows) | windows-1257 | 1257
Central European (ISO) | iso-8859-2 | 28592
Central European (Windows) | windows-1250 | 1250
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Simplified (HZ) | hz-gb-2312 | 52936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (ISO) | iso-8859-5 | 28595
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (KOI8-U) | koi8-u | 21866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Greek (Windows) | windows-1253 | 1253
Hebrew (ISO-Logical) | iso-8859-8-i | 38598
Hebrew (Windows) | windows-1255 | 1255
Japanese (EUC) | euc-jp | 51932
Japanese (JIS) | iso-2022-jp | 50220
Japanese (JIS-Allow 1 byte Kana) | csISO2022JP | 50221
Japanese (Shift-JIS) | iso-2022-jp | 932
Korean | ks_c_5601-1987 | 949
Korean (EUC) | euc-kr | 51949
Latin 3 (ISO) | iso-8859-3 | 28593
Latin 9 (ISO) | iso-8859-15 | 28605
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Turkish (Windows) | windows-1254 | 1254
Unicode (UTF-7) | utf-7 | 65000
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591
Western European (Windows) | Windows-1252 | 1252

The following table lists the code pages Microsoft recommends that you use for the best compatiblity with older e-mail systems.

Name | Character Set | Code Page
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Central European (ISO) | iso-8859-2 | 28592
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Hebrew (Windows) | windows-1255 | 1255
Japanese (JIS) | iso-2022-jp | 50220
Korean | ks_c_5601-1987 | 949
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the sender name of the current e-mail item if its Internet code page value is 1256. This value corresponds to the Internet code page value for Arabic text.

VBA Copy code Copy code
Sub FindArabicUser()

 'Tells if the sender of the current item used the Arabic codepage

 Dim objMail As Outlook.MailItem

 Const cstArabic As Long = 1256

 Set objMail = Application.ActiveInspector.CurrentItem

 If objMail.InternetCodePage = cstArabic Then

 MsgBox objMail.SenderName & " uses an Arabic code page."

 End If

 Set objMail = Nothing

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.IsConflict Property (Outlook)

 Copy code hover
[image]

MailItem.IsConflict Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a MailItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new mail item and attempts to send it. If the IsConflict property returns True, the item will not be sent.

VBA Copy code Copy code
Sub NewMail()

 'Creates and tries to send a new e-mail message.

 Dim objNewMail As Outlook.MailItem

 Set objNewMail = Application.CreateItem(olMailItem)

 objNewMail.Body = _

 "This e-mail message was created automatically on " & Now

 objNewMail.To = "Jeff Smith"

 If objNewMail.IsConflict = False Then

 objNewMail.Send

 Else

 MsgBox "Conflict: Cannot send mail item."

 End If

 Set olApp = Nothing

 Set objNewMail = Nothing

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.IsMarkedAsTask Property (Outlook)

 Copy code hover
[image]

MailItem.IsMarkedAsTask Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the MailItem is marked as a task. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsMarkedAsTask

expression An expression that returns a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

MailItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a MailItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

Example

The following Microsoft Visual Basic for Applications (VBA) example returns the ItemProperties collection associated with a MailItem object.

VBA Copy code Copy code
Sub ItemProperty()

 'Creates a new e-mail item and accesses its properties.

 Dim objMail As Outlook.MailItem

 Dim objItems As Outlook.ItemProperties

 Dim objItem As Outlook.ItemProperty

 'Create the e-mail item.

 Set objMail = Application.CreateItem(olMailItem)

 'Create a reference to the e-mail item's properties collection.

 Set objItems = objMail.ItemProperties

 'Create a reference to the third e-mail item property.

 Set objItem = objItems.Item(2)

 MsgBox objItem.Name & " = " & objItem.Value

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

MailItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

MailItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a MailItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.MessageClass Property (Outlook)

 Copy code hover
[image]

MailItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
MailItem Object

Other resources

MailItem Object Members


MailItem.Mileage Property (Outlook)

 Copy code hover
[image]

MailItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a MailItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.NoAging Property (Outlook)

 Copy code hover
[image]

MailItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.OriginatorDeliveryReportRequested Property (Outlook)

 Copy code hover
[image]

MailItem.OriginatorDeliveryReportRequested Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.

Syntax

expression .OriginatorDeliveryReportRequested

expression A variable that represents a MailItem object.

Remarks

Each transport provider that handles your message sends you a single delivery notification containing the names and addresses of each recipient to whom it was delivered. Delivery does not imply that the message has been read. True if the originator requested a delivery receipt on the message.

The OriginatorDeliveryReportRequested property corresponds to the MAPI property PidTagOriginatorDeliveryReportRequested.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

MailItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

MailItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Parent Property (Outlook)

 Copy code hover
[image]

MailItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Permission Property (Outlook)

 Copy code hover
[image]

MailItem.Permission Property (Outlook)
See also Send feedback

Published: July 16, 2012

Sets or returns an OlPermission constant that determines what permissions to grant to the recipients of the e-mail item. Read/write.

Syntax

expression .Permission

expression A variable that represents a MailItem object.

Remarks

The Permission property should be synchronized with the PermissionTemplateGuid property to accurately reflect the permission status of the MailItem. Setting the PermissionTemplateGuid property to a valid GUID also sets the Permission property to OlPermission.olPermissionTemplate.

When no Information Rights Management (IRM) has been set up, (in which case the Permission property is OlPermission.olUnrestricted), or the restriction is not to forward the MailItem, (in which case the Permission property is OlPermission.olDoNotForward), the value of the PermissionTemplateGuid property should be an empty string.

Although you can view content that is protected by IRM on any computer that is running the 2007 Microsoft Office system or a later version, you must have Microsoft Office Professional Edition 2003, Microsoft Office Outlook 2007, or a later version of Outlook to create or send an e-mail that is protected by IRM.

Example

This Microsoft Visual Basic for Applications (VBA) example uses the Send event and sends an item with a 'Do not forward' restriction. You must place the sample code in a class module such as ThisOutlookSession, and the SendMyMail procedure must be called before the event procedure can be called by Microsoft Outlook. Replace 'Dan Wilson' with a valid recipient name before you run this example.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub SendMyMail()

 Set myItem = Outlook.CreateItem(olMailItem)

 myItem.To = "Dan Wilson"

 myItem.Subject = "Data files information"

 myItem.Send

End Sub

Private Sub myItem_Send(Cancel As Boolean)

 myItem.Permission = olDoNotForward

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.PermissionService Property (Outlook)

 Copy code hover
[image]

MailItem.PermissionService Property (Outlook)
See also Send feedback

Published: July 16, 2012

Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a message protected by Information Rights Management (IRM). Read/write.

Syntax

expression .PermissionService

expression A variable that represents a MailItem object.

Remarks

This property is useful only if you have more than one permission identity for a particular SMTP address.

While you can view content that is protected by IRM on any computer running the 2007 Microsoft Office system or a later version, you must have Microsoft Office Professional Edition 2003, Microsoft Office Outlook 2007, or a later version of Outlook to create or send an e-mail that is protected by IRM.

Example

This Microsoft Visual Basic for Applications (VBA) example demonstrates how to specify the permission service before sending an item. Replace 'Dan Wilson' with a valid recipient name before running this example.

VBA Copy code Copy code
Sub SendMyMail()

 Set myItem = Outlook.CreateItem(olMailItem)

 myItem.To = "Dan Wilson"

 myItem.Subject = "Data files information"

 myItem.Permission = olDoNotForward

 myItem.PermissionService = olWindows

 myItem.Send

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.PermissionTemplateGuid Property (Outlook)

 Copy code hover
[image]

MailItem.PermissionTemplateGuid Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the GUID of the template file to apply to the MailItem in order to specify Information Rights Management (IRM) permissions. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .PermissionTemplateGuid

expression A variable that represents a MailItem object.

Remarks

This property complements the IRM properties on a MailItem object; that is, the Permission property and the PermissionService properties.

In particular, the PermissionTemplateGuid property should be synchronized with the Permission property to accurately reflect the permission status of the MailItem. Setting the PermissionTemplateGuid property to a valid GUID should also incur setting the Permission property to OlPermission.olPermissionTemplate.

An empty string value for the PermissionTemplateGuid property means that there is no permission template file specified for the MailItem. For example, if no IRM has been set up (in which case the Permission property is OlPermission.olUnrestricted), or the restriction is not to forward the MailItem (in which case the Permission property is OlPermission.olDoNotForward).

If you attempt to set the PermissionTemplateGuid property for a received message (that is, the Sent property of the MailItem is True), Microsoft Outlook returns an error.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

MailItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MailItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReadReceiptRequested Property (Outlook)

 Copy code hover
[image]

MailItem.ReadReceiptRequested Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates True if a read receipt has been requested by the sender.

Syntax

expression .ReadReceiptRequested

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReadReceiptRequested. Read/write for e-mail items that have been created but have not been sent or posted; read-only for sent e-mail items.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReceivedByEntryID Property (Outlook)

 Copy code hover
[image]

MailItem.ReceivedByEntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the mail message. Read-only.

Syntax

expression .ReceivedByEntryID

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedByEntryId.

If you are getting this property in a Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) solution, owing to some type issues, instead of directly referencing ReceivedByEntryID, you should get the property through the PropertyAccessor object returned by the MailItem.PropertyAccessor property, specifying the PidTagReceivedByEntryId property and its MAPI proptag namespace. The following code sample in VBA shows the workaround.

VBA Copy code Copy code
Public Sub GetReceiverEntryID()

 Dim objInbox As Outlook.Folder

 Dim objMail As Outlook.MailItem

 Dim oPA As Outlook.PropertyAccessor

 Dim strEntryID As String

 Const PidTagReceivedByEntryId As String = "http://schemas.microsoft.com/mapi/proptag/0x003F0102"

 Set objInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 Set objMail = objInbox.Items(1)

 Set oPA = objMail.PropertyAccessor

 strEntryID = oPA.BinaryToString(oPA.GetProperty(PidTagReceivedByEntryId))

 Debug.Print strEntryID

 Set objInbox = Nothing

 Set objMail = Nothing

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReceivedByName Property (Outlook)

 Copy code hover
[image]

MailItem.ReceivedByName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the true recipient for the mail message. Read-only.

Syntax

expression .ReceivedByName

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedByName.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReceivedOnBehalfOfEntryID Property (Outlook)

 Copy code hover
[image]

MailItem.ReceivedOnBehalfOfEntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the EntryID of the user delegated to represent the recipient for the mail message. Read-only.

Syntax

expression .ReceivedOnBehalfOfEntryID

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedRepresentingEntryId.

If you are getting this property in a Microsoft Visual Basic or Microsoft Visual Basic for Applications (VBA) solution, owing to some type issues, instead of directly referencing ReceivedOnBehalfOfEntryID, you should get the property through the PropertyAccessor object returned by the MailItem.PropertyAccessor property, specifying the MAPI property PidTagReceivedRepresentingEntryId property and its MAPI proptag namespace. The following code sample in VBA shows the workaround.

VBA Copy code Copy code
Public Sub GetReceiverEntryID()

 Dim objInbox As Outlook.Folder

 Dim objMail As Outlook.MailItem

 Dim oPA As Outlook.PropertyAccessor

 Dim strEntryID As String

 Const PidTagReceivedRepresentingEntryId As String = "http://schemas.microsoft.com/mapi/proptag/0x00430102"

 Set objInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 Set objMail = objInbox.Items(1)

 Set oPA = objMail.PropertyAccessor

 strEntryID = oPA.BinaryToString(oPA.GetProperty(PidTagReceivedRepresentingEntryId))

 Debug.Print strEntryID

 Set objInbox = Nothing

 Set objMail = Nothing

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReceivedOnBehalfOfName Property (Outlook)

 Copy code hover
[image]

MailItem.ReceivedOnBehalfOfName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the user delegated to represent the recipient for the mail message. Read-only.

Syntax

expression .ReceivedOnBehalfOfName

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedRepresentingName.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReceivedTime Property (Outlook)

 Copy code hover
[image]

MailItem.ReceivedTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time at which the item was received. Read-only.

Syntax

expression .ReceivedTime

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.RecipientReassignmentProhibited Property (Outlook)

 Copy code hover
[image]

MailItem.RecipientReassignmentProhibited Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the recipient cannot forward the mail message. Read/write.

Syntax

expression .RecipientReassignmentProhibited

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Recipients Property (Outlook)

 Copy code hover
[image]

MailItem.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.

Syntax

expression .Recipients

expression A variable that represents a MailItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

Example

This Visual Basic for Applications (VBA) example creates a new e-mail message, uses the Add method to add "Dan Wilson" as a To recipient, and displays the message.

VBA Copy code Copy code
Sub CreateStatusReportToBoss()

 Dim myItem As Outlook.MailItem

 Dim myRecipient As Outlook.Recipient

 Set myItem = Application.CreateItem(olMailItem)

 Set myRecipient = myItem.Recipients.Add("Dan Wilson")

 myItem.Subject = "Status Report"

 myItem.Display

End Sub

See also

Concepts

MailItem Object
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

MailItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a MailItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

MailItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents a MailItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

MailItem.ReminderSet Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

MailItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents a MailItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

MailItem.ReminderTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.RemoteStatus Property (Outlook)

 Copy code hover
[image]

MailItem.RemoteStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant specifying the remote status of the mail message. Read/write.

Syntax

expression .RemoteStatus

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReplyRecipientNames Property (Outlook)

 Copy code hover
[image]

MailItem.ReplyRecipientNames Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a semicolon-delimited String list of reply recipients for the mail message. Read-only.

Syntax

expression .ReplyRecipientNames

expression A variable that represents a MailItem object.

Remarks

This property only contains the display names for the reply recipients. The reply recipients list should be set by using the ReplyRecipients collection.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReplyRecipients Property (Outlook)

 Copy code hover
[image]

MailItem.ReplyRecipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.

Syntax

expression .ReplyRecipients

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.RetentionExpirationDate Property (Outlook)

 Copy code hover
[image]

MailItem.RetentionExpirationDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that specifies the date when the MailItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionExpirationDate

expression A variable that represents a MailItem object.

Remarks

A retention policy is enabled and disabled by an administrator for an Exchange Server on a mailbox level. This feature is available only on an Exchange mailbox with MRM version 2.0 or later enabled.

Microsoft Outlook calculates the value of this property based on the item retention start date and the retention period, if Outlook is in cache or offline mode. The Exchange Server specifies the value if Outlook is in online mode.

In general, the retention start date for the item is determined as follows:

  • Received or sent items: the retention start date is the received date.

  • Nonrecurring calendar items: the retention start date is the appointment end date.

  • Recurring calendar items: the retention start date is the end date of last recurrence. If there is no end date, the item never expires.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.RetentionPolicyName Property (Outlook)

 Copy code hover
[image]

MailItem.RetentionPolicyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that specifies the name of the retention policy. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionPolicyName

expression A variable that represents a MailItem object.

Remarks

Retention is enabled and disabled by an administrator for an Exchange Server on a mailbox level. The feature is available only on an Exchange mailbox with Messaging Records Management (MRM), version 2.0 or later enabled. An example of a retention policy name is "Define time interval for expiration Quick Searches".

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.RTFBody Property (Outlook)

 Copy code hover
[image]

MailItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a MailItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

Example

The following code samples in Microsoft Visual Basic for Applications (VBA) and C# displays the Rich Text Format body of the appointment in the active inspector. A MailItem must be the active inspector for this code to work.

VBA Copy code Copy code
Sub GetRTFBodyForMail()

 Dim oMail As Outlook.MailItem

 Dim strRTF As String

 If Application.ActiveInspector.CurrentItem.Class = olMail Then

 Set oMail = Application.ActiveInspector.CurrentItem

 strRTF = StrConv(oMail.RTFBody, vbUnicode)

 Debug.Print strRTF

 End If

End Sub
Copy code Copy code
private void GetRTFBodyForMail()

{

 if (Application.ActiveInspector().CurrentItem is Outlook.MailItem)

 {

 Outlook.MailItem mail =

 Application.ActiveInspector().CurrentItem as Outlook.MailItem;

 byte[] byteArray = mail.RTFBody as byte[];

 System.Text.Encoding encoding = new System.Text.ASCIIEncoding();

 string RTF = encoding.GetString(byteArray);

 Debug.WriteLine(RTF);

 }

}

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Saved Property (Outlook)

 Copy code hover
[image]

MailItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a MailItem object.

Example

This Microsoft Visual Basic for Applications (VBA) example tests for the Close event and if the item has not been Saved, it uses the Save method to save the item without prompting the user.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Public Sub Initalize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_Close(Cancel As Boolean)

 If Not myItem.Saved Then

 myItem.Save

 MsgBox "Item was saved."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SaveSentMessageFolder Property (Outlook)

 Copy code hover
[image]

MailItem.SaveSentMessageFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.

Syntax

expression .SaveSentMessageFolder

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications (VBA) example sends a reply to Dan Wilson and sets the SaveMyPersonalItems folder as the folder in which a copy of the item will be saved after being sent. To run this example without errors, make sure a mail item is open in the active inspector window and replace 'Dan Wilson' with a valid recipient name.

Copy code Copy code
Sub SetSentFolder()

 Dim myItem As Outlook.MailITem

 Dim myResponse As Outlook.MailITem

 Dim mpfInbox As Outlook.Folder

 Dim mpf As Outlook.Folder

 Set mpfInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 Set mpf = mpfInbox.Folders.Add("SaveMyPersonalItems")

 Set myItem = Application.ActiveInspector.CurrentItem

 Set myResponse = myItem.Reply

 myResponse.Display

 myResponse.To = "Dan Wilson"

 Set myResponse.SaveSentMessageFolder = mpf

 myResponse.Send

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Sender Property (Outlook)

 Copy code hover
[image]

MailItem.Sender Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an AddressEntry object that corresponds to the user of the account from which the MailItem is sent. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Sender

expression A variable that represents a MailItem object.

Remarks

In a session where multiple accounts are defined in the profile, you can set this property to specify the account from which to send a mail item. Set this property to the AddressEntry object of the user that is represented by the CurrentUser property of a specific account.

If you set the Sender property to an AddressEntry that does not have permissions to send messages on that account, Microsoft Outlook will raise an error.

Example

Michael Bauer provided the following code example. Michael is a Microsoft Most Valuable Professional with expertise in developing Outlook solutions in Visual Basic and Visual Basic for Applications (VBA). Michael maintains a professional site at VBOffice.net.

The following VBA code example shows how to display the details of the sender of an e-mail. If the sender corresponds to a contact in the user's Outlook Contacts Address Book (CAB), the code example displays information about that contact in an inspector. If the sender is not a contact in the user's CAB, the code example displays details from the user's address entry (taken from the transport provider's address book container) in a dialog box.

To display information about a sender, the user should have selected a MailItem in the explorer. The code example also checks whether the selected MailItem has been sent, because the Sender property is defined only if the Mailtem has been sent. The example then accesses the Sender property to obtain the AddressEntry object that corresponds to the sender of that mail item, and displays the contact information, if it exists; otherwise, the example displays the address entry details.

VBA Copy code Copy code

Public Sub DisplaySenderDetails()
 Dim Explorer As Outlook.Explorer
 Dim CurrentItem As Object
 Dim Sender As Outlook.AddressEntry
 Dim Contact As Outlook.ContactItem

 Set Explorer = Application.ActiveExplorer

 ' Check whether any item is selected in the current folder.
 If Explorer.Selection.Count Then

 ' Get the first selected item.
 Set CurrentItem = Explorer.Selection(1)

 ' Check for the type of the selected item as only the
 ' MailItem object has the Sender property.
 If CurrentItem.Class = olMail Then
 Set Sender = CurrentItem.Sender

 ' There is no sender if the item has not been sent yet.
 If Sender Is Nothing Then
 MsgBox "There's no sender for the current email", vbInformation
 Exit Sub
 End If

 Set Contact = Sender.GetContact

 If Not Contact Is Nothing Then
 ' The sender is stored in the contacts folder,
 ' so the contact item can be displayed.
 Contact.Display

 Else
 ' If the contact cannot be found, display the
 ' address entry in the properties dialog box.
 Sender.Details 0
 End If
 End If
 End If
End Sub

See also

Concepts

MailItem Object
How to: Create a Sendable Item for a Specific Account Based on the Current Folder

Other resources

MailItem Object Members


MailItem.SenderEmailAddress Property (Outlook)

 Copy code hover
[image]

MailItem.SenderEmailAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.

Syntax

expression .SenderEmailAddress

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderEmailAddress.

Example

The following Microsoft Visual Basic for Applications (VBA) example loops all items in a folder named Test in the Inbox and sets the yellow flag on items sent by 'someone@example.com'. To run this example without errors, make sure the Test folder exists in the default Inbox folder and replace 'someone@example.com' with a valid sender e-mail address in the Test folder.

VBA Copy code Copy code
Sub SetFlagIcon()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Outlook.MailItem

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Folders("Test")

 ' Loop all items in the Inbox\Test Folder

 For i = 1 To mpfInbox.Items.Count

 If mpfInbox.Items(i).Class = olMail Then

 Set obj = mpfInbox.Items.Item(i)

 If obj.SenderEmailAddress = "someone@example.com" Then

 'Set the yellow flag icon

 obj.FlagIcon = olYellowFlagIcon

 obj.Save

 End If

 End If

 Next

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SenderEmailType Property (Outlook)

 Copy code hover
[image]

MailItem.SenderEmailType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.

Syntax

expression .SenderEmailType

expression A variable that represents a MailItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example demonstrates how to use the SenderEmailType property. To run this example without errors, an e-mail item should be open in the active inspector window.

VBA Copy code Copy code
Sub SenderEmailTypeExample()

 Dim mail As Outlook.MailItem

 Set mail = Application.ActiveInspector.CurrentItem

 MsgBox mail.SenderEmailType

 If mail.SenderEmailType = "SMTP" Then

 MsgBox "Message from Internet e-mail user."

 Else

 If mail.SenderEmailType = "EX" Then

 MsgBox "Message from internal Exchange user."

 End If

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SenderName Property (Outlook)

 Copy code hover
[image]

MailItem.SenderName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the display name of the sender for the Outlook item. Read-only.

Syntax

expression .SenderName

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderName.

If you wish to retrieve the fully qualified e-mail address of the sender, use the SenderEmailAddress property.

Example

This Visual Basic for Applications (VBA) example checks if the item displayed in the topmost inspector is sent by 'Dan Wilson' with 'High' importance. If it is, then it displays a message box to the user. Before running this example, replace 'Dan Wilson' with a valid name in your address book.

VBA Copy code Copy code
Sub CheckSenderName

 Dim myItem As Outlook.MailItem

 Set myItem = Application.ActiveInspector.CurrentItem

 If myItem.Importance = 2 And myItem.SenderName = _

 "Dan Wilson" Then

 MsgBox "This message is sent by your manager with High importance."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SendUsingAccount Property (Outlook)

 Copy code hover
[image]

MailItem.SendUsingAccount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an Account object that represents the account under which the MailItem is to be sent. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SendUsingAccount

expression An expression that returns a MailItem object.

Remarks

The SendUsingAccount property can be used to specify the account that should be used to send the MailItem when the Send method is called. This property returns Null (Nothing in Visual Basic) if the account specified for the MailItem no longer exists.

Example

The following code sample in Microsoft Visual Basic for Applications enumerates the Accounts collection to find a Pop3 account. If the account is found, then a message is created programmatically and the SendUsingAccount property is assigned to the Pop3 account. Note that you must assign the SendUsingAccount property before you call the Send method.

VBA Copy code Copy code
Sub SendUsingAccount()

 Dim oAccount As Outlook.account

 For Each oAccount In Application.Session.Accounts

 If oAccount.AccountType = olPop3 Then

 Dim oMail As Outlook.MailItem

 Set oMail = Application.CreateItem(olMailItem)

 oMail.Subject = "Sent using POP3 Account"

 oMail.Recipients.Add ("someone@example.com")

 oMail.Recipients.ResolveAll

 oMail.SendUsingAccount = oAccount

 oMail.Send

 End If

 Next

End Sub

See also

Concepts

MailItem Object
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

MailItem.Sensitivity Property (Outlook)
See also Send feedback

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Sent Property (Outlook)

 Copy code hover
[image]

MailItem.Sent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates if a message has been sent. Read-only.

Syntax

expression .Sent

expression A variable that represents a MailItem object.

Remarks

In general, there are three different kinds of messages: sent, posted, and saved. Sent messages are items sent to a recipient or public folder. Posted messages are created in a public folder. Saved messages are created and saved without either sending or posting.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SentOn Property (Outlook)

 Copy code hover
[image]

MailItem.SentOn Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.

Syntax

expression .SentOn

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagClientSubmitTime. When you send an item using the object's Send method, the transport provider sets the ReceivedTime and SentOn properties for you.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SentOnBehalfOfName Property (Outlook)

 Copy code hover
[image]

MailItem.SentOnBehalfOfName Property (Outlook)
See also Send feedback

Returns a String indicating the display name for the intended sender of the mail message. Read/write.

Syntax

expression .SentOnBehalfOfName

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagSentRepresentingName.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Session Property (Outlook)

 Copy code hover
[image]

MailItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a MailItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Size Property (Outlook)

 Copy code hover
[image]

MailItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Subject Property (Outlook)

 Copy code hover
[image]

MailItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

Example

This Microsoft Visual Basic for Applications (VBA) example creates a new e-mail message, uses the Add method to add "Dan Wilson" as a To recipient, sets the Subject property, and displays the message.

VBA Copy code Copy code
Sub CreateStatusReportToBoss()

 Dim myItem As Outlook.MailItem

 Dim myRecipient As Outlook.Recipient

 Set myItem = Application.CreateItem(olMailItem)

 Set myRecipient = myItem.Recipients.Add("Dan Wilson")

 myItem.Subject = "Status Report"

 myItem.Display

End Sub

See also

Concepts

MailItem Object

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem.Submitted Property (Outlook)

 Copy code hover
[image]

MailItem.Submitted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the item has been submitted. Read-only.

Syntax

expression .Submitted

expression A variable that represents a MailItem object.

Remarks

A message is always created and submitted in a folder, usually the Outbox.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.TaskCompletedDate Property (Outlook)

 Copy code hover
[image]

MailItem.TaskCompletedDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the completion date of the task for this MailItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskCompletedDate

expression An expression that returns a MailItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.TaskDueDate Property (Outlook)

 Copy code hover
[image]

MailItem.TaskDueDate Property (Outlook)
See also Send feedback

Returns or sets a Date value that represents the due date of the task for this MailItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskDueDate

expression An expression that returns a MailItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.TaskStartDate Property (Outlook)

 Copy code hover
[image]

MailItem.TaskStartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date of the task for this MailItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskStartDate

expression An expression that returns a MailItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.TaskSubject Property (Outlook)

 Copy code hover
[image]

MailItem.TaskSubject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the subject of the task for the MailItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskSubject

expression An expression that returns a MailItem object.

Remarks

This property returns the value of the Subject property if the IsMarkedAsTask property is set to False.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.To Property (Outlook)

 Copy code hover
[image]

MailItem.To Property (Outlook)
See also Send feedback

Returns or sets a semicolon-delimited String list of display names for the To recipients for the Outlook item. Read/write.

Syntax

expression .To

expression A variable that represents a MailItem object.

Remarks

This property contains the display names only. The To property corresponds to the MAPI property PidTagDisplayTo. The Recipients collection should be used to modify this property.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

MailItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Returns or sets a Date value that represents the ordinal value of the task for the MailItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a MailItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar. The value used in this property does not have any relation to the values of the TaskStartDate, TaskDueDate, or TaskCompletedDate properties.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.UnRead Property (Outlook)

 Copy code hover
[image]

MailItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.UserProperties Property (Outlook)

 Copy code hover
[image]

MailItem.UserProperties Property (Outlook)
See also Send feedback

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.VotingOptions Property (Outlook)

 Copy code hover
[image]

MailItem.VotingOptions Property (Outlook)
See also Send feedback

Returns or sets a String specifying a delimited string containing the voting options for the mail message. Read/write.

Syntax

expression .VotingOptions

expression A variable that represents a MailItem object.

Remarks

This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple voting options.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.VotingResponse Property (Outlook)

 Copy code hover
[image]

MailItem.VotingResponse Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the voting response for the mail message. Read/write.

Syntax

expression .VotingResponse

expression A variable that represents a MailItem object.

Remarks

This property is usually set to one of the delimited values returned by the VotingOptions property on a reply to the original message.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem Methods (Outlook)

 Copy code hover
[image]

MailItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddBusinessCard | Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the MailItem object.
ClearConversationIndex | Clears the index of the conversation thread for the mail message.
ClearTaskFlag | Clears the MailItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a MailItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the e-mail message.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


MailItem.AddBusinessCard Method (Outlook)

 Copy code hover
[image]

MailItem.AddBusinessCard Method (Outlook)
See also Send feedback

Published: July 16, 2012

Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the MailItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddBusinessCard(contact)

expression An expression that returns a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
contact | Required | ContactItem | The contact item from which to obtain the business card information.

Remarks

This method adds contact information, generated from the information stored in the ContactItem object, to the existing MailItem object. The information included depends on the value of the BodyFormat property for the MailItem object:

Property value | Result
olFormatPlain | A vCard (.vcf) file is created and added to the Attachments collection of the MailItem object.
olFormatRichText | A vCard (.vcf) file is created and added to the Attachments collection of the MailItem object.
olFormatHTML | An image of the business card is generated and included in the Body property of the MailItem object, and a vCard (.vcf) file is created and added to the Attachments collection of the MailItem object.
Note Note

The attached vCard file contains only the contact information included in the Electronic Business Card associated with the ContactItem object. Any contact information not displayed in the Electronic Business Card is excluded from the vCard file.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ClearConversationIndex Method (Outlook)

 Copy code hover
[image]

MailItem.ClearConversationIndex Method (Outlook)
See also Send feedback

Clears the index of the conversation thread for the mail message.

Syntax

expression .ClearConversationIndex

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ClearTaskFlag Method (Outlook)

 Copy code hover
[image]

MailItem.ClearTaskFlag Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the MailItem object as a task.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearTaskFlag

expression An expression that returns a MailItem object.

Remarks

Calling this method sets the IsMarkedAsTask property to False.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Close Method (Outlook)

 Copy code hover
[image]

MailItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

Example

This Visual Basic for Applications (VBA) example saves and closes the item displayed in the active inspector without prompting the user. To run this example, you need to have an item displayed in an inspector window.

VBA Copy code Copy code
Sub CloseItem()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Set myinspector = Application.ActiveInspector

 Set myItem = myinspector.CurrentItem

 myItem.Close olSave

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Copy Method (Outlook)

 Copy code hover
[image]

MailItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a MailItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Delete Method (Outlook)

 Copy code hover
[image]

MailItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a MailItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

MailItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

MailItem Object Members


MailItem.Display Method (Outlook)

 Copy code hover
[image]

MailItem.Display Method (Outlook)
See also Send feedback

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

Example

This Visual Basic for Applications example displays the first item in the Inbox folder. This example will return an error if the Inbox is empty, because you are trying to display a specific item. If there are no items in the folder, a message box will be displayed to inform the user.

Note Note

The items in the Items collection object are not guaranteed to be in any particular order.
VBA Copy code Copy code
Sub DisplayFirstItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 On Error GoTo ErrorHandler

 myFolder.Items(1).Display

 Exit Sub

ErrorHandler:

 MsgBox "There are no items to display."

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Forward Method (Outlook)

 Copy code hover
[image]

MailItem.Forward Method (Outlook)
See also Send feedback

Executes the Forward action for an item and returns the resulting copy as a MailItem object.

Syntax

expression .Forward

expression A variable that represents a MailItem object.

Return Value

A MailItem object that represents the new mail item.

Example

This Visual Basic for Applications (VBA) example uses the Remove method to remove all attachments from a forwarded message before sending it on to Dan Wilson. To run this example, replace 'Dan Wilson' with a valid recipient name and keep a mail item that contains at least one attachment open in the active window.

VBA Copy code Copy code
Sub RemoveAttachmentBeforeForwarding()

 Dim myinspector As Outlook.Inspector

 Dim myItem As Outlook.MailItem

 Dim myattachments As Outlook.Attachments

 Set myinspector = Application.ActiveInspector

 If Not TypeName(myinspector) = "Nothing" Then

 Set myItem = myinspector.CurrentItem.Forward

 Set myattachments = myItem.Attachments

 While myattachments.Count > 0

 myattachments.Remove 1

 Wend

 myItem.Display

 myItem.Recipients.Add "Dan Wilson"

 myItem.Send

 Else

 MsgBox "There is no active inspector."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.GetConversation Method (Outlook)

 Copy code hover
[image]

MailItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a MailItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

Example

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code example assumes that the selected item in the explorer window is a mail item. The code example gets the conversation that the selected mail item is associated with, and enumerates each item in that conversation, displaying the subject of the item. The DemoConversation method calls the GetConversation method of the selected mail item to get the associated Conversation object. DemoConversation then calls the GetTable and GetRootItems methods of the Conversation object to get a Table object and SimpleItems collection, respectively. DemoConversation calls the recurrent method EnumerateConversation to enumerate and display the subject of each item in that conversation.

C# Copy code Copy code
void DemoConversation()
{
 object selectedItem =
 Application.ActiveExplorer().Selection[1];
 // This example uses only
 // MailItem. Other item types such as
 // MeetingItem and PostItem can participate
 // in the conversation.
 if (selectedItem is Outlook.MailItem)
 {
 // Cast selectedItem to MailItem.
 Outlook.MailItem mailItem =
 selectedItem as Outlook.MailItem;
 // Determine the store of the mail item.
 Outlook.Folder folder = mailItem.Parent
 as Outlook.Folder;
 Outlook.Store store = folder.Store;
 if (store.IsConversationEnabled == true)
 {
 // Obtain a Conversation object.
 Outlook.Conversation conv =
 mailItem.GetConversation();
 // Check for null Conversation.
 if (conv != null)
 {
 // Obtain Table that contains rows
 // for each item in the conversation.
 Outlook.Table table = conv.GetTable();
 Debug.WriteLine("Conversation Items Count: " +
 table.GetRowCount().ToString());
 Debug.WriteLine("Conversation Items from Table:");
 while (!table.EndOfTable)
 {
 Outlook.Row nextRow = table.GetNextRow();
 Debug.WriteLine(nextRow["Subject"]
 + " Modified: "
 + nextRow["LastModificationTime"]);
 }
 Debug.WriteLine("Conversation Items from Root:");
 // Obtain root items and enumerate the conversation.
 Outlook.SimpleItems simpleItems
 = conv.GetRootItems();
 foreach (object item in simpleItems)
 {
 // In this example, enumerate only MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (item is Outlook.MailItem)
 {
 Outlook.MailItem mail = item
 as Outlook.MailItem;
 Outlook.Folder inFolder =
 mail.Parent as Outlook.Folder;
 string msg = mail.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Call EnumerateConversation
 // to access child nodes of root items.
 EnumerateConversation(item, conv);
 }
 }
 }
 }
}

void EnumerateConversation(object item,
 Outlook.Conversation conversation)
{
 Outlook.SimpleItems items =
 conversation.GetChildren(item);
 if (items.Count > 0)
 {
 foreach (object myItem in items)
 {
 // In this example, enumerate only MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (myItem is Outlook.MailItem)
 {
 Outlook.MailItem mailItem =
 myItem as Outlook.MailItem;
 Outlook.Folder inFolder =
 mailItem.Parent as Outlook.Folder;
 string msg = mailItem.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Continue recursion.
 EnumerateConversation(myItem, conversation);
 }
 }
}

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.MarkAsTask Method (Outlook)

 Copy code hover
[image]

MailItem.MarkAsTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks a MailItem object as a task and assigns a task interval for the object.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask(MarkInterval)

expression An expression that returns a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
MarkInterval | Required | OlMarkInterval | The task interval for the MailItem.

Remarks

Calling this method sets the value of several other properties, depending on the value provided in MarkInterval. For more information about the properties set by specifying MarkInterval, see OlMarkInterval Enumeration.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Move Method (Outlook)

 Copy code hover
[image]

MailItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

Example

This Visual Basic for Applications (VBA) example uses GetDefaultFolder to return the Folder object that represents the default folder. It then uses the Find and FindNext methods to find all messages sent by Dan Wilson and uses the Move method to move all e-mail messages sent by Dan Wilson from the default Inbox folder to the Personal Mail folder. To run this example without any errors, replace 'Dan Wilson' with a vaid sender name and make sure there's a folder under Inbox called 'Personal Mail'. Note that myItem is declared as type Object so that it can represent all types of Outlook items including meeting request and task request items.

VBA Copy code Copy code
Sub MoveItems()
 Dim myNameSpace As Outlook.NameSpace
 Dim myInbox As Outlook.Folder
 Dim myDestFolder As Outlook.Folder
 Dim myItems As Outlook.Items
 Dim myItem As Object

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myInbox = myNameSpace.GetDefaultFolder(olFolderInbox)
 Set myItems = myInbox.Items
 Set myDestFolder = myInbox.Folders("Personal Mail")
 Set myItem = myItems.Find("[SenderName] = 'Dan Wilson'")
 While TypeName(myItem) <> "Nothing"
 myItem.Move myDestFolder
 Set myItem = myItems.FindNext
 Wend
End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.PrintOut Method (Outlook)

 Copy code hover
[image]

MailItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a MailItem object.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Reply Method (Outlook)

 Copy code hover
[image]

MailItem.Reply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a reply, pre-addressed to the original sender, from the original message.

Syntax

expression .Reply

expression A variable that represents a MailItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReplyAll Method (Outlook)

 Copy code hover
[image]

MailItem.ReplyAll Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a reply to all original recipients from the original message.

Syntax

expression .ReplyAll

expression A variable that represents a MailItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Save Method (Outlook)

 Copy code hover
[image]

MailItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a MailItem object.

Remarks

If a mail item is an inline reply, calling Save on that mail item may fail and result in unexpected behavior.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.SaveAs Method (Outlook)

 Copy code hover
[image]

MailItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.MailItem

 Set MyItem = Application.CreateItem(olMailItem)
 MyItem.Subject = "Status Report"
 MyItem.To = "Dan Wilson"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Send Method (Outlook)

 Copy code hover
[image]

MailItem.Send Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends the e-mail message.

Syntax

expression .Send

expression A variable that represents a MailItem object.

Remarks

The Send method sends an item using the default account specified for the session. In a session where multiple Microsoft Exchange accounts are defined in the profile, the first Exchange account added to the profile is the primary Exchange account, and is also the default account for the session. To specify a different account to send an item, set the SendUsingAccount property to the desired Account object and then call the Send method.

Example

If you use Microsoft Visual Basic Scripting Edition (VBScript) in an Outlook form, you do not create the Application object, and you cannot use named constants. This example shows how to forward a mail item using VBScript code.

Copy code Copy code
Sub CommandButton1_Click()
 Set myNameSpace = Application.GetNameSpace("MAPI")
 Set myFolder = myNameSpace.GetDefaultFolder(6)
 Set myForward = myFolder.Items(1).Forward
 myForward.Recipients.Add "Laura Jennings"
 myForward.Send
End Sub

See also

Concepts

MailItem Object
How to: Send an E-mail Given the SMTP Address of an Account

Other resources

How to: Send an E-mail Given the SMTP Address of an Account
MailItem Object Members


MailItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

MailItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a MailItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new mail item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub MailItem()

 'Creates a mail item to access ShowCategoriesDialog

 Dim olmyMailItem As Outlook.MailItem

 'Create mail item

 Set olmyMailItem = Application.CreateItem(olMailItem)

 olmyMailItem.Body = "Can you help me with these sales figures."

 olmyMailItem.Recipients.Add ("Jeff Smith")

 olmyMailItem.Subject = "Sales Reports"

 'Display the item

 olmyMailItem.Display

 'Display the Show categories dialog

 olmyMailItem.ShowCategoriesDialog

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem Events (Outlook)

 Copy code hover
[image]

MailItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


MailItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

MailItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a MailItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

MailItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

Example

This Visual Basic for Applications (VBA) example checks the size of the item after an attachment has been added and displays a warning if the size exceeds 500,000 bytes. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAttachAdd() procedure should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents newItem As Outlook.MailItem

Private Sub newItem_AttachmentAdd(ByVal newAttachment As Attachment)

 If newAttachment.Type = olByValue Then

 newItem.Save

 If newItem.Size > 500000 Then

 MsgBox "Warning: Item size is now " & newItem.Size & " bytes."

 End If

 End If

End Sub

Public Sub TestAttachAdd()

 Dim atts As Outlook.Attachments

 Dim newAttachment As Outlook.Attachment

 Set newItem = Application.CreateItem(olMailItem)

 newItem.Subject = "Test attachment"

 Set atts = newItem.Attachments

 Set newAttachment = atts.Add("C:\Test.txt", olByValue)

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

MailItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

Example

This Visual Basic for Applications (VBA) example displays a message when the user tries to read an attachment. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAttachRead() procedure should be called before the event procedure can be called by Microsoft Outlook. For this example to run, there has to be at least one item in the Inbox with subject as 'Test' and containing at least one attachment.

VBA Copy code Copy code
Public WithEvents myItem As outlook.MailItem

Private Sub myItem_AttachmentRead(ByVal myAttachment As Outlook.Attachment)

 If myAttachment.Type = olByValue Then

 MsgBox "If you change this file, also save your changes to the original file."

 End If

End Sub

Public Sub TestAttachRead()

 Dim atts As Outlook.Attachments

 Dim myAttachment As Outlook.Attachment

 Set myItem = Application.ActiveExplorer.CurrentFolder.Items("Test")

 Set atts = myItem.Attachments

 myItem.Display

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

MailItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

Example

This Visual Basic for Applications (VBA) example notifies the user that the user is not allowed to save the attachment. The Cancel argument is set to True to cancel the save operation. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAttachSave() procedure should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Private Sub myItem_BeforeAttachmentSave(ByVal myAttachment As Attachment, Cancel As Boolean)
 MsgBox "You are not allowed to save " & myAttachment.FileName
 Cancel = True
End Sub

Public Sub TestAttachSave()
 Set myItem = Application.ActiveInspector.CurrentItem
End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel, )

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the MailItem to be saved.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

Example

This Visual Basic for Applications (VBA) example asks the user if the user wants to resolve names and returns False to cancel the operation if the user answers no. The sample code must be placed in a class module such as ThisOutlookSession, and the SendMail() procedure should be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Private Sub myItem_BeforeCheckNames(Cancel As Boolean)

 If MsgBox("Do you want to resolve names now?", 4) = vbOK Then

 Cancel = True

 End If

End Sub

Public Sub SendMail()

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Recipients.Add ("Dan Wilson")

 myItem.Recipients.Add ("Nate Sun")

 myItem.Body = "Good morning!"

 myItem.Send

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

Example

The following Visual Basic for Applications (VBA) example prompts the user regarding whether to delete the item currently open. For this example to run, you need to have an open e-mail item that can be deleted. If you click No, the item will not be deleted. If this event is canceled, Microsoft Outlook displays an error message. Therefore, you need to capture this event in your code. One way to do this is shown below. The sample code must be placed in a class module such as ThisOutlookSession, and the DeleteMail() procedure should be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Public Sub DeleteMail()

 Const strCancelEvent = "Application-defined or object-defined error"

 On Error GoTo ErrHandler

 Set myItem = Application.ActiveInspector.CurrentItem

 myItem.Delete

 Exit Sub

ErrHandler:

 MsgBox Err.Description

 If Err.Description = strCancelEvent Then

 MsgBox "The event was cancelled."

 End If

 'If you want to execute the next instruction

 Resume Next

 'Otherwise it will finish here

End Sub

Private Sub myItem_BeforeDelete(ByVal Item As Object, Cancel As Boolean)

 'Prompts the user before deleting an item

 Dim strPrompt As String

 'Prompt the user for a response

 strPrompt = "Are you sure you want to delete the item?"

 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbNo Then

 'Don't delete the item

 Cancel = True

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

MailItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a MailItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Close Event (Outlook)

 Copy code hover
[image]

MailItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

Example

This Microsoft Visual Basic for Applications (VBA) example tests for the Close event and if the item has not been Saved, it uses the Save method to save the item without prompting the user.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Public Sub Initalize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_Close(Cancel As Boolean)

 If Not myItem.Saved Then

 myItem.Save

 MsgBox " The item was saved."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.CustomAction Event (Outlook)

 Copy code hover
[image]

MailItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

Example

This Visual Basic for Applications (VBA) example uses the CustomAction event to set the Subject property on the response item. Execute the AddAction procedure before executing the Initialize_Handler to create an item with a custom event called 'Link Original'.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub AddAction()

 Dim myAction As Outlook.Action

 Set myItem = Application.CreateItem(olMailItem)

 Set myAction = myItem.Actions.Add

 myAction.Name = "Link Original"

 myAction.ShowOn = olMenuAndToolbar

 myAction.ReplyStyle = olLinkOriginalItem

 myItem.To = "Dan Wilson"

 myItem.Subject = "Before"

 myItem.Send

End Sub

Sub Initialize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_CustomAction(ByVal Action As Object, ByVal Response As Object, Cancel As Boolean)

 Select Case Action.Name

 Case "Link Original"

 Response.Subject = "Changed by VB Script"

 Case Else

 End Select

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

MailItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Forward Event (Outlook)

 Copy code hover
[image]

MailItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in Microsoft Visual Basic Scripting Edition (VBScript).) False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

Example

This Microsoft Visual Basic for Applications (VBA) example uses the Forward event to disable forwarding on an item that has the subject "Do not forward" by setting the Cancel argument to True and it also displays a message that the item may not be forwarded. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() routine should be called before the event procedure can be called by Microsoft Outlook. A e-mail item must be open when you run Initialize_Handler().

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Public Sub Initialize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_Forward(ByVal Forward As Object, Cancel As Boolean)

 If myItem.Subject = "Do not forward" Then

 MsgBox "You may not forward this message!"

 Cancel = True

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Open Event (Outlook)

 Copy code hover
[image]

MailItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

Example

This Visual Basic for Applications (VBA) example uses the Open event to display the "All Fields" page every time the item is opened.

Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub Initialize_handler()

 Set myItem = Application.Session.GetDefaultFolder(olFolderInbox).Items(1)

 myItem.Display

End Sub

Private Sub myItem_Open(Cancel As Boolean)

 myItem.GetInspector.SetCurrentFormPage "All Fields"

End Sub

This Visual Basic for Applications example uses the Unread property to detect whether the item has been previously read. If it has, then it asks if the user wants to open it. If the user answers No, the return value is set to False to prevent the item from opening.

Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub Initialize_handler()

 Set myItem = Application.Session.GetDefaultFolder(olFolderInbox).Items(1)

 myItem.Display

End Sub

Private Sub myItem_Open(Cancel As Boolean)

 Dim mymsg As String

 If myItem.UnRead = False Then

 mymsg = "You have already read this message. Do you want to open this message again?"

 If MsgBox(mymsg, 4) = 6 Then

 Cancel = False

 Else

 Cancel = True

 End If

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

MailItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Read Event (Outlook)

 Copy code hover
[image]

MailItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a MailItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

Example

This Visual Basic for Applications (VBA) example uses the Read event to increment a counter that tracks how often an item is read.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub Initialize_handler()

 Set myItem = Application.ActiveExplorer.CurrentFolder.Items(1)

 myItem.Display

End Sub

Sub myItem_Read()

 Dim myProperty As Outlook.UserProperty

 Set myProperty = myItem.UserProperties("ReadCount")

 If (myProperty Is Nothing) Then

 Set myProperty = myItem.UserProperties.Add("ReadCount", olNumber)

 End If

 myProperty.Value = myProperty.Value + 1

 myItem.Save

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

MailItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Reply Event (Outlook)

 Copy code hover
[image]

MailItem.Reply Event (Outlook)
See also Send feedback

Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

Example

This Visual Basic for Applications (VBA) example uses the Reply event and sets the Sent Items folder for the reply item to the folder in which the original item resides. To use this example, open an existing mailitem, run the Initialize Handler() procedure, then reply to the open item.

Copy code Copy code
Public WithEvents myItem As MailItem

Sub Initialize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_Reply(ByVal Response As Object, Cancel As Boolean)

 Set Response.SaveSentMessageFolder = myItem.Parent

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

MailItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

Example

This Visual Basic for Applications (VBA) example uses the ReplyAll event and reminds the user that proceeding will reply to all original recipients of an item and, depending on the user's response, either allows the action to continue or stops it. To use this example, open an existing mail item, run the Initialize Handler() procedure, then reply to the item.

Copy code Copy code
Public WithEvents myItem As MailItem

Sub Initialize_Handler()

 Set myItem = Application.ActiveInspector.CurrentItem

End Sub

Private Sub myItem_ReplyAll(ByVal Response As Object, Cancel As Boolean)

 Dim mymsg As String

 Dim myResult As Integer

 mymsg = "Do you really want to reply to all original recipients?"

 myResult = MsgBox(mymsg, vbYesNo, "Flame Protector")

 If myResult = vbNo Then

 Cancel = True

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Send Event (Outlook)

 Copy code hover
[image]

MailItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.

Syntax

expression .Send(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

Example

This Visual Basic for Applications (VBA) example uses the Send event and sends an item with an automatic expiration date. The sample code must be placed in a class module such as ThisOutlookSession, and the SendMyMail procedure must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub SendMyMail()

 Set myItem = Outlook.CreateItem(olMailItem)

 myItem.To = "Dan Wilson"

 myItem.Subject = "Data files information"

 myItem.Send

End Sub

Private Sub myItem_Send(Cancel As Boolean)

 myItem.ExpiryTime = #2/2/2003 4:00:00 PM#

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Unload Event (Outlook)

 Copy code hover
[image]

MailItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a MailItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailItem.Write Event (Outlook)

 Copy code hover
[image]

MailItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a MailItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

Example

This Visual Basic for Applications (VBA) example uses the Write event and warns the user that the item is about to be saved and will overwrite any existing item and, depending on the user's response, either allows the operation to continue or stops it. If this event is canceled, Microsoft Outlook displays an error message. Therefore, you need to capture this event in your code. One way to do this is shown below. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_Handler() subroutine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Private Sub myItem_Write(Cancel As Boolean)

 Dim myResult As Integer

 myItem = "The item is about to be saved. Do you wish to overwrite the existing item?"

 myResult = MsgBox(myItem, vbYesNo, "Save")

 If myResult = vbNo Then

 Cancel = True

 End If

End Sub

Public Sub Initalize_Handler()

 Const strCancelEvent = "Application-defined or object-defined error"

 On Error GoTo ErrHandler

 Set myItem = Application.ActiveInspector.CurrentItem

 myItem.Save

 Exit Sub

 ErrHandler:

 MsgBox Err.Description

 If Err.Description = strCancelEvent Then

 MsgBox "The event was cancelled."

 End If

End Sub

See also

Concepts

MailItem Object

Other resources

MailItem Object Members


MailModule Object (Outlook)

 Copy code hover
[image]

MailModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the Mail navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The MailModule object, derived from the NavigationModule object, provides read-only access to the navigation groups contained in the Mail navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the Modules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the navigation module type. If the NavigationModuleType property is set to olModuleMail, you can then cast the NavigationModule object reference as a MailModule object to access the NavigationGroups property for that navigation module.

Note Note

Unlike other navigation modules, such as the CalendarModule object, you cannot create or delete navigation groups in the MailModule object.

You can use the Visible property to determine if the navigation module is visible, and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Mail navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

MailModule Object Members


MailModule Members (Outlook)

 Copy code hover
[image]

MailModule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Mail navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the MailModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the MailModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the MailModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the MailModule object is displayed in the Navigation Pane. Read/write.


MailModule Properties (Outlook)

 Copy code hover
[image]

MailModule Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the MailModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the MailModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the MailModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the MailModule object is displayed in the Navigation Pane. Read/write.


MailModule.Application Property (Outlook)

 Copy code hover
[image]

MailModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Class Property (Outlook)

 Copy code hover
[image]

MailModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a MailModule object.

Remarks

This property returns olMailModule for the MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Name Property (Outlook)

 Copy code hover
[image]

MailModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the MailModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

MailModule.NavigationGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroups object that contains the set of navigation groups associated with the MailModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

MailModule.NavigationModuleType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a MailModule object.

Remarks

This property returns olModuleMail for the MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Parent Property (Outlook)

 Copy code hover
[image]

MailModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Position Property (Outlook)

 Copy code hover
[image]

MailModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the MailModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a MailModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a given MailModule object changes the Position values of other navigaton modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified MailModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified MailModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Session Property (Outlook)

 Copy code hover
[image]

MailModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a MailModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MailModule.Visible Property (Outlook)

 Copy code hover
[image]

MailModule.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the MailModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a MailModule object.

See also

Concepts

MailModule Object

Other resources

MailModule Object Members


MarkAsTaskRuleAction Object (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction Object (Outlook)
See also Send feedback

Represents an action that marks a message as a task.

Version Information

Version Added: Outlook 2007

Remarks

MarkAsTaskRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has a MarkAsTask property. The MarkAsTask property always returns a MarkAsTaskRuleAction object. If the rule has an enabled rule action that marks a message as a task, then MarkAsTaskRuleAction.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction Members (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an action that marks a message as a task.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionMarkAsTask, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
FlagTo | Returns or sets a String that represents the label of the flag for the message. Read/write
MarkInterval | Returns or sets a constant in the OlMarkInterval enumeration that represents the interval before the task is due. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


MarkAsTaskRuleAction Properties (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionMarkAsTask, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
FlagTo | Returns or sets a String that represents the label of the flag for the message. Read/write
MarkInterval | Returns or sets a constant in the OlMarkInterval enumeration that represents the interval before the task is due. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


MarkAsTaskRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.ActionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olRuleActionMarkAsTask, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a MarkAsTaskRuleAction object.

Remarks

The task marking rule action is supported only by rules for receiving messages. For more information, see Specify Rule Actions.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.Application Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a MarkAsTaskRuleAction object.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.Class Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a MarkAsTaskRuleAction object.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a MarkAsTaskRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.FlagTo Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.FlagTo Property (Outlook)
See also Send feedback

Returns or sets a String that represents the label of the flag for the message. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .FlagTo

expression A variable that represents a MarkAsTaskRuleAction object.

Remarks

Returns an error if FlagTo is an empty string.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.MarkInterval Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.MarkInterval Property (Outlook)
See also Send feedback

Returns or sets a constant in the OlMarkInterval enumeration that represents the interval before the task is due. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkInterval

expression A variable that represents a MarkAsTaskRuleAction object.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a MarkAsTaskRuleAction object.

Remarks

The parent object is the RuleAction object.

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MarkAsTaskRuleAction.Session Property (Outlook)

 Copy code hover
[image]

MarkAsTaskRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a MarkAsTaskRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

MarkAsTaskRuleAction Object

Other resources

MarkAsTaskRuleAction Object Members


MeetingItem Object (Outlook)

 Copy code hover
[image]

MeetingItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a change to the recipient's Calendar folder initiated by another party or as a result of a group action.

Remarks

Unlike other Microsoft Outlook objects, you cannot create this object. It is created automatically when you set the MeetingStatus property of an AppointmentItem object to olMeeting and send it to one or more users. They receive it in their inboxes as a MeetingItem.

Use the GetAssociatedAppointment method to return the AppointmentItem object associated with a MeetingItem object, and work directly with the AppointmentItem object to respond to the request.

Example

The following example uses the CreateItem method to create an appointment. It becomes a MeetingItem with both a required and an optional attendee when it is received in the inbox of each of the recipients.

VBA Copy code Copy code
Set myItem = myOlApp.CreateItem(olAppointmentItem)

myItem.MeetingStatus = olMeeting

myItem.Subject = "Strategy Meeting"

myItem.Location = "Conference Room B"

myItem.Start = #9/24/97 1:30:00 PM#

myItem.Duration = 90

Set myRequiredAttendee = myItem.Recipients.Add("Nate _

 Sun")

myRequiredAttendee.Type = olRequired

Set myOptionalAttendee = myItem.Recipients.Add("Kevin _

 Kennedy")

myOptionalAttendee.Type = olOptional

Set myResourceAttendee = _

 myItem.Recipients.Add("Conference Room B")

myResourceAttendee.Type = olResource

myItem.Send

See also

Concepts

Outlook Object Model Reference

Other resources

MeetingItem Object Members


MeetingItem Members (Outlook)

 Copy code hover
[image]

MeetingItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a change to the recipient's Calendar folder initiated by another party or as a result of a group action.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MeetingItem object.
GetAssociatedAppointment | Returns an AppointmentItem object that represents the appointment associated with the meeting request.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the meeting item.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoForwarded | A Boolean value that returns True if the item was automatically forwarded. Read/write.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the MeetingItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsLatestVersion | Returns a Boolean value that indicates whether the MeetingItem represents the latest version of the item on the organizer's calendar. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MeetingWorkspaceURL | Returns a String value that represents the URL for the Meeting Workspace that the meeting item is linked to. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MeetingItem object. Read-only.
ReceivedTime | Returns or sets a Date indicating the date and time at which the item was received. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the MeetingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account to use to send the MeetingItem. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Sent | Returns a Boolean value that indicates if a message has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Submitted | Returns a Boolean value that is True if the item has been submitted. Read-only.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


MeetingItem Properties (Outlook)

 Copy code hover
[image]

MeetingItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoForwarded | A Boolean value that returns True if the item was automatically forwarded. Read/write.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the MeetingItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsLatestVersion | Returns a Boolean value that indicates whether the MeetingItem represents the latest version of the item on the organizer's calendar. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MeetingWorkspaceURL | Returns a String value that represents the URL for the Meeting Workspace that the meeting item is linked to. Read-only.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MeetingItem object. Read-only.
ReceivedTime | Returns or sets a Date indicating the date and time at which the item was received. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the MeetingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account to use to send the MeetingItem. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Sent | Returns a Boolean value that indicates if a message has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
Submitted | Returns a Boolean value that is True if the item has been submitted. Read-only.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


MeetingItem.Actions Property (Outlook)

 Copy code hover
[image]

MeetingItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Application Property (Outlook)

 Copy code hover
[image]

MeetingItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Attachments Property (Outlook)

 Copy code hover
[image]

MeetingItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.AutoForwarded Property (Outlook)

 Copy code hover
[image]

MeetingItem.AutoForwarded Property (Outlook)
See also Send feedback

Published: July 16, 2012

A Boolean value that returns True if the item was automatically forwarded. Read/write.

Syntax

expression .AutoForwarded

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

MeetingItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a MeetingItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its MeetingItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

MeetingItem.BillingInformation Property (Outlook)
See also Send feedback

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a MeetingItem object.

Remarks

This is a free-form text field.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Body Property (Outlook)

 Copy code hover
[image]

MeetingItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Categories Property (Outlook)

 Copy code hover
[image]

MeetingItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a MeetingItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Class Property (Outlook)

 Copy code hover
[image]

MeetingItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Companies Property (Outlook)

 Copy code hover
[image]

MeetingItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a MeetingItem object.

Remarks

This is a free-form text field.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Conflicts Property (Outlook)

 Copy code hover
[image]

MeetingItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ConversationID Property (Outlook)

 Copy code hover
[image]

MeetingItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the MeetingItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a MeetingItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the MeetingItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

MeetingItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

MeetingItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.CreationTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.DeferredDeliveryTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.DeferredDeliveryTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time the mail message is to be delivered. Read/write.

Syntax

expression .DeferredDeliveryTime

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagDeferredDeliveryTime.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.DeleteAfterSubmit Property (Outlook)

 Copy code hover
[image]

MeetingItem.DeleteAfterSubmit Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if a copy of the mail message is not saved upon being sent, and False if a copy is saved. Read/write.

Syntax

expression .DeleteAfterSubmit

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.DownloadState Property (Outlook)

 Copy code hover
[image]

MeetingItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a MeetingItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.EntryID Property (Outlook)

 Copy code hover
[image]

MeetingItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ExpiryTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.ExpiryTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.

Syntax

expression .ExpiryTime

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.FormDescription Property (Outlook)

 Copy code hover
[image]

MeetingItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.GetInspector Property (Outlook)

 Copy code hover
[image]

MeetingItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a MeetingItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Importance Property (Outlook)

 Copy code hover
[image]

MeetingItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.IsConflict Property (Outlook)

 Copy code hover
[image]

MeetingItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a MeetingItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.IsLatestVersion Property (Outlook)

 Copy code hover
[image]

MeetingItem.IsLatestVersion Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the MeetingItem represents the latest version of the item on the organizer's calendar. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .IsLatestVersion

expression A variable that represents a MeetingItem object.

Remarks

This property applies to all MeetingItem objects including meeting requests, meeting updates, and meeting cancellation.

True indicates that the latest version of the meeting item is on the organizer's calendar; False indicates that the meeting item on the calendar is not the latest version, or that there is a conflict between the meeting request and another appointment item on the calendar.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

MeetingItem.ItemProperties Property (Outlook)
See also Send feedback

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a MeetingItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

MeetingItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a MeetingItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.MeetingWorkspaceURL Property (Outlook)

 Copy code hover
[image]

MeetingItem.MeetingWorkspaceURL Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the URL for the Meeting Workspace that the meeting item is linked to. Read-only.

Syntax

expression .MeetingWorkspaceURL

expression A variable that represents a MeetingItem object.

Remarks

A Meeting Workspace is a shared Web site for planning the meeting and tracking the results.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.MessageClass Property (Outlook)

 Copy code hover
[image]

MeetingItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

MeetingItem Object
Item Types and Message Classes

Other resources

MeetingItem Object Members


MeetingItem.Mileage Property (Outlook)

 Copy code hover
[image]

MeetingItem.Mileage Property (Outlook)
See also Send feedback

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a MeetingItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.NoAging Property (Outlook)

 Copy code hover
[image]

MeetingItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.OriginatorDeliveryReportRequested Property (Outlook)

 Copy code hover
[image]

MeetingItem.OriginatorDeliveryReportRequested Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the originator of the meeting item or mail message will receive a delivery report. Read/write.

Syntax

expression .OriginatorDeliveryReportRequested

expression A variable that represents a MeetingItem object.

Remarks

Each transport provider that handles your message sends you a single delivery notification containing the names and addresses of each recipient to whom it was delivered. Delivery does not imply that the message has been read. True if the originator requested a delivery receipt on the message.

The OriginatorDeliveryReportRequested property corresponds to the MAPI property PidTagOriginatorDeliveryReportRequested.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

MeetingItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

MeetingItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Parent Property (Outlook)

 Copy code hover
[image]

MeetingItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

MeetingItem.PropertyAccessor Property (Outlook)
See also Send feedback

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent MeetingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReceivedTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.ReceivedTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the item was received. Read/write.

Syntax

expression .ReceivedTime

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Recipients Property (Outlook)

 Copy code hover
[image]

MeetingItem.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.

Syntax

expression .Recipients

expression A variable that represents a MeetingItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

MeetingItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

MeetingItem.ReminderTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReplyRecipients Property (Outlook)

 Copy code hover
[image]

MeetingItem.ReplyRecipients Property (Outlook)
See also Send feedback

Returns a Recipients collection that represents all the reply recipient objects for the Outlook item. Read-only.

Syntax

expression .ReplyRecipients

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.RetentionExpirationDate Property (Outlook)

 Copy code hover
[image]

MeetingItem.RetentionExpirationDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that specifies the date when the MeetingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionExpirationDate

expression A variable that represents a MeetingItem object.

Remarks

A retention policy is enabled and disabled by an administrator for an Exchange Server on a mailbox level. This feature is available only on an Exchange mailbox with MRM version 2.0 or later enabled.

Microsoft Outlook calculates the value of this property based on the item retention start date and the retention period, if Outlook is in cache or offline mode. The Exchange Server specifies the value if Outlook is in online mode.

In general, the retention start date for the item is determined as follows:

  • Received or sent items: the retention start date is the received date.

  • Nonrecurring calendar items: the retention start date is the appointment end date.

  • Recurring calendar items: the retention start date is the end date of last recurrence. If there is no end date, the item never expires.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.RetentionPolicyName Property (Outlook)

 Copy code hover
[image]

MeetingItem.RetentionPolicyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that specifies the name of the retention policy. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionPolicyName

expression A variable that represents a MeetingItem object.

Remarks

Retention is enabled and disabled by an administrator for an Exchange Server on a mailbox level. The feature is available only on an Exchange mailbox with Messaging Records Management (MRM), version 2.0 or later enabled. An example of a retention policy name is "Define time interval for expiration Quick Searches".

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.RTFBody Property (Outlook)

 Copy code hover
[image]

MeetingItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a MeetingItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Saved Property (Outlook)

 Copy code hover
[image]

MeetingItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SaveSentMessageFolder Property (Outlook)

 Copy code hover
[image]

MeetingItem.SaveSentMessageFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Folder object that represents the folder in which a copy of the e-mail message will be saved after being sent. Read/write.

Syntax

expression .SaveSentMessageFolder

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SenderEmailAddress Property (Outlook)

 Copy code hover
[image]

MeetingItem.SenderEmailAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.

Syntax

expression .SenderEmailAddress

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderEmailAddress.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SenderEmailType Property (Outlook)

 Copy code hover
[image]

MeetingItem.SenderEmailType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.

Syntax

expression .SenderEmailType

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SenderName Property (Outlook)

 Copy code hover
[image]

MeetingItem.SenderName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the display name of the sender for the Outlook item. Read-only.

Syntax

expression .SenderName

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderName.

If you wish to retrieve the fully qualified e-mail address of the sender, use the SenderEmailAddress property.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SendUsingAccount Property (Outlook)

 Copy code hover
[image]

MeetingItem.SendUsingAccount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an Account object that represents the account to use to send the MeetingItem. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .SendUsingAccount

expression A variable that represents a MeetingItem object.

Remarks

You can use the SendUsingAccount property to specify the account that the Send method uses to send the MeetingItem. This property returns Null (Nothing in Visual Basic) if the account specified for the MeetingItem no longer exists.

This property is read-only if the MeetingItem is a received item, or if the MeetingItem has already been sent (that is, the Sent property of the object is set to True).

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

MeetingItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Sent Property (Outlook)

 Copy code hover
[image]

MeetingItem.Sent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates if a message has been sent. Read-only.

Syntax

expression .Sent

expression A variable that represents a MeetingItem object.

Remarks

In general, there are three different kinds of messages: sent, posted, and saved. Sent messages are items sent to a recipient or public folder. Posted messages are created in a public folder. Saved messages are created and saved without either sending or posting.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SentOn Property (Outlook)

 Copy code hover
[image]

MeetingItem.SentOn Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.

Syntax

expression .SentOn

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagClientSubmitTime. When you send a meeting request item using the object's Send method, the transport provider sets the ReceivedTime and SentOn properties for you.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Session Property (Outlook)

 Copy code hover
[image]

MeetingItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a MeetingItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Size Property (Outlook)

 Copy code hover
[image]

MeetingItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Subject Property (Outlook)

 Copy code hover
[image]

MeetingItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a MeetingItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Submitted Property (Outlook)

 Copy code hover
[image]

MeetingItem.Submitted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the item has been submitted. Read-only.

Syntax

expression .Submitted

expression A variable that represents a MeetingItem object.

Remarks

A message is always created and submitted in a folder, usually the Outbox.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.UnRead Property (Outlook)

 Copy code hover
[image]

MeetingItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.UserProperties Property (Outlook)

 Copy code hover
[image]

MeetingItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem Methods (Outlook)

 Copy code hover
[image]

MeetingItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MeetingItem object.
GetAssociatedAppointment | Returns an AppointmentItem object that represents the appointment associated with the meeting request.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
ReplyAll | Creates a reply to all original recipients from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the meeting item.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


MeetingItem.Close Method (Outlook)

 Copy code hover
[image]

MeetingItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Copy Method (Outlook)

 Copy code hover
[image]

MeetingItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Delete Method (Outlook)

 Copy code hover
[image]

MeetingItem.Delete Method (Outlook)
See also Send feedback

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a MeetingItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

MeetingItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

MeetingItem Object Members


MeetingItem.Display Method (Outlook)

 Copy code hover
[image]

MeetingItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Forward Method (Outlook)

 Copy code hover
[image]

MeetingItem.Forward Method (Outlook)
See also Send feedback

Published: July 16, 2012

Executes the Forward action for an item and returns the resulting copy as a MeetingItem object.

Syntax

expression .Forward

expression A variable that represents a MeetingItem object.

Return Value

A MeetingItem object that represents the new meeting item.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.GetAssociatedAppointment Method (Outlook)

 Copy code hover
[image]

MeetingItem.GetAssociatedAppointment Method (Outlook)
See also Send feedback

Returns an AppointmentItem object that represents the appointment associated with the meeting request.

Syntax

expression .GetAssociatedAppointment(AddToCalendar)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
AddToCalendar | Required | Boolean | True to add the meeting to the default Calendar folder.

Return Value

An AppointmentItem object that represents the associated appointment.

Example

This Visual Basic for Applications (VBA) example finds a MeetingItem in the default Inbox folder that has not been responded to yet and adds the associated appointment to the Calendar folder. It then responds to the sender by accepting the meeting.

VBA Copy code Copy code
Sub AcceptMeeting()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myMtgReq As Outlook.MeetingItem

 Dim myAppt As Outlook.AppointmentItem

 Dim myMtg As Outlook.MeetingItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myMtgReq = myFolder.Items.Find("[MessageClass] = 'IPM.Schedule.Meeting.Request'")

 If TypeName(myMtgReq) <> "Nothing" Then

 Set myAppt = myMtgReq.GetAssociatedAppointment(True)

 Set myMtg = myAppt.Respond(olResponseAccepted, True)

 myMtg.Send

 End If

End Sub

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.GetConversation Method (Outlook)

 Copy code hover
[image]

MeetingItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a MeetingItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Move Method (Outlook)

 Copy code hover
[image]

MeetingItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.PrintOut Method (Outlook)

 Copy code hover
[image]

MeetingItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Reply Method (Outlook)

 Copy code hover
[image]

MeetingItem.Reply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a reply, pre-addressed to the original sender, from the original message.

Syntax

expression .Reply

expression A variable that represents a MeetingItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReplyAll Method (Outlook)

 Copy code hover
[image]

MeetingItem.ReplyAll Method (Outlook)
See also Send feedback

Creates a reply to all original recipients from the original message.

Syntax

expression .ReplyAll

expression A variable that represents a MeetingItem object.

Return Value

A MailItem that represents the reply.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Save Method (Outlook)

 Copy code hover
[image]

MeetingItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.SaveAs Method (Outlook)

 Copy code hover
[image]

MeetingItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Send Method (Outlook)

 Copy code hover
[image]

MeetingItem.Send Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends the meeting item.

Syntax

expression .Send

expression A variable that represents a MeetingItem object.

Remarks

When you create a meeting request programmatically, you first create an AppointmentItem object instead of a MeetingItem object. To indicate the appointment is a meeting, set the MeetingStatus property of the AppointmentItem object to olMeeting. To send the meeting request, apply the Send method to that AppointmentItem object.

See also

Concepts

How to: Create an Appointment as a Meeting on the Calendar
MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

MeetingItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a MeetingItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem Events (Outlook)

 Copy code hover
[image]

MeetingItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


MeetingItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

MeetingItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a MeetingItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

MeetingItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

MeetingItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

MeetingItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the MeetingItem to be saved.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

MeetingItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a MeetingItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Close Event (Outlook)

 Copy code hover
[image]

MeetingItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.CustomAction Event (Outlook)

 Copy code hover
[image]

MeetingItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

MeetingItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Forward Event (Outlook)

 Copy code hover
[image]

MeetingItem.Forward Event (Outlook)
See also Send feedback

Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Open Event (Outlook)

 Copy code hover
[image]

MeetingItem.Open Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

MeetingItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Read Event (Outlook)

 Copy code hover
[image]

MeetingItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a MeetingItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

MeetingItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Reply Event (Outlook)

 Copy code hover
[image]

MeetingItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

MeetingItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Send Event (Outlook)

 Copy code hover
[image]

MeetingItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.

Syntax

expression .Send(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Unload Event (Outlook)

 Copy code hover
[image]

MeetingItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a MeetingItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MeetingItem.Write Event (Outlook)

 Copy code hover
[image]

MeetingItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a MeetingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

MeetingItem Object

Other resources

MeetingItem Object Members


MoveOrCopyRuleAction Object (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an action that moves or copies a message.

Version Information

Version Added: Outlook 2007

Remarks

MoveOrCopyRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has a CopyToFolder property and a MoveToFolder property. Each of these properties always returns a MoveOrCopyRuleAction object. MoveOrCopyRuleAction.ActionType distinguishes between the two action types. If the rule has an enabled rule action that copies or moves a message to the specified folder, then the corresponding MoveOrCopyRuleAction.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction Members (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an action that moves or copies a message.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionMoveToFolder, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Folder | Returns or sets a Folder object that represents the folder to which the rule moves or copies the message. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


MoveOrCopyRuleAction Properties (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionMoveToFolder, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Folder | Returns or sets a Folder object that represents the folder to which the rule moves or copies the message. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


MoveOrCopyRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.ActionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olRuleActionMoveToFolder, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a MoveOrCopyRuleAction object.

Remarks

The moving or copying rule action is supported only by rules for receiving messages. For more information, see Specify Rule Actions.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Application Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a MoveOrCopyRuleAction object.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Class Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a MoveOrCopyRuleAction object.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a MoveOrCopyRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Folder Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Folder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Folder object that represents the folder to which the rule moves or copies the message. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Folder

expression A variable that represents a MoveOrCopyRuleAction object.

Remarks

If no folder has been assigned to the move or copy rule action, this property is Null (Nothing in Visual Basic).

This property returns an error if the specified folder cannot serve as a target folder for the copy or move operation. For example, the folder is a search folder, is read-only, or the user does not have the required permissions to move or copy messages to it.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a MoveOrCopyRuleAction object.

Remarks

The parent object is the RuleAction object.

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


MoveOrCopyRuleAction.Session Property (Outlook)

 Copy code hover
[image]

MoveOrCopyRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a MoveOrCopyRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

MoveOrCopyRuleAction Object

Other resources

MoveOrCopyRuleAction Object Members


NameSpace Object (Outlook)

 Copy code hover
[image]

NameSpace Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an abstract root object for any data source.

Remarks

The object itself provides methods for logging in and out, accessing storage objects directly by ID, accessing certain special default folders directly, and accessing data sources owned by other users.

Use GetNameSpace ("MAPI") to return the Outlook NameSpace object from the Application object.

The only data source supported is MAPI, which allows access to all Outlook data stored in the user's mail stores.

See also

Concepts

How to: Obtain and Log On to an Instance of Outlook
Outlook Object Model Reference

Other resources

NameSpace Object Members


NameSpace Members (Outlook)

 Copy code hover
[image]

NameSpace Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an abstract root object for any data source.

Events

Name | Description
AutoDiscoverComplete | Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange server that hosts the primary Exchange account and has the related information available in NameSpace.AutoDiscoverXml.
OptionsPagesAdd | Occurs whenever the Properties dialog box for a folder is opened.

Methods

Name | Description
AddStore | Adds a Personal Folders (.pst) file to the current profile.
AddStoreEx | Adds a Personal Folders file (.pst) in the specified format to the current profile.
CompareEntryIDs | Returns a Boolean value that indicates if two entry ID values refer to the same Outlook item.
CreateContactCard | Creates an instance of a ContactCard object for the contact that is specified by the AddressEntry parameter.
CreateRecipient | Creates a Recipient object.
CreateSharingItem | Creates a new SharingItem object.
Dial | Displays the New Call dialog box that allows users to dial the primary phone number of a specified contact.
GetAddressEntryFromID | Returns an AddressEntry object that represents the address entry for the specified ID.
GetDefaultFolder | Returns a Folder object that represents the default folder of the requested type for the current profile, for example, obtains the default Calendar folder for the user who is currently logged on.
GetFolderFromID | Returns a Folder object identified by the specified entry ID (if valid).
GetGlobalAddressList | Returns an AddressList object that represents the Exchange Global Address List.
GetItemFromID | Returns a Microsoft Outlook item identified by the specified entry ID (if valid).
GetRecipientFromID | Returns the Recipient object that is identified by the specified entry ID (if valid).
GetSelectNamesDialog | Obtains a SelectNamesDialog object for the current session.
GetSharedDefaultFolder | Returns a Folder object that represents the specified default folder for the specified user.
GetStoreFromID | Returns a Store object that represents the store specified by ID.
Logoff | Logs the user off from the current MAPI session.
Logon | Logs the user on to MAPI, obtaining a MAPI session.
OpenSharedFolder | Opens a shared folder referenced through a URL or file name.
OpenSharedItem | Opens a shared item from a specified path or URL.
PickFolder | Displays the Pick Folder dialog box.
RemoveStore | Removes a Personal Folders file (.pst) from the current MAPI profile or session.
SendAndReceive | Initiates immediate delivery of all undelivered messages submitted in the current session, and immediate receipt of mail for all accounts in the current profile.

Properties

Name | Description
Accounts | Returns an Accounts collection object that represents all the Account objects in the current profile. Read-only.
AddressLists | Returns an AddressLists collection representing a collection of the address lists available for this session. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoDiscoverConnectionMode | Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection for auto-discovery of the Microsoft Exchange server that hosts the primary Exchange account. Read-only.
AutoDiscoverXml | Returns a String that represents information in XML retrieved from the auto-discovery service for the Microsoft Exchange server that hosts the primary Exchange account. Read-only.
Categories | Returns or sets a Categories object that represents the set of Category objects that are available to the namespace. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentProfileName | Returns a String representing the name of the current profile. Read-only.
CurrentUser | Returns the display name of the currently logged-on user as a Recipient object. Read-only.
DefaultStore | Returns a Store object representing the default Store for the profile. Read-only.
ExchangeConnectionMode | Returns an OlExchangeConnectionMode constant that indicates the connection mode of the user's primary Exchange account. Read-only.
ExchangeMailboxServerName | Returns a String value that represents the name of the Exchange server that hosts the primary Exchange account mailbox. Read-only.
ExchangeMailboxServerVersion | Returns a String value that represents the full version number of the Exchange server that hosts the primary Exchange account mailbox. Read-only.
Folders | Returns the Folders collection that represents all the folders contained in the specified NameSpace. Read-only.
Offline | Returns a Boolean indicating True if Outlook is offline (not connected to an Exchange server), and False if online (connected to an Exchange server). Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Stores | Returns a Stores collection object that represents all the Store objects in the current profile. Read-only.
SyncObjects | Returns a SyncObjects collection containing all Send\Receive groups. Read-only.
Type | Returns a String indicating the type of the specified object. Read-only.


NameSpace Properties (Outlook)

 Copy code hover
[image]

NameSpace Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Accounts | Returns an Accounts collection object that represents all the Account objects in the current profile. Read-only.
AddressLists | Returns an AddressLists collection representing a collection of the address lists available for this session. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoDiscoverConnectionMode | Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection for auto-discovery of the Microsoft Exchange server that hosts the primary Exchange account. Read-only.
AutoDiscoverXml | Returns a String that represents information in XML retrieved from the auto-discovery service for the Microsoft Exchange server that hosts the primary Exchange account. Read-only.
Categories | Returns or sets a Categories object that represents the set of Category objects that are available to the namespace. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentProfileName | Returns a String representing the name of the current profile. Read-only.
CurrentUser | Returns the display name of the currently logged-on user as a Recipient object. Read-only.
DefaultStore | Returns a Store object representing the default Store for the profile. Read-only.
ExchangeConnectionMode | Returns an OlExchangeConnectionMode constant that indicates the connection mode of the user's primary Exchange account. Read-only.
ExchangeMailboxServerName | Returns a String value that represents the name of the Exchange server that hosts the primary Exchange account mailbox. Read-only.
ExchangeMailboxServerVersion | Returns a String value that represents the full version number of the Exchange server that hosts the primary Exchange account mailbox. Read-only.
Folders | Returns the Folders collection that represents all the folders contained in the specified NameSpace. Read-only.
Offline | Returns a Boolean indicating True if Outlook is offline (not connected to an Exchange server), and False if online (connected to an Exchange server). Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Stores | Returns a Stores collection object that represents all the Store objects in the current profile. Read-only.
SyncObjects | Returns a SyncObjects collection containing all Send\Receive groups. Read-only.
Type | Returns a String indicating the type of the specified object. Read-only.


NameSpace.Accounts Property (Outlook)

 Copy code hover
[image]

NameSpace.Accounts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Accounts collection object that represents all the Account objects in the current profile. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Accounts

expression A variable that represents a NameSpace object.

Remarks

If Outlook is running in sessionless mode, Accounts returns an Accounts collection with Accounts.Count equal to 0.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.AddressLists Property (Outlook)

 Copy code hover
[image]

NameSpace.AddressLists Property (Outlook)
See also Send feedback

Returns an AddressLists collection representing a collection of the address lists available for this session. Read-only.

Syntax

expression .AddressLists

expression A variable that represents a NameSpace object.

Remarks

The AddressLists collection represents the root of the address book hierarchy for the current session. A particular AddressList object represents one of the available address books. The type of access you obtain depends on the access permissions granted to you by each individual address book provider.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Application Property (Outlook)

 Copy code hover
[image]

NameSpace.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.AutoDiscoverConnectionMode Property (Outlook)

 Copy code hover
[image]

NameSpace.AutoDiscoverConnectionMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlAutoDiscoverConnectionMode constant that specifies the type of connection for auto-discovery of the Microsoft Exchange server that hosts the primary Exchange account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoDiscoverConnectionMode

expression A variable that represents a NameSpace object.

Remarks

This property is similar to the AutoDiscoverConnectionMode property of the Account object. If there are multiple Exchange accounts defined in the current profile, use the AutoDiscoverConnectionMode property for the specific account.

Example

NameSpace.AutoDiscoverXml is an XML string that is returned from the auto-discovery service of the Exchange server. The following code sample uses the AutoDiscoverConnectionMode property to show when this XML string is available during a normal Outlook session.

  • When the Application.Startup event occurs, if AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown.

  • When the NameSpace.AutoDiscoverComplete event occurs, if AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown.

VBA Copy code Copy code
Dim WithEvents Session As NameSpace

Dim LastAutoDiscoverXml As String

Dim LastAutoDiscoverConnectionMode As OlAutoDiscoverConnectionMode

Private Sub Application_Startup()

 Set Session = Application.Session

 If (Session.AutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown) Then

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub Session_AutoDiscoverComplete()

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 If LastAutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown Then

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub DoAutoDiscoverBasedWork()

 ' Do activity requires auto discover information

 Dim displayName As String

 Dim posStartTag, posEndTag As Integer

 posStartTag = InStr(1, LastAutoDiscoverXml, "<DisplayName>")

 posEndTag = InStr(1, LastAutoDiscoverXml, "</DisplayName>")

 If (posStartTag > 1 And posEndTag > 1) Then

 displayName = Mid(LastAutoDiscoverXml, posStartTag + 13, posEndTag - posStartTag - 13)

 Debug.Print "DisplayName = " & displayName

 End If

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.AutoDiscoverXml Property (Outlook)

 Copy code hover
[image]

NameSpace.AutoDiscoverXml Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents information in XML retrieved from the auto-discovery service for the Microsoft Exchange server that hosts the primary Exchange account. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoDiscoverXml

expression A variable that represents a NameSpace object.

Remarks

This property is similar to the AutoDiscoverXml property of the Account object. If there are multiple Exchange accounts defined in the current profile, use the AutoDiscoverXml property for the specific account.

The returned string of XML contains information about various Web services (for example, availability service and unified messaging service) and available servers.

An error is returned if the active profile does not contain an account that is connected to a server that is Microsoft Exchange Server 2007 or later.

Example

NameSpace.AutoDiscoverXml is an XML string that is returned from the auto-discovery service of the Exchange server. The following code sample uses the AutoDiscoverConnectionMode property to show when this XML string is available during a normal Outlook session.

  • When the Application.Startup event occurs, if NameSpace.AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown.

  • When the NameSpace.AutoDiscoverComplete event occurs, if AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown.

VBA Copy code Copy code
Dim WithEvents Session As NameSpace

Dim LastAutoDiscoverXml As String

Dim LastAutoDiscoverConnectionMode As OlAutoDiscoverConnectionMode

Private Sub Application_Startup()

 Set Session = Application.Session

 If (Session.AutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown) Then

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub Session_AutoDiscoverComplete()

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 If LastAutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown Then

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub DoAutoDiscoverBasedWork()

 ' Do activity requires auto discover information

 Dim displayName As String

 Dim posStartTag, posEndTag As Integer

 posStartTag = InStr(1, LastAutoDiscoverXml, "<DisplayName>")

 posEndTag = InStr(1, LastAutoDiscoverXml, "</DisplayName>")

 If (posStartTag > 1 And posEndTag > 1) Then

 displayName = Mid(LastAutoDiscoverXml, posStartTag + 13, posEndTag - posStartTag - 13)

 Debug.Print "DisplayName = " & displayName

 End If

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Categories Property (Outlook)

 Copy code hover
[image]

NameSpace.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Categories object that represents the set of Category objects that are available to the namespace. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Categories

expression A variable that represents a NameSpace object.

Remarks

This property represents the Master Category List, which is the set of Category objects that can be applied to Outlook items contained by the NameSpace object, and applies to all users of that namespace.

This property is similar to the Categories property of the Store object. If there are multiple accounts defined in the current profile, use the Categories property of the store that is associated with the specific account.

Example

The following Visual Basic for Applications (VBA) example displays a dialog box that contains the names and identifiers for each Category object that is contained in the Categories collection associated with the default NameSpace object.

VBA Copy code Copy code
Private Sub ListCategoryIDs()

 Dim objNameSpace As NameSpace

 Dim objCategory As Category

 Dim strOutput As String

 ' Obtain a NameSpace object reference.

 Set objNameSpace = Application.GetNamespace("MAPI")

 ' Check whether the Categories collection for the Namespace

 ' contains one or more Category objects.

 If objNameSpace.Categories.Count > 0 Then

 ' Enumerate the Categories collection.

 For Each objCategory In objNameSpace.Categories

 ' Add the name and ID of the Category object to

 ' the output string.

 strOutput = strOutput & objCategory.Name & _

 ": " & objCategory.CategoryID & vbCrLf

 Next

 End If

 ' Display the output string.

 MsgBox strOutput

 ' Clean up.

 Set objCategory = Nothing

 Set objNameSpace = Nothing

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Class Property (Outlook)

 Copy code hover
[image]

NameSpace.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CurrentProfileName Property (Outlook)

 Copy code hover
[image]

NameSpace.CurrentProfileName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the name of the current profile. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CurrentProfileName

expression A variable that represents a NameSpace object.

Remarks

You assign a profile name when you create a profile.

CurrentProfileName maps to the MAPI property PidTagProfileName.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CurrentUser Property (Outlook)

 Copy code hover
[image]

NameSpace.CurrentUser Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the display name of the currently logged-on user as a Recipient object. Read-only.

Syntax

expression .CurrentUser

expression A variable that represents a NameSpace object.

Example

This Visual Basic for Applications (VBA) example uses the CurrentUser property to obtain the name of the currently logged-on user and then displays a message box containing the name.

VBA Copy code Copy code
Sub DisplayCurrentUser()

 Dim myNamespace As Outlook.NameSpace

 Set myNameSpace = Application.GetNameSpace("MAPI")

 MsgBox myNameSpace.CurrentUser

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.DefaultStore Property (Outlook)

 Copy code hover
[image]

NameSpace.DefaultStore Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Store object representing the default Store for the profile. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultStore

expression A variable that represents a NameSpace object.

Remarks

Returns an error if there is no default store for the current profile.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.ExchangeConnectionMode Property (Outlook)

 Copy code hover
[image]

NameSpace.ExchangeConnectionMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlExchangeConnectionMode constant that indicates the connection mode of the user's primary Exchange account. Read-only.

Syntax

expression .ExchangeConnectionMode

expression A variable that represents a NameSpace object.

Remarks

If the ExchangeConnectionMode property is olOffline or olDisconnected, the NameSpace.Offline property returns True . If the ExchangeConnectionMode property is olOnline, olConnected, or olConnectedHeaders, the NameSpace.Offline property returns False.

Example

The following Microsoft Visual Basic for Applications (VBA) example marks the items that are sent with high importance for download if the connection mode is 'Connected Headers' and the download state is 'Header Only' in the Inbox folder.

VBA Copy code Copy code
Sub MarkHighImportance()

 Dim myNamespace As Outlook.NameSpace

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim ctr As Integer

 Dim i As Integer

 Set myNamespace = Application.GetNamespace("MAPI")

 Set mpfInbox = myNamespace.GetDefaultFolder(olFolderInbox)

 ctr = mpfInbox.Items.count

 If (myNamespace.ExchangeConnectionMode = olConnectedHeaders) Then

 For i = 1 To ctr

 Set obj = mpfInbox.Items.Item(i)

 If (obj.Importance <> olImportanceHigh And obj.DownloadState = olHeaderOnly) Then

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

 End If

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.ExchangeMailboxServerName Property (Outlook)

 Copy code hover
[image]

NameSpace.ExchangeMailboxServerName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the name of the Exchange server that hosts the primary Exchange account mailbox. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ExchangeMailboxServerName

expression An expression that returns a NameSpace object.

Remarks

If an Exchange mailbox is not present in the namespace, this property returns an empty string.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.ExchangeMailboxServerVersion Property (Outlook)

 Copy code hover
[image]

NameSpace.ExchangeMailboxServerVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the full version number of the Exchange server that hosts the primary Exchange account mailbox. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ExchangeMailboxServerVersion

expression An expression that returns a NameSpace object.

Remarks

This property returns a string that contains the version number of the Exchange server for the active mailbox. The version number has the following four parts.

Copy code Copy code
<major version>.<minor version>.<build number>.<revision>

Not all parts may be present in the version number, depending on the version information that is supplied by the Microsoft Exchange Server. For example, this property returns "6.5.7638" for Microsoft Exchange Server 2003 Service Pack 2.

If an Exchange mailbox is not present in the namespace, this property returns an empty string.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Folders Property (Outlook)

 Copy code hover
[image]

NameSpace.Folders Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Folders collection that represents all the folders contained in the specified NameSpace. Read-only.

Syntax

expression .Folders

expression A variable that represents a NameSpace object.

Remarks

The NameSpace object is the root of all the folders for the given name space.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Offline Property (Outlook)

 Copy code hover
[image]

NameSpace.Offline Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean indicating True if Outlook is offline (not connected to an Exchange server), and False if online (connected to an Exchange server). Read-only.

Syntax

expression .Offline

expression A variable that represents a NameSpace object.

Remarks

The Offline property returns valid information only for an Exchange profile. It is not intended for non-Exchange account types such as POP3, IMAPI, and HTTP.

If the NameSpace.ExchangeConnectionMode property is olOffline or olDisconnected, the Offline property will return True. If the ExchangeConnectionMode property is olOnline, olConnected, or olConnectedHeaders, the Offline property will return False.

Example

The following Microsoft Visual Basic for Applications (VBA) example returns True or False depending on whether the NameSpace object is currently online.

VBA Copy code Copy code
Sub Off()

 'Determines whether Outlook is currently offline.

 Dim nmsName As Outlook.NameSpace

 Set nmsName = Application.GetNamespace("MAPI")

 MsgBox nmsName.Offline

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Parent Property (Outlook)

 Copy code hover
[image]

NameSpace.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Session Property (Outlook)

 Copy code hover
[image]

NameSpace.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a NameSpace object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Stores Property (Outlook)

 Copy code hover
[image]

NameSpace.Stores Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Stores collection object that represents all the Store objects in the current profile. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Stores

expression A variable that represents a NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.SyncObjects Property (Outlook)

 Copy code hover
[image]

NameSpace.SyncObjects Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SyncObjects collection containing all Send\Receive groups. Read-only.

Syntax

expression .SyncObjects

expression A variable that represents a NameSpace object.

Example

This Microsoft Visual Basic for Applications (VBA) example displays all the Send and Receive groups set up for the user and starts the synchronization based on the user's response.

VBA Copy code Copy code
Public Sub Sync()

 Dim nsp As Outlook.NameSpace

 Dim sycs As Outlook.SyncObjects

 Dim syc As Outlook.SyncObject

 Dim i As Integer

 Dim strPrompt As Integer

 Set nsp = Application.GetNamespace("MAPI")

 Set sycs = nsp.SyncObjects

 For i = 1 To sycs.Count

 Set syc = sycs.Item(i)

 strPrompt = MsgBox("Do you wish to synchronize " & syc.Name &"?", vbYesNo)

 If strPrompt = vbYes Then

 syc.Start

 End If

 Next

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Type Property (Outlook)

 Copy code hover
[image]

NameSpace.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the type of the specified object. Read-only.

Syntax

expression .Type

expression A variable that represents a NameSpace object.

Remarks

The only supported string is "MAPI."

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace Methods (Outlook)

 Copy code hover
[image]

NameSpace Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddStore | Adds a Personal Folders (.pst) file to the current profile.
AddStoreEx | Adds a Personal Folders file (.pst) in the specified format to the current profile.
CompareEntryIDs | Returns a Boolean value that indicates if two entry ID values refer to the same Outlook item.
CreateContactCard | Creates an instance of a ContactCard object for the contact that is specified by the AddressEntry parameter.
CreateRecipient | Creates a Recipient object.
CreateSharingItem | Creates a new SharingItem object.
Dial | Displays the New Call dialog box that allows users to dial the primary phone number of a specified contact.
GetAddressEntryFromID | Returns an AddressEntry object that represents the address entry for the specified ID.
GetDefaultFolder | Returns a Folder object that represents the default folder of the requested type for the current profile, for example, obtains the default Calendar folder for the user who is currently logged on.
GetFolderFromID | Returns a Folder object identified by the specified entry ID (if valid).
GetGlobalAddressList | Returns an AddressList object that represents the Exchange Global Address List.
GetItemFromID | Returns a Microsoft Outlook item identified by the specified entry ID (if valid).
GetRecipientFromID | Returns the Recipient object that is identified by the specified entry ID (if valid).
GetSelectNamesDialog | Obtains a SelectNamesDialog object for the current session.
GetSharedDefaultFolder | Returns a Folder object that represents the specified default folder for the specified user.
GetStoreFromID | Returns a Store object that represents the store specified by ID.
Logoff | Logs the user off from the current MAPI session.
Logon | Logs the user on to MAPI, obtaining a MAPI session.
OpenSharedFolder | Opens a shared folder referenced through a URL or file name.
OpenSharedItem | Opens a shared item from a specified path or URL.
PickFolder | Displays the Pick Folder dialog box.
RemoveStore | Removes a Personal Folders file (.pst) from the current MAPI profile or session.
SendAndReceive | Initiates immediate delivery of all undelivered messages submitted in the current session, and immediate receipt of mail for all accounts in the current profile.


NameSpace.AddStore Method (Outlook)

 Copy code hover
[image]

NameSpace.AddStore Method (Outlook)
See also Send feedback

Adds a Personal Folders (.pst) file to the current profile.

Syntax

expression .AddStore(Store)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Variant | The path of the .pst file to be added to the profile. If the .pst file does not exist, Microsoft Outlook creates it.

Remarks

Use the RemoveStore method to remove a .pst that is already added to a profile.

Example

This Microsoft Visual Basic for Applications (VBA) example adds a new Personal Folders (.pst) file to the user's profile.

VBA Copy code Copy code
Sub CreatePST()

 Dim myNameSpace As Outlook.NameSpace

 Set myNameSpace = Application.GetNamespace("MAPI")

 myNameSpace.AddStore "c:\" & myNameSpace.CurrentUser & "\.pst"

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.AddStoreEx Method (Outlook)

 Copy code hover
[image]

NameSpace.AddStoreEx Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a Personal Folders file (.pst) in the specified format to the current profile.

Syntax

expression .AddStoreEx(Store, Type)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Variant | The path of the .pst file to be added to the profile. If the .pst file does not exist, Microsoft Outlook creates it.
Type | Required | OlStoreType | The format in which the data file should be created.

Remarks

Use the olStoreUnicode constant to add a new .pst file that has greater storage capacity for items and folders and supports multilingual Unicode data, to the user's profile. The olStoreANSI constant allows you to create .pst files that do not provide full support for multilingual Unicode data, but are compatible with earlier versions of Outlook. The olStoreDefault constant helps you create a .pst file in the default format that is compatible with the mailbox mode in which Outlook runs on the Microsoft Exchange Server.

Example

This Microsoft Visual Basic for Applications (VBA) example adds a new Personal Folders (.pst) file that has greater storage capacity for items and folders and supports Unicode to the user's profile.

VBA Copy code Copy code
Sub CreateUnicodePST()

 Dim myNameSpace As Outlook.NameSpace

 Set myNameSpace = Application.GetNamespace("MAPI")

 myNameSpace.AddStoreEx "c:\" & myNameSpace.CurrentUser & "\.pst",olStoreUnicode

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CompareEntryIDs Method (Outlook)

 Copy code hover
[image]

NameSpace.CompareEntryIDs Method (Outlook)
See also Send feedback

Returns a Boolean value that indicates if two entry ID values refer to the same Outlook item.

Version Information

Version Added: Outlook 2007

Syntax

expression .CompareEntryIDs(FirstEntryID, SecondEntryID)

expression An expression that returns a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
FirstEntryID | Required | String | The first entry ID to be compared.
SecondEntryID | Required | String | The second entry ID to be compared.

Return Value

True if the entry ID values refer to the same Outlook item; otherwise, False.

Remarks

Entry identifiers cannot be compared directly because one object can be represented by two different binary values. Use this method to determine whether two entry identifiers represent the same object.

Example

The following Visual Basic for Applications (VBA) example compares the entry identifier associated with the organizer of a specified AppointmentItem object with the entry identifier of a specified Recipient object, using the CompareEntryIDs method, and returns True if the organizer and the specified recipient represent the same user.

VBA Copy code Copy code
Function IsRecipientTheOrganizer( _

 ByVal Appt As Outlook.AppointmentItem, _

 ByVal Recipient As Outlook.Recipient) As Boolean

 Dim objAddrEntry As Outlook.AddressEntry

 Dim objPropAc As Outlook.PropertyAccessor

 Dim strOrganizerEntryId As String

 Dim bytResult() As Byte

 Dim objRecipientUser As Outlook.ExchangeUser

 Dim objOrganizerUser As Outlook.ExchangeUser

 Dim blnReturn As Boolean

 'Property tag for Organizer EntryID

 Const PR_SENT_REPRESENTING_ENTRYID As String = _

 "http://schemas.microsoft.com/mapi/proptag/0x00410102"

 ' Retrieve an AddressEntry object reference for the

 ' specified recipient.

 Set objAddrEntry = Recipient.AddressEntry

 ' If the address entry represents an Exchange user

 ' or Exchange remote user, retrieve an

 ' ExchangeUser object reference for the sender and

 ' compare the EntryID value of that object with

 ' the EntryID of the specified recipient.

 If objAddrEntry.AddressEntryUserType = _

 OlAddressEntryUserType.olExchangeUserAddressEntry _

 Or objAddrEntry.AddressEntryUserType = _

 OlAddressEntryUserType.olExchangeRemoteUserAddressEntry Then

 ' Attempt to retrieve an ExchangeUser

 ' object reference for the specified

 ' recipient.

 Set objRecipientUser = objAddrEntry.GetExchangeUser()

 If objRecipientUser Is Nothing Then

 ' An Exchange user could not be retrieved

 ' for the specified recipient.

 blnReturn = False

 Else

 ' Retrieve the EntryID property value of the organizer.

 ' The Organizer property of the AppointmentItem object only

 ' contains a string representation of the name of the

 ' organizer, so the PR_SENT_REPRESENTING_ENTRYID property value

 ' is instead retrieved, using the PropertyAccessor object

 ' associated with the appointment item.

 Set objPropAc = Appt.PropertyAccessor

 bytResult = objPropAc.GetProperty( _

 PR_SENT_REPRESENTING_ENTRYID)

 If Not IsEmpty(bytResult) Then

 ' Convert the binary value retrieved from the

 ' PR_SENT_REPRESENTING_ENTRYID property into

 ' a string value for comparison.

 strOrganizerEntryId = _

 objPropAc.BinaryToString(bytResult)

 ' Attempt to retrieve an ExchangeUser

 ' object reference for the organizer.

 Set objOrganizerUser = Appt.Application.Session. _

 GetAddressEntryFromID(strOrganizerEntryId).GetExchangeUser()

 If objOrganizerUser Is Nothing Then

 ' An Exchange user could not be retrieved

 ' for the organizer.

 blnReturn = False

 Else

 ' Compare the EntryIDs of the organizer

 ' and the specified recipient.

 blnReturn = Appt.Application.Session. _

 CompareEntryIDs( _

 objRecipientUser.ID, _

 objOrganizerUser.ID)

 End If

 End If

 End If

 End If

EndRoutine:

 ' Clean up

 Set objOrganizerUser = Nothing

 Set objRecipientUser = Nothing

 Set objAddrEntry = Nothing

 Set objPropAc = Nothing

 ' Return the results.

 IsRecipientTheOrganizer = blnReturn

 Exit Function

ErrRoutine:

 Debug.Print Err.Number & " - " & Err.Description, _

 vbOKOnly Or vbCritical, _

 "IsRecipientTheOrganizer"

 GoTo EndRoutine

End Function

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CreateContactCard Method (Outlook)

 Copy code hover
[image]

NameSpace.CreateContactCard Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates an instance of a ContactCard object for the contact that is specified by the AddressEntry parameter.

Version Information

Version Added: Outlook 2010

Syntax

expression .CreateContactCard(Address)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
AddressEntry | Required | AddressEntry | The AddressEntry object that represents the user for whom the contact card is to be created.

Return Value

The Office.ContactCard object that is created for the specified user.

Remarks

The ContactCard object is available in the type library of Microsoft Office. Before calling CreateContactCard to create a contact card in Microsoft Outlook, Outlook must be logged into an Outlook session.

The AddressEntry parameter is an AddressEntry object that represents one of the following AddressEntry types defined in the OlAddressEntryUserType enumeration:

  • olExchangeDistributionListAddressEntry

  • olExchangeRemoteUserAddressEntry

  • olExchangeUserAddressEntry

  • olOutlookContactAddressEntry

  • olSmtpAddressEntry

Outlook raises the E_INVALIDARG error when you pass any of the following OlAddressEntryUserType values as an argument to the CreateContactCard method:

  • olExchangeAgentAddressEntry

  • olExchangeOrganizationAddressEntry

  • olExchangePublicFolderAddressEntry

  • olLdapAddressEntry

  • olOtherAddressEntry

  • olOutlookDistributionListAddressEntry

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) displays a Contact Card for the current user defined by the CurrentUser property of the NameSpace object.

You cannot run this code directly from the VBA window. To run the code, click the Developer tab, click the Macros menu, and then select Project1.DisplayContactCardForCurrentUser. For more information about the Developer tab, see Run in Developer Mode in Outlook.

VBA Copy code Copy code
Sub DisplayContactCardForCurrentUser()

 Dim oCC As Office.ContactCard

 Dim oAddrEntry As Outlook.AddressEntry

 Set oAddrEntry = Application.session.CurrentUser.AddressEntry

 Set oCC = Application.session.CreateContactCard(oAddrEntry)

 oCC.Show msoContactCardFull, 100, 100, 100, 100, 100, True

 End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CreateRecipient Method (Outlook)

 Copy code hover
[image]

NameSpace.CreateRecipient Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a Recipient object.

Syntax

expression .CreateRecipient(RecipientName)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
RecipientName | Required | String | The name of the recipient; it can be a string representing the display name, the alias, or the full SMTP e-mail address of the recipient.

Return Value

A Recipient object that represents the new recipient.

Remarks

This method is most commonly used to create a Recipient object for use with the GetSharedDefaultFolder method, for example, to open a delegator's folder. It can also be used to verify a given name against an address book.

Example

This Visual Basic for Applications (VBA) example uses the GetSharedDefaultFolder method to resolve the Recipient object representing Dan Wilson, and then returns Dan's shared default Calendar folder. To run this example, replace 'Dan Wilson' with a valid recipient name and make sure the calendar is shared and you have permissions to view the calendar.

VBA Copy code Copy code
Sub ResolveName()

 Dim myNamespace As Outlook.NameSpace

 Dim myRecipient As Outlook.Recipient

 Dim CalendarFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myRecipient = myNamespace.CreateRecipient("Dan Wilson")

 myRecipient.Resolve

 If myRecipient.Resolved Then

 Call ShowCalendar(myNamespace, myRecipient)

 End If

End Sub

Sub ShowCalendar(myNamespace, myRecipient)

 Dim CalendarFolder As Folder

 Set CalendarFolder = _

 myNamespace.GetSharedDefaultFolder _

 (myRecipient, olFolderCalendar)

 CalendarFolder.Display

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.CreateSharingItem Method (Outlook)

 Copy code hover
[image]

NameSpace.CreateSharingItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new SharingItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .CreateSharingItem(Context, Provider)

expression An expression that returns a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Context | Required | Variant | Either a String value or a Folder object representing the sharing context to be used.
Provider | Optional | Variant | An OlSharingProvider value representing the sharing provider to be used.

Return Value

A SharingItem object that represents a sharing message for the specified context.

Remarks

If a String value is specified in Context, the method assumes that a URL has been provided as a sharing context. If a Folder object is specified in Context, the method attempts to discover the sharing context from the folder. If no sharing context exists, or if more than one sharing context exists, an error occurs.

If Provider is not specified, the method attempts to use the appropriate sharing provider for the value specified in Context.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Dial Method (Outlook)

 Copy code hover
[image]

NameSpace.Dial Method (Outlook)
See also Send feedback

Displays the New Call dialog box that allows users to dial the primary phone number of a specified contact.

Syntax

expression .Dial(ContactItem)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
ContactItem | Optional | Variant | The ContactItem object of the contact you want to dial.

Example

The following Microsoft Visual Basic for Applications (VBA) example opens the New Call dialog box.

VBA Copy code Copy code
Sub DialContact()

 'Opens the New Call dialog

 Application.GetNamespace("MAPI").Dial

End Sub

The following VBA example opens the New Call dialog box with the contact's information. To run this example, replace 'Jeff Smith' with a valid contact name.

VBA Copy code Copy code
Sub DialContact()

 'Opens the New Call dialog with the contact info

 Dim objContact As Outlook.ContactItem

 Set objContact = Application.GetNamespace("MAPI"). _

 GetDefaultFolder(olFolderContacts).Items("Jeff Smith")

 Application.GetNamespace("MAPI").Dial objContact

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetAddressEntryFromID Method (Outlook)

 Copy code hover
[image]

NameSpace.GetAddressEntryFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressEntry object that represents the address entry for the specified ID.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetAddressEntryFromID(ID)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
ID | Required | String | Used to identify an address entry that is maintained for the session.

Return Value

An AddressEntry that has the ID property that matches the specified ID.

Remarks

This method is similar to the GetAddressEntryFromID method of the Account object. Use this method if there is only the primary Exchange account in the current profile. If there are multiple Microsoft Exchange accounts in the current profile, use the GetAddressEntryFromID method for the corresponding account.

The ID property for an AddressEntry is a permanent, unique string identifier that the transport provider assigns when an AddressEntry is created.

Outlook maintains a hierarchy of address books for a session, and the address entry returned must match the given ID and be in one of the address books.

GetAddressEntryFromID returns an error if no item with the given ID can be found, if no connection is available, or if the user is set to work offline.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetDefaultFolder Method (Outlook)

 Copy code hover
[image]

NameSpace.GetDefaultFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object that represents the default folder of the requested type for the current profile, for example, obtains the default Calendar folder for the user who is currently logged on.

Syntax

expression .GetDefaultFolder(FolderType)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
FolderType | Required | OlDefaultFolders | The type of default folder to return.

Return Value

A Folder object that represents the default folder of the requested type for the current profile. If the default folder of the requested type does not exist, for example, because olFolderManagedEmail is specified as the FolderType but the Managed Folders group has not been deployed, then Microsoft Outlook raises an error.

Remarks

To return a specific non-default folder, use the Folders collection.

Example

This Visual Basic for Applications (VBA) example uses the CurrentFolder property to change the displayed folder to the user's default Calendar folder.

VBA Copy code Copy code
Sub ChangeCurrentFolder()

 Dim myNamespace As Outlook.NameSpace

 Set myNamespace = Application.GetNamespace("MAPI")

 Set Application.ActiveExplorer.CurrentFolder = _

 myNamespace.GetDefaultFolder(olFolderCalendar)

End Sub

This VBA example returns the first folder in the Tasks Folders collection.

VBA Copy code Copy code
Sub DisplayATaskFolder()

 Dim myNamespace As Outlook.NameSpace

 Dim myTasks As Outlook.Folder

 Dim myFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myTasks = myNamespace.GetDefaultFolder(olFolderTasks)

 Set myFolder = myTasks.Folders(1)

 myFolder.Display

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetFolderFromID Method (Outlook)

 Copy code hover
[image]

NameSpace.GetFolderFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object identified by the specified entry ID (if valid).

Syntax

expression .GetFolderFromID(EntryIDFolder, EntryIDStore)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
EntryIDFolder | Required | String | The EntryID of the folder.
EntryIDStore | Optional | Variant | The StoreID for the folder.

Return Value

A Folder object that represents the specified folder.

Remarks

This method is used for ease of transition between MAPI and OLE/Messaging applications and Microsoft Outlook.

Example

This Visual Basic for Applications (VBA) example obtains the EntryID and StoreID for the default Tasks folder and then calls the GetFolderFromID method using these values to obtain the same folder. The folder is then displayed.

VBA Copy code Copy code
Sub GetWithID()

 Dim myFolder As Outlook.Folder

 Dim myEntryID As String

 Dim myStoreID As String

 Dim myNewFolder As Outlook.Folder

 Set myFolder = Application.Session.GetDefaultFolder(olFolderTasks)

 myEntryID = myFolder.EntryID

 myStoreID = myFolder.StoreID

 Set myNewFolder = Application.Session.GetFolderFromID(myEntryID, myStoreID)

 myNewFolder.Display

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetGlobalAddressList Method (Outlook)

 Copy code hover
[image]

NameSpace.GetGlobalAddressList Method (Outlook)
See also Send feedback

Returns an AddressList object that represents the Exchange Global Address List.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetGlobalAddressList

expression A variable that represents a NameSpace object.

Return Value

An AddressList that represents the Global Address List.

Remarks

GetGlobalAddressList supports only Exchange servers. It returns an error if the Global Address List is not available or cannot be found.

It also returns an error if no connection is available or the user is set to work offline.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetItemFromID Method (Outlook)

 Copy code hover
[image]

NameSpace.GetItemFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Microsoft Outlook item identified by the specified entry ID (if valid).

Syntax

expression .GetItemFromID(EntryIDItem, EntryIDStore)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
EntryIDItem | Required | String | The EntryID of the item.
EntryIDStore | Optional | Variant | The StoreID for the folder. EntryIDStore usually must be provided when retrieving an item based on its MAPI IDs.

Return Value

An Object value that represents the specified Outlook item.

Remarks

This method is used for ease of transition between MAPI and OLE/Messaging applications and Outlook.

For more information about Entry IDs, see the EntryID property.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetRecipientFromID Method (Outlook)

 Copy code hover
[image]

NameSpace.GetRecipientFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Recipient object that is identified by the specified entry ID (if valid).

Syntax

expression .GetRecipientFromID(EntryID)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
EntryID | Required | String | The EntryID of the recipient.

Return Value

A Recipient object that represents the specified recipient.

Remarks

This method is used to ease the transition between MAPI and OLE/Messaging applications and Microsoft Outlook.

This method is similar to the GetRecipientFromID method of the Account object. If there are multiple Microsoft Exchange accounts in the current profile, use the GetRecipientFromID method for the corresponding account.

Example

This Visual Basic for Applications (VBA) example gets the entry ID of the first recipient for the first item in the Items collection for the Inbox folder, uses GetRecipientFromID to obtain the recipient from the entry ID, and displays the recipient name.

VBA Copy code Copy code
Public Sub GetRecipientFromID()

 Dim inbox As Outlook.folder

 Dim mail As Outlook.MailItem

 Dim rcp As Outlook.Recipient

 Dim rcp1 As Outlook.Recipient

 Dim strEntryId As String

 'Get Inbox folder.

 Set inbox = Application.session.GetDefaultFolder(olFolderInbox)

 ' Get the first item in the Inbox.

 Set mail = inbox.items(1)

 ' Get the first recipient on that first item.

 Set rcp = mail.Recipients.Item(1)

 ' Get the string entry ID of the recipient.

 strEntryId = rcp.entryID

 ' Get the Recipient object based on the string entry ID.

 Set rcp1 = Application.session.GetRecipientFromID(strEntryId)

 MsgBox "Recipient Name: " & rcp1.name, vbInformation

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetSelectNamesDialog Method (Outlook)

 Copy code hover
[image]

NameSpace.GetSelectNamesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a SelectNamesDialog object for the current session.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetSelectNamesDialog

expression A variable that represents a NameSpace object.

Return Value

A SelectNamesDialog object for the current session. The SelectNamesDialog object supports displaying the Select Names dialog box for the user to select entries from one or more address lists in the current session.

Example

The following code sample shows how to instantiate an instance of SelectNamesDialog for the current session, and use it to display entries from the Contacts folder in a dialog box that resembles the Select Names dialog box in the Outlook user interface.

VBA Copy code Copy code
Sub ShowContactsInDialog()
 Dim oDialog As SelectNamesDialog
 Dim oAL As AddressList
 Dim oContacts As Folder

 Set oDialog = Application.Session.GetSelectNamesDialog
 Set oContacts = _
 Application.Session.GetDefaultFolder(olFolderContacts)

 'Look for the address list that corresponds with the Contacts folder
 For Each oAL In Application.Session.AddressLists
 If oAL.GetContactsFolder = oContacts Then
 Exit For
 End If
 Next
 With oDialog
 'Initialize the dialog box with the address list representing the Contacts folder
 .InitialAddressList = oAL
 .ShowOnlyInitialAddressList = True
 If .Display Then
 'Recipients Resolved
 'Access Recipients using oDialog.Recipients
 End If
 End With
End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetSharedDefaultFolder Method (Outlook)

 Copy code hover
[image]

NameSpace.GetSharedDefaultFolder Method (Outlook)
See also Send feedback

Returns a Folder object that represents the specified default folder for the specified user.

Syntax

expression .GetSharedDefaultFolder(Recipient, FolderType)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Recipient | Required | Recipient | The owner of the folder. Note that the Recipient object must be resolved.
FolderType | Required | OlDefaultFolders | The type of folder.

Return Value

A Folder object that represents the specified default folder for the specified user.

Remarks

This method is used in a delegation scenario, where one user has delegated access to another user for one or more of their default folders (for example, their shared Calendar folder).

FolderType can be one of the following OlDefaultFolders constants: olFolderCalendar, olFolderContacts, olFolderDrafts, olFolderInbox, olFolderJournal, olFolderNotes, or olFolderTasks. (The constants olFolderDeletedItems, olFolderOutbox, olFolderJunk, olFolderConflicts, olFolderLocalFailures, olFolderServerFailures, olFolderSyncIssues, olPublicFoldersAllPublicFolders, olFolderRssSubscriptions, olFolderToDo, olFolderManagedEmail, and olFolderSentMail cannot be specified for this argument.)

Example

This Visual Basic for Applications (VBA) example uses the GetSharedDefaultFolder method to resolve the Recipient object representing Dan Wilson, and then returns Dan's shared default Calendar folder.

VBA Copy code Copy code
Sub ResolveName()

 Dim myNamespace As Outlook.NameSpace

 Dim myRecipient As Outlook.Recipient

 Dim CalendarFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myRecipient = myNamespace.CreateRecipient("Dan Wilson")

 myRecipient.Resolve

 If myRecipient.Resolved Then

 Call ShowCalendar(myNamespace, myRecipient)

 End If

End Sub

Sub ShowCalendar(myNamespace, myRecipient)

 Dim CalendarFolder As Outlook.Folder

 Set CalendarFolder = _

 myNamespace.GetSharedDefaultFolder _

 (myRecipient, olFolderCalendar)

 CalendarFolder.Display

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.GetStoreFromID Method (Outlook)

 Copy code hover
[image]

NameSpace.GetStoreFromID Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Store object that represents the store specified by ID.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetStoreFromID(ID)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
ID | Required | String | A string value identifying a store.

Return Value

A Store object that has the StoreID property matching ID.

Remarks

The StoreID property of a Store is unique to the profile for the session. It is equivalent to the MAPI property PR_STORE_ENTRY_ID.

The store must be mounted in order for this method to succeed.

GetStoreFromID returns an error if no store with the specified ID can be found for the current session.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Logoff Method (Outlook)

 Copy code hover
[image]

NameSpace.Logoff Method (Outlook)
See also Send feedback

Published: July 16, 2012

Logs the user off from the current MAPI session.

Syntax

expression .Logoff

expression A variable that represents a NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.Logon Method (Outlook)

 Copy code hover
[image]

NameSpace.Logon Method (Outlook)
See also Send feedback

Published: July 16, 2012

Logs the user on to MAPI, obtaining a MAPI session.

Syntax

expression .Logon(Profile, Password, ShowDialog, NewSession)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Profile | Optional | Variant | The MAPI profile name, as a String, to use for the session. Specify an empty string to use the default profile for the current session.
Password | Optional | Variant | The password (if any), as a String, associated with the profile. This parameter exists only for backwards compatibility and for security reasons, it is not recommended for use. Microsoft Oultook will prompt the user to specify a password in most system configurations. This is your logon password and should not be confused with PST passwords.
ShowDialog | Optional | Variant | True to display the MAPI logon dialog box to allow the user to select a MAPI profile.
NewSession | Optional | Variant | True to create a new Microsoft Outlook session. Since multiple sessions cannot be created in Outlook, this parameter should be specified as True only if a session does not already exist.

Remarks

Use the Logon method only to log on to a specific profile when Outlook is not already running. This is because only one Outlook process can run at a time, and that Outlook process uses only one profile and supports only one MAPI session. When users start Outlook a second time, that instance of Outlook runs within the same Outlook process, does not create a new process, and uses the same profile.

If Outlook is already running, using this method does not create a new Outlook session or change the current profile to a different one.

If Outlook is not running and you only want to start Outlook with the default profile, do not use the Logon method. A better alternative is shown in the following code example, InitializeMAPI: first, instantiate the Outlook Application object, then reference a default folder such as the Inbox. This has the side effect of initializing MAPI to use the default profile and to make the object model fully functional.

VBA Copy code Copy code
Sub InitializeMAPI ()

    ' Start Outlook.
    Dim olApp As Outlook.Application
    Set olApp = CreateObject("Outlook.Application")

    ' Get a session object.
    Dim olNs As Outlook.NameSpace
    Set olNs = olApp.GetNamespace("MAPI")

    ' Create an instance of the Inbox folder.
    ' If Outlook is not already running, this has the side
    ' effect of initializing MAPI.
    Dim mailFolder As Outlook.Folder
    Set mailFolder = olNs.GetDefaultFolder(olFolderInbox)

    ' Continue to use the object model to automate Outlook.
End Sub

Starting in Outlook 2010, if you have multiple profiles, you have configured Outlook to always use a default profile, and you use the Logon method to log on to the default profile without prompting the user, the user will receive a prompt to choose a profile anyway. To avoid this behavior, do not use the Logon method; use the workaround suggested in the preceding InitializeMAPI example instead.

Example

This Visual Basic for Applications example uses the Logon method to log on to a new session, displaying the dialog box to verify the profile name and enter password.

VBA Copy code Copy code
Sub StartOutlook()
    Dim myNameSpace As Outlook.NameSpace

    Set myNameSpace = Application.GetNamespace("MAPI")
    myNameSpace.Logon "LatestProfile", , True, True
End Sub

See also

Concepts

How to: Obtain and Log On to an Instance of Outlook
NameSpace Object

Other resources

NameSpace Object Members


NameSpace.OpenSharedFolder Method (Outlook)

 Copy code hover
[image]

NameSpace.OpenSharedFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Opens a shared folder referenced through a URL or file name.

Version Information

Version Added: Outlook 2007

Syntax

expression .OpenSharedFolder(Path, Name, DownloadAttachments, UseTTL)

expression An expression that returns a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The URL or local file name of the shared folder to be opened.
Name | Optional | Variant | The name of the Really Simple Syndication (RSS) feed or Webcal calendar. This parameter is ignored for other shared folder types.
DownloadAttachments | Optional | Variant | Indicates whether to download enclosures (for RSS feeds) or attachments (for Webcal calendars.) This parameter is ignored for other shared folder types.
UseTTL | Optional | Variant | Indicates whether the Time To Live (TTL) setting in an RSS feed or WebCal calendar should be used. This parameter is ignored for other shared folder types.

Return Value

A Folder object that represents the shared folder.

Remarks

This method is used to access the following shared folder types:

  • Webcal calendars (webcal://mysite/mycalendar)

  • RSS feeds (feed://mysite/myfeed)

  • Microsoft SharePoint Foundation folders (stssync://mysite/myfolder)

  • iCalendar calendar (.ics) files

  • vCard contact (.vcf) files

  • Outlook message (.msg) files

Note Note

This method does not support iCalendar appointment (.ics) files. To open iCalendar appointment files, you can use the OpenSharedItem method of the NameSpace object.

You can use the GetSharedDefaultFolder method of the Namespace object to share default folders, such as the Inbox folder, in Exchange.

Example

The following Visual Basic for Applications (VBA) example opens and displays a Webcal calendar.

VBA Copy code Copy code
Public Sub OpenSharedHolidayCalendar()

 Dim oNamespace As NameSpace

 Dim oFolder As Folder

 On Error GoTo ErrRoutine

 Set oNamespace = Application.GetNamespace("MAPI")

 Set oFolder = oNamespace.OpenSharedFolder( _

 "webcal://icalx.com/public/icalshare/US32Holidays.ics")

 oFolder.Display

EndRoutine:

 On Error GoTo 0

 Set oFolder = Nothing

 Set oNamespace = Nothing

Exit Sub

ErrRoutine:

 MsgBox Err.Description, vbOKOnly, Err.Number & " - " & Err.Source

 GoTo EndRoutine

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.OpenSharedItem Method (Outlook)

 Copy code hover
[image]

NameSpace.OpenSharedItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Opens a shared item from a specified path or URL.

Version Information

Version Added: Outlook 2007

Syntax

expression .OpenSharedItem(Path)

expression An expression that returns a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path or URL of the shared item to be opened.

Return Value

An Object representing the appropriate Outlook item for the shared item.

Remarks

This method is used to open iCalendar appointment (.ics) files, vCard (.vcf) files, and Outlook message (.msg) files. The type of object returned by this method depends on the type of shared item opened, as described in the following table.

Shared item type | Outlook item
iCalendar appointment (.ics) file | AppointmentItem
vCard (.vcf) file | ContactItem
Outlook message (.msg) file | Type corresponds to the type of the item that was saved as the .msg file
Note Note

This method does not support iCalendar calendar (.ics) files. To open iCalendar calendar files, you can use the OpenSharedFolder method of the NameSpace object.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.PickFolder Method (Outlook)

 Copy code hover
[image]

NameSpace.PickFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Pick Folder dialog box.

Syntax

expression .PickFolder

expression A variable that represents a NameSpace object.

Return Value

A Folder object that represents the folder that the user selects in the dialog box, or Nothing if the dialog box is canceled by the user.

Remarks

The Pick Folder dialog box is a modal dialog box which means that code execution will not continue until the user either selects a folder or cancels the dialog box.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.RemoveStore Method (Outlook)

 Copy code hover
[image]

NameSpace.RemoveStore Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes a Personal Folders file (.pst) from the current MAPI profile or session.

Syntax

expression .RemoveStore(Folder)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Folder | Required | Folder | The Personal Folders file (.pst) to be deleted from the list.

Remarks

This method removes a store only from the Microsoft Outlook user interface. You cannot remove a store from the main mailbox on the server or from a user's hard disk using the Outlook object model.

Example

The following Microsoft Visual Basic for Applications (VBA) examples removes a folder called Personal Folders from the list of folders.

VBA Copy code Copy code
Sub RemovePST()

 Dim objName As Outlook.NameSpace

 Dim objFolder As Outlook.Folder

 Set objName = Application.GetNamespace("MAPI")

 Set objFolder = objName.Folders.Item("Personal Folders")

 'Prompt the user for confirmation

 Dim strPrompt As String

 strPrompt = "Are you sure you want to remove the Personal Folders file?"

 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then

 objName.RemoveStore objFolder

 End If

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.SendAndReceive Method (Outlook)

 Copy code hover
[image]

NameSpace.SendAndReceive Method (Outlook)
See also Send feedback

Published: July 16, 2012

Initiates immediate delivery of all undelivered messages submitted in the current session, and immediate receipt of mail for all accounts in the current profile.

Version Information

Version Added: Outlook 2007

Syntax

expression .SendAndReceive(showProgressDialog)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
showProgressDialog | Required | Boolean | Indicates whether the Outlook Send/Receive Progress dialog box should be displayed, regardless of user settings.

Remarks

Calling the SendAndReceive method is synchronous.

SendAndReceive provides the programmatic equivalent to the Send/Receive All command that is available when you click Tools and then Send/Receive.

If you do not need to synchronize all objects, you can use the SyncObjects collection object to select specific objects. For more information, see NameSpace.SyncObjects.

All accounts defined in the current profile are used in Send/Receive All. If an online connection is required to perform the Send/Receive All, then the connection is made according to user preferences.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace Events (Outlook)

 Copy code hover
[image]

NameSpace Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AutoDiscoverComplete | Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange server that hosts the primary Exchange account and has the related information available in NameSpace.AutoDiscoverXml.
OptionsPagesAdd | Occurs whenever the Properties dialog box for a folder is opened.


NameSpace.AutoDiscoverComplete Event (Outlook)

 Copy code hover
[image]

NameSpace.AutoDiscoverComplete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has finished accessing the auto-discovery service of the Microsoft Exchange server that hosts the primary Exchange account and has the related information available in NameSpace.AutoDiscoverXml.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoDiscoverComplete

expression A variable that represents a NameSpace object.

Remarks

This event is similar to the AutoDiscoverComplete event of the Accounts object. If there are multiple Exchange accounts defined in the current profile, use the AutoDiscoverComplete event of the Accounts object that specifies the particular account.

Example

NameSpace.AutoDiscoverXml is an XML string that is returned from the auto-discovery service of the Exchange server. The following code sample shows when this XML string is available during a normal Outlook session:

  1. When the Application.Startup event occurs, if NameSpace.AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown

  2. When the AutoDiscoverComplete event occurs, if AutoDiscoverConnectionMode is not equal to olAutoDiscoverConnectionUnknown

VBA Copy code Copy code
Dim WithEvents Session As NameSpace

Dim LastAutoDiscoverXml As String

Dim LastAutoDiscoverConnectionMode As OlAutoDiscoverConnectionMode

Private Sub Application_Startup()

 Set Session = Application.Session

 If (Session.AutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown) Then

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub Session_AutoDiscoverComplete()

 LastAutoDiscoverXml = Session.AutoDiscoverXml

 LastAutoDiscoverConnectionMode = Session.AutoDiscoverConnectionMode

 If LastAutoDiscoverConnectionMode <> olAutoDiscoverConnectionUnknown Then

 DoAutoDiscoverBasedWork

 End If

End Sub

Private Sub DoAutoDiscoverBasedWork()

 ' Do activity requires auto discover information

 Dim displayName As String

 Dim posStartTag, posEndTag As Integer

 posStartTag = InStr(1, LastAutoDiscoverXml, "<DisplayName>")

 posEndTag = InStr(1, LastAutoDiscoverXml, "</DisplayName>")

 If (posStartTag > 1 And posEndTag > 1) Then

 displayName = Mid(LastAutoDiscoverXml, posStartTag + 13, posEndTag - posStartTag - 13)

 Debug.Print "DisplayName = " & displayName

 End If

End Sub

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NameSpace.OptionsPagesAdd Event (Outlook)

 Copy code hover
[image]

NameSpace.OptionsPagesAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs whenever the Properties dialog box for a folder is opened.

Syntax

expression .OptionsPagesAdd(Pages, Folder)

expression A variable that represents a NameSpace object.

Parameters

Name | Required/Optional | Data Type | Description
Pages | Required | PropertyPages | The collection of property pages that have been added to the dialog box. This collection includes only custom property pages. It does not include standard Microsoft Outlook property pages.
Folder | Required | Folder | This argument is only used with the Folder object. The Folder object for which the Properties dialog box is being opened.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

You can open the Properties dialog box for a folder by right-clicking the folder and selecting Properties.

Your program handles this event to add a custom property page. The property page will be added to Properties dialog box of the specified folder. When the event fires, the PropertyPages collection object identified by Pages contains the property pages that have been added prior to the event handler being called. To add your property page to the collection, use the Add method of the PropertyPages collection before exiting the event handler.

See also

Concepts

NameSpace Object

Other resources

NameSpace Object Members


NavigationFolder Object (Outlook)

 Copy code hover
[image]

NavigationFolder Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a navigation folder displayed in a navigation group of a navigation module in the Navigation Pane.

Version Information

Version Added: Outlook 2007

Remarks

Use the Item method to retrieve a NavigationFolder object from the NavigationFolders collection of the parent NavigationGroup object. Use the Add method of the NavigationFolders collection to create a new NavigationFolder object based on an existing Folder object.

Use the Folder method to return or set the Folder object on which the NavigationFolder object is based.

Use the IsSelected property to determine if the navigation folder is selected and the Position property to return or set the display position of the navigation folder within the Navigation Pane. You can also use the DisplayName property to return the display name of the navigation folder within the Navigation Pane.

Use the IsRemovable property to determine if a navigation folder can be removed from the NavigationFolders collection and the IsSideBySide property to return or set the viewing mode for a navigation folder associated with a CalendarModule object.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationFolder Object Members


NavigationFolder Members (Outlook)

 Copy code hover
[image]

NavigationFolder Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a navigation folder displayed in a navigation group of a navigation module in the Navigation Pane.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns a String representing the display name of the NavigationFolder object. Read-only.
Folder | Returns a Folder object that represents the shared or linked folder associated with the navigation folder. Read-only.
IsRemovable | Returns a Boolean value that indicates whether the NavigationFolder object can be removed from the Navigation Pane. Read-only.
IsSelected | Returns or sets a Boolean variable that indicates whether the NavigationFolder object is selected for display. Read/write.
IsSideBySide | Returns or sets a Boolean value that indicates whether the NavigationFolder object is displayed in side-by-side or overlay mode. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets an Long value that represents the ordinal position of the NavigationFolder object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationFolder Properties (Outlook)

 Copy code hover
[image]

NavigationFolder Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns a String representing the display name of the NavigationFolder object. Read-only.
Folder | Returns a Folder object that represents the shared or linked folder associated with the navigation folder. Read-only.
IsRemovable | Returns a Boolean value that indicates whether the NavigationFolder object can be removed from the Navigation Pane. Read-only.
IsSelected | Returns or sets a Boolean variable that indicates whether the NavigationFolder object is selected for display. Read/write.
IsSideBySide | Returns or sets a Boolean value that indicates whether the NavigationFolder object is displayed in side-by-side or overlay mode. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets an Long value that represents the ordinal position of the NavigationFolder object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationFolder.Application Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NavigationFolder object.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.Class Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NavigationFolder object.

Remarks

This property returns olNavigationFolder for the NavigationFolder object.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.DisplayName Property (Outlook)

 Copy code hover
[image]

NavigationFolder.DisplayName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the NavigationFolder object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayName

expression A variable that represents a NavigationFolder object.

Remarks

Use NavigationFolder.DisplayName, instead of Folder.Name, to get the name of a shared folder.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.Folder Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Folder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object that represents the shared or linked folder associated with the navigation folder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Folder

expression A variable that represents a NavigationFolder object.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.IsRemovable Property (Outlook)

 Copy code hover
[image]

NavigationFolder.IsRemovable Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the NavigationFolder object can be removed from the Navigation Pane. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsRemovable

expression A variable that represents a NavigationFolder object.

Remarks

Only shared or linked folders can be programmatically removed from the Navigation Pane.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.IsSelected Property (Outlook)

 Copy code hover
[image]

NavigationFolder.IsSelected Property (Outlook)
See also Send feedback

Returns or sets a Boolean variable that indicates whether the NavigationFolder object is selected for display. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsSelected

expression A variable that represents a NavigationFolder object.

Remarks

Navigation folders contained in a Calendar navigation module are treated differently than navigation folders in other navigation modules.

If the active explorer uses the Day/Week/Month or Day/Week/Month View with AutoPreview view to display navigation folders in the Calendar navigation module, this property returns True if the navigation folder is checked in the Navigation Pane (and is therefore displayed either in side-by-side or overlay mode in the active explorer.) Setting this property to False removes a calendar from display in the active explorer. An error occurs if this property is set to True for more than 30 navigation folders.

If the active explorer uses another view, such as the All Appointments view, to display navigation folders in the Calendar navigation module, or in navigation modules other than the Calendar navigation module, this property returns True if the navigation folder is selected and currently displayed in the active explorer; otherwise, the property returns False.

In either case, an error occurs if the value of this property is set to False for all NavigationFolder objects in the parent NavigationFolders collection, or if the NavigationFolder object is contained by a navigation module other than the navigation module currently displayed in the Navigation Pane.

The SelectedChange event for the parent NavigationFolders collection is raised if the value of this property is changed for a NavigationFolder object in a Calendar navigation module, regardless of the current view.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.IsSideBySide Property (Outlook)

 Copy code hover
[image]

NavigationFolder.IsSideBySide Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether the NavigationFolder object is displayed in side-by-side or overlay mode. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsSideBySide

expression A variable that represents a NavigationFolder object.

Remarks

Setting this property to True displays the NavigationFolder in side-by-side mode; otherwise, overlay mode is used to display the navigation folder in the current view of the active explorer. The default value for this property is True.

Setting this property has no effect for a NavigationFolder object that is not associated with a Calendar module. If the NavigationFolder object is associated with a Calendar module, the value of this property is dependent on the following conditions:

If the IsSelected property of the NavigationFolder object is set to False, then this property value has no effect until the IsSelected property is set to True. If the IsSelected property is set to True, then the property value is applied when the NavigationFolder is displayed.

However, the IsSideBySide property is automatically set to True if the IsSelected property for only one NavigationFolder associated with the parent CalendarModule object is set to True. In other words, if the NavigationFolder object is the only navigation folder displayed in the current view of the active explorer, then the IsSideBySide property for that one NavigationFolder object is automatically set to True.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.Parent Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NavigationFolder object.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.Position Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Position Property (Outlook)
See also Send feedback

Returns or sets an Long value that represents the ordinal position of the NavigationFolder object when displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a NavigationFolder object.

Remarks

This property can only be set to a value between 1 and the value of the Count property for the parent NavigationFolders object. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a NavigationFolder object changes the Position values of other navigation folders contained by a NavigationFolders collection, depending on the relative change between the new value and the original value of the Position property for that NavigationFolder object:

  • If the new value is less than the original value, then the specified NavigationFolder object moves up to the new position and pushes the other navigation folders already at or below that new position down.

  • If the new value is greater than the original value, then the specified NavigationFolder object moves down to the new position and pushes the other navigation folders between the old position and the new position up, filling the old position.

If the navigation folder has been removed from the Navigation Pane, then this property returns -1 to indicate that the navigation folder is no longer part of the navigation group.

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolder.Session Property (Outlook)

 Copy code hover
[image]

NavigationFolder.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NavigationFolder object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationFolder Object

Other resources

NavigationFolder Object Members


NavigationFolders Object (Outlook)

 Copy code hover
[image]

NavigationFolders Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of NavigationFolder objects that represent the navigation folders associated with a navigation group.

Version Information

Version Added: Outlook 2007

Remarks

Use the NavigationFolders property of the NavigationGroup object to return a NavigationFolders object.

Use the Add method to create a new NavigationFolder object based on an existing Folder object and add it to the collection. Use the Item method to return an existing NavigationFolder object contained by the NavigationFolders collection. Use the Remove method from the NavigationFolders collection of the parent NavigationGroup object.

Use the NavigationFolderAdd and NavigationFolderRemove events to detect when a navigation folder is added or removed, respectively, from the NavigationFolders object. Use the SelectedChange event to detect changes in selection state for navigation folders contained in the NavigationFolders object that are based on calendar folders.

Note that if you delete a Folder using Folder.Delete, the deletion will be reflected automatically in the Navigation Pane and in the NavigationFolders collection, but because the synchronization between the actual folders and the Navigation Pane happens asynchronously, this will take a few milliseconds to complete.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationFolders Object Members


NavigationFolders Members (Outlook)

 Copy code hover
[image]

NavigationFolders Members (Outlook)
Send feedback

Contains a set of NavigationFolder objects that represent the navigation folders associated with a navigation group.

Methods

Name | Description
Add | Adds the specified Folder, as a NavigationFolder object, to the end of the NavigationFolders collection.
Item | Returns a NavigationFolder object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationFolders Properties (Outlook)

 Copy code hover
[image]

NavigationFolders Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationFolders.Application Property (Outlook)

 Copy code hover
[image]

NavigationFolders.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NavigationFolders object.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Class Property (Outlook)

 Copy code hover
[image]

NavigationFolders.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NavigationFolders object.

Remarks

This property returns olNavigationFolders for the NavigationFolders object.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Count Property (Outlook)

 Copy code hover
[image]

NavigationFolders.Count Property (Outlook)
See also Send feedback

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a NavigationFolders object.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Parent Property (Outlook)

 Copy code hover
[image]

NavigationFolders.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NavigationFolders object.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Session Property (Outlook)

 Copy code hover
[image]

NavigationFolders.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NavigationFolders object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders Methods (Outlook)

 Copy code hover
[image]

NavigationFolders Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds the specified Folder, as a NavigationFolder object, to the end of the NavigationFolders collection.
Item | Returns a NavigationFolder object from the collection.
Remove | Removes an object from the collection.


NavigationFolders.Add Method (Outlook)

 Copy code hover
[image]

NavigationFolders.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds the specified Folder, as a NavigationFolder object, to the end of the NavigationFolders collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(Folder)

expression A variable that represents a NavigationFolders object.

Parameters

Name | Required/Optional | Data Type | Description
Folder | Required | Folder | The folder to add.

Return Value

A NavigationFolder object that represents the new navigation folder.

Remarks

A folder can only appear in one navigation group. When adding a Folder object to a new navigation group, any references to that Folder are removed from any other navigation group of which it was previously a member.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Item Method (Outlook)

 Copy code hover
[image]

NavigationFolders.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationFolder object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a NavigationFolders object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or the value used to match the default property of an object in the collection.

Return Value

A NavigationFolder object that represents the specified object.

Remarks

The index value of a NavigationFolder in the collection represents the ordinal position of the folder in the navigation group when displayed in the Navigation Pane. Changing the position of navigation folders within the navigation group also changes the index values of folders contained within the NavigationFolders collection for that NavigationGroup object.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationFolders.Remove Method (Outlook)

 Copy code hover
[image]

NavigationFolders.Remove Method (Outlook)
See also Send feedback

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(RemovableFolder)

expression A variable that represents a NavigationFolders object.

Parameters

Name | Required/Optional | Data Type | Description
RemovableFolder | Required | NavigationFolder | The navigation folder to be removed.

Remarks

Only removable folders, NavigationFolder objects with an IsRemovable property value set to True, can be removed from a NavigationFolders collection. This means that you can use NavigationFolders.Remove to remove shared folders, public folders, and linked folders. However, you must use Folder.Delete to remove any user-created folders.

See also

Concepts

NavigationFolders Object

Other resources

NavigationFolders Object Members


NavigationGroup Object (Outlook)

 Copy code hover
[image]

NavigationGroup Object (Outlook)
See also Send feedback

Represents a navigation group displayed by a navigation module in the Navigation Pane.

Version Information

Version Added: Outlook 2007

Remarks

Use the Item method to retrieve a NavigationGroup object from the NavigationGroups collection of a parent navigation module, such as a MailModule object. Use the Create method of the NavigationGroups collection to create a new NavigationGroup object.

Use the GroupType property to determine the group type of the navigation group and the Position property to return or set the display position of the navigation group within the Navigation Pane. You can also use the Name property to return or set the display name of the navigation group within the Navigation Pane.

Use the NavigationFolders property to return a NavigationFolders object containing the navigation folders for the specified navigation group.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationGroup Object Members


NavigationGroup Members (Outlook)

 Copy code hover
[image]

NavigationGroup Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a navigation group displayed by a navigation module in the Navigation Pane.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
GroupType | Returns an OlGroupType constant that indicates the group type for the NavigationGroup object. Read-only.
Name | Returns or sets a String value that represents the display name for the NavigationGroup object. Read/write.
NavigationFolders | Returns a NavigationFolders object that contains the set of navigation folders associated with the NavigationGroup object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NavigationGroup object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationGroup Properties (Outlook)

 Copy code hover
[image]

NavigationGroup Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
GroupType | Returns an OlGroupType constant that indicates the group type for the NavigationGroup object. Read-only.
Name | Returns or sets a String value that represents the display name for the NavigationGroup object. Read/write.
NavigationFolders | Returns a NavigationFolders object that contains the set of navigation folders associated with the NavigationGroup object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NavigationGroup object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationGroup.Application Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NavigationGroup object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.Class Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NavigationGroup object.

Remarks

This property returns olNavigationGroup for the NavigationGroup object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.GroupType Property (Outlook)

 Copy code hover
[image]

NavigationGroup.GroupType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlGroupType constant that indicates the group type for the NavigationGroup object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GroupType

expression A variable that represents a NavigationGroup object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.Name Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the NavigationGroup object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a NavigationGroup object.

Remarks

This property is limited to 127 characters. String values longer than 127 characters are truncated.

An error occurs if you attempt to set the value of this property for any NavigationGroup object associated with a MailModule object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.NavigationFolders Property (Outlook)

 Copy code hover
[image]

NavigationGroup.NavigationFolders Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationFolders object that contains the set of navigation folders associated with the NavigationGroup object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationFolders

expression A variable that represents a NavigationGroup object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.Parent Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NavigationGroup object.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.Position Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the NavigationGroup object when displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a NavigationGroup object.

Remarks

This property can only be set to a value between 1 and the value of the Count property for the parent NavigationGroups object. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a NavigationGroup object changes the Position values of other navigation groups contained by a NavigationGroups collection, depending on the relative change between the new value and the original value of the Position property for that NavigationGroup object:

  • If the new value is less than the original value, then the specified NavigationGroup object moves up to the new position and pushes the other navigation groups already at or below that new position down.

  • If the new value is greater than the original value, then the specified NavigationGroup object moves down to the new position and pushes the other navigation groups between the old position and the new position up, filling the old position.

If the navigation group is not on the Navigation Pane, then this property returns -1.

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroup.Session Property (Outlook)

 Copy code hover
[image]

NavigationGroup.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NavigationGroup object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationGroup Object

Other resources

NavigationGroup Object Members


NavigationGroups Object (Outlook)

 Copy code hover
[image]

NavigationGroups Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of NavigationGroup objects that represent the navigation groups displayed by a navigation module in the Navigation Pane.

Version Information

Version Added: Outlook 2007

Remarks

Use the NavigationGroups property of the parent navigation module, such as a MailModule object, to return a NavigationGroups object.

Use the Create method to create a new NavigationGroup object and add it to the collection. Use the Item method to retrieve a NavigationGroup object from the collection. Use the Delete method of the NavigationGroups collection to create a new NavigationGroup object.

Use the GetDefaultNavigationGroup to return the default navigation group for a specified group type.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationGroups Object Members


NavigationGroups Members (Outlook)

 Copy code hover
[image]

NavigationGroups Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of NavigationGroup objects that represent the navigation groups displayed by a navigation module in the Navigation Pane.

Events

Name | Description
NavigationFolderAdd | Occurs after a folder is added to a NavigationGroups collection.
NavigationFolderRemove | Occurs after a navigation folder has been removed from the NavigationGroups collection.
SelectedChange | Occurs after the selection state is changed for a navigation folder contained in a Calendar navigation module.

Methods

Name | Description
Create | Creates and returns a new NavigationGroup object, added to the end of the NavigationGroups collection.
Delete | Deletes the specified NavigationGroup object from the NavigationGroups collection.
GetDefaultNavigationGroup | Returns the NavigationGroup that corresponds to the selected default shared folder group.
Item | Returns a NavigationGroup object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationGroups Properties (Outlook)

 Copy code hover
[image]

NavigationGroups Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationGroups.Application Property (Outlook)

 Copy code hover
[image]

NavigationGroups.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NavigationGroups object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Class Property (Outlook)

 Copy code hover
[image]

NavigationGroups.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NavigationGroups object.

Remarks

This property returns olNavigationGroups for the NavigationGroups object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Count Property (Outlook)

 Copy code hover
[image]

NavigationGroups.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a NavigationGroups object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Parent Property (Outlook)

 Copy code hover
[image]

NavigationGroups.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NavigationGroups object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Session Property (Outlook)

 Copy code hover
[image]

NavigationGroups.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NavigationGroups object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups Methods (Outlook)

 Copy code hover
[image]

NavigationGroups Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Create | Creates and returns a new NavigationGroup object, added to the end of the NavigationGroups collection.
Delete | Deletes the specified NavigationGroup object from the NavigationGroups collection.
GetDefaultNavigationGroup | Returns the NavigationGroup that corresponds to the selected default shared folder group.
Item | Returns a NavigationGroup object from the collection.


NavigationGroups.Create Method (Outlook)

 Copy code hover
[image]

NavigationGroups.Create Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates and returns a new NavigationGroup object, added to the end of the NavigationGroups collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Create(GroupDisplayName)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
GroupDisplayName | Required | String | The value of the Name property for the new NavigationGroup object.

Return Value

A NavigationGroup object that represents the new navigation group.

Remarks

A NavigationGroups collection can contain multiple NavigationGroup objects with the same Name property values.

An error occurs if an add-in attempts to add more than 50 navigation groups to a NavigationGroups collection, or if an add-in attempts to add a NavigationGroup object to the NavigationGroups collection of a MailModule object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Delete Method (Outlook)

 Copy code hover
[image]

NavigationGroups.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes the specified NavigationGroup object from the NavigationGroups collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete(Group)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Group | Required | NavigationGroup | The navigation group to be deleted.

Remarks

The Delete method raises an error if:

  • The navigation group specified in Group contains navigation folders in its NavigationFolders collection.

  • The GroupType property of the navigation group specified in Group is set to olMyFoldersGroup.

  • The parent of the NavigationGroups collection is a MailModule object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.GetDefaultNavigationGroup Method (Outlook)

 Copy code hover
[image]

NavigationGroups.GetDefaultNavigationGroup Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NavigationGroup that corresponds to the selected default shared folder group.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetDefaultNavigationGroup(DefaultFolderGroup)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
DefaultFolderGroup | Required | OlGroupType | The type of navigation group to be retrieved.

Return Value

A NavigationGroup object that represents the selected default folder group.

Remarks

If the default navigation group specified in DefaultFolderGroup was deleted or otherwise doesn't exist, it is automatically created if the parent NavigationModule object supports the specified navigation group type. An error occurs if the parent NavigationModule object does not support creating this navigation group type.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.Item Method (Outlook)

 Copy code hover
[image]

NavigationGroups.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroup object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The index number of the object.

Return Value

A NavigationGroup object that represents the specified object.

Remarks

The index value of a NavigationGroup in the collection represents the ordinal position of the navigation group when displayed in the Navigation Pane. Changing the position of navigation groups also changes the index values of navigation groups contained within the NavigationGroups collection.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups Events (Outlook)

 Copy code hover
[image]

NavigationGroups Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
NavigationFolderAdd | Occurs after a folder is added to a NavigationGroups collection.
NavigationFolderRemove | Occurs after a navigation folder has been removed from the NavigationGroups collection.
SelectedChange | Occurs after the selection state is changed for a navigation folder contained in a Calendar navigation module.


NavigationGroups.NavigationFolderAdd Event (Outlook)

 Copy code hover
[image]

NavigationGroups.NavigationFolderAdd Event (Outlook)
See also Send feedback

Occurs after a folder is added to a NavigationGroups collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationFolderAdd(NavigationFolder)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
NavigationFolder | Required | NavigationFolder | The navigation folder added to the collection.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.NavigationFolderRemove Event (Outlook)

 Copy code hover
[image]

NavigationGroups.NavigationFolderRemove Event (Outlook)
See also Send feedback

Occurs after a navigation folder has been removed from the NavigationGroups collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationFolderRemove

expression A variable that represents a NavigationGroups object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationGroups.SelectedChange Event (Outlook)

 Copy code hover
[image]

NavigationGroups.SelectedChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the selection state is changed for a navigation folder contained in a Calendar navigation module.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelectedChange(NavigationFolder)

expression A variable that represents a NavigationGroups object.

Parameters

Name | Required/Optional | Data Type | Description
NavigationFolder | Required | NavigationFolder | The selected navigation folder.

Remarks

This event occurs when the selection state changes for a folder in the Calendar navigation module, either by a user checking or unchecking a folder in the Calendar navigation module of the Navigation Pane or by an add-in changing the value of the IsSelected property for a NavigationFolder object contained in the NavigationGroups collection of a CalendarModule object.

See also

Concepts

NavigationGroups Object

Other resources

NavigationGroups Object Members


NavigationModule Object (Outlook)

 Copy code hover
[image]

NavigationModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a navigation module in the Navigation Pane.

Version Information

Version Added: Outlook 2007

Remarks

The NavigationModule object provides access to the various navigation modules that are displayed in the Microsoft Outlook Navigation Pane. The following objects are derived from the NavigationModule object:

  • CalendarModule

  • ContactsModule

  • JournalModule

  • MailModule

  • NotesModule

  • TasksModule

  • SolutionsModule

Use the GetNavigationModule method or the Item method of the NavigationModules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the module type. Depending on the value of the NavigationModuleType property, you can then cast the NavigationModule object reference as one of the objects listed in the previous paragraph to access the NavigationGroups property for that object, such as a CalendarModule object.

The Shortcuts and Folder List navigation modules do not have a corresponding object, such as MailModule, because they do not support programmatic access to navigation groups or navigation folders. You can use the NavigationModule object to access the properties of the Shortcuts and Folder List modules.

You can use the Visible property to determine whether the navigation module is visible, and use the Position property to return or set the display position of the navigation module within the Navigation Pane. You can also use the Name property to return the display name of the navigation module in the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationModule Object Members


NavigationModule Members (Outlook)

 Copy code hover
[image]

NavigationModule Members (Outlook)
Send feedback

Represents a navigation module in the Navigation Pane.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the NavigationModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NavigationModule object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the NavigationModule object is displayed in the Navigation Pane. Read/write.


NavigationModule Properties (Outlook)

 Copy code hover
[image]

NavigationModule Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the NavigationModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NavigationModule object when displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the NavigationModule object is displayed in the Navigation Pane. Read/write.


NavigationModule.Application Property (Outlook)

 Copy code hover
[image]

NavigationModule.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression An expression that returns a NavigationModule object.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Class Property (Outlook)

 Copy code hover
[image]

NavigationModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression An expression that returns a NavigationModule object.

Remarks

This property returns olNavigationModule for the NavigationModule object.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Name Property (Outlook)

 Copy code hover
[image]

NavigationModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the NavigationModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression An expression that returns a NavigationModule object.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

NavigationModule.NavigationModuleType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a NavigationModule object.

Remarks

This property is typically used when casting a NavigationModule object to one of the following objects in order to access the NavigationGroups property:

  • CalendarModule

  • ContactsModule

  • JournalModule

  • MailModule

  • NotesModule

  • TasksModule

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Parent Property (Outlook)

 Copy code hover
[image]

NavigationModule.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression An expression that returns a NavigationModule object.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Position Property (Outlook)

 Copy code hover
[image]

NavigationModule.Position Property (Outlook)
See also Send feedback

Returns or sets a Long value that represents the ordinal position of the NavigationModule object when displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression An expression that returns a NavigationModule object.

Remarks

This property can only be set to a value between 1 and 8. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a NavigationModule object changes the Position values of other navigation modules contained by a NavigationModules collection, depending on the relative change between the new value and the original value of the Position property for that NavigationModule object:

  • If the new value is less than the original value, then the specified NavigationModule object moves up to the new position and pushes the other navigation modules already at or below that new position down.

  • If the new value is greater than the original value, then the specified NavigationModule object moves down to the new position and pushes the other navigation modules between the old position and the new position up, filling the old position.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Session Property (Outlook)

 Copy code hover
[image]

NavigationModule.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression An expression that returns a NavigationModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModule.Visible Property (Outlook)

 Copy code hover
[image]

NavigationModule.Visible Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that determines whether the NavigationModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression An expression that returns a NavigationModule object.

See also

Concepts

NavigationModule Object

Other resources

NavigationModule Object Members


NavigationModules Object (Outlook)

 Copy code hover
[image]

NavigationModules Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a read-only set of NavigationModule objects that represent the navigation modules displayed by the Navigation Pane.

Version Information

Version Added: Outlook 2007

Remarks

Use the Modules property of the NavigationPane object to return a NavigationModules object.

Use the Item method to retrieve a NavigationModule object by either the name or ordinal position of the navigation module within the collection, or use the GetNavigationModule method to return a NavigationModule object by the navigation module type.

Use the Count property to return the number of navigation modules contained in the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationModules Object Members


NavigationModules Members (Outlook)

 Copy code hover
[image]

NavigationModules Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a read-only set of NavigationModule objects that represent the navigation modules displayed by the Navigation Pane.

Methods

Name | Description
GetNavigationModule | Retrieves a NavigationModule object with the specified navigation module type from the Navigation Pane.
Item | Returns a NavigationModule object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationModules Properties (Outlook)

 Copy code hover
[image]

NavigationModules Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationModules.Application Property (Outlook)

 Copy code hover
[image]

NavigationModules.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression An expression that returns a NavigationModules object.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules.Class Property (Outlook)

 Copy code hover
[image]

NavigationModules.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression An expression that returns a NavigationModules object.

Remarks

This property returns olNavigationModules for the NavigationModules object.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules.Count Property (Outlook)

 Copy code hover
[image]

NavigationModules.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression An expression that returns a NavigationModules object.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules.Parent Property (Outlook)

 Copy code hover
[image]

NavigationModules.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression An expression that returns a NavigationModules object.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules.Session Property (Outlook)

 Copy code hover
[image]

NavigationModules.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression An expression that returns a NavigationModules object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules Methods (Outlook)

 Copy code hover
[image]

NavigationModules Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetNavigationModule | Retrieves a NavigationModule object with the specified navigation module type from the Navigation Pane.
Item | Returns a NavigationModule object from the collection.


NavigationModules.GetNavigationModule Method (Outlook)

 Copy code hover
[image]

NavigationModules.GetNavigationModule Method (Outlook)
See also Send feedback

Published: July 16, 2012

Retrieves a NavigationModule object with the specified navigation module type from the Navigation Pane.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetNavigationModule(ModuleType)

expression An expression that returns a NavigationModules object.

Parameters

Name | Required/Optional | Data Type | Description
ModuleType | Required | OlNavigationModuleType | The type of navigation module to be retrieved.

Return Value

A NavigationModule object that represents the navigation module with the specified navigation module type.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationModules.Item Method (Outlook)

 Copy code hover
[image]

NavigationModules.Item Method (Outlook)
See also Send feedback

Returns a NavigationModule object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression An expression that returns a NavigationModules object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the integer index of the position of the navigation module in the Navigation Pane, or the value used to match the default property of an object in the collection.

Return Value

A NavigationModule object that represents the specified object.

Remarks

The Name property is the default property of the NavigationModule object.

See also

Concepts

NavigationModules Object

Other resources

NavigationModules Object Members


NavigationPane Object (Outlook)

 Copy code hover
[image]

NavigationPane Object (Outlook)
See also Send feedback

Represents the Navigation Pane displayed by the active Explorer object.

Version Information

Version Added: Outlook 2007

Remarks

Use the NavigationPane property of the Explorer object to retrieve a NavigationPane object, if one exists for the explorer.

Note Note

Some Explorer objects may not have a Navigation Pane.

Use the IsCollapsed property to return or set the display mode of the Navigation Pane.

Use the Modules property to return a NavigationModules object that represents the collection of navigation modules contained by the Navigation Pane. Use the DisplayedModuleCount to return the count of NavigationModule objects currently displayed in the Navigation Pane and the CurrentModule property to return or set the currently selected NavigationModule object.

Use the ModuleSwitch event to detect when the selected NavigationModule object changes in the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

NavigationPane Object Members


NavigationPane Members (Outlook)

 Copy code hover
[image]

NavigationPane Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Navigation Pane displayed by the active Explorer object.

Events

Name | Description
ModuleSwitch | Occurs after the selection changes for a navigation module in the NavigationModules collection of the NavigationPane object.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentModule | Returns or sets a NavigationModule object that represents the currently selected navigation module in the Navigation Pane. Read/write.
DisplayedModuleCount | Returns or sets a Long value that indicates the number of NavigationModule objects displayed in the Navigation Pane. Read/write.
IsCollapsed | Returns or sets a Boolean value that determines whether the Navigation Pane is collapsed. Read/write.
Modules | Returns a NavigationModules object that represents the set of navigation modules contained by the Navigation Pane. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationPane Properties (Outlook)

 Copy code hover
[image]

NavigationPane Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CurrentModule | Returns or sets a NavigationModule object that represents the currently selected navigation module in the Navigation Pane. Read/write.
DisplayedModuleCount | Returns or sets a Long value that indicates the number of NavigationModule objects displayed in the Navigation Pane. Read/write.
IsCollapsed | Returns or sets a Boolean value that determines whether the Navigation Pane is collapsed. Read/write.
Modules | Returns a NavigationModules object that represents the set of navigation modules contained by the Navigation Pane. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


NavigationPane.Application Property (Outlook)

 Copy code hover
[image]

NavigationPane.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NavigationPane object.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.Class Property (Outlook)

 Copy code hover
[image]

NavigationPane.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NavigationPane object.

Remarks

This property returns olNavigationPane for the NavigationPane object.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.CurrentModule Property (Outlook)

 Copy code hover
[image]

NavigationPane.CurrentModule Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a NavigationModule object that represents the currently selected navigation module in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CurrentModule

expression A variable that represents a NavigationPane object.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.DisplayedModuleCount Property (Outlook)

 Copy code hover
[image]

NavigationPane.DisplayedModuleCount Property (Outlook)
See also Send feedback

Returns or sets a Long value that indicates the number of NavigationModule objects displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayedModuleCount

expression A variable that represents a NavigationPane object.

Remarks

This property can only be set to a value between 0 and the value of the Count property for the Modules collection of the NavigationPane object. If this property is set to a value greater than the maximum allowable value, the property value is automatically set to the maximum allowable value. An error occurs if this property is set to less than 0.

If the IsCollapsed property of the NavigationPane object is set to False, then this property value represents the number of navigation modules for which both icon and name are displayed in the Navigation Pane. If IsCollapsed is set to True, then the DisplayedModuleCount property value represents the number of navigation modules for which an icon is displayed in the Navigation Pane.

Setting the value of this property resizes the Modules section of the Navigation Pane to display more or fewer NavigationModule objects as needed.

Example

The following Visual Basic for Applications (VBA) example displays all navigation modules contained by the Navigation Pane, by setting the value of the DisplayedModuleCount property equal to the Count property of the Modules collection for the NavigationPane object.

Copy code Copy code
Sub DisplayAllModules()

 Dim objPane As NavigationPane

 ' Get the NavigationPane object for the

 ' currently displayed Explorer object.

 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Set the DisplayedModuleCount property to

 ' display all modules contained by the

 ' Navigation Pane.

 objPane.DisplayedModuleCount = objPane.Modules.Count

End Sub

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.IsCollapsed Property (Outlook)

 Copy code hover
[image]

NavigationPane.IsCollapsed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the Navigation Pane is collapsed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsCollapsed

expression A variable that represents a NavigationPane object.

Example

The following Visual Basic for Applications (VBA) example collapses the Navigation Pane after hiding all of the modules contained by it.

Copy code Copy code
Sub CollapseAndHideAllModules()

 Dim objPane As NavigationPane

 ' Get the NavigationPane object for the

 ' currently displayed Explorer object.

 Set objPane = Application.ActiveExplorer.NavigationPane

 ' Set the DisplayedModuleCount property to

 ' hide all modules contained by the

 ' Navigation Pane.

 objPane.DisplayedModuleCount = 0

 ' Set the IsCollapsed property to

 ' collapse the Navigation Pane.

 objPane.IsCollapsed = True

End Sub

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.Modules Property (Outlook)

 Copy code hover
[image]

NavigationPane.Modules Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationModules object that represents the set of navigation modules contained by the Navigation Pane. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Modules

expression A variable that represents a NavigationPane object.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.Parent Property (Outlook)

 Copy code hover
[image]

NavigationPane.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NavigationPane object.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane.Session Property (Outlook)

 Copy code hover
[image]

NavigationPane.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NavigationPane object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NavigationPane Events (Outlook)

 Copy code hover
[image]

NavigationPane Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
ModuleSwitch | Occurs after the selection changes for a navigation module in the NavigationModules collection of the NavigationPane object.


NavigationPane.ModuleSwitch Event (Outlook)

 Copy code hover
[image]

NavigationPane.ModuleSwitch Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the selection changes for a navigation module in the NavigationModules collection of the NavigationPane object.

Version Information

Version Added: Outlook 2007

Syntax

expression .ModuleSwitch(CurrentModule)

expression A variable that represents a NavigationPane object.

Parameters

Name | Required/Optional | Data Type | Description
CurrentModule | Required | NavigationModule | The selected navigation module.

See also

Concepts

NavigationPane Object

Other resources

NavigationPane Object Members


NewItemAlertRuleAction Object (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an action that displays a new item alert to the user.

Version Information

Version Added: Outlook 2007

Remarks

NewItemAlertRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has a NewItemAlert property. The NewItemAlert property always returns a NewItemAlertRuleAction object. If the rule has an enabled rule action that displays the specified alert in the New item Alert dialog box, then NewItemAlertRuleAction.Enabled would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction Members (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction Members (Outlook)
Send feedback

Represents an action that displays a new item alert to the user.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionNewItemAlert, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Text | Returns or sets a String that represents the text displayed in the new item alert dialog box. Read/write.


NewItemAlertRuleAction Properties (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionNewItemAlert, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Text | Returns or sets a String that represents the text displayed in the new item alert dialog box. Read/write.


NewItemAlertRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.ActionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olRuleActionNewItemAlert, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a NewItemAlertRuleAction object.

Remarks

The new item alert rule action is supported only by rules for receiving messages. For more information, see Specify Rule Actions.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Application Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NewItemAlertRuleAction object.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Class Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NewItemAlertRuleAction object.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a NewItemAlertRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NewItemAlertRuleAction object.

Remarks

The parent object is the RuleAction object.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Session Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NewItemAlertRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NewItemAlertRuleAction.Text Property (Outlook)

 Copy code hover
[image]

NewItemAlertRuleAction.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents the text displayed in the new item alert dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents a NewItemAlertRuleAction object.

Remarks

Returns an error if the text is an empty string.

See also

Concepts

NewItemAlertRuleAction Object

Other resources

NewItemAlertRuleAction Object Members


NoteItem Object (Outlook)

 Copy code hover
[image]

NoteItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a note in a Notes folder.

Remarks

A NoteItem is not customizable. If you open a new note, you will notice that it is not possible to place it in design time.

The Subject property of a NoteItem object is read-only because it is calculated from the body text of the note. Also, the NoteItemBody can only be rich text, so the properties that correspond to HTML and Microsoft Word content do not apply. Although the GetInspector property will work on notes, because notes can't be customized, some of the Inspector properties, methods, and events will not apply to NoteItem objects.

Use the CreateItem method to create a NoteItem object that represents a new note.

Use Items(index), where index is the index number of a note or a value used to match the default property of a note, to return a single NoteItem object from a Notes folder.

Example

The following Microsoft Visual Basic example returns a new note.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olNoteItem)

See also

Concepts

Outlook Object Model Reference

Other resources

NoteItem Object Members


NoteItem Members (Outlook)

 Copy code hover
[image]

NoteItem Members (Outlook)
Send feedback

Represents a note in a Notes folder.

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Height | Returns or sets a Long specifying the height (in pixels) of the note window. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of a note window from the edge of the screen. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent NoteItem object. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of a note window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.


NoteItem Properties (Outlook)

 Copy code hover
[image]

NoteItem Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Height | Returns or sets a Long specifying the height (in pixels) of the note window. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
Left | Returns or sets a Long specifying the position (in pixels) of the left vertical edge of a note window from the edge of the screen. Read/write.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent NoteItem object. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read-only.
Top | Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of a note window from the edge of the screen. Read/write.
Width | Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.


NoteItem.Application Property (Outlook)

 Copy code hover
[image]

NoteItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

NoteItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a NoteItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its NoteItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Body Property (Outlook)

 Copy code hover
[image]

NoteItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Categories Property (Outlook)

 Copy code hover
[image]

NoteItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a NoteItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Class Property (Outlook)

 Copy code hover
[image]

NoteItem.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Conflicts Property (Outlook)

 Copy code hover
[image]

NoteItem.Conflicts Property (Outlook)
See also Send feedback

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.CreationTime Property (Outlook)

 Copy code hover
[image]

NoteItem.CreationTime Property (Outlook)
See also Send feedback

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a NoteItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.DownloadState Property (Outlook)

 Copy code hover
[image]

NoteItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a NoteItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.EntryID Property (Outlook)

 Copy code hover
[image]

NoteItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a NoteItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.GetInspector Property (Outlook)

 Copy code hover
[image]

NoteItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a NoteItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Height Property (Outlook)

 Copy code hover
[image]

NoteItem.Height Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the height (in pixels) of the note window. Read/write.

Syntax

expression .Height

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.IsConflict Property (Outlook)

 Copy code hover
[image]

NoteItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a NoteItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

NoteItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a NoteItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

NoteItem.LastModificationTime Property (Outlook)
See also Send feedback

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a NoteItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Left Property (Outlook)

 Copy code hover
[image]

NoteItem.Left Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the position (in pixels) of the left vertical edge of a note window from the edge of the screen. Read/write.

Syntax

expression .Left

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

NoteItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a NoteItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.MessageClass Property (Outlook)

 Copy code hover
[image]

NoteItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a NoteItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Parent Property (Outlook)

 Copy code hover
[image]

NoteItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

NoteItem.PropertyAccessor Property (Outlook)
See also Send feedback

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent NoteItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Saved Property (Outlook)

 Copy code hover
[image]

NoteItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Session Property (Outlook)

 Copy code hover
[image]

NoteItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a NoteItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Size Property (Outlook)

 Copy code hover
[image]

NoteItem.Size Property (Outlook)
See also Send feedback

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Subject Property (Outlook)

 Copy code hover
[image]

NoteItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read-only.

Syntax

expression .Subject

expression A variable that represents a NoteItem object.

Remarks

The Subject property is a String that is calculated from the body text of the note.

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Top Property (Outlook)

 Copy code hover
[image]

NoteItem.Top Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the position (in pixels) of the top horizontal edge of a note window from the edge of the screen. Read/write.

Syntax

expression .Top

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Width Property (Outlook)

 Copy code hover
[image]

NoteItem.Width Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the width (in pixels) of the specified object. Read/write.

Syntax

expression .Width

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem Methods (Outlook)

 Copy code hover
[image]

NoteItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.


NoteItem.Close Method (Outlook)

 Copy code hover
[image]

NoteItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a NoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Copy Method (Outlook)

 Copy code hover
[image]

NoteItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression An expression that returns a NoteItem object.

Return Value

A NoteItem object that represents a copy of the specified note.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Delete Method (Outlook)

 Copy code hover
[image]

NoteItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a NoteItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

NoteItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

NoteItem Object Members


NoteItem.Display Method (Outlook)

 Copy code hover
[image]

NoteItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a NoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Move Method (Outlook)

 Copy code hover
[image]

NoteItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a NoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.PrintOut Method (Outlook)

 Copy code hover
[image]

NoteItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.Save Method (Outlook)

 Copy code hover
[image]

NoteItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a NoteItem object.

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NoteItem.SaveAs Method (Outlook)

 Copy code hover
[image]

NoteItem.SaveAs Method (Outlook)
See also Send feedback

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a NoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.NoteItem

 Set MyItem = Application.CreateItem(olNoteItem)
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

NoteItem Object

Other resources

NoteItem Object Members


NotesModule Object (Outlook)

 Copy code hover
[image]

NotesModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the Notes navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The NotesModule object, derived from the NavigationModule object, provides access to the navigation groups contained in the Notes navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the NavigationModules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the navigation module type. If the NavigationModuleType property is set to olModuleNotes, you can then cast the Module object reference as a NotesModule object to access the NavigationGroups property for that navigation module.

You can use the Visible property to determine if the navigation module is visible and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Notes navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

NotesModule Object Members


NotesModule Members (Outlook)

 Copy code hover
[image]

NotesModule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Notes navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the NotesModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the NotesModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NotesModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the NotesModule object is displayed in the Navigation Pane. Read/write.


NotesModule Properties (Outlook)

 Copy code hover
[image]

NotesModule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the NotesModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the NotesModule object. Read-only.
NavigationModuleType | Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the NotesModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the NotesModule object is displayed in the Navigation Pane. Read/write.


NotesModule.Application Property (Outlook)

 Copy code hover
[image]

NotesModule.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Class Property (Outlook)

 Copy code hover
[image]

NotesModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a NotesModule object.

Remarks

This property returns olNotesModule for the NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Name Property (Outlook)

 Copy code hover
[image]

NotesModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the NotesModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

NotesModule.NavigationGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroups object that contains the set of navigation groups associated with the NotesModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

NotesModule.NavigationModuleType Property (Outlook)
See also Send feedback

Returns an olNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a NotesModule object.

Remarks

This property returns olModuleNotes for the NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Parent Property (Outlook)

 Copy code hover
[image]

NotesModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Position Property (Outlook)

 Copy code hover
[image]

NotesModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the NotesModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a NotesModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a given NotesModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified NotesModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified NotesModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Session Property (Outlook)

 Copy code hover
[image]

NotesModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a NotesModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


NotesModule.Visible Property (Outlook)

 Copy code hover
[image]

NotesModule.Visible Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that determines whether the NotesModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a NotesModule object.

See also

Concepts

NotesModule Object

Other resources

NotesModule Object Members


OlkBusinessCardControl Object (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl Object (Outlook)
See also Send feedback

Published: July 16, 2012

This control displays a business card.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Business Card Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is an example of a Business Card control at runtime:

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl Members (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl Members (Outlook)
Send feedback

Published: July 16, 2012

This control displays a business card.

Events

Name | Description
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action or programmatically.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkBusinessCardControl Properties (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkBusinessCardControl.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkBusinessCardControl object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkBusinessCardControl object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl Events (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action or programmatically.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkBusinessCardControl.Click Event (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is clicked, either through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkBusinessCardControl object.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is double-clicked through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkBusinessCardControl object.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkBusinessCardControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkBusinessCardControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkBusinessCardControl.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkBusinessCardControl.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkBusinessCardControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkBusinessCardControl Object

Other resources

OlkBusinessCardControl Object Members


OlkCategory Object (Outlook)

 Copy code hover
[image]

OlkCategory Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that displays the selected categories.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Category Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

This control shows both the category name and the category color. Right-clicking this control displays the category selector context menu that allows the user to select categories in standard Outlook forms. If there are no categories to be displayed, this control will resize automatically to a height of zero.

The following is an example of a category control at runtime. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkCategory Object Members


OlkCategory Members (Outlook)

 Copy code hover
[image]

OlkCategory Members (Outlook)
Send feedback

Published: July 16, 2012

A control that displays the selected categories.

Events

Name | Description
Change | Occurs when a category selection has changed.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkCategory Properties (Outlook)

 Copy code hover
[image]

OlkCategory Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkCategory.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkCategory.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkCategory object.

Remarks

The default value for this property is True.

This control assumes one line unless the contents expand and need more space. If this happens, the control will grow to display the contents and move the remaining form contents down to make space.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.BackColor Property (Outlook)

 Copy code hover
[image]

OlkCategory.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkCategory object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x8000000F, "Button Face."

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkCategory.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkCategory object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.Enabled Property (Outlook)

 Copy code hover
[image]

OlkCategory.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkCategory object.

Remarks

The default value is True.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkCategory.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkCategory object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkCategory.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkCategory object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkCategory.MousePointer Property (Outlook)
See also Send feedback

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkCategory object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory Events (Outlook)

 Copy code hover
[image]

OlkCategory Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
Change | Occurs when a category selection has changed.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkCategory.Change Event (Outlook)

 Copy code hover
[image]

OlkCategory.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a category selection has changed.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkCategory object.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.Click Event (Outlook)

 Copy code hover
[image]

OlkCategory.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkCategory object.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkCategory.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkCategory object.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.Enter Event (Outlook)

 Copy code hover
[image]

OlkCategory.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the control actually receives the focus from a control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkCategory object.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.Exit Event (Outlook)

 Copy code hover
[image]

OlkCategory.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkCategory.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkCategory.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkCategory.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkCategory.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkCategory.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCategory.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkCategory.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkCategory object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCategory Object

Other resources

OlkCategory Object Members


OlkCheckBox Object (Outlook)

 Copy code hover
[image]

OlkCheckBox Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports one or more selections in a defined group of check box choices.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Check Box Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of a check box control that has been bound to the Recurring field. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkCheckBox Object Members


OlkCheckBox Members (Outlook)

 Copy code hover
[image]

OlkCheckBox Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports one or more selections in a defined group of check box choices.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
TripleState | Returns or sets a Boolean that specifies whether a user can specify in the user interface the Null state for the control. Read/write.
Value | Returns or sets a Variant that specifies the state of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkCheckBox Properties (Outlook)

 Copy code hover
[image]

OlkCheckBox Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
TripleState | Returns or sets a Boolean that specifies whether a user can specify in the user interface the Null state for the control. Read/write.
Value | Returns or sets a Variant that specifies the state of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkCheckBox.Accelerator Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Accelerator Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Accelerator

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is an empty string, meaning there is no hot key. If the property is set with a string of more than one character, the value will be truncated to the first character.

You cannot use digits in an accelerator.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Alignment Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Alignment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Alignment

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is olAlignmentLeft.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.BackColor Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.BackColor Property (Outlook)
See also Send feedback

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkCheckBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x8000000F, "Button Face."

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Caption Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is based on the control's name. The position of the caption relative to the check box is determined by the Alignment property.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Enabled Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is True.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Font Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkCheckBox object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkCheckBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkCheckBox object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.TripleState Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.TripleState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a user can specify in the user interface the Null state for the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TripleState

expression A variable that represents an OlkCheckBox object.

Remarks

If this property is True, the check box clicks through the three states. If this property is False, the check box supports only the True and False states. The default value is False.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Value Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that specifies the state of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkCheckBox object.

Remarks

For the check box control, this property is True or False, or if the TripleState property is set, the Value property can also be Null (Nothing in Visual Basic). The default value is False.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.WordWrap Property (Outlook)

 Copy code hover
[image]

OlkCheckBox.WordWrap Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WordWrap

expression A variable that represents an OlkCheckBox object.

Remarks

The default value is True.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox Events (Outlook)

 Copy code hover
[image]

OlkCheckBox Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkCheckBox.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkCheckBox object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Change Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkCheckBox object.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Click Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkCheckBox object.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkCheckBox object.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Enter Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkCheckBox object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.Exit Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.Exit Event (Outlook)
See also Send feedback

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkCheckBox.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkCheckBox.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkCheckBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCheckBox Object

Other resources

OlkCheckBox Object Members


OlkComboBox Object (Outlook)

 Copy code hover
[image]

OlkComboBox Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports the display of a selection from a drop-down list of all choices.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Combo Box Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of a combo box control that has been bound to the Sensitivity field. This control supports Microsoft Windows themes.

If the Click event is implemented but the DropButtonClick event is not implemented, then clicking the drop button will fire only the Click event.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkComboBox Object Members


OlkComboBox Members (Outlook)

 Copy code hover
[image]

OlkComboBox Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports the display of a selection from a drop-down list of all choices.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the selection in the list displayed by the control changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the drop-down list in the combo box control, or when the DropDown method is called programmatically.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
AddItem | Adds an item to the list, optionally specifying an index for the new item to appear in the list.
Clear | Removes all objects from the list in the combo box.
Copy | Copies the contents of the control to the clipboard.
Cut | Removes the contents of the control and copies the contents to the clipboard.
DropDown | Expands the drop-down portion of the combo box.
GetItem | Obtains a String that represents an item at the specified location in the list of the combo box control.
Paste | Pastes the contents of the clipboard in the control.
RemoveItem | Removes the specified item from the list.
SetItem | Sets the item at the specified location in the list of the combo box to the specified value.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
DragBehavior | Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
ListCount | Returns a Long that specifies the number of elements in the drop-down list of the combo box control. Read-only.
ListIndex | Reurns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that specifies the number of characters in the current selection. Read/write.
SelStart | Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.
SelText | Returns a String that represents the selected portion of the value of the combo box. Read-only.
Style | Returns or sets an OlComboBoxStyle constant to specify how the user can choose or set the control's value. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
TopIndex | Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list in the combo box. Read/write.
Value | Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.


OlkComboBox Properties (Outlook)

 Copy code hover
[image]

OlkComboBox Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
DragBehavior | Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
ListCount | Returns a Long that specifies the number of elements in the drop-down list of the combo box control. Read-only.
ListIndex | Reurns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that specifies the number of characters in the current selection. Read/write.
SelStart | Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.
SelText | Returns a String that represents the selected portion of the value of the combo box. Read-only.
Style | Returns or sets an OlComboBoxStyle constant to specify how the user can choose or set the control's value. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
TopIndex | Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list in the combo box. Read/write.
Value | Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.


OlkComboBox.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkComboBox.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkComboBox object.

Remarks

The default value for this property is False.

Setting AutoSize to True automatically sets the width of the display area to the length of the text in the combo box. This behavior is similar to the single-line text box.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.AutoTab Property (Outlook)

 Copy code hover
[image]

OlkComboBox.AutoTab Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoTab

expression A variable that represents an OlkComboBox object.

Remarks

The default value for this property is False.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.AutoWordSelect Property (Outlook)

 Copy code hover
[image]

OlkComboBox.AutoWordSelect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoWordSelect

expression A variable that represents an OlkComboBox object.

Remarks

The default value is True.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.BackColor Property (Outlook)

 Copy code hover
[image]

OlkComboBox.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkComboBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000005, "Window."

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.BorderStyle Property (Outlook)

 Copy code hover
[image]

OlkComboBox.BorderStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BorderStyle

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olBorderStyleSingle.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.DragBehavior Property (Outlook)

 Copy code hover
[image]

OlkComboBox.DragBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DragBehavior

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olDragDropDisabled.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Enabled Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkComboBox object.

Remarks

The default value is True.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.EnterFieldBehavior Property (Outlook)

 Copy code hover
[image]

OlkComboBox.EnterFieldBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnterFieldBehavior

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olEnterFieldBehaviorSelectAll.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Font Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkComboBox object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkComboBox.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkComboBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.HideSelection Property (Outlook)

 Copy code hover
[image]

OlkComboBox.HideSelection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HideSelection

expression A variable that represents an OlkComboBox object.

Remarks

The default value of this property is True.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.ListCount Property (Outlook)

 Copy code hover
[image]

OlkComboBox.ListCount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long that specifies the number of elements in the drop-down list of the combo box control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ListCount

expression A variable that represents an OlkComboBox object.

Remarks

The default value is zero, indicating that there are no items in the list.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.ListIndex Property (Outlook)

 Copy code hover
[image]

OlkComboBox.ListIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Reurns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ListIndex

expression A variable that represents an OlkComboBox object.

Remarks

ListIndex is a zero-based value indexing into the array of items in the list. The default value is -1, indicating that no item is selected.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Locked Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkComboBox object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MaxLength Property (Outlook)

 Copy code hover
[image]

OlkComboBox.MaxLength Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MaxLength

expression A variable that represents an OlkComboBox object.

Remarks

The default value is zero, which only means that no maximum length for the value has been defined for this control. A maximum length may still be in place based on available memory or other factors.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkComboBox.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkComboBox object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkComboBox.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.SelectionMargin Property (Outlook)

 Copy code hover
[image]

OlkComboBox.SelectionMargin Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelectionMargin

expression A variable that represents an OlkComboBox object.

Remarks

If True, clicking in the margin causes selection of text. If False, this action does not select any text. The default value is False.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.SelLength Property (Outlook)

 Copy code hover
[image]

OlkComboBox.SelLength Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies the number of characters in the current selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelLength

expression A variable that represents an OlkComboBox object.

Remarks

The current selection is specified by SelText, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is zero, which means no text is currently selected.

The SelLength property is always valid, even when the control does not have focus.

Setting SelLength to a value less than zero causes an error. Attempting to set the value greater than MaxLength results in setting SelLength to MaxLength.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.SelStart Property (Outlook)

 Copy code hover
[image]

OlkComboBox.SelStart Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelStart

expression A variable that represents an OlkComboBox object.

Remarks

The current selection is specified by SelText, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is zero, which means no text is selected and the insertion point is at the beginning.

The SelStart property is always valid, even when the control does not have focus. Setting SelStart to a value less than zero causes an error. Setting SelStart to a value greater than MaxLength will reset SelStart to MaxLength. Changing the value of SelStart cancels any existing selection, places the insertion point in the text, and sets the SelLength property to zero.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.SelText Property (Outlook)

 Copy code hover
[image]

OlkComboBox.SelText Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the selected portion of the value of the combo box. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelText

expression A variable that represents an OlkComboBox object.

Remarks

SelText represents the current selection, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is an empty string.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Style Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Style Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlComboBoxStyle constant to specify how the user can choose or set the control's value. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Style

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olComboBoxStyleCombo.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Text Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that is the text displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents an OlkComboBox object.

Remarks

The default value of the Text property is the empty string.

The Text property provides the same value as the Value property, but the value is strongly typed as a String.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkComboBox.TextAlign Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkComboBox object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.TopIndex Property (Outlook)

 Copy code hover
[image]

OlkComboBox.TopIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list in the combo box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TopIndex

expression A variable that represents an OlkComboBox object.

Remarks

As the list scrolls, the item at the top of the list will change, and the value of this property will change to reflect the item currently displayed at the top of the list.

The index value is zero-based. The default value is -1, indicating that no special ordering should be applied.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Value Property (Outlook)

 Copy code hover
[image]

OlkComboBox.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkComboBox object.

Remarks

The value is the same as the value of Text, except that this property is Variant and Text is strongly typed as String.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox Methods (Outlook)

 Copy code hover
[image]

OlkComboBox Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
AddItem | Adds an item to the list, optionally specifying an index for the new item to appear in the list.
Clear | Removes all objects from the list in the combo box.
Copy | Copies the contents of the control to the clipboard.
Cut | Removes the contents of the control and copies the contents to the clipboard.
DropDown | Expands the drop-down portion of the combo box.
GetItem | Obtains a String that represents an item at the specified location in the list of the combo box control.
Paste | Pastes the contents of the clipboard in the control.
RemoveItem | Removes the specified item from the list.
SetItem | Sets the item at the specified location in the list of the combo box to the specified value.


OlkComboBox.AddItem Method (Outlook)

 Copy code hover
[image]

OlkComboBox.AddItem Method (Outlook)
See also Send feedback

Adds an item to the list, optionally specifying an index for the new item to appear in the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddItem(ItemText, Index)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
ItemText | Required | String | Value to be added to the list in the combo box.
Index | Optional | Long | A 0-based value that specifies the order of the new item in the list.

Remarks

If the value of Index is equal to or larger than the number of elements in the list, the new item will be added to the end of the list.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Clear Method (Outlook)

 Copy code hover
[image]

OlkComboBox.Clear Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes all objects from the list in the combo box.

Version Information

Version Added: Outlook 2007

Syntax

expression .Clear

expression A variable that represents an OlkComboBox object.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Copy Method (Outlook)

 Copy code hover
[image]

OlkComboBox.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Copies the contents of the control to the clipboard.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy

expression A variable that represents an OlkComboBox object.

Remarks

The data is copied in unformatted text format, replacing the existing contents of the clipboard.

If the control style is olComboBoxStyleListBox, then this method copies the current selection in the drop-down list to the clipboard.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Cut Method (Outlook)

 Copy code hover
[image]

OlkComboBox.Cut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the contents of the control and copies the contents to the clipboard.

Version Information

Version Added: Outlook 2007

Syntax

expression .Cut

expression A variable that represents an OlkComboBox object.

Remarks

The data is copied to the clipboard in unformatted text format, replacing the existing contents of the clipboard.

If the control style is olComboBoxStyleListBox, then this method will not cut anything.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.DropDown Method (Outlook)

 Copy code hover
[image]

OlkComboBox.DropDown Method (Outlook)
See also Send feedback

Expands the drop-down portion of the combo box.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropDown

expression A variable that represents an OlkComboBox object.

Remarks

Simulates the user clicking the drop button on the control. This method causes the DropButtonClick event to fire.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.GetItem Method (Outlook)

 Copy code hover
[image]

OlkComboBox.GetItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a String that represents an item at the specified location in the list of the combo box control.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetItem(Index)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.

Return Value

A String value that represents the item at the specified location in the list.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Paste Method (Outlook)

 Copy code hover
[image]

OlkComboBox.Paste Method (Outlook)
See also Send feedback

Published: July 16, 2012

Pastes the contents of the clipboard in the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Paste

expression A variable that represents an OlkComboBox object.

Remarks

The contents of the clipboard are pasted in unformatted text.

This method does not paste anything when the control's Style is olComboBoxStyleListBox.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.RemoveItem Method (Outlook)

 Copy code hover
[image]

OlkComboBox.RemoveItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the specified item from the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoveItem(Index)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value indexing into the array of items in the list.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.SetItem Method (Outlook)

 Copy code hover
[image]

OlkComboBox.SetItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the item at the specified location in the list of the combo box to the specified value.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetItem(Index, Item)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.
Item | Required | String | The value to be used to update the list at the specified location.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox Events (Outlook)

 Copy code hover
[image]

OlkComboBox Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the selection in the list displayed by the control changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the drop-down list in the combo box control, or when the DropDown method is called programmatically.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkComboBox.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkComboBox.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkComboBox object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkComboBox.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Change Event (Outlook)

 Copy code hover
[image]

OlkComboBox.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the selection in the list displayed by the control changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkComboBox object.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Click Event (Outlook)

 Copy code hover
[image]

OlkComboBox.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkComboBox object.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkComboBox.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkComboBox object.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.DropButtonClick Event (Outlook)

 Copy code hover
[image]

OlkComboBox.DropButtonClick Event (Outlook)
See also Send feedback

Occurs when the user clicks the drop button to expand the drop-down list in the combo box control, or when the DropDown method is called programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropButtonClick

expression A variable that represents an OlkComboBox object.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Enter Event (Outlook)

 Copy code hover
[image]

OlkComboBox.Enter Event (Outlook)
See also Send feedback

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkComboBox object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.Exit Event (Outlook)

 Copy code hover
[image]

OlkComboBox.Exit Event (Outlook)
See also Send feedback

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkComboBox.KeyDown Event (Outlook)
See also Send feedback

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkComboBox.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkComboBox.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkComboBox.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkComboBox.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkComboBox.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkComboBox.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkComboBox Object

Other resources

OlkComboBox Object Members


OlkCommandButton Object (Outlook)

 Copy code hover
[image]

OlkCommandButton Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports a user action specified as a command.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Command Button Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of the command button control at runtime. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkCommandButton Object Members


OlkCommandButton Members (Outlook)

 Copy code hover
[image]

OlkCommandButton Members (Outlook)
Send feedback

A control that supports a user action specified as a command.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
DisplayDropArrow | Returns or sets a Boolean that enables the rendering of a downward-pointing arrow on the button. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
Picture | Returns or sets a StdPicture value that represents the picture that is displayed on the control. Read/write.
PictureAlignment | Returns or sets an OlPictureAlignment constant that specifies the alignment of the image and the text on the button. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkCommandButton Properties (Outlook)

 Copy code hover
[image]

OlkCommandButton Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
DisplayDropArrow | Returns or sets a Boolean that enables the rendering of a downward-pointing arrow on the button. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
Picture | Returns or sets a StdPicture value that represents the picture that is displayed on the control. Read/write.
PictureAlignment | Returns or sets an OlPictureAlignment constant that specifies the alignment of the image and the text on the button. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkCommandButton.Accelerator Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.Accelerator Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Accelerator

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is an empty string, meaning there is no hot key. If the property is set with a string of more than one character, the value will be truncated to the first character.

You cannot use digits in an accelerator.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.AutoSize Property (Outlook)
See also Send feedback

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkCommandButton object.

Remarks

The default value for this property is False.

For a button control, this property specifies whether the control automatically adjusts to display the entire caption value.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Caption Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is an empty string. The Forms Designer sets this property to the control's default name.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.DisplayDropArrow Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.DisplayDropArrow Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that enables the rendering of a downward-pointing arrow on the button. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayDropArrow

expression A variable that represents an OlkCommandButton object.

Remarks

This arrow is rendered on the right on the button in langauges written left-to-right and on the left in langauges written right-to-left. True to render the arrow on the button, False to disable the rendering.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Enabled Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is False.

When the control is disabled, the contents of the control appear dimmed.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Font Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkCommandButton object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkCommandButton object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Picture Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.Picture Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture value that represents the picture that is displayed on the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Picture

expression A variable that represents an OlkCommandButton object.

Remarks

The picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

A picture and text cannot be displayed at the same time on the control, so when the picture property is set, the text property is ignored.

The picture is always displayed in the center of the button control. The picture will be clipped as necessary to fit in the available space.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.PictureAlignment Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.PictureAlignment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlPictureAlignment constant that specifies the alignment of the image and the text on the button. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .PictureAlignment

expression A variable that represents an OlkCommandButton object.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.TextAlign Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

For the Command Button control, when TextAlign is set to olTextAlignLeft, the left margin is only one pixel from the border of the control.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.WordWrap Property (Outlook)

 Copy code hover
[image]

OlkCommandButton.WordWrap Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WordWrap

expression A variable that represents an OlkCommandButton object.

Remarks

The default value is True.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton Events (Outlook)

 Copy code hover
[image]

OlkCommandButton Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkCommandButton.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkCommandButton object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Click Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.Click Event (Outlook)
See also Send feedback

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkCommandButton object.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkCommandButton object.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Enter Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the control actually receives the focus from a control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkCommandButton object.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.Exit Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.Exit Event (Outlook)
See also Send feedback

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.KeyPress Event (Outlook)
See also Send feedback

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkCommandButton.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkCommandButton.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkCommandButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkCommandButton Object

Other resources

OlkCommandButton Object Members


OlkContactPhoto Object (Outlook)

 Copy code hover
[image]

OlkContactPhoto Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that shows the contact picture for a contact item if a contact picture has been defined, or the contact picture button if no contact picture has been assigned.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Contact Photo Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is the contact picture button that is displayed at runtime if no contact picture has been defined. If a contact picture has been defined for a contact, the contact photo will be rescaled to fit into the control space. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkContactPhoto Object Members


OlkContactPhoto Members (Outlook)

 Copy code hover
[image]

OlkContactPhoto Members (Outlook)
Send feedback

Published: July 16, 2012

A control that shows the contact picture for a contact item if a contact picture has been defined, or the contact picture button if no contact picture has been assigned.

Events

Name | Description
Change | Occurs when the contact picture has changed.
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action or programmatically.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkContactPhoto Properties (Outlook)

 Copy code hover
[image]

OlkContactPhoto Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkContactPhoto.Enabled Property (Outlook)

 Copy code hover
[image]

OlkContactPhoto.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkContactPhoto object.

Remarks

The default value is True.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkContactPhoto.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkContactPhoto object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkContactPhoto.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkContactPhoto object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto Events (Outlook)

 Copy code hover
[image]

OlkContactPhoto Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
Change | Occurs when the contact picture has changed.
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action or programmatically.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkContactPhoto.Change Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.Change Event (Outlook)
See also Send feedback

Occurs when the contact picture has changed.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkContactPhoto object.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.Click Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is clicked, either through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkContactPhoto object.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is double-clicked through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkContactPhoto object.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.Enter Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the control actually receives the focus from a control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkContactPhoto object.

Remarks

This event occurs only when the control is displaying the contact picture button and no contact picture has been defined.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.Exit Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

Remarks

This event occurs only when the control is displaying the contact picture button and no contact picture has been defined.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkContactPhoto.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkContactPhoto.MouseUp Event (Outlook)
See also Send feedback

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkContactPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkContactPhoto Object

Other resources

OlkContactPhoto Object Members


OlkControl Object (Outlook)

 Copy code hover
[image]

OlkControl Object (Outlook)
See also Send feedback

Published: July 16, 2012

Defines a set of control properties common to some Microsoft Outlook controls.

Version Information

Version Added: Outlook 2007

Remarks

The members offered by OlkControl can apply to most Outlook controls. OlkControl provides a class to which you can conveniently cast an Outlook control without resorting to reflection. Although OlkControl does not apply to Microsoft Forms 2.0 controls, similar properties are available to Forms 2.0 controls. For more information, see KB 180972: Additional Control Properties Available for Programming.

Example

The following code sample uses the OlkControl class to enable automatic resizing of a text box control with respect to any resizing of the form. It uses casting in Visual Basic to allow the text box control to use the properties of OlkControl.

Copy code Copy code
Sub ResizeWithForm()
 Dim myTextBox As OlkTextBox
 Dim olkCtrl As OlkControl

 ' Let the text box control use the properties of OlkControl
 Set olkCtrl = myTextBox

 ' Enable automatic adjustments of the layout with respect to the rest of the form
 olkCtrl.EnableAutoLayout = True

 ' Allow resizing the text box control horizontally and vertically with the form
 olkCtrl.HorizontalLayout = olHorizontalLayoutGrow
 olkCtrl.VerticalLayout = olVerticalLayoutGrow
End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

OlkControl Object Members


OlkControl Members (Outlook)

 Copy code hover
[image]

OlkControl Members (Outlook)
Send feedback

Published: July 16, 2012

Defines a set of control properties common to some Microsoft Outlook controls.

Properties

Name | Description
ControlProperty | Returns or sets a String that represents the property on the control that the databind occurs with. Read/write.
EnableAutoLayout | Returns or sets a Boolean that enables automatic adjustments of the layout for the control with respect to the rest of the form. Read/write.
Format | Returns or sets a Long that specifies how a value is to be displayed in the control. Read/write.
HorizontalLayout | Returns or sets an OlHorizontalLayout constant that specifies any alignment in the horizontal direction of this control with other selected controls on the form, or whether the control is adjusted in the horizontal direction automatically when the form's width is changed. Read/write.
ItemProperty | Returns or sets a String that specifies the name of the property in the Outlook object model that the control is bound to. Read/write.
MinimumHeight | Returns or sets a Long that specifies the minimum height the control can be automatically sized down to. Read/write.
MinimumWidth | Returns or sets a Long that specifies the minimum width the control can be automatically sized down to. Read/write.
PossibleValues | Returns or sets a String that represents a list of possible values for the drop-down list for the control, seperated by semicolons. Read/write.
VerticalLayout | Returns or sets an OlVerticalLayout constant that specifies any alignment in the vertical direction of this control with other selected controls on the form, or whether the control is adjusted in the vertical direction automatically when the form's length is changed. Read/write.


OlkControl Properties (Outlook)

 Copy code hover
[image]

OlkControl Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ControlProperty | Returns or sets a String that represents the property on the control that the databind occurs with. Read/write.
EnableAutoLayout | Returns or sets a Boolean that enables automatic adjustments of the layout for the control with respect to the rest of the form. Read/write.
Format | Returns or sets a Long that specifies how a value is to be displayed in the control. Read/write.
HorizontalLayout | Returns or sets an OlHorizontalLayout constant that specifies any alignment in the horizontal direction of this control with other selected controls on the form, or whether the control is adjusted in the horizontal direction automatically when the form's width is changed. Read/write.
ItemProperty | Returns or sets a String that specifies the name of the property in the Outlook object model that the control is bound to. Read/write.
MinimumHeight | Returns or sets a Long that specifies the minimum height the control can be automatically sized down to. Read/write.
MinimumWidth | Returns or sets a Long that specifies the minimum width the control can be automatically sized down to. Read/write.
PossibleValues | Returns or sets a String that represents a list of possible values for the drop-down list for the control, seperated by semicolons. Read/write.
VerticalLayout | Returns or sets an OlVerticalLayout constant that specifies any alignment in the vertical direction of this control with other selected controls on the form, or whether the control is adjusted in the vertical direction automatically when the form's length is changed. Read/write.


OlkControl.ControlProperty Property (Outlook)

 Copy code hover
[image]

OlkControl.ControlProperty Property (Outlook)
See also Send feedback

Returns or sets a String that represents the property on the control that the databind occurs with. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ControlProperty

expression A variable that represents an OlkControl object.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.EnableAutoLayout Property (Outlook)

 Copy code hover
[image]

OlkControl.EnableAutoLayout Property (Outlook)
See also Send feedback

Returns or sets a Boolean that enables automatic adjustments of the layout for the control with respect to the rest of the form. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnableAutoLayout

expression A variable that represents an OlkControl object.

Remarks

Automatic adjustments of the layout of a control include vertically or horizontally aligning the control with respect to other controls, and sizing the height or the width of the control with respect to the length or the width of the form.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.Format Property (Outlook)

 Copy code hover
[image]

OlkControl.Format Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies how a value is to be displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Format

expression A variable that represents an OlkControl object.

Remarks

The Format property can be a constant in an enumeration that describes how to display a value. For example, you can specify Format as the constant olFormatCurrencyDecimal that is defined in the OlFormatCurrency enumeration to display a currency value in an OlkTextBox control.

The Format property is specific to the property in the Outlook Object Model that the control is bound to. The latter is indicated by OlkControl.ItemProperty. If the control is not bound to any property, then accessing Format will return an error.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.HorizontalLayout Property (Outlook)

 Copy code hover
[image]

OlkControl.HorizontalLayout Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlHorizontalLayout constant that specifies any alignment in the horizontal direction of this control with other selected controls on the form, or whether the control is adjusted in the horizontal direction automatically when the form's width is changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HorizontalLayout

expression A variable that represents an OlkControl object.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.ItemProperty Property (Outlook)

 Copy code hover
[image]

OlkControl.ItemProperty Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that specifies the name of the property in the Outlook object model that the control is bound to. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ItemProperty

expression A variable that represents an OlkControl object.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.MinimumHeight Property (Outlook)

 Copy code hover
[image]

OlkControl.MinimumHeight Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies the minimum height the control can be automatically sized down to. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MinimumHeight

expression A variable that represents an OlkControl object.

Remarks

EnableAutoLayout must be set to True in order for MinimumLength to become effective.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.MinimumWidth Property (Outlook)

 Copy code hover
[image]

OlkControl.MinimumWidth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies the minimum width the control can be automatically sized down to. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MinimumWidth

expression A variable that represents an OlkControl object.

Remarks

EnableAutoLayout must be set to True in order for MinimumWidth to become effective.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.PossibleValues Property (Outlook)

 Copy code hover
[image]

OlkControl.PossibleValues Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents a list of possible values for the drop-down list for the control, seperated by semicolons. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .PossibleValues

expression A variable that represents an OlkControl object.

Remarks

For controls that do not support a drop-down list, the value of this property is Null (Nothing for Visual Basic).

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkControl.VerticalLayout Property (Outlook)

 Copy code hover
[image]

OlkControl.VerticalLayout Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlVerticalLayout constant that specifies any alignment in the vertical direction of this control with other selected controls on the form, or whether the control is adjusted in the vertical direction automatically when the form's length is changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .VerticalLayout

expression A variable that represents an OlkControl object.

See also

Concepts

OlkControl Class

Other resources

OlkControl Object Members


OlkDateControl Object (Outlook)

 Copy code hover
[image]

OlkDateControl Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports the drop-down date picker used in inspectors for task and appointment items to select a date.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Date Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is an example of the date control at runtime. This control supports Microsoft Windows themes.

This control can bind to any built-in or custom DateTime field. However, the control does not support any date format setting for the field, nor does it support the select range behavior that is available in the appointment inspector.

If the Click event is implemented but the DropButtonClick event is not implemented, then clicking the drop button will fire only the Click event.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkDateControl Object Members


OlkDateControl Members (Outlook)

 Copy code hover
[image]

OlkDateControl Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports the drop-down date picker used in inspectors for task and appointment items to select a date.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the calendar in the date control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
DropDown | Expands the calendar portion of the date control.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Date | Returns or sets the currently selected Date value with the time set to 12:00 AM. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
ShowNoneButton | Returns or sets a Boolean that specifies whether to display the None button in the date control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkDateControl Properties (Outlook)

 Copy code hover
[image]

OlkDateControl Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Date | Returns or sets the currently selected Date value with the time set to 12:00 AM. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
ShowNoneButton | Returns or sets a Boolean that specifies whether to display the None button in the date control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkDateControl.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkDateControl.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkDateControl object.

Remarks

The default value for this property is False.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.AutoWordSelect Property (Outlook)

 Copy code hover
[image]

OlkDateControl.AutoWordSelect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoWordSelect

expression A variable that represents an OlkDateControl object.

Remarks

The default value is True.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.BackColor Property (Outlook)

 Copy code hover
[image]

OlkDateControl.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkDateControl object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000005, "Window."

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkDateControl.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkDateControl object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Date Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Date Property (Outlook)
See also Send feedback

Returns or sets the currently selected Date value with the time set to 12:00 AM. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Date

expression A variable that represents an OlkDateControl object.

Remarks

When getting this property, the default value is the current date with the time set to 12:00 AM. When setting this property, any time information will be ignored; the time will be set to 12:00 AM.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Enabled Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkDateControl object.

Remarks

The default value is True.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.EnterFieldBehavior Property (Outlook)

 Copy code hover
[image]

OlkDateControl.EnterFieldBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnterFieldBehavior

expression A variable that represents an OlkDateControl object.

Remarks

The default value is olEnterFieldBehaviorSelectAll.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Font Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Font Property (Outlook)
See also Send feedback

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkDateControl object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkDateControl.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkDateControl object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.HideSelection Property (Outlook)

 Copy code hover
[image]

OlkDateControl.HideSelection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HideSelection

expression A variable that represents an OlkDateControl object.

Remarks

The default value of this property is True.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Locked Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkDateControl object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkDateControl.MouseIcon Property (Outlook)
See also Send feedback

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkDateControl object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkDateControl.MousePointer Property (Outlook)
See also Send feedback

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkDateControl object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.ShowNoneButton Property (Outlook)

 Copy code hover
[image]

OlkDateControl.ShowNoneButton Property (Outlook)
See also Send feedback

Returns or sets a Boolean that specifies whether to display the None button in the date control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowNoneButton

expression A variable that represents an OlkDateControl object.

Remarks

The default value is True.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Text Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Text Property (Outlook)
See also Send feedback

Returns or sets a String that is the text displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents an OlkDateControl object.

Remarks

The default value of the Text property is the empty string.

The Text property provides the same value as the Value property, but the value is strongly typed as a String.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkDateControl.TextAlign Property (Outlook)
See also Send feedback

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkDateControl object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Value Property (Outlook)

 Copy code hover
[image]

OlkDateControl.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkDateControl object.

Remarks

The value is the same as the value of Text, except that this property is Variant and Text is strongly typed as String.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl Methods (Outlook)

 Copy code hover
[image]

OlkDateControl Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
DropDown | Expands the calendar portion of the date control.


OlkDateControl.DropDown Method (Outlook)

 Copy code hover
[image]

OlkDateControl.DropDown Method (Outlook)
See also Send feedback

Published: July 16, 2012

Expands the calendar portion of the date control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropDown

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl Events (Outlook)

 Copy code hover
[image]

OlkDateControl Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the calendar in the date control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkDateControl.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkDateControl.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkDateControl object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkDateControl.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Change Event (Outlook)

 Copy code hover
[image]

OlkDateControl.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Click Event (Outlook)

 Copy code hover
[image]

OlkDateControl.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkDateControl.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.DropButtonClick Event (Outlook)

 Copy code hover
[image]

OlkDateControl.DropButtonClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks the drop button to expand the calendar in the date control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropButtonClick

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Enter Event (Outlook)

 Copy code hover
[image]

OlkDateControl.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the control actually receives the focus from a control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkDateControl object.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.Exit Event (Outlook)

 Copy code hover
[image]

OlkDateControl.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkDateControl.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkDateControl.KeyPress Event (Outlook)
See also Send feedback

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkDateControl.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkDateControl.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkDateControl.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkDateControl.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkDateControl.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkDateControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkDateControl Object

Other resources

OlkDateControl Object Members


OlkFrameHeader Object (Outlook)

 Copy code hover
[image]

OlkFrameHeader Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that provides a separator between sections in a form.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Frame Header Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is an example of a frame header control at runtime. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkFrameHeader Object Members


OlkFrameHeader Members (Outlook)

 Copy code hover
[image]

OlkFrameHeader Members (Outlook)
Send feedback

A control that provides a separator between sections in a form.

Properties

Name | Description
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkFrameHeader Properties (Outlook)

 Copy code hover
[image]

OlkFrameHeader Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkFrameHeader.Alignment Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.Alignment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Alignment

expression A variable that represents an OlkFrameHeader object.

Remarks

The default value is olAlignmentLeft.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.Caption Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents an OlkFrameHeader object.

Remarks

The default value is an empty string. The Forms Designer sets this property to the control's default name.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.Enabled Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkFrameHeader object.

Remarks

The default value is False.

When the control is disabled, the contents of the control appear dimmed.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.Font Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkFrameHeader object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkFrameHeader object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

The frame header control has only the foreground color and not the background color.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkFrameHeader object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkFrameHeader.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkFrameHeader.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkFrameHeader object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkFrameHeader Object

Other resources

OlkFrameHeader Object Members


OlkInfoBar Object (Outlook)

 Copy code hover
[image]

OlkInfoBar Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that provides an area to display specific information on a custom form.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook InfoBar Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is an example of this control at runtime. This control supports Microsoft Windows themes.

If there is no information to display, this control will automatically resize to a height of zero.

You can specify only the placement of the control, as there are no configurable options or settings other than its position.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkInfoBar Object Members


OlkInfoBar Members (Outlook)

 Copy code hover
[image]

OlkInfoBar Members (Outlook)
Send feedback

Published: July 16, 2012

A control that provides an area to display specific information on a custom form.

Events

Name | Description
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkInfoBar Properties (Outlook)

 Copy code hover
[image]

OlkInfoBar Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.


OlkInfoBar.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkInfoBar.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkInfoBar object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkInfoBar.MousePointer Property (Outlook)
See also Send feedback

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkInfoBar object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar Events (Outlook)

 Copy code hover
[image]

OlkInfoBar Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkInfoBar.Click Event (Outlook)

 Copy code hover
[image]

OlkInfoBar.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is clicked, either through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkInfoBar object.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkInfoBar.DoubleClick Event (Outlook)
See also Send feedback

Occurs when the control is double-clicked through user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkInfoBar object.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkInfoBar.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkInfoBar object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkInfoBar.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkInfoBar object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkInfoBar.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkInfoBar.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkInfoBar object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkInfoBar Object

Other resources

OlkInfoBar Object Members


OlkLabel Object (Outlook)

 Copy code hover
[image]

OlkLabel Object (Outlook)
See also Send feedback

Published: July 16, 2012

The basic label control, used for displaying text for read-only purposes.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Label Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of the label control at runtime showing the default caption. This control supports Microsoft Windows themes.

The label control typically provides information to or serves as a label for another control.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkLabel Object Members


OlkLabel Members (Outlook)

 Copy code hover
[image]

OlkLabel Members (Outlook)
Send feedback

Published: July 16, 2012

The basic label control, used for displaying text for read-only purposes.

Events

Name | Description
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
UseHeaderColor | Returns or sets a Boolean that indicates whether the label control should use the foreground color to match the current Windows XP or Windows Vista theme. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkLabel Properties (Outlook)

 Copy code hover
[image]

OlkLabel Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
UseHeaderColor | Returns or sets a Boolean that indicates whether the label control should use the foreground color to match the current Windows XP or Windows Vista theme. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkLabel.Accelerator Property (Outlook)

 Copy code hover
[image]

OlkLabel.Accelerator Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Accelerator

expression A variable that represents an OlkLabel object.

Remarks

The default value is an empty string, meaning there is no hot key. If the property is set with a string of more than one character, the value will be truncated to the first character.

You cannot use digits in an accelerator.

When the accelerator key for a label is pressed, the next control in the tab order receives the focus, not the label control.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkLabel.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkLabel object.

Remarks

The default value for this property is False.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.BackColor Property (Outlook)

 Copy code hover
[image]

OlkLabel.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkLabel object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x8000000F, "Button Face."

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkLabel.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkLabel object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.BorderStyle Property (Outlook)

 Copy code hover
[image]

OlkLabel.BorderStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BorderStyle

expression A variable that represents an OlkLabel object.

Remarks

The default value is olBorderStyleSingle.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.Caption Property (Outlook)

 Copy code hover
[image]

OlkLabel.Caption Property (Outlook)
See also Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents an OlkLabel object.

Remarks

The default value is an empty string. The Forms Designer sets this property to the control's default name.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.Enabled Property (Outlook)

 Copy code hover
[image]

OlkLabel.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkLabel object.

Remarks

The default value is True.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.Font Property (Outlook)

 Copy code hover
[image]

OlkLabel.Font Property (Outlook)
See also Send feedback

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkLabel object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkLabel.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkLabel object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkLabel.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkLabel object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkLabel.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkLabel object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkLabel.TextAlign Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkLabel object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.UseHeaderColor Property (Outlook)

 Copy code hover
[image]

OlkLabel.UseHeaderColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates whether the label control should use the foreground color to match the current Windows XP or Windows Vista theme. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .UseHeaderColor

expression A variable that represents an olkLabel object.

Remarks

This property is intended for label controls in a message form displayed in the Reading Pane and in the Inspector. If the property is True, then the label should use the foreground color that matches the current Windows theme. If the property is False, then the label should use the foreground color indicated by the ForeColor property.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.WordWrap Property (Outlook)

 Copy code hover
[image]

OlkLabel.WordWrap Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WordWrap

expression A variable that represents an OlkLabel object.

Remarks

The default value is True.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel Events (Outlook)

 Copy code hover
[image]

OlkLabel Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkLabel.Click Event (Outlook)

 Copy code hover
[image]

OlkLabel.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkLabel object.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkLabel.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkLabel object.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkLabel.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkLabel object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkLabel.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkLabel object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkLabel.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkLabel.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkLabel object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkLabel Object

Other resources

OlkLabel Object Members


OlkListBox Object (Outlook)

 Copy code hover
[image]

OlkListBox Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports displaying a scrollable list of items.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook List Box Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of the list box control that has been bound to the Sensitivity field at runtime. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkListBox Object Members


OlkListBox Members (Outlook)

 Copy code hover
[image]

OlkListBox Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports displaying a scrollable list of items.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the selection in the list displayed by the control changes
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
AddItem | Adds an item to the list, optionally specifying an index for the new item to appear in the list.
Clear | Removes all objects from the list.
Copy | Copies the current selection in the drop-down list to the clipboard.
GetItem | Obtains a String that represents an item at the specified location in the list.
GetSelected | Returns a Boolean that indicates if the indexed item is currently selected.
RemoveItem | Removes the specified item from the list.
SetItem | Sets the item at the specified location in the list to the specified value.
SetSelected | Sets the selected state of an item at the specified location in the list to the given Selected value.

Properties

Name | Description
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
ListCount | Returns a Long that specifies the number of elements in the drop-down list of the list box control. Read-only.
ListIndex | Returns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MatchEntry | Returns or sets an olMatchEntry constant that indicates how the control searches its list as the user types. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
MultiSelect | Returns or sets an OlMultiSelect constant that specifies the range of items that can be selected in the list box control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
TopIndex | Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list. Read/write.
Value | Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.


OlkListBox Properties (Outlook)

 Copy code hover
[image]

OlkListBox Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
ListCount | Returns a Long that specifies the number of elements in the drop-down list of the list box control. Read-only.
ListIndex | Returns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MatchEntry | Returns or sets an olMatchEntry constant that indicates how the control searches its list as the user types. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
MultiSelect | Returns or sets an OlMultiSelect constant that specifies the range of items that can be selected in the list box control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
TopIndex | Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list. Read/write.
Value | Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.


OlkListBox.BackColor Property (Outlook)

 Copy code hover
[image]

OlkListBox.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkListBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000005, "Window."

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.BorderStyle Property (Outlook)

 Copy code hover
[image]

OlkListBox.BorderStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BorderStyle

expression A variable that represents an OlkListBox object.

Remarks

The default value is olBorderStyleSingle.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Enabled Property (Outlook)

 Copy code hover
[image]

OlkListBox.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkListBox object.

Remarks

The default value is True.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Font Property (Outlook)

 Copy code hover
[image]

OlkListBox.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkListBox object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkListBox.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkListBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.ListCount Property (Outlook)

 Copy code hover
[image]

OlkListBox.ListCount Property (Outlook)
See also Send feedback

Returns a Long that specifies the number of elements in the drop-down list of the list box control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ListCount

expression A variable that represents an OlkListBox object.

Remarks

The default value is zero, indicating that there are no items in the list.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.ListIndex Property (Outlook)

 Copy code hover
[image]

OlkListBox.ListIndex Property (Outlook)
See also Send feedback

Returns or sets a Long that indicates the location of the currently selected element in the list of the combo box control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ListIndex

expression A variable that represents an OlkListBox object.

Remarks

ListIndex is a zero-based value indexing into the array of items in the list. The default value is -1, indicating that no item is selected.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Locked Property (Outlook)

 Copy code hover
[image]

OlkListBox.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkListBox object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MatchEntry Property (Outlook)

 Copy code hover
[image]

OlkListBox.MatchEntry Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olMatchEntry constant that indicates how the control searches its list as the user types. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MatchEntry

expression A variable that represents an OlkListBox object.

Remarks

The default value is olMatchEntryComplete.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkListBox.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkListBox object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkListBox.MousePointer Property (Outlook)
See also Send feedback

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkListBox object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MultiSelect Property (Outlook)

 Copy code hover
[image]

OlkListBox.MultiSelect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMultiSelect constant that specifies the range of items that can be selected in the list box control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MultiSelect

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Text Property (Outlook)

 Copy code hover
[image]

OlkListBox.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that is the text displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents an OlkListBox object.

Remarks

The default value of the Text property is the empty string.

The Text property provides the same value as the Value property, but the value is strongly typed as a String.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkListBox.TextAlign Property (Outlook)
See also Send feedback

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkListBox object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.TopIndex Property (Outlook)

 Copy code hover
[image]

OlkListBox.TopIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that represents the index of the item at the top of the displayed portion of the list. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TopIndex

expression A variable that represents an OlkListBox object.

Remarks

As the list scrolls, the item at the top of the list will change, and the value of this property will change to reflect the item currently displayed at the top of the list.

The index value is zero-based. The default value is -1, indicating that no special ordering should be applied.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Value Property (Outlook)

 Copy code hover
[image]

OlkListBox.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content selected in the list displayed by the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkListBox object.

Remarks

The value is the same as the value of Text, except that this property is Variant and Text is strongly typed as String.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox Methods (Outlook)

 Copy code hover
[image]

OlkListBox Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddItem | Adds an item to the list, optionally specifying an index for the new item to appear in the list.
Clear | Removes all objects from the list.
Copy | Copies the current selection in the drop-down list to the clipboard.
GetItem | Obtains a String that represents an item at the specified location in the list.
GetSelected | Returns a Boolean that indicates if the indexed item is currently selected.
RemoveItem | Removes the specified item from the list.
SetItem | Sets the item at the specified location in the list to the specified value.
SetSelected | Sets the selected state of an item at the specified location in the list to the given Selected value.


OlkListBox.AddItem Method (Outlook)

 Copy code hover
[image]

OlkListBox.AddItem Method (Outlook)
See also Send feedback

Adds an item to the list, optionally specifying an index for the new item to appear in the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddItem(ItemText, Index)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
ItemText | Required | String | Value to be added to the list in the list box control.
Index | Optional | Long | A 0-based value that specifies the order of the new item in the list.

Remarks

If the value of Index is equal to or larger than the number of elements in the list, the new item will be added to the end of the list.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Clear Method (Outlook)

 Copy code hover
[image]

OlkListBox.Clear Method (Outlook)
See also Send feedback

Removes all objects from the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .Clear

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Copy Method (Outlook)

 Copy code hover
[image]

OlkListBox.Copy Method (Outlook)
See also Send feedback

Copies the current selection in the drop-down list to the clipboard.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.GetItem Method (Outlook)

 Copy code hover
[image]

OlkListBox.GetItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a String that represents an item at the specified location in the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetItem(Index)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.

Return Value

A String value that represents the item at the specified location in the list.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount -1), then an out-of-bounds error will be returned.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.GetSelected Method (Outlook)

 Copy code hover
[image]

OlkListBox.GetSelected Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the indexed item is currently selected.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetSelected(Index)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.

Return Value

A Boolean value that is True if the specified item is currently selected, False otherwise.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.RemoveItem Method (Outlook)

 Copy code hover
[image]

OlkListBox.RemoveItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the specified item from the list.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoveItem(Index)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value indexing into the array of items in the list.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.SetItem Method (Outlook)

 Copy code hover
[image]

OlkListBox.SetItem Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the item at the specified location in the list to the specified value.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetItem(Index, Item)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.
Item | Required | String | The value to be used to update the list at the specified location.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.SetSelected Method (Outlook)

 Copy code hover
[image]

OlkListBox.SetSelected Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the selected state of an item at the specified location in the list to the given Selected value.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetSelected(Index, Selected)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A zero-based value that specifies the location of an item in the list.
Selected | Required | Boolean | True to indicate that the item should be selected, False to indicate that the item should not be selected.

Remarks

If Index is outside the range of the allowed values (between zero and ListCount-1), then an out-of-bounds error will be returned.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox Events (Outlook)

 Copy code hover
[image]

OlkListBox Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the selection in the list displayed by the control changes
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkListBox.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkListBox.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkListBox object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkListBox.BeforeUpdate Event (Outlook)
See also Send feedback

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Change Event (Outlook)

 Copy code hover
[image]

OlkListBox.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the selection in the list displayed by the control changes

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Click Event (Outlook)

 Copy code hover
[image]

OlkListBox.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkListBox.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkListBox object.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Enter Event (Outlook)

 Copy code hover
[image]

OlkListBox.Enter Event (Outlook)
See also Send feedback

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkListBox object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.Exit Event (Outlook)

 Copy code hover
[image]

OlkListBox.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkListBox.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkListBox.KeyPress Event (Outlook)
See also Send feedback

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkListBox.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkListBox.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkListBox.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkListBox.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkListBox.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkListBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkListBox Object

Other resources

OlkListBox Object Members


OlkOptionButton Object (Outlook)

 Copy code hover
[image]

OlkOptionButton Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports a single exclusive selection within a defined group of option button choices.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Option Button Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of an option button control at runtime. This control supports Microsoft Windows themes.

Typically more than one option button control is defined in a group. Each option button control in the group provides a single, mutually exclusive choice. Selecting one option button in the group will automatically remove the prior selection of another option button in the same group.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkOptionButton Object Members


OlkOptionButton Members (Outlook)

 Copy code hover
[image]

OlkOptionButton Members (Outlook)
Send feedback

A control that supports a single exclusive selection within a defined group of option button choices.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
GroupName | Returns or sets a String that identifies a group of mutually exclusive option button controls. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
Value | Returns or sets a Variant that represents the state of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkOptionButton Properties (Outlook)

 Copy code hover
[image]

OlkOptionButton Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Accelerator | Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.
Alignment | Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
GroupName | Returns or sets a String that identifies a group of mutually exclusive option button controls. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
Value | Returns or sets a Variant that represents the state of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkOptionButton.Accelerator Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Accelerator Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the accelerator or hot key for the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Accelerator

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is an empty string, meaning there is no hot key. If the property is set with a string of more than one character, the value will be truncated to the first character.

You cannot use digits in an accelerator.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Alignment Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Alignment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olAlignment constant that indicates the position of a control relative to its caption. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Alignment

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is olAlignmentLeft.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.BackColor Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkOptionButton object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x8000000F, "Button Face."

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Caption Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is based on the control's name. The position of the caption relative to the check box is determined by the Alignment property.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Enabled Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is True.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Font Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Font Property (Outlook)
See also Send feedback

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkOptionButton object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkOptionButton object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.GroupName Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.GroupName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that identifies a group of mutually exclusive option button controls. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .GroupName

expression A variable that represents an OlkOptionButton object.

Remarks

Only one member in the group can be selected at a time. Selecting a new member of the group automatically removes the previous selection of any other group member.

The default value is an empty string.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.MouseIcon Property (Outlook)
See also Send feedback

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkOptionButton object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Value Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the state of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkOptionButton object.

Remarks

For the option button control, the value is either True or False, representing whether the button has been selected or not. The default value is False.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.WordWrap Property (Outlook)

 Copy code hover
[image]

OlkOptionButton.WordWrap Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WordWrap

expression A variable that represents an OlkOptionButton object.

Remarks

The default value is True.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton Events (Outlook)

 Copy code hover
[image]

OlkOptionButton Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkOptionButton.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.AfterUpdate Event (Outlook)
See also Send feedback

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkOptionButton object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Change Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkOptionButton object.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Click Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkOptionButton object.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.DoubleClick Event (Outlook)
See also Send feedback

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkOptionButton object.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Enter Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.Enter Event (Outlook)
See also Send feedback

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkOptionButton object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.Exit Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.Exit Event (Outlook)
See also Send feedback

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.KeyPress Event (Outlook)
See also Send feedback

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.KeyUp Event (Outlook)
See also Send feedback

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkOptionButton.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkOptionButton.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkOptionButton object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkOptionButton Object

Other resources

OlkOptionButton Object Members


OlkPageControl Object (Outlook)

 Copy code hover
[image]

OlkPageControl Object (Outlook)
See also Send feedback

A control that displays the contents of a page.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Page Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor. This control supports Microsoft Windows themes.

Currently this control supports two Outlook pages: the free/busy scheduling page and the meeting request tracking page. The following is an example of the page control displaying a free/busy schedule at runtime.

The following is an example of the page control displaying a meeting request tracking page at runtime.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkPageControl Object Members


OlkPageControl Members (Outlook)

 Copy code hover
[image]

OlkPageControl Members (Outlook)
Send feedback

Published: July 16, 2012

A control that displays the contents of a page.

Properties

Name | Description
Page | Returns or sets an OlPageType constant that specifies the type of page that will be displayed in this control. Read/write.


OlkPageControl Properties (Outlook)

 Copy code hover
[image]

OlkPageControl Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Page | Returns or sets an OlPageType constant that specifies the type of page that will be displayed in this control. Read/write.


OlkPageControl.Page Property (Outlook)

 Copy code hover
[image]

OlkPageControl.Page Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlPageType constant that specifies the type of page that will be displayed in this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Page

expression A variable that represents an OlkPageControl object.

Remarks

The default value is olPageTypePlanner.

See also

Concepts

OlkPageControl Object

Other resources

OlkPageControl Object Members


OlkSenderPhoto Object (Outlook)

 Copy code hover
[image]

OlkSenderPhoto Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that displays the sender's contact picture for items that can be received via e-mail.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Sender Photo Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor. This control supports Microsoft Windows themes.

If no contact item or contact picture exists for the sender, the control is blank. Right-clicking the control at runtime will display the sender's persona menu, an example of which is shown below.

Double-clicking the control will display the contact item inspector.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto Members (Outlook)

 Copy code hover
[image]

OlkSenderPhoto Members (Outlook)
Send feedback

Published: July 16, 2012

A control that displays the sender's contact picture for items that can be received via e-mail.

Events

Name | Description
Change | Occurs when the sender's contact picture has changed.
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Properties

Name | Description
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
PreferredHeight | Returns a Long that specifies the application-preferred height of the sender picture. Read-only.
PreferredWidth | Returns a Long that specifies the application-preferred width of the sender picture. Read-only.


OlkSenderPhoto Properties (Outlook)

 Copy code hover
[image]

OlkSenderPhoto Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
PreferredHeight | Returns a Long that specifies the application-preferred height of the sender picture. Read-only.
PreferredWidth | Returns a Long that specifies the application-preferred width of the sender picture. Read-only.


OlkSenderPhoto.Enabled Property (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkSenderPhoto object.

Remarks

The default value is True.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.MouseIcon Property (Outlook)
See also Send feedback

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkSenderPhoto object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkSenderPhoto object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.PreferredHeight Property (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.PreferredHeight Property (Outlook)
See also Send feedback

Returns a Long that specifies the application-preferred height of the sender picture. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PreferredHeight

expression A variable that represents an OlkSenderPhoto object.

Remarks

The value is expressed in units of pixels. The default value is 96.

You can use this property and the PreferredWidth property to simulate Outlook's behavior to render, resize, and align the sender picture in a standard form.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.PreferredWidth Property (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.PreferredWidth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long that specifies the application-preferred width of the sender picture. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PreferredWidth

expression A variable that represents an OlkSenderPhoto object.

Remarks

The value is expressed in units of pixels. The default value is 72.

You can use this property and the PreferredHeight property to simulate Outlook's behavior to render, resize, and align the sender picture in a standard form.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto Events (Outlook)

 Copy code hover
[image]

OlkSenderPhoto Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
Change | Occurs when the sender's contact picture has changed.
Click | Occurs when the control is clicked, either through user action or programmatically.
DoubleClick | Occurs when the control is double-clicked through user action.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkSenderPhoto.Change Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the sender's contact picture has changed.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkSenderPhoto object.

Remarks

The change of the sender's contact picture usually means that the PreferredWidth and PreferredHeight properties have changed as well. Therefore, this event can be used as an indication of the necessity to resize the control.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.Click Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is clicked, either through user action or programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkSenderPhoto object.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control is double-clicked through user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkSenderPhoto object.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkSenderPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkSenderPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkSenderPhoto.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkSenderPhoto.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkSenderPhoto object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkSenderPhoto Object

Other resources

OlkSenderPhoto Object Members


OlkTextBox Object (Outlook)

 Copy code hover
[image]

OlkTextBox Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that supports a single or multiple-line data entry.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Text Box Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer.

The following is an example of a text box control that has been bound to the Organizer field. This control supports Microsoft Windows themes.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkTextBox Object Members


OlkTextBox Members (Outlook)

 Copy code hover
[image]

OlkTextBox Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports a single or multiple-line data entry.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
Clear | Removes the text in the text box.
Copy | Copies the contents of the control to the clipboard.
Cut | Removes the contents of the control and copies the contents to the clipboard.
Paste | Pastes the contents of the clipboard in the control.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
DragBehavior | Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
EnterKeyBehavior | Returns or sets a Boolean that defines the way the ENTER key behaves in the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
IntegralHeight | Returns or sets a Boolean that specifies whether this control displays full lines of text. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
MultiLine | Returns or sets a Boolean that specifies whether a control can accept and display multiple lines of text. Read/write.
PasswordChar | Returns or sets a String that specifies a placeholder character that is to be displayed repetitively as a string instead of the actual characters entered in the text box. Read/write.
Scrollbars | Returns or sets an olScrollBars constant that specifies whether the control has a vertical scroll bar, horizontal scroll bar, or both. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that specifies the number of characters in the current selection. Read/write.
SelStart | Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.
SelText | Returns a String that represents the currently selected portion of the value of the text box. Read-only.
TabKeyBehavior | Returns or sets a Boolean that specifies how the control responds to the TAB key. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkTextBox Properties (Outlook)

 Copy code hover
[image]

OlkTextBox Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
DragBehavior | Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
EnterKeyBehavior | Returns or sets a Boolean that defines the way the ENTER key behaves in the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
IntegralHeight | Returns or sets a Boolean that specifies whether this control displays full lines of text. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
MultiLine | Returns or sets a Boolean that specifies whether a control can accept and display multiple lines of text. Read/write.
PasswordChar | Returns or sets a String that specifies a placeholder character that is to be displayed repetitively as a string instead of the actual characters entered in the text box. Read/write.
Scrollbars | Returns or sets an olScrollBars constant that specifies whether the control has a vertical scroll bar, horizontal scroll bar, or both. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that specifies the number of characters in the current selection. Read/write.
SelStart | Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.
SelText | Returns a String that represents the currently selected portion of the value of the text box. Read-only.
TabKeyBehavior | Returns or sets a Boolean that specifies how the control responds to the TAB key. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.


OlkTextBox.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkTextBox.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkTextBox object.

Remarks

The default value for this property is False.

For a single-line text box, setting AutoSize to True automatically sets the width of the display area to the length of the text in the text box.

For a multiline text box that contains no text, setting AutoSize to True automatically displays the text as a column. The width of the text column is set to accommodate the widest letter of that font size. The height of the text column is set to display the entire text of the text box. For a multiline text box that contains text, setting AutoSize to True automatically extends the text box vertically to display the entire text. The width of the text box does not change.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.AutoTab Property (Outlook)

 Copy code hover
[image]

OlkTextBox.AutoTab Property (Outlook)
See also Send feedback

Returns or sets a Boolean that specifies if a tab is inserted automatically when the control has been filled to the maximum length specified. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoTab

expression A variable that represents an OlkTextBox object.

Remarks

The default value for this property is False.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.AutoWordSelect Property (Outlook)

 Copy code hover
[image]

OlkTextBox.AutoWordSelect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoWordSelect

expression A variable that represents an OlkTextBox object.

Remarks

The default value is True.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.BackColor Property (Outlook)

 Copy code hover
[image]

OlkTextBox.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkTextBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000005, "Window."

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.BorderStyle Property (Outlook)

 Copy code hover
[image]

OlkTextBox.BorderStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BorderStyle

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olBorderStyleSingle.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.DragBehavior Property (Outlook)

 Copy code hover
[image]

OlkTextBox.DragBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDragBehavior Enumeration constant that indicates whether the system enables the drag-and-drop feature for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DragBehavior

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olDragDropDisabled.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Enabled Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkTextBox object.

Remarks

The default value is True.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.EnterFieldBehavior Property (Outlook)

 Copy code hover
[image]

OlkTextBox.EnterFieldBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnterFieldBehavior

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olEnterFieldBehaviorSelectAll.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.EnterKeyBehavior Property (Outlook)

 Copy code hover
[image]

OlkTextBox.EnterKeyBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that defines the way the ENTER key behaves in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnterKeyBehavior

expression A variable that represents an OlkTextBox object.

Remarks

When this property is True, pressing ENTER creates a new line. When this property is False, pressing ENTER moves the focus to the next control in tab order. The default value for this property is False.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Font Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkTextBox object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkTextBox.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkTextBox object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.HideSelection Property (Outlook)

 Copy code hover
[image]

OlkTextBox.HideSelection Property (Outlook)
See also Send feedback

Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HideSelection

expression A variable that represents an OlkTextBox object.

Remarks

The default value of this property is True.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.IntegralHeight Property (Outlook)

 Copy code hover
[image]

OlkTextBox.IntegralHeight Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether this control displays full lines of text. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IntegralHeight

expression A variable that represents an OlkTextBox object.

Remarks

If this property is True, the control displays fill lines of text; otherwise it displays partial lines. The default value is True.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Locked Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkTextBox object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MaxLength Property (Outlook)

 Copy code hover
[image]

OlkTextBox.MaxLength Property (Outlook)
See also Send feedback

Returns or sets a Long that specifies the maximum number of characters for the Value of this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MaxLength

expression A variable that represents an OlkTextBox object.

Remarks

The default value is zero, which only means that no maximum length for the value has been defined for this control. A maximum length may still be in place based on available memory or other factors.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkTextBox.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkTextBox object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkTextBox.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MultiLine Property (Outlook)

 Copy code hover
[image]

OlkTextBox.MultiLine Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a control can accept and display multiple lines of text. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Multiline

expression A variable that represents an OlkTextBox object.

Remarks

The default value is False.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.PasswordChar Property (Outlook)

 Copy code hover
[image]

OlkTextBox.PasswordChar Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that specifies a placeholder character that is to be displayed repetitively as a string instead of the actual characters entered in the text box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .PasswordChar

expression A variable that represents an OlkTextBox object.

Remarks

A common application of setting this property to True is password entry, where you would not want to display the actual characters of the password that the user enters in the text box. The default value is an empty string.

Only one character is accepted for the value of this property. If a string of more than one character is set, only the first character will be used as the placeholder character and the rest will be ignored.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Scrollbars Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Scrollbars Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olScrollBars constant that specifies whether the control has a vertical scroll bar, horizontal scroll bar, or both. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Scrollbars

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olScrollBarsNone.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.SelectionMargin Property (Outlook)

 Copy code hover
[image]

OlkTextBox.SelectionMargin Property (Outlook)
See also Send feedback

Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelectionMargin

expression A variable that represents an OlkTextBox object.

Remarks

If True, clicking in the margin causes selection of text. If False, this action does not select any text. The default value is False.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.SelLength Property (Outlook)

 Copy code hover
[image]

OlkTextBox.SelLength Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies the number of characters in the current selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelLength

expression A variable that represents an OlkTextBox object.

Remarks

The current selection is specified by SelText, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is zero, which means no text is currently selected.

The SelLength property is always valid, even when the control does not have focus.

Setting SelLength to a value less than zero causes an error. Attempting to set the value greater than MaxLength results in setting SelLength to MaxLength.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.SelStart Property (Outlook)

 Copy code hover
[image]

OlkTextBox.SelStart Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that specifies either the starting point of the selected text or the insertion point if no text has been selected. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelStart

expression A variable that represents an OlkTextBox object.

Remarks

The current selection is specified by SelText, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is zero, which means no text is selected and the insertion point is at the beginning.

The SelStart property is always valid, even when the control does not have focus. Setting SelStart to a value less than zero causes an error. Setting SelStart to a value greater than MaxLength will reset SelStart to MaxLength. Changing the value of SelStart cancels any existing selection, places the insertion point in the text, and sets the SelLength property to zero.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.SelText Property (Outlook)

 Copy code hover
[image]

OlkTextBox.SelText Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the currently selected portion of the value of the text box. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelText

expression A variable that represents an OlkTextBox object.

Remarks

SelText represents the current selection, which is a portion of the control's Value. The maximum number of characters that can be supported for Value is MaxLength.

The default value is an empty string.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.TabKeyBehavior Property (Outlook)

 Copy code hover
[image]

OlkTextBox.TabKeyBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies how the control responds to the TAB key. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TabKeyBehavior

expression A variable that represents an OlkTextBox object.

Remarks

If this property is True, pressing TAB inserts a tab character in the text box. If this property is False, focus moves to the next control in the tab order.

The default value is False.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Text Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that is the text displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents an OlkTextBox object.

Remarks

The default value of the Text property is the empty string.

The Text property provides the same value as the Value property, but the value is strongly typed as a String.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkTextBox.TextAlign Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkTextBox object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Value Property (Outlook)

 Copy code hover
[image]

OlkTextBox.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkTextBox object.

Remarks

The value is the same as the value of Text, except that this property is Variant and Text is strongly typed as String.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.WordWrap Property (Outlook)

 Copy code hover
[image]

OlkTextBox.WordWrap Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .WordWrap

expression A variable that represents an OlkTextBox object.

Remarks

The default value is True.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox Methods (Outlook)

 Copy code hover
[image]

OlkTextBox Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Clear | Removes the text in the text box.
Copy | Copies the contents of the control to the clipboard.
Cut | Removes the contents of the control and copies the contents to the clipboard.
Paste | Pastes the contents of the clipboard in the control.


OlkTextBox.Clear Method (Outlook)

 Copy code hover
[image]

OlkTextBox.Clear Method (Outlook)
See also Send feedback

Removes the text in the text box.

Version Information

Version Added: Outlook 2007

Syntax

expression .Clear

expression A variable that represents an OlkTextBox object.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Copy Method (Outlook)

 Copy code hover
[image]

OlkTextBox.Copy Method (Outlook)
See also Send feedback

Copies the contents of the control to the clipboard.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy

expression A variable that represents an OlkTextBox object.

Remarks

The data is copied in unformatted text format, replacing the existing contents of the clipboard.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Cut Method (Outlook)

 Copy code hover
[image]

OlkTextBox.Cut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the contents of the control and copies the contents to the clipboard.

Version Information

Version Added: Outlook 2007

Syntax

expression .Cut

expression A variable that represents an OlkTextBox object.

Remarks

The data is copied to the clipboard in unformatted text format, replacing the existing contents of the clipboard.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Paste Method (Outlook)

 Copy code hover
[image]

OlkTextBox.Paste Method (Outlook)
See also Send feedback

Pastes the contents of the clipboard in the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Paste

expression A variable that represents an OlkTextBox object.

Remarks

The contents of the clipboard are pasted in unformatted text.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox Events (Outlook)

 Copy code hover
[image]

OlkTextBox Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkTextBox.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkTextBox.AfterUpdate Event (Outlook)
See also Send feedback

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkTextBox object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkTextBox.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Change Event (Outlook)

 Copy code hover
[image]

OlkTextBox.Change Event (Outlook)
See also Send feedback

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkTextBox object.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Click Event (Outlook)

 Copy code hover
[image]

OlkTextBox.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkTextBox object.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkTextBox.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkTextBox object.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Enter Event (Outlook)

 Copy code hover
[image]

OlkTextBox.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkTextBox object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.Exit Event (Outlook)

 Copy code hover
[image]

OlkTextBox.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkTextBox.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkTextBox.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkTextBox.KeyUp Event (Outlook)
See also Send feedback

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkTextBox.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkTextBox.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTextBox.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkTextBox.MouseUp Event (Outlook)
See also Send feedback

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkTextBox object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTextBox Object

Other resources

OlkTextBox Object Members


OlkTimeControl Object (Outlook)

 Copy code hover
[image]

OlkTimeControl Object (Outlook)
See also Send feedback

Published: July 16, 2012

A control that displays the Outlook time drop-down menu.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Time Control to the control toolbox. You can only add this control to a form region in an Outlook form using the forms designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The time control has several different modes which are exposed via properties on the control. It can be bound to any DateTime property, and can be bound to the same property as a date control to provide the capability to select both date and time.

The following is an example of the time control at runtime. This control supports Microsoft Windows themes.

If the Click event is implemented but the DropButtonClick event is not implemented, then clicking the drop button will fire only the Click event.

If you bind the time control to the start time or the end time of an appointment item, you must use an add-in to control enabling and disabling of the time control. In particular, when the user sets the appointment as an all-day event, you must use code to disable the time controls for the start time and the end time, and enable the controls only when the user clears this setting.

For more information about Outlook controls, see Controls in a Custom Form. For examples of add-ins in C# and Visual Basic .NET that use Outlook controls, see code sample downloads on MSDN.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkTimeControl Object Members


OlkTimeControl Members (Outlook)

 Copy code hover
[image]

OlkTimeControl Members (Outlook)
Send feedback

Published: July 16, 2012

A control that displays the Outlook time drop-down menu.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the time drop-down list in the time control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
DropDown | Expands the time drop-down list of the time control.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
IntervalTime | Returns or sets a Date that specifies the number of minutes displayed as an interval used for the olTimeStyleTimeDuration style setting on the time control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
ReferenceTime | Returns or sets a Date that specifies a reference time used for the olTimeStyleTimeDuration style setting on the time control. Read/write.
Style | Returns or sets an OlTimeStyle constant that specifies the style of the time control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Time | Returns or sets a Date that represents the time value currently selected in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkTimeControl Properties (Outlook)

 Copy code hover
[image]

OlkTimeControl Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AutoSize | Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.
BackColor | Returns or sets a Long that indicates the background color of the control. Read/write.
BackStyle | Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
EnterFieldBehavior | Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.
Font | Returns a StdFont that represents the font used to render the text inside the control. Read-only.
ForeColor | Returns or sets a Long that indicates the foreground color of the control. Read/write.
HideSelection | Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.
IntervalTime | Returns or sets a Date that specifies the number of minutes displayed as an interval used for the olTimeStyleTimeDuration style setting on the time control. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
ReferenceTime | Returns or sets a Date that specifies a reference time used for the olTimeStyleTimeDuration style setting on the time control. Read/write.
Style | Returns or sets an OlTimeStyle constant that specifies the style of the time control. Read/write.
Text | Returns or sets a String that is the text displayed in the control. Read/write.
TextAlign | Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.
Time | Returns or sets a Date that represents the time value currently selected in the control. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkTimeControl.AutoSize Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.AutoSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that automatically sizes the control to display the entire contents. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoSize

expression A variable that represents an OlkTimeControl object.

Remarks

The default value for this property is False.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.AutoWordSelect Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.AutoWordSelect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether a word or a character is the basic unit used to extend a selection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoWordSelect

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is True.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.BackColor Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.BackColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the background color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackColor

expression A variable that represents an OlkTimeControl object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000005, "Window."

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.BackStyle Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.BackStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olBackStyle constant that changes the background style of the control between transparent and opaque. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BackStyle

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is olBackStyleOpaque.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Enabled Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is True.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.EnterFieldBehavior Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.EnterFieldBehavior Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an olEnterFieldBehavior constant that specifies the selection behavior when entering the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EnterFieldBehavior

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is olEnterFieldBehaviorSelectAll.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Font Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Font Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a StdFont that represents the font used to render the text inside the control. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Font

expression A variable that represents an OlkTimeControl object.

Remarks

The font is expressed as the Microsoft Windows type StdFont.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.ForeColor Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.ForeColor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the foreground color of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForeColor

expression A variable that represents an OlkTimeControl object.

Remarks

This property is of the type OLE_COLOR which is a Long value. The default value for this property is 0x80000008, "Window Text."

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.HideSelection Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.HideSelection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies if a selection is displayed or hidden for the control when the control loses focus. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HideSelection

expression A variable that represents an OlkTimeControl object.

Remarks

The default value of this property is True.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.IntervalTime Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.IntervalTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date that specifies the number of minutes displayed as an interval used for the olTimeStyleTimeDuration style setting on the time control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IntervalTime

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is 30.

The minimum value for IntervalTime is 1 and the maximum value is 1440. Assigning a value outside of this range will result in the nearest edge value being used instead.

When Style is olTimeStyleTimeDuration, the date control displays the value of ReferenceTime as the first selectable time value, shows additional intervals (specified by IntervalTime) starting from the ReferenceTime value, and shows the duration of an event.

The default value for ReferenceTime is 30 Dec 1899 12:00 AM. In this case, the time control will display 30 Dec 1899 12:00 AM as the first selectable time. A value of 60 for IntervalTime will mark 30 Dec 1899 1:00 AM as the first interval.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Locked Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkTimeControl object.

Remarks

The custom picture is of the Microsoft Windows type StdPicture. The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.MousePointer Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.ReferenceTime Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.ReferenceTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date that specifies a reference time used for the olTimeStyleTimeDuration style setting on the time control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReferenceTime

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is 12/30/1899.

When Style is olTimeStyleTimeDuration, the date control displays the value of ReferenceTime as the first selectable time value, shows additional intervals (specified by IntervalTime) starting from the ReferenceTime value, and shows the duration of an event.

The default value for ReferenceTime is 30 Dec 1899 12:00 AM. In this case, the time control will display 30 Dec 1899 12:00 AM as the first selectable time. A value of 60 for IntervalTime will mark 30 Dec 1899 1:00 AM as the first interval.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Style Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Style Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTimeStyle constant that specifies the style of the time control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Style

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is olTimeStyleTimeOnly.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Text Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that is the text displayed in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents an OlkTimeControl object.

Remarks

The default value of the Text property is the empty string.

The Text property provides the same value as the Value property, but the value is strongly typed as a String.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.TextAlign Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.TextAlign Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTextAlign constant that specifies how text is aligned in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TextAlign

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is olTextAlignLeft in left-to-right languages such as English.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Time Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Time Property (Outlook)
See also Send feedback

Returns or sets a Date that represents the time value currently selected in the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Time

expression A variable that represents an OlkTimeControl object.

Remarks

The default value is Dec 30, 1899 12:00 AM.

When using the time control to indicate a duration (that is, the Style is olTimeStyleDuration), if the duration is longer than 24 hours, the Time property will indicate the duration from Dec 30, 1899 12:00 AM. For example, a duration spanning 24 hours will return a Date value of Dec 31 1899 12:00 AM. If this is a duration value for an appointment and you would like to determine an end time for the appointment, you can add this value to the ReferenceTime property value.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Value Property (Outlook)

 Copy code hover
[image]

OlkTimeControl.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkTimeControl object.

Remarks

The value is the same as the value of Text, except that this property is Variant and Text is strongly typed as String.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl Methods (Outlook)

 Copy code hover
[image]

OlkTimeControl Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
DropDown | Expands the time drop-down list of the time control.


OlkTimeControl.DropDown Method (Outlook)

 Copy code hover
[image]

OlkTimeControl.DropDown Method (Outlook)
See also Send feedback

Expands the time drop-down list of the time control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropDown

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl Events (Outlook)

 Copy code hover
[image]

OlkTimeControl Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the time drop-down list in the time control.
Enter | Occurs before the control actually receives the focus from a control on the same form.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkTimeControl.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkTimeControl object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving BeforeUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate

  3. Control data is updated

  4. AfterUpdate

  5. Exit: User moves focus away from control

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Change Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Click Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.DropButtonClick Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.DropButtonClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks the drop button to expand the time drop-down list in the time control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropButtonClick

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Enter Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the control actually receives the focus from a control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkTimeControl object.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.Exit Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains in this control.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.KeyDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.MouseDown Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.MouseMove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeControl.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkTimeControl.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkTimeControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | Integer | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | Integer | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTimeControl Object

Other resources

OlkTimeControl Object Members


OlkTimeZoneControl Object (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl Object (Outlook)
See also Send feedback

A control that supports a selection from a drop-down list of time zones.

Version Information

Version Added: Outlook 2007

Remarks

Before you use this control for the first time in the forms designer, add the Microsoft Outlook Time Zone Control to the control toolbox. You can only add this control to a form region in an Outlook form using the Forms Designer; you cannot add this control to a Visual Basic UserForm object in the Visual Basic Editor.

The following is an example of a time zone control. The time zone data can be obtained from the Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones.

If an appointment item was originally created with a time zone value that no longer exists, the appointment time will be converted to the current local time zone.

See also

Concepts

Outlook Object Model Reference

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl Members (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl Members (Outlook)
Send feedback

Published: July 16, 2012

A control that supports a selection from a drop-down list of time zones.

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the drop-down list in the time zone control, or when the DropDown method is called programmatically.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.

Methods

Name | Description
DropDown | Expands the drop-down portion of the time zone control.

Properties

Name | Description
AppointmentTimeField | Returns or sets an OlAppointmentTimeField constant that specifies the time field on the appointment that the control binds against. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
SelectedTimeZoneIndex | Returns or sets an index into the Application.TimeZones collection that determines the selected time zone. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkTimeZoneControl Properties (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AppointmentTimeField | Returns or sets an OlAppointmentTimeField constant that specifies the time field on the appointment that the control binds against. Read/write.
BorderStyle | Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.
Enabled | Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.
Locked | Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.
MouseIcon | Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.
MousePointer | Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.
SelectedTimeZoneIndex | Returns or sets an index into the Application.TimeZones collection that determines the selected time zone. Read/write.
Value | Returns or sets a Variant that represents the content of the control. Read/write.


OlkTimeZoneControl.AppointmentTimeField Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.AppointmentTimeField Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlAppointmentTimeField constant that specifies the time field on the appointment that the control binds against. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AppointmentTimeField

expression A variable that represents an OlkTimeZoneControl object.

Remarks

This control does not support standard data binding.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.BorderStyle Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.BorderStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBorderStyle constant that defines the style of the border around the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BorderStyle

expression A variable that represents an OlkTimeZoneControl object.

Remarks

The default value is olBorderStyleSingle.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Enabled Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates if the control is allowed to function. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents an OlkTimeZoneControl object.

Remarks

The default value is True.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Locked Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Locked Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that specifies whether or not the control is locked from being changed. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Locked

expression A variable that represents an OlkTimeZoneControl object.

Remarks

The default value is False.

When the control is locked, the control does not have a "disabled" appearance, but the user cannot edit the contents of the control.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.MouseIcon Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.MouseIcon Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a StdPicture that represents a custom picture to the mouse cursor for this control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseIcon

expression A variable that represents an OlkTimeZoneControl object.

Remarks

The default value is Null (Nothing in Visual Basic).

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.MousePointer Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.MousePointer Property (Outlook)
See also Send feedback

Returns or sets an OlMousePointer constant that specifies the type of pointer displayed when the user positions the mouse over the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MousePointer

expression A variable that represents an OlkTimeZoneControl object.

Remarks

The default value is olMousePointerDefault.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.SelectedTimeZoneIndex Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.SelectedTimeZoneIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an index into the Application.TimeZones collection that determines the selected time zone. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SelectedTimeZoneIndex

expression A variable that represents an OlkTimeZoneControl object.

Remarks

SelectedTimeZoneIndex is 1-based, and a value of zero (0) means that no time zone has been selected.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Value Property (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant that represents the content of the control. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Value

expression A variable that represents an OlkTimeZoneControl object.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl Methods (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
DropDown | Expands the drop-down portion of the time zone control.


OlkTimeZoneControl.DropDown Method (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.DropDown Method (Outlook)
See also Send feedback

Expands the drop-down portion of the time zone control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropDown

expression A variable that represents an OlkTimeZoneControl object.

Remarks

Simulates the user clicking the drop button on the control. This method causes the DropButtonClick event to fire.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl Events (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
AfterUpdate | Occurs after the data in the control has been changed through the user interface.
BeforeUpdate | Occurs when the data in the control is changed through the user interface and is about to be saved to the item.
Change | Occurs when the Value property changes.
Click | Occurs when the user clicks inside the control.
DoubleClick | Occurs when the user double-clicks inside the control.
DropButtonClick | Occurs when the user clicks the drop button to expand the drop-down list in the time zone control, or when the DropDown method is called programmatically.
Enter | Occurs when the control receives focus, immediately after the previous control's Exit event.
Exit | Occurs just after the focus passes from this control to another control on the same form.
KeyDown | Occurs when a user presses a key.
KeyPress | Occurs when the user presses an ANSI key.
KeyUp | Occurs when the user releases a key.
MouseDown | Occurs when the user presses a mouse button on the control.
MouseMove | Occurs after a mouse movement has been registered over the control.
MouseUp | Occurs after the user releases a mouse button that has been pressed on the control.


OlkTimeZoneControl.AfterUpdate Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.AfterUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the data in the control has been changed through the user interface.

Version Information

Version Added: Outlook 2007

Syntax

expression .AfterUpdate

expression A variable that represents an OlkTimeZoneControl object.

Remarks

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate occurs

  3. Control data is updated

  4. AfterUpdate occurs

  5. Exit occurs: User moves focus away from control

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.BeforeUpdate Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.BeforeUpdate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the data in the control is changed through the user interface and is about to be saved to the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeUpdate(Cancel)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation will not be completed and the property bound to the control will not be updated.

Remarks

Canceling this property will revert the control to the current value of the property and return the focus to the control.

BeforeUpdate and AfterUpdate can occur any time the data in the control is being saved to the item. The typical sequence of events involving AfterUpdate for this control is as follows:

  1. User focuses on the control

  2. BeforeUpdate occurs

  3. Control data is updated

  4. AfterUpdate occurs

  5. Exit occurs: User moves focus away from control

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Change Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Change Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the Value property changes.

Version Information

Version Added: Outlook 2007

Syntax

expression .Change

expression A variable that represents an OlkTimeZoneControl object.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Click Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Click Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .Click

expression A variable that represents an OlkTimeZoneControl object.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.DoubleClick Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.DoubleClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user double-clicks inside the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .DoubleClick

expression A variable that represents an OlkTimeZoneControl object.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.DropButtonClick Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.DropButtonClick Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks the drop button to expand the drop-down list in the time zone control, or when the DropDown method is called programmatically.

Version Information

Version Added: Outlook 2007

Syntax

expression .DropButtonClick

expression A variable that represents an OlkTimeZoneControl object.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Enter Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Enter Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the control receives focus, immediately after the previous control's Exit event.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enter

expression A variable that represents an OlkTimeZoneControl object.

Remarks

This is similar to the GotFocus event exposed by managed-code controls or in Microsoft Visual Basic 6.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.Exit Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.Exit Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just after the focus passes from this control to another control on the same form.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exit(Cancel)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the exit operation is not completed and the focus remains on this control

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.KeyDown Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.KeyDown Event (Outlook)
See also Send feedback

Occurs when a user presses a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyDown(KeyCode, Shift)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | OlShiftState | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyDown event is accessible through the Shift parameter.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.KeyPress Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.KeyPress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user presses an ANSI key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyPress(KeyAscii)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyAscii | Required | Long | The numerical value of the key pressed.

Remarks

An ANSI key is one that produces a typeable character when the user presses it. The KeyPress event occurs when the user presses an ANSI key on a running form while the form or a control on it has the focus. The event can occur either before or after the key is released.

A KeyPress event does not occur under the following conditions:

  • Pressing TAB

  • Pressing ENTER

  • Pressing an arrow key

  • When a keystroke causes the focus to move from one control to another

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.KeyUp Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.KeyUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user releases a key.

Version Information

Version Added: Outlook 2007

Syntax

expression .KeyUp(KeyCode, Shift)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
KeyCode | Required | Long | The numerical value of the key pressed.
Shift | Required | OlShiftState | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.

Remarks

The state of the modifier keys (SHIFT, CTRL, or ALT) that are pressed during the KeyUp event is accessible through the Shift parameter.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.MouseDown Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.MouseDown Event (Outlook)
See also Send feedback

Occurs when the user presses a mouse button on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseDown(Button, Shift, X, Y)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | OlMouseButton | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | OlShiftState | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.MouseMove Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.MouseMove Event (Outlook)
See also Send feedback

Occurs after a mouse movement has been registered over the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseMove(Button, Shift, X, Y)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | OlMouseButton | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | OlShiftState | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

Remarks

Pressing the ALT key fires the MouseMove event.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OlkTimeZoneControl.MouseUp Event (Outlook)

 Copy code hover
[image]

OlkTimeZoneControl.MouseUp Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after the user releases a mouse button that has been pressed on the control.

Version Information

Version Added: Outlook 2007

Syntax

expression .MouseUp(Button, Shift, X, Y)

expression A variable that represents an OlkTimeZoneControl object.

Parameters

Name | Required/Optional | Data Type | Description
Button | Required | OlMouseButton | An OlMouseButton constant that specifies which button on the mouse has been pressed.
Shift | Required | OlShiftState | A bitwise-OR mask of constants in the OlShiftState enumeration that specifies whether the SHIFT, CTRL, or ALT keys have been pressed.
X | Required | [OLE_XPOS_CONTAINER] | Identifies the location of the mouse cursor on the X-axis relative to the form.
Y | Required | [OLE_YPOS_CONTAINER] | Identifies the location of the mouse cursor on the Y-axis relative to the form.

See also

Concepts

OlkTimeZoneControl Object

Other resources

OlkTimeZoneControl Object Members


OrderField Object (Outlook)

 Copy code hover
[image]

OrderField Object (Outlook)
See also Send feedback

Represents an order field, used to sort information in a view.

Version Information

Version Added: Outlook 2007

Remarks

Use the Add method of the OrderFields object to add an Outlook item property to the SortFields collection for the following objects derived from the View object:

  • BusinessCardView

  • CardView

  • IconView

  • TableView

Use the ViewXMLSchemaName property to obtain the name of the order field as referenced in the XML definition of the view.

OrderField objects contained in an OrderFields collection are applied to Outlook items displayed in the view in the order in which the objects are contained in the collection. For each OrderField object, use the IsDescending property to determine whether to sort the contents of the order field in ascending or descending order.

Example

The following Visual Basic for Applications (VBA) example iterates through the SortFields collection of the current TableView object, displaying the label and XML schema names of each OrderField object in the collection.

VBA Copy code Copy code
Private Sub DisplayTableViewSortFields()

 Dim objTableView As TableView

 Dim objOrderField As OrderField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the OrderFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field used to sort

 ' the items in the view.

 For Each objOrderField In objTableView.SortFields

 With objOrderField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' sort field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

OrderField Object Members


OrderField Members (Outlook)

 Copy code hover
[image]

OrderField Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an order field, used to sort information in a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsDescending | Returns or sets a Boolean value that indicates whether the contents of the OrderField object are sorted in descending order. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ViewXMLSchemaName | Returns a String value that represents the XML schema name for the property referenced by the OrderField object. Read-only.


OrderField Properties (Outlook)

 Copy code hover
[image]

OrderField Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsDescending | Returns or sets a Boolean value that indicates whether the contents of the OrderField object are sorted in descending order. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ViewXMLSchemaName | Returns a String value that represents the XML schema name for the property referenced by the OrderField object. Read-only.


OrderField.Application Property (Outlook)

 Copy code hover
[image]

OrderField.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OrderField object.

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderField.Class Property (Outlook)

 Copy code hover
[image]

OrderField.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OrderField object.

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderField.IsDescending Property (Outlook)

 Copy code hover
[image]

OrderField.IsDescending Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the contents of the OrderField object are sorted in descending order. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsDescending

expression A variable that represents an OrderField object.

Remarks

If this property is set to True, the contents of the property referenced by the OrderField object are sorted in descending order; otherwise, the contents are sorted in ascending order.

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderField.Parent Property (Outlook)

 Copy code hover
[image]

OrderField.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OrderField object.

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderField.Session Property (Outlook)

 Copy code hover
[image]

OrderField.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OrderField object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderField.ViewXMLSchemaName Property (Outlook)

 Copy code hover
[image]

OrderField.ViewXMLSchemaName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the XML schema name for the property referenced by the OrderField object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewXMLSchemaName

expression A variable that represents an OrderField object.

Remarks

The value of this property contains the name of the property as it is included within the XML definition of the view containing the ViewField object. This value may not match the name used to refer to the property when the OrderField object was defined.

Example

The following Visual Basic for Applications (VBA) example iterates through the SortFields collection of the current TableView object, displaying the label and XML schema names of each OrderField object in the collection.

VBA Copy code Copy code
Private Sub DisplayTableViewSortFields()

 Dim objTableView As TableView

 Dim objOrderField As OrderField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the OrderFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field used to sort

 ' the items in the view.

 For Each objOrderField In objTableView.SortFields

 With objOrderField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' sort field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

OrderField Object

Other resources

OrderField Object Members


OrderFields Object (Outlook)

 Copy code hover
[image]

OrderFields Object (Outlook)
See also Send feedback

Represents the collection of OrderField objects in a view.

Version Information

Version Added: Outlook 2007

Remarks

The OrderFields collection represents the Outlook item properties used to sort Outlook items displayed in the view. Use the Add method or the OrderFields collection to create a new order field for the following objects derived from the View object:

  • BusinessCardView

  • CardView

  • IconView

  • PeopleView

  • TableView

OrderField objects contained in an OrderFields collection are applied to Outlook items displayed in the view in the order in which the objects are contained in the collection.

Example

The following Visual Basic for Applications (VBA) example iterates through the SortFields collection of the current TableView object, displaying the label and XML schema names of each OrderField object in the collection.

Copy code Copy code
Private Sub DisplayTableViewSortFields()

 Dim objTableView As TableView

 Dim objOrderField As OrderField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the OrderFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field used to sort

 ' the items in the view.

 For Each objOrderField In objTableView.SortFields

 With objOrderField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' sort field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

OrderFields Object Members


OrderFields Members (Outlook)

 Copy code hover
[image]

OrderFields Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the collection of OrderField objects in a view.

Methods

Name | Description
Add | Creates a new OrderField object and appends it to the OrderFields collection.
Insert | Creates a new OrderField object and inserts it at the specified index within the OrderFields collection.
Item | Returns an OrderField object from the collection.
Remove | Removes an object from the collection.
RemoveAll | Removes all sorting properties from the OrderFields collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of OrderField objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OrderFields Properties (Outlook)

 Copy code hover
[image]

OrderFields Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of OrderField objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OrderFields.Application Property (Outlook)

 Copy code hover
[image]

OrderFields.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OrderFields object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Class Property (Outlook)

 Copy code hover
[image]

OrderFields.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OrderFields object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Count Property (Outlook)

 Copy code hover
[image]

OrderFields.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value indicating the count of OrderField objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an OrderFields object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Parent Property (Outlook)

 Copy code hover
[image]

OrderFields.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OrderFields object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Session Property (Outlook)

 Copy code hover
[image]

OrderFields.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OrderFields object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields Methods (Outlook)

 Copy code hover
[image]

OrderFields Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new OrderField object and appends it to the OrderFields collection.
Insert | Creates a new OrderField object and inserts it at the specified index within the OrderFields collection.
Item | Returns an OrderField object from the collection.
Remove | Removes an object from the collection.
RemoveAll | Removes all sorting properties from the OrderFields collection.


OrderFields.Add Method (Outlook)

 Copy code hover
[image]

OrderFields.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new OrderField object and appends it to the OrderFields collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(PropertyName, IsDescending)

expression A variable that represents an OrderFields object.

Parameters

Name | Required/Optional | Data Type | Description
PropertyName | Required | String | The name of the property to which the new object is associated.
IsDescending | Optional | Boolean | The value used to set the IsDescending property of the new OrderField object. If this value is not specified, the default value of the IsDescending property is used.

Return Value

An OrderField object that represents the new order field.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Insert Method (Outlook)

 Copy code hover
[image]

OrderFields.Insert Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new OrderField object and inserts it at the specified index within the OrderFields collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Insert(PropertyName, Index, IsDescending)

expression A variable that represents an OrderFields object.

Parameters

Name | Required/Optional | Data Type | Description
PropertyName | Required | String | The name of the property to which the new object is associated.
Index | Required | Variant | Either the index number at which to insert the new object, or a value used to match the ViewXMLSchemaName property value of an object in the collection at where the new object is to be inserted.
IsDescending | Optional | Boolean | The value used to set the IsDescending property of the new OrderField object. If this value is not specified, the default value of the IsDescending property is used.

Return Value

An OrderField object that represents the new order field.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Item Method (Outlook)

 Copy code hover
[image]

OrderFields.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderField object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents an OrderFields object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The value can be a one-based integer that indexes an OrderField object in the OrderFields collection, a string that matches the ViewXMLSchemaName property value of an OrderField object in the collection, or a field name as displayed in the Field Chooser.

Return Value

An OrderField object that represents the specified object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.Remove Method (Outlook)

 Copy code hover
[image]

OrderFields.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents an OrderFields object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the ViewXMLSchemaName property value of an object in the collection.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OrderFields.RemoveAll Method (Outlook)

 Copy code hover
[image]

OrderFields.RemoveAll Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes all sorting properties from the OrderFields collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoveAll

expression A variable that represents an OrderFields object.

See also

Concepts

OrderFields Object

Other resources

OrderFields Object Members


OutlookBarGroup Object (Outlook)

 Copy code hover
[image]

OutlookBarGroup Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a group of shortcuts in the Shortcuts pane of an explorer window.

Remarks

Use the Item method to retrieve the OutlookBarGroup object from an OutlookBarGroups object. Because the Name property is the default property of the OutlookBarGroup object, you can identify the group by name.

Example

The following example retrieves an OutlookBarGroup object by name.

Copy code Copy code
Set myOlBarGroup = myOutlookBarGroups.Item("Other Shortcuts")

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarGroup Object Members


OutlookBarGroup Members (Outlook)

 Copy code hover
[image]

OutlookBarGroup Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a group of shortcuts in the Shortcuts pane of an explorer window.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Shortcuts | Returns an OutlookBarShortcuts collection of shortcuts contained within the Shortcuts pane. Read-only.
ViewType | Returns or sets an OlOutlookBarViewType constant representing the view type of an OutlookBarGroup object. Read/write.


OutlookBarGroup Properties (Outlook)

 Copy code hover
[image]

OutlookBarGroup Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Shortcuts | Returns an OutlookBarShortcuts collection of shortcuts contained within the Shortcuts pane. Read-only.
ViewType | Returns or sets an OlOutlookBarViewType constant representing the view type of an OutlookBarGroup object. Read/write.


OutlookBarGroup.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarGroup object.

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarGroup object.

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.Name Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an OutlookBarGroup object.

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarGroup object.

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarGroup object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.Shortcuts Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.Shortcuts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OutlookBarShortcuts collection of shortcuts contained within the Shortcuts pane. Read-only.

Syntax

expression .Shortcuts

expression A variable that represents an OutlookBarGroup object.

Example

This Microsoft Visual Basic for Applications (VBA) example deletes all empty groups in the Shortcuts pane.

VBA Copy code Copy code
Sub DeleteEmptyGroups()
 Dim myOlBar As Outlook.OutlookBarPane
 Dim myOlGroup As Outlook.OutlookBarGroup
 Dim x As Integer

 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 For x = myOlBar.Contents.Groups.Count To 1 Step -1
 Set myOlGroup = myOlBar.Contents.Groups.Item(x)
 If myOlGroup.Shortcuts.Count = 0 Then
 myOlBar.Contents.Groups.Remove x
 End If
 Next x
End Sub

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroup.ViewType Property (Outlook)

 Copy code hover
[image]

OutlookBarGroup.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlOutlookBarViewType constant representing the view type of an OutlookBarGroup object. Read/write.

Syntax

expression .ViewType

expression An expression that returns a OutlookBarGroup object.

Remarks

This property does not have any effect on the icons displayed in the Shortcuts pane. Large icons have been removed and if this property is set to olLargeIcon, it will not have any effect. In previous versions of Microsoft Outlook, it returns or sets the icon view displayed by the specified Outlook Bar group.

See also

Concepts

OutlookBarGroup Object

Other resources

OutlookBarGroup Object Members


OutlookBarGroups Object (Outlook)

 Copy code hover
[image]

OutlookBarGroups Object (Outlook)
See also Send feedback

Contains a set of OutlookBarGroup objects representing all groups in the Outlook Bar.

Remarks

Use the Groups property to return the OutlookBarGroups object from the OutlookBarStorage object.

Use Groups(index), where index is the name of an available group, to return a single OutlookBarGroup object.

Example

The following Visual Basic for Applications (VBA) example retrieves the OutlookBarGroups collection from an OutlookBarStorage object.

VBA Copy code Copy code
Set myGroups = myOutlookBarStorage.Groups

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarGroups Object Members


OutlookBarGroups Members (Outlook)

 Copy code hover
[image]

OutlookBarGroups Members (Outlook)
Send feedback

Contains a set of OutlookBarGroup objects representing all groups in the Outlook Bar.

Events

Name | Description
BeforeGroupAdd | Occurs before a new group is added to the Shortcuts pane, either as a result of user action or through program code.
BeforeGroupRemove | Occurs before a new group is removed from the Shortcuts pane, either as a result of user action or through program code.
GroupAdd | Occurs when a new group has been added to the Shortcuts pane.

Methods

Name | Description
Add | Adds a new, empty group to the Shortcuts pane.
Item | Returns an OutlookBarGroup object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarGroups Properties (Outlook)

 Copy code hover
[image]

OutlookBarGroups Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarGroups.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarGroups object.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarGroups object.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Count Property (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an OutlookBarGroups object.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarGroups object.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarGroups object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups Methods (Outlook)

 Copy code hover
[image]

OutlookBarGroups Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds a new, empty group to the Shortcuts pane.
Item | Returns an OutlookBarGroup object from the collection.
Remove | Removes an object from the collection.


OutlookBarGroups.Add Method (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a new, empty group to the Shortcuts pane.

Syntax

expression .Add(Name, Index)

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the group being created.
Index | Optional | Long | The position at which the new group will be inserted in the Shortcuts pane. Position one is at the top of the bar.

Return Value

An OutlookBarGroup object that represents the new group.

Example

This Microsoft Visual Basic for Applications (VBA) example adds a group named Marketing as the last group in the Shortcuts pane.

VBA Copy code Copy code
Sub AddGroup()
 Dim myolBar As Outlook.OutlookBarPane

 Set myolBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 myolBar.Contents.Groups.Add "Marketing", myolBar.Contents.Groups.Count + 1
End Sub

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Item Method (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Item Method (Outlook)
See also Send feedback

Returns an OutlookBarGroup object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An OutlookBarGroup object that represents the specified object.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.Remove Method (Outlook)

 Copy code hover
[image]

OutlookBarGroups.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The name or 1-based index value of an object within a collection.

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups Events (Outlook)

 Copy code hover
[image]

OutlookBarGroups Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeGroupAdd | Occurs before a new group is added to the Shortcuts pane, either as a result of user action or through program code.
BeforeGroupRemove | Occurs before a new group is removed from the Shortcuts pane, either as a result of user action or through program code.
GroupAdd | Occurs when a new group has been added to the Shortcuts pane.


OutlookBarGroups.BeforeGroupAdd Event (Outlook)

 Copy code hover
[image]

OutlookBarGroups.BeforeGroupAdd Event (Outlook)
See also Send feedback

Occurs before a new group is added to the Shortcuts pane, either as a result of user action or through program code.

Syntax

expression .BeforeGroupAdd(Cancel)

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the group is not added to the Shortcuts pane.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Visual Basic for Applications (VBA) example prevents the user from adding a group to the Shortcuts pane. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Dim WithEvents myOlGroups As Outlook.OutlookBarGroups
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myOlGroups = myOlBar.Contents.Groups
End Sub

Private Sub myOlGroups_BeforeGroupAdd(Cancel As Boolean)
 Cancel = True
End Sub

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.BeforeGroupRemove Event (Outlook)

 Copy code hover
[image]

OutlookBarGroups.BeforeGroupRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before a new group is removed from the Shortcuts pane, either as a result of user action or through program code.

Syntax

expression .BeforeGroupRemove(Group, Cancel)

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
Group | Required | OutlookBarGroup | The OutlookBarGroup that is being removed.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the group is not removed from the Shortcuts pane.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example prevents the user from removing a group from the Shortcuts pane. The sample code must be placed in a class module such as ThisOutlookSession, and the Initialize_handler routine must be called before the event procedure can be called by Outlook. You will still be prompted when you try to delete a shortcut. However, the group will not be deleted even if you clicked Yes.

VBA Copy code Copy code
Dim WithEvents myOlGroups As Outlook.OutlookBarGroups
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.item("OutlookBar")
 Set myOlGroups = myOlBar.Contents.Groups
End Sub

Private Sub myOlGroups_BeforeGroupRemove(ByVal Group As OutlookBarGroup, Cancel As Boolean)
 Cancel = True
End Sub

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarGroups.GroupAdd Event (Outlook)

 Copy code hover
[image]

OutlookBarGroups.GroupAdd Event (Outlook)
See also Send feedback

Occurs when a new group has been added to the Shortcuts pane.

Syntax

expression .GroupAdd(NewGroup)

expression A variable that represents an OutlookBarGroups object.

Parameters

Name | Required/Optional | Data Type | Description
NewGroup | Required | OutlookBarGroup | The OutlookBarGroup that was added.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example adds a shortcut to the Calendar whenever a group is created. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myOlGroups As Outlook.OutlookBarGroups
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myOlGroups = myOlBar.Contents.Groups
End Sub

Private Sub myOlGroups_GroupAdd(ByVal NewGroup As Outlook.OutlookBarGroup)
 Dim myFolder As Outlook.Folder
 Set myFolder = myOlApp.GetNamespace("MAPI").GetDefaultFolder(olFolderCalendar)
 NewGroup.Shortcuts.Add myFolder, "Calendar"
End Sub

See also

Concepts

OutlookBarGroups Object

Other resources

OutlookBarGroups Object Members


OutlookBarPane Object (Outlook)

 Copy code hover
[image]

OutlookBarPane Object (Outlook)
See also Send feedback

Represents the Shortcuts pane in an explorer window.

Remarks

Use the Item method to retrieve the OutlookBarPane object from a Panes object. Because the Name property is the default property of the OutlookBarPane object, you can identify the OutlookBarPane object by name. For example:

Example

The following example retrieves an OutlookBarPane object by name.

Copy code Copy code
Set myOlBarPane = myPanes.Item("OutlookBar")

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarPane Object Members


OutlookBarPane Members (Outlook)

 Copy code hover
[image]

OutlookBarPane Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Shortcuts pane in an explorer window.

Events

Name | Description
BeforeNavigate | Occurs when the user clicks a shortcut in the Shortcuts pane to navigate to a different folder.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Contents | Returns the OutlookBarStorage object for the specified Outlook Bar pane. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean indicating the visible state of the specified object. Read/write.


OutlookBarPane Properties (Outlook)

 Copy code hover
[image]

OutlookBarPane Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Contents | Returns the OutlookBarStorage object for the specified Outlook Bar pane. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean indicating the visible state of the specified object. Read/write.


OutlookBarPane.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarPane object.

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarPane object.

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Contents Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Contents Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the OutlookBarStorage object for the specified Outlook Bar pane. Read-only.

Syntax

expression .Contents

expression A variable that represents an OutlookBarPane object.

Example

This Microsoft Visual Basic for Applications example displays a message listing the groups in the Outlook Bar.

VBA Copy code Copy code
Sub ListGroups()

 Dim myOlBar As Outlook.OutlookBarPane

 Dim myOlGroups As Outlook.OutlookBarGroups

 myMsg = "The groups in the Outlook Bar are:"

 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")

 Set myOlGroups = myOlBar.Contents.Groups

 For x = 1 To myOlGroups.Count

 myMsg = myMsg & Chr(13) & myOlGroups.Item(x)

 Next x

 MsgBox myMsg

End Sub

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Name Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents an OutlookBarPane object.

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarPane object.

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarPane object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane.Visible Property (Outlook)

 Copy code hover
[image]

OutlookBarPane.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean indicating the visible state of the specified object. Read/write.

Syntax

expression .Visible

expression A variable that represents an OutlookBarPane object.

Remarks

True to display the object; False to hide the object.

You can also use the ShowPane method or the IsPaneVisible method of an Explorer object to set or retrieve this value.

Example

This Microsoft Visual Basic for Applications (VBA) example toggles the visible state of the Shortcuts pane.

VBA Copy code Copy code
Sub ShowHideShortcutsBar()

 Dim myOlBar As Outlook.OutlookBarPane

 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")

 myOlBar.Visible = Not myOlBar.Visible

End Sub

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarPane Events (Outlook)

 Copy code hover
[image]

OutlookBarPane Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeNavigate | Occurs when the user clicks a shortcut in the Shortcuts pane to navigate to a different folder.


OutlookBarPane.BeforeNavigate Event (Outlook)

 Copy code hover
[image]

OutlookBarPane.BeforeNavigate Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user clicks a shortcut in the Shortcuts pane to navigate to a different folder.

Syntax

expression .BeforeNavigate(Shortcut, Cancel)

expression A variable that represents an OutlookBarPane object.

Parameters

Name | Required/Optional | Data Type | Description
Shortcut | Required | OutlookBarShortcut | The shortcut that the user clicked.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the current folder is not changed.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example prevents the user from using the Shortcuts pane to open the Notes folder. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook. If you do not have a shortcut to the Notes folder already, you need to create one to run this example.

VBA Copy code Copy code
Public WithEvents myOlPane As Outlook.OutlookBarPane

Public Sub Initialize_handler()

 Set myOlPane = Application.ActiveExplorer.Panes.Item("OutlookBar")

End Sub

Private Sub myOlPane_BeforeNavigate(ByVal Shortcut As Outlook.OutlookBarShortcut, Cancel As Boolean)

 If Shortcut.Name = "Notes" Then

 MsgBox "You cannot view the Notes folder."

 Cancel = True

 End If

End Sub

See also

Concepts

OutlookBarPane Object

Other resources

OutlookBarPane Object Members


OutlookBarShortcut Object (Outlook)

 Copy code hover
[image]

OutlookBarShortcut Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a shortcut in a group in the Shortcuts pane.

Remarks

Use the Item method to retrieve the OutlookBarShortcut object from an OutlookBarShortcuts object. Because the Name property is the default property of the OutlookBarShortcut object, you can identify the shortcut by name.

Example

The following example retrieves an OutlookBarShortcut object by name.

Copy code Copy code
Set myOlBarShortcut = myOutlookBarShortcuts.Item("Calendar")

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut Members (Outlook)

 Copy code hover
[image]

OutlookBarShortcut Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a shortcut in a group in the Shortcuts pane.

Methods

Name | Description
SetIcon | Sets the icon for the specified shortcut on the Shortcuts pane.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Target | Returns a Variant indicating the target of the specified shortcut in a Shortcuts pane group. Read-only.


OutlookBarShortcut Properties (Outlook)

 Copy code hover
[image]

OutlookBarShortcut Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Target | Returns a Variant indicating the target of the specified shortcut in a Shortcuts pane group. Read-only.


OutlookBarShortcut.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarShortcut object.

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarShortcut object.

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut.Name Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents an OutlookBarShortcut object.

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarShortcut object.

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarShortcut object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut.Target Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.Target Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Variant indicating the target of the specified shortcut in a Shortcuts pane group. Read-only.

Syntax

expression .Target

expression A variable that represents an OutlookBarShortcut object.

Remarks

The return type depends on the shortcut type. If the shortcut represents an Outlook folder, the return type is Folder. If the shortcut represents a file-system folder, the return type is an Object. If the shortcut represents a file-system path or URL, the return type is a String.

Example

This Microsoft Visual Basic for Applications (VBA) example steps through the shortcuts in the first Shortcuts pane group. It counts the number of shortcuts that are Outlook folders and displays the count.

VBA Copy code Copy code
Sub DeleteShortcuts()
 Dim myOlBar As Outlook.OutlookBarPane
 Dim myolGroup As Outlook.OutlookBarGroup
 Dim myOlShortcuts As Outlook.OutlookBarShortcuts
 Dim myOlShortcut As Outlook.OutlookBarShortcut
 Dim myTop As Integer
 Dim x As Integer
 Dim count As Integer

 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myolGroup = myOlBar.Contents.Groups.Item(1)
 Set myOlShortcuts = myolGroup.Shortcuts
 myTop = myOlShortcuts.Count
 For x = myTop To 1 Step -1
 Set myOlShortcut = myOlShortcuts.Item(x)
 If TypeName(myOlShortcut.Target) = "Folder" Then
 count = count + 1
 End If
 Next x
 MsgBox ("Number of shortcuts that are Outlook folders:" & count)
End Sub

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcut Methods (Outlook)

 Copy code hover
[image]

OutlookBarShortcut Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
SetIcon | Sets the icon for the specified shortcut on the Shortcuts pane.


OutlookBarShortcut.SetIcon Method (Outlook)

 Copy code hover
[image]

OutlookBarShortcut.SetIcon Method (Outlook)
See also Send feedback

Sets the icon for the specified shortcut on the Shortcuts pane.

Syntax

expression .SetIcon(Icon)

expression A variable that represents an OutlookBarShortcut object.

Parameters

Name | Required/Optional | Data Type | Description
Icon | Required | Variant | The path of the icon.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a group called MicrosoftSites and adds a shortcut to the Microsoft Network Web page. Then it sets the icon of the shortcut to the icon image MSN.ico located on the user's computer. The example assumes that this icon exists in the specified location.

VBA Copy code Copy code
 Sub CreateMSNShortcutWithIcon()

 Dim exp As Outlook.Explorer

 Dim pans As Outlook.Panes

 Dim bpan As Outlook.OutlookBarPane

 Dim bgrps As Outlook.OutlookBarGroups

 Dim bgrp As Outlook.OutlookBarGroup

 Dim bscs As Outlook.OutlookBarShortcuts

 Dim bsc As Outlook.OutlookBarShortcut

 Dim bsc2 As Outlook.OutlookBarShortcut

 Set exp = Application.ActiveExplorer

 Set pans = exp.Panes

 Set bpan = pans.Item("OutlookBar")

 Set bgrps = bpan.Contents.Groups

 Set bgrp = bgrps.Add("MicrosoftSites")

 Set bscs = bgrp.Shortcuts

 Set bsc = bscs.Add("http://www.msn.com", "MSN Home Page")

 bsc.SetIcon "C:\MSN.ico"

End Sub

See also

Concepts

OutlookBarShortcut Object

Other resources

OutlookBarShortcut Object Members


OutlookBarShortcuts Object (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of OutlookBarShortcut objects representing all shortcuts in a group in the Shortcuts pane.

Remarks

Use the Shortcuts property to return the OutlookBarShortcuts collection object from the OutlookBarGroup object.

Example

The following Microsoft Visual Basic for Applications (VBA) example shows how to retrieve the OutlookBarShortcuts object.

Copy code Copy code
Set myShortcuts = myOutlookBarGroup.Shortcuts

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts Members (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of OutlookBarShortcut objects representing all shortcuts in a group in the Shortcuts pane.

Events

Name | Description
BeforeShortcutAdd | Occurs before a new shortcut is added to a group in the Shortcuts pane, either as a result of user action or through program code.
BeforeShortcutRemove | Occurs before a new shortcut is removed from a group in the Shortcuts pane, either as a result of user action or through program code.
ShortcutAdd | Occurs when a new shortcut is added to a Shortcuts pane group.

Methods

Name | Description
Add | Adds a new shortcut to a group in the Shortcuts pane.
Item | Returns an OutlookBarShortcut object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarShortcuts Properties (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarShortcuts.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarShortcuts object.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarShortcuts object.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Count Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Count Property (Outlook)
See also Send feedback

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents an OutlookBarShortcuts object.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarShortcuts object.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarShortcuts object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts Methods (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds a new shortcut to a group in the Shortcuts pane.
Item | Returns an OutlookBarShortcut object from the collection.
Remove | Removes an object from the collection.


OutlookBarShortcuts.Add Method (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a new shortcut to a group in the Shortcuts pane.

Syntax

expression .Add(Target, Name, Index)

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
Target | Required | Variant | The target of the shortcut being created.
Name | Required | String | The name of the shortcut being created.
Index | Optional | Long | The position at which the new shortcut will be inserted in the Shortcuts pane group. Position one is at the top of the group.The Target type depends on the shortcut type. If the type is Folder, the shortcut represents a Microsoft Outlook folder. If the type is a String, the shortcut represents a file-system path or a URL.

Return Value

An OutlookBarShortcut object that represents the new shortcut.

Example

The following Microsoft Visual Basic for Applications example adds a shortcut to the Microsoft home page on the Web.

VBA Copy code Copy code
Sub AddShortcut()
 Dim myOlBar As Outlook.OutlookBarPane
 Dim myolGroup As Outlook.OutlookBarGroup
 Dim myOlShortcuts As Outlook.OutlookBarShortcuts

 Set myOlBar = Application.ActiveExplorer.panes.Item("OutlookBar")
 Set myolGroup = myOlBar.Contents.Groups.Item(1)
 Set myOlShortcuts = myolGroup.Shortcuts
 myOlShortcuts.Add "http://www.microsoft.com", _
 "Microsoft Home Page", 1
End Sub

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Item Method (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OutlookBarShortcut object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An OutlookBarShortcut object that represents the specified object.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.Remove Method (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The name or 1-based index value of an object within a collection.

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts Events (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeShortcutAdd | Occurs before a new shortcut is added to a group in the Shortcuts pane, either as a result of user action or through program code.
BeforeShortcutRemove | Occurs before a new shortcut is removed from a group in the Shortcuts pane, either as a result of user action or through program code.
ShortcutAdd | Occurs when a new shortcut is added to a Shortcuts pane group.


OutlookBarShortcuts.BeforeShortcutAdd Event (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.BeforeShortcutAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before a new shortcut is added to a group in the Shortcuts pane, either as a result of user action or through program code.

Syntax

expression .BeforeShortcutAdd(Cancel)

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the shortcut is not added to the group.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example prevents a user from adding a shortcut to the first group in the Shortcuts pane. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myOlShortcuts As Outlook.OutlookBarShortcuts
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myOlShortcuts = myOlBar.Contents.Groups.Item(1).Shortcuts
End Sub

Private Sub myOlShortcuts_BeforeShortcutAdd(Cancel As Boolean)
 MsgBox "You are not allowed to add a shortcut to this group."
 Cancel = True
End Sub

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.BeforeShortcutRemove Event (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.BeforeShortcutRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before a new shortcut is removed from a group in the Shortcuts pane, either as a result of user action or through program code.

Syntax

expression .BeforeShortcutRemove(Shortcut, Cancel)

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
Shortcut | Required | OutlookBarShortcut | The OutlookBarShortcut that is being removed.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the shortcut is not removed from the group.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

The following Microsoft Visual Basic for Applications (VBA) example prevents a user from removing a shortcut from the Shortcuts pane. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myOlShortcuts As Outlook.OutlookBarShortcuts
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myOlShortcuts = myOlBar.Contents.Groups.Item(1).Shortcuts
End Sub

Private Sub myOlShortcuts_BeforeShortcutRemove(ByVal Shortcut As OutlookBarShortcut, Cancel As Boolean)
 MsgBox "You are not allowed to remove a shortcut from this group."
 Cancel = True
End Sub

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarShortcuts.ShortcutAdd Event (Outlook)

 Copy code hover
[image]

OutlookBarShortcuts.ShortcutAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a new shortcut is added to a Shortcuts pane group.

Syntax

expression .ShortcutAdd(NewShortcut)

expression A variable that represents an OutlookBarShortcuts object.

Parameters

Name | Required/Optional | Data Type | Description
NewShortcut | Required | OutlookBarShortcut | The shortcut that is being added.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example changes the name of a Calendar shortcut when it is added to the first group in the Shortcuts pane. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents myOlSCuts As Outlook.OutlookBarShortcuts
Dim myOlBar As Outlook.OutlookBarPane

Sub Initialize_handler()
 Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")
 Set myOlSCuts = myOlBar.Contents.Groups.Item(1).Shortcuts
End Sub

Private Sub myOlSCuts_ShortcutAdd(ByVal NewShortcut As outlook.OutlookBarShortcut)
 Dim myNS As Outlook.NameSpace

 Set myNS = Application.GetNamespace("MAPI")
 If NewShortcut.Target.Name = "Calendar" Then
 NewShortcut.Name = myNS.CurrentUser & "'s Schedules"
 End If
End Sub

See also

Concepts

OutlookBarShortcuts Object

Other resources

OutlookBarShortcuts Object Members


OutlookBarStorage Object (Outlook)

 Copy code hover
[image]

OutlookBarStorage Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the storage for objects in the Outlook Bar.

Remarks

Use the Contents property of an OutlookBarPane object to retrieve the OutlookBarStorage object for the Outlook Bar.

Use the Groups property to retrieve the OutlookBarGroups object for the Outlook Bar.

Example

The following example retrieves an OutlookBarStorage object by name.

VBA Copy code Copy code
Set myOLBarStorage = myPanes.Item("OutlookBar").Contents

See also

Concepts

Outlook Object Model Reference

Other resources

OutlookBarStorage Object Members


OutlookBarStorage Members (Outlook)

 Copy code hover
[image]

OutlookBarStorage Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the storage for objects in the Outlook Bar.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Groups | Returns an OutlookBarGroups object representing the set of groups in the Shortcuts pane. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarStorage Properties (Outlook)

 Copy code hover
[image]

OutlookBarStorage Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Groups | Returns an OutlookBarGroups object representing the set of groups in the Shortcuts pane. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


OutlookBarStorage.Application Property (Outlook)

 Copy code hover
[image]

OutlookBarStorage.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents an OutlookBarStorage object.

See also

Concepts

OutlookBarStorage Object

Other resources

OutlookBarStorage Object Members


OutlookBarStorage.Class Property (Outlook)

 Copy code hover
[image]

OutlookBarStorage.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents an OutlookBarStorage object.

See also

Concepts

OutlookBarStorage Object

Other resources

OutlookBarStorage Object Members


OutlookBarStorage.Groups Property (Outlook)

 Copy code hover
[image]

OutlookBarStorage.Groups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OutlookBarGroups object representing the set of groups in the Shortcuts pane. Read-only.

Syntax

expression .Groups

expression A variable that represents an OutlookBarStorage object.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the number of groups in the Shortcuts pane.

VBA Copy code Copy code
Sub CountOlBarGroups()     Dim myOlBar As Outlook.OutlookBarPane     Dim myCount As Integer      Set myOlBar = Application.ActiveExplorer.Panes.Item("OutlookBar")     myCount = myOlBar.Contents.Groups.Count     MsgBox "There are " & myCount & " groups in the Shortcuts pane" End Sub

See also

Concepts

OutlookBarStorage Object

Other resources

OutlookBarStorage Object Members


OutlookBarStorage.Parent Property (Outlook)

 Copy code hover
[image]

OutlookBarStorage.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents an OutlookBarStorage object.

See also

Concepts

OutlookBarStorage Object

Other resources

OutlookBarStorage Object Members


OutlookBarStorage.Session Property (Outlook)

 Copy code hover
[image]

OutlookBarStorage.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents an OutlookBarStorage object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

OutlookBarStorage Object

Other resources

OutlookBarStorage Object Members


Pages Object (Outlook)

 Copy code hover
[image]

Pages Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains pages that represent the pages of an Inspector window.

Remarks

Every Inspector object has a Pages object defined, which is empty (count 0) if the Outlook item has never been customized before.

Use the ModifiedFormPages property to return the Pages object from an Inspector object.

Use the Add method to create a custom page (you can add as many as 5 customizable pages). Use the Name argument of the Add method to set the display name of the returned page. In addition to adding custom pages, you can use the Name argument to return the main page of an Inspector object for modification.

Use ModifiedFormPages(index), where index is the name or index number, to return a single page from a Pages object.

Example

The following example returns the Pages object for the active Inspector.

VBA Copy code Copy code
Set myPages = myItem.GetInspector.ModifiedFormPages

The following example returns a custom page with a default name (such as "Custom1").

VBA Copy code Copy code
Set myPage = myPages.Add

The following example returns a custom page named "My Page."

Copy code Copy code
Set myPage = myPages.Add("My Page")

The following example returns the Message page if the Inspector contains a mail message.

VBA Copy code Copy code
Set myPage = myPages.Add("Message")

The following example returns the General (main) page if the inspector contains a contact.

VBA Copy code Copy code
Set myPage = myPages.Add("General")

See also

Concepts

Object model (Outlook 2013 developer reference)

Other resources

Pages Members (Outlook)


Pages Members (Outlook)

 Copy code hover
[image]

Pages Members (Outlook)
Send feedback

Contains pages that represent the pages of an Inspector window.

Methods

Name | Description
Add | Creates a new page in the Pages collection.
Item | Returns a page from a collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Pages Properties (Outlook)

 Copy code hover
[image]

Pages Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Pages.Application Property (Outlook)

 Copy code hover
[image]

Pages.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Pages object.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages.Class Property (Outlook)

 Copy code hover
[image]

Pages.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Pages object.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages.Count Property (Outlook)

 Copy code hover
[image]

Pages.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Pages object.

See also

Concepts

Pages Object (Outlook)

Other resources

Pages Members (Outlook)


Pages.Parent Property (Outlook)

 Copy code hover
[image]

Pages.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Pages object.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages.Session Property (Outlook)

 Copy code hover
[image]

Pages.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Pages object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages Methods (Outlook)

 Copy code hover
[image]

Pages Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new page in the Pages collection.
Item | Returns a page from a collection.
Remove | Removes an object from the collection.


Pages.Add Method (Outlook)

 Copy code hover
[image]

Pages.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new page in the Pages collection.

Syntax

expression .Add Name

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the page.

Return Value

A Page object that represents the new page.

Remarks

The Pages collection is initially empty, and there is a limit of 5 customizable pages per collection.

See also

Concepts

Pages Object (Outlook)

Other resources

Pages Members (Outlook)


Pages.Item Method (Outlook)

 Copy code hover
[image]

Pages.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a page from a collection.

Syntax

expression .Item(Index)

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
varg | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object value that represents the specified object.

See also

Concepts

Pages Object (Outlook)

Other resources

Pages Members (Outlook)


Pages.Remove Method (Outlook)

 Copy code hover
[image]

Pages.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

Pages Object (Outlook)

Other resources

Pages Members (Outlook)


Panes Object (Outlook)

 Copy code hover
[image]

Panes Object (Outlook)
See also Send feedback

Contains the panes displayed by the specified Explorer.

Remarks

Use the Panes property to return the Panes collection object from an Explorer object.

Use the Item method to retrieve a specific pane.

For Microsoft Outlook 2000 and later, the Shortcuts pane is the only pane that you can access through the Panes object.

Example

The following Visual Basic for Applications (VBA) example retrieves the Panes object from an Explorer object.

Copy code Copy code
Set myPanes = myExplorer.Panes

The following example retrieves the OutlookBarPane object representing the Shortcuts pane.

Copy code Copy code
Set myOLBarPane = myExplorer.Panes.Item("OutlookBar")

See also

Concepts

Outlook Object Model Reference

Other resources

Panes Object Members


Panes Members (Outlook)

 Copy code hover
[image]

Panes Members (Outlook)
Send feedback

Published: July 16, 2012

Contains the panes displayed by the specified Explorer.

Methods

Name | Description
Item | Returns a pane from a collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Panes Properties (Outlook)

 Copy code hover
[image]

Panes Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Panes.Application Property (Outlook)

 Copy code hover
[image]

Panes.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Panes object.

See also

Concepts

Panes Object

Other resources

Panes Object Members


Panes.Class Property (Outlook)

 Copy code hover
[image]

Panes.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Panes object.

See also

Concepts

Panes Object

Other resources

Panes Object Members


Panes.Count Property (Outlook)

 Copy code hover
[image]

Panes.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Panes object.

See also

Concepts

Panes Object

Other resources

Panes Object Members


Panes.Parent Property (Outlook)

 Copy code hover
[image]

Panes.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Panes object.

See also

Concepts

Panes Object

Other resources

Panes Object Members


Panes.Session Property (Outlook)

 Copy code hover
[image]

Panes.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Panes object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Panes Object

Other resources

Panes Object Members


Panes Methods (Outlook)

 Copy code hover
[image]

Panes Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns a pane from a collection.


Panes.Item Method (Outlook)

 Copy code hover
[image]

Panes.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a pane from a collection.

Syntax

expression .Item(Index)

expression A variable that represents a Panes object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object value that represents the specified object.

See also

Concepts

Panes Object

Other resources

Panes Object Members


PeopleView Object (Outlook)

 Copy code hover
[image]

PeopleView Object (Outlook)
See also Send feedback

Represents a view that displays a list of all the contacts in the current Contacts folder, and details for a selected contact.

Version information

Version Added: Outlook 2013

See also

Concepts

Outlook Object Model Reference

Other resources

PeopleView Object Members


PeopleView Members (Outlook)

 Copy code hover
[image]

PeopleView Members (Outlook)
Send feedback

Represents a view that displays a list of all the contacts in the current Contacts folder, and details for a selected contact.

Methods

Name | Description
Apply | Applies the PeopleView object to the current view.
Copy | Creates a new View object based on the existing PeopleView object.
Delete | Deletes this object from the collection of views in the current folder.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets this built-in Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the PeopleView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the PeopleView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


PeopleView Properties (Outlook)

 Copy code hover
[image]

PeopleView Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the PeopleView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the PeopleView object is a built-in Outlook view. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


PeopleView.Application Property (Outlook)

 Copy code hover
[image]

PeopleView.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .Application

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Class Property (Outlook)

 Copy code hover
[image]

PeopleView.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .Class

expression A variable that represents a PeopleView object.

Property value

OLOBJECTCLASS

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Filter Property (Outlook)

 Copy code hover
[image]

PeopleView.Filter Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the filter for a view. Read/write.

Version information

Version Added: Outlook 2013

Syntax

expression .Filter

expression A variable that represents a PeopleView object.

Property value

STRING

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Language Property (Outlook)

 Copy code hover
[image]

PeopleView.Language Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the language setting for the view. Read/write.

Version information

Version Added: Outlook 2013

Syntax

expression .Language

expression A variable that represents a PeopleView object.

Property value

STRING

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

PeopleView.LockUserChanges Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.

Version information

Version Added: Outlook 2013

Syntax

expression .LockUserChanges

expression A variable that represents a PeopleView object.

Property value

BOOL

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Name Property (Outlook)

 Copy code hover
[image]

PeopleView.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Version information

Version Added: Outlook 2013

Syntax

expression .Name

expression A variable that represents a PeopleView object.

Property value

STRING

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Parent Property (Outlook)

 Copy code hover
[image]

PeopleView.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .Parent

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.SaveOption Property (Outlook)

 Copy code hover
[image]

PeopleView.SaveOption Property (Outlook)
See also Send feedback

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .SaveOption

expression A variable that represents a PeopleView object.

Property value

OLVIEWSAVEOPTION

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Session Property (Outlook)

 Copy code hover
[image]

PeopleView.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .Session

expression A variable that represents a PeopleView object.

Property value

_NAMESPACE

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.SortFields Property (Outlook)

 Copy code hover
[image]

PeopleView.SortFields Property (Outlook)
See also Send feedback

Returns an OrderFields object that represents the set of fields by which the items displayed in the PeopleView object are ordered. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .SortFields

expression A variable that represents a PeopleView object.

Property value

ORDERFIELDS

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Standard Property (Outlook)

 Copy code hover
[image]

PeopleView.Standard Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the PeopleView object is a built-in Outlook view. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .Standard

expression A variable that represents a PeopleView object.

Property value

BOOL

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.ViewType Property (Outlook)

 Copy code hover
[image]

PeopleView.ViewType Property (Outlook)
See also Send feedback

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version information

Version Added: Outlook 2013

Syntax

expression .ViewType

expression A variable that represents a PeopleView object.

Property value

OLVIEWTYPE

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.XML Property (Outlook)

 Copy code hover
[image]

PeopleView.XML Property (Outlook)
See also Send feedback

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version information

Version Added: Outlook 2013

Syntax

expression .XML

expression A variable that represents a PeopleView object.

Property value

STRING

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView Methods (Outlook)

 Copy code hover
[image]

PeopleView Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Apply | Applies the PeopleView object to the current view.
Copy | Creates a new View object based on the existing PeopleView object.
Delete | Deletes this object from the collection of views in the current folder.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets this built-in Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


PeopleView.Apply Method (Outlook)

 Copy code hover
[image]

PeopleView.Apply Method (Outlook)
See also Send feedback

Applies the PeopleView object to the current view.

Version information

Version Added: Outlook 2013

Syntax

expression .Apply

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Copy Method (Outlook)

 Copy code hover
[image]

PeopleView.Copy Method (Outlook)
See also Send feedback

Creates a new View object based on the existing PeopleView object.

Version information

Version Added: Outlook 2013

Syntax

expression .Copy(Name,SaveOption)

expression A variable that represents a PeopleView object.

Parameters

Name | Required/Optional | Data type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Delete Method (Outlook)

 Copy code hover
[image]

PeopleView.Delete Method (Outlook)
See also Send feedback

Deletes this object from the collection of views in the current folder.

Version information

Version Added: Outlook 2013

Syntax

expression .Delete

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.GoToDate Method (Outlook)

 Copy code hover
[image]

PeopleView.GoToDate Method (Outlook)
See also Send feedback

Changes the date used by the current view to display information.

Version information

Version Added: Outlook 2013

Syntax

expression .GoToDate(Date)

expression A variable that represents a PeopleView object.

Parameters

Name | Required/Optional | Data type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Reset Method (Outlook)

 Copy code hover
[image]

PeopleView.Reset Method (Outlook)
See also Send feedback

Resets this built-in Outlook view to its original settings.

Version information

Version Added: Outlook 2013

Syntax

expression .Reset

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PeopleView.Save Method (Outlook)

 Copy code hover
[image]

PeopleView.Save Method (Outlook)
See also Send feedback

Saves the view, or saves the changes to a view.

Version information

Version Added: Outlook 2013

Syntax

expression .Save

expression A variable that represents a PeopleView object.

See also

Other resources

PeopleView Object
PeopleView Members


PlaySoundRuleAction Object (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an action that plays a .wav file sound.

Version Information

Version Added: Outlook 2007

Remarks

PlaySoundRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has a PlaySound property. The PlaySound property always returns a PlaySoundRuleAction object. If the rule has an enabled rule action that plays a sound file, then PlaySoundRuleAction.Enabled property would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction Members (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an action that plays a .wav file sound.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionPlaySound, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
FilePath | Returns or sets a String that represents the full file path to a sound file (.wav). Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PlaySoundRuleAction Properties (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionPlaySound, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
FilePath | Returns or sets a String that represents the full file path to a sound file (.wav). Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PlaySoundRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.ActionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olRuleActionPlaySound, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a PlaySoundRuleAction object.

Remarks

The sound playing rule action is supported only by rules for receiving messages. For more information, see Specify Rule Actions.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.Application Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a PlaySoundRuleAction object.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.Class Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a PlaySoundRuleAction object.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a PlaySoundRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.FilePath Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.FilePath Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents the full file path to a sound file (.wav). Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FilePath

expression A variable that represents a PlaySoundRuleAction object.

Remarks

Returns an error if the path is invalid.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a PlaySoundRuleAction object.

Remarks

The parent object is the RuleAction object.

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PlaySoundRuleAction.Session Property (Outlook)

 Copy code hover
[image]

PlaySoundRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a PlaySoundRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

PlaySoundRuleAction Object

Other resources

PlaySoundRuleAction Object Members


PostItem Object (Outlook)

 Copy code hover
[image]

PostItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a post in a public folder that others may browse.

Remarks

Unlike a MailItem object, a PostItem object is not sent to a recipient. You use the Post method, which is analogous to the Send method for the MailItem object, to save the PostItem to the target public folder instead of mailing it.

Use the CreateItem or CreateItemFromTemplate method to create a PostItem object that represents a new post.

Use Items(index), where index is the index number of a post or a value used to match the default property of a post, to return a single PostItem object from a public folder.

Example

The following example returns a new post.

Copy code Copy code
Set myItem = myOlApp.CreateItem(olPostItem)

See also

Concepts

Outlook Object Model Reference

Other resources

PostItem Object Members


PostItem Members (Outlook)

 Copy code hover
[image]

PostItem Members (Outlook)
Send feedback

Represents a post in a public folder that others may browse.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
ClearConversationIndex | Clears the index of the conversation thread for the post.
ClearTaskFlag | Clears the PostItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a PostItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
Post | Sends (posts) the PostItem object.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the PostItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified item. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the PostItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent PostItem object. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the item was received. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this PostItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this PostItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this PostItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the PostItem object. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the PostItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


PostItem Properties (Outlook)

 Copy code hover
[image]

PostItem Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the PostItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified item. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the PostItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent PostItem object. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the item was received. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.
SenderName | Returns a String indicating the display name of the sender for the Outlook item. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
SentOn | Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this PostItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this PostItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this PostItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the PostItem object. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the PostItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


PostItem.Actions Property (Outlook)

 Copy code hover
[image]

PostItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Application Property (Outlook)

 Copy code hover
[image]

PostItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Attachments Property (Outlook)

 Copy code hover
[image]

PostItem.Attachments Property (Outlook)
See also Send feedback

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

PostItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a PostItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its PostItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

PostItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a PostItem object.

Remarks

This is a free-form text field.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Body Property (Outlook)

 Copy code hover
[image]

PostItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BodyFormat Property (Outlook)

 Copy code hover
[image]

PostItem.BodyFormat Property (Outlook)
See also Send feedback

Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.

Syntax

expression .BodyFormat

expression A variable that represents a PostItem object.

Remarks

The body text format determines the standard used to display the text of the message. Microsoft Outlook provides three body text format options: Plain Text, Rich Text (RTF), and HTML.

All text formatting will be lost when the BodyFormat property is switched from RTF to HTML and vice-versa.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Categories Property (Outlook)

 Copy code hover
[image]

PostItem.Categories Property (Outlook)
See also Send feedback

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a PostItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Class Property (Outlook)

 Copy code hover
[image]

PostItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Companies Property (Outlook)

 Copy code hover
[image]

PostItem.Companies Property (Outlook)
See also Send feedback

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a PostItem object.

Remarks

This is a free-form text field.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Conflicts Property (Outlook)

 Copy code hover
[image]

PostItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ConversationID Property (Outlook)

 Copy code hover
[image]

PostItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the PostItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a PostItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the PostItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

PostItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

PostItem.ConversationTopic Property (Outlook)
See also Send feedback

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.CreationTime Property (Outlook)

 Copy code hover
[image]

PostItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.DownloadState Property (Outlook)

 Copy code hover
[image]

PostItem.DownloadState Property (Outlook)
See also Send feedback

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a PostItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.EntryID Property (Outlook)

 Copy code hover
[image]

PostItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ExpiryTime Property (Outlook)

 Copy code hover
[image]

PostItem.ExpiryTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the item becomes invalid and can be deleted. Read/write.

Syntax

expression .ExpiryTime

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.FormDescription Property (Outlook)

 Copy code hover
[image]

PostItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.GetInspector Property (Outlook)

 Copy code hover
[image]

PostItem.GetInspector Property (Outlook)
See also Send feedback

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a PostItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.HTMLBody Property (Outlook)

 Copy code hover
[image]

PostItem.HTMLBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the HTML body of the specified item. Read/write.

Syntax

expression .HTMLBody

expression A variable that represents a PostItem object.

Remarks

The HTMLBody property should be an HTML syntax string.

Setting the HTMLBody property sets the EditorType property of the item's Inspector to olEditorHTML.

Setting the HTMLBody property will always update the Body property immediately.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Importance Property (Outlook)

 Copy code hover
[image]

PostItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.InternetCodepage Property (Outlook)

 Copy code hover
[image]

PostItem.InternetCodepage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that determines the Internet code page used by the item. Read/write.

Syntax

expression .InternetCodepage

expression A variable that represents a PostItem object.

Remarks

The Internet code page defines the text encoding scheme used by the item.

The following table lists the values that are supported by the InternetCodePage property.

Name | Character Set | Code Page
Arabic (ISO) | iso-8859-6 | 28596
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Baltic (Windows) | windows-1257 | 1257
Central European (ISO) | iso-8859-2 | 28592
Central European (Windows) | windows-1250 | 1250
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Simplified (HZ) | hz-gb-2312 | 52936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (ISO) | iso-8859-5 | 28595
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (KOI8-U) | koi8-u | 21866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Greek (Windows) | windows-1253 | 1253
Hebrew (ISO-Logical) | iso-8859-8-i | 38598
Hebrew (Windows) | windows-1255 | 1255
Japanese (EUC) | euc-jp | 51932
Japanese (JIS) | iso-2022-jp | 50220
Japanese (JIS-Allow 1 byte Kana) | csISO2022JP | 50221
Japanese (Shift-JIS) | iso-2022-jp | 932
Korean | ks_c_5601-1987 | 949
Korean (EUC) | euc-kr | 51949
Latin 3 (ISO) | iso-8859-3 | 28593
Latin 9 (ISO) | iso-8859-15 | 28605
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Turkish (Windows) | windows-1254 | 1254
Unicode (UTF-7) | utf-7 | 65000
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591
Western European (Windows) | Windows-1252 | 1252

The following table lists the code pages Microsoft recommends that you use for the best compatiblity with older e-mail systems.

Name | Character Set | Code Page
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Central European (ISO) | iso-8859-2 | 28592
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Hebrew (Windows) | windows-1255 | 1255
Japanese (JIS) | iso-2022-jp | 50220
Korean | ks_c_5601-1987 | 949
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.IsConflict Property (Outlook)

 Copy code hover
[image]

PostItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a PostItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.IsMarkedAsTask Property (Outlook)

 Copy code hover
[image]

PostItem.IsMarkedAsTask Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the PostItem is marked as a task. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsMarkedAsTask

expression An expression that returns a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

PostItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a PostItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

PostItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

PostItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a PostItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.MessageClass Property (Outlook)

 Copy code hover
[image]

PostItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
PostItem Object

Other resources

PostItem Object Members


PostItem.Mileage Property (Outlook)

 Copy code hover
[image]

PostItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a PostItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.NoAging Property (Outlook)

 Copy code hover
[image]

PostItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

PostItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

PostItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Parent Property (Outlook)

 Copy code hover
[image]

PostItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

PostItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent PostItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReceivedTime Property (Outlook)

 Copy code hover
[image]

PostItem.ReceivedTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time at which the item was received. Read-only.

Syntax

expression .ReceivedTime

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

PostItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a PostItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

PostItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents a PostItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

PostItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

PostItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents a PostItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

PostItem.ReminderTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.RTFBody Property (Outlook)

 Copy code hover
[image]

PostItem.RTFBody Property (Outlook)
See also Send feedback

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a PostItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Saved Property (Outlook)

 Copy code hover
[image]

PostItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.SenderEmailAddress Property (Outlook)

 Copy code hover
[image]

PostItem.SenderEmailAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the e-mail address of the sender of the Outlook item. Read-only.

Syntax

expression .SenderEmailAddress

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderEmailAddress.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.SenderEmailType Property (Outlook)

 Copy code hover
[image]

PostItem.SenderEmailType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the type of entry for the e-mail address of the sender of the Outlook item, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, etc. Read-only.

Syntax

expression .SenderEmailType

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.SenderName Property (Outlook)

 Copy code hover
[image]

PostItem.SenderName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the display name of the sender for the Outlook item. Read-only.

Syntax

expression .SenderName

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderName.

If you wish to retrieve the fully qualified e-mail address of the sender, use the SenderEmailAddress property.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

PostItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.SentOn Property (Outlook)

 Copy code hover
[image]

PostItem.SentOn Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time on which the Outlook item was sent. Read-only.

Syntax

expression .SentOn

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagClientSubmitTime.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Session Property (Outlook)

 Copy code hover
[image]

PostItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a PostItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Size Property (Outlook)

 Copy code hover
[image]

PostItem.Size Property (Outlook)
See also Send feedback

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Subject Property (Outlook)

 Copy code hover
[image]

PostItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a PostItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.TaskCompletedDate Property (Outlook)

 Copy code hover
[image]

PostItem.TaskCompletedDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the completion date of the task for this PostItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskCompletedDate

expression An expression that returns a PostItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.TaskDueDate Property (Outlook)

 Copy code hover
[image]

PostItem.TaskDueDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the due date of the task for this PostItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskDueDate

expression An expression that returns a PostItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.TaskStartDate Property (Outlook)

 Copy code hover
[image]

PostItem.TaskStartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date of the task for this PostItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskStartDate

expression An expression that returns a PostItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.TaskSubject Property (Outlook)

 Copy code hover
[image]

PostItem.TaskSubject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the subject of the task for the PostItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskSubject

expression An expression that returns a PostItem object.

Remarks

This property returns the value of the Subject property if the IsMarkedAsTask property is set to False.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

PostItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the ordinal value of the task for the PostItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a PostItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar. The value used in this property does not have any relation to the values of the TaskStartDate, TaskDueDate, or TaskCompletedDate properties.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.UnRead Property (Outlook)

 Copy code hover
[image]

PostItem.UnRead Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.UserProperties Property (Outlook)

 Copy code hover
[image]

PostItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem Methods (Outlook)

 Copy code hover
[image]

PostItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
ClearConversationIndex | Clears the index of the conversation thread for the post.
ClearTaskFlag | Clears the PostItem object as a task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
Forward | Executes the Forward action for an item and returns the resulting copy as a MailItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a PostItem object as a task and assigns a task interval for the object.
Move | Moves a Microsoft Outlook item to a new folder.
Post | Sends (posts) the PostItem object.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Reply | Creates a reply, pre-addressed to the original sender, from the original message.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


PostItem.ClearConversationIndex Method (Outlook)

 Copy code hover
[image]

PostItem.ClearConversationIndex Method (Outlook)
See also Send feedback

Clears the index of the conversation thread for the post.

Syntax

expression .ClearConversationIndex

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ClearTaskFlag Method (Outlook)

 Copy code hover
[image]

PostItem.ClearTaskFlag Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the PostItem object as a task.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearTaskMark

expression An expression that returns a PostItem object.

Remarks

Calling this method sets the IsMarkedAsTask property to False.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Close Method (Outlook)

 Copy code hover
[image]

PostItem.Close Method (Outlook)
See also Send feedback

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Copy Method (Outlook)

 Copy code hover
[image]

PostItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a PostItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Delete Method (Outlook)

 Copy code hover
[image]

PostItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a PostItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

PostItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

PostItemMembers


PostItem.Display Method (Outlook)

 Copy code hover
[image]

PostItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Forward Method (Outlook)

 Copy code hover
[image]

PostItem.Forward Method (Outlook)
See also Send feedback

Published: July 16, 2012

Executes the Forward action for an item and returns the resulting copy as a MailItem object.

Syntax

expression .Forward

expression A variable that represents a PostItem object.

Return Value

A MailItem object that represents the new mail item.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.GetConversation Method (Outlook)

 Copy code hover
[image]

PostItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a PostItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.MarkAsTask Method (Outlook)

 Copy code hover
[image]

PostItem.MarkAsTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks a PostItem object as a task and assigns a task interval for the object.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask(MarkInterval)

expression An expression that returns a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
MarkInterval | Required | OlMarkInterval | The task interval for the PostItem.

Remarks

Calling this method sets the value of several other properties, depending on the value provided in MarkInterval. For more information about the properties set by specifying MarkInterval, see OlMarkInterval Enumeration.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Move Method (Outlook)

 Copy code hover
[image]

PostItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Post Method (Outlook)

 Copy code hover
[image]

PostItem.Post Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends (posts) the PostItem object.

Syntax

expression .Post

expression A variable that represents a PostItem object.

Remarks

The Post method, which is analogous to the Send method for the MailItem object, is used to save the post to the target public folder instead of mailing it.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.PrintOut Method (Outlook)

 Copy code hover
[image]

PostItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Reply Method (Outlook)

 Copy code hover
[image]

PostItem.Reply Method (Outlook)
See also Send feedback

Creates a reply, pre-addressed to the original sender, from the original message.

Syntax

expression .Reply

expression A variable that represents a PostItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Save Method (Outlook)

 Copy code hover
[image]

PostItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a PostItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.SaveAs Method (Outlook)

 Copy code hover
[image]

PostItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item? " & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.PostItem

 Set MyItem = Application.CreateItem(olPostItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

PostItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a PostItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new post item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub PostItem()

 'Creates a post item to access ShowCategoriesDialog

 Dim olmyPostItem As Outlook.PostItem

 'Create post item

 Set olmyPostItem = Application.CreateItem(olPostItem)

 olmyPostItem.Body = "Please comment on these sales figures."

 olmyPostItem.Subject = "Sales Reports"

 'Display the item

 olmyPostItem.Display

 'Display the Show categories dialog

 olmyPostItem.ShowCategoriesDialog

End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem Events (Outlook)

 Copy code hover
[image]

PostItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


PostItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

PostItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a PostItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

PostItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

PostItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

PostItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the PostItem to be saved.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

PostItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a PostItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Close Event (Outlook)

 Copy code hover
[image]

PostItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.CustomAction Event (Outlook)

 Copy code hover
[image]

PostItem.CustomAction Event (Outlook)
See also Send feedback

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

PostItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Forward Event (Outlook)

 Copy code hover
[image]

PostItem.Forward Event (Outlook)
See also Send feedback

Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Open Event (Outlook)

 Copy code hover
[image]

PostItem.Open Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

PostItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Read Event (Outlook)

 Copy code hover
[image]

PostItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a PostItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

PostItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Reply Event (Outlook)

 Copy code hover
[image]

PostItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

PostItem.ReplyAll Event (Outlook)
See also Send feedback

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Send Event (Outlook)

 Copy code hover
[image]

PostItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Unload Event (Outlook)

 Copy code hover
[image]

PostItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a PostItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PostItem.Write Event (Outlook)

 Copy code hover
[image]

PostItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a PostItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

PostItem Object

Other resources

PostItem Object Members


PropertyAccessor Object (Outlook)

 Copy code hover
[image]

PropertyAccessor Object (Outlook)
See also Send feedback

Provides the ability to create, get, set, and delete properties on objects.

Version Information

Version Added: Outlook 2007

Remarks

Use the PropertyAccessor object to get and set item-level properties that are not explicitly exposed in the Outlook object model, or properties for the following non-item objects: AddressEntry, AddressList, Attachment, ExchangeDistributionList, ExchangeUser, Folder, Recipient, and Store.

To get or set multiple custom properties, use the PropertyAccessor object instead of the UserProperties object for better performance.

For more information on using the PropertyAccessor object, see Properties Overview.

Example

The following code sample demonstrates how to use the PropertyAccessor.GetProperty method to read a MAPI property that belongs to a MailItem but that is not exposed in the Outlook object model, PR_TRANSPORT_MESSAGE_HEADERS.

VBA Copy code Copy code
Sub DemoPropertyAccessorGetProperty()

 Dim PropName, Header As String

 Dim oMail As Object

 Dim oPA As Outlook.PropertyAccessor

 'Get first item in the inbox

 Set oMail = _

 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)

 'PR_TRANSPORT_MESSAGE_HEADERS

 PropName = "http://schemas.microsoft.com/mapi/proptag/0x007D001E"

 'Obtain an instance of PropertyAccessor class

 Set oPA = oMail.PropertyAccessor

 'Call GetProperty

 Header = oPA.GetProperty(PropName)

 Debug.Print (Header)

End Sub

The next code sample demonstrates how the PropertyAccessor.SetProperties method sets the values of multiple properties. If a property does not exist, then SetProperties will create the property as long as the parent object supports the creation of those properties. If the object supports an explicit Save operation, then the properties are saved to the object when the explicit Save operation is called. If the object does not support an explicit Save operation, then the properties are saved to the object when SetProperties is called.

VBA Copy code Copy code
Sub DemoPropertyAccessorSetProperties()

 Dim PropNames(), myValues() As Variant

 Dim arrErrors As Variant

 Dim prop1, prop2, prop3, prop4 As String

 Dim i As Integer

 Dim oMail As Outlook.MailItem

 Dim oPA As Outlook.PropertyAccessor

 'Get first item in the inbox

 Set oMail = _

 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)

 'Names for properties using the MAPI string namespace

 prop1 = "http://schemas.microsoft.com/mapi/string/" & _

 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mylongprop"

 prop2 = "http://schemas.microsoft.com/mapi/string/" & _

 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mystringprop"

 prop3 = "http://schemas.microsoft.com/mapi/string/" & _

 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mydateprop"

 prop4 = "http://schemas.microsoft.com/mapi/string/" & _

 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/myboolprop"

 PropNames = Array(prop1, prop2, prop3, prop4)

 myValues = Array(1020, "111-222-Kudo", Now(), False)

 'Set values with SetProperties call

 'If the properties do not exist, then SetProperties

 'adds the properties to the object when saved.

 'The type of the property is the type of the element

 'passed in myValues array.

 Set oPA = oMail.PropertyAccessor

 arrErrors = oPA.SetProperties(PropNames, myValues)

 If Not (IsEmpty(arrErrors)) Then

 'Examine the arrErrors array to determine if any

 'elements contain errors

 For i = LBound(arrErrors) To UBound(arrErrors)

 'Examine the type of the element

 If IsError(arrErrors(i)) Then

 Debug.Print (CVErr(arrErrors(i)))

 End If

 Next

 End If

 'Save the item

 oMail.Save

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

PropertyAccessor Object Members


PropertyAccessor Members (Outlook)

 Copy code hover
[image]

PropertyAccessor Members (Outlook)
Send feedback

Published: July 16, 2012

Provides the ability to create, get, set, and delete properties on objects.

Methods

Name | Description
BinaryToString | Converts the array of bytes specified by Value to a String.
DeleteProperties | Deletes the properties specified in the array SchemaNames.
DeleteProperty | Deletes the property specified by SchemaName.
GetProperties | Obtains the values of the properties specified by the one-dimensional array SchemaNames.
GetProperty | Returns an Object that represents the value of the property specified by SchemaName.
LocalTimeToUTC | Converts a date-time value specified by Value from the local time format to Coordinated Universal Time (UTC) format.
SetProperties | Sets the properties specified by the array SchemaNames to the values specified by the array Values.
SetProperty | Sets the property specified by SchemaName to the value specified by Value.
StringToBinary | Converts a string specified by Value to an array of bytes.
UTCToLocalTime | Converts the date-time value that is specified by Value and expressed in Coordinated Universal Time (UTC) to a value in local time.

Properties

Name | Description
Application | Returns the Application object that represents the parent application (Outlook) for the PropertyAccessor object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the PropertyAccessor object. Read-only.
Parent | Returns the parent object of the PropertyAccessor object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyAccessor Properties (Outlook)

 Copy code hover
[image]

PropertyAccessor Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns the Application object that represents the parent application (Outlook) for the PropertyAccessor object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the PropertyAccessor object. Read-only.
Parent | Returns the parent object of the PropertyAccessor object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyAccessor.Application Property (Outlook)

 Copy code hover
[image]

PropertyAccessor.Application Property (Outlook)
See also Send feedback

Returns the Application object that represents the parent application (Outlook) for the PropertyAccessor object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a PropertyAccessor object.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.Class Property (Outlook)

 Copy code hover
[image]

PropertyAccessor.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlObjectClass enumeration indicating the class of the PropertyAccessor object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a PropertyAccessor object.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.Parent Property (Outlook)

 Copy code hover
[image]

PropertyAccessor.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent object of the PropertyAccessor object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a PropertyAccessor object.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.Session Property (Outlook)

 Copy code hover
[image]

PropertyAccessor.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a PropertyAccessor object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor Methods (Outlook)

 Copy code hover
[image]

PropertyAccessor Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
BinaryToString | Converts the array of bytes specified by Value to a String.
DeleteProperties | Deletes the properties specified in the array SchemaNames.
DeleteProperty | Deletes the property specified by SchemaName.
GetProperties | Obtains the values of the properties specified by the one-dimensional array SchemaNames.
GetProperty | Returns an Object that represents the value of the property specified by SchemaName.
LocalTimeToUTC | Converts a date-time value specified by Value from the local time format to Coordinated Universal Time (UTC) format.
SetProperties | Sets the properties specified by the array SchemaNames to the values specified by the array Values.
SetProperty | Sets the property specified by SchemaName to the value specified by Value.
StringToBinary | Converts a string specified by Value to an array of bytes.
UTCToLocalTime | Converts the date-time value that is specified by Value and expressed in Coordinated Universal Time (UTC) to a value in local time.


PropertyAccessor.BinaryToString Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.BinaryToString Method (Outlook)
See also Send feedback

Published: July 16, 2012

Converts the array of bytes specified by Value to a String.

Version Information

Version Added: Outlook 2007

Syntax

expression .BinaryToString(Value)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
Value | Required | Variant | Represents the array of bytes to be converted.

Return Value

A hexadecimal String that represents the converted value.

Remarks

For more information on type conversion when using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

Example

The Outlook object model exposes an EntryID property for item objects to obtain the Entry ID of an item. This property is a string representing the value of the MAPI property, PR_ENTRYID, of that item. Aside from the EntryID property, you can also use the PropertyAccessor.GetProperty method to obtain the value of PR_ENTRYID for an item, and use PropertyAccessor.BinaryToString to convert that value to a string. This string should match the EntryID property value for the same item. The following code sample shows the equivalence of the Entry ID returned by the PropertyAccessor.GetProperty method and the Entry ID returned by the EntryID property for each item in the Inbox.

VBA Copy code Copy code
Sub TestEntryIDs()
 Dim oMsg As Object
 Dim oFolder As Outlook.Folder
 Dim oItems As Outlook.Items
 Dim oPA As Outlook.PropertyAccessor
 Dim EntryID1 As String, EntryID2 As String, EntryIDProperty As String

 'This is the MAPI property PR_ENTRYID referenced with its MAPI proptag namespace
 EntryIDProperty = "http://schemas.microsoft.com/mapi/proptag/0x0FFF0102"
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)
 Set oItems = oFolder.Items
 For Each oMsg In oItems
 Set oPA = oMsg.PropertyAccessor
 'First use the EntryID property of the item
 EntryID1 = oMsg.EntryID
 'Then use the PropertyAccessor
 EntryID2 = oPA.BinaryToString(oPA.GetProperty(EntryIDProperty))
 'The string equivalents of the two Entry IDs should be the same
 If EntryID1 <> EntryID2 Then
 Debug.Print "Error obtaining EntryID for " & oMsg.Subject
 End If
 Next
End Sub

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.DeleteProperties Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.DeleteProperties Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes the properties specified in the array SchemaNames.

Version Information

Version Added: Outlook 2007

Syntax

expression .DeleteProperties(SchemaNames)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaNames | Required | Variant | An array that contains the names of the properties that are to be deleted for the parent object of the PropertyAccessor object. These properties are referenced by namespace. For more information, see Referencing Properties by Namespace.

Return Value

A Variant that is Null (Nothing in VBA) if the operation is successful, or is an array of Err objects if an error occurs. If the return value is an array, the size of this array is the same as that of the SchemaNames array. An Err value in the array is mapped to the error result of deleting the corresponding property in the SchemaNames parameter.

Remarks

The caller must have the permission to delete properties. The DeleteProperties method only deletes custom properties that exist. It does not delete any Outlook built-in property or any MAPI property. It does not delete custom properties of the DocumentItem object.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.DeleteProperty Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.DeleteProperty Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes the property specified by SchemaName.

Version Information

Version Added: Outlook 2007

Syntax

expression .DeleteProperty(SchemaName)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaName | Required | String | The name of the property that is to be deleted for the parent object of the PropertyAccessor object. The property is referenced by namespace. For more information, see Referencing Properties by Namespace.

Remarks

The caller must have the permission to delete properties. The DeleteProperty method deletes only custom properties; it does not delete any Outlook built-in property or any MAPI property. It does not delete custom properties of the DocumentItem object.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.GetProperties Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.GetProperties Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains the values of the properties specified by the one-dimensional array SchemaNames.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetProperties(SchemaNames)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaNames | Required | Variant | An array that contains the names of the properties whose values are to be returned. These properties are referenced by namespace. For more information, see Referencing Properties by Namespace.

Return Value

A Variant that represents an array of values of the properties specified in the parameter SchemaNames. The number of elements in the returned array equals the number of elements in the SchemaNames array. If an error occurs for getting a specific property, the Err value will be returned in the corresponding location in the returned array.

Remarks

The array returned by GetProperties can contain elements of different types, depending on the type of the property requested. The type of the array element returned by GetProperties will be the same as the type of the underlying property. Certain raw property types such as PT_OBJECT are unsupported and will raise an error. If you require conversion of the raw property type, for example, from PT_BINARY to a string, or from PT_SYSTIME to a local time, use the helper methods PropertyAccessor.BinaryToString and PropertyAccessor.UTCToLocalTime.

For more information on getting properties using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

Example

The following code sample shows how to use the PropertyAccessor object to get MAPI properties that are not exposed on an Outlook item, namely: PR_SUBJECT, PR_ATTR_HIDDEN, PR_ATTR_READONLY, and PR_ATTR_SYSTEM. This code sample uses the GetProperties method to retrieve them in a single call, specifying an array of namespace references to these properties, and obtains a returned array that contains the raw value for each property.

VBA Copy code Copy code
Sub DemoPropertyAccessorGetProperties()

 Dim PropNames() As Variant

 Dim myValues As Variant

 Dim i As Integer

 Dim j As Integer

 Dim oMail As Object

 Dim oPA As Outlook.PropertyAccessor

 'Get first item in the inbox

 Set oMail = _

 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)

 'PR_SUBJECT, PR_ATTR_HIDDEN, PR_ATTR_READONLY, PR_ATTR_SYSTEM

 PropNames = _

 Array("http://schemas.microsoft.com/mapi/proptag/0x0037001E", _

 "http://schemas.microsoft.com/mapi/proptag/0x10F4000B", _

 "http://schemas.microsoft.com/mapi/proptag/0x10F6000B", _

 "http://schemas.microsoft.com/mapi/proptag/0x10F5000B")

 'Obtain an instance of a PropertyAccessor object

 Set oPA = oMail.PropertyAccessor

 'Get myValues array with GetProperties call

 myValues = oPA.GetProperties(PropNames)

 For i = LBound(myValues) To UBound(myValues)

 'Examine the type of the element

 If IsError(myValues(i)) Then

 'CVErr returns a variant of subtype error

 Debug.Print (CVErr(myValues(i)))

 ElseIf IsArray(myValues(i)) Then

 propArray = myValues(i)

 For j = LBound(propArray) To UBound(propArray)

 Debug.Print (propArray(j))

 Next

 ElseIf IsNull(myValues(i)) Then

 Debug.Print ("Null value")

 ElseIf IsEmpty(myValues(i)) Then

 Debug.Print ("Empty value")

 ElseIf IsDate(myValues(i)) Then

 Debug.Print (oPA.UTCToLocalTime(myValues(i)))

 'VB does not have IsBinary function

 ElseIf VarType(myValues(i)) = vbByte Then

 Debug.Print (oPA.BinaryToString(myValues(i)))

 Else

 Debug.Print (myValues(i))

 End If

 Next

End Sub

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.GetProperty Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.GetProperty Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object that represents the value of the property specified by SchemaName.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetProperty(SchemaName)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaName | Required | String | The name of the property whose value is to be returned. The property is referenced by namespace. For more information, see Referencing Properties by Namespace.

Return Value

A Variant value that represents the value of the requested property as specified by SchemaName.

Remarks

The type of the return value will be the same as the type of the underlying property. Certain raw property types such as PT_OBJECT are unsupported and will raise an error. If you require conversion of the raw property type, for example, from PT_BINARY to a string, or from PT_SYSTIME to a local time, use the helper methods PropertyAccessor.BinaryToString and PropertyAccessor.UTCToLocalTime.

For more information on getting properties using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

Example

The following code sample demonstrates how to use the GetProperty method to read a MAPI property that belongs to a MailItem but which is not exposed in the Outlook object model, PR_TRANSPORT_MESSAGE_HEADERS.

Copy code Copy code
Sub DemoPropertyAccessorGetProperty()
 Dim PropName, Header As String
 Dim oMail As Object
 Dim oPA As Outlook.PropertyAccessor
 'Get first item in the inbox
 Set oMail = _
 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)
 'PR_TRANSPORT_MESSAGE_HEADERS
 PropName = "http://schemas.microsoft.com/mapi/proptag/0x007D001E"
 'Obtain an instance of PropertyAccessor class
 Set oPA = oMail.PropertyAccessor
 'Call GetProperty
 Header = oPA.GetProperty(PropName)
 Debug.Print (Header)
End Sub

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.LocalTimeToUTC Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.LocalTimeToUTC Method (Outlook)
See also Send feedback

Published: July 16, 2012

Converts a date-time value specified by Value from the local time format to Coordinated Universal Time (UTC) format.

Version Information

Version Added: Outlook 2007

Syntax

expression .LocalTimeToUTC(Value)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
Value | Required | Date | The date-time value to be converted from local time to UTC.

Return Value

A Date value that represents Value after being converted from local time to UTC.

Remarks

For more information on type conversion when using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.SetProperties Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.SetProperties Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the properties specified by the array SchemaNames to the values specified by the array Values.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetProperties(SchemaNames, Values)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaNames | Required | Variant | An array of names of properties whose values are to be set as specified by the Values parameter. These properties are referenced by namespace. For more information, see Referencing Properties by Namespace.
Values | Required | Variant | An array of values that are to be set for the properties specified by the SchemaNames parameter.

Return Value

A Variant that is Null (Nothing in VBA) if the operation is successful. If there is an error before any properties are set, for example, the number of elements in the SchemaNames array does not match that in the Values array, and an Err value will be returned. If there is an error during the setting of the properties, the return value is an array of Err objects, with the number of elements in this array being the same as that of the SchemaNames array. An Err value in the array is mapped to the error result of setting the corresponding property in the SchemaNames parameter.

Remarks

If the property does not exist and the SchemaNames element contains a valid property specifier, then SetProperties creates the property and assigns the property with the value specified by Values. The type of the property will be the type of the element passed in Values. If the property does exist, then SetProperties assigns the property the value as specified by Values.

Note that a custom property created by using the PropertyAccessor is not supported in a custom view. If you want to view a custom property on an item, create the property by using the Add method of the UserProperties object.

If the parent object of the PropertyAccessor supports an explicit Save operation, then the properties should be saved to the object with an explicit Save method call. If the object does not support an explicit Save operation, then the properties are saved to the object when SetProperties is called.

Use caution and ensure that all exceptions are handled correctly. Conditions where setting properties fails include:

  • The property is read-only, as some Outlook and MAPI properties are read-only.

  • The property referenced by the specified namespace is not found.

  • The property is specified in an invalid format and cannot be parsed.

  • The property does not exist and cannot be created.

  • The property exists but is passed a value of an incorrect type.

  • Cannot open the property because the client is offline.

  • The property is created using the UserProperties.Add method. When setting the property for the first time, you must use the UserProperty.Value property instead of the SetProperties or SetProperty method of the PropertyAccessor object.

For more information on setting properties using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

Example

This code sample demonstrates how the SetProperties method sets the values of multiple properties. If a property does not exist, then SetProperties will create the property as long as the parent object supports the creation of those properties. Since the MailItem object supports a MailItem.Save operation, the properties here are saved with an explicit oMail.Save.

VBA Copy code Copy code
Sub DemoPropertyAccessorSetProperties()
 Dim PropNames(), myValues() As Variant
 Dim arrErrors As Variant
 Dim prop1, prop2, prop3, prop4 As String
 Dim i As Integer
 Dim oMail As Outlook.MailItem
 Dim oPA As Outlook.PropertyAccessor
 'Get first item in the inbox
 Set oMail = _
 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)
 'Names for properties using the MAPI string namespace
 prop1 = "http://schemas.microsoft.com/mapi/string/" & _
 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mylongprop"
 prop2 = "http://schemas.microsoft.com/mapi/string/" & _
 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mystringprop"
 prop3 = "http://schemas.microsoft.com/mapi/string/" & _
 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/mydateprop"
 prop4 = "http://schemas.microsoft.com/mapi/string/" & _
 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/myboolprop"
 PropNames = Array(prop1, prop2, prop3, prop4)
 myValues = Array(1020, "111-222-Kudo", Now(), False)
 'Set values with SetProperties call
 'If the properties do not exist, then SetProperties
 'adds the properties to the object when saved.
 'The type of the property is the type of the element
 'passed in myValues array.
 Set oPA = oMail.PropertyAccessor
 arrErrors = oPA.SetProperties(PropNames, myValues)
 If Not (IsEmpty(arrErrors)) Then
 'Examine the arrErrors array to determine if any
 'elements contain errors
 For i = LBound(arrErrors) To UBound(arrErrors)
 'Examine the type of the element
 If IsError(arrErrors(i)) Then
 Debug.Print (CVErr(arrErrors(i)))
 End If
 Next
 End If
 'Save the item
 oMail.Save
End Sub

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.SetProperty Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.SetProperty Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the property specified by SchemaName to the value specified by Value.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetProperty(SchemaName, Value)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
SchemaName | Required | String | The name of a property whose value is to be set as specified by the Value parameter. The property is referenced by namespace. For more information, see Referencing Properties by Namespace.
Value | Required | Variant | The value that is to be set for the property specified by the SchemaName parameter.

Remarks

If the property does not exist and the SchemaName contains a valid property specifier, then SetProperty creates the property and assigns the value specified by Value. If the property does exist and SchemaName is valid, then SetProperty assigns the property with the value specified by Value.

Note that a custom property created by using the PropertyAccessor is not supported in a custom view. If you want to view a custom property on an item, create the property by using the Add method of the UserProperties object.

If the parent object of the PropertyAccessor supports an explicit Save operation, then the properties should be saved to the object with an explicit Save method call. If the object does not support an explicit Save operation, then the properties are saved to the object when SetProperties is called.

Use caution and ensure that all exceptions are handled correctly. Conditions where setting properties fails include:

  • The property is read-only, as some Outlook and MAPI properties are read-only.

  • The property referenced by the specified namespace is not found.

  • The property is specified in an invalid format and cannot be parsed.

  • The property does not exist and cannot be created.

  • The property exists but is passed a value of an incorrect type.

  • Cannot open the property because the client is offline.

  • The property is created using the UserProperties.Add method. When setting the property for the first time, you must use the UserProperty.Value property instead of the SetProperties or SetProperty method of the PropertyAccessor object.

For more information on setting properties using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

Example

The following code sample shows how to use the PropertyAccessor to set a custom property on a MailItem object to a value. If the custom property does not exist, PropertyAccessor.SetProperty will create and then set the property. The property is saved with the MailItem.Save method.

VBA Copy code Copy code
Sub DemoPropertyAccessorSetProperty()
 Dim myProp As String
 Dim myValue As Variant
 Dim oMail As Outlook.MailItem
 Dim oPA As Outlook.PropertyAccessor
 'Get first item in the inbox
 Set oMail = _
 Application.Session.GetDefaultFolder(olFolderInbox).Items(1)
 'Name for custom property using the MAPI string namespace
 myProp = "http://schemas.microsoft.com/mapi/string/" & _
 "{FFF40745-D92F-4C11-9E14-92701F001EB3}/myCustomer"
 myValue = "Dan Wilson"
 'Set value with SetProperty call
 'If the property does not exist, then SetProperty
 'adds the property to the object when saved.
 'The type of the property is the type of the element
 'passed in myValue.
 On Error GoTo ErrTrap
 Set oPA = oMail.PropertyAccessor
 oPA.SetProperty myProp, myValue

 'Save the item
 oMail.Save
 Exit Sub
ErrTrap:
 Debug.Print Err.Number, Err.Description
End Sub

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.StringToBinary Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.StringToBinary Method (Outlook)
See also Send feedback

Published: July 16, 2012

Converts a string specified by Value to an array of bytes.

Version Information

Version Added: Outlook 2007

Syntax

expression .StringToBinary(Value)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
Value | Required | String | A hexadecimal string value that is to be converted to an array of bytes.

Return Value

A Variant value that represents an array of bytes returned from the conversion.

Remarks

For more information on type conversion when using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyAccessor.UTCToLocalTime Method (Outlook)

 Copy code hover
[image]

PropertyAccessor.UTCToLocalTime Method (Outlook)
See also Send feedback

Converts the date-time value that is specified by Value and expressed in Coordinated Universal Time (UTC) to a value in local time.

Version Information

Version Added: Outlook 2007

Syntax

expression .UTCToLocalTime(Value)

expression A variable that represents a PropertyAccessor object.

Parameters

Name | Required/Optional | Data Type | Description
Value | Required | Date | The date-time value to be converted from UTC to local time.

Return Value

A Date value that represents Value after being converted from UTC to local time.

Remarks

For more information on type conversion when using the PropertyAccessor object, see Best Practices for Getting and Setting Properties.

See also

Concepts

PropertyAccessor Object

Other resources

PropertyAccessor Object Members


PropertyPage Object (Outlook)

 Copy code hover
[image]

PropertyPage Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a custom property page in the Options dialog box or in the folder Properties dialog box.

Remarks

Outlook uses this object to allow a custom property page to interact with the Apply button in the dialog box.

The PropertyPage object is an abstract object. That is, the PropertyPage object in the Microsoft Outlook Object Library contains no implementation code. Instead, it is provided as a template to help you implement the object in Microsoft Visual Basic for Applications (VBA). This provides a predefined set of interfaces that Outlook can use to determine whether your custom property page has changed and to notify your program that the user has clicked the Apply or OK button. (If your custom property page does not rely on the Apply button, then you do not need to implement the PropertyPage object.)

A custom property page is an ActiveX control that is displayed by Outlook in the Options dialog box or in the folder Properties dialog box when the user clicks on the custom property page's tab. To implement the PropertyPage object, the module that contains the implementation code must contain the following statement.

VBA Copy code Copy code
Implements Outlook.PropertyPage

The module must also contain procedures that implement the properties and methods of the PropertyPage object. For example, to implement the Dirty property, a procedure similar to the following appears in the module.

VBA Copy code Copy code
Private Property Get PropertyPage_Dirty() As Boolean

 PropertyPage_Dirty = gblDirty

End Property

To implement a method of the PropertyPage object, the module must contain a statement similar to the following.

VBA Copy code Copy code
Private Sub PropertyPage_Apply()

 ' Code to set properties according to the user's

 ' selections goes here.

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

PropertyPage Object Members


PropertyPage Members (Outlook)

 Copy code hover
[image]

PropertyPage Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a custom property page in the Options dialog box or in the folder Properties dialog box.

Methods

Name | Description
Apply | Applies the changes that have been made in a custom property page.
GetPageInfo | Returns Help information about a custom property page.

Properties

Name | Description
Dirty | Returns a Boolean value that indicates whether the contents of a custom property page have been altered. Read-only.


PropertyPage Properties (Outlook)

 Copy code hover
[image]

PropertyPage Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Dirty | Returns a Boolean value that indicates whether the contents of a custom property page have been altered. Read-only.


PropertyPage.Dirty Property (Outlook)

 Copy code hover
[image]

PropertyPage.Dirty Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the contents of a custom property page have been altered. Read-only.

Syntax

expression .Dirty(Dirty)

expression A variable that represents a PropertyPage object.

Parameters

Name | Required/Optional | Data Type | Description
Dirty | Required | Boolean | True indicates that the contents of a custom property page has been altered.

Remarks

The ActiveX control that implements the PropertyPage object sets the value of this property, and Microsoft Outlook queries this in response to the OnStatusChange method of a PropertyPageSite object.

Example

This Visual Basic for Applications (VBA) example returns the value of the Dirty property as the value of a global variable.

VBA Copy code Copy code
Private Property Get PropertyPage_Dirty() As Boolean
 PropertyPage_Dirty = globDirty
End Property

See also

Concepts

PropertyPage Object

Other resources

PropertyPage Object Members


PropertyPage Methods (Outlook)

 Copy code hover
[image]

PropertyPage Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Apply | Applies the changes that have been made in a custom property page.
GetPageInfo | Returns Help information about a custom property page.


PropertyPage.Apply Method (Outlook)

 Copy code hover
[image]

PropertyPage.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the changes that have been made in a custom property page.

Syntax

expression .Apply

expression A variable that represents a PropertyPage object.

Return Value

An HRESULT value that represents the response of the event.

Remarks

Because the PropertyPage is an abstract object that is implemented in your application (rather than by Microsoft Outlook itself), the implementation of the Apply method resembles an event procedure in your program code. That is, you write the code that implements the method in much the same way you would write an event procedure. In other words, Outlook calls the Apply method to notify your program that the user has taken an action in the dialog box displaying the custom property page that requires your program to apply the property values changed by the user.

Example

This Microsoft Visual Basic for Applications (VBA) example sets two global variables to reflect the values in controls on a form and then sets a global variable representing the Dirty property to False.

VBA Copy code Copy code
Private Sub PropertyPage_Apply()

 globWorkGroup = Form1.Text1.Text

 globUserType = Form1.Combo1.Text

 globDirty = False

End Sub

See also

Concepts

PropertyPage Object

Other resources

PropertyPage Object Members


PropertyPage.GetPageInfo Method (Outlook)

 Copy code hover
[image]

PropertyPage.GetPageInfo Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns Help information about a custom property page.

Syntax

expression .GetPageInfo(HelpFile, HelpContext)

expression A variable that represents a PropertyPage object.

Parameters

Name | Required/Optional | Data Type | Description
HelpFile | Required | String | Specifies the Help file associated with the property page.
HelpContext | Required | Long | Specifies the context ID of the Help topic associated with the property page.

Return Value

An HRESULT value that represents the result of the method.

Example

This Microsoft Visual Basic for Applications (VBA) example returns the name of the Help file and the context ID of the topic to be displayed.

VBA Copy code Copy code
Private Sub PropertyPage_GetPageInfo(HelpFile As String, HelpContext As Long)
 HelpFile = "ProjPage.chm"
 HelpContext = IDH_PageInfo
End Sub

See also

Concepts

PropertyPage Object

Other resources

PropertyPage Object Members


PropertyPages Object (Outlook)

 Copy code hover
[image]

PropertyPages Object (Outlook)
See also Send feedback

Contains the custom property pages that have been added to the Microsoft OutlookOptions dialog box or to the folder Properties dialog box.

Remarks

You receive a PropertyPages object as a parameter of the OptionsPagesAdd event. Use the Add method to add a PropertyPage object to the PropertyPages object.

Note Note

If more than one program handles the OptionsPagesAdd event, the order in which the programs receive the event (and therefore, the order in which pages are added to the PropertyPages object) cannot be guaranteed.

See also

Concepts

Outlook Object Model Reference

Other resources

PropertyPages Object Members


PropertyPages Members (Outlook)

 Copy code hover
[image]

PropertyPages Members (Outlook)
Send feedback

Published: July 16, 2012

Contains the custom property pages that have been added to the Microsoft OutlookOptions dialog box or to the folder Properties dialog box.

Methods

Name | Description
Add | Adds a new custom property page to the Microsoft OutlookOptions dialog box or to the folder Properties dialog box.
Item | Returns a PropertyPage object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyPages Properties (Outlook)

 Copy code hover
[image]

PropertyPages Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyPages.Application Property (Outlook)

 Copy code hover
[image]

PropertyPages.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a PropertyPages object.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Class Property (Outlook)

 Copy code hover
[image]

PropertyPages.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a PropertyPages object.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Count Property (Outlook)

 Copy code hover
[image]

PropertyPages.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a PropertyPages object.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Parent Property (Outlook)

 Copy code hover
[image]

PropertyPages.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a PropertyPages object.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Session Property (Outlook)

 Copy code hover
[image]

PropertyPages.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a PropertyPages object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages Methods (Outlook)

 Copy code hover
[image]

PropertyPages Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Add | Adds a new custom property page to the Microsoft OutlookOptions dialog box or to the folder Properties dialog box.
Item | Returns a PropertyPage object from the collection.
Remove | Removes an object from the collection.


PropertyPages.Add Method (Outlook)

 Copy code hover
[image]

PropertyPages.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Adds a new custom property page to the Microsoft OutlookOptions dialog box or to the folder Properties dialog box.

Syntax

expression .Add(Page, Title)

expression A variable that represents a PropertyPages object.

Parameters

Name | Required/Optional | Data Type | Description
Page | Required | Variant | The property page being added to the dialog box.
Title | Optional | String | The caption to be displayed on the property-page tab.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Item Method (Outlook)

 Copy code hover
[image]

PropertyPages.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyPage object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a PropertyPages object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object value that represents the specified object.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPages.Remove Method (Outlook)

 Copy code hover
[image]

PropertyPages.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents a PropertyPages object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The name or 1-based index value of an object within a collection.

See also

Concepts

PropertyPages Object

Other resources

PropertyPages Object Members


PropertyPageSite Object (Outlook)

 Copy code hover
[image]

PropertyPageSite Object (Outlook)
See also Send feedback

Represents the container of a custom property page.

Remarks

Use the Parent property of the ActiveX control that implements the PropertyPage object associated with the PropertyPageSite object to return the PropertyPageSite object. The Declarations section of the module implementing the PropertyPage object must contain a declaration similar to the following.

VBA Copy code Copy code
Private myPropertyPageSite As Outlook.PropertyPageSite

The object is then returned from the Parent property.

VBA Copy code Copy code
Set myPropertyPageSite = Parent

Use the OnStatusChange method to notify Microsoft Outlook that the property page has changed.

See also

Concepts

Outlook Object Model Reference

Other resources

PropertyPageSite Object Members


PropertyPageSite Members (Outlook)

 Copy code hover
[image]

PropertyPageSite Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the container of a custom property page.

Methods

Name | Description
OnStatusChange | Notifies Microsoft Outlook that a custom property page has changed.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyPageSite Properties (Outlook)

 Copy code hover
[image]

PropertyPageSite Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


PropertyPageSite.Application Property (Outlook)

 Copy code hover
[image]

PropertyPageSite.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a PropertyPageSite object.

See also

Concepts

PropertyPageSite Object

Other resources

PropertyPageSite Object Members


PropertyPageSite.Class Property (Outlook)

 Copy code hover
[image]

PropertyPageSite.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a PropertyPageSite object.

See also

Concepts

PropertyPageSite Object

Other resources

PropertyPageSite Object Members


PropertyPageSite.Parent Property (Outlook)

 Copy code hover
[image]

PropertyPageSite.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a PropertyPageSite object.

See also

Concepts

PropertyPageSite Object

Other resources

PropertyPageSite Object Members


PropertyPageSite.Session Property (Outlook)

 Copy code hover
[image]

PropertyPageSite.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a PropertyPageSite object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

PropertyPageSite Object

Other resources

PropertyPageSite Object Members


PropertyPageSite Methods (Outlook)

 Copy code hover
[image]

PropertyPageSite Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
OnStatusChange | Notifies Microsoft Outlook that a custom property page has changed.


PropertyPageSite.OnStatusChange Method (Outlook)

 Copy code hover
[image]

PropertyPageSite.OnStatusChange Method (Outlook)
See also Send feedback

Notifies Microsoft Outlook that a custom property page has changed.

Syntax

expression .OnStatusChange

expression A variable that represents a PropertyPageSite object.

Example

This Microsoft Visual Basic for Applications (VBA) example shows how to call the OnStatusChange method to notify Outlook that the user has changed a value on a custom property page.

VBA Copy code Copy code
Private Sub Option1_Click()

 Dim myPPSite As Outlook.PropertyPageSite

 Set myPPSite = Parent

 If Not TypeName(myPPSite) = "Nothing" Then

 globNewUserType = globAdministrator

 If globUserType <> globNewUserType Then

 globDirty = True

 myPPSite.OnStatusChange

 End If

 Else

 If TypeName(myPPSite) = "Nothing" Then

 MsgBox "The Property Page returned an empty result."

 End If

 End If

End Sub

See also

Concepts

PropertyPageSite Object

Other resources

PropertyPageSite Object Members


Recipient Object (Outlook)

 Copy code hover
[image]

Recipient Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a user or resource in Outlook, generally a mail or mobile message addressee.

Remarks

Use the Recipients(index) method, where index is the name or index number, to return a single Recipient object. The name can be a string that represents the display name, the alias, the full SMTP e-mail address, or the mobile phone number of the recipient. A good practice is to use the SMTP e-mail address for a mail message, and the mobile phone number for a mobile message.

Use the Add method to create a new Recipient object and add it to the Recipients object. The Type property of a new Recipient object is set to the default value for the associated AppointmentItem, JournalItem, MailItem, MeetingItem, or TaskItem object and must be reset to indicate another recipient type.

Example

The following Visual Basic for Applications (VBA) example creates a new MailItem object and adds Jon Grande as the recipient by using the default type ("To").

VBA Copy code Copy code
Set myItem = Application.CreateItem(olMailItem)

Set myRecipient = myItem.Recipients.Add ("Jon Grande")

The following VBA example creates the same MailItem object as the preceding example, and then changes the type of the Recipient object from the default (To) to CC.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olMailItem)

Set myRecipient = myItem.Recipients.Add ("Jon Grande")

myRecipient.Type = olCC

See also

Concepts

How to: Obtain the E-mail Address of a Recipient
Outlook Object Model Reference

Other resources

Recipient Object Members


Recipient Members (Outlook)

 Copy code hover
[image]

Recipient Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a user or resource in Outlook, generally a mail or mobile message addressee.

Methods

Name | Description
Delete | Deletes an object from the collection.
FreeBusy | Returns free/busy information for the recipient.
Resolve | Attempts to resolve a Recipient object against the Address Book.

Properties

Name | Description
Address | Returns a String representing the e-mail address of the Recipient. Read-only.
AddressEntry | Returns the AddressEntry object corresponding to the resolved recipient. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoResponse | Returns or sets a String representing the text of an automatic response for a Recipient. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayType | Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the Recipient. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
MeetingResponseStatus | Returns an OlResponseStatus constant indicating the overall status of the response to the meeting request for the recipient. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Recipient object. Read-only.
Resolved | Returns a Boolean that indicates True if the recipient has been validated against the Address Book. Read-only.
Sendable | Returns or sets a Boolean value that indicates whether a meeting request can be sent to the Recipient. Read/write
Session | Returns the NameSpace object for the current session. Read-only.
TrackingStatus | Returns or sets an OlTrackingStatus constant indicating the tracking status for the recipient. Read/write.
TrackingStatusTime | Returns or sets a Date indicating the tracking status date and time for the recipient. Read/write.
Type | Returns or sets a Long representing the type of recipient. Read/write.


Recipient Properties (Outlook)

 Copy code hover
[image]

Recipient Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Address | Returns a String representing the e-mail address of the Recipient. Read-only.
AddressEntry | Returns the AddressEntry object corresponding to the resolved recipient. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoResponse | Returns or sets a String representing the text of an automatic response for a Recipient. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayType | Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the Recipient. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
Index | Returns a Long indicating the position of the object within the collection. Read-only.
MeetingResponseStatus | Returns an OlResponseStatus constant indicating the overall status of the response to the meeting request for the recipient. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Recipient object. Read-only.
Resolved | Returns a Boolean that indicates True if the recipient has been validated against the Address Book. Read-only.
Sendable | Returns or sets a Boolean value that indicates whether a meeting request can be sent to the Recipient. Read/write
Session | Returns the NameSpace object for the current session. Read-only.
TrackingStatus | Returns or sets an OlTrackingStatus constant indicating the tracking status for the recipient. Read/write.
TrackingStatusTime | Returns or sets a Date indicating the tracking status date and time for the recipient. Read/write.
Type | Returns or sets a Long representing the type of recipient. Read/write.


Recipient.Address Property (Outlook)

 Copy code hover
[image]

Recipient.Address Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the e-mail address of the Recipient. Read-only.

Syntax

expression .Address

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.AddressEntry Property (Outlook)

 Copy code hover
[image]

Recipient.AddressEntry Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the AddressEntry object corresponding to the resolved recipient. Read/write.

Syntax

expression .AddressEntry

expression A variable that represents a Recipient object.

Remarks

Accessing the AddressEntry property forces resolution of an unresolved recipient name. If the name cannot be resolved, an error is returned. If the recipient is resolved, the Resolved property is True.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Application Property (Outlook)

 Copy code hover
[image]

Recipient.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.AutoResponse Property (Outlook)

 Copy code hover
[image]

Recipient.AutoResponse Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the text of an automatic response for a Recipient. Read/write.

Syntax

expression .AutoResponse

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Class Property (Outlook)

 Copy code hover
[image]

Recipient.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.DisplayType Property (Outlook)

 Copy code hover
[image]

Recipient.DisplayType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant belonging to the OlDisplayType enumeration that describes the nature of the Recipient. Read-only.

Syntax

expression .DisplayType

expression A variable that represents a Recipient object.

Remarks

You can use the DisplayType property to filter recipients. The DisplayType property corresponds to the MAPI property PidTagDisplayType.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.EntryID Property (Outlook)

 Copy code hover
[image]

Recipient.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a Recipient object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Index Property (Outlook)

 Copy code hover
[image]

Recipient.Index Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the position of the object within the collection. Read-only.

Syntax

expression .Index

expression A variable that represents a Recipient object.

Remarks

The Index property is only valid during the current session and can change as objects are added to and deleted from the collection. The first object in the collection has an Index value of 1.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.MeetingResponseStatus Property (Outlook)

 Copy code hover
[image]

Recipient.MeetingResponseStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlResponseStatus constant indicating the overall status of the response to the meeting request for the recipient. Read-only.

Syntax

expression .MeetingResponseStatus

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Name Property (Outlook)

 Copy code hover
[image]

Recipient.Name Property (Outlook)
See also Send feedback

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Parent Property (Outlook)

 Copy code hover
[image]

Recipient.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

Recipient.PropertyAccessor Property (Outlook)
See also Send feedback

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Recipient object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Resolved Property (Outlook)

 Copy code hover
[image]

Recipient.Resolved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the recipient has been validated against the Address Book. Read-only.

Syntax

expression .Resolved

expression A variable that represents a Recipient object.

Remarks

If similar names exist for a recipient in an Address Book, you can resolve the recipient by specifying the recipient's full SMTP e-mail address.

Example

This Visual Basic for Applications (VBA) example uses the Resolve method to resolve the Recipient object representing Dan Wilson, and then returns Dan's shared default Calendar folder.

VBA Copy code Copy code
Sub ResolveName()

 Dim myNamespace As Outlook.NameSpace

 Dim myRecipient As Outlook.Recipient

 Dim CalendarFolder As Outlook.Folder

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myRecipient = myNamespace.CreateRecipient("Dan Wilson")

 myRecipient.Resolve

 If myRecipient.Resolved Then

 Call ShowCalendar(myNamespace, myRecipient)

 End If

End Sub

Sub ShowCalendar(myNamespace, myRecipient)

 Dim CalendarFolder As Outlook.Folder

 Set CalendarFolder = _

 myNamespace.GetSharedDefaultFolder _

 (myRecipient, olFolderCalendar)

 CalendarFolder.Display

End Sub

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Sendable Property (Outlook)

 Copy code hover
[image]

Recipient.Sendable Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a meeting request can be sent to the Recipient. Read/write

Version Information

Version Added: Outlook 2010

Syntax

expression .Sendable

expression A variable that represents a Recipient object.

Remarks

This property corresponds to the MAPI property PidTagRecipientFlags. It returns True if PidTagRecipientFlags is equal to 0x00000001. Setting the property changes PidTagRecipientFlags accordingly.

This property applies only to a recipient of a meeting request. If the recipient is not on a meeting request, getting and setting this property does not do anything.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Session Property (Outlook)

 Copy code hover
[image]

Recipient.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Recipient object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.TrackingStatus Property (Outlook)

 Copy code hover
[image]

Recipient.TrackingStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTrackingStatus constant indicating the tracking status for the recipient. Read/write.

Syntax

expression .TrackingStatus

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.TrackingStatusTime Property (Outlook)

 Copy code hover
[image]

Recipient.TrackingStatusTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the tracking status date and time for the recipient. Read/write.

Syntax

expression .TrackingStatusTime

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Type Property (Outlook)

 Copy code hover
[image]

Recipient.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long representing the type of recipient. Read/write.

Syntax

expression .Type

expression A variable that represents a Recipient object.

Remarks

Depending on the type of recipient, this property returns or sets a Long corresponding to the numeric equivalent of one of the following constants:

  • JournalItem recipient: the OlJournalRecipientType constant olAssociatedContact.

  • MailItem recipient: one of the following OlMailRecipientType constants: olBCC, olCC, olOriginator, or olTo.

  • MeetingItem recipient: one of the following OlMeetingRecipientType constants: olOptional, olOrganizer, olRequired, or olResource.

  • TaskItem recipient: either of the following OlTaskRecipientType constants: olFinalStatus, or olUpdate.

This property may not always return the appropriate recipient type for a conference room. For instance, a conference room may be specified as a required recipient in a meeting request, in which case this property will not return olResource for that conference room.

To reliably determine if a recipient is a conference room, use the Messaging API (MAPI) property, PidTagDisplayTypeEx, of the Recipient object. You can access this property using the PropertyAccessor object in the Outlook object model. The PidTagDisplayTypeEx property is represented as "http://schemas.microsoft.com/mapi/proptag/0x39050003" in the MAPI proptag namespace. Note that the PidTagDisplayTypeEx property is not available in versions of Microsoft Exchange Server earlier than Microsoft Exchange Server 2007; in such earlier versions of Exchange Server, you can use the Recipient.Type property and assume that a recipient having a type other than olResource is not a conference room.

Example

The following Visual Basic for Applications (VBA) example shows how to use the PropertyAccessor on the PidTagDisplayTypeEx property for each of the Recipient objects in the Recipients collection of a meeting request. If the value of that property is 7 (the value for the MAPI constant DT_ROOM as defined in the MAPI header file, mapidefs.h), then that recipient is a conference room. This example assumes that there is a meeting request in the current inspector.

VBA Copy code Copy code
Sub DemoMeetingRecipients()
 Dim myAppointment As Outlook.AppointmentItem
 Dim myPA As Outlook.PropertyAccessor
 Dim d As Long
 Dim myInt As Long

 Set myAppointment = Application.ActiveInspector.CurrentItem

 For d = 1 To myAppointment.Recipients.count
 Debug.Print myAppointment.Recipients.item(d).name
 Debug.Print myAppointment.Recipients.item(d).Type
 Set myPA = myAppointment.Recipients.item(d).PropertyAccessor
 myInt = myPA.GetProperty("http://schemas.microsoft.com/mapi/proptag/0x39050003")
 Debug.Print myInt
 Debug.Print "---"
 Next d
End Sub

The following VBA example uses CreateItem to create an appointment and uses MeetingStatus to set the meeting status to "Meeting" to turn it into a meeting request with both a required and an optional attendee. The recipient names should be replaced with valid names to avoid errors.

VBA Copy code Copy code
Sub ScheduleMeeting()
 Dim myItem as Outlook.AppointmentItem
 Dim myRequiredAttendee As Outlook.Recipient
 Dim myOptionalAttendee As Outlook.Recipient
 Dim myResourceAttendee As Outlook.Recipient

 Set myItem = Application.CreateItem(olAppointmentItem)
 myItem.MeetingStatus = olMeeting
 myItem.Subject = "Strategy Meeting"
 myItem.Location = "Conference Room B"
 myItem.Start = #9/24/2003 1:30:00 PM#
 myItem.Duration = 90
 Set myRequiredAttendee = myItem.Recipients.Add ("Nate Sun")
 myRequiredAttendee.Type = olRequired
 Set myOptionalAttendee = myItem.Recipients.Add ("Kevin Kennedy")
 myOptionalAttendee.Type = olOptional
 Set myResourceAttendee = myItem.Recipients.Add("Conference Room B")
 myResourceAttendee.Type = olResource
 myItem.Display
End Sub

See also

Concepts

Referencing Properties by Namespace
Recipient Object

Other resources

Recipient Object Members


Recipient Methods (Outlook)

 Copy code hover
[image]

Recipient Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.
FreeBusy | Returns free/busy information for the recipient.
Resolve | Attempts to resolve a Recipient object against the Address Book.


Recipient.Delete Method (Outlook)

 Copy code hover
[image]

Recipient.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents a Recipient object.

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.FreeBusy Method (Outlook)

 Copy code hover
[image]

Recipient.FreeBusy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns free/busy information for the recipient.

Syntax

expression .FreeBusy(Start, MinPerChar, CompleteFormat)

expression A variable that represents a Recipient object.

Parameters

Name | Required/Optional | Data Type | Description
Start | Required | Date | The start date for the returned period of free/busy information.
MinPerChar | Required | Long | The number of minutes per character represented in the returned free/busy string.
CompleteFormat | Optional | Variant | True if the returned string should contain not only free/busy information, but also values for each character according to the OlBusyStatus constants.

Return Value

A String value that represents the free/busy information.

Remarks

The default is to return a string representing one month of free/busy information compatible with the Microsoft Schedule+ Automation format (that is, the string contains one character for each MinPerChar minute, up to one month of information from the specified Start date).

If the optional argument CompleteFormat is omitted or False, then "free" is indicated by the character 0 and all other states by the character 1.

If CompleteFormat is True, then the same length string is returned as defined above, but the characters now correspond to the OlBusyStatus constants.

Example

This Visual Basic for Applications (VBA) example uses the FreeBusy method to return a string of free/busy information with one character for each day. This example allows for the possibility that the free/busy information for this recipient is not accessible. To run this example, you need to replace 'Nate Sun' with a valid recipient name.

VBA Copy code Copy code
Public Sub GetFreeBusyInfo()
 Dim myNameSpace As Outlook.NameSpace
 Dim myRecipient As Outlook.Recipient
 Dim myFBInfo As String

 Set myNameSpace = Application.GetNamespace("MAPI")
 Set myRecipient = myNameSpace.CreateRecipient("Nate Sun")
 On Error GoTo ErrorHandler
 myFBInfo = myRecipient.FreeBusy(#11/11/2003#, 60 * 24)
 MsgBox myFBInfo
 Exit Sub
ErrorHandler:
 MsgBox "Cannot access the information. "
End Sub

This VBA example returns a string of free/busy information with one character for each hour (complete format).

VBA Copy code Copy code
Set myRecipient = myNameSpace.CreateRecipient("Nate Sun")
myFBInfo = myRecipient.FreeBusy(#8/1/03#, 60, True)

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipient.Resolve Method (Outlook)

 Copy code hover
[image]

Recipient.Resolve Method (Outlook)
See also Send feedback

Attempts to resolve a Recipient object against the Address Book.

Syntax

expression .Resolve

expression A variable that represents a Recipient object.

Return Value

True if the object was resolved; otherwise, False.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create a simple task and delegate it as a task request to another user. Before running this example, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub AssignTask()

 Dim myItem As Outlook.TaskItem

 Dim myDelegate As Outlook.Recipient

 Set MyItem = Application.CreateItem(olTaskItem)

 MyItem.Assign

 Set myDelegate = MyItem.Recipients.Add("Dan Wilson")

 myDelegate.Resolve

 If myDelegate.Resolved Then

 myItem.Subject = "Prepare Agenda For Meeting"

 myItem.DueDate = Now + 30

 myItem.Display

 myItem.Send

 End If

End Sub

See also

Concepts

Recipient Object

Other resources

Recipient Object Members


Recipients Object (Outlook)

 Copy code hover
[image]

Recipients Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of Recipient objects for an Outlook item.

Remarks

Use the Recipients property to return the Recipients object of an AppointmentItem, JournalItem, MailItem, MeetingItem, or TaskItem object.

Use the Add method to create a new Recipient object and add it to the Recipients object. The Type property of a new Recipient object is set to the default for the associated AppointmentItem, JournalItem, MailItem, or TaskItem object and must be reset to indicate another recipient type.

Use Recipients(index), where index is the name or index number, to return a single Recipient object. The name can be a string representing the display name, the alias, or the full SMTP e-mail address of the recipient.

Example

The following example creates a new MailItem object and adds Jon Grande as the recipient using the default type ("To").

VBA Copy code Copy code
Set myItem = Application.CreateItem(olMailItem)

Set myRecipient = myItem.Recipients.Add ("Jon Grande")

The following example creates the same MailItem object as the preceding example, and then changes the type of the Recipient object from the default ("To") to CC.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olMailItem)

Set myRecipient = myItem.Recipients.Add ("Jon Grande")

myRecipient.Type = olCC

See also

Concepts

Outlook Object Model Reference

Other resources

Recipients Object Members


Recipients Members (Outlook)

 Copy code hover
[image]

Recipients Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of Recipient objects for an Outlook item.

Methods

Name | Description
Add | Creates a new recipient in the Recipients collection.
Item | Returns a Recipient object from the collection.
Remove | Removes an object from the collection.
ResolveAll | Attempts to resolve all the Recipient objects in the Recipients collection against the Address Book.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Recipients Properties (Outlook)

 Copy code hover
[image]

Recipients Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Recipients.Application Property (Outlook)

 Copy code hover
[image]

Recipients.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Recipients object.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Class Property (Outlook)

 Copy code hover
[image]

Recipients.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Recipients object.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Count Property (Outlook)

 Copy code hover
[image]

Recipients.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Recipients object.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Parent Property (Outlook)

 Copy code hover
[image]

Recipients.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Recipients object.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Session Property (Outlook)

 Copy code hover
[image]

Recipients.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Recipients object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients Methods (Outlook)

 Copy code hover
[image]

Recipients Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new recipient in the Recipients collection.
Item | Returns a Recipient object from the collection.
Remove | Removes an object from the collection.
ResolveAll | Attempts to resolve all the Recipient objects in the Recipients collection against the Address Book.


Recipients.Add Method (Outlook)

 Copy code hover
[image]

Recipients.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new recipient in the Recipients collection.

Syntax

expression .Add(Name)

expression A variable that represents a Recipients object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the recipient; it can be a string representing the display name, the alias, or the full SMTP e-mail address of the recipient.

Return Value

A Recipient object that represents the new recipient.

Example

This VBA example creates a new mail message, uses the Add method to add 'Dan Wilson' as a To recipient, and displays the message. To run this example without errors, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub CreateStatusReportToBoss()

 Dim myItem As Outlook.MailItem

 Dim myRecipient As Outlook.Recipient

 Set myItem = Application.CreateItem(olMailItem)

 Set myRecipient = myItem.Recipients.Add("Dan Wilson")

 myItem.Subject = "Status Report"

 myItem.Display

End Sub

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Item Method (Outlook)

 Copy code hover
[image]

Recipients.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipient object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a Recipients object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A Recipient object that represents the specified object.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.Remove Method (Outlook)

 Copy code hover
[image]

Recipients.Remove Method (Outlook)
See also Send feedback

Removes an object from the collection.

Syntax

expression .Remove(Index)

expression A variable that represents a Recipients object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


Recipients.ResolveAll Method (Outlook)

 Copy code hover
[image]

Recipients.ResolveAll Method (Outlook)
See also Send feedback

Published: July 16, 2012

Attempts to resolve all the Recipient objects in the Recipients collection against the Address Book.

Syntax

expression .ResolveAll

expression A variable that represents a Recipients object.

Return Value

True if all of the objects were resolved, False if one or more were not.

Example

This Visual Basic for Applications (VBA) example uses the ResolveAll method to attempt to resolve all recipients and, if unsuccessful, displays a message box for each unresolved recipient.

VBA Copy code Copy code
Sub CheckRecipients()

 Dim MyItem As Outlook.MailItem

 Dim myRecipients As Outlook.Recipients

 Dim myRecipient As Outlook.Recipient

 Set myItem = Application.CreateItem(olMailItem)

 Set myRecipients = myItem.Recipients

 myRecipients.Add("Aaron Con")

 myRecipients.Add("Nate Sun")

 myRecipients.Add("Dan Wilson")

 If Not myRecipients.ResolveAll Then

 For Each myRecipient In myRecipients

 If Not myRecipient.Resolved Then

 MsgBox myRecipient.Name

 End If

 Next

 End If

End Sub

See also

Concepts

Recipients Object

Other resources

Recipients Object Members


RecurrencePattern Object (Outlook)

 Copy code hover
[image]

RecurrencePattern Object (Outlook)
See also Send feedback

Represents the pattern of incidence of recurring appointments and tasks for the associated AppointmentItem and TaskItem object.

Remarks

Use the GetRecurrencePattern method to return the RecurrencePattern object associated with an AppointmentItem or TaskItem object.

Calling GetRecurrencePattern or ClearRecurrencePattern has the side effect of setting the IsRecurring property of the item accordingly. This property can be used as required for efficient filtering of the Items object.

The type of recurrence pattern is indicated by the RecurrenceType property. The RecurrenceType property is the first property you should set.

The following properties are valid for all recurrence patterns: EndTime, Occurrences, StartDate, StartTime, or Type.

The following table shows the properties that are valid for the different recurrence types. An error occurs if the item is saved and the property is null or contains an invalid value. Monthly and yearly patterns are only valid for a single day. Weekly patterns are only valid as the Or of the DayOfWeekMask.

RecurrenceType | Properties | Examples
olRecursDaily | Duration , EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | A value N for Interval is every N days.
olRecursWeekly | DayOfWeekMask, Duration, EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | A value N for Interval is every N weeks. An example of DayofWeekMask is every Tuesday, Wednesday, and Thursday.
olRecursMonthly | DayOfMonth , Duration, EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | A value N for Interval is every N months. A value N for DayofMonth is every Nth day of the month.
olRecursMonthNth | DayOfWeekMask, Duration, EndTime, Interval, Instance, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | A value N for Interval is every N months. An example of value N for Instance is every Nth Tuesday. An example of DayofWeekMask is every Tuesday and Wednesday.
olRecursYearly | DayOfMonth, Duration, EndTime, Interval, MonthOfYear, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | A value N for DayofMonth is the Nth day of the month. An example of MonthOfYear is February.
olRecursYearNth | DayOfWeekMask, Duration, EndTime, Interval, Instance, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime | An example of value N for Instance is the Nth Tuesday. An example of DayofWeekMask is Tuesday, Wednesday, and Thursday. An example of MonthOfYear is February.

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

See also

Concepts

Outlook Object Model Reference

Other resources

RecurrencePattern Object Members


RecurrencePattern Members (Outlook)

 Copy code hover
[image]

RecurrencePattern Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the pattern of incidence of recurring appointments and tasks for the associated AppointmentItem and TaskItem object.

Methods

Name | Description
GetOccurrence | Returns a specific instance of the AppointmentItem object on the specified date.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DayOfMonth | Returns or sets a Long indicating the day of the month on which the recurring appointment or task occurs. Read/write.
DayOfWeekMask | Returns or sets an OlDaysOfWeek constant representing the mask for the days of the week on which the recurring appointment or task occurs. Read/write.
Duration | Returns or sets a Long indicating the duration (in minutes) of the RecurrencePattern. Read/write.
EndTime | Returns or sets a Date indicating the end time for a recurrence pattern. Read/write.
Exceptions | Returns the Exceptions collection for a specified series of recurring appointments. Read-only.
Instance | Returns or sets a Long specifying the count for which the recurrence pattern is valid for a given interval. Read/write.
Interval | Returns or sets a Long specifying the number of units of a given recurrence type between occurrences. Read/write.
MonthOfYear | Returns or sets a Long indicating which month of the year is valid for the specified recurrence pattern. Read/write.
NoEndDate | Returns a Boolean value that indicates whether the recurrence pattern has no end date. Read/write.
Occurrences | Returns or sets a Long indicating the number of occurrences of the recurrence pattern. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PatternEndDate | Returns or sets a Date indicating the end date for the recurrence pattern. Read/write.
PatternStartDate | Returns or sets a Date indicating the start date for the recurrence pattern. Read/write.
RecurrenceType | Returns or sets an OlRecurrenceType constant specifying the frequency of occurrences for the recurrence pattern. Read/write.
Regenerate | Returns a Boolean that indicates True if the task should be regenerated following this pass through the recurrence pattern. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
StartTime | Returns or sets a Date indicating the start time for a recurrence pattern. Read/write.


RecurrencePattern Properties (Outlook)

 Copy code hover
[image]

RecurrencePattern Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DayOfMonth | Returns or sets a Long indicating the day of the month on which the recurring appointment or task occurs. Read/write.
DayOfWeekMask | Returns or sets an OlDaysOfWeek constant representing the mask for the days of the week on which the recurring appointment or task occurs. Read/write.
Duration | Returns or sets a Long indicating the duration (in minutes) of the RecurrencePattern. Read/write.
EndTime | Returns or sets a Date indicating the end time for a recurrence pattern. Read/write.
Exceptions | Returns the Exceptions collection for a specified series of recurring appointments. Read-only.
Instance | Returns or sets a Long specifying the count for which the recurrence pattern is valid for a given interval. Read/write.
Interval | Returns or sets a Long specifying the number of units of a given recurrence type between occurrences. Read/write.
MonthOfYear | Returns or sets a Long indicating which month of the year is valid for the specified recurrence pattern. Read/write.
NoEndDate | Returns a Boolean value that indicates whether the recurrence pattern has no end date. Read/write.
Occurrences | Returns or sets a Long indicating the number of occurrences of the recurrence pattern. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
PatternEndDate | Returns or sets a Date indicating the end date for the recurrence pattern. Read/write.
PatternStartDate | Returns or sets a Date indicating the start date for the recurrence pattern. Read/write.
RecurrenceType | Returns or sets an OlRecurrenceType constant specifying the frequency of occurrences for the recurrence pattern. Read/write.
Regenerate | Returns a Boolean that indicates True if the task should be regenerated following this pass through the recurrence pattern. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
StartTime | Returns or sets a Date indicating the start time for a recurrence pattern. Read/write.


RecurrencePattern.Application Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a RecurrencePattern object.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Class Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a RecurrencePattern object.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.DayOfMonth Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.DayOfMonth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the day of the month on which the recurring appointment or task occurs. Read/write.

Syntax

expression .DayOfMonth

expression A variable that represents a RecurrencePattern object.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.DayOfWeekMask Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.DayOfWeekMask Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDaysOfWeek constant representing the mask for the days of the week on which the recurring appointment or task occurs. Read/write.

Syntax

expression .DayOfWeekMask

expression A variable that represents a RecurrencePattern object.

Remarks

The DayOfWeekMask should be set after the RecurrenceType property has been set and before the PatternEndDate and PatternStartDate properties are set.

Monthly and yearly patterns are only valid for a single day. Weekly patterns are only valid as the Or of the DayOfWeekMask.

Example

This Visual Basic for Applications example uses GetRecurrencePattern to obtain the RecurrencePattern object for the newly-created AppointmentItem. The properties, RecurrenceType, DayOfWeekMask, PatternStartDate, PatternEndDate, Duration, StartTime, EndTime, and Subject are set, the appointment is saved and then displayed with the pattern: "Occurs every Monday, Wednesday, and Friday effective 7/10/2006 until 8/25/2006 from 2:00 PM to 3:00 PM."

Copy code Copy code
Sub RecurringAppointmentEveryMondayWednesdayFriday()

 Dim oAppt As AppointmentItem

 Dim oPattern As RecurrencePattern

 Set oAppt = Application.CreateItem(olAppointmentItem)

 Set oPattern = oAppt.GetRecurrencePattern

 With oPattern

 .RecurrenceType = olRecursWeekly

 .DayOfWeekMask = olMonday Or olWednesday Or olFriday

 .PatternStartDate = #7/10/2006#

 .PatternEndDate = #8/25/2006#

 .Duration = 60

 .StartTime = #2:00:00 PM#

 .EndTime = #3:00:00 PM#

 End With

 oAppt.Subject = "Recurring Appointment Monday Wednesday Friday"

 oAppt.Save

 oAppt.Display

End Sub

Similar to the last example, this Visual Basic for Applications example also uses GetRecurrencePattern to obtain the RecurrencePattern object for the newly-created AppointmentItem. The properties, RecurrenceType, DayOfWeekMask, PatternStartDate, PatternEndDate, Duration , StartTime, EndTime, and Subject are set, the appointment is saved and then displayed with the pattern: "Occurs every Monday, Tuesday, Wednesday, Thursday, and Friday effective 7/10/2006 until 8/4/2006."

Copy code Copy code
Sub RecurringEventEveryWeekday()

 Dim oPattern As Outlook.RecurrencePattern

 Dim oAppt As Outlook.AppointmentItem

 Set oAppt = Application.CreateItem(olAppointmentItem)

 Set oPattern = oAppt.GetRecurrencePattern

 With oPattern

 .RecurrenceType = olRecursWeekly

 .DayOfWeekMask = olMonday Or olTuesday Or olWednesday Or olThursday Or olFriday

 .PatternStartDate = #7/10/2006#

 .PatternEndDate = #8/4/2006#

 .Duration = 1440 'Duration in minutes, for all day event = 24 * 60

 .StartTime = #12:00:00 AM#

 .EndTime = #12:00:00 AM#

 End With

 oAppt.Subject = "Recurring Event Every Weekday"

 oAppt.Save

 oAppt.Display

End Sub

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Duration Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Duration Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the duration (in minutes) of the RecurrencePattern. Read/write.

Syntax

expression .Duration

expression A variable that represents a RecurrencePattern object.

Remarks

For recurrences, this property is only valid for appointments.

To create a duration of one day for an all-day event, set the duration equal to 1440.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.EndTime Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.EndTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the end time for a recurrence pattern. Read/write.

Syntax

expression .EndTime

expression A variable that represents a RecurrencePattern object.

Remarks

This property is only valid for appointments.

When you create a RecurrencePattern object and no time zones have been specified for the appointment, StartTime and EndTime of the RecurrencePattern object are based on the time zone specified by Application.TimeZones.CurrentTimeZone.

If you want to create a recurring appointment for a particular time zone, you should first create an AppointmentItem, set AppointmentItem.StartTimeZone, and then call AppointmentItem.GetRecurrencePattern. The RecurrencePattern object returned will have both StartTime and EndTime based on the time zone specified by AppointmentItem.StartTimeZone. Note that in the Appointment Recurrence dialog box, the time indicated as Start is RecurrencePattern.StartTime which is based on AppointmentItem.StartTimeZone, but the time indicated as End is not always the same as RecurrencePattern.EndTime which is based on AppointmentItem.StartTimeZone; the displayed time value is based on AppointmentItem.EndTimeZone.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Exceptions Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Exceptions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the Exceptions collection for a specified series of recurring appointments. Read-only.

Syntax

expression .Exceptions

expression A variable that represents a RecurrencePattern object.

Remarks

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the GetRecurrencePattern method. By setting the RecurrencePattern properties, RecurrenceType, PatternStartDate, and PatternEndDate , the appointments are now a recurring series that occur on a daily basis for the period of one year.

An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original Subject and OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Release references to the appointment series

 Set myApptItem = Nothing

 Set myRecurrPatt = Nothing

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.Item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Instance Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Instance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the count for which the recurrence pattern is valid for a given interval. Read/write.

Syntax

expression .Instance

expression A variable that represents a RecurrencePattern object.

Remarks

This property is only valid for recurrences of the olRecursMonthNth and olRecursYearNth type and allows the definition of a recurrence pattern that is only valid for the Nth occurrence, such as "the 2nd Sunday in March" pattern. The count is set numerically: 1 for the first, 2 for the second, and so on through 5 for the last. Values greater than 5 will generate errors when the pattern is saved.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Interval Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Interval Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the number of units of a given recurrence type between occurrences. Read/write.

Syntax

expression .Interval

expression A variable that represents a RecurrencePattern object.

Remarks

The Interval property must be set before setting PatternEndDate.

For example, setting the Interval property to 2 and the RecurrenceType property to olRecursWeekly would cause the pattern to occur every second week.

When RecurrenceType is set to olRecursYearNth or olRecursYear, the Interval property indicates the number of years between occurrences. For example, Interval equals 1 indicates the recurrence is every year, Interval equals 2 indicates the recurrence is every 2 years, and so on.

Example

This Visual Basic for Applications example uses GetRecurrencePattern to obtain the RecurrencePattern object for the newly-created AppointmentItem. The properties, RecurrenceType , DayOfWeekMask , PatternStartDate , Interval , PatternEndDate , and Subject are set, the appointment is saved and then displayed with the pattern: "Occurs every 3 week(s) on Monday effective 1/21/2003 until 12/21/2004 from 2:00 PM to 5:00 PM."

VBA Copy code Copy code
Sub CreateAppointment()

 Dim myApptItem As AppointmentItem

 Dim myRecurrPatt As RecurrencePattern

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursWeekly

 myRecurrPatt.DayOfWeekMask = olMonday

 myRecurrPatt.PatternStartDate = #1/21/2003 2:00:00 PM#

 myRecurrPatt.Interval = 3

 myRecurrPatt.PatternEndDate = #12/21/2004 5:00:00 PM#

 myApptItem.Subject = "Important Appointment"

 myApptItem.Save

 myApptItem.Display

 Set myOlApp = Nothing

 Set myApptItem = Nothing

 Set myRecurrPatt = Nothing

End Sub

See also

Concepts

How to: Create an Appointment as a Meeting on the Calendar
RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.MonthOfYear Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.MonthOfYear Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating which month of the year is valid for the specified recurrence pattern. Read/write.

Syntax

expression .MonthOfYear

expression A variable that represents a RecurrencePattern object.

Remarks

The value can be a number from 1 through 12. For example, setting this property to 5 and the RecurrenceType property to olRecursYearly would cause this recurrence pattern to occur every May. This property is only valid for recurrence patterns whose RecurrenceType property is set to olRecursYearly or olRecursYearNth.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.NoEndDate Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.NoEndDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the recurrence pattern has no end date. Read/write.

Syntax

expression .NoEndDate

expression A variable that represents a RecurrencePattern object.

Remarks

This property must be coordinated with other properties when setting up a recurrence pattern. If the PatternEndDate property or the Occurrences property is set, the pattern is considered to be finite and the NoEndDate property is False. If neither PatternEndDate nor Occurrences is set, the pattern is considered infinite and NoEndDate is True.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Occurrences Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Occurrences Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the number of occurrences of the recurrence pattern. Read/write.

Syntax

expression .Occurrences

expression A variable that represents a RecurrencePattern object.

Remarks

This property allows the definition of a recurrence pattern that is only valid for the specified number of subsequent occurrences. For example, you can set this property to 10 for a formal training course that will be held on the next ten Thursday evenings. This property must be coordinated with other properties when setting up a recurrence pattern. If the PatternEndDate property or the Occurrences property is set, the pattern is considered to be finite and the NoEndDate property is False. If neither PatternEndDate nor Occurrences is set, the pattern is considered infinite and NoEndDate is True.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Parent Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a RecurrencePattern object.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.PatternEndDate Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.PatternEndDate Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the end date for the recurrence pattern. Read/write.

Syntax

expression .PatternEndDate

expression A variable that represents a RecurrencePattern object.

Remarks

This property is optional but must be coordinated with other properties when setting up a recurrence pattern. If this property or the Occurrences property is set, the pattern is considered to be finite, and the NoEndDate property is False. If neither PatternEndDate nor Occurrences is set, the pattern is considered infinite and NoEndDate is True. The Interval property must be set before setting PatternEndDate.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.PatternStartDate Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.PatternStartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the start date for the recurrence pattern. Read/write.

Syntax

expression .PatternStartDate

expression A variable that represents a RecurrencePattern object.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.RecurrenceType Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.RecurrenceType Property (Outlook)
See also Send feedback

Returns or sets an OlRecurrenceType constant specifying the frequency of occurrences for the recurrence pattern. Read/write.

Syntax

expression .RecurrenceType

expression A variable that represents a RecurrencePattern object.

Remarks

You must set the RecurrenceType property before you set other properties for a RecurrencePattern object. The RecurrencePattern properties that you can set subsequently depends on the value of RecurrenceType, as shown in the following table:

OlRecurrenceType | Valid RecurrencePattern Properties
olRecursDaily | Duration , EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime
olRecursWeekly | DayOfWeekMask , Duration, EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime
olRecursMonthly | DayOfMonth , Duration, EndTime, Interval, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime
olRecursMonthNth | DayOfWeekMask, Duration, EndTime, Interval, Instance, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime
olRecursYearly | DayOfMonth, Duration, EndTime, Interval, MonthOfYear, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime
olRecursYearNth | DayOfWeekMask, Duration, EndTime, Interval, Instance, NoEndDate, Occurrences, PatternStartDate, PatternEndDate, StartTime

Example

This Visual Basic for Applications example uses GetRecurrencePattern to obtain the RecurrencePattern object for the newly-created AppointmentItem. The properties, RecurrenceType , DayOfWeekMask, MonthOfYear, Instance, Occurences, StartTime, EndTime, and Subject are set, the appointment is saved and then displayed with the pattern: "Occurs the first Monday of June effective 6/1/2007 until 6/6/2016 from 2:00 PM to 5:00 PM."

VBA Copy code Copy code
Sub RecurringYearNth()

 Dim oAppt As AppointmentItem

 Dim oPattern As RecurrencePattern

 Set oAppt = Application.CreateItem(olAppointmentItem)

 Set oPattern = oAppt.GetRecurrencePattern

 With oPattern

 .RecurrenceType = olRecursYearNth

 .DayOfWeekMask = olMonday

 .MonthOfYear = 6

 .Instance = 1

 .Occurrences = 10

 .Duration = 180

 .PatternStartDate = #6/1/2007#

 .StartTime = #2:00:00 PM#

 .EndTime = #5:00:00 PM#

 End With

 oAppt.Subject = "Recurring YearNth Appointment"

 oAppt.Save

 oAppt.Display

End Sub

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Regenerate Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Regenerate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the task should be regenerated following this pass through the recurrence pattern. Read/write.

Syntax

expression .Regenerate

expression A variable that represents a RecurrencePattern object.

Remarks

This property is used to control the regeneration of the task as each occurrence of a recurring task is completed. It is only valid for tasks. It is not valid for appointments.

To create a recurrence pattern, you must first set the RecurrenceType property to set the frequency, then set the Regenerate property to True to regenerate the task. After setting Regenerate to True, do not set it to False. If you subsequently set Regenerate to False, then you should set up the recurrence pattern again by getting a new RecurrencePattern object.

Example

This Visual Basic for Applications (VBA) example creates a task called "Oil Change" that recurs every three months and uses the Regenerate property to set it to regenerate after each recurrence.

VBA Copy code Copy code
Sub CreateTaskOilChange()

 Dim myItem As Outlook.TaskItem

 Dim myPattern As Outlook.RecurrencePattern

 Set myItem = Application.CreateItem(olTaskItem)

 Set myPattern = myItem.GetRecurrencePattern

 myPattern.RecurrenceType = olRecursMonthly

 myPattern.Regenerate = True

 myPattern.Interval = 3

 myItem.Subject = "Oil Change"

 myItem.Save

 myItem.Display

End Sub

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.Session Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a RecurrencePattern object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern.StartTime Property (Outlook)

 Copy code hover
[image]

RecurrencePattern.StartTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the start time for a recurrence pattern. Read/write.

Syntax

expression .StartTime

expression A variable that represents a RecurrencePattern object.

Remarks

This property is only valid for appointments.

When you create a RecurrencePattern object and no time zones have been specified for the appointment, StartTime and EndTime of the RecurrencePattern object are based on the time zone specified by Application.TimeZones.CurrentTimeZone.

If you want to create a recurring appointment for a particular time zone, you should first create an AppointmentItem, set AppointmentItem.StartTimeZone, and then call AppointmentItem.GetRecurrencePattern. The RecurrencePattern object returned will have both StartTime and EndTime based on the time zone specified by AppointmentItem.StartTimeZone. Note that in the Appointment Recurrence dialog box, the time indicated as Start is RecurrencePattern.StartTime which is based on AppointmentItem.StartTimeZone, but the time indicated as End is not always the same as RecurrencePattern.EndTime which is based on AppointmentItem.StartTimeZone; the displayed time value is based on AppointmentItem.EndTimeZone.

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


RecurrencePattern Methods (Outlook)

 Copy code hover
[image]

RecurrencePattern Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetOccurrence | Returns a specific instance of the AppointmentItem object on the specified date.


RecurrencePattern.GetOccurrence Method (Outlook)

 Copy code hover
[image]

RecurrencePattern.GetOccurrence Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a specific instance of the AppointmentItem object on the specified date.

Syntax

expression .GetOccurrence(StartDate)

expression A variable that represents a RecurrencePattern object.

Parameters

Name | Required/Optional | Data Type | Description
StartDate | Required | Date | A Date value that represents local time.

Return Value

An AppointmentItem object that represents the specific appointment on the specified date.

Remarks

The GetOccurrence method generates an error if no appointment of that series exists on the specified date.

When you work with recurring appointment items, you should release any prior references, obtain new references to the recurring appointment item before you access or modify the item, and release these references as soon as you are finished and have saved the changes. This practice applies to the recurring AppointmentItem object, and any Exception or RecurrencePattern object. To release a reference in Visual Basic for Applications (VBA) or Visual Basic, set that existing object to Nothing. In C#, explicitly release the memory for that object. For a code example, see the topic for the AppointmentItem object.

Note that even after you release your reference and attempt to obtain a new reference, if there is still an active reference, held by another add-in or Outlook, to one of the above objects, your new reference will still point to an out-of-date copy of the object. Therefore, it is important that you release your references as soon as you are finished with the recurring appointment.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create an AppointmentItem object. The RecurrencePattern is obtained for this item using the GetRecurrencePattern method. By setting the RecurrencePattern properties, RecurrenceType, PatternStartDate, and PatternEndDate , the appointments are now a recurring series that occur on a daily basis for the period of one year.

An Exception object is created when one instance of this recurring appointment is obtained using the GetOccurrence method and properties for this instance are altered. This exception to the series of appointments is obtained using the GetRecurrencePattern method to access the Exceptions collection associated with this series. Message boxes display the original Subject and OriginalDate for this exception to the series of appointments and the current date, time, and subject for this exception.

VBA Copy code Copy code
Public Sub cmdExample()

 Dim myApptItem As Outlook.AppointmentItem

 Dim myRecurrPatt As Outlook.RecurrencePattern

 Dim myNamespace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myItems As Outlook.Items

 Dim myDate As Date

 Dim myOddApptItem As Outlook.AppointmentItem

 Dim saveSubject As String

 Dim newDate As Date

 Dim myException As Outlook.Exception

 Set myApptItem = Application.CreateItem(olAppointmentItem)

 myApptItem.Start = #2/2/2003 3:00:00 PM#

 myApptItem.End = #2/2/2003 4:00:00 PM#

 myApptItem.Subject = "Meet with Boss"

 'Get the recurrence pattern for this appointment

 'and set it so that this is a daily appointment

 'that begins on 2/2/03 and ends on 2/2/04

 'and save it.

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 myRecurrPatt.RecurrenceType = olRecursDaily

 myRecurrPatt.PatternStartDate = #2/2/2003#

 myRecurrPatt.PatternEndDate = #2/2/2004#

 myApptItem.Save

 'Access the items in the Calendar folder to locate

 'the master AppointmentItem for the new series.

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myFolder = myNamespace.GetDefaultFolder(olFolderCalendar)

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 'Get the recurrence pattern for this appointment

 'and obtain the occurrence for 3/12/03.

 myDate = #3/12/2003 3:00:00 PM#

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myOddApptItem = myRecurrPatt.GetOccurrence(myDate)

 'Save the existing subject. Change the subject and

 'starting time for this particular appointment

 'and save it.

 saveSubject = myOddApptItem.Subject

 myOddApptItem.Subject = "Meet NEW Boss"

 newDate = #3/12/2003 3:30:00 PM#

 myOddApptItem.Start = newDate

 myOddApptItem.Save

 'Release references to the appointment series

 Set myApptItem = Nothing

 Set myRecurrPatt = Nothing

 'Get the recurrence pattern for the master

 'AppointmentItem. Access the collection of

 'exceptions to the regular appointments.

 Set myItems = myFolder.Items

 Set myApptItem = myItems("Meet with Boss")

 Set myRecurrPatt = myApptItem.GetRecurrencePattern

 Set myException = myRecurrPatt.Exceptions.Item(1)

 'Display the original date, time, and subject

 'for this exception.

 MsgBox myException.OriginalDate & ": " & saveSubject

 'Display the current date, time, and subject

 'for this exception.

 MsgBox myException.AppointmentItem.Start & ": " & _

 myException.AppointmentItem.Subject

End Sub

See also

Concepts

RecurrencePattern Object

Other resources

RecurrencePattern Object Members


Reminder Object (Outlook)

 Copy code hover
[image]

Reminder Object (Outlook)
See also Send feedback

Represents an Outlook reminder.

Remarks

Reminders allow users to keep track of upcoming appointments by scheduling a pop-up dialog box to appear at a given time. In addition to appointments, reminders can occur for tasks, contacts and e-mail messages.

Use Reminders(index), where index is the name or index number of the reminder, to return a single Reminder object.

Reminders are created programmatically when a new Microsoft Outlook item, such as an AppointmentItem object, is created and the item 's ReminderSet property is set to True.

Use the Reminders collection's Remove method to remove a Reminder object from the collection. Once a reminder is removed from its associated item, the AppointmentItem object's ReminderSet property is set to False.

Example

The following example displays the caption of the first reminder in the collection.

VBA Copy code Copy code
Sub ViewReminderInfo()

 'Displays information about first reminder in collection

 Dim colReminders As Outlook.Reminders

 Dim objRem As Reminder

 Set colReminders = Application.Reminders

 'If there are reminders, display message

 If colReminders.Count <> 0 Then

 Set objRem = colReminders.Item(1)

 MsgBox "The caption of the first reminder in the collection is: " & _

 objRem.Caption

 Else

 MsgBox "There are no reminders in the collection."

 End If

End Sub

The following example creates a new appointment item and sets the ReminderSet property to True, adding a new Reminder object to the Reminders collection.

VBA Copy code Copy code
Sub AddAppt()

 'Adds a new appointment and reminder to the reminders collection

 Dim objApt As AppointmentItem

 Set objApt = Application.CreateItem(olAppointmentItem)

 objApt.ReminderSet = True

 objApt.Subject = "Tuesday's meeting"

 objApt.Save

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Reminder Object Members


Reminder Members (Outlook)

 Copy code hover
[image]

Reminder Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an Outlook reminder.

Methods

Name | Description
Dismiss | Dismisses the current reminder.
Snooze | Delays the reminder by a specified time.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsVisible | Returns a Boolean that determines if the reminder is currently visible. Read-only.
Item | Returns an Object corresponding to the specified Outlook item. Read-only.
NextReminderDate | Returns a Date that indicates the next time the specified reminder will occur. Read-only.
OriginalReminderDate | Returns a Date that specifies the original date and time that the specified reminder is set to occur. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Reminder Properties (Outlook)

 Copy code hover
[image]

Reminder Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Caption | Returns a String representing the title. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
IsVisible | Returns a Boolean that determines if the reminder is currently visible. Read-only.
Item | Returns an Object corresponding to the specified Outlook item. Read-only.
NextReminderDate | Returns a Date that indicates the next time the specified reminder will occur. Read-only.
OriginalReminderDate | Returns a Date that specifies the original date and time that the specified reminder is set to occur. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Reminder.Application Property (Outlook)

 Copy code hover
[image]

Reminder.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Reminder object.

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Caption Property (Outlook)

 Copy code hover
[image]

Reminder.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the title. Read-only.

Syntax

expression .Caption

expression A variable that represents a Reminder object.

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Class Property (Outlook)

 Copy code hover
[image]

Reminder.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Reminder object.

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.IsVisible Property (Outlook)

 Copy code hover
[image]

Reminder.IsVisible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the reminder is currently visible. Read-only.

Syntax

expression .IsVisible

expression A variable that represents a Reminder object.

Remarks

Outlook determines the return value of this property based on the state of the current reminder. All active reminders are visible. If IsVisible is True, the reminder is visible.

Example

The following Microsoft Visual Basic for Applications (VBA) example dismisses all reminders that are currently visible. For example, if the current reminder is active, the IsVisible property will return True.

VBA Copy code Copy code
Sub DismissReminders()

 'Dismisses any active reminders.

 Dim objRems As Outlook.Reminders

 Dim objRem As Outlook.Reminder

 Dim i As Integer

 Set objRems = Application.Reminders

 For i = objRems.Count To 1 Step -1

 If objRems(i).IsVisible = True Then

 objRems(i).Dismiss

 End If

 Next

 Set olApp = Nothing

 Set objRems = Nothing

 Set objRem = Nothing

End Sub

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Item Property (Outlook)

 Copy code hover
[image]

Reminder.Item Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Object corresponding to the specified Outlook item. Read-only.

Syntax

expression .Item

expression A variable that represents a Reminder object.

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.NextReminderDate Property (Outlook)

 Copy code hover
[image]

Reminder.NextReminderDate Property (Outlook)
See also Send feedback

Returns a Date that indicates the next time the specified reminder will occur. Read-only.

Syntax

expression .NextReminderDate

expression A variable that represents a Reminder object.

Remarks

The NextReminderDate property value changes every time the object's Snooze method is executed or when the user clicks the Snooze button.

Example

The following example creates a report of all reminders in the collection and the dates when they will next occur. The subroutine concatenates the Caption and NextReminderDate properties into a string and displays the string in a dialog box.

VBA Copy code Copy code
Sub DisplayNextDateReport()

 'Displays the next time all reminders will be displayed.

 Dim objRems As Outlook.Reminders

 Dim objRem As Outlook.Reminder

 Dim strTitle As String

 Dim strReport As String

 Set objRems = Application.Reminders

 strTitle = "Current Reminder Schedule:"

 strReport = ""

 'Check if any reminders exist.

 If objRems.Count = 0 Then

 MsgBox "There are no current reminders."

 Else

 For Each objRem In objRems

 'Add information to string.

 strReport = strReport & objRem.Caption & vbTab & _

 objRem.NextReminderDate & vbCr

 Next objRem

 'Display report in dialog box

 MsgBox strTitle & vbCr & vbCr & strReport

 End If

End Sub

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.OriginalReminderDate Property (Outlook)

 Copy code hover
[image]

Reminder.OriginalReminderDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that specifies the original date and time that the specified reminder is set to occur. Read-only.

Syntax

expression .OriginalReminderDate

expression A variable that represents a Reminder object.

Remarks

This value corresponds to the original date and time value before the Snooze method is executed or the user clicks the Snooze button.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a report of all reminders in the Reminders collection and the dates at which they are scheduled to occur. The subroutine concatenates the Caption and OriginalReminderDate properties of all Reminder objects in the collection into a string and displays the string in a dialog box.

VBA Copy code Copy code
Sub DisplayOriginalDateReport()

 'Displays the time at which all reminders will be displayed.

 Dim objRems As Outlook.Reminders

 Dim objRem As Outlook.Reminder

 Dim strTitle As String

 Dim strReport As String

 Set objRems = Application.Reminders

 strTitle = "Original Reminder Schedule:"

 strReport = ""

 'Check if any reminders exist.

 If objRems.Count = 0 Then

 MsgBox "There are no current reminders."

 Else

 For Each objRem In objRems

 'Add info to string

 strReport = strReport & objRem.Caption & vbTab & vbTab & _

 objRem.OriginalReminderDate & vbCr

 Next objRem

 'Display report in dialog

 MsgBox strTitle & vbCr & vbCr & strReport

 End If

End Sub

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Parent Property (Outlook)

 Copy code hover
[image]

Reminder.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Reminder object.

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Session Property (Outlook)

 Copy code hover
[image]

Reminder.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Reminder object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder Methods (Outlook)

 Copy code hover
[image]

Reminder Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Dismiss | Dismisses the current reminder.
Snooze | Delays the reminder by a specified time.


Reminder.Dismiss Method (Outlook)

 Copy code hover
[image]

Reminder.Dismiss Method (Outlook)
See also Send feedback

Published: July 16, 2012

Dismisses the current reminder.

Syntax

expression .Dismiss

expression A variable that represents a Reminder object.

Remarks

The Dismiss method will fail if there is no visible reminder.

Example

The following example dismisses all active reminders. A reminder is active if its IsVisible property is set to True.

VBA Copy code Copy code
Sub DismissReminders()

'Dismisses any active reminders.

 Dim objRems As Outlook.Reminders

 Dim objRem As Outlook.Reminder

 Dim i As Integer

 Set objRems = Application.Reminders

 For i = objRems.Count To 1 Step -1

 If objRems(i).IsVisible = True Then

 objRems(i).Dismiss

 End If

 Next

 Set olApp = Nothing

 Set objRems = Nothing

 Set objRem = Nothing

End Sub

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminder.Snooze Method (Outlook)

 Copy code hover
[image]

Reminder.Snooze Method (Outlook)
See also Send feedback

Published: July 16, 2012

Delays the reminder by a specified time.

Syntax

expression .Snooze(SnoozeTime)

expression An expression that returns a Reminder object.

Parameters

Name | Required/Optional | Data Type | Description
SnoozeTime | Optional | Variant | Indicates the amount of time (in minutes) to delay the reminder. The default value is 5 minutes.

Remarks

This is equivalent to the user clicking the Snooze button.

This method will fail if the current reminder is not active.

Example

The following Microsoft Visual Basic for Applications (VBA) example delays all active reminders by a specified amount of time.

VBA Copy code Copy code
Sub SnoozeReminders()

 'Delays all reminders by a specified amount of time

 Dim objRems As Outlook.Reminders

 Dim objRem As Outlook.Reminder

 Dim varTime As Variant

 Set objRems = Application.Reminders

 varTime = InputBox("Type the number of minutes to delay")

 For Each objRem In objRems

 If objRem.IsVisible = True Then

 objRem.Snooze (varTime)

 End If

 Next objRem

End Sub

See also

Concepts

Reminder Object

Other resources

Reminder Object Members


Reminders Object (Outlook)

 Copy code hover
[image]

Reminders Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of all the Reminder objects in a Microsoft Outlook application that represent the reminders for all pending items.

Remarks

Use the Application object's Reminders property to return the Reminders collection. Use Reminders(index), where index is the name or ordinal value of the reminder, to return a single Reminder object.

Reminders are created programmatically when a new Outlook item is created with a reminder. For example, a reminder is created when an AppointmentItem object is created and the AppointmentItem object's ReminderSet property is set to True.

Example

The following example displays the captions of each reminder in the list.

VBA Copy code Copy code
Sub ViewReminderInfo()
 'Lists reminder caption information
 Dim objRem As Reminder
 Dim objRems As Reminders
 Dim strTitle As String
 Dim strReport As String

 Set objRems = Application.Reminders
 strTitle = "Current Reminders:"
 'If there are reminders, display message
 If Application.Reminders.Count <> 0 Then
 For Each objRem In objRems
 'If string is empty, create new string
 If strReport = "" Then
 strReport = objRem.Caption & vbCr
 Else
 'Add info to string
 strReport = strReport & objRem.Caption & vbCr
 End If
 Next objRem
 'Display report in dialog
 MsgBox strTitle & vbCr & vbCr & strReport
 Else
 MsgBox "There are no reminders in the collection."
 End If
End Sub

The following example creates a new appointment item and sets the ReminderSet property to True, adding a new Reminder object to the Reminders collection.

VBA Copy code Copy code
Sub AddAppt()
 'Adds a new appointment and reminder to the reminders collection
 Dim objApt As AppointmentItem

 Set objApt = Application.CreateItem(olAppointmentItem)
 objApt.ReminderSet = True
 objApt.Subject = "Tuesday's meeting"
 objApt.Save
End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Reminders Object Members


Reminders Members (Outlook)

 Copy code hover
[image]

Reminders Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of all the Reminder objects in a Microsoft Outlook application that represent the reminders for all pending items.

Events

Name | Description
BeforeReminderShow | Occurs before the Reminder dialog box is displayed.
ReminderAdd | Occurs after a reminder is added.
ReminderChange | Occurs after a reminder has been modified.
ReminderFire | Occurs before the reminder is executed.
ReminderRemove | Occurs when a Reminder object has been removed from the collection.
Snooze | Occurs when a reminder is dismissed using the Snooze button.

Methods

Name | Description
Item | Returns a Reminder object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Reminders Properties (Outlook)

 Copy code hover
[image]

Reminders Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Reminders.Application Property (Outlook)

 Copy code hover
[image]

Reminders.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Reminders object.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Class Property (Outlook)

 Copy code hover
[image]

Reminders.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Reminders object.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Count Property (Outlook)

 Copy code hover
[image]

Reminders.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Reminders object.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Parent Property (Outlook)

 Copy code hover
[image]

Reminders.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Reminders object.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Session Property (Outlook)

 Copy code hover
[image]

Reminders.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Reminders object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders Methods (Outlook)

 Copy code hover
[image]

Reminders Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns a Reminder object from the collection.
Remove | Removes an object from the collection.


Reminders.Item Method (Outlook)

 Copy code hover
[image]

Reminders.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Reminder object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A Reminder object that represents the specified object.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Remove Method (Outlook)

 Copy code hover
[image]

Reminders.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The 1-based index value of the object within the collection.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders Events (Outlook)

 Copy code hover
[image]

Reminders Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeReminderShow | Occurs before the Reminder dialog box is displayed.
ReminderAdd | Occurs after a reminder is added.
ReminderChange | Occurs after a reminder has been modified.
ReminderFire | Occurs before the reminder is executed.
ReminderRemove | Occurs when a Reminder object has been removed from the collection.
Snooze | Occurs when a reminder is dismissed using the Snooze button.


Reminders.BeforeReminderShow Event (Outlook)

 Copy code hover
[image]

Reminders.BeforeReminderShow Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the Reminder dialog box is displayed.

Syntax

expression .BeforeReminderShow(Cancel)

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | True to cancel the event. The default value is False.

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.ReminderAdd Event (Outlook)

 Copy code hover
[image]

Reminders.ReminderAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a reminder is added.

Syntax

expression .ReminderAdd(ReminderObject)

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
ReminderObject | Required | [_REMINDER] | The Reminder object added to the collection.

Remarks

A reminder is not actually created until the associated Microsoft Outlook item has been saved. Therefore, this event will not occur until the associated item object has been saved.

Example

The following example displays the date of the next reminder when a reminder is added to the collection.

VBA Copy code Copy code
Public WithEvents objReminders As Outlook.Reminders

Sub Initialize_handler()

 Set objReminders = Application.Reminders

End Sub

Private Sub objReminders_ReminderAdd(ByVal ReminderObject As Reminder)

 'Occurs when a Reminder object is added to the collection using the user interface or object model

 MsgBox "A new reminder is added that will fire at: " & _

 ReminderObject.NextReminderDate

End Sub

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.ReminderChange Event (Outlook)

 Copy code hover
[image]

Reminders.ReminderChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after a reminder has been modified.

Syntax

expression .ReminderChange(ReminderObject)

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
ReminderObject | Required | Reminder | The Reminder object that has been modified.

Example

The following Microsoft Visual Basic for Applications (VBA) example prompts the user with a message every time a reminder is modified.

VBA Copy code Copy code
Public WithEvents objReminders As Outlook.Reminders

Sub Initialize_handler()

 Set objReminders = Application.Reminders

End Sub

Private Sub objReminders_ReminderChange(ByVal ReminderObject As Reminder)

 'Occurs when reminder is changed

 MsgBox "The reminder " & ReminderObject.Caption & " has changed."

End Sub

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.ReminderFire Event (Outlook)

 Copy code hover
[image]

Reminders.ReminderFire Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the reminder is executed.

Syntax

expression .ReminderFire(ReminderObject)

expression A variable that represents a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
ReminderObject | Required | Reminder | The Reminder object that has been executed.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the item that fired the Reminder event every time a reminder is executed.

VBA Copy code Copy code
Public WithEvents objReminders As Outlook.Reminders

Sub Initialize_handler()

 Set objReminders = Application.Reminders

End Sub

Private Sub objReminders_ReminderFire(ByVal ReminderObject As Reminder)

 'Opens the item when a reminder executes

 ReminderObject.Item.Display

End Sub

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.ReminderRemove Event (Outlook)

 Copy code hover
[image]

Reminders.ReminderRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a Reminder object has been removed from the collection.

Syntax

expression .ReminderRemove

expression A variable that represents a Reminders object.

Remarks

A reminder can be removed from the Reminders collection by any of the following means:

  • The Reminders collection's Removemethod.

  • The Reminder object's Dismissmethod.

  • When the user clicks the Dismiss button.

  • When a user turns off a meeting reminder from within the associated item.

  • When a user deletes an item that contains a reminder.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays a message to the user when a Reminder object is removed from the collection.

VBA Copy code Copy code
Public WithEvents objReminders As Outlook.Reminders

Sub Initialize_handler()

 Set objReminders = Application.Reminders

End Sub

Private Sub objReminders_ReminderRemove()

'Occurs when a reminder is removed from the collection

'or the user clicks Dismiss

 MsgBox "A reminder has been removed from the collection."

End Sub

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


Reminders.Snooze Event (Outlook)

 Copy code hover
[image]

Reminders.Snooze Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a reminder is dismissed using the Snooze button.

Syntax

expression .Snooze(ReminderObject)

expression An expression that returns a Reminders object.

Parameters

Name | Required/Optional | Data Type | Description
ReminderObject | Required | Reminder | Represents the reminder to dismiss.

Remarks

This event will fire when the Snooze method is executed, or when the user clicks the Snooze button.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the original date and time set for the Reminder object that has been snoozed.

VBA Copy code Copy code
Public WithEvents objReminders As Outlook.Reminders

Sub Initialize_Handler()
 Set objReminders = Application.Reminders
End Sub

Private Sub objReminders_Snooze(ByVal ReminderObject As Reminder)
 'Occurs when a user clicks Snooze or when snooze is
 'programmatically executed.
 MsgBox "The reminder was originally set at " _
 & ReminderObject.OriginalReminderDate
End Sub

See also

Concepts

Reminders Object

Other resources

Reminders Object Members


RemoteItem Object (Outlook)

 Copy code hover
[image]

RemoteItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a remote item in an Inbox folder.

Remarks

The RemoteItem object is similar to the MailItem object, but it contains only the Subject, Received Date and Time, Sender, Size, and the first 256 characters of the body of the message. It is used to give someone connecting in remote mode enough information to decide whether or not to download the corresponding mail message. However, the headers in items contained in an Offline Folders file (.ost) cannot be accessed using the RemoteItem object.

Unlike other Microsoft Outlook objects, you cannot create this object. Remote items are created by Outlook automatically when you use a Remote Access System (RAS) connection. Each RemoteItem object created on the local system corresponds to a preexisting MailItem object on the remote system.

The RemoteItem object inherits a number of properties, methods, and events that, because of the nature of the object, have no function. The Object Browser shows these properties, methods, and events as belonging to the RemoteItem object, but trying to use them will produce no effect.

The methods that do not work for the RemoteItem object include Close, Copy, Display, Move, and Save.

The properties that do not work for the RemoteItem object include BillingInformation, Body, Categories, Companies, and Mileage.

The events that do not work for the RemoteItem object include Open, Close, Forward, Reply, ReplyAll, and Send.

See also

Concepts

Outlook Object Model Reference

Other resources

RemoteItem Object Members


RemoteItem Members (Outlook)

 Copy code hover
[image]

RemoteItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a remote item in an Inbox folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the RemoteItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HasAttachment | Returns a Boolean that is True (default) if the remote item has an attachment associated with it. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent RemoteItem object. Read-only.
RemoteMessageClass | Returns a String indicating the message class for the remote item. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TransferSize | Returns a Long specifying the transfer size (in bytes) for the remote item. Read-only.
TransferTime | Returns a Long indicating the transfer time (in seconds) for the remote item. Read-only.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


RemoteItem Properties (Outlook)

 Copy code hover
[image]

RemoteItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the RemoteItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
HasAttachment | Returns a Boolean that is True (default) if the remote item has an attachment associated with it. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent RemoteItem object. Read-only.
RemoteMessageClass | Returns a String indicating the message class for the remote item. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TransferSize | Returns a Long specifying the transfer size (in bytes) for the remote item. Read-only.
TransferTime | Returns a Long indicating the transfer time (in seconds) for the remote item. Read-only.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


RemoteItem.Actions Property (Outlook)

 Copy code hover
[image]

RemoteItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Application Property (Outlook)

 Copy code hover
[image]

RemoteItem.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Attachments Property (Outlook)

 Copy code hover
[image]

RemoteItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

RemoteItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a RemoteItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its RemoteItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

RemoteItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a RemoteItem object.

Remarks

This is a free-form text field.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Body Property (Outlook)

 Copy code hover
[image]

RemoteItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Categories Property (Outlook)

 Copy code hover
[image]

RemoteItem.Categories Property (Outlook)
See also Send feedback

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a RemoteItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Class Property (Outlook)

 Copy code hover
[image]

RemoteItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Companies Property (Outlook)

 Copy code hover
[image]

RemoteItem.Companies Property (Outlook)
See also Send feedback

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a RemoteItem object.

Remarks

This is a free-form text field.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Conflicts Property (Outlook)

 Copy code hover
[image]

RemoteItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ConversationID Property (Outlook)

 Copy code hover
[image]

RemoteItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the RemoteItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a RemoteItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the RemoteItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

RemoteItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

RemoteItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.CreationTime Property (Outlook)

 Copy code hover
[image]

RemoteItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.DownloadState Property (Outlook)

 Copy code hover
[image]

RemoteItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a RemoteItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.EntryID Property (Outlook)

 Copy code hover
[image]

RemoteItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.FormDescription Property (Outlook)

 Copy code hover
[image]

RemoteItem.FormDescription Property (Outlook)
See also Send feedback

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.GetInspector Property (Outlook)

 Copy code hover
[image]

RemoteItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a RemoteItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.HasAttachment Property (Outlook)

 Copy code hover
[image]

RemoteItem.HasAttachment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that is True (default) if the remote item has an attachment associated with it. Read-only.

Syntax

expression .HasAttachment

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Importance Property (Outlook)

 Copy code hover
[image]

RemoteItem.Importance Property (Outlook)
See also Send feedback

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.IsConflict Property (Outlook)

 Copy code hover
[image]

RemoteItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a RemoteItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

RemoteItem.ItemProperties Property (Outlook)
See also Send feedback

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a RemoteItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

RemoteItem.LastModificationTime Property (Outlook)
See also Send feedback

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

RemoteItem.MarkForDownload Property (Outlook)
See also Send feedback

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a RemoteItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.MessageClass Property (Outlook)

 Copy code hover
[image]

RemoteItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

RemoteItem Object
Item Types and Message Classes

Other resources

RemoteItem Object Members


RemoteItem.Mileage Property (Outlook)

 Copy code hover
[image]

RemoteItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a RemoteItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.NoAging Property (Outlook)

 Copy code hover
[image]

RemoteItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

RemoteItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

RemoteItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Parent Property (Outlook)

 Copy code hover
[image]

RemoteItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

RemoteItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent RemoteItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.RemoteMessageClass Property (Outlook)

 Copy code hover
[image]

RemoteItem.RemoteMessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the message class for the remote item. Read-only.

Syntax

expression .RemoteMessageClass

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Saved Property (Outlook)

 Copy code hover
[image]

RemoteItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

RemoteItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Session Property (Outlook)

 Copy code hover
[image]

RemoteItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a RemoteItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Size Property (Outlook)

 Copy code hover
[image]

RemoteItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Subject Property (Outlook)

 Copy code hover
[image]

RemoteItem.Subject Property (Outlook)
See also Send feedback

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a RemoteItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.TransferSize Property (Outlook)

 Copy code hover
[image]

RemoteItem.TransferSize Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long specifying the transfer size (in bytes) for the remote item. Read-only.

Syntax

expression .TransferSize

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.TransferTime Property (Outlook)

 Copy code hover
[image]

RemoteItem.TransferTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the transfer time (in seconds) for the remote item. Read-only.

Syntax

expression .TransferTime

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.UnRead Property (Outlook)

 Copy code hover
[image]

RemoteItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.UserProperties Property (Outlook)

 Copy code hover
[image]

RemoteItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem Methods (Outlook)

 Copy code hover
[image]

RemoteItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


RemoteItem.Close Method (Outlook)

 Copy code hover
[image]

RemoteItem.Close Method (Outlook)
See also Send feedback

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Copy Method (Outlook)

 Copy code hover
[image]

RemoteItem.Copy Method (Outlook)
See also Send feedback

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Delete Method (Outlook)

 Copy code hover
[image]

RemoteItem.Delete Method (Outlook)
See also Send feedback

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a RemoteItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

RemoteItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

RemoteItemMembers


RemoteItem.Display Method (Outlook)

 Copy code hover
[image]

RemoteItem.Display Method (Outlook)
See also Send feedback

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.GetConversation Method (Outlook)

 Copy code hover
[image]

RemoteItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a RemoteItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Move Method (Outlook)

 Copy code hover
[image]

RemoteItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.PrintOut Method (Outlook)

 Copy code hover
[image]

RemoteItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Save Method (Outlook)

 Copy code hover
[image]

RemoteItem.Save Method (Outlook)
See also Send feedback

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.SaveAs Method (Outlook)

 Copy code hover
[image]

RemoteItem.SaveAs Method (Outlook)
See also Send feedback

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

RemoteItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a RemoteItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem Events (Outlook)

 Copy code hover
[image]

RemoteItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


RemoteItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

RemoteItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a RemoteItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

RemoteItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

RemoteItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

RemoteItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the RemoteItem to be saved.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeDelete Event (Outlook)
See also Send feedback

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

RemoteItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a RemoteItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Close Event (Outlook)

 Copy code hover
[image]

RemoteItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.CustomAction Event (Outlook)

 Copy code hover
[image]

RemoteItem.CustomAction Event (Outlook)
See also Send feedback

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

RemoteItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Forward Event (Outlook)

 Copy code hover
[image]

RemoteItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Open Event (Outlook)

 Copy code hover
[image]

RemoteItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

RemoteItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Read Event (Outlook)

 Copy code hover
[image]

RemoteItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a RemoteItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

RemoteItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Reply Event (Outlook)

 Copy code hover
[image]

RemoteItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

RemoteItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Send Event (Outlook)

 Copy code hover
[image]

RemoteItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Unload Event (Outlook)

 Copy code hover
[image]

RemoteItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a RemoteItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


RemoteItem.Write Event (Outlook)

 Copy code hover
[image]

RemoteItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a RemoteItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

RemoteItem Object

Other resources

RemoteItem Object Members


ReportItem Object (Outlook)

 Copy code hover
[image]

ReportItem Object (Outlook)
See also Send feedback

Represents a mail-delivery report in an Inbox folder.

Remarks

The ReportItem object is similar to a MailItem object, and it contains a report (usually the non-delivery report) or error message from the mail transport system.

Unlike other Microsoft Outlook objects, you cannot create this object. Report items are created automatically when any report or error in general is received from the mail transport system.

See also

Concepts

Outlook Object Model Reference

Other resources

ReportItem Object Members


ReportItem Members (Outlook)

 Copy code hover
[image]

ReportItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a mail-delivery report in an Inbox folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the ReportItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ReportItem object. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the ReportItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


ReportItem Properties (Outlook)

 Copy code hover
[image]

ReportItem Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the ReportItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ReportItem object. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the ReportItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


ReportItem.Actions Property (Outlook)

 Copy code hover
[image]

ReportItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Application Property (Outlook)

 Copy code hover
[image]

ReportItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Attachments Property (Outlook)

 Copy code hover
[image]

ReportItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

ReportItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a ReportItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its ReportItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

ReportItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a ReportItem object.

Remarks

This is a free-form text field.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Body Property (Outlook)

 Copy code hover
[image]

ReportItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Categories Property (Outlook)

 Copy code hover
[image]

ReportItem.Categories Property (Outlook)
See also Send feedback

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a ReportItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Class Property (Outlook)

 Copy code hover
[image]

ReportItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Companies Property (Outlook)

 Copy code hover
[image]

ReportItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a ReportItem object.

Remarks

This is a free-form text field.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Conflicts Property (Outlook)

 Copy code hover
[image]

ReportItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ConversationID Property (Outlook)

 Copy code hover
[image]

ReportItem.ConversationID Property (Outlook)
See also Send feedback

Returns a String that uniquely identifies a Conversation object that the ReportItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a ReportItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the ReportItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

ReportItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

ReportItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.CreationTime Property (Outlook)

 Copy code hover
[image]

ReportItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.DownloadState Property (Outlook)

 Copy code hover
[image]

ReportItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a ReportItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.EntryID Property (Outlook)

 Copy code hover
[image]

ReportItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.FormDescription Property (Outlook)

 Copy code hover
[image]

ReportItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.GetInspector Property (Outlook)

 Copy code hover
[image]

ReportItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a ReportItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Importance Property (Outlook)

 Copy code hover
[image]

ReportItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.IsConflict Property (Outlook)

 Copy code hover
[image]

ReportItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a ReportItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

ReportItem.ItemProperties Property (Outlook)
See also Send feedback

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a ReportItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

ReportItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

ReportItem.MarkForDownload Property (Outlook)
See also Send feedback

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a ReportItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.MessageClass Property (Outlook)

 Copy code hover
[image]

ReportItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Mileage Property (Outlook)

 Copy code hover
[image]

ReportItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a ReportItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.NoAging Property (Outlook)

 Copy code hover
[image]

ReportItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

ReportItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

ReportItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Parent Property (Outlook)

 Copy code hover
[image]

ReportItem.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

ReportItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent ReportItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.RetentionExpirationDate Property (Outlook)

 Copy code hover
[image]

ReportItem.RetentionExpirationDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that specifies the date when the ReportItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionExpirationDate

expression A variable that represents a ReportItem object.

Remarks

A retention policy is enabled and disabled by an administrator for an Exchange Server on a mailbox level. This feature is available only on an Exchange mailbox with MRM version 2.0 or later enabled.

Microsoft Outlook calculates the value of this property based on the item retention start date and the retention period, if Outlook is in cache or offline mode. The Exchange Server specifies the value if Outlook is in online mode.

In general, the retention start date for the item is determined as follows:

  • Received or sent items: the retention start date is the received date.

  • Nonrecurring calendar items: the retention start date is the appointment end date.

  • Recurring calendar items: the retention start date is the end date of last recurrence. If there is no end date, the item never expires.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.RetentionPolicyName Property (Outlook)

 Copy code hover
[image]

ReportItem.RetentionPolicyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that specifies the name of the retention policy. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionPolicyName

expression A variable that represents a ReportItem object.

Remarks

Retention is enabled and disabled by an administrator for an Exchange Server on a mailbox level. The feature is available only on an Exchange mailbox with Messaging Records Management (MRM), version 2.0 or later enabled. An example of a retention policy name is "Define time interval for expiration Quick Searches".

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Saved Property (Outlook)

 Copy code hover
[image]

ReportItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

ReportItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Session Property (Outlook)

 Copy code hover
[image]

ReportItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ReportItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Size Property (Outlook)

 Copy code hover
[image]

ReportItem.Size Property (Outlook)
See also Send feedback

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Subject Property (Outlook)

 Copy code hover
[image]

ReportItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a ReportItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.UnRead Property (Outlook)

 Copy code hover
[image]

ReportItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.UserProperties Property (Outlook)

 Copy code hover
[image]

ReportItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem Methods (Outlook)

 Copy code hover
[image]

ReportItem Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


ReportItem.Close Method (Outlook)

 Copy code hover
[image]

ReportItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Copy Method (Outlook)

 Copy code hover
[image]

ReportItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Delete Method (Outlook)

 Copy code hover
[image]

ReportItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a ReportItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

ReportItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

ReportItem Object Members


ReportItem.Display Method (Outlook)

 Copy code hover
[image]

ReportItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.GetConversation Method (Outlook)

 Copy code hover
[image]

ReportItem.GetConversation Method (Outlook)
See also Send feedback

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a ReportItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Move Method (Outlook)

 Copy code hover
[image]

ReportItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.PrintOut Method (Outlook)

 Copy code hover
[image]

ReportItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Save Method (Outlook)

 Copy code hover
[image]

ReportItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.SaveAs Method (Outlook)

 Copy code hover
[image]

ReportItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

ReportItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a ReportItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem Events (Outlook)

 Copy code hover
[image]

ReportItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


ReportItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

ReportItem.AfterWrite Event (Outlook)
See also Send feedback

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a ReportItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

ReportItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

ReportItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

ReportItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment, )

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the ReportItem to be saved.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

ReportItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a ReportItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Close Event (Outlook)

 Copy code hover
[image]

ReportItem.Close Event (Outlook)
See also Send feedback

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.CustomAction Event (Outlook)

 Copy code hover
[image]

ReportItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

ReportItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Forward Event (Outlook)

 Copy code hover
[image]

ReportItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Open Event (Outlook)

 Copy code hover
[image]

ReportItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

ReportItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Read Event (Outlook)

 Copy code hover
[image]

ReportItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a ReportItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

ReportItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Reply Event (Outlook)

 Copy code hover
[image]

ReportItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

ReportItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Send Event (Outlook)

 Copy code hover
[image]

ReportItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Unload Event (Outlook)

 Copy code hover
[image]

ReportItem.Unload Event (Outlook)
See also Send feedback

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a ReportItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


ReportItem.Write Event (Outlook)

 Copy code hover
[image]

ReportItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a ReportItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

ReportItem Object

Other resources

ReportItem Object Members


Results Object (Outlook)

 Copy code hover
[image]

Results Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains data and results returned by the Search object and the AdvancedSearch method.

Remarks

The Results object contains properties and methods that allow you to view and manipulate data. For example the GetNext, GetPrevious, GetFirst, and GetLast methods allow you to search through the results and view the data by field. The Sort method allows you to sort the data.

Use the SearchObject.Results property to return a Results object.

Example

The following event procedure stores the results of a search in a variable named objRsts and displays the results of the search in the Immediate window.

Copy code Copy code
Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 Dim objRsts As Outlook.Results

 MsgBox "The search " & SearchObject.Tag & _

 "has completed. The scope of the search was " & _

 SearchObject.Scope & "."

 Set objRsts = SearchObject.Results

 'Print out number in Results collection

 Debug.Print objRsts.Count

 'Print out each member of Results collection

 For Each Item In objRsts

 Debug.Print Item

 Next

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Results Object Members


Results Members (Outlook)

 Copy code hover
[image]

Results Members (Outlook)
Send feedback

Published: July 16, 2012

Contains data and results returned by the Search object and the AdvancedSearch method.

Events

Name | Description
ItemAdd | Occurs when one or more items are added to the specified collection.
ItemChange | Occurs when an item in the specified collection is changed.
ItemRemove | Occurs when an item is deleted from the specified collection.

Methods

Name | Description
GetFirst | Returns the first object in the collection.
GetLast | Returns the last object in the collection.
GetNext | Returns the next object in the collection.
GetPrevious | Returns the previous object in the collection.
Item | Returns an Outlook item from a collection.
ResetColumns | Clears the properties that have been cached with the SetColumns method.
SetColumns | Caches certain properties for extremely fast access to those particular properties of an item within the collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
DefaultItemType | Returns an OlItemType constant indicating the default Outlook item type contained in the folder. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Results Properties (Outlook)

 Copy code hover
[image]

Results Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
DefaultItemType | Returns an OlItemType constant indicating the default Outlook item type contained in the folder. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Results.Application Property (Outlook)

 Copy code hover
[image]

Results.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Results object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Class Property (Outlook)

 Copy code hover
[image]

Results.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Results object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Count Property (Outlook)

 Copy code hover
[image]

Results.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Results object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.DefaultItemType Property (Outlook)

 Copy code hover
[image]

Results.DefaultItemType Property (Outlook)
See also Send feedback

Returns an OlItemType constant indicating the default Outlook item type contained in the folder. Read/write.

Syntax

expression .DefaultItemType

expression A variable that represents a Results object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Parent Property (Outlook)

 Copy code hover
[image]

Results.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Results object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Session Property (Outlook)

 Copy code hover
[image]

Results.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Results object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Results Object

Other resources

Results Object Members


Results Methods (Outlook)

 Copy code hover
[image]

Results Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetFirst | Returns the first object in the collection.
GetLast | Returns the last object in the collection.
GetNext | Returns the next object in the collection.
GetPrevious | Returns the previous object in the collection.
Item | Returns an Outlook item from a collection.
ResetColumns | Clears the properties that have been cached with the SetColumns method.
SetColumns | Caches certain properties for extremely fast access to those particular properties of an item within the collection.
Sort | Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.


Results.GetFirst Method (Outlook)

 Copy code hover
[image]

Results.GetFirst Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the first object in the collection.

Syntax

expression .GetFirst

expression A variable that represents a Results object.

Return Value

An Object value that represents the first object contained by the collection.

Remarks

Returns Nothing if no first object exists, for example, if there are no objects in the collection. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.GetLast Method (Outlook)

 Copy code hover
[image]

Results.GetLast Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the last object in the collection.

Syntax

expression .GetLast

expression A variable that represents a Results object.

Return Value

An Object value that represents the last object contained by the collection.

Remarks

It returns Nothing if no last object exists, for example, if the collection is empty. To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.GetNext Method (Outlook)

 Copy code hover
[image]

Results.GetNext Method (Outlook)
See also Send feedback

Returns the next object in the collection.

Syntax

expression .GetNext

expression A variable that represents a Results object.

Return Value

An Object value that represents the next object contained by the collection.

Remarks

It returns Nothing if no next object exists, for example, if already positioned at the end of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.GetPrevious Method (Outlook)

 Copy code hover
[image]

Results.GetPrevious Method (Outlook)
See also Send feedback

Returns the previous object in the collection.

Syntax

expression .GetPrevious

expression A variable that represents a Results object.

Return Value

An Object value that represents the previous object contained by the collection.

Remarks

It returns Nothing if no previous object exists, for example, if already positioned at the beginning of the collection.To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before calling GetNext on that collection, and call GetLast before calling GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection before entering the loop.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Item Method (Outlook)

 Copy code hover
[image]

Results.Item Method (Outlook)
See also Send feedback

Returns an Outlook item from a collection.

Syntax

expression .Item(Index)

expression A variable that represents a Results object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object value that represents the specified object.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.ResetColumns Method (Outlook)

 Copy code hover
[image]

Results.ResetColumns Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the properties that have been cached with the SetColumns method.

Syntax

expression .ResetColumns

expression A variable that represents a Results object.

Remarks

All properties are accessible after calling the ResetColumns method. SetColumns should be reused to store new properties again. ResetColumns does nothing if SetColumns has not been called first.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.SetColumns Method (Outlook)

 Copy code hover
[image]

Results.SetColumns Method (Outlook)
See also Send feedback

Published: July 16, 2012

Caches certain properties for extremely fast access to those particular properties of an item within the collection.

Syntax

expression .SetColumns(Columns)

expression A variable that represents a Results object.

Remarks

The SetColumns method is useful for iterating through the Results object. If you don't use this method, Microsoft Outlook must open each item to access the property. With the SetColumns method, Outlook only checks the properties that you have cached. Properties which are not cached are returned empty.

See also

Concepts

Results Object

Other resources

Results Object Members


Results.Sort Method (Outlook)

 Copy code hover
[image]

Results.Sort Method (Outlook)
See also Send feedback

Sorts the collection of items by the specified property. The index for the collection is reset to 1 upon completion of this method.

Syntax

expression .Sort(Property, Descending)

expression A variable that represents a Results object.

Parameters

Name | Required/Optional | Data Type | Description
Property | Required | String | The name of the property by which to sort, which may be enclosed in brackets (for example, "[CompanyName]"). May not be a user-defined field, and may not be a multi-valued property, such as a category.
Descending | Optional | Variant | True to sort in descending order. The default value is False (ascending).

Remarks

Sort only affects the order of items in a collection. It does not affect the order of items in an explorer view.

See also

Concepts

Results Object

Other resources

Results Object Members


Results Events (Outlook)

 Copy code hover
[image]

Results Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
ItemAdd | Occurs when one or more items are added to the specified collection.
ItemChange | Occurs when an item in the specified collection is changed.
ItemRemove | Occurs when an item is deleted from the specified collection.


Results.ItemAdd Event (Outlook)

 Copy code hover
[image]

Results.ItemAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when one or more items are added to the specified collection.

Syntax

expression .ItemAdd(Item)

expression A variable that represents a Results object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item that was added.

Remarks

This event does not run when a large number of items are added to the folder at once. It is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

In this Visual Basic for Applications (VBA) example, when a new contact is added to the Contacts folder, the contact item is attached to an e-mail message and sent to a distribution list named "Sales Team". The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts).Items

End Sub

Private Sub myOlItems_ItemAdd(ByVal Item As Object)

 Dim myOlMItem As Outlook.MailItem

 Dim myOlAtts As Outlook.Attachments

 Set myOlMItem = myOlApp.CreateItem(olMailItem)

 myOlMItem.Save

 Set myOlAtts = myOlMItem.Attachments

 ' Add new contact to attachments in mail message

 myOlAtts.Add Item, olByValue

 myOlMItem.To = "Sales Team"

 myOlMItem.Subject = "New contact"

 myOlMItem.Send

End Sub

See also

Concepts

Results Object

Other resources

Results Object Members


Results.ItemChange Event (Outlook)

 Copy code hover
[image]

Results.ItemChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an item in the specified collection is changed.

Syntax

expression .ItemChange(Item)

expression A variable that represents a Results object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item that was changed.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This example uses the Start property of the AppointmentItem object to determine if the appointment starts after normal business hours. If it does, and if the Sensitivity property of the AppointmentItem object is not already set to olPrivate, the example offers to mark the appointment as private.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderCalendar).Items

End Sub

Private Sub myOlItems_ItemChange(ByVal Item As Object)

Dim prompt As String

 If VBA.Format(Item.Start, "h") >= "17" And Item.Sensitivity <> olPrivate Then

 prompt = "Appointment occurs after hours. Mark it private?"

 If MsgBox(prompt, vbYesNo + vbQuestion) = vbYes Then

 Item.Sensitivity = olPrivate

 Item.Display

 End If

 End If

End Sub

See also

Concepts

Results Object

Other resources

Results Object Members


Results.ItemRemove Event (Outlook)

 Copy code hover
[image]

Results.ItemRemove Event (Outlook)
See also Send feedback

Occurs when an item is deleted from the specified collection.

Syntax

expression .ItemRemove

expression A variable that represents a Results object.

Remarks

This event does not run when the last item in a Personal Folders file (.pst) is deleted, or if 16 or more items are deleted at once from a .pst file, Microsoft Exchange mailbox, or an Exchange public folder.

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example optionally sends a notification message to a workgroup when the user removes a contact from the default Contacts folder. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myOlItems As Outlook.Items

Public Sub Initialize_handler()

 Set myOlItems = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderContacts).Items

End Sub

Private Sub myOlItems_ItemRemove()

 Dim myOlMItem As Outlook.MailItem

 If MsgBox("Do you want to notify the Sales Team?", vbYesNo + vbQuestion) = vbYes Then

 Set myOlMItem = Application.CreateItem(olMailItem)

 myOlMItem.To = "Sales Team"

 myOlMItem.Subject = "Remove Contact"

 myOlMItem.Body = "Remove the following contact from your list:"

 myOlMItem.Display

 End If

End Sub

See also

Concepts

Results Object

Other resources

Results Object Members


Row Object (Outlook)

 Copy code hover
[image]

Row Object (Outlook)
See also Send feedback

Represents a row of data in the Table object.

Version Information

Version Added: Outlook 2007

Remarks

A Table is composed of rows and columns. It represents a read-only dynamic rowset of data in a Folder or Search object. You can regard each row of a Table as an item in the folder, and each column as a property of the item. By default, the Table contains only a subset of properties for items in the folder. This makes the Table an in-memory lightweight rowset that supports fast enumeration and filtering of items in the folder.

If the Table object is obtained from Folder.GetTable, you can further specify a filter (in Table.Restrict) to obtain a more restricted set of rows in the Table.

You can use the Table methods: FindRow, FindNextRow, GetNextRow, and MoveToStart to obtain a specific row in a Table.

Use Row.GetValues to obtain an array of values that correspond to column values at that row in the Table.

Use the helper functions Row.BinaryToString, Row.LocalTimeToUTC, and Row.UTCToLocalTime to facilitate type conversion of column values at a specific row. For more information on property value representation in a Table, see Factors Affecting Property Value Representation in the Table and View Classes.

Although additions and deletions of the underlying folder are reflected by the rows in the Table, the Table does not support any events for adding, changing, and removing of rows. If you require a writeable object from the Table row, obtain the Entry ID for that row from the default EntryID column in the Table and then use the GetItemFromID method of the NameSpace object to obtain a full item, such as a MailItem or ContactItem, that supports read-write operations. For more information on default columns in a Table, see Default Properties Displayed in a Table Object.

Example

The following code sample illustrates how to obtain a Table object based on the LastModificationTime of items in the Inbox. It also shows how to customize columns in the Table, and how to enumerate and print the values of the corresponding properties of these items.

VBA Copy code Copy code
Sub DemoTable()

 'Declarations

 Dim Filter As String

 Dim oRow As Outlook.Row

 Dim oTable As Outlook.Table

 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox

 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005

 Filter = "[LastModificationTime] > '5/1/2005'"

 'Restrict with Filter

 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set

 oTable.Columns.RemoveAll

 'Specify desired properties

 With oTable.Columns

 .Add ("Subject")

 .Add ("LastModificationTime")

 'PR_ATTR_HIDDEN referenced by the MAPI proptag namespace

 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")

 End With

 'Enumerate the table using test for EndOfTable

 Do Until (oTable.EndOfTable)

 Set oRow = oTable.GetNextRow()

 Debug.Print (oRow("Subject"))

 Debug.Print (oRow("LastModificationTime"))

 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))

 Loop

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Row Object Members


Row Members (Outlook)

 Copy code hover
[image]

Row Members (Outlook)
Send feedback

Represents a row of data in the Table object.

Methods

Name | Description
BinaryToString | Obtains a String representing a value that has been converted from a binary value for the parent Row at the column specified by Index.
GetValues | Obtains a one-dimensional array containing the values for all columns at the Row in the parent Table.
Item | Obtains an Object that represents the value for the Row object at the column specified by Index.
LocalTimeToUTC | Obtains a Date value in a Table specified by the Row object at Index, that has been converted from local time to Coordinated Universal Time (UTC).
UTCToLocalTime | Obtains a Date value in a Table specified by the Row object at Index, that has been converted from Coordinated Universal Time (UTC) to local time.

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Row object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Row object. Read-only.
Parent | Returns the parent object of the Row object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Row Properties (Outlook)

 Copy code hover
[image]

Row Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Row object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Row object. Read-only.
Parent | Returns the parent object of the Row object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Row.Application Property (Outlook)

 Copy code hover
[image]

Row.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent application (Outlook) for the Row object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Row object.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.Class Property (Outlook)

 Copy code hover
[image]

Row.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlObjectClass enumeration indicating the class of the Row object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Row object.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.Parent Property (Outlook)

 Copy code hover
[image]

Row.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent object of the Row object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Row object.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.Session Property (Outlook)

 Copy code hover
[image]

Row.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Row object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Row Object

Other resources

Row Object Members


Row Methods (Outlook)

 Copy code hover
[image]

Row Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
BinaryToString | Obtains a String representing a value that has been converted from a binary value for the parent Row at the column specified by Index.
GetValues | Obtains a one-dimensional array containing the values for all columns at the Row in the parent Table.
Item | Obtains an Object that represents the value for the Row object at the column specified by Index.
LocalTimeToUTC | Obtains a Date value in a Table specified by the Row object at Index, that has been converted from local time to Coordinated Universal Time (UTC).
UTCToLocalTime | Obtains a Date value in a Table specified by the Row object at Index, that has been converted from Coordinated Universal Time (UTC) to local time.


Row.BinaryToString Method (Outlook)

 Copy code hover
[image]

Row.BinaryToString Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a String representing a value that has been converted from a binary value for the parent Row at the column specified by Index.

Version Information

Version Added: Outlook 2007

Syntax

expression .BinaryToString(Index)

expression A variable that represents a Row object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Return Value

A hexadecimal String value that has been converted from a PT_BINARY value for the parent Row at the column specified by Index. Returns the error, "Cannot convert the column specified by Index to String" if the value specified by Index is not PT_BINARY.

Remarks

Use the helper functions Row.BinaryToString, Row.LocalTimeToUTC, and Row.UTCToLocalTime to facilitate type conversion of column values at a specific row. For more information on property value representation in a Table, see Factors Affecting Property Value Representation in the Table and View Classes.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.GetValues Method (Outlook)

 Copy code hover
[image]

Row.GetValues Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a one-dimensional array containing the values for all columns at the Row in the parent Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetValues

expression A variable that represents a Row object.

Return Value

A Variant that represents an array of values for all the columns at that Row in the Table.

Remarks

GetValues is a helper method that facilitates fetching all the column values in the Row in a single call.

Since the array is zero-based, the length of the array is the number of columns in the Row minus one.

Values returned in the array are of the same type as the values in the parent Table. This means that binary properties in the Table are returned as arrays of bytes. For date-time properties, if a Column is a default column or if it has been added using an explicit built-in property name, then its value in the Table and in the array are expressed in local time. If the Column has been added to the Table using a namespace reference, then its value in the Table and in the array are expressed in Coordinated Universal Time (UTC). For more information on referencing properties by namespace, see Referencing Properties by Namespace.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.Item Method (Outlook)

 Copy code hover
[image]

Row.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains an Object that represents the value for the Row object at the column specified by Index.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a Row object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Return Value

A Variant that represents the value of a property (as specified by Index) of an item (as specified by the parent Row).

Remarks

The Item method is the default method of the Row object, meaning that the method can be used implicitly. The following two lines of code both access the value of the Subject property at the specified Row in a Table:

Row.Item("Subject")

Row("Subject")

If a Column has been added to a Table using a property name referencing a namespace, you must reference the Column in the Row.Item method by the same namespace reference. If you use an explicit built-in name reference in Row.Item, you will get an error.

Example

The following code sample illustrates how to obtain a Table object based on the LastModificationTime of items in the Inbox. It then enumerates and prints the values of a couple of default properties of these items. Since the Item method is the default method of the Row object, it uses the Item method in an implicit way.

Copy code Copy code
Sub DemoTable()
 'Declarations
 Dim Filter As String
 Dim oRow As Outlook.Row
 Dim oTable As Outlook.Table
 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005
 Filter = "[LastModificationTime] > '5/1/2005'"
 'Restrict with Filter
 Set oTable = oFolder.GetTable(Filter)

 'Enumerate the table using test for EndOfTable
 Do Until (oTable.EndOfTable)
 Set oRow = oTable.GetNextRow()
 Debug.Print (oRow("Subject"))
 Debug.Print (oRow("LastModificationTime"))
 Loop
End Sub

See also

Concepts

Row Object

Other resources

Row Object Members


Row.LocalTimeToUTC Method (Outlook)

 Copy code hover
[image]

Row.LocalTimeToUTC Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Date value in a Table specified by the Row object at Index, that has been converted from local time to Coordinated Universal Time (UTC).

Version Information

Version Added: Outlook 2007

Syntax

expression .LocalTimeToUTC(Index)

expression A variable that represents a Row object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Return Value

A Date value that has been converted from a representation in local time to UTC. An error is returned if Index is invalid or the row value indicated by Index is not a Date value.

Remarks

Use the helper functions Row.BinaryToString, Row.LocalTimeToUTC, and Row.UTCToLocalTime to facilitate type conversion of column values at a specific row.

For information on property value representation in a Table, see Factors Affecting Property Value Representation in the Table and View Classes. For information on using Date-time comparisons in Table filters, see Filtering Items Using a Date-time Comparison.

See also

Concepts

Row Object

Other resources

Row Object Members


Row.UTCToLocalTime Method (Outlook)

 Copy code hover
[image]

Row.UTCToLocalTime Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Date value in a Table specified by the Row object at Index, that has been converted from Coordinated Universal Time (UTC) to local time.

Version Information

Version Added: Outlook 2007

Syntax

expression .UTCToLocalTime(Index)

expression A variable that represents a Row object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | A 1-based index value that can be either a Long representing the column index for the Columns collection or a String representing the Name of the Column.

Return Value

A Date value that has been converted from a representation in UTC to local time. An error is returned if Index is invalid or the row value indicated by Index is not a Date value.

Remarks

Use the helper functions Row.BinaryToString, Row.LocalTimeToUTC, and Row.UTCToLocalTime to facilitate type conversion of column values at a specific row.

For information on property value representation in a Table, see Factors Affecting Property Value Representation in the Table and View Classes. For information on using Date-time comparisons in Table filters, see Filtering Items Using a Date-time Comparison.

See also

Concepts

Row Object

Other resources

Row Object Members


Rule Object (Outlook)

 Copy code hover
[image]

Rule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an Outlook rule.

Version Information

Version Added: Outlook 2007

Remarks

Both client and server side rules are represented by the Rule object.

The Rules object model consists primarily of these objects: Rules, Rule, RuleActions, RuleConditions, RuleAction, RuleCondition, and the derived objects for certain rule actions and rule conditions. It provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. Although it does not support creation of every single rule that you can possibly create using the Wizard, it supports the most commonly used rule actions and conditions.

For more information on how to programmatically create, edit, and delete rules, see Manage Rules in the Outlook Object Model and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

Rule Object Members


Rule Members (Outlook)

 Copy code hover
[image]

Rule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an Outlook rule.

Methods

Name | Description
Execute | Applies a rule as an one-off operation.

Properties

Name | Description
Actions | Returns a RuleActions collection object that represents all the available rule actions for the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Conditions | Returns a RuleConditions collection object that represents all the available rule conditions for the rule. Read-only.
Enabled | Returns or sets a Boolean value that determines if the rule is to be applied. Read/write.
Exceptions | Returns a RuleConditions collection object that represents all the available rule exception conditions for the rule. Read-only.
ExecutionOrder | Returns or sets a Long that indicates the order of execution of the rule among other rules in the Rules collection. Read/write.
IsLocalRule | Returns a Boolean that indicates if the rule executes as a client-side rule. Read-only.
Name | Returns or sets a String representing the name of the rule. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RuleType | Returns a constant from the OlRuleType enumeration that indicates if the rule applies to messages that are being sent or received. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Rule Properties (Outlook)

 Copy code hover
[image]

Rule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns a RuleActions collection object that represents all the available rule actions for the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Conditions | Returns a RuleConditions collection object that represents all the available rule conditions for the rule. Read-only.
Enabled | Returns or sets a Boolean value that determines if the rule is to be applied. Read/write.
Exceptions | Returns a RuleConditions collection object that represents all the available rule exception conditions for the rule. Read-only.
ExecutionOrder | Returns or sets a Long that indicates the order of execution of the rule among other rules in the Rules collection. Read/write.
IsLocalRule | Returns a Boolean that indicates if the rule executes as a client-side rule. Read-only.
Name | Returns or sets a String representing the name of the rule. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RuleType | Returns a constant from the OlRuleType enumeration that indicates if the rule applies to messages that are being sent or received. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Rule.Actions Property (Outlook)

 Copy code hover
[image]

Rule.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleActions collection object that represents all the available rule actions for the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Actions

expression A variable that represents a Rule object.

Remarks

You can enumerate and enable rules with any rule action that the Rules and Alerts Wizard support, but you can programmatically create rules that have only the most commonly used rule actions, and not any rule action that the Rules and Alerts Wizard supports. For more information on rule action support, see Specify Rule Actions.

Through the Actions property, each rule is associated with a RuleActions object. The RuleActions collection is a fixed object - you cannot add or remove items from this collection. Rule actions that are enabled in the rule will have an enabled rule action in the RuleActions collection. Rule actions that are not enabled in the rule will have a rule action in this collection that has the RuleAction.Enabled property set to False. Rule actions that are not supported during programmatic rule creation can only be enumerated in the RuleActions collection for an existing rule, but because the RuleActions collection is fixed, you cannot create a rule and add such an action to the associated RuleActions collection.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Application Property (Outlook)

 Copy code hover
[image]

Rule.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Rule object.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Class Property (Outlook)

 Copy code hover
[image]

Rule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Rule object.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Conditions Property (Outlook)

 Copy code hover
[image]

Rule.Conditions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleConditions collection object that represents all the available rule conditions for the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Conditions

expression A variable that represents a Rule object.

Remarks

A condition for a rule states the condition under which the rule should be applied. Both the Conditions and Exceptions properties share the same pool of conditions and return a corresponding RuleConditions collection object.

Programmatically you can enumerate and enable rules with any rule condition that the Rules and Alerts Wizard support, but you can create rules that have only the most commonly used rule conditions, and not any rule condition that the Rules and Alerts Wizard supports. For more information on rule condition support, see Specify Rule Conditions.

Through the Conditions property, each rule is associated with a RuleConditions object. The RuleConditions collection is a fixed object - you cannot add or remove items from this collection. Rule conditions that are enabled in the rule will have an enabled rule condition in the RuleConditions collection. Rule conditions that are not enabled in the rule will have a rule condition in this collection that has the RuleCondition.Enabled property set to False. Rule conditions that are not supported during programmatic rule creation can only be enumerated in the RuleConditions collection for an existing rule, but because the RuleConditions collection is fixed, you cannot create a rule and add such a condition to the associated RuleConditions collection.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Enabled Property (Outlook)

 Copy code hover
[image]

Rule.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines if the rule is to be applied. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a Rule object.

Remarks

Setting the Enabled property of a rule does not guarantee that the rule will be enabled. The rule is enabled only after Rules.Save executes successfully.

Using Rule.Enabled and Rules.Save applies the rule consistently and persists the rules beyond the current session. Enabling a rule (that has been saved successfully) ensures that the rule will be applied. If it is a local client rule, the rule will be applied when Outlook is running, and if the rule is a server-based rule, it will be applied regardless of whether Outlook is running. If you do not enable the rule, then the rule is defined, but it will not be applied. However, you can use Rule.Execute to apply a rule as an one-off operation regardless of whether the rule is enabled.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Exceptions Property (Outlook)

 Copy code hover
[image]

Rule.Exceptions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleConditions collection object that represents all the available rule exception conditions for the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Exceptions

expression A variable that represents a Rule object.

Remarks

An exception condition for a rule states the condition under which the rule should not be applied. Both the Conditions and Exceptions properties share the same pool of conditions and return a corresponding RuleConditions collection object.

You can enumerate and enable rules with any rule exception condition that the Rules and Alerts Wizard support, but you can programmatically create rules that have only the most commonly used rule exception conditions, and not any rule exception condition that the Rules and Alerts Wizard supports. For more information on rule condition support, see Specify Rule Conditions.

Through the Conditions property, each rule is associated with a RuleConditions object. The RuleConditions collection is a fixed object - you cannot add or remove items from this collection. Rule exception conditions that are enabled in the rule will have an enabled rule exception condition in the RuleConditions collection. Rule exception conditions that are not enabled in the rule will have a rule exception condition in this collection that has the RuleCondition.Enabled property set to False. Rule exception conditions that are not supported during programmatic rule creation can only be enumerated in the RuleConditions collection for an existing rule, but because the RuleConditions collection is fixed, you cannot create a rule and add such an exception condition to the associated RuleConditions collection.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.ExecutionOrder Property (Outlook)

 Copy code hover
[image]

Rule.ExecutionOrder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that indicates the order of execution of the rule among other rules in the Rules collection. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ExecutionOrder

expression A variable that represents a Rule object.

Remarks

ExecutionOrder is directly mapped with the numerical value of Index in the Item method. For example, Rules.Item(1) represents a rule with ExecutionOrder being 1, Rules.Item(2) represents a rule with ExecutionOrder being 2, and Rules.Item(Rules.Count) represents the rule with ExecutionOrder being Count property.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.IsLocalRule Property (Outlook)

 Copy code hover
[image]

Rule.IsLocalRule Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the rule executes as a client-side rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsLocalRule

expression A variable that represents a Rule object.

Remarks

A client-side rule executes only when Outlook is running. If IsLocalRule is False, then the rule executes as a server-side rule.

If you have a Microsoft Exchange Server e-mail account, the server can apply server-side rules to your messages even if you don't have Outlook running. The rules must be set to be applied to messages when they are delivered to your Inbox on the server, and the rules must be able to run to completion on the server. For example, a rule cannot run to completion on the server if the action specifies that a message be printed. If a rule cannot be applied on the server, it is applied when you start Outlook.

If the rules collection on a store contains both server and client-side rules, the server-side rules are applied first, followed by the client-side rules.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Name Property (Outlook)

 Copy code hover
[image]

Rule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the name of the rule. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a Rule object.

Remarks

Name is the default property and an indexer for a rule in a Rules collection object. It corresponds to PidTagRuleMsgName (0x65EC001E).

Rule names are not unique among rules in the same collection.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Parent Property (Outlook)

 Copy code hover
[image]

Rule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Rule object.

Remarks

The parent of the Rule object is the Rules object.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.RuleType Property (Outlook)

 Copy code hover
[image]

Rule.RuleType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlRuleType enumeration that indicates if the rule applies to messages that are being sent or received. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RuleType

expression A variable that represents a Rule object.

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule.Session Property (Outlook)

 Copy code hover
[image]

Rule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Rule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Rule Object

Other resources

Rule Object Members


Rule Methods (Outlook)

 Copy code hover
[image]

Rule Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Execute | Applies a rule as an one-off operation.


Rule.Execute Method (Outlook)

 Copy code hover
[image]

Rule.Execute Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies a rule as an one-off operation.

Version Information

Version Added: Outlook 2007

Syntax

expression .Execute(ShowProgress, Folder, IncludeSubfolders, RuleExecuteOption)

expression A variable that represents a Rule object.

Parameters

Name | Required/Optional | Data Type | Description
ShowProgress | Optional | Boolean | True to display the progress dialog box when the rule is executed, False to run the rule without displaying the dialog box.
Folder | Optional | Folder | Represents the folder where the rule will be applied.
IncludeSubfolders | Optional | Boolean | True to apply the rule to subfolders of the folder indicated by the Folder parameter; False to apply the rule only to that folder but not its subfolders.
RuleExecuteOption | Optional | OlRuleExecuteOption | Represents whether to apply the rule to read, unread, or all messages in the folder or folders specified by the Folder and IncludeSubfolders parameters.

Remarks

Use Rule.Execute to apply a rule as a one-off operation regardless of whether Rule.Enabled is True. Use Rule.Enabled and then Rules.Save if you want to apply the rule consistently and persist the rules beyond the current session.

The parameters to the Execute method are optional. If you do not specify any parameters, the rule will be applied to all messages in the Inbox but not to the subfolders of the Inbox. The default values for the optional arguments are as follows:

Parameter | Default Value
ShowProgress | False
Folder | Inbox
IncludeSubfolders | False
RuleExecuteOption | OlRuleExecuteOption.olRuleExecuteAllMessages

If ShowProgress is True and the user cancels the progress dialog box, rule execution is canceled in the same manner as if the user had canceled rule execution through the Rules and Alerts Wizard. Execute returns an error when the user cancels the progress dialog.

If you plan to show a custom progress user interface instead of using the progress dialog box, you should be aware that there are no events that indicate when rule execution starts and stops.

See also

Concepts

Rule Object

Other resources

Rule Object Members


RuleAction Object (Outlook)

 Copy code hover
[image]

RuleAction Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an action that is run when a Rule object executes.

Version Information

Version Added: Outlook 2007

Remarks

RuleAction is the base class for rule actions that are supported in programmatic rule creation. The classes derived from RuleAction include:

  • AssignToCategoryRuleAction

  • MarkAsTaskRuleAction

  • MoveOrCopyRuleAction

  • NewItemAlertRuleAction

  • PlaySoundRuleAction

  • SendRuleAction

The Rules object model provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. It supports the most commonly used rule actions and conditions. Although it does not support creating rules with each rule action or rule condition that the Wizard supports, you can still enumerate and enable these rule actions and conditions in existing rules.

For more information on rule actions, see Specifying Rule Actions and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

RuleAction Object Members


RuleAction Members (Outlook)

 Copy code hover
[image]

RuleAction Members (Outlook)
Send feedback

Published: July 16, 2012

Represents an action that is run when a Rule object executes.

Properties

Name | Description
ActionType | Returns a constant from the OlRuleActionType enumeration that indicates the type of action that is taken by the RuleAction. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the RuleAction is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


RuleAction Properties (Outlook)

 Copy code hover
[image]

RuleAction Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant from the OlRuleActionType enumeration that indicates the type of action that is taken by the RuleAction. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the RuleAction is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


RuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

RuleAction.ActionType Property (Outlook)
See also Send feedback

Returns a constant from the OlRuleActionType enumeration that indicates the type of action that is taken by the RuleAction. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a RuleAction object.

Remarks

For more information on the rule actions supported for programmatic rule creation, those supported for rules for receiving message, and those supported for rules for sending messages, see Specify Rule Actions.

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleAction.Application Property (Outlook)

 Copy code hover
[image]

RuleAction.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a RuleAction object.

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleAction.Class Property (Outlook)

 Copy code hover
[image]

RuleAction.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a RuleAction object.

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

RuleAction.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the RuleAction is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a RuleAction object.

Remarks

After you enable a rule action, you must also save the rule by using Rules.Save so that the rule action and its enabled state will persist beyond the current session. A rule action is only enabled after it has been saved successfully.

Returns an error if you attempt to enable a rule action that is supported only on a rule of type olRuleSend for a rule of type olRuleReceive, or vice versa.

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleAction.Parent Property (Outlook)

 Copy code hover
[image]

RuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a RuleAction object.

Remarks

The parent of the RuleAction object is the RuleActions object.

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleAction.Session Property (Outlook)

 Copy code hover
[image]

RuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a RuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RuleAction Object

Other resources

RuleAction Object Members


RuleActions Object (Outlook)

 Copy code hover
[image]

RuleActions Object (Outlook)
See also Send feedback

Published: July 16, 2012

The RuleActions object contains a set of RuleAction objects or objects derived from RuleAction, representing the actions that are executed on a Rule object.

Version Information

Version Added: Outlook 2007

Remarks

The RuleActions object is a fixed collection. RuleAction objects or types that derive from the RuleAction object cannot be added to or removed from the RuleActions object.

The Rules object model provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. It supports the most commonly used rule actions and conditions. Although it does not support creating rules with any rule action or rule condition that the Wizard supports, you can still enumerate and enable these rule actions and conditions in existing rules.

For more information on rule actions, see Specifying Rule Actions and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

RuleActions Object Members


RuleActions Members (Outlook)

 Copy code hover
[image]

RuleActions Members (Outlook)
Send feedback

Published: July 16, 2012

The RuleActions object contains a set of RuleAction objects or objects derived from RuleAction, representing the actions that are executed on a Rule object.

Methods

Name | Description
Item | Obtains a RuleAction object specified by Index which is a numerical index into the RuleActions collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AssignToCategory | Returns an AssignToCategoryRuleAction object with AssignToCategoryRuleAction.ActionType being olRuleAssignToCategory. Read-only.
CC | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionCcMessage. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ClearCategories | Returns a RuleAction object with a RuleAction.ActionType of olRuleActionClearCategories. Read-only.
CopyToFolder | Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionCopyToFolder. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Delete | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDelete. Read-only.
DeletePermanently | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDeletePermanently. Read-only.
DesktopAlert | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDesktopAlert. Read-only.
Forward | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForward. Read-only.
ForwardAsAttachment | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForwardAsAttachment. Read-only.
MarkAsTask | Returns a MarkAsTaskRuleAction object with MarkAsTaskRuleAction.ActionType being olRuleActionMarkAsTask. Read-only.
MoveToFolder | Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionMoveToFolder. Read-only.
NewItemAlert | Returns a NewItemAlertRuleAction object with ActionType being olRuleActionNewItemAlert. Read-only.
NotifyDelivery | Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyDelivery. Read-only.
NotifyRead | Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyRead. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PlaySound | Returns a PlaySoundRuleAction object with PlaySoundRuleAction.ActionType being olRuleActionNotifyRead. Read-only.
Redirect | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionRedirect. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Stop | Returns a RuleAction object with RuleAction.ActionType being olRuleActionStop. Read-only.


RuleActions Properties (Outlook)

 Copy code hover
[image]

RuleActions Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AssignToCategory | Returns an AssignToCategoryRuleAction object with AssignToCategoryRuleAction.ActionType being olRuleAssignToCategory. Read-only.
CC | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionCcMessage. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ClearCategories | Returns a RuleAction object with a RuleAction.ActionType of olRuleActionClearCategories. Read-only.
CopyToFolder | Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionCopyToFolder. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Delete | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDelete. Read-only.
DeletePermanently | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDeletePermanently. Read-only.
DesktopAlert | Returns a RuleAction object with RuleAction.ActionType being olRuleActionDesktopAlert. Read-only.
Forward | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForward. Read-only.
ForwardAsAttachment | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForwardAsAttachment. Read-only.
MarkAsTask | Returns a MarkAsTaskRuleAction object with MarkAsTaskRuleAction.ActionType being olRuleActionMarkAsTask. Read-only.
MoveToFolder | Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionMoveToFolder. Read-only.
NewItemAlert | Returns a NewItemAlertRuleAction object with ActionType being olRuleActionNewItemAlert. Read-only.
NotifyDelivery | Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyDelivery. Read-only.
NotifyRead | Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyRead. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PlaySound | Returns a PlaySoundRuleAction object with PlaySoundRuleAction.ActionType being olRuleActionNotifyRead. Read-only.
Redirect | Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionRedirect. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Stop | Returns a RuleAction object with RuleAction.ActionType being olRuleActionStop. Read-only.


RuleActions.Application Property (Outlook)

 Copy code hover
[image]

RuleActions.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a RuleActions object.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.AssignToCategory Property (Outlook)

 Copy code hover
[image]

RuleActions.AssignToCategory Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AssignToCategoryRuleAction object with AssignToCategoryRuleAction.ActionType being olRuleAssignToCategory. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AssignToCategory

expression A variable that represents a RuleActions object.

Remarks

Use the returned AssignToCategoryRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that assigns categories to a message.

This property of the RuleActions collection always returns an AssignToCategoryRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then AssignToCategoryRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.CC Property (Outlook)

 Copy code hover
[image]

RuleActions.CC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionCcMessage. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CC

expression A variable that represents a RuleActions object.

Remarks

Use the returned SendRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies cc-ing a message to specific recipients as an action.

This property of the RuleActions collection always returns a SendRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then SendRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Class Property (Outlook)

 Copy code hover
[image]

RuleActions.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a RuleActions object.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.ClearCategories Property (Outlook)

 Copy code hover
[image]

RuleActions.ClearCategories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleAction object with a RuleAction.ActionType of olRuleActionClearCategories. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearCategories

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a rule that specifies removing all the categories of a message as an action.

This property of the RuleActions collection always returns a RuleAction object, regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.CopyToFolder Property (Outlook)

 Copy code hover
[image]

RuleActions.CopyToFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionCopyToFolder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CopyToFolder

expression A variable that represents a RuleActions object.

Remarks

Use the returned MoveOrCopyRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies copying a message to a specific folder as an action.

This property of the RuleActions collection always returns a MoveOrCopyRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then MoveOrCopyRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Count Property (Outlook)

 Copy code hover
[image]

RuleActions.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a RuleActions object.

Remarks

You can enumerate the RuleActions collection from 1 through RuleActions.Count to determine all the rule actions for an existing rule. Although the Rules OM supports creating rules with only the most commonly used rule actions and not all rule actions supported by the Rules and Alerts Wizard, the RuleActions collection includes all rule actions of a rule. Hence you can always enumerate the RuleActions collection object to determine which rule actions are enabled for an existing rule.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Delete Property (Outlook)

 Copy code hover
[image]

RuleActions.Delete Property (Outlook)
See also Send feedback

Returns a RuleAction object with RuleAction.ActionType being olRuleActionDelete. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies deleting a message as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.DeletePermanently Property (Outlook)

 Copy code hover
[image]

RuleActions.DeletePermanently Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleAction object with RuleAction.ActionType being olRuleActionDeletePermanently. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DeletePermanently

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies deleting a message permanently as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.DesktopAlert Property (Outlook)

 Copy code hover
[image]

RuleActions.DesktopAlert Property (Outlook)
See also Send feedback

Returns a RuleAction object with RuleAction.ActionType being olRuleActionDesktopAlert. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DesktopAlert

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies displaying a desktop alert as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Forward Property (Outlook)

 Copy code hover
[image]

RuleActions.Forward Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForward. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Forward

expression A variable that represents a RuleActions object.

Remarks

Use the returned SendRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies forwarding a message to specific recipients as an action.

This property of the RuleActions collection always returns a SendRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then SendRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.ForwardAsAttachment Property (Outlook)

 Copy code hover
[image]

RuleActions.ForwardAsAttachment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionForwardAsAttachment. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForwardAsAttachment

expression A variable that represents a RuleActions object.

Remarks

Use the returned SendRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies forwarding a message as an attachment to specific recipients as an action.

This property of the RuleActions collection always returns a SendRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then SendRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.MarkAsTask Property (Outlook)

 Copy code hover
[image]

RuleActions.MarkAsTask Property (Outlook)
See also Send feedback

Returns a MarkAsTaskRuleAction object with MarkAsTaskRuleAction.ActionType being olRuleActionMarkAsTask. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask

expression A variable that represents a RuleActions object.

Remarks

Use the returned MarkAsTaskRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies the action of marking a message as a task.

This property of the RuleActions collection always returns a MarkAsTaskRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then MarkAsTaskRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.MoveToFolder Property (Outlook)

 Copy code hover
[image]

RuleActions.MoveToFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a MoveOrCopyRuleAction object with MoveOrCopyRuleAction.ActionType being olRuleActionMoveToFolder. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .MoveToFolder

expression A variable that represents a RuleActions object.

Remarks

Use the returned MoveOrCopyRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies copying a message to a specific folder as an action.

This property of the RuleActions collection always returns a MoveOrCopyRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then MoveOrCopyRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.NewItemAlert Property (Outlook)

 Copy code hover
[image]

RuleActions.NewItemAlert Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NewItemAlertRuleAction object with ActionType being olRuleActionNewItemAlert. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NewItemAlert

expression A variable that represents a RuleActions object.

Remarks

Use the returned NewItemAlertRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies displaying an alert for a new item as an action.

This property of the RuleActions collection always returns a NewItemAlertRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then NewItemAlertRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.NotifyDelivery Property (Outlook)

 Copy code hover
[image]

RuleActions.NotifyDelivery Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyDelivery. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NotifyDelivery

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies notifying delivery of a message as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.NotifyRead Property (Outlook)

 Copy code hover
[image]

RuleActions.NotifyRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleAction object with RuleAction.ActionType being olRuleActionNotifyRead. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NotifyRead

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies sending a notification about the opening of a message as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Parent Property (Outlook)

 Copy code hover
[image]

RuleActions.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a RuleActions object.

Remarks

The parent of the RuleActions object is the Rule object.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.PlaySound Property (Outlook)

 Copy code hover
[image]

RuleActions.PlaySound Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PlaySoundRuleAction object with PlaySoundRuleAction.ActionType being olRuleActionNotifyRead. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PlaySound

expression A variable that represents a RuleActions object.

Remarks

Use the returned PlaySoundRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies playing a sound file as an action.

This property of the RuleActions collection always returns a PlaySoundRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then PlaySoundRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Redirect Property (Outlook)

 Copy code hover
[image]

RuleActions.Redirect Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SendRuleAction object with SendRuleAction.ActionType being olRuleActionRedirect. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Redirect

expression A variable that represents a RuleActions object.

Remarks

Use the returned SendRuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies redirecting a message to specific recipients as an action.

This property of the RuleActions collection always returns a SendRuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then SendRuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Session Property (Outlook)

 Copy code hover
[image]

RuleActions.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a RuleActions object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions.Stop Property (Outlook)

 Copy code hover
[image]

RuleActions.Stop Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleAction object with RuleAction.ActionType being olRuleActionStop. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Stop

expression A variable that represents a RuleActions object.

Remarks

Use the returned RuleAction object when enumerating the rule actions of an existing rule or when creating a new rule that specifies stopping the processing of more rules as an action.

This property of the RuleActions collection always returns a RuleAction object regardless of whether the rule associated with this RuleActions collection has defined such a rule action. If the rule has defined and enabled such a rule action, then RuleAction.Enabled will be True.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleActions Methods (Outlook)

 Copy code hover
[image]

RuleActions Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Obtains a RuleAction object specified by Index which is a numerical index into the RuleActions collection.


RuleActions.Item Method (Outlook)

 Copy code hover
[image]

RuleActions.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a RuleAction object specified by Index which is a numerical index into the RuleActions collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a RuleActions object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A 1-based numerical value that reflects the ordinal position of a rule action within the RuleActions collection. For example, the index value of the first rule action in the collection is 1, and the index value of the second rule action is 2.

Return Value

A RuleAction object that matches the rule action specified by Index.

Remarks

The RuleActions collection object is a fixed collection. It contains RuleAction objects or objects derived from RuleAction. You cannot add or remove items from this collection, but you can use Item to enumerate the rule action items, and set the Enabled property of the rule action. When using Item to enumerate the collection, you can enumerate Index from 1 to Count.

See also

Concepts

RuleActions Object

Other resources

RuleActions Object Members


RuleCondition Object (Outlook)

 Copy code hover
[image]

RuleCondition Object (Outlook)
See also Send feedback

The RuleCondition object represents either a condition that must be met before a rule executes, or an exception condition that must not be met before a rule executes.

Version Information

Version Added: Outlook 2007

Remarks

RuleCondition is the base class for rule conditions that are supported in programmatic rule creation. The classes derived from RuleCondition include:

  • AccountRuleCondition

  • AddressRuleCondition

  • CategoryRuleCondition

  • FromRssFeedRuleCondition

  • FormNameRuleCondition

  • ImportanceRuleCondition

  • SenderInAddressListRuleCondition

  • TextRuleCondition

  • ToOrFromRuleCondition

The Rules object model provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. It supports the most commonly used rule actions and conditions. Although it does not support creating rules with each rule action or rule condition that the Wizard supports, you can still enumerate and enable these rule actions and conditions in existing rules.

For more information on rule conditions, see Specifying Rule Conditions and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

RuleCondition Object Members


RuleCondition Members (Outlook)

 Copy code hover
[image]

RuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

The RuleCondition object represents either a condition that must be met before a rule executes, or an exception condition that must not be met before a rule executes.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant in the OlRuleConditionType enumeration that indicates the type of condition for the RuleCondition object. Read-only.
Enabled | Returns or sets a Boolean that determines if the RuleCondition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


RuleCondition Properties (Outlook)

 Copy code hover
[image]

RuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant in the OlRuleConditionType enumeration that indicates the type of condition for the RuleCondition object. Read-only.
Enabled | Returns or sets a Boolean that determines if the RuleCondition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


RuleCondition.Application Property (Outlook)

 Copy code hover
[image]

RuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a RuleCondition object.

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleCondition.Class Property (Outlook)

 Copy code hover
[image]

RuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a RuleCondition object.

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

RuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlRuleConditionType enumeration that indicates the type of condition for the RuleCondition object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a RuleCondition object.

Remarks

For more information on the rule conditions supported for programmatic rule creation, those supported for rules for receiving message, and those supported for rules for sending messages, see Specify Rule Conditions.

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

RuleCondition.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if the RuleCondition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a RuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it has been saved successfully.

Returns an error if you attempt to enable a rule condition that is supported only on a rule of type olRuleSend for a rule of type olRuleReceive, or vice versa. For more information on suppport by rules for receiving messages or rules for sending messages, see Specify Rule Conditions.

You cannot enable or disable a condition of type olConditionOtherMachine. This type of rule condition indicates that the rule can run only on a specific computer that is not the current one. This happens when the rule is created on that computer and the rule condition olConditionLocalMachineOnly is enabled, indicating that the rule can run only on that computer. When you run the same rule on another computer, the rule will show that the condition olConditionOtherMachine is enabled.

Returns an error if you attempt to enable an exception condition of type olConditionLocalMachineOnly.

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

RuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a RuleCondition object.

Remarks

The parent of the RuleCondition object is the Rule object.

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleCondition.Session Property (Outlook)

 Copy code hover
[image]

RuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a RuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RuleCondition Object

Other resources

RuleCondition Object Members


RuleConditions Object (Outlook)

 Copy code hover
[image]

RuleConditions Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of RuleCondition objects or objects derived from RuleCondition, representing the conditions or exception conditions that must be satisfied in order for the Rule to execute.

Version Information

Version Added: Outlook 2007

Remarks

The RuleConditions object include both rule conditions and rule exceptions. The type of rule condition that can be added to a RuleConditions collection depends upon the Rule.RuleType.

The RuleConditions object is a fixed collection. A RuleCondition object or a type that is derived from the RuleCondition object cannot be added or removed from the RuleConditions object.

The Rules object model provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. It supports the most commonly used rule actions and conditions. Although it does not support creating rules with any rule action or rule condition that the Wizard supports, you can still enumerate and enable these rule actions and conditions in existing rules.

For more information on rule conditions, see Specifying Rule Conditions and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

RuleConditions Object Members


RuleConditions Members (Outlook)

 Copy code hover
[image]

RuleConditions Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of RuleCondition objects or objects derived from RuleCondition, representing the conditions or exception conditions that must be satisfied in order for the Rule to execute.

Methods

Name | Description
Item | Obtains a RuleCondition object specified by Index which is a numerical index into the RuleConditions collection.

Properties

Name | Description
Account | Returns a AccountRuleCondition object with an AccountRuleCondition.ConditionType of olConditionAccount. Read-only.
AnyCategory | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionAnyCategory. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Body | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBody. Read-only.
BodyOrSubject | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBodyOrSubject. Read-only.
Category | Returns a CategoryRuleCondition object with a CategoryRuleCondition.ConditionType of olConditionCategory. Read-only.
CC | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionCc. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
FormName | Returns a FormNameRuleCondition object with a FormNameRuleCondition.ConditionType of olConditionFormName. Read-only.
From | Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionFrom. Read-only.
FromAnyRSSFeed | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionFromAnyRssFeed. Read-only.
FromRssFeed | Returns a FromRssFeedRuleCondition object with a FromRssFeedRuleCondition.ConditionType of olConditionFromRssFeed. Read-only.
HasAttachment | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionHasAttachment. Read-only.
Importance | Returns an ImportanceRuleCondition object with an ImportanceRuleCondition.ConditionType of olConditionImportance. Read-only.
MeetingInviteOrUpdate | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionMeetingInviteOrUpdate. Read-only.
MessageHeader | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionMessageHeader. Read-only.
NotTo | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionNotTo. Read-only.
OnLocalMachine | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionLocalMachineOnly. Read-only.
OnlyToMe | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOnlyToMe. Read-only.
OnOtherMachine | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOtherMachine. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
RecipientAddress | Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionRecipientAddress. Read-only.
SenderAddress | Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionSenderAddress. Read-only.
SenderInAddressList | Returns a SenderInAddressListRuleCondition object with a SenderInAddressListRuleCondition.ConditionType of olConditionAccount. Read-only.
SentTo | Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionSentTo. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Subject | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionSubject. Read-only.
ToMe | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionTo. Read-only.
ToOrCc | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionToOrCc. Read-only.


RuleConditions Properties (Outlook)

 Copy code hover
[image]

RuleConditions Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Account | Returns a AccountRuleCondition object with an AccountRuleCondition.ConditionType of olConditionAccount. Read-only.
AnyCategory | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionAnyCategory. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Body | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBody. Read-only.
BodyOrSubject | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBodyOrSubject. Read-only.
Category | Returns a CategoryRuleCondition object with a CategoryRuleCondition.ConditionType of olConditionCategory. Read-only.
CC | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionCc. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
FormName | Returns a FormNameRuleCondition object with a FormNameRuleCondition.ConditionType of olConditionFormName. Read-only.
From | Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionFrom. Read-only.
FromAnyRSSFeed | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionFromAnyRssFeed. Read-only.
FromRssFeed | Returns a FromRssFeedRuleCondition object with a FromRssFeedRuleCondition.ConditionType of olConditionFromRssFeed. Read-only.
HasAttachment | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionHasAttachment. Read-only.
Importance | Returns an ImportanceRuleCondition object with an ImportanceRuleCondition.ConditionType of olConditionImportance. Read-only.
MeetingInviteOrUpdate | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionMeetingInviteOrUpdate. Read-only.
MessageHeader | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionMessageHeader. Read-only.
NotTo | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionNotTo. Read-only.
OnLocalMachine | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionLocalMachineOnly. Read-only.
OnlyToMe | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOnlyToMe. Read-only.
OnOtherMachine | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOtherMachine. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
RecipientAddress | Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionRecipientAddress. Read-only.
SenderAddress | Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionSenderAddress. Read-only.
SenderInAddressList | Returns a SenderInAddressListRuleCondition object with a SenderInAddressListRuleCondition.ConditionType of olConditionAccount. Read-only.
SentTo | Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionSentTo. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Subject | Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionSubject. Read-only.
ToMe | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionTo. Read-only.
ToOrCc | Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionToOrCc. Read-only.


RuleConditions.Account Property (Outlook)

 Copy code hover
[image]

RuleConditions.Account Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a AccountRuleCondition object with an AccountRuleCondition.ConditionType of olConditionAccount. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Account

expression A variable that represents a RuleConditions object.

Remarks

Use the returned AccountRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that a message is sent or received through the specified account.

This property of the RuleConditions collection always returns an AccountRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then AccountRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.AnyCategory Property (Outlook)

 Copy code hover
[image]

RuleConditions.AnyCategory Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionAnyCategory. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AnyCategory

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a rule that specifies the condition or exception condition that the message is assigned to any category.

This property of the RuleConditions collection always returns a RuleCondition object, regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Application Property (Outlook)

 Copy code hover
[image]

RuleConditions.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a RuleConditions object.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Body Property (Outlook)

 Copy code hover
[image]

RuleConditions.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBody. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Body

expression A variable that represents a RuleConditions object.

Remarks

Use the returned TextRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that certain text is in the message body.

This property of the RuleConditions collection always returns a TextRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then TextRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.BodyOrSubject Property (Outlook)

 Copy code hover
[image]

RuleConditions.BodyOrSubject Property (Outlook)
See also Send feedback

Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionBodyOrSubject. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .BodyOrSubject

expression A variable that represents a RuleConditions object.

Remarks

Use the returned TextRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that certain text is in the message body or subject.

This property of the RuleConditions collection always returns a TextRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then TextRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Category Property (Outlook)

 Copy code hover
[image]

RuleConditions.Category Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a CategoryRuleCondition object with a CategoryRuleCondition.ConditionType of olConditionCategory. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Category

expression A variable that represents a RuleConditions object.

Remarks

Use the returned CategoryRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message is assigned specific categories.

This property of the RuleConditions collection always returns a CategoryRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then CategoryRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.CC Property (Outlook)

 Copy code hover
[image]

RuleConditions.CC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionCc. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CC

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that your name is in the Cc box.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Class Property (Outlook)

 Copy code hover
[image]

RuleConditions.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a RuleConditions object.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Count Property (Outlook)

 Copy code hover
[image]

RuleConditions.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a RuleConditions object.

Remarks

You can enumerate the RuleConditions collection from 1 through RuleConditions.Count to determine all the rule conditions for an existing rule. Although the Rules OM supports creating rules with only the most commonly used rule conditions and not all rule conditions supported by the Rules and Alerts Wizard, the RuleConditions collection includes all rule conditions of a rule. Hence you can always enumerate the RuleConditions collection object to determine which rule conditions are enabled for an existing rule.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.FormName Property (Outlook)

 Copy code hover
[image]

RuleConditions.FormName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a FormNameRuleCondition object with a FormNameRuleCondition.ConditionType of olConditionFormName. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FormName

expression A variable that represents a RuleConditions object.

Remarks

Use the returned FormNameRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message uses a specified form.

This property of the RuleConditions collection always returns a FormNameRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then FormNameRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.From Property (Outlook)

 Copy code hover
[image]

RuleConditions.From Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionFrom. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .From

expression A variable that represents a RuleConditions object.

Remarks

Use the returned ToOrFromRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the sender of the message is in the specified list of Recipients.

This property of the RuleConditions collection always returns a ToOrFromRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then ToOrFromRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.FromAnyRSSFeed Property (Outlook)

 Copy code hover
[image]

RuleConditions.FromAnyRSSFeed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionFromAnyRssFeed. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FromAnyRSSFeed

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a rule that specifies the condition or exception condition that the message is from an RSS subscription.

This property of the RuleConditions collection always returns a RuleCondition object, regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.FromRssFeed Property (Outlook)

 Copy code hover
[image]

RuleConditions.FromRssFeed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a FromRssFeedRuleCondition object with a FromRssFeedRuleCondition.ConditionType of olConditionFromRssFeed. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FromRssFeed

expression A variable that represents a RuleConditions object.

Remarks

Use the returned FromRSSFeedRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message is from a specific RSS subscription.

This property of the RuleConditions collection always returns a FromRSSFeedRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then FromRSSFeedRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.HasAttachment Property (Outlook)

 Copy code hover
[image]

RuleConditions.HasAttachment Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionHasAttachment. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .HasAttachment

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message has an attachment.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Importance Property (Outlook)

 Copy code hover
[image]

RuleConditions.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ImportanceRuleCondition object with an ImportanceRuleCondition.ConditionType of olConditionImportance. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Importance

expression A variable that represents a RuleConditions object.

Remarks

Use the returned ImportanceRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message is of the specified level of importance.

This property of the RuleConditions collection always returns an ImportanceRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then ImportanceRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.MeetingInviteOrUpdate Property (Outlook)

 Copy code hover
[image]

RuleConditions.MeetingInviteOrUpdate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionMeetingInviteOrUpdate. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .MeetingInviteOrUpdate

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message is a meeting request or a meeting update.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.MessageHeader Property (Outlook)

 Copy code hover
[image]

RuleConditions.MessageHeader Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionMessageHeader. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .MessageHeader

expression A variable that represents a RuleConditions object.

Remarks

Use the returned TextRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message header contains the specified text.

This property of the RuleConditions collection always returns a TextRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then TextRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.NotTo Property (Outlook)

 Copy code hover
[image]

RuleConditions.NotTo Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionNotTo. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NotTo

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that your name is not in the To box.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.OnLocalMachine Property (Outlook)

 Copy code hover
[image]

RuleConditions.OnLocalMachine Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionLocalMachineOnly. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .OnLocalMachine

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the rule can run on this machine only. When you run the same rule on another computer, the rule will show that the condition olConditionOtherMachine is enabled.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. You can programmatically enable a rule condition of this type. In certain cases, olConditionLocalMachine is automatically set as a result of enabling another rule condition such as olConditionAccount. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.OnlyToMe Property (Outlook)

 Copy code hover
[image]

RuleConditions.OnlyToMe Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOnlyToMe. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .OnlyToMe

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message is sent only to you.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.OnOtherMachine Property (Outlook)

 Copy code hover
[image]

RuleConditions.OnOtherMachine Property (Outlook)
See also Send feedback

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionOtherMachine. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .OnOtherMachine

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule. This rule condition indicates that the rule can run only on some machine other than the local machine.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition.

You cannot programmatically enable or disable a condition of type olConditionOtherMachine. This type of rule condition indicates that the rule can run only on a specific computer that is not the current one. This happens when the rule is created on that computer and the rule condition olConditionLocalMachineOnly is enabled, indicating that the rule can run only on that computer. When you run the same rule on another computer, the rule will show that the condition olConditionOtherMachine is enabled.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Parent Property (Outlook)

 Copy code hover
[image]

RuleConditions.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a RuleConditions object.

Remarks

The parent of the RuleConditions object is the Rule object.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.RecipientAddress Property (Outlook)

 Copy code hover
[image]

RuleConditions.RecipientAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionRecipientAddress. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RecipientAddress

expression A variable that represents a RuleConditions object.

Remarks

Use the returned AddressRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the recipient address contain the specified text.

This property of the RuleConditions collection always returns a AddressRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then AddressRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.SenderAddress Property (Outlook)

 Copy code hover
[image]

RuleConditions.SenderAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AddressRuleCondition object with an AddressRuleCondition.ConditionType of olConditionSenderAddress. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SenderAddress

expression A variable that represents a RuleConditions object.

Remarks

Use the returned AddressRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the sender address contains the specified text.

This property of the RuleConditions collection always returns a AddressRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then AddressRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.SenderInAddressList Property (Outlook)

 Copy code hover
[image]

RuleConditions.SenderInAddressList Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SenderInAddressListRuleCondition object with a SenderInAddressListRuleCondition.ConditionType of olConditionAccount. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SenderInAddressList

expression A variable that represents a RuleConditions object.

Remarks

Use the returned SenderInAddressListRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the sender is in a specified address list.

This property of the RuleConditions collection always returns a SenderInAddressListRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then SenderInAddressListRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.SentTo Property (Outlook)

 Copy code hover
[image]

RuleConditions.SentTo Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ToOrFromRuleCondition object with a ToOrFromRuleCondition.ConditionType of olConditionSentTo. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SentTo

expression A variable that represents a RuleConditions object.

Remarks

Use the returned ToOrFromRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the recipients (in the To and Cc text boxes) of the message are in the specified list of Recipients.

This property of the RuleConditions collection always returns a ToOrFromRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then ToOrFromRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Session Property (Outlook)

 Copy code hover
[image]

RuleConditions.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a RuleConditions object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.Subject Property (Outlook)

 Copy code hover
[image]

RuleConditions.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TextRuleCondition object with a TextRuleCondition.ConditionType of olConditionSubject. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Subject

expression A variable that represents a RuleConditions object.

Remarks

Use the returned TextRuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that the message subject contains the specified text.

This property of the RuleConditions collection always returns a TextRuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then TextRuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.ToMe Property (Outlook)

 Copy code hover
[image]

RuleConditions.ToMe Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionTo. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToMe

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that your name is in the To box.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions.ToOrCc Property (Outlook)

 Copy code hover
[image]

RuleConditions.ToOrCc Property (Outlook)
See also Send feedback

Returns a RuleCondition object with a RuleCondition.ConditionType of olConditionToOrCc. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToOrCc

expression A variable that represents a RuleConditions object.

Remarks

Use the returned RuleCondition object when enumerating the rule conditions or exception conditions of an existing rule, or when creating a new rule that specifies the condition or exception condition that your name is in the To or Cc box.

This property of the RuleConditions collection always returns a RuleCondition object regardless of whether the rule associated with this RuleConditions collection has defined such a rule condition. If the rule has defined and enabled such a rule condition, then RuleCondition.Enabled will be True.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


RuleConditions Methods (Outlook)

 Copy code hover
[image]

RuleConditions Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Obtains a RuleCondition object specified by Index which is a numerical index into the RuleConditions collection.


RuleConditions.Item Method (Outlook)

 Copy code hover
[image]

RuleConditions.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a RuleCondition object specified by Index which is a numerical index into the RuleConditions collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a RuleConditions object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | A 1-based numerical value that reflects the ordinal position of a rule condition within the RuleConditions collection. For example, the index value of the first rule condition in the collection is 1, and the index value of the second rule condition is 2.

Return Value

A RuleCondition object that represents the specified object.

Remarks

The RuleConditions collection object is a fixed collection. It contains RuleCondition objects or objects derived from RuleCondition. You cannot add or remove items from this collection, but you can index into the collection to enumerate the rule condition items, and set the Enabled property of the rule condition. When using Item to enumerate the collection, you can enumerate Index from 1 to Count.

See also

Concepts

RuleConditions Object

Other resources

RuleConditions Object Members


Rules Object (Outlook)

 Copy code hover
[image]

Rules Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a set of Rule objects that are the rules available in the current session.

Version Information

Version Added: Outlook 2007

Remarks

The Rules object model consists primarily of these objects: Rules, Rule, RuleActions, RuleConditions, RuleAction, RuleCondition, and the derived objects for certain rule actions and rule conditions. It provides partial parity with the Rules and Alerts Wizard in the Outlook user interface. Although it does not support creation of every single rule that you can possibly create using the Wizard, it supports the most commonly used rule actions and conditions.

For more information on how to programmatically create, edit, and delete rules, see Managing Rules in the Outlook Object Model and How to: Create a Rule to Move Specific E-mails to a Folder.

See also

Concepts

Outlook Object Model Reference

Other resources

Rules Object Members


Rules Members (Outlook)

 Copy code hover
[image]

Rules Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a set of Rule objects that are the rules available in the current session.

Methods

Name | Description
Create | Creates a Rule object with the name specified by Name and the type of rule specified by RuleType.
Item | Obtains a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.
Remove | Removes from the Rules collection a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.
Save | Saves all rules in the Rules collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
IsRssRulesProcessingEnabled | Returns or sets a Boolean that indicates whether RSS rules processing has been enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Rules Properties (Outlook)

 Copy code hover
[image]

Rules Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
IsRssRulesProcessingEnabled | Returns or sets a Boolean that indicates whether RSS rules processing has been enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Rules.Application Property (Outlook)

 Copy code hover
[image]

Rules.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Rules object.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Class Property (Outlook)

 Copy code hover
[image]

Rules.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Rules object.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Count Property (Outlook)

 Copy code hover
[image]

Rules.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a Rules object.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.IsRssRulesProcessingEnabled Property (Outlook)

 Copy code hover
[image]

Rules.IsRssRulesProcessingEnabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that indicates whether RSS rules processing has been enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsRssRulesProcessingEnabled

expression A variable that represents a Rules object.

Remarks

After setting IsRssRulesProcessingEnabled, you must call Rules.Save to persist this setting. This property is persisted on a mailbox-level setting that will roam with the user.

If IsRssRulesProcessingEnabled is False, then no conditions about RSS feeds will be evaluated during rules processing.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Parent Property (Outlook)

 Copy code hover
[image]

Rules.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Rules object.

Remarks

The parent of the Rules object is the Store object.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Session Property (Outlook)

 Copy code hover
[image]

Rules.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Rules object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules Methods (Outlook)

 Copy code hover
[image]

Rules Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Create | Creates a Rule object with the name specified by Name and the type of rule specified by RuleType.
Item | Obtains a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.
Remove | Removes from the Rules collection a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.
Save | Saves all rules in the Rules collection.


Rules.Create Method (Outlook)

 Copy code hover
[image]

Rules.Create Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a Rule object with the name specified by Name and the type of rule specified by RuleType.

Version Information

Version Added: Outlook 2007

Syntax

expression .Create(Name, RuleType)

expression A variable that represents a Rules object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | A string identifier for the rule, which will be represented by Rule.Name after rule creation. Names of rules in a collection are not unique.
RuleType | Required | OlRuleType | A constant in the OlRuleType enumeration that determines whether the rule is applied on sending or receiving a message.

Return Value

A Rule object that represents the newly created rule.

Remarks

The RuleType parameter of the added rule determines valid rule actions, rule conditions, and rule exception conditions that can be associated with the Rule object.

When a rule is added to the collection, the Rule.ExecutionOrder of the new rule is 1. The ExecutionOrder of other rules in the collection is incremented by 1.

Example

The following code sample in Visual Basic for Applicatons (VBA) uses the Rules object model to create a rule. The code sample uses the RuleAction and RuleCondition objects to specify a rule that forwards messages from a specific sender to a specific folder, unless the message contains certain terms in the subject. Note that the code sample assumes that there already exists a folder "Dan" under the Inbox.

VBA Copy code Copy code
Sub CreateRule()

 Dim colRules As Outlook.Rules

 Dim oRule As Outlook.Rule

 Dim colRuleActions As Outlook.RuleActions

 Dim oMoveRuleAction As Outlook.MoveOrCopyRuleAction

 Dim oFromCondition As Outlook.ToOrFromRuleCondition

 Dim oExceptSubject As Outlook.TextRuleCondition

 Dim oInbox As Outlook.Folder

 Dim oMoveTarget As Outlook.Folder

 'Specify target folder for rule move action

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 'Assume that target folder already exists

 Set oMoveTarget = oInbox.Folders("Dan")

 'Get Rules from Session.DefaultStore object

 Set colRules = Application.Session.DefaultStore.GetRules()

 'Create the rule by adding a Receive Rule to Rules collection

 Set oRule = colRules.Create("Dan's rule", olRuleReceive)

 'Specify the condition in a ToOrFromRuleCondition object

 'Condition is if the message is sent by "DanWilson"

 Set oFromCondition = oRule.Conditions.From

 With oFromCondition

 .Enabled = True

 .Recipients.Add ("DanWilson")

 .Recipients.ResolveAll

 End With

 'Specify the action in a MoveOrCopyRuleAction object

 'Action is to move the message to the target folder

 Set oMoveRuleAction = oRule.Actions.MoveToFolder

 With oMoveRuleAction

 .Enabled = True

 .Folder = oMoveTarget

 End With

 'Specify the exception condition for the subject in a TextRuleCondition object

 'Exception condition is if the subject contains "fun" or "chat"

 Set oExceptSubject = _

 oRule.Exceptions.Subject

 With oExceptSubject

 .Enabled = True

 .Text = Array("fun", "chat")

 End With

 'Update the server and display progress dialog

 colRules.Save

End Sub

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Item Method (Outlook)

 Copy code hover
[image]

Rules.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a Rules object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either a 1-based long value representing an index into the Rules collection, or a string name representing the value of the default property of a rule, Rule.Name.

Return Value

A Rule object that matches the rule specified by Index.

Remarks

Returns an error when the rule cannot be found in the collection.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Remove Method (Outlook)

 Copy code hover
[image]

Rules.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes from the Rules collection a Rule object specified by Index, which is either a numerical index into the Rules collection or the rule name.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents a Rules object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either a long value representing an index into the Rules collection, or a string name representing the value of the default property of a rule, Rule.Name.

Remarks

Returns an error when the rule cannot be found in the collection.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Rules.Save Method (Outlook)

 Copy code hover
[image]

Rules.Save Method (Outlook)
See also Send feedback

Saves all rules in the Rules collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save(ShowProgress)

expression A variable that represents a Rules object.

Parameters

Name | Required/Optional | Data Type | Description
ShowProgress | Optional | Boolean | True to display the progress dialog box, False to save rules without showing the progress.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

Rules.Save can be an expensive operation in terms of performance on slow connections to Exchange server. For more information on using the progress dialog box, see Manage Rules in the Outlook Object Model.

Saving rules that are incompatible or have improperly defined actions or conditions (such as an empty string for TextRuleCondition.Text) will return an error.

The Exchange server limits the maximum number of rules that can be supported by a store. Rules.Save returns an error when this limit is reached.

See also

Concepts

Rules Object

Other resources

Rules Object Members


Search Object (Outlook)

 Copy code hover
[image]

Search Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains information about individual searches performed against Outlook items.

Remarks

The Search object contains properties that define the type of search and the parameters of the search itself.

Use the Application object's AdvancedSearch method to return a Search object.

Use the AdvancedSearchComplete event to determine when a given search has completed.

Example

The following Microsoft Visual Basic for Applications (VBA) example returns a search object named "SubjectSearch" and displays the object's Tag and Filter property values. The Tag property is used to identify a specific search once it has completed.

Copy code Copy code
Sub SearchInboxFolder()

'Searches the Inbox

 Dim objSch As Search

 Const strF As String = _

 "urn:schemas:mailheader:subject = 'Office Christmas Party'"

 Const strS As String = "Inbox"

 Const strTag As String = "SubjectSearch"

 Set objSch = Application.AdvancedSearch(Scope:=strS, _

 Filter:=strF, SearchSubFolders:=True, Tag:=strTag)

End Sub

The following VBA example displays information about the search and the results of the search.

Copy code Copy code
Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 Dim objRsts As Results

 MsgBox "The search " & SearchObject.Tag & "has completed.

 Set objRsts = SearchObject.Results

 'Print out number in Results collection

 Debug.Print objRsts.Count

 'Print out each member of Results collection

 For Each Item In objRsts

 Debug.Print Item

 Next

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Search Object Members


Search Members (Outlook)

 Copy code hover
[image]

Search Members (Outlook)
Send feedback

Published: July 16, 2012

Contains information about individual searches performed against Outlook items.

Methods

Name | Description
GetTable | Obtains a Table object that contains items filtered by the Filter parameter in a preceding Application.AdvancedSearch method call.
Save | Saves the search results to a Search Folder.
Stop | Immediately ends the search that is being performed currently.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns a String value that represents the DASL statement used to restrict the search to a specified subset of data. Read-only
IsSynchronous | Returns a Boolean indicating whether the search is synchronous. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Results | Returns a Results collection that specifies the results of the search. Read-only.
Scope | Returns a String that specifies the scope of the specified search. Read-only.
SearchSubFolders | Returns a Boolean indicating whether the scope of the specified search included the subfolders of any folders searched. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Tag | Returns a String specifying the name of the current search. The Tag property is used to identify a specific search. Read-only.


Search Properties (Outlook)

 Copy code hover
[image]

Search Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns a String value that represents the DASL statement used to restrict the search to a specified subset of data. Read-only
IsSynchronous | Returns a Boolean indicating whether the search is synchronous. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Results | Returns a Results collection that specifies the results of the search. Read-only.
Scope | Returns a String that specifies the scope of the specified search. Read-only.
SearchSubFolders | Returns a Boolean indicating whether the scope of the specified search included the subfolders of any folders searched. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Tag | Returns a String specifying the name of the current search. The Tag property is used to identify a specific search. Read-only.


Search.Application Property (Outlook)

 Copy code hover
[image]

Search.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Search object.

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Class Property (Outlook)

 Copy code hover
[image]

Search.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Search object.

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Filter Property (Outlook)

 Copy code hover
[image]

Search.Filter Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the DASL statement used to restrict the search to a specified subset of data. Read-only

Syntax

expression .Filter

expression A variable that represents a Search object.

Remarks

This property is set as the Filter argument in the Application object's AdvancedSearch method.

When searching Text fields, you can use either an apostrophe (') or double quotation marks ("") to delimit the values that are part of the filter. For example, all of the following lines function correctly when the field is of type String:

VBA Copy code Copy code
sFilter = "[CompanyName] = 'Microsoft'"
VBA Copy code Copy code
sFilter = "[CompanyName] = ""Microsoft"""
VBA Copy code Copy code
sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new Search object. The event subroutine fires after the search has finished and displays the Tag and Filter properties of the Search object in addition to the results of the search.

VBA Copy code Copy code
Sub SearchInboxFolder()

 'Searches the Inbox folder

 Dim objSch As Outlook.Search

 Const strF As String = _

 "urn:schemas:mailheader:subject = 'Office Holiday Party'"

 Const strS As String = "Inbox"

 Const strTag As String = "SubjectSearch"

 Set objSch = _

 Application.AdvancedSearch(Scope:=strS, Filter:=strF, Tag:=strTag)

End Sub

Use an AdvancedSearchComplete event subroutine to ensure the integrity of the data stored in the Search object.

VBA Copy code Copy code
Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 Dim objRsts As Outlook.Results

 Dim Item as Outlook.MailItem

 MsgBox "The search " & SearchObject.Tag & "has finished. The filter used was " & _

 SearchObject.Filter & "."

 Set objRsts = SearchObject.Results

 'Print out number in results collection

 MsgBox objRsts.Count

 'Print out each member of results collection

 For Each Item In objRsts

 MsgBox Item

 Next

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search.IsSynchronous Property (Outlook)

 Copy code hover
[image]

Search.IsSynchronous Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean indicating whether the search is synchronous. Read-only.

Syntax

expression .IsSynchronous

expression A variable that represents a Search object.

Remarks

A search can be synchronous or asynchronous. If the search is synchronous, code execution will pause until the search has completed. Conversely, if the search is asynchronous, code execution will continue even though the search has not completed. In this case, use the Search object's Stop method to halt the search. In order to get meaningful results from an asynchronous search, use the AdvancedSearchComplete event to notify you when the search has finished.

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Parent Property (Outlook)

 Copy code hover
[image]

Search.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Search object.

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Results Property (Outlook)

 Copy code hover
[image]

Search.Results Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Results collection that specifies the results of the search. Read-only.

Syntax

expression .Results

expression A variable that represents a Search object.

Example

The following Visual Basic for Applications (VBA) example searches the Inbox for items with a subject that equals "Test" and displays the names of the senders of the e-mail items returned by the search. The AdvanceSearchComplete event procedure sets the boolean blnSearchComp to True when the search is complete. This boolean variable is used by the TestAdvancedSearchComplete() procedure to determine when the search is complete. The sample code must be placed in a class module, such as ThisOutlookSession, and the TestAdvancedSearchComplete() procedure must be called before the event procedure can be called by Outlook.

Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired"

 blnSearchComp = True

End Sub

Sub TestAdvancedSearchComplete()

 Dim sch As Outlook.Search

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS As String = "Inbox"

 Set sch = Application.AdvancedSearch(strS, strF)

 While blnSearchComp = False

 DoEvents

 Wend

 Set rsts = sch.Results

 For i = 1 To rsts.Count

 MsgBox rsts.Item(i).SenderName

 Next

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Scope Property (Outlook)

 Copy code hover
[image]

Search.Scope Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that specifies the scope of the specified search. Read-only.

Syntax

expression .Scope

expression A variable that represents a Search object.

Remarks

The scope of the search is defined when the search is initiated. For more information, see the AdvancedSearch method.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a Search object. The user's Inbox is specified as the scope of the search. The event subroutine occurs when the search has completed and displays the Tag and Scope properties for the new object in addition to the results of the search.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired for " & SearchObject.Tag & " and the scope was " & SearchObject.Scope

 blnSearchComp = True

End Sub

Sub TestAdvancedSearchComplete()

 'List all items in the Inbox that do NOT have a flag.

 Dim objSch As Outlook.Search

 Const strF As String = "urn:schemas:httpmail:messageflag IS NULL"

 Const strS As String = "Inbox"

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF1 As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS1 As String = "Inbox"

 Set objSch = _

 Application.AdvancedSearch(Scope:=strS1, Filter:=strF1, Tag:="FlagSearch")

 While blnSearchComp = False

 DoEvents

 Wend

 Set rsts = objSch.Results

 For i = 1 To rsts.Count

 MsgBox rsts.Item(i).SenderName

 Next

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search.SearchSubFolders Property (Outlook)

 Copy code hover
[image]

Search.SearchSubFolders Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean indicating whether the scope of the specified search included the subfolders of any folders searched. Read-only.

Syntax

expression .SearchSubFolders

expression A variable that represents a Search object.

Remarks

This property is determined by the SearchSubfolders argument of the AdvancedSearch method and is specified when the search is initiated. If True, the Search object searches through any subfolders in the specified filter path.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a Search object. The user's Inbox is specified as the scope of the search and the SearchSubFolders property is set to True. The event subroutine fires when the search has completed and displays the Tag and Scope properties for the new object as well as the results of the search.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired for " & SearchObject.Tag & _

 " and the scope was " & SearchObject.Scope

 blnSearchComp = True

End Sub

Sub TestAdvancedSearchComplete()

 'List all items in the Inbox that do NOT have a flag:

 Dim objSch As Outlook.Search

 Const strF As String = "urn:schemas:httpmail:messageflag IS NULL"

 Const strS As String = "Inbox"

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF1 As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS1 As String = "Inbox"

 Set objSch = _

 Application.AdvancedSearch(Scope:=strS1, Filter:=strF1, _

 SearchSubFolders:=True, Tag:="FlagSearch")

 While blnSearchComp = False

 DoEvents

 Wend

 Set rsts = objSch.Results

 For i = 1 To rsts.Count

 MsgBox rsts.Item(i).SenderName

 Next

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Session Property (Outlook)

 Copy code hover
[image]

Search.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Search object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Tag Property (Outlook)

 Copy code hover
[image]

Search.Tag Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String specifying the name of the current search. The Tag property is used to identify a specific search. Read-only.

Syntax

expression .Tag

expression A variable that represents a Search object.

Remarks

The Tag property is set by using the AdvancedSearch method when the Search object is created.

Example

The following Visual Basic for Applications (VBA) example searches through the user's Inbox for all items that do not have a flag. The name "FlagSearch", specified by the Tag property, is given to the search. The AdvanceSearchComplete event procedure sets the boolean blnSearchComp to True when the search is complete. This boolean variable is used by the TestAdvancedSearchComplete() procedure to determine when the search is complete. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAdvancedSearchComplete() subroutine must be called before the event procedure can be called by Outlook. The AdvanceSearchComplete event procedure displays the tag to the user so the user can identify which search was completed because usually the search is asynchronous (use the IsSynchronous property to determine if the search will be synchronous or asynchronous), and you can execute multiple searches simultaneously.

Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired for " & _

 SearchObject.Tag & " and the scope was " & SearchObject.Scope

 blnSearchComp = True

End Sub

Sub TestAdvancedSearch111Complete()

 'List all items in the Inbox that do NOT have a flag:

 Dim objSch As Outlook.Search

 Const strF As String = "urn:schemas:httpmail:messageflag IS NULL"

 Const strS As String = "Inbox"

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF1 As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS1 As String = "Inbox"

 Set objSch = _

 Application.AdvancedSearch(Scope:=strS1, Filter:=strF1, _

 Tag:="FlagSearch")

 While blnSearchComp = False

 DoEvents

 Wend

 Set rsts = objSch.Results

 For i = 1 To rsts.Count

 MsgBox rsts.Item(i).SenderName

 Next

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search Methods (Outlook)

 Copy code hover
[image]

Search Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetTable | Obtains a Table object that contains items filtered by the Filter parameter in a preceding Application.AdvancedSearch method call.
Save | Saves the search results to a Search Folder.
Stop | Immediately ends the search that is being performed currently.


Search.GetTable Method (Outlook)

 Copy code hover
[image]

Search.GetTable Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Table object that contains items filtered by the Filter parameter in a preceding Application.AdvancedSearch method call.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetTable

expression A variable that represents a Search object.

Return Value

A Table that contains items that meet the criteria specified by the Filter parameter in a preceding Application.AdvancedSearch method call.

Remarks

Unlike Folder.GetTable, Search.GetTable does not accept a Filter parameter. The filter for the Table is determined by Search.Filter. Since Search.Filter is a read-only property, the Filter parameter for the Application.AdvancedSearch method establishes the filter for the Table object returned by Search.GetTable.

The Filter parameter supplied to Application.AdvancedSearch must be a DASL query. The filter for AdvancedSearch will not accept a JET query. Do not prefix a DASL query for AdvancedSearch with "@SQL=". If you add the "@SQL=" prefix, your query will raise an error. For more information on filters, see Filtering Items.

Search.GetTable returns a Table with the default column set for the folder type of the parent Folder. To modify the default column set, use the Add, Remove, or RemoveAll methods of the Columns collection object. For more information on default column sets, see Default Properties Displayed in a Table Object.

Unlike Folder.GetTable, you cannot use Table.Restrict to apply subsequent filters to a Table that is based on the Search object. Specify a new filter in Application.AdvancedSearch to re-apply a filter.

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Save Method (Outlook)

 Copy code hover
[image]

Search.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the search results to a Search Folder.

Syntax

expression .Save SchFldrName

expression A variable that represents a Search object.

Parameters

Name | Required/Optional | Data Type | Description
SchFldrName | Required | String | A string that represents the Search Folder name.

Remarks

The Save method displays an error if a Search Folder with the same name already exists.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches the Inbox for items with Subject line equal to 'Test' and saves the results in a Search Folder. The AdvanceSearchComplete event procedure sets the Boolean blnSearchComp to True when the search is complete. This Boolean variable is used by the TestAdvancedSearchComplete() procedure to determine when the search is complete. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAdvancedSearchComplete() procedure must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public blnSearchComp As Boolean

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)

 MsgBox "The AdvancedSearchComplete Event fired"

 blnSearchComp = True

End Sub

Sub TestAdvancedSearchComplete()

 Dim sch As Outlook.Search

 Dim rsts As Outlook.Results

 Dim i As Integer

 blnSearchComp = False

 Const strF As String = "urn:schemas:mailheader:subject = 'Test'"

 Const strS As String = "Inbox"

 Set sch = Application.AdvancedSearch(strS, strF)

 While blnSearchComp = False

 DoEvents

 Wend

 sch.Save("Subject Test")

End Sub

See also

Concepts

Search Object

Other resources

Search Object Members


Search.Stop Method (Outlook)

 Copy code hover
[image]

Search.Stop Method (Outlook)
See also Send feedback

Immediately ends the search that is being performed currently.

Syntax

expression .Stop

expression A variable that represents a Search object.

See also

Concepts

Search Object

Other resources

Search Object Members


Selection Object (Outlook)

 Copy code hover
[image]

Selection Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains the set of Outlook items currently selected in an explorer.

Remarks

Use the Selection property to return the Selection collection from the Explorer object.

Example

The following example returns a Selection object from an Explorer object.

Copy code Copy code
Set mySelectedItems = myExplorer.Selection

See also

Concepts

Outlook Object Model Reference

Other resources

Selection Object Members


Selection Members (Outlook)

 Copy code hover
[image]

Selection Members (Outlook)
Send feedback

Published: July 16, 2012

Contains the set of Outlook items currently selected in an explorer.

Methods

Name | Description
GetSelection | Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer.
Item | Returns a Microsoft Outlook item or conversation header from the selection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long that indicates the number of items or conversation headers in the selection. Read-only.
Location | Returns an OlSelectionLocation constant that specifies where in the Microsoft Outlook user interface the current selection is. Read-only
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Selection Properties (Outlook)

 Copy code hover
[image]

Selection Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long that indicates the number of items or conversation headers in the selection. Read-only.
Location | Returns an OlSelectionLocation constant that specifies where in the Microsoft Outlook user interface the current selection is. Read-only
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Selection.Application Property (Outlook)

 Copy code hover
[image]

Selection.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Selection object.

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection.Class Property (Outlook)

 Copy code hover
[image]

Selection.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Selection object.

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection.Count Property (Outlook)

 Copy code hover
[image]

Selection.Count Property (Outlook)
See also Send feedback

Returns a Long that indicates the number of items or conversation headers in the selection. Read-only.

Syntax

expression .Count

expression A variable that represents a Selection object.

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection.Location Property (Outlook)

 Copy code hover
[image]

Selection.Location Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlSelectionLocation constant that specifies where in the Microsoft Outlook user interface the current selection is. Read-only

Version Information

Version Added: Outlook 2010

Syntax

expression .Location

expression A variable that represents a Selection object.

Remarks

A Location property with the value olViewList means that the current selection is in a list of items in an explorer. Calling Selection.GetSelection with olConversationHeaders as the argument returns a Selection object with Selection.Count equal to the number of conversation headers in the current selection.

If the Location property is not equal to olViewList, calling GetSelection with olConversationHeaders as the argument returns a Selection object with Selection.Count equal to 0.

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection.Parent Property (Outlook)

 Copy code hover
[image]

Selection.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Selection object.

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection.Session Property (Outlook)

 Copy code hover
[image]

Selection.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Selection object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Selection Object

Other resources

Selection Object Members


Selection Methods (Outlook)

 Copy code hover
[image]

Selection Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetSelection | Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer.
Item | Returns a Microsoft Outlook item or conversation header from the selection.


Selection.GetSelection Method (Outlook)

 Copy code hover
[image]

Selection.GetSelection Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Selection object that contains the kind of objects specified by the SelectionContents parameter, and that are currently selected in the active explorer.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetSelection(SelectionContents)

expression A variable that represents a Selection object.

Parameters

Name | Required/Optional | Data Type | Description
SelectionContents | Required | OlSelectionContents | Specifies the kind of objects in the selection to return.

Return Value

A Selection object that contains the specified kind of objects that are selected in the active explorer.

Remarks

Calling GetSelection with olConversationHeaders as the argument returns a Selection object that has the Location property equal to OlSelectionLocation.olViewList.

If the current view is not a conversation view, or, if Selection.Location is not equal to OlSelectionLocation.olViewList, calling GetSelection with olConversationHeaders as the argument returns a Selection object with Selection.Count equal to 0.

See also

Concepts

How to: Obtain and Enumerate Selected Conversations
Selection Object

Other resources

Selection Object Members


Selection.Item Method (Outlook)

 Copy code hover
[image]

Selection.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Microsoft Outlook item or conversation header from the selection.

Syntax

expression .Item(Index)

expression A variable that represents a Selection object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

An Object that represents the specified item or conversation header.

Remarks

Do not make any assumptions about the Item method return type; your code should be able to handle multiple item types or a ConversationHeader object. For example, the Item method can return an AppointmentItem, MailItem, MeetingItem, or TaskItem in the Inbox folder, depending on the value of the Selection.Location property.

The Selection collection contains ConversationHeader objects only if you specify olConversationHeaders in the GetSelection method of the Selection object.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the sender of each selected item in the active explorer. It uses the Count property and Item method of the Selection object, returned by the Explorer.Selection property, to display the senders of all messages that are selected in the active explorer.

VBA Copy code Copy code
Sub GetSelectedItems()
 Dim myOlExp As Outlook.Explorer
 Dim myOlSel As Outlook.Selection
 Dim mySender As Outlook.AddressEntry
 Dim oMail As Outlook.MailItem
 Dim oAppt As Outlook.AppointmentItem
 Dim oPA As Outlook.PropertyAccessor
 Dim strSenderID As String
 Const PR_SENT_REPRESENTING_ENTRYID As String = _
 "http://schemas.microsoft.com/mapi/proptag/0x00410102"
 Dim MsgTxt As String
 Dim x As Long

 MsgTxt = "Senders of selected items:"
 Set myOlExp = Application.ActiveExplorer
 Set myOlSel = myOlExp.Selection
 For x = 1 To myOlSel.Count
 If myOlSel.Item(x).Class = OlObjectClass.olMail Then
 ' For mail item, use the SenderName property.
 Set oMail = myOlSel.Item(x)
 MsgTxt = MsgTxt & oMail.SenderName & ";"
 ElseIf myOlSel.Item(x).Class = OlObjectClass.olAppointment Then
 ' For appointment item, use the Organizer property.
 Set oAppt = myOlSel.Item(x)
 MsgTxt = MsgTxt & oAppt.Organizer & ";"
 Else
 ' For other items, use the property accessor to get sender ID,
 ' then get the address entry to display the sender name.
 Set oPA = myOlSel.Item(x).PropertyAccessor
 strSenderID = oPA.GetProperty(PR_SENT_REPRESENTING_ENTRYID)
 Set mySender = Application.Session.GetAddressEntryFromID(strSenderID)
 MsgTxt = MsgTxt & mySender.Name & ";"
 End If
 Next x
 Debug.Print MsgTxt
End Sub

See also

Concepts

Selection Object

Other resources

Selection Object Members


SelectNamesDialog Object (Outlook)

 Copy code hover
[image]

SelectNamesDialog Object (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Select Names dialog box for the user to select entries from one or more address lists, and returns the selected entries in the collection object specified by the property SelectNamesDialog.Recipients.

Version Information

Version Added: Outlook 2007

Remarks

You can instantiate an instance of the SelectNamesDialog object by calling NameSpace.GetSelectNamesDialog.

The dialog box displayed by SelectNamesDialog.Display is similar to the Select Names dialog box in the Outlook user interface. It observes the size and position settings of the built-in Select Names dialog box. However, its default state does not show Message Recipients above the To, Cc, and Bcc edit boxes. For more information on using the SelectNamesDialog object to display the Select Names dialog box, see Display Names from the Address Book.

Example

The following code sample shows how to use the SelectNamesDialog object to display entries from the Contacts folder in a dialog box that resembles the Select Names dialog box in the Outlook user interface.

Copy code Copy code
Sub ShowContactsInDialog()

 Dim oDialog As SelectNamesDialog

 Dim oAL As AddressList

 Dim oContacts As Folder

 Set oDialog = Application.Session.GetSelectNamesDialog

 Set oContacts = _

 Application.Session.GetDefaultFolder(olFolderContacts)

 'Look for the address list that corresponds with the Contacts folder

 For Each oAL In Application.Session.AddressLists

 If oAL.GetContactsFolder = oContacts Then

 Exit For

 End If

 Next

 With oDialog

 'Initialize the dialog box with the address list representing the Contacts folder

 .InitialAddressList = oAL

 .ShowOnlyInitialAddressList = True

 If .Display Then

 'Recipients Resolved

 'Access Recipients using oDialog.Recipients

 End If

 End With

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

SelectNamesDialog Object Members


SelectNamesDialog Members (Outlook)

 Copy code hover
[image]

SelectNamesDialog Members (Outlook)
Send feedback

Published: July 16, 2012

Displays the Select Names dialog box for the user to select entries from one or more address lists, and returns the selected entries in the collection object specified by the property SelectNamesDialog.Recipients.

Methods

Name | Description
Display | Displays the Select Names dialog box.
SetDefaultDisplayMode | Sets the default display mode for the Select Names dialog box, specifying its caption and button labels.

Properties

Name | Description
AllowMultipleSelection | Returns or sets a Boolean that determines whether more than one address entry can be selected at a time in the Select Names dialog. Read/write.
Application | Returns an Application object that represents the parent application (Outlook) for the SelectNamesDialog object. Read-only.
BccLabel | Returns or sets a String for the text that appears on the Bcc command button on the Select Names dialog box. Read/write.
Caption | Returns or sets a String value that represents the title for the Select Names dialog box. Read/write.
CcLabel | Returns or sets a String for the text that appears on the Cc command button on the Select Names dialog box. Read/write.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the SelectNamesDialog object. Read-only.
ForceResolution | Returns or sets a Boolean that determines if Outlook must resolve all recipients in the object specified by SelectNamesDialog.Recipients before the user can click OK to accept the typed or selected recipients in the Select Names dialog box. Read/write.
InitialAddressList | Returns or sets an AddressList object that determines the initial address list to be displayed in the Select Names dialog box. Read/write.
NumberOfRecipientSelectors | Returns or sets a OlRecipientSelectors constant that determines the number of recipient edit boxes (each associated with a command button) displayed in the Select Names dialog box. Read/write.
Parent | Returns the parent object of the SelectNamesDialog object. Read-only.
Recipients | Returns a Recipients collection object that represents the recipients selected in the Select Names dialog, or sets a Recipients collection object that represents the initial recipients to be displayed in the Select Names dialog box. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
ShowOnlyInitialAddressList | Returns or sets a Boolean that determines if the AddressList represented by SelectNamesDialog.InitialAddressList is the only AddressList available in the drop-down list for Address Book in the Select Names dialog box. Read/write.
ToLabel | Returns or sets a String for the text that appears on the To command button on the Select Names dialog box. Read/write.


SelectNamesDialog Properties (Outlook)

 Copy code hover
[image]

SelectNamesDialog Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AllowMultipleSelection | Returns or sets a Boolean that determines whether more than one address entry can be selected at a time in the Select Names dialog. Read/write.
Application | Returns an Application object that represents the parent application (Outlook) for the SelectNamesDialog object. Read-only.
BccLabel | Returns or sets a String for the text that appears on the Bcc command button on the Select Names dialog box. Read/write.
Caption | Returns or sets a String value that represents the title for the Select Names dialog box. Read/write.
CcLabel | Returns or sets a String for the text that appears on the Cc command button on the Select Names dialog box. Read/write.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the SelectNamesDialog object. Read-only.
ForceResolution | Returns or sets a Boolean that determines if Outlook must resolve all recipients in the object specified by SelectNamesDialog.Recipients before the user can click OK to accept the typed or selected recipients in the Select Names dialog box. Read/write.
InitialAddressList | Returns or sets an AddressList object that determines the initial address list to be displayed in the Select Names dialog box. Read/write.
NumberOfRecipientSelectors | Returns or sets a OlRecipientSelectors constant that determines the number of recipient edit boxes (each associated with a command button) displayed in the Select Names dialog box. Read/write.
Parent | Returns the parent object of the SelectNamesDialog object. Read-only.
Recipients | Returns a Recipients collection object that represents the recipients selected in the Select Names dialog, or sets a Recipients collection object that represents the initial recipients to be displayed in the Select Names dialog box. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
ShowOnlyInitialAddressList | Returns or sets a Boolean that determines if the AddressList represented by SelectNamesDialog.InitialAddressList is the only AddressList available in the drop-down list for Address Book in the Select Names dialog box. Read/write.
ToLabel | Returns or sets a String for the text that appears on the To command button on the Select Names dialog box. Read/write.


SelectNamesDialog.AllowMultipleSelection Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.AllowMultipleSelection Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines whether more than one address entry can be selected at a time in the Select Names dialog. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AllowMultipleSelection

expression A variable that represents a SelectNamesDialog object.

Remarks

The default value of AllowMultipleSelection is True. If AllowMultipleSelection is set to True, the user can select multiple recipients by using the CTRL or SHIFT key. If AllowMultipleSelection is set to False, multiple selection is disabled.

Setting AllowMultipleSelection to False does not ensure that only one recipient can be selected. The user can type additional recipients in the edit box or select from the recipient list multiple times. To ensure that only one recipient can be selected in the dialog, set AllowMultipleSelect to False and SelectNamesDialog.NumberOfRecipientSelectors to olShowNone.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Application Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent application (Outlook) for the SelectNamesDialog object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a SelectNamesDialog object.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.BccLabel Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.BccLabel Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String for the text that appears on the Bcc command button on the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BccLabel

expression A variable that represents a SelectNamesDialog object.

Remarks

To provide an accelerator key for the recipient edit boxes, include an ampersand (&) character in the label argument string, immediately before the character that serves as the access key. For example, if BccLabel is the string "Local &Attendees", users can press ALT+A to move the focus to the first recipient edit box.

If BccLabel is not set, then the default value will be the localized string for "Bcc". If the BccLabel is set to an empty string, then the Bcc command button shows ->. If the BccLabel property contains more than 32 characters (including the ampersand (&) access key), only the first 32 characters will be displayed in the command button.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Caption Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Caption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the title for the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Caption

expression A variable that represents a SelectNamesDialog object.

Remarks

If you do not set Caption, the title of the dialog box will be Select Names or the localized equivalent. If you set Caption to an empty string, the dialog box caption will be an empty string.

Setting the Caption to a long string (for example, 300 characters) will cause the caption to be truncated, and will not cause the width of the Select Names dialog to change.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.CcLabel Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.CcLabel Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String for the text that appears on the Cc command button on the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CcLabel

expression A variable that represents a SelectNamesDialog object.

Remarks

To provide an accelerator key for the recipient edit boxes, include an ampersand (&) character in the label argument string, immediately before the character that serves as the access key. For example, if CcLabel is the string "Local &Attendees", users can press ALT+A to move the focus to the first recipient edit box.

If CcLabel is not set, then the default value will be the localized string for "Cc". If the CcLabel is set to an empty string, then the Cc command button shows ->. If the CcLabel property contains more than 32 characters (including the ampersand (&) access key), only the first 32 characters will be displayed in the command button.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Class Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Class Property (Outlook)
See also Send feedback

Returns a constant in the OlObjectClass enumeration indicating the class of the SelectNamesDialog object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a SelectNamesDialog object.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.ForceResolution Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.ForceResolution Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if Outlook must resolve all recipients in the object specified by SelectNamesDialog.Recipients before the user can click OK to accept the typed or selected recipients in the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ForceResolution

expression A variable that represents a SelectNamesDialog object.

Remarks

The default value is True. If a recipient cannot be resolved, Outlook will prompt the user to resolve the ambiguous names. The user must have all recipients in the recipient edit box resolved before being able to click OK.

ForceResolution is ignored if the user clicks Cancel or the Close icon.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.InitialAddressList Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.InitialAddressList Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an AddressList object that determines the initial address list to be displayed in the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .InitialAddressList

expression A variable that represents a SelectNamesDialog object.

Remarks

Setting the InitialAddressList property is the programmatic equivalent to selecting an AddressList from the drop-down list for Address Book in the Select Names dialog box.

In its default state, InitialAddressList is the AddressList that has the property AddressList.IsInitialAddressList set to True. IsInitialAddressList corresponds to setting Show this address list first in the Addressing dialog box, which is available by clicking Tools, and then Options in the Address Book dialog box.

Example

The following code sample shows how to use InitialAddressList and SelectNamesDialog.ShowOnlyInitialAddressList to have the Select Names dialog box always display only the address list in the default Contacts folder, regardless of the user's setting for the initial address list.

VBA Copy code Copy code
Sub ShowOnlyContacts()

 Dim oMsg As MailItem

 Set oMsg = Application.CreateItem(olMailItem)

 Dim oDialog As SelectNamesDialog

 Set oDialog = Application.Session.GetSelectNamesDialog

 Dim oContacts As Folder

 Set oContacts = _

 Application.Session.GetDefaultFolder(olFolderContacts)

 Dim oAL As AddressList

 For Each oAL In Application.Session.AddressLists

 If oAL.GetContactsFolder = oContacts Then

 Exit For

 End If

 Next

 With oDialog

 .InitialAddressList = oAL

 .ShowOnlyInitialAddressList = True

 .Recipients = oMsg.Recipients

 If .Display Then

 'Recipients Resolved

 End If

 End With

End Sub

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.NumberOfRecipientSelectors Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.NumberOfRecipientSelectors Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a OlRecipientSelectors constant that determines the number of recipient edit boxes (each associated with a command button) displayed in the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .NumberOfRecipientSelectors

expression A variable that represents a SelectNamesDialog object.

Remarks

A recipient edit box allows you to enter recipient names. Each recipient edit box is associated with a command button in the Select Names dialog box; examples of a command button for a recipient edit box are the To and Cc command buttons. The default value of NumberOfRecipientSelectors is OlRecipientSelectors.olToCcBcc.

If you set NumberOfRecipientSelectors to OlRecipientSelectors.olShowTo and then subsequently set the text for SelectNamesDialog.CcLabel or SelectNamesDialog.BccLabel, the NumberOfRecipientSelectors will remain unchanged.

If you set NumberOfRecipientSelectors to OlRecipientSelectors.olShowNone, then the SelectNamesDialog.AllowMultipleSelection property will be ignored.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Parent Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent object of the SelectNamesDialog object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a SelectNamesDialog object.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Recipients Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection object that represents the recipients selected in the Select Names dialog, or sets a Recipients collection object that represents the initial recipients to be displayed in the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Recipients

expression A variable that represents a SelectNamesDialog object.

Remarks

This property specifies a Recipients collection object that has a Recipients.Count equal to the total number of recipients in the To, Cc, and Bcc edit boxes.

If you do not set this property before displaying the Select Names dialog box, then the Recipients object represented by SelectNamesDialog.Recipients will have a Recipients.Count equal to zero.

If the user does not select any names from the Select Names dialog box and clicks OK, SelectNamesDialog.Recipients will return a Recipients collection object with Recipients.Count equal to zero.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.Session Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a SelectNamesDialog object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.ShowOnlyInitialAddressList Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.ShowOnlyInitialAddressList Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the AddressList represented by SelectNamesDialog.InitialAddressList is the only AddressList available in the drop-down list for Address Book in the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowOnlyInitialAddressList

expression A variable that represents a SelectNamesDialog object.

Remarks

The default value of this property is False, meaning that all address lists are displayed. To restrict the drop-down list for Address Book to the one indicated by InitialAddressList, set ShowOnlyInitialAddressList to True.

If you do not set the InitialAddressList property and then set ShowOnlyInitialAddressList to True, then the AddressList with AddressList.IsInitialAddressList equal to True will be the only address list available in the drop-down list for Address Book.

Example

The following code sample shows how to use IsInitialAddressList and ShowOnlyInitialAddressList to have the Select Names dialog box always display only the address list in the default Contacts folder, regardless of the user's setting for the initial address list.

VBA Copy code Copy code
Sub ShowOnlyContacts()

 Dim oMsg As MailItem

 Set oMsg = Application.CreateItem(olMailItem)

 Dim oDialog As SelectNamesDialog

 Set oDialog = Application.Session.GetSelectNamesDialog

 Dim oContacts As Folder

 Set oContacts = _

 Application.Session.GetDefaultFolder(olFolderContacts)

 Dim oAL As AddressList

 For Each oAL In Application.Session.AddressLists

 If oAL.GetContactsFolder = oContacts Then

 Exit For

 End If

 Next

 With oDialog

 .InitialAddressList = oAL

 .ShowOnlyInitialAddressList = True

 .Recipients = oMsg.Recipients

 If .Display Then

 'Recipients Resolved

 End If

 End With

End Sub

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.ToLabel Property (Outlook)

 Copy code hover
[image]

SelectNamesDialog.ToLabel Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String for the text that appears on the To command button on the Select Names dialog box. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToLabel

expression A variable that represents a SelectNamesDialog object.

Remarks

To provide an accelerator key for the recipient edit boxes, include an ampersand (&) character in the label argument string, immediately before the character that serves as the access key. For example, if ToLabel is the string "Local &Attendees", users can press ALT+A to move the focus to the first recipient edit box.

If ToLabel is not set, the default value will be the localized string for "To". If the ToLabel is set to an empty string, then the To command button shows ->. If the ToLabel property contains more than 32 characters (including the ampersand (&) access key), only the first 32 characters will be displayed in the command button.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog Methods (Outlook)

 Copy code hover
[image]

SelectNamesDialog Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Display | Displays the Select Names dialog box.
SetDefaultDisplayMode | Sets the default display mode for the Select Names dialog box, specifying its caption and button labels.


SelectNamesDialog.Display Method (Outlook)

 Copy code hover
[image]

SelectNamesDialog.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Select Names dialog box.

Version Information

Version Added: Outlook 2007

Syntax

expression .Display

expression A variable that represents a SelectNamesDialog object.

Return Value

A Boolean value that is True if the user has clicked OK, and False if the user has clicked Cancel or the Close icon.

Remarks

When displaying the Select Names dialog box, Display uses the previous location and size (indicated by the top, left, width, and height) of the dialog box.

The Select Names dialog box is modal, meaning that code execution will halt until the user clicks OK, Cancel, or the close icon.

You should detect for error conditions that include insufficient memory or another message or dialog box is open.

Example

The following code sample shows how to create a mail item, allow the user to select recipients from the Exchange Global Address List in the Select Names dialog box, and if the user has selected recipients that can be completely resolved, then send the mail item.

VBA Copy code Copy code
Sub SelectRecipients()
 Dim oMsg As MailItem
 Set oMsg = Application.CreateItem(olMailItem)
 Dim oDialog As SelectNamesDialog
 Set oDialog = Application.Session.GetSelectNamesDialog
 With oDialog
 .InitialAddressList = _
 Application.Session.GetGlobalAddressList
 .Recipients = oMsg.Recipients
 If .Display Then
 'Recipients Resolved
 oMsg.Subject = "Hello"
 oMsg.Send
 End If
 End With
End Sub

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SelectNamesDialog.SetDefaultDisplayMode Method (Outlook)

 Copy code hover
[image]

SelectNamesDialog.SetDefaultDisplayMode Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sets the default display mode for the Select Names dialog box, specifying its caption and button labels.

Version Information

Version Added: Outlook 2007

Syntax

expression .SetDefaultDisplayMode(defaultMode)

expression A variable that represents a SelectNamesDialog object.

Parameters

Name | Required/Optional | Data Type | Description
defaultMode | Required | OlDefaultSelectNamesDisplayMode | A constant in the OlDefaultSelectNamesDisplayMode enumeration that determines the default caption and button labels for the Select Names dialog box.

Remarks

SetDefaultDisplayMode is optional. If you do not call SetDefaultDisplayMode before calling Display, the default display mode will be OlDefaultSelectNamesDisplayMode.olDefaultMail. To set the display mode to a different value, you should call SetDefaultDisplayMode before calling the Display method.

This method allows you to display the Select Names dialog box without using a resource file to localize the values for the caption, the To label, Cc label, and Bcc label. You can override the built-in behavior by setting your own values for Caption, ToLabel, CcLabel, and BccLabel.

You can set additional properties (for example, setting NumberOfRecipientSelectors to olRecipientSelectors.olToCc) after calling SetDefaultDisplayMode. The Select Names dialog box will observe the subsequent setting.

See also

Concepts

SelectNamesDialog Object

Other resources

SelectNamesDialog Object Members


SenderInAddressListRuleCondition Object (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that the sender's address is in the address list specified in AddressRuleCondition.Address.

Version Information

Version Added: Outlook 2007

Remarks

SenderInAddressListRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has a SenderInAddressList property. The SenderInAddressList property always returns a SenderInAddressListRuleCondition object. If the rule has any of these rule conditions enabled, then SenderInAddressListRuleCondition.Enabled would be True.

For more information on specifying rule conditions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

SenderInAddressListRuleCondition Members


SenderInAddressListRuleCondition Members (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that the sender's address is in the address list specified in AddressRuleCondition.Address.

Properties

Name | Description
AddressList | Returns or sets an AddressList object that represents the address list used to evaluate the rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionSenderInAddressBook, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SenderInAddressListRuleCondition Properties (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AddressList | Returns or sets an AddressList object that represents the address list used to evaluate the rule condition. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant, olConditionSenderInAddressBook, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SenderInAddressListRuleCondition.AddressList Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.AddressList Property (Outlook)
See also Send feedback

Returns or sets an AddressList object that represents the address list used to evaluate the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddressList

expression A variable that represents a SenderInAddressListRuleCondition object.

Remarks

Returns an error if the AddressList object does not represent an initialized AddressList object.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a SenderInAddressListRuleCondition object.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a SenderInAddressListRuleCondition object.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant, olConditionSenderInAddressBook, from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a SenderInAddressListRuleCondition object.

Remarks

The rule condition that the sender must be in the address list is supported only by rules for receiving messages. For more information, see Specify Rule Conditions.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a SenderInAddressListRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it has been saved successfully.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a SenderInAddressListRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SenderInAddressListRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

SenderInAddressListRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a SenderInAddressListRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SenderInAddressListRuleCondition Object

Other resources

SenderInAddressListRuleCondition Object Members


SendRuleAction Object (Outlook)

 Copy code hover
[image]

SendRuleAction Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents an action that sends a message to one or more recipients.

Version Information

Version Added: Outlook 2007

Remarks

SendRuleAction is derived from the RuleAction object. Each rule is associated with a RuleActions object which has a CC property, a Forward property, a ForwardAsAttachment property, and a Redirect property. Each of these properties always returns a SendRuleAction object. SendRuleAction.ActionType distinguishes among these rule actions. If the rule has any of the above rule actions enabled, then the Enabled property of the corresponding SendRuleAction object would be True.

For more information on specifying rule actions, see Specify Rule Actions.

See also

Concepts

Outlook Object Model Reference

Other resources

SendRuleAction Object Members


SendRuleAction Members (Outlook)

 Copy code hover
[image]

SendRuleAction Members (Outlook)
Send feedback

Represents an action that sends a message to one or more recipients.

Properties

Name | Description
ActionType | Returns a constant, olRuleActionRedirect, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Recipients | Returns a Recipients collection that represents the recipient list for the send action. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SendRuleAction Properties (Outlook)

 Copy code hover
[image]

SendRuleAction Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
ActionType | Returns a constant, olRuleActionRedirect, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule action is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Recipients | Returns a Recipients collection that represents the recipient list for the send action. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SendRuleAction.ActionType Property (Outlook)

 Copy code hover
[image]

SendRuleAction.ActionType Property (Outlook)
See also Send feedback

Returns a constant, olRuleActionRedirect, from the OlRuleActionType enumeration that indicates the type of action that is taken by the rule. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ActionType

expression A variable that represents a SendRuleAction object.

Remarks

The send rule action is supported only by rules for receiving messages. For more information, see Specify Rule Actions.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Application Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a SendRuleAction object.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Class Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a SendRuleAction object.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Enabled Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Enabled Property (Outlook)
See also Send feedback

Returns or sets a Boolean that determines if the rule action is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a SendRuleAction object.

Remarks

After you enable a rule, you must also save the rule by using Rules.Save so that the rule and its enabled state will persist beyond the current session. A rule is only enabled after it has been saved successfully.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Parent Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a SendRuleAction object.

Remarks

The parent object is the RuleAction object.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Recipients Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents the recipient list for the send action. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Recipients

expression A variable that represents a SendRuleAction object.

Remarks

Multiple recipients are evaluated using the logical OR operation.

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SendRuleAction.Session Property (Outlook)

 Copy code hover
[image]

SendRuleAction.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a SendRuleAction object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SendRuleAction Object

Other resources

SendRuleAction Object Members


SharingItem Object (Outlook)

 Copy code hover
[image]

SharingItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a sharing message in an Inbox folder.

Version Information

Version Added: Outlook 2007

Remarks

Use the CreateSharingItem method of the NameSpace object to create a SharingItem object that represents a new sharing request or sharing invitation.

Use Item (index), where index is the index number of a sharing message or a value used to match the default property of a message, to return a single SharingItem object from an Inbox folder.

Example

The following Visual Basic for Applications (VBA) example creates and displays a new sharing invitation for the Tasks folder.

VBA Copy code Copy code
Public Sub CreateTasksSharingItem()

 Dim oNamespace As NameSpace

 Dim oFolder As Folder

 Dim oSharingItem As SharingItem

 On Error GoTo ErrRoutine

 Set oNamespace = Application.GetNamespace("MAPI")

 Set oFolder = oNamespace.GetDefaultFolder(olFolderTasks)

 Set oSharingItem = oNamespace.CreateSharingItem(oFolder)

 oSharingItem.Display

EndRoutine:

 On Error GoTo 0

 Set oSharingItem = Nothing

 Set oFolder = Nothing

 Set oNamespace = Nothing

Exit Sub

ErrRoutine:

 MsgBox Err.Description, _

 vbOKOnly, _

 Err.Number & " - " & Err.Source

 GoTo EndRoutine

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

SharingItem Object Members


SharingItem Members (Outlook)

 Copy code hover
[image]

SharingItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a sharing message in an Inbox folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read.
BeforeAttachmentSave | Occurs before an attachment associated with an instance of the parent object is read.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the SharingItem is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
AddBusinessCard | Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the SharingItem object.
Allow | Allows a sharing request and sends a sharing response to the sender of the SharingItem.
ClearConversationIndex | Clears the index of the conversation thread for the SharingItem.
ClearTaskFlag | Clears the SharingItem object as a task.
Close | Closes and optionally saves changes to the SharingItem.
Copy | Creates another instance of a SharingItem.
Delete | Removes a SharingItem item from the folder that contains the item.
Deny | Denies a sharing request and sends a sharing response to the sender of the SharingItem.
Display | Displays a new Inspector object for the SharingItem.
Forward | Executes the Forward action for an item and returns the resulting copy as a SharingItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a SharingItem object as a task and assigns a task interval for the object.
Move | Moves a SharingItem to a new folder.
OpenSharedFolder | Opens a shared folder offered by a sharing invitation.
PrintOut | Prints the SharingItem using all default settings.
Reply | Creates a reply, pre-addressed to the original sender, from the original SharingItem.
ReplyAll | Creates a reply to all original recipients from the original SharingItem.
Save | Saves the SharingItem to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the SharingItem to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the SharingItem.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the SharingItem. Read-only.
AllowWriteAccess | Returns or sets a Boolean value that indicates whether a sharing invitation should include write access to the folder. Read/write.
AlternateRecipientAllowed | Returns or sets a Boolean value that is True if the item can be forwarded. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the SharingItem. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified SharingItem. Read-only.
AutoForwarded | Returns or sets a Boolean value that is True if the item was automatically forwarded. Read/write.
BCC | Returns a String representing the display list of blind carbon copy (BCC) names for a SharingItem. Read/write.
BillingInformation | Returns or sets a String representing the billing information associated with the SharingItem. Read/write.
Body | Returns or sets a String representing the clear-text body of the SharingItem. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the SharingItem. Read/write.
CC | Returns a String representing the display list of carbon copy (CC) names for a SharingItem. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the SharingItem. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict with the SharingItem. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the SharingItem object belongs to. Read-only.
ConversationIndex | Returns a String representing the index of the conversation thread of the SharingItem. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the SharingItem. Read-only.
CreationTime | Returns a Date indicating the creation time for the SharingItem. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the SharingItem is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the item is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the SharingItem. Read-only.
EntryID | Returns a String representing the unique Entry ID of the SharingItem. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the SharingItem becomes invalid and can be deleted. Read/write.
FlagRequest | Returns or sets a String indicating the requested action for the SharingItem. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified SharingItem. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified SharingItem. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified SharingItem. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the SharingItem. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the SharingItem. Read/write.
IsConflict | Returns a Boolean that determines if the SharingItem is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the SharingItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the SharingItem. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the SharingItem was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the SharingItem. Read/write.
Mileage | Returns or sets a String representing the mileage for a SharingItem. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the SharingItem. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the SharingItem will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for a SharingItem. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for a SharingItem. Read-only.
Parent | Returns the parent Object of the specified SharingItem. Read-only.
Permission | Sets or returns an OlPermission constant that determines what permissions to grant the recipients on the SharingItem. Read/write.
PermissionService | Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a SharingItem protected by Information Rights Management (IRM). Read/write.
PermissionTemplateGuid | Returns or sets a String that represents the GUID of the template file to be applied to the SharingItem in order to specify Information Rights Management (IRM) permissions. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent SharingItem object. Read-only.
ReadReceiptRequested | Returns a Boolean value that indicates true if a read receipt has been requested by the sender.
ReceivedByEntryID | Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the SharingItem. Read-only.
ReceivedByName | Returns a String representing the display name of the true recipient for the SharingItem. Read-only.
ReceivedOnBehalfOfEntryID | Returns a String representing the EntryID of the user delegated to represent the recipient for the SharingItem. Read-only.
ReceivedOnBehalfOfName | Returns a String representing the display name of the user delegated to represent the recipient for the SharingItem. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the SharingItem was received. Read-only.
RecipientReassignmentProhibited | Returns a Boolean that indicates true if the recipient cannot forward the specified SharingItem. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the SharingItem. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the specified SharingItem. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for the specified SharingItem. Read/write.
ReminderSet | Returns or sets a Boolean value that is true if a reminder has been set for the specified SharingItem. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified SharingItem. Read/write.
RemoteID | Returns a String that represents the unique identifier of the sharing context for a SharingItem object. Read-only.
RemoteName | Returns a String that represents the name of the sharing context for a SharingItem object. Read-only.
RemotePath | Returns a String that represents the path of the sharing context for a SharingItem object. Read-only.
RemoteStatus | Returns or sets an OlRemoteStatus constant specifying the remote status of the SharingItem. Read/write.
ReplyRecipientNames | Returns a semicolon-delimited String list of reply recipients for the SharingItem. Read-only.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the SharingItem. Read-only.
RequestedFolder | Returns an OlDefaultFolders constant that represents the type of default folder to which access is requested by a sharing request. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the SharingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is true if the SharingItem has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the SharingItem will be saved after being sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the SharingItem. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the SharingItem, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, and so on. Read-only.
SenderName | Returns a String indicating the display name of the sender for the SharingItem. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the SharingItem is to be sent. Read/write.
Sensitivity | Returns or sets an OlSensitivity constant indicating the sensitivity for the SharingItem. Read/write.
Sent | Returns a Boolean value that indicates if the SharingItem has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the SharingItem was sent. Read-only.
SentOnBehalfOfName | Returns or sets a String indicating the display name for the intended sender of the SharingItem. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
SharingProvider | Returns an OlSharingProvider constant that indicates the sharing provider used by the SharingItem. Read-only.
SharingProviderGuid | Returns a String that represents the GUID of the sharing provider used by the SharingItem object. Read-only.
Size | Returns a Long indicating the size (in bytes) of the SharingItem. Read-only.
Subject | Returns or sets a String indicating the subject for the SharingItem. Read/write.
Submitted | Returns a Boolean value that is True if the SharingItem has been submitted. Read-only.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this SharingItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this SharingItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this SharingItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the SharingItem object. Read/write.
To | Returns or sets a semicolon-delimited String list of display names for the To recipients for the SharingItem. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the SharingItem. Read/write.
Type | Returns or sets an OlSharingMsgType constant that indicates the type of sharing message represented by the SharingItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the SharingItem has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the SharingItem. Read-only.


SharingItem Properties (Outlook)

 Copy code hover
[image]

SharingItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the SharingItem. Read-only.
AllowWriteAccess | Returns or sets a Boolean value that indicates whether a sharing invitation should include write access to the folder. Read/write.
AlternateRecipientAllowed | Returns or sets a Boolean value that is True if the item can be forwarded. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the SharingItem. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified SharingItem. Read-only.
AutoForwarded | Returns or sets a Boolean value that is True if the item was automatically forwarded. Read/write.
BCC | Returns a String representing the display list of blind carbon copy (BCC) names for a SharingItem. Read/write.
BillingInformation | Returns or sets a String representing the billing information associated with the SharingItem. Read/write.
Body | Returns or sets a String representing the clear-text body of the SharingItem. Read/write.
BodyFormat | Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.
Categories | Returns or sets a String representing the categories assigned to the SharingItem. Read/write.
CC | Returns a String representing the display list of carbon copy (CC) names for a SharingItem. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the SharingItem. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict with the SharingItem. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the SharingItem object belongs to. Read-only.
ConversationIndex | Returns a String representing the index of the conversation thread of the SharingItem. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the SharingItem. Read-only.
CreationTime | Returns a Date indicating the creation time for the SharingItem. Read-only.
DeferredDeliveryTime | Returns or sets a Date indicating the date and time the SharingItem is to be delivered. Read/write.
DeleteAfterSubmit | Returns or sets a Boolean value that is True if a copy of the item is not saved upon being sent, and False if a copy is saved. Read/write.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the SharingItem. Read-only.
EntryID | Returns a String representing the unique Entry ID of the SharingItem. Read-only.
ExpiryTime | Returns or sets a Date indicating the date and time at which the SharingItem becomes invalid and can be deleted. Read/write.
FlagRequest | Returns or sets a String indicating the requested action for the SharingItem. Read/write.
FormDescription | Returns the FormDescription object that represents the form description for the specified SharingItem. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified SharingItem. Read-only.
HTMLBody | Returns or sets a String representing the HTML body of the specified SharingItem. Read/write.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the SharingItem. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the SharingItem. Read/write.
IsConflict | Returns a Boolean that determines if the SharingItem is in conflict. Read-only.
IsMarkedAsTask | Returns a Boolean value that indicates whether the SharingItem is marked as a task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the SharingItem. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the SharingItem was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the SharingItem. Read/write.
Mileage | Returns or sets a String representing the mileage for a SharingItem. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the SharingItem. Read/write.
OriginatorDeliveryReportRequested | Returns or sets a Boolean value that determines whether the originator of the SharingItem will receive a delivery report. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for a SharingItem. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for a SharingItem. Read-only.
Parent | Returns the parent Object of the specified SharingItem. Read-only.
Permission | Sets or returns an OlPermission constant that determines what permissions to grant the recipients on the SharingItem. Read/write.
PermissionService | Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a SharingItem protected by Information Rights Management (IRM). Read/write.
PermissionTemplateGuid | Returns or sets a String that represents the GUID of the template file to be applied to the SharingItem in order to specify Information Rights Management (IRM) permissions. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent SharingItem object. Read-only.
ReadReceiptRequested | Returns a Boolean value that indicates true if a read receipt has been requested by the sender.
ReceivedByEntryID | Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the SharingItem. Read-only.
ReceivedByName | Returns a String representing the display name of the true recipient for the SharingItem. Read-only.
ReceivedOnBehalfOfEntryID | Returns a String representing the EntryID of the user delegated to represent the recipient for the SharingItem. Read-only.
ReceivedOnBehalfOfName | Returns a String representing the display name of the user delegated to represent the recipient for the SharingItem. Read-only.
ReceivedTime | Returns a Date indicating the date and time at which the SharingItem was received. Read-only.
RecipientReassignmentProhibited | Returns a Boolean that indicates true if the recipient cannot forward the specified SharingItem. Read/write.
Recipients | Returns a Recipients collection that represents all the recipients for the SharingItem. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the specified SharingItem. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for the specified SharingItem. Read/write.
ReminderSet | Returns or sets a Boolean value that is true if a reminder has been set for the specified SharingItem. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified SharingItem. Read/write.
RemoteID | Returns a String that represents the unique identifier of the sharing context for a SharingItem object. Read-only.
RemoteName | Returns a String that represents the name of the sharing context for a SharingItem object. Read-only.
RemotePath | Returns a String that represents the path of the sharing context for a SharingItem object. Read-only.
RemoteStatus | Returns or sets an OlRemoteStatus constant specifying the remote status of the SharingItem. Read/write.
ReplyRecipientNames | Returns a semicolon-delimited String list of reply recipients for the SharingItem. Read-only.
ReplyRecipients | Returns a Recipients collection that represents all the reply recipient objects for the SharingItem. Read-only.
RequestedFolder | Returns an OlDefaultFolders constant that represents the type of default folder to which access is requested by a sharing request. Read-only.
RetentionExpirationDate | Returns a Date that specifies the date when the SharingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.
RetentionPolicyName | Returns a String that specifies the name of the retention policy. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is true if the SharingItem has not been modified since the last save. Read-only.
SaveSentMessageFolder | Returns or sets a Folder object that represents the folder in which a copy of the SharingItem will be saved after being sent. Read/write.
SenderEmailAddress | Returns a String that represents the e-mail address of the sender of the SharingItem. Read-only.
SenderEmailType | Returns a String that represents the type of entry for the e-mail address of the sender of the SharingItem, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, and so on. Read-only.
SenderName | Returns a String indicating the display name of the sender for the SharingItem. Read-only.
SendUsingAccount | Returns or sets an Account object that represents the account under which the SharingItem is to be sent. Read/write.
Sensitivity | Returns or sets an OlSensitivity constant indicating the sensitivity for the SharingItem. Read/write.
Sent | Returns a Boolean value that indicates if the SharingItem has been sent. Read-only.
SentOn | Returns a Date indicating the date and time on which the SharingItem was sent. Read-only.
SentOnBehalfOfName | Returns or sets a String indicating the display name for the intended sender of the SharingItem. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
SharingProvider | Returns an OlSharingProvider constant that indicates the sharing provider used by the SharingItem. Read-only.
SharingProviderGuid | Returns a String that represents the GUID of the sharing provider used by the SharingItem object. Read-only.
Size | Returns a Long indicating the size (in bytes) of the SharingItem. Read-only.
Subject | Returns or sets a String indicating the subject for the SharingItem. Read/write.
Submitted | Returns a Boolean value that is True if the SharingItem has been submitted. Read-only.
TaskCompletedDate | Returns or sets a Date value that represents the completion date of the task for this SharingItem. Read/write.
TaskDueDate | Returns or sets a Date value that represents the due date of the task for this SharingItem. Read/write.
TaskStartDate | Returns or sets a Date value that represents the start date of the task for this SharingItem object. Read/write.
TaskSubject | Returns or sets a String value that represents the subject of the task for the SharingItem object. Read/write.
To | Returns or sets a semicolon-delimited String list of display names for the To recipients for the SharingItem. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the SharingItem. Read/write.
Type | Returns or sets an OlSharingMsgType constant that indicates the type of sharing message represented by the SharingItem. Read/write.
UnRead | Returns or sets a Boolean value that is True if the SharingItem has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the SharingItem. Read-only.


SharingItem.Actions Property (Outlook)

 Copy code hover
[image]

SharingItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Actions

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AllowWriteAccess Property (Outlook)

 Copy code hover
[image]

SharingItem.AllowWriteAccess Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a sharing invitation should include write access to the folder. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AllowWriteAccess

expression An expression that returns a SharingItem object.

Return Value

True if the recipient of the sharing invitation should receive write access; otherwise False. The default is false.

Remarks

When sending a sharing invitation for a non-default folder, the recipient can be granted write access to the folder in addition to the default read access. This property determines if write permission should be granted to the recipient when the SharingItem is sent.

An error occurs if you attempt to set this property after the sharing message has been sent or received.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AlternateRecipientAllowed Property (Outlook)

 Copy code hover
[image]

SharingItem.AlternateRecipientAllowed Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the item can be forwarded. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AlternateRecipientAllowed

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Application Property (Outlook)

 Copy code hover
[image]

SharingItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Attachments Property (Outlook)

 Copy code hover
[image]

SharingItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Attachments

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AutoForwarded Property (Outlook)

 Copy code hover
[image]

SharingItem.AutoForwarded Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the item was automatically forwarded. Read/write.

Syntax

expression .AutoForwarded

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BCC Property (Outlook)

 Copy code hover
[image]

SharingItem.BCC Property (Outlook)
See also Send feedback

Returns a String representing the display list of blind carbon copy (BCC) names for a SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BCC

expression A variable that represents a SharingItem object.

Remarks

This property contains only the display names, delimited with semicolon (;) characters. The Recipients collection should be used to modify the BCC recipients.

Note Note

If the SharingItem uses an Exchange sharing context, then setting this property to any value other than Nothing prevents the item from being sent and causes the Send method to raise an error.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

SharingItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BillingInformation

expression A variable that represents a SharingItem object.

Remarks

This is a free-form text field.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Body Property (Outlook)

 Copy code hover
[image]

SharingItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Body

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BodyFormat Property (Outlook)

 Copy code hover
[image]

SharingItem.BodyFormat Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlBodyFormat constant indicating the format of the body text. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .BodyFormat

expression A variable that represents a SharingItem object.

Remarks

The body text format determines the standard used to display the text of the message. Microsoft Outlook provides three body text format options: Plain Text, Rich Text (RTF), and HTML.

All text formatting will be lost when the BodyFormat property is switched from RTF to HTML and vice-versa.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Categories Property (Outlook)

 Copy code hover
[image]

SharingItem.Categories Property (Outlook)
See also Send feedback

Returns or sets a String representing the categories assigned to the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Categories

expression A variable that represents a SharingItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.CC Property (Outlook)

 Copy code hover
[image]

SharingItem.CC Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display list of carbon copy (CC) names for a SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .CC

expression A variable that represents a SharingItem object.

Remarks

This property contains only the display names, delimited by semicolon (;) characters. The Recipients collection should be used to modify the CC recipients.

Note Note

If the SharingItem uses an Exchange sharing context, then setting this property to any value other than Nothing prevents the item from being sent and causes the Send method to raise an error.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Class Property (Outlook)

 Copy code hover
[image]

SharingItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a SharingItem object.

Remarks

This property always returns olSharing for the SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Companies Property (Outlook)

 Copy code hover
[image]

SharingItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Companies

expression A variable that represents a SharingItem object.

Remarks

This is a free-form text field.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Conflicts Property (Outlook)

 Copy code hover
[image]

SharingItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict with the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Conflicts

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ConversationID Property (Outlook)

 Copy code hover
[image]

SharingItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the SharingItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a SharingItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the SharingItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

SharingItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the index of the conversation thread of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConversationIndex

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

SharingItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConversationTopic

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.CreationTime Property (Outlook)

 Copy code hover
[image]

SharingItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CreationTime

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.DeferredDeliveryTime Property (Outlook)

 Copy code hover
[image]

SharingItem.DeferredDeliveryTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time the SharingItem is to be delivered. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DeferredDeliveryTime

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagDeferredDeliveryTime.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.DeleteAfterSubmit Property (Outlook)

 Copy code hover
[image]

SharingItem.DeleteAfterSubmit Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a copy of the item is not saved upon being sent, and False if a copy is saved. Read/write.

Syntax

expression .DeleteAfterSubmit

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.DownloadState Property (Outlook)

 Copy code hover
[image]

SharingItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DownloadState

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.EntryID Property (Outlook)

 Copy code hover
[image]

SharingItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .EntryID

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ExpiryTime Property (Outlook)

 Copy code hover
[image]

SharingItem.ExpiryTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the SharingItem becomes invalid and can be deleted. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ExpiryTime

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.FlagRequest Property (Outlook)

 Copy code hover
[image]

SharingItem.FlagRequest Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the requested action for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .FlagRequest

expression A variable that represents a SharingItem object.

Remarks

This is a free-form text field.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.FormDescription Property (Outlook)

 Copy code hover
[image]

SharingItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FormDescription

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.GetInspector Property (Outlook)

 Copy code hover
[image]

SharingItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetInspector

expression A variable that represents a SharingItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.HTMLBody Property (Outlook)

 Copy code hover
[image]

SharingItem.HTMLBody Property (Outlook)
See also Send feedback

Returns or sets a String representing the HTML body of the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HTMLBody

expression A variable that represents a SharingItem object.

Remarks

The HTMLBody property should be an HTML syntax string.

Setting the HTMLBody property sets the EditorType property of the item's Inspector to olEditorHTML.

Setting the HTMLBody property will always update the Body property immediately.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Importance Property (Outlook)

 Copy code hover
[image]

SharingItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Importance

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.InternetCodepage Property (Outlook)

 Copy code hover
[image]

SharingItem.InternetCodepage Property (Outlook)
See also Send feedback

Returns or sets a Long that determines the Internet code page used by the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .InternetCodepage

expression A variable that represents a SharingItem object.

Remarks

The Internet code page defines the text encoding scheme used by the item.

The following table lists the values that are supported by the InternetCodepage property.

Name | Character Set | Code Page
Arabic (ISO) | iso-8859-6 | 28596
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Baltic (Windows) | windows-1257 | 1257
Central European (ISO) | iso-8859-2 | 28592
Central European (Windows) | windows-1250 | 1250
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Simplified (HZ) | hz-gb-2312 | 52936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (ISO) | iso-8859-5 | 28595
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (KOI8-U) | koi8-u | 21866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Greek (Windows) | windows-1253 | 1253
Hebrew (ISO-Logical) | iso-8859-8-i | 38598
Hebrew (Windows) | windows-1255 | 1255
Japanese (EUC) | euc-jp | 51932
Japanese (JIS) | iso-2022-jp | 50220
Japanese (JIS-Allow 1 byte Kana) | csISO2022JP | 50221
Japanese (Shift-JIS) | iso-2022-jp | 932
Korean | ks_c_5601-1987 | 949
Korean (EUC) | euc-kr | 51949
Latin 3 (ISO) | iso-8859-3 | 28593
Latin 9 (ISO) | iso-8859-15 | 28605
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Turkish (Windows) | windows-1254 | 1254
Unicode (UTF-7) | utf-7 | 65000
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591
Western European (Windows) | windows-1252 | 1252

The following table lists the code pages Microsoft recommends that you use for the best compatiblity with older e-mail systems.

Name | Character Set | Code Page
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Central European (ISO) | iso-8859-2 | 28592
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Hebrew (Windows) | windows-1255 | 1255
Japanese (JIS) | iso-2022-jp | 50220
Korean | ks_c_5601-1987 | 949
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.IsConflict Property (Outlook)

 Copy code hover
[image]

SharingItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the SharingItem is in conflict. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsConflict

expression A variable that represents a SharingItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return true.

If true, the specified item is in conflict.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.IsMarkedAsTask Property (Outlook)

 Copy code hover
[image]

SharingItem.IsMarkedAsTask Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the SharingItem is marked as a task. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsMarkedAsTask

expression An expression that returns a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

SharingItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ItemProperties

expression A variable that represents a SharingItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

SharingItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the SharingItem was last modified. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .LastModificationTime

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

SharingItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkForDownload

expression A variable that represents a SharingItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.MessageClass Property (Outlook)

 Copy code hover
[image]

SharingItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MessageClass

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

The default value for this property is IPM.Sharing.

See also

Concepts

SharingItem Object
Item Types and Message Classes

Other resources

SharingItem Object Members


SharingItem.Mileage Property (Outlook)

 Copy code hover
[image]

SharingItem.Mileage Property (Outlook)
See also Send feedback

Returns or sets a String representing the mileage for a SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Mileage

expression A variable that represents a SharingItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.NoAging Property (Outlook)

 Copy code hover
[image]

SharingItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .NoAging

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.OriginatorDeliveryReportRequested Property (Outlook)

 Copy code hover
[image]

SharingItem.OriginatorDeliveryReportRequested Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that determines whether the originator of the SharingItem will receive a delivery report. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .OriginatorDeliveryReportRequested

expression A variable that represents a SharingItem object.

Remarks

Each transport provider that handles your message sends you a single delivery notification containing the names and addresses of each recipient to whom it was delivered. Delivery does not imply that the message has been read. True if the originator requested a delivery receipt on the message.

The OriginatorDeliveryReportRequested property corresponds to the MAPI property PidTagOriginatorDeliveryReportRequested.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

SharingItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Returns a Long representing the build number of the Outlook application for a SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .OutlookInternalVersion

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

SharingItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for a SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .OutlookVersion

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Parent Property (Outlook)

 Copy code hover
[image]

SharingItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a SharingItem object.

Remarks

If the SharingItem was just created, this property returns a Folder object representing the Inbox folder. Otherwise, this property returns a Folder object representing the folder in which the SharingItem was saved.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Permission Property (Outlook)

 Copy code hover
[image]

SharingItem.Permission Property (Outlook)
See also Send feedback

Published: July 16, 2012

Sets or returns an OlPermission constant that determines what permissions to grant the recipients on the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Permission

expression A variable that represents a SharingItem object.

Remarks

The Permission property should be synchronized with the PermissionTemplateGuid property to accurately reflect the permission status of the SharingItem. Setting the PermissionTemplateGuid property to a valid GUID should also incur setting the Permission property to OlPermission.olPermissionTemplate.

When no Information Rights Management (IRM) has been set up (in which case the Permission property is OlPermission.olUnrestricted), or the restriction is not to forward the SharingItem (in which case the Permission property is OlPermission.olDoNotForward), the value of the PermissionTemplateGuid property should be an empty string.

Although you can view content that is protected by IRM on any computer running the 2007 Microsoft Office system or a later version, you must have Microsoft Office Professional Edition 2003, Microsoft Office Outlook 2007, or a later version of Outlook to create or send an e-mail that is protected by IRM.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.PermissionService Property (Outlook)

 Copy code hover
[image]

SharingItem.PermissionService Property (Outlook)
See also Send feedback

Published: July 16, 2012

Sets or returns an OlPermissionService constant that determines the permission service that will be used when sending a SharingItem protected by Information Rights Management (IRM). Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .PermissionService

expression A variable that represents a SharingItem object.

Remarks

This property is useful only if you have more than one permission identity for a particular SMTP address.

While you can view content that is protected by IRM on any computer running the 2007 Microsoft Office system or a later version, you must have Microsoft Office Professional Edition 2003, Microsoft Office Outlook 2007, or a later version of Outlook to create or send an e-mail that is protected by IRM.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.PermissionTemplateGuid Property (Outlook)

 Copy code hover
[image]

SharingItem.PermissionTemplateGuid Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String that represents the GUID of the template file to be applied to the SharingItem in order to specify Information Rights Management (IRM) permissions. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .PermissionTemplateGuid

expression A variable that represents a SharingItem object.

Remarks

This property complements the IRM properties on a SharingItem object; that is, the Permission property and PermissionService properties.

The PermissionTemplateGuid property should be synchronized with the Permission property to accurately reflect the permission status of the SharingItem. Setting the PermissionTemplateGuid property to a valid GUID should also incur setting the Permission property toOlPermission.olPermissionTemplate.

An empty string value for the PermissionTemplateGuid property means there is no permission template file specified for the SharingItem. This occurs when no IRM has been set up (in which case the Permission property is OlPermission.olUnrestricted), or the restriction is not to forward the SharingItem (in which case the Permission property is OlPermission.olDoNotForward).

If you attempt to set the PermissionTemplateGuid property for a received message (that is, the Sent property of the SharingItem is True), Microsoft Outlook returns an error.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

SharingItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent SharingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression An expression that returns a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReadReceiptRequested Property (Outlook)

 Copy code hover
[image]

SharingItem.ReadReceiptRequested Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates true if a read receipt has been requested by the sender.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReadReceiptRequested

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReadReceiptRequested. This property is read/write for SharingItem objects that have been created but have not been sent or posted; it is read-only for sent SharingItem objects.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReceivedByEntryID Property (Outlook)

 Copy code hover
[image]

SharingItem.ReceivedByEntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the EntryID for the true recipient as set by the transport provider delivering the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReceivedByEntryID

expression A variable that represents a MailItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedByEntryId.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReceivedByName Property (Outlook)

 Copy code hover
[image]

SharingItem.ReceivedByName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the true recipient for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReceivedByName

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedByName.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReceivedOnBehalfOfEntryID Property (Outlook)

 Copy code hover
[image]

SharingItem.ReceivedOnBehalfOfEntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the EntryID of the user delegated to represent the recipient for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReceivedOnBehalfOfEntryID

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedRepresentingEntryId.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReceivedOnBehalfOfName Property (Outlook)

 Copy code hover
[image]

SharingItem.ReceivedOnBehalfOfName Property (Outlook)
See also Send feedback

Returns a String representing the display name of the user delegated to represent the recipient for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReceivedOnBehalfOfName

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagReceivedRepresentingName.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReceivedTime Property (Outlook)

 Copy code hover
[image]

SharingItem.ReceivedTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the date and time at which the SharingItem was received. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReceivedTime

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RecipientReassignmentProhibited Property (Outlook)

 Copy code hover
[image]

SharingItem.RecipientReassignmentProhibited Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates true if the recipient cannot forward the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .RecipientReassignmentProhibited

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Recipients Property (Outlook)

 Copy code hover
[image]

SharingItem.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the recipients for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Recipients

expression A variable that represents a SharingItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

SharingItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a SharingItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

SharingItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReminderPlaySound

expression A variable that represents a SharingItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

SharingItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is true if a reminder has been set for the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReminderSet

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

SharingItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReminderSoundFile

expression A variable that represents a SharingItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to true.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

SharingItem.ReminderTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReminderTime

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RemoteID Property (Outlook)

 Copy code hover
[image]

SharingItem.RemoteID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the unique identifier of the sharing context for a SharingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoteID

expression An expression that returns a SharingItem object.

Remarks

This property contains either a GUID or EntryID for the sharing context contained within the SharingItem object.

This property is set to an empty string if the Type property of the SharingItem object is set to olSharingMsgTypeRequest.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RemoteName Property (Outlook)

 Copy code hover
[image]

SharingItem.RemoteName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the name of the sharing context for a SharingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoteName

expression An expression that returns a SharingItem object.

Remarks

This property contains the name used for the sharing context, such as the name of the folder or item, contained within the SharingItem object.

This property is set to an empty string if the Type property of the SharingItem object is set to olSharingMsgTypeRequest.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RemotePath Property (Outlook)

 Copy code hover
[image]

SharingItem.RemotePath Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the path of the sharing context for a SharingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemotePath

expression An expression that returns a SharingItem object.

Remarks

This property contains the path of the sharing context, such as the URL of a WebCal calendar, contained within the SharingItem object.

This property is set to an empty string if the Type property of the SharingItem object is set to olSharingMsgTypeRequest.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RemoteStatus Property (Outlook)

 Copy code hover
[image]

SharingItem.RemoteStatus Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant specifying the remote status of the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .RemoteStatus

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReplyRecipientNames Property (Outlook)

 Copy code hover
[image]

SharingItem.ReplyRecipientNames Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a semicolon-delimited String list of reply recipients for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReplyRecipientNames

expression A variable that represents a SharingItem object.

Remarks

This property only contains the display names for the reply recipients. The reply recipients list should be set by using the ReplyRecipients collection.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReplyRecipients Property (Outlook)

 Copy code hover
[image]

SharingItem.ReplyRecipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the reply recipient objects for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReplyRecipients

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RequestedFolder Property (Outlook)

 Copy code hover
[image]

SharingItem.RequestedFolder Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlDefaultFolders constant that represents the type of default folder to which access is requested by a sharing request. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RequestedFolder

expression An expression that returns a SharingItem object.

Remarks

A SharingItem object that represents a sharing request can only request access to a default folder.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RetentionExpirationDate Property (Outlook)

 Copy code hover
[image]

SharingItem.RetentionExpirationDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date that specifies the date when the SharingItem object expires, after which the Messaging Records Management (MRM) Assistant will delete the item. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionExpirationDate

expression A variable that represents a SharingItem object.

Remarks

A retention policy is enabled and disabled by an administrator for an Exchange Server on a mailbox level. This feature is available only on an Exchange mailbox with MRM version 2.0 or later enabled.

Microsoft Outlook calculates the value of this property based on the item retention start date and the retention period, if Outlook is in cache or offline mode. The Exchange Server specifies the value if Outlook is in online mode.

In general, the retention start date for the item is determined as follows:

  • Received or sent items: the retention start date is the received date.

  • Nonrecurring calendar items: the retention start date is the appointment end date.

  • Recurring calendar items: the retention start date is the end date of last recurrence. If there is no end date, the item never expires.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RetentionPolicyName Property (Outlook)

 Copy code hover
[image]

SharingItem.RetentionPolicyName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that specifies the name of the retention policy. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .RetentionPolicyName

expression A variable that represents a SharingItem object.

Remarks

Retention is enabled and disabled by an administrator for an Exchange Server on a mailbox level. The feature is available only on an Exchange mailbox with Messaging Records Management (MRM), version 2.0 or later enabled. An example of a retention policy name is "Define time interval for expiration Quick Searches".

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.RTFBody Property (Outlook)

 Copy code hover
[image]

SharingItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a SharingItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Saved Property (Outlook)

 Copy code hover
[image]

SharingItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is true if the SharingItem has not been modified since the last save. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Saved

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SaveSentMessageFolder Property (Outlook)

 Copy code hover
[image]

SharingItem.SaveSentMessageFolder Property (Outlook)
See also Send feedback

Returns or sets a Folder object that represents the folder in which a copy of the SharingItem will be saved after being sent. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveSentMessageFolder

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SenderEmailAddress Property (Outlook)

 Copy code hover
[image]

SharingItem.SenderEmailAddress Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the e-mail address of the sender of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SenderEmailAddress

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderEmailAddress.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SenderEmailType Property (Outlook)

 Copy code hover
[image]

SharingItem.SenderEmailType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the type of entry for the e-mail address of the sender of the SharingItem, such as 'SMTP' for Internet address, 'EX' for a Microsoft Exchange server address, and so on. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SenderEmailType

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SenderName Property (Outlook)

 Copy code hover
[image]

SharingItem.SenderName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the display name of the sender for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SenderName

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagSenderName.

If you wish to retrieve the fully qualified e-mail address of the sender, use the SenderEmailAddress property.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SendUsingAccount Property (Outlook)

 Copy code hover
[image]

SharingItem.SendUsingAccount Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an Account object that represents the account under which the SharingItem is to be sent. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SendUsingAccount

expression An expression that returns a SharingItem object.

Remarks

The SendUsingAccount property can be used to specify the account that should be used to send the SharingItem when the Send method is called. This property returns Null (Nothing in Visual Basic) if the SharingItem is a received item, or if the account specified for the SharingItem no longer exists.

This property is read-only if the SharingItem is a received item, or if the SharingItem has already been sent (the Sent property of the object is set to True.)

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

SharingItem.Sensitivity Property (Outlook)
See also Send feedback

Returns or sets an OlSensitivity constant indicating the sensitivity for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Sensitivity

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Sent Property (Outlook)

 Copy code hover
[image]

SharingItem.Sent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates if the SharingItem has been sent. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Sent

expression A variable that represents a SharingItem object.

Remarks

In general, there are three different kinds of messages: sent, posted, and saved. Sent messages are items sent to a recipient or public folder. Posted messages are created in a public folder. Saved messages are created and saved without either sending or posting.

If this property is set to True, attempting to set the SendUsingAccount property raises an error.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SentOn Property (Outlook)

 Copy code hover
[image]

SharingItem.SentOn Property (Outlook)
See also Send feedback

Returns a Date indicating the date and time on which the SharingItem was sent. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SentOn

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagClientSubmitTime. When you send an item using the object's Send method, the transport provider sets the ReceivedTime and SentOn properties for you.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SentOnBehalfOfName Property (Outlook)

 Copy code hover
[image]

SharingItem.SentOnBehalfOfName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the display name for the intended sender of the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SentOnBehalfOfName

expression An expression that returns a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagSentRepresentingName.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Session Property (Outlook)

 Copy code hover
[image]

SharingItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a SharingItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SharingProvider Property (Outlook)

 Copy code hover
[image]

SharingItem.SharingProvider Property (Outlook)
See also Send feedback

Returns an OlSharingProvider constant that indicates the sharing provider used by the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SharingProvider

expression An expression that returns a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SharingProviderGuid Property (Outlook)

 Copy code hover
[image]

SharingItem.SharingProviderGuid Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the GUID of the sharing provider used by the SharingItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SharingProviderGuid

expression An expression that returns a SharingItem object.

Remarks

The GUID is returned as a string using the following format:

Copy code Copy code
{00000000-0000-0000-0000-000000000000}

If the SharingProvider property of the SharingItem object is set to olProviderUnknown, you can use the SharingProviderGUID property to identify the sharing provider.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Size Property (Outlook)

 Copy code hover
[image]

SharingItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Size

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Subject Property (Outlook)

 Copy code hover
[image]

SharingItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Subject

expression A variable that represents a SharingItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Submitted Property (Outlook)

 Copy code hover
[image]

SharingItem.Submitted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the SharingItem has been submitted. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Submitted

expression A variable that represents a SharingItem object.

Remarks

A message is always created and submitted in a folder, usually the Outbox.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.TaskCompletedDate Property (Outlook)

 Copy code hover
[image]

SharingItem.TaskCompletedDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the completion date of the task for this SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskCompletedDate

expression An expression that returns a SharingItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.TaskDueDate Property (Outlook)

 Copy code hover
[image]

SharingItem.TaskDueDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the due date of the task for this SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskDueDate

expression An expression that returns a SharingItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.TaskStartDate Property (Outlook)

 Copy code hover
[image]

SharingItem.TaskStartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the start date of the task for this SharingItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskStartDate

expression An expression that returns a SharingItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.TaskSubject Property (Outlook)

 Copy code hover
[image]

SharingItem.TaskSubject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the subject of the task for the SharingItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TaskSubject

expression An expression that returns a SharingItem object.

Remarks

This property returns the value of the Subject property if the IsMarkedAsTask property is set to False.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.To Property (Outlook)

 Copy code hover
[image]

SharingItem.To Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a semicolon-delimited String list of display names for the To recipients for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .To

expression A variable that represents a SharingItem object.

Remarks

This property contains the display names only. The To property corresponds to the MAPI property PidTagDisplayTo. The Recipients collection should be used to modify this property.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

SharingItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the ordinal value of the task for the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a SharingItem object.

Remarks

This property returns Null (Nothing in Visual Basic) if the IsMarkedAsTask property is set to False.

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar. The value used in this property does not have any relation to the values of the TaskStartDate, TaskDueDate, or TaskCompletedDate properties.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Type Property (Outlook)

 Copy code hover
[image]

SharingItem.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlSharingMsgType constant that indicates the type of sharing message represented by the SharingItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Type

expression An expression that returns a SharingItem object.

Remarks

An error occurs if you attempt to set this property after the sharing message has been sent or received, or if you attempt to set this property to olSharingMsgTypeResponseAllow or olSharingMsgTypeResponseDeny.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.UnRead Property (Outlook)

 Copy code hover
[image]

SharingItem.UnRead Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the SharingItem has not been opened (read). Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .UnRead

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.UserProperties Property (Outlook)

 Copy code hover
[image]

SharingItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the SharingItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .UserProperties

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem Methods (Outlook)

 Copy code hover
[image]

SharingItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddBusinessCard | Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the SharingItem object.
Allow | Allows a sharing request and sends a sharing response to the sender of the SharingItem.
ClearConversationIndex | Clears the index of the conversation thread for the SharingItem.
ClearTaskFlag | Clears the SharingItem object as a task.
Close | Closes and optionally saves changes to the SharingItem.
Copy | Creates another instance of a SharingItem.
Delete | Removes a SharingItem item from the folder that contains the item.
Deny | Denies a sharing request and sends a sharing response to the sender of the SharingItem.
Display | Displays a new Inspector object for the SharingItem.
Forward | Executes the Forward action for an item and returns the resulting copy as a SharingItem object.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
MarkAsTask | Marks a SharingItem object as a task and assigns a task interval for the object.
Move | Moves a SharingItem to a new folder.
OpenSharedFolder | Opens a shared folder offered by a sharing invitation.
PrintOut | Prints the SharingItem using all default settings.
Reply | Creates a reply, pre-addressed to the original sender, from the original SharingItem.
ReplyAll | Creates a reply to all original recipients from the original SharingItem.
Save | Saves the SharingItem to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the SharingItem to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the SharingItem.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


SharingItem.AddBusinessCard Method (Outlook)

 Copy code hover
[image]

SharingItem.AddBusinessCard Method (Outlook)
See also Send feedback

Appends contact information based on the Electronic Business Card (EBC) associated with the specified ContactItem object to the SharingItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AddBusinessCard(contact)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
contact | Required | ContactItem | The contact item from which to obtain the business card information.

Remarks

This method adds contact information, generated from the information stored in the ContactItem object, to the existing SharingItem object. The information included depends on the value of the BodyFormat property for the SharingItem object:

Property value | Result
olFormatPlain | A vCard (.vcf) file is created and added to the Attachments collection of the SharingItem object.
olFormatRichText | A vCard (.vcf) file is created and added to the Attachments collection of the SharingItem object.
olFormatHTML | An image of the business card is generated and included in the Body property of the SharingItem object, and a vCard (.vcf) file is created and added to the Attachments collection of the SharingItem object.
Note Note

The attached vCard file contains only the contact information included in the Electronic Business Card associated with the ContactItem object. Any contact information not displayed in the Electronic Business Card is excluded from the vCard file.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Allow Method (Outlook)

 Copy code hover
[image]

SharingItem.Allow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Allows a sharing request and sends a sharing response to the sender of the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Allow

expression An expression that returns a SharingItem object.

Remarks

The Allow method can only be called on SharingItem objects with a Type property value of olSharingMsgTypeRequest or olSharingMsgTypeInviteAndRequest.

The Type property of the sharing response sent when this method is called is set to olSharingMsgTypeResponseAllow.

Note Note

Sharing is allowed immediately after this method is called, regardless of whether the sharing response was received.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ClearConversationIndex Method (Outlook)

 Copy code hover
[image]

SharingItem.ClearConversationIndex Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the index of the conversation thread for the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearConversationIndex

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ClearTaskFlag Method (Outlook)

 Copy code hover
[image]

SharingItem.ClearTaskFlag Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the SharingItem object as a task.

Version Information

Version Added: Outlook 2007

Syntax

expression .ClearTaskFlag

expression An expression that returns a SharingItem object.

Remarks

Calling this method sets the IsMarkedAsTask property to False.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Close Method (Outlook)

 Copy code hover
[image]

SharingItem.Close Method (Outlook)
See also Send feedback

Closes and optionally saves changes to the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Close(SaveMode)

expression A variable that represents a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Copy Method (Outlook)

 Copy code hover
[image]

SharingItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of a SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Delete Method (Outlook)

 Copy code hover
[image]

SharingItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes a SharingItem item from the folder that contains the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a SharingItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

SharingItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

SharingItem Object Members


SharingItem.Deny Method (Outlook)

 Copy code hover
[image]

SharingItem.Deny Method (Outlook)
See also Send feedback

Published: July 16, 2012

Denies a sharing request and sends a sharing response to the sender of the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Deny

expression An expression that returns a SharingItem object.

Return Value

A SharingItem object that represents the sharing response.

Remarks

The Deny method can only be called on SharingItem objects with a Type property value of olSharingMsgTypeRequest or olSharingMsgTypeInviteAndRequest.

This method generates a new SharingItem object and sets the Type property of the new object to olSharingMsgTypeResponseDeny. The SharingItem is not immediately sent to the sender of the sharing request, however, so you can edit the sharing response as needed.

Note Note

Sharing is denied immediately after this method is called, regardless of whether the sharing response was received.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Display Method (Outlook)

 Copy code hover
[image]

SharingItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Display(Modal)

expression A variable that represents a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Forward Method (Outlook)

 Copy code hover
[image]

SharingItem.Forward Method (Outlook)
See also Send feedback

Published: July 16, 2012

Executes the Forward action for an item and returns the resulting copy as a SharingItem object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Forward

expression A variable that represents a SharingItem object.

Return Value

A SharingItem object that represents the new sharing invitation.

Remarks

An error occurs if this method is called on sharing invitations using an Exchange sharing context or on sharing requests.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.GetConversation Method (Outlook)

 Copy code hover
[image]

SharingItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a SharingItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.MarkAsTask Method (Outlook)

 Copy code hover
[image]

SharingItem.MarkAsTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Marks a SharingItem object as a task and assigns a task interval for the object.

Version Information

Version Added: Outlook 2007

Syntax

expression .MarkAsTask(MarkInterval)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
MarkInterval | Required | OlMarkInterval | The task interval for the SharingItem.

Remarks

Calling this method sets the IsMarkedAsTask property to True and updates the TaskStartDate, TaskDueDate, and TaskOrdinal properties depending on the value provided in MarkInterval.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Move Method (Outlook)

 Copy code hover
[image]

SharingItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a SharingItem to a new folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .Move(DestFldr)

expression A variable that represents a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item that has been moved to the designated folder.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.OpenSharedFolder Method (Outlook)

 Copy code hover
[image]

SharingItem.OpenSharedFolder Method (Outlook)
See also Send feedback

Opens a shared folder offered by a sharing invitation.

Version Information

Version Added: Outlook 2007

Syntax

expression .OpenSharedFolder

expression An expression that returns a SharingItem object.

Return Value

A Folder object that represents the shared folder.

Remarks

This method allows the recipient of a sharing invitation to open the shared folder offered by the sender. An error occurs if this method is called on a SharingItem object with a Type property value other than olSharingMsgTypeInvite or olSharingMsgTypeInviteAndRequest, or if Outlook cannot connect to the shared folder.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.PrintOut Method (Outlook)

 Copy code hover
[image]

SharingItem.PrintOut Method (Outlook)
See also Send feedback

Prints the SharingItem using all default settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .PrintOut

expression A variable that represents a MailItem object.

Remarks

The PrintOut method is the only Outlook method that can be used for printing.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Reply Method (Outlook)

 Copy code hover
[image]

SharingItem.Reply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a reply, pre-addressed to the original sender, from the original SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reply

expression A variable that represents a SharingItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReplyAll Method (Outlook)

 Copy code hover
[image]

SharingItem.ReplyAll Method (Outlook)
See also Send feedback

Creates a reply to all original recipients from the original SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReplyAll

expression A variable that represents a SharingItem object.

Return Value

A MailItem object that represents the reply.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Save Method (Outlook)

 Copy code hover
[image]

SharingItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the SharingItem to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.SaveAs Method (Outlook)

 Copy code hover
[image]

SharingItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the SharingItem to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()

 Dim myItem As Outlook.Inspector

 Dim objItem As Object

 Set myItem = Application.ActiveInspector

 If Not TypeName(myItem) = "Nothing" Then

 Set objItem = myItem.CurrentItem

 strname = objItem.Subject

 'Prompt the user for confirmation

 Dim strPrompt As String

 strPrompt = "Are you sure you want to save the item? " & _

 "If a file with the same name already exists, " & _

 "it will be overwritten with this copy of the file."

 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then

 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT

 End If

 Else

 MsgBox "There is no current active inspector."

 End If

End Sub

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Send Method (Outlook)

 Copy code hover
[image]

SharingItem.Send Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends the SharingItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Send

expression A variable that represents a SharingItem object.

Remarks

The Send method sends an item using the default account specified for the session. In a session where multiple Microsoft Exchange accounts are defined in the profile, the first Exchange account added to the profile is the primary Exchange account, and is also the default account for the session. To specify a different account to send an item, set the SendUsingAccount property to the desired Account object and then call the Send method.

Certain sharing providers may have restrictions on the type of recipients allowed. When this method is called, some providers will attempt to set access control list (ACL) entries on the folder for each recipient included in the SharingItem. If an error occurs while attempting to set ACLs for any recipient, this method raises an error and the SharingItem is not sent to any of the recipients.

An error occurs if the BCC or CC properties are set for a SharingItem using an Exchange sharing context.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

SharingItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a SharingItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem Events (Outlook)

 Copy code hover
[image]

SharingItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read.
BeforeAttachmentSave | Occurs before an attachment associated with an instance of the parent object is read.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the SharingItem is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.
ReplyAll | Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


SharingItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

SharingItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a SharingItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

SharingItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentAdd(Attachment)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

SharingItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRead(Attachment)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

SharingItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be saved.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the SharingItem is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the SharingItem to be saved.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeCheckNames(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeDelete(Item, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when a sharing message is deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

SharingItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a SharingItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Close Event (Outlook)

 Copy code hover
[image]

SharingItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Version Information

Version Added: Outlook 2007

Syntax

expression .Close(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.CustomAction Event (Outlook)

 Copy code hover
[image]

SharingItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Version Information

Version Added: Outlook 2007

Syntax

expression .CustomAction(Action, Response, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

SharingItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Version Information

Version Added: Outlook 2007

Syntax

expression .CustomPropertyChange(Name)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Forward Event (Outlook)

 Copy code hover
[image]

SharingItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item, or when the Forward method is called for the item, which is an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Forward(Forward, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Open Event (Outlook)

 Copy code hover
[image]

SharingItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Version Information

Version Added: Outlook 2007

Syntax

expression .Open(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

SharingItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyChange(Name)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Read Event (Outlook)

 Copy code hover
[image]

SharingItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Version Information

Version Added: Outlook 2007

Syntax

expression .Read

expression An expression that returns a SharingItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

SharingItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a SharingItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Reply Event (Outlook)

 Copy code hover
[image]

SharingItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item, or when the Reply method is called for the item, which is an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reply(Response, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

SharingItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item, or when the ReplyAll method is called for the item, which is an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .ReplyAll(Response, Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Send Event (Outlook)

 Copy code hover
[image]

SharingItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Send(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Unload Event (Outlook)

 Copy code hover
[image]

SharingItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression An expression that returns a SharingItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SharingItem.Write Event (Outlook)

 Copy code hover
[image]

SharingItem.Write Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Version Information

Version Added: Outlook 2007

Syntax

expression .Write(Cancel)

expression An expression that returns a SharingItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

SharingItem Object

Other resources

SharingItem Object Members


SimpleItems Object (Outlook)

 Copy code hover
[image]

SimpleItems Object (Outlook)
See also Send feedback

Represents a set of possibly heterogeneous Microsoft Outlook items, with each member in the set tracking only a small, common set of properties that apply to Outlook items in general.

Version Information

Version Added: Outlook 2010

Remarks

The SimpleItems collection is used to represent child objects of a Conversation node object. This collection has only few members and serves the purpose of providing easy access to these items, as opposed to the Items and Results collections, which have more members.

The order of items in the collection is the same as the ordering of items in the conversation. The collection is ordered by the value of the CreationTime property of each item in ascending order.

Example

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code example assumes that the selected item in the explorer window is a mail item. The example obtains the conversation that the selected mail item is associated with, and enumerates each item in that conversation, displaying the subject of the item. The DemoConversation method calls the GetConversation method of the selected mail item to obtain the associated Conversation object. DemoConversation then calls the GetTable and GetRootItems methods of the Conversation object to obtain a Table object and SimpleItems collection, respectively. DemoConversation calls the recurrent method EnumerateConversation to enumerate and display the subject of each item in that conversation.

C# Copy code Copy code
void DemoConversation()
{
 object selectedItem =
 Application.ActiveExplorer().Selection[1];
 // This example uses only
 // MailItem. Other item types such as
 // MeetingItem and PostItem can participate
 // in the conversation.
 if (selectedItem is Outlook.MailItem)
 {
 // Cast selectedItem to MailItem.
 Outlook.MailItem mailItem =
 selectedItem as Outlook.MailItem;
 // Determine the store of the mail item.
 Outlook.Folder folder = mailItem.Parent
 as Outlook.Folder;
 Outlook.Store store = folder.Store;
 if (store.IsConversationEnabled == true)
 {
 // Obtain a Conversation object.
 Outlook.Conversation conv =
 mailItem.GetConversation();
 // Check for null Conversation.
 if (conv != null)
 {
 // Obtain Table that contains rows
 // for each item in the conversation.
 Outlook.Table table = conv.GetTable();
 Debug.WriteLine("Conversation Items Count: " +
 table.GetRowCount().ToString());
 Debug.WriteLine("Conversation Items from Table:");
 while (!table.EndOfTable)
 {
 Outlook.Row nextRow = table.GetNextRow();
 Debug.WriteLine(nextRow["Subject"]
 + " Modified: "
 + nextRow["LastModificationTime"]);
 }
 Debug.WriteLine("Conversation Items from Root:");
 // Obtain root items and enumerate the conversation.
 Outlook.SimpleItems simpleItems
 = conv.GetRootItems();
 foreach (object item in simpleItems)
 {
 // In this example, enumerate only MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (item is Outlook.MailItem)
 {
 Outlook.MailItem mail = item
 as Outlook.MailItem;
 Outlook.Folder inFolder =
 mail.Parent as Outlook.Folder;
 string msg = mail.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Call EnumerateConversation
 // to access child nodes of root items.
 EnumerateConversation(item, conv);
 }
 }
 }
 }
}

void EnumerateConversation(object item,
 Outlook.Conversation conversation)
{
 Outlook.SimpleItems items =
 conversation.GetChildren(item);
 if (items.Count > 0)
 {
 foreach (object myItem in items)
 {
 // In this example, enumerate only MailItem type.
 // Other types such as PostItem or MeetingItem
 // can appear in the conversation.
 if (myItem is Outlook.MailItem)
 {
 Outlook.MailItem mailItem =
 myItem as Outlook.MailItem;
 Outlook.Folder inFolder =
 mailItem.Parent as Outlook.Folder;
 string msg = mailItem.Subject
 + " in folder " + inFolder.Name;
 Debug.WriteLine(msg);
 }
 // Continue recursion.
 EnumerateConversation(myItem, conversation);
 }
 }
}

See also

Concepts

Outlook Object Model Reference
How to: Obtain and Enumerate Selected Conversations

Other resources

SimpleItems Object Members


SimpleItems Members (Outlook)

 Copy code hover
[image]

SimpleItems Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a set of possibly heterogeneous Microsoft Outlook items, with each member in the set tracking only a small, common set of properties that apply to Outlook items in general.

Methods

Name | Description
Item | Returns an item in the SimpleItems collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Microsoft Outlook application for the SimpleItems object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
Count | Returns a Long that indicates the count of objects in the SimpleItems collection. Read-only.
Parent | Returns the parent Object of the SimpleItems object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SimpleItems Properties (Outlook)

 Copy code hover
[image]

SimpleItems Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Microsoft Outlook application for the SimpleItems object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
Count | Returns a Long that indicates the count of objects in the SimpleItems collection. Read-only.
Parent | Returns the parent Object of the SimpleItems object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SimpleItems.Application Property (Outlook)

 Copy code hover
[image]

SimpleItems.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Microsoft Outlook application for the SimpleItems object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Application

expression A variable that represents a SimpleItems object.

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SimpleItems.Class Property (Outlook)

 Copy code hover
[image]

SimpleItems.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that indicates the object's class. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Class

expression A variable that represents a SimpleItems object.

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SimpleItems.Count Property (Outlook)

 Copy code hover
[image]

SimpleItems.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long that indicates the count of objects in the SimpleItems collection. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Count

expression A variable that represents a SimpleItems object.

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SimpleItems.Parent Property (Outlook)

 Copy code hover
[image]

SimpleItems.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the SimpleItems object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Parent

expression A variable that represents a SimpleItems object.

Remarks

The parent object of a SimpleItems object is a Conversation object.

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SimpleItems.Session Property (Outlook)

 Copy code hover
[image]

SimpleItems.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Session

expression A variable that represents a SimpleItems object.

Remarks

This property returns Null (Nothing in Visual Basic) if there is no logged-on session.

You can use the Session property and the GetNamespace method interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SimpleItems Methods (Outlook)

 Copy code hover
[image]

SimpleItems Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns an item in the SimpleItems collection.


SimpleItems.Item Method (Outlook)

 Copy code hover
[image]

SimpleItems.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an item in the SimpleItems collection.

Version Information

Version Added: Outlook 2010

Syntax

expression .Item(Index)

expression A variable that represents a SimpleItems object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The zero-based index number of the object in the SimpleItems collection.

Return Value

An Object that represents an Outlook item in the SimpleItems collection.

Remarks

If this method fails to return an object in the collection as specified by the Index parameter, the method returns Null (Nothing in Visual Basic).

See also

Concepts

SimpleItems Object

Other resources

SimpleItems Object Members


SolutionsModule Object (Outlook)

 Copy code hover
[image]

SolutionsModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the Solutions navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2010

Remarks

The Solutions navigation module contains folders that developers of individual add-ins want to expose to users in the Navigation Pane. Each solution has one root folder under the Solutions module, and each root folder can contain subfolders that hold heterogeneous Outlook items.

To add solution folders programmatically to the Solutions module, use the SolutionsModule object, which is derived from the NavigationModule object.

To obtain an object for the Solutions module, you must first determine whether the Solutions module exists in the Navigation Pane. To do that, use the Modules property for the NavigationPane object to obtain a NavigationModules collection, and then specify the argument olModuleSolutions in the GetNavigationModule method of the NavigationModules collection.

If the call is successful, you can then cast the returned NavigationModule object reference as a SolutionsModule object to access the properties and methods for that navigation module.

To add a solution root folder and its subfolders, pass a Folder object reference to the AddSolution method of the SolutionsModule object. The default position of the Solutions module on the Navigation Pane is '9'.

If no solutions have been added to the Solutions module, it is not visible in the Navigation Pane, and any attempt to set the Position or the Visible properties of the SolutionsModule object raises an error. In addition, any attempt to set the SolutionsModule as the CurrentModule property of the NavigationPane object raises an error.

Example

To see an example of an add-in that adds folders to the Solutions module, see the article Programming the Outlook 2010 Solutions Module on MSDN. The add-in in the article renames the Solutions module as Solution Demo, adds calendar, contacts, and tasks folders as subfolders to the solution root folder, sets custom icons for each of the subfolders, and customizes the Navigation Pane to move and enlarge the button for the Solution Demo module.

See also

Concepts

Outlook Object Model Reference

Other resources

SolutionsModule Object Members


SolutionsModule Members (Outlook)

 Copy code hover
[image]

SolutionsModule Members (Outlook)
Send feedback

Represents the Solutions navigation module in the Navigation Pane of an explorer.

Methods

Name | Description
AddSolution | Adds a solution root folder and its subfolders to the Solutions module.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the SolutionsModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the SolutionsModule object. Read-only.
Parent | Returns the parent Object of the specified SolutionsModule object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the SolutionsModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that indicates whether the Solutions module is displayed in the Navigation Pane. Read/write.


SolutionsModule Properties (Outlook)

 Copy code hover
[image]

SolutionsModule Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that indicates the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the SolutionsModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the SolutionsModule object. Read-only.
Parent | Returns the parent Object of the specified SolutionsModule object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the SolutionsModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that indicates whether the Solutions module is displayed in the Navigation Pane. Read/write.


SolutionsModule.Application Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Application

expression A variable that represents a SolutionsModule object.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Class Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant that indicates the object's class. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Class

expression A variable that represents a SolutionsModule object.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Name Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the SolutionsModule object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Name

expression A variable that represents a SolutionsModule object.

Remarks

The display name of the Solutions module can be customized if there is only one solution root folder under the Solutions module. If there are multiple solution root folders, the name reverts back to Solutions.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

SolutionsModule.NavigationModuleType Property (Outlook)
See also Send feedback

Returns an OlNavigationModuleType constant that represents the navigation module type for the SolutionsModule object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .NavigationModuleType

expression A variable that represents a SolutionsModule object.

Remarks

For the SolutionsModule object, this property returns the value olModuleSolutions.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Parent Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified SolutionsModule object. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Parent

expression A variable that represents a SolutionsModule object.

Remarks

The parent of a SolutionsModule object returns a NavigationPane object.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Position Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the SolutionsModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Position

expression A variable that represents a SolutionsModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range. If no solutions exist in the Solutions module, setting or getting the Position property also raises an error.

Changing the value of this property for a given SolutionsModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified SolutionsModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified SolutionsModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Session Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Session

expression A variable that represents a SolutionsModule object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function.

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule.Visible Property (Outlook)

 Copy code hover
[image]

SolutionsModule.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the Solutions module is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Visible

expression A variable that represents a SolutionsModule object.

Remarks

If there are no solutions under the Solutions module, setting or getting the Visible property raises an error.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


SolutionsModule Methods (Outlook)

 Copy code hover
[image]

SolutionsModule Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
AddSolution | Adds a solution root folder and its subfolders to the Solutions module.


SolutionsModule.AddSolution Method (Outlook)

 Copy code hover
[image]

SolutionsModule.AddSolution Method (Outlook)
See also Send feedback

Adds a solution root folder and its subfolders to the Solutions module.

Version Information

Version Added: Outlook 2010

Syntax

expression .AddSolution(Solution, Scope)

expression A variable that represents a SolutionsModule object.

Parameters

Name | Required/Optional | Data Type | Description
Solution | Required | Folder | Specifies the solution root folder to add to the Solutions module.
Scope | Required | OlSolutionScope | Specifies whether to display the folders that are in the solution only in the Solutions module and the Folder List, or to display them in their respective default modules in the Navigation Pane as well.

Remarks

If the AddSolution method succeeds and no solution root folder previously existed under the Solutions module, Microsoft Outlook displays the Solutions module in the NavigationPane.

You cannot add the following folders to the Solutions module as a solution root folder:

  • A folder that Outlook displays on the Navigation Pane, as defined by the OlDefaultFolders enumeration.

  • A special folder, as defined by the OlSpecialFolders enumeration.

  • Any folder on a Microsoft Exchange Server public folder store. The ExchangeStoreType property on the Store object for this folder is olExchangePublicFolder.

  • A hidden folder. A hidden folder is one whose MAPI property, PR_ATTR_HIDDEN, is True or one that is not in the IPM Subtree.

This method also returns an error if the folder that you specify already exists as a root folder or a subfolder in the Solutions module, or if the folder is a parent folder of a folder in the Solutions module.

If the Scope parameter is set to olShowInDefaultModules of the OlSolutionScope enumeration, the solution root and its subfolders are displayed in their respective default modules as well as the Solutions module. If the Scope parameter is set to olHideInDefaultModules, the solution root and its subfolders are displayed in the Solutions module.

Solution folders are always displayed in the Folder List module.

By default, Outlook displays the Solutions module after the Tasks module, provided that the navigation modules are in the default order - Mail, Calendar, Contacts, and Tasks. If the Navigation Pane is expanded, the Solutions module is also initially displayed as an expanded module. If the Tasks module is not displayed, the Solutions module is displayed after the last expanded module in the Navigation Pane.

See also

Concepts

SolutionsModule Object

Other resources

SolutionsModule Object Members


StorageItem Object (Outlook)

 Copy code hover
[image]

StorageItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

A message object in MAPI that is always saved as a hidden item in the parent folder and stores private data for Outlook solutions.

Version Information

Version Added: Outlook 2007

Remarks

A StorageItem object is stored at the folder level, allowing it to roam with the account and be available online or offline.

The Outlook object model does not provide any collection object for StorageItem objects. However, you can use Folder.GetTable to obtain a Table with all the hidden items in a Folder, when you specify the TableContents parameter as olHiddenItems. If keeping your data private is of a high concern, you should encrypt the data before storing it.

Once you have obtained a StorageItem object, you can do the following to store solution data:

  • Add attachments to the item for storage.

  • Use explicit built-in properties of the item such as Body to store custom data.

  • Add custom properties to the item using UserProperties.Add method. Note that in this case, the optional AddToFolderFields and DisplayFormat arguments of the UserProperties.Add method will be ignored.

  • Use the PropertyAccessor object to get or set custom properties.

The default message class for a new StorageItem is IPM.Storage. If the StorageItem existed as a hidden message in a version of Outlook prior to Microsoft Office Outlook 2007, the message class will remain unchanged. In order to prevent modification of the message class, StorageItem does not expose an explicit MessageClass property.

For more information on storing solution data using the StorageItem object, see Storing Data for Solutions.

Example

The following code sample in Visual Basic for Applications shows how to use the StorageItem object to store private solution data. It saves the data in a custom property of a StorageItem object in the Inbox folder. The following describes the steps.

  1. The code sample calls Folder.GetStorage to obtain an existing StorageItem object that has the subject "My Private Storage" in the Inbox. If no StorageItem with that subject already exists, GetStorage creates a StorageItem object with that subject.

  2. If the StorageItem is newly created, the code sample creates a custom property "Order Number" for the object. Note that "Order Number" is a property of a hidden item in the Inbox.

  3. The code sample then assigns a value to "Order Number" and saves the StorageItem object.

VBA Copy code Copy code
Sub AssignStorageData()

 Dim oInbox As Outlook.Folder

 Dim myStorage As Outlook.StorageItem

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 ' Get an existing instance of StorageItem, or create new if it doesn't exist

 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 ' If StorageItem is new, add a custom property for Order Number

 If myStorage.Size = 0 Then

 myStorage.UserProperties.Add "Order Number", olNumber

 End If

 ' Assign a value to the custom property

 myStorage.UserProperties("Order Number").Value = 100

 myStorage.Save

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

StorageItem Object Members


StorageItem Members (Outlook)

 Copy code hover
[image]

StorageItem Members (Outlook)
Send feedback

Published: July 16, 2012

A message object in MAPI that is always saved as a hidden item in the parent folder and stores private data for Outlook solutions.

Methods

Name | Description
Delete | Permanently removes the StorageItem object from the parent folder.
Save | Saves the StorageItem.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CreationTime | Returns a DateTime value that indicates the creation time for the StorageItem. Read-only.
Creator | Returns and sets the solution that created the StorageItem object. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
LastModificationTime | Returns a DateTime value specifying the date and time that the Outlook item was last modified. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent StorageItem object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the StorageItem. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


StorageItem Properties (Outlook)

 Copy code hover
[image]

StorageItem Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
CreationTime | Returns a DateTime value that indicates the creation time for the StorageItem. Read-only.
Creator | Returns and sets the solution that created the StorageItem object. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
LastModificationTime | Returns a DateTime value specifying the date and time that the Outlook item was last modified. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent StorageItem object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the StorageItem. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


StorageItem.Application Property (Outlook)

 Copy code hover
[image]

StorageItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a StorageItem object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Attachments Property (Outlook)

 Copy code hover
[image]

StorageItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Attachments

expression A variable that represents a StorageItem object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Body Property (Outlook)

 Copy code hover
[image]

StorageItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Body

expression A variable that represents a StorageItem object.

Remarks

StorageItem objects only support the item body in text format. They do not support HTML or RTF body streams.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Class Property (Outlook)

 Copy code hover
[image]

StorageItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a StorageItem object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.CreationTime Property (Outlook)

 Copy code hover
[image]

StorageItem.CreationTime Property (Outlook)
See also Send feedback

Returns a DateTime value that indicates the creation time for the StorageItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CreationTime

expression A variable that represents a StorageItem object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Creator Property (Outlook)

 Copy code hover
[image]

StorageItem.Creator Property (Outlook)
See also Send feedback

Returns and sets the solution that created the StorageItem object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Creator

expression A variable that represents a StorageItem object.

Remarks

Outlook does not set the Creator property. Use the Creator property to identify the StorageItem objects you have created for your add-in. One recomended value for this property is the programmatic identifier (ProgID) of the add-in.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.EntryID Property (Outlook)

 Copy code hover
[image]

StorageItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .EntryID

expression A variable that represents a StorageItem object.

Remarks

The EntryID is one of the three means to identify a StorageItem object using Folder.GetStorage.

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

StorageItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a DateTime value specifying the date and time that the Outlook item was last modified. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .LastModificationTime

expression A variable that represents a StorageItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Parent Property (Outlook)

 Copy code hover
[image]

StorageItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a StorageItem object.

Remarks

The parent of the StorageItem object is the Folder object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

StorageItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent StorageItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a StorageItem object.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Session Property (Outlook)

 Copy code hover
[image]

StorageItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a StorageItem object.

Remarks

Returns Null (Nothing in Visual Basic) if there is no logged-on session.

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Size Property (Outlook)

 Copy code hover
[image]

StorageItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the StorageItem. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Size

expression A variable that represents a StorageItem object.

Remarks

The Size of a StorageItem that is newly created is zero (0) until you make an explicit call on the Save method of the item.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Subject Property (Outlook)

 Copy code hover
[image]

StorageItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Subject

expression A variable that represents a StorageItem object.

Remarks

This property corresponds to the MAPI property, PidTagSubject. The Subject property is the default property for Outlook items.

The Subject serves as a unique identifier for StorageItem objects. You should set the subject in a way to ensure that the objects are unique and would not be overwritten by other solution writers. The recommended practice is to use a ProgID plus other unique text to identify the StorageItem.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.UserProperties Property (Outlook)

 Copy code hover
[image]

StorageItem.UserProperties Property (Outlook)
See also Send feedback

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a StorageItem object.

Remarks

If you use the UserProperties.Add method on the UserProperties object associated with a StorageItem, the optional AddToFolderFields and DisplayFormat arguments of the UserProperties.Add method will be ignored. Any custom properties of the StorageItem object will not be exposed as custom properties in the Field Chooser.

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem Methods (Outlook)

 Copy code hover
[image]

StorageItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Permanently removes the StorageItem object from the parent folder.
Save | Saves the StorageItem.


StorageItem.Delete Method (Outlook)

 Copy code hover
[image]

StorageItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Permanently removes the StorageItem object from the parent folder.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a StorageItem object.

Remarks

This call allows a solution to clean up or reset the storage for its private data. Attempting to delete a StorageItem that has been removed by a prior StorageItem.Delete call will result in the error, "Could not complete the deletion."

For more information on deleting solution data stored in a StorageItem object, see Updating and Deleting Solution Storage.

Example

The following code sample in Visual Basic for Applications shows how to clean up any existing StorageItem object that has the specified subject, create a new instance with the same subject, assign a value to a custom property, and save the new instance.

VBA Copy code Copy code
Sub AssignStorageData()

 Dim oInbox As Outlook.Folder

 Dim myStorage As Outlook.StorageItem

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 ' Remove and reset any existing instance of StorageItem of the specified subject

 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 myStorage.Delete

 Set myStorage = Nothing

 ' Get a new instance of StorageItem

 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 myStorage.UserProperties.Add "Order Number", olNumber

 myStorage.UserProperties("Order Number").Value = 1000

 myStorage.Save

End Sub

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


StorageItem.Save Method (Outlook)

 Copy code hover
[image]

StorageItem.Save Method (Outlook)
See also Send feedback

Saves the StorageItem.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a StorageItem object.

Remarks

If the StorageItem has never been saved before, Save saves the item as a hidden item in the Folder on which Folder.GetStorage was called. If the StorageItem has been saved previously and the item has since been changed, Save saves the changes to the item. If the StorageItem has been saved previously and the item has not been changed since then, the Save method does nothing.

For more information on saving solution data to a StorageItem object, see Creating and Saving Data to Solution Storage.

Example

The following code sample in Visual Basic for Applications shows how to use the StorageItem object to store private solution data. It saves the data in a custom property of a StorageItem object in the Inbox folder. The following describes the steps:

  1. The code sample calls Folder.GetStorage to obtain an existing StorageItem object that has the subject "My Private Storage" in the Inbox; if no StorageItem with that subject already exists, GetStorage creates a StorageItem object with that subject.

  2. If the StorageItem is newly created, the code sample creates a custom property "Order Number" for the object. Note that "Order Number" is a property of a hidden item in the Inbox.

  3. The code sample then assigns a value to "Order Number" and saves the StorageItem object.

Copy code Copy code
Sub AssignStorageData()

 Dim oInbox As Outlook.Folder

 Dim myStorage As Outlook.StorageItem

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 ' Get an existing instance of StorageItem, or create new if it doesn't exist

 Set myStorage = oInbox.GetStorage("My Private Storage", olIdentifyBySubject)

 ' If StorageItem is new, add a custom property for Order Number

 If myStorage.Size = 0 Then

 myStorage.UserProperties.Add "Order Number", olNumber

 End If

 ' Assign a value to the custom property

 myStorage.UserProperties("Order Number").Value = 100

 myStorage.Save

End Sub

See also

Concepts

StorageItem Object

Other resources

StorageItem Object Members


Store Object (Outlook)

 Copy code hover
[image]

Store Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a file on the local computer or a network drive that stores e-mail messages and other items for an account in the current profile.

Version Information

Version Added: Outlook 2007

Remarks

A profile defines one or more e-mail accounts, and each e-mail account is associated with a server of a specific type. For an Exchange server, a store can be on the server, in an Exchange Public folder, or in a local Personal Folders File (.pst) or Offline Folder File (.ost). For a POP3, IMAP, or HTTP e-mail server, a store is a .pst file.

You can use the Stores and Store objects to enumerate all folders and search folders on all stores in the current session. Since getting the root folder or search folders in a store requires the store to be open and opening a store imposes an overhead on performance, you can check the Store.IsOpen property before you decide to pursue the operation.

If you use an Exchange server, you can access other explicit built-in Store properties for store characteristics such as ExchangeStoreType, IsCachedExchange, and IsDataFileStore. Use the PropertyAccessor object returned by Store.PropertyAccessor to access other store properties that are not exposed in the Outlook object model.

For more information on storing Outlook items in folders and stores, see Storing Outlook Items.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) enumerates all folders on all stores for a session:

VBA Copy code Copy code
Sub EnumerateFoldersInStores()

 Dim colStores As Outlook.Stores

 Dim oStore As Outlook.Store

 Dim oRoot As Outlook.Folder

 On Error Resume Next

 Set colStores = Application.Session.Stores

 For Each oStore In colStores

 Set oRoot = oStore.GetRootFolder

 Debug.Print (oRoot.FolderPath)

 EnumerateFolders oRoot

 Next

End Sub

Private Sub EnumerateFolders(ByVal oFolder As Outlook.Folder)

 Dim folders As Outlook.folders

 Dim Folder As Outlook.Folder

 Dim foldercount As Integer

 On Error Resume Next

 Set folders = oFolder.folders

 foldercount = folders.Count

 'Check if there are any folders below oFolder

 If foldercount Then

 For Each Folder In folders

 Debug.Print (Folder.FolderPath)

 EnumerateFolders Folder

 Next

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Store Object Members


Store Members (Outlook)

 Copy code hover
[image]

Store Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a file on the local computer or a network drive that stores e-mail messages and other items for an account in the current profile.

Methods

Name | Description
GetDefaultFolder | Returns a Folder object that represents the default folder in the store and that is of the type specified by the FolderType argument.
GetRootFolder | Returns a Folder object representing the root-level folder of the Store. Read-only.
GetRules | Returns a Rules collection object that contains the Rule objects defined for the current session.
GetSearchFolders | Returns a Folders collection object that represents the search folders defined for the Store object.
GetSpecialFolder | Returns a Folder object for a special folder specified by FolderType in a given store.
RefreshQuotaDisplay | Refreshes the store quota information that is displayed in the status bar in the explorer window.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns a Categories collection that represents all of the categories that are defined for the Store. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns a String representing the display name of the Store object. Read-only.
ExchangeStoreType | Returns a constant in the OlExchangeStoreType enumeration that indicates the type of an Exchange store. Read-only.
FilePath | Returns a String representing the full file path for a Personal Folders File (.pst) or an Offline Folder File (.ost) store. Read-only.
IsCachedExchange | Returns a Boolean that indicates if the Store is a cached Exchange store. Read-only.
IsConversationEnabled | Returns a Boolean value that is True if the store supports Conversation view. Read-only.
IsDataFileStore | Returns a Boolean that indicates if the Store is a store for an Outlook data file, which is either a Personal Folders File (.pst) or an Offline Folder File (.ost). Read-only.
IsInstantSearchEnabled | Returns a Boolean that indicates whether Instant Search is enabled and operational on a store. Read-only.
IsOpen | Returns a Boolean that indicates if the Store is open. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Store object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StoreID | Returns a String identifying the Store. Read-only.


Store Properties (Outlook)

 Copy code hover
[image]

Store Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Categories | Returns a Categories collection that represents all of the categories that are defined for the Store. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayName | Returns a String representing the display name of the Store object. Read-only.
ExchangeStoreType | Returns a constant in the OlExchangeStoreType enumeration that indicates the type of an Exchange store. Read-only.
FilePath | Returns a String representing the full file path for a Personal Folders File (.pst) or an Offline Folder File (.ost) store. Read-only.
IsCachedExchange | Returns a Boolean that indicates if the Store is a cached Exchange store. Read-only.
IsConversationEnabled | Returns a Boolean value that is True if the store supports Conversation view. Read-only.
IsDataFileStore | Returns a Boolean that indicates if the Store is a store for an Outlook data file, which is either a Personal Folders File (.pst) or an Offline Folder File (.ost). Read-only.
IsInstantSearchEnabled | Returns a Boolean that indicates whether Instant Search is enabled and operational on a store. Read-only.
IsOpen | Returns a Boolean that indicates if the Store is open. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Store object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StoreID | Returns a String identifying the Store. Read-only.


Store.Application Property (Outlook)

 Copy code hover
[image]

Store.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Store object.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.Categories Property (Outlook)

 Copy code hover
[image]

Store.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Categories collection that represents all of the categories that are defined for the Store. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Categories

expression A variable that represents a Store object.

Remarks

This property is similar to the Categories property of the NameSpace object, except that the Store.Categories property applies to a session profile that specifies one or more accounts and Store.Categories specifies the categories for the store that an account is associated with, whereas NameSpace.Categories applies to a session profile that defines only one account and the NameSpace.Categories property specifies the Master Category List for that session.

For certain secondary delivery stores such as an IMAP store, the Categories property returns the Categories collection for the primary store. IMAP stores do not actually support a separate categories collection.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) displays the name of each Category object that is contained in the Categories collection associated with each Store object in the Stores collection for the session.

VBA Copy code Copy code
Sub EnumerateCategoriesForStores()

 Dim oStores As Outlook.Stores

 Dim oStore As Outlook.Store

 Dim oCategories As Outlook.Categories

 Dim oCategory As Outlook.Category

 Set oStores = Application.Session.Stores

 For Each oStore In oStores

 Debug.Print oStore.DisplayName

 Debug.Print "--------------Categories-----------------"

 Set oCategories = oStore.Categories

 For Each oCategory In oCategories

 Debug.Print Chr(9) & oCategory.Name

 Next

 Debug.Print ""

 Next

End Sub

See also

Concepts

Store Object

Other resources

Store Object Members


Store.Class Property (Outlook)

 Copy code hover
[image]

Store.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Store object.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.DisplayName Property (Outlook)

 Copy code hover
[image]

Store.DisplayName Property (Outlook)
See also Send feedback

Returns a String representing the display name of the Store object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayName

expression A variable that represents a Store object.

Remarks

DisplayName is the default property of the Store object. This property corresponds to the MAPI property, PidTagDisplayName.

DisplayName is read-only. To change the DisplayName of a Personal Folders File (.pst), use the PropertyAccessor object and the PropertyAccessor.SetProperty method.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.ExchangeStoreType Property (Outlook)

 Copy code hover
[image]

Store.ExchangeStoreType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlExchangeStoreType enumeration that indicates the type of an Exchange store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ExchangeStoreType

expression A variable that represents a Store object.

Remarks

The ExchangeStoreType property distinguishes among different Exchange store types, such as primary Exchange mailbox, Exchange mailbox, Public Folder store, or non-Exchange store. This property does not distinguish among every type of store including Hotmail, HTTP, IMAP, and so forth. Use Account.AccountType for the type of server associated with an e-mail account, such as Exchange, HTTP, IMAP, or POP3.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.FilePath Property (Outlook)

 Copy code hover
[image]

Store.FilePath Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the full file path for a Personal Folders File (.pst) or an Offline Folder File (.ost) store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .FilePath

expression A variable that represents a Store object.

Remarks

This property supports both Exchange and non-Exchange stores. If the store is not a .pst or .ost store, FilePath returns an empty string.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.IsCachedExchange Property (Outlook)

 Copy code hover
[image]

Store.IsCachedExchange Property (Outlook)
See also Send feedback

Returns a Boolean that indicates if the Store is a cached Exchange store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsCachedExchange

expression A variable that represents a Store object.

Remarks

IsCachedExchange returns True when Store.ExchangeStoreType is a primary Exchange mailbox (Store.ExchangeStoreType is olExchangePrimaryMailbox) and the mailbox is configured to use cached Exchange mode. It returns False otherwise. In particular, it returns False for an Exchange Public Folder store that is configured to cache Public Folder favorites.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.IsConversationEnabled Property (Outlook)

 Copy code hover
[image]

Store.IsConversationEnabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the store supports Conversation view. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .IsConversationEnabled

expression A variable that represents a Store object.

Remarks

A store supports Conversation view if the store is a POP, IMAP, or PST store, or if it runs a version of Microsoft Exchange Server that is at least Microsoft Exchange Server 2010. A store also supports Conversation view if the store is running Microsoft Exchange Server 2007, the version of Outlook is at least Microsoft Outlook 2010, and Outlook is running in cached mode.

If a store supports conversations, calling the GetConversation method of an item in the store returns a Conversation object for the item. If the store does not support conversations, GetConversation returns Null (Nothing in Visual Basic) for items in the store.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.IsDataFileStore Property (Outlook)

 Copy code hover
[image]

Store.IsDataFileStore Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the Store is a store for an Outlook data file, which is either a Personal Folders File (.pst) or an Offline Folder File (.ost). Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsDataFileStore

expression A variable that represents a Store object.

Remarks

IsDataFileStore supports only Exchange stores, and will return False for HTTP-type stores such as Hotmail and MSN, and for IMAP stores.

For Exchange stores, IsDataFileStore will return False if the user profile is not using Cached Exchange mode. IsDataFileStore will also return False when the store is an Exchange Public Folder (that is, Store.ExchangeStoreType is olExchangePublicFolder).

IsDataFileStore does not indicate whether the store is located on a local hard drive. For example, a .pst file could be located on a mapped network drive and IsDataFileStore would still return True.

The return value of IsDataFileStore can change if the user is configured for classic Exchange offline mode. When the user is offline and using classic Exchange offline mode, IsDataFileStore will return True. When the user is online and using classic Exchange online mode, IsDataFileStore will return False.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.IsInstantSearchEnabled Property (Outlook)

 Copy code hover
[image]

Store.IsInstantSearchEnabled Property (Outlook)
See also Send feedback

Returns a Boolean that indicates whether Instant Search is enabled and operational on a store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsInstantSearchEnabled

expression A variable that represents a Store object.

Remarks

Use IsInstantSearchEnabled to evaluate whether you should use ci_startswith or ci_phrasematch operators in your query. If you use ci_startswith or ci_phrasematch in the query and Instant Search is not enabled, Outlook will return an error.

Example

The following code sample accepts a matching string as an input parameter, constructs a DASL filter with the content indexing keyword ci_phrasematch if Instant Search is enabled on the store, and returns the filter. Otherwise, if Instant Search is not operational, then the code sample returns a filter that uses the like keyword.

For more information on filtering with keywords, see Filtering Items Using Query Keywords.

Copy code Copy code
Function CreateSubjectRestriction(criteria As String) As String

 Dim result As String

 If Application.Session.DefaultStore.IsInstantSearchEnabled Then

 result = "@SQL=" & Chr(34) & "urn:schemas:httpmail:subject" _

 & Chr(34) & " ci_phrasematch '" & criteria & "'"

 Else

 result = "@SQL=" & Chr(34) & "urn:schemas:httpmail:subject" _

 & Chr(34) & " like '%" & criteria & "%'"

 End If

 CreateSubjectRestriction = result

End Function

See also

Concepts

Store Object

Other resources

Store Object Members


Store.IsOpen Property (Outlook)

 Copy code hover
[image]

Store.IsOpen Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates if the Store is open. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .IsOpen

expression A variable that represents a Store object.

Remarks

This property supports both Exchange and non-Exchange stores.

IsOpen only indicates if the store is open. It does not indicate if the store is offline, or if it is an Exchange mailbox or an Exchange Public Folder and the store server is down.

Because opening a store can impose a performance overhead, and Store.GetRootFolder and Store.GetSearchFolders will open a store if it is not already open, you can use IsOpen before deciding to call GetRootFolder or GetSearchFolders to minimize performance overhead.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.Parent Property (Outlook)

 Copy code hover
[image]

Store.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Store object.

Remarks

The parent of the Store object is the NameSpace object.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

Store.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent Store object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a Store object.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.Session Property (Outlook)

 Copy code hover
[image]

Store.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Store object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Store Object

Other resources

Store Object Members


Store.StoreID Property (Outlook)

 Copy code hover
[image]

Store.StoreID Property (Outlook)
See also Send feedback

Returns a String identifying the Store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .StoreID

expression A variable that represents a Store object.

Remarks

StoreID is unique to the profile. It is equivalent to the MAPI property PidTagStoreEntryId.

See also

Concepts

Store Object

Other resources

Store Object Members


Store Methods (Outlook)

 Copy code hover
[image]

Store Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
GetDefaultFolder | Returns a Folder object that represents the default folder in the store and that is of the type specified by the FolderType argument.
GetRootFolder | Returns a Folder object representing the root-level folder of the Store. Read-only.
GetRules | Returns a Rules collection object that contains the Rule objects defined for the current session.
GetSearchFolders | Returns a Folders collection object that represents the search folders defined for the Store object.
GetSpecialFolder | Returns a Folder object for a special folder specified by FolderType in a given store.
RefreshQuotaDisplay | Refreshes the store quota information that is displayed in the status bar in the explorer window.


Store.GetDefaultFolder Method (Outlook)

 Copy code hover
[image]

Store.GetDefaultFolder Method (Outlook)
See also Send feedback

Returns a Folder object that represents the default folder in the store and that is of the type specified by the FolderType argument.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetDefaultFolder(FolderType)

expression A variable that represents a Store object.

Parameters

Name | Required/Optional | Data Type | Description
FolderType | Required | OlDefaultFolders | Specifies the type of the requested default folder.

Return Value

A Folder object that represents the default folder of the requested type. If the default folder of the requested type does not exist, GetDefaultFolder returns Null (Nothing in Visual Basic).

Remarks

This method is similar to the GetDefaultFolder method of the NameSpace object. The difference is that this method gets the default folder on the delivery store that is associated with the account, whereas NameSpace.GetDefaultFolder returns the default folder on the default store for the current profile.

One example of when GetDefaultFolder returns Null (Nothing in Visual Basic) is when olFolderManagedEmail is specified as the FolderType but the Managed Folders group has not been deployed.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.GetRootFolder Method (Outlook)

 Copy code hover
[image]

Store.GetRootFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object representing the root-level folder of the Store. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetRootFolder

expression A variable that represents a Store object.

Return Value

A Folder object that represents the folder at the root of that Store.

Remarks

You can use the GetRootFolder method to enumerate the subfolders of the root folder of the Store. Unlike NameSpace.Folders which contains all folders for all stores in the current profile, Store.GetRootFolder.Folders allows you to enumerate all folders for a given Store object in the current profile.

The Parent property of the root folder of a store returns the string "Mapi".

The root folder for the Exchange Public Folder store is the folder Public Folders. This folder is returned by the call to Application.Session.GetDefaultFolder(olPublicFoldersAllPublicFolders).

GetRootFolder returns an error if the service provider does not support root folders.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) starts at the root-level folder of each Store in a Stores collection for a session, and enumerates all folders on all stores for that session.

VBA Copy code Copy code
Sub EnumerateFoldersInStores()

 Dim colStores As Outlook.Stores

 Dim oStore As Outlook.Store

 Dim oRoot As Outlook.Folder

 On Error Resume Next

 Set colStores = Application.Session.Stores

 For Each oStore In colStores

 Set oRoot = oStore.GetRootFolder

 Debug.Print (oRoot.FolderPath)

 EnumerateFolders oRoot

 Next

End Sub

Private Sub EnumerateFolders(ByVal oFolder As Outlook.Folder)

 Dim folders As Outlook.folders

 Dim Folder As Outlook.Folder

 Dim foldercount As Integer

 On Error Resume Next

 Set folders = oFolder.folders

 foldercount = folders.Count

 'Check if there are any folders below oFolder

 If foldercount Then

 For Each Folder In folders

 Debug.Print (Folder.FolderPath)

 EnumerateFolders Folder

 Next

 End If

End Sub

See also

Concepts

Store Object

Other resources

Store Object Members


Store.GetRules Method (Outlook)

 Copy code hover
[image]

Store.GetRules Method (Outlook)
See also Send feedback

Returns a Rules collection object that contains the Rule objects defined for the current session.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetRules

expression A variable that represents a Store object.

Return Value

A Rules collection object that represents the set of Rules defined for the current session.

Remarks

Calling GetRules can be an expensive operation in terms of performance on slow connections to an Exchange server.

The order of the Rule objects in the collection returned from GetRules follows that of Rule.ExecutionOrder with ExecutionOrder equal 1 being the first Rule in the collection and ExecutionOrder equal Rules.Count being the last Rule in the collection.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.GetSearchFolders Method (Outlook)

 Copy code hover
[image]

Store.GetSearchFolders Method (Outlook)
See also Send feedback

Returns a Folders collection object that represents the search folders defined for the Store object.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetSearchFolders

expression A variable that represents a Store object.

Return Value

A Folders collection object that represents all the search folders for the Store object.

Remarks

GetSearchFolders returns all the visible active search folders for the Store. It does not return uninitialized or aged out search folders.

GetSearchFolders returns a Folders collection object with Folders.Count equal zero (0) if no search folders have been defined for the Store.

For a Folders collection object that represents a collection of search folders, Folders.Parent returns the same object as Store.GetRootFolder. Folder.Folders returns Null (Nothing in Visual Basic).

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) enumerates the search folders on all stores for the current session.

VBA Copy code Copy code
Sub EnumerateSearchFoldersInStores()

 Dim colStores As Outlook.Stores

 Dim oStore As Outlook.Store

 Dim oSearchFolders As Outlook.folders

 Dim oFolder As Outlook.Folder

 On Error Resume Next

 Set colStores = Application.Session.Stores

 For Each oStore In colStores

 Set oSearchFolders = oStore.GetSearchFolders

 For Each oFolder In oSearchFolders

 Debug.Print (oFolder.FolderPath)

 Next

 Next

End Sub

See also

Concepts

Store Object

Other resources

Store Object Members


Store.GetSpecialFolder Method (Outlook)

 Copy code hover
[image]

Store.GetSpecialFolder Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Folder object for a special folder specified by FolderType in a given store.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetSpecialFolder(FolderType)

expression A variable that represents a Store object.

Parameters

Name | Required/Optional | Data Type | Description
FolderType | Required | OlSpecialFolders | A constant in the OlSpecialFolders enumeration that specifies the type of the special folder in the store.

Return Value

A Folder object that represents a special folder specified by the FolderType.

Remarks

Not all special folders exist in all stores. If the requested special folder does not exist, a Null value (Nothing in VB) will be returned.

See also

Concepts

Store Object

Other resources

Store Object Members


Store.RefreshQuotaDisplay Method (Outlook)

 Copy code hover
[image]

Store.RefreshQuotaDisplay Method (Outlook)
See also Send feedback

Published: July 16, 2012

Refreshes the store quota information that is displayed in the status bar in the explorer window.

Version Information

Version Added: Outlook 2010

Syntax

expression .RefreshQuotaDisplay

expression A variable that represents a Store object.

Remarks

If the store does not support the display of quota information, this method does nothing.

See also

Concepts

Store Object

Other resources

Store Object Members


Stores Object (Outlook)

 Copy code hover
[image]

Stores Object (Outlook)
See also Send feedback

Published: July 16, 2012

A set of Store objects representing all the stores available in the current profile.

Version Information

Version Added: Outlook 2007

Remarks

You can use the Stores and Store objects to enumerate all folders and search folders on all stores in the current session. For more information on storing Outlook items in folders and stores, see Storing Outlook Items.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) enumerates all folders on all stores for a session:

VBA Copy code Copy code
Sub EnumerateFoldersInStores()

 Dim colStores As Outlook.Stores

 Dim oStore As Outlook.Store

 Dim oRoot As Outlook.Folder

 On Error Resume Next

 Set colStores = Application.Session.Stores

 For Each oStore In colStores

 Set oRoot = oStore.GetRootFolder

 Debug.Print (oRoot.FolderPath)

 EnumerateFolders oRoot

 Next

End Sub

Private Sub EnumerateFolders(ByVal oFolder As Outlook.Folder)

 Dim folders As Outlook.folders

 Dim Folder As Outlook.Folder

 Dim foldercount As Integer

 On Error Resume Next

 Set folders = oFolder.folders

 foldercount = folders.Count

 'Check if there are any folders below oFolder

 If foldercount Then

 For Each Folder In folders

 Debug.Print (Folder.FolderPath)

 EnumerateFolders Folder

 Next

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Stores Object Members


Stores Members (Outlook)

 Copy code hover
[image]

Stores Members (Outlook)
Send feedback

Published: July 16, 2012

A set of Store objects representing all the stores available in the current profile.

Events

Name | Description
BeforeStoreRemove | Occurs when a Store is about to be removed from the current session either programmatically or through user action.
StoreAdd | Occurs when a Store has been added to the current session either programmatically or through user action.

Methods

Name | Description
Item | Returns a Store object that is specified by Index. Read-only.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Stores Properties (Outlook)

 Copy code hover
[image]

Stores Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Stores.Application Property (Outlook)

 Copy code hover
[image]

Stores.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Stores object.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores.Class Property (Outlook)

 Copy code hover
[image]

Stores.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Stores object.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores.Count Property (Outlook)

 Copy code hover
[image]

Stores.Count Property (Outlook)
See also Send feedback

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a Stores object.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores.Parent Property (Outlook)

 Copy code hover
[image]

Stores.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Stores object.

Remarks

The parent of a Stores object is the NameSpace object.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores.Session Property (Outlook)

 Copy code hover
[image]

Stores.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Stores object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores Methods (Outlook)

 Copy code hover
[image]

Stores Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Item | Returns a Store object that is specified by Index. Read-only.


Stores.Item Method (Outlook)

 Copy code hover
[image]

Stores.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Store object that is specified by Index. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a Stores object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either an Integer that specifies a one-based index into the Stores collection, or a String value that specifies the DisplayName of a Store in the Stores collection.

Return Value

A Store object in the parent Stores collection, as specified by Index.

Remarks

The Store.DisplayName property is the default property of a Store.

If Index is a string and no item can be found by that name, an error will be returned.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores Events (Outlook)

 Copy code hover
[image]

Stores Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
BeforeStoreRemove | Occurs when a Store is about to be removed from the current session either programmatically or through user action.
StoreAdd | Occurs when a Store has been added to the current session either programmatically or through user action.


Stores.BeforeStoreRemove Event (Outlook)

 Copy code hover
[image]

Stores.BeforeStoreRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a Store is about to be removed from the current session either programmatically or through user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeStoreRemove(Store, Cancel)

expression A variable that represents a Stores object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | The Store object to be removed from the current session.
Cancel | Required | Boolean | True to cancel the removal of the specified store, False otherwise.

Remarks

Outlook must be running in order for this event to fire. This event will fire when any of the following occurs:

  • A store is removed by the user clicking the Close command on the Shortcut menu.

  • A store is removed programmatically by calling Namespace.RemoveStore.

This event will not fire when any of the following occurs:

  • When Outlook shuts down and closes a primary or delegate store.

  • If a store is removed through the Mail applet in the Microsoft Windows Control Panel and Outlook is not running.

  • A delegate store is removed on the Advanced tab of the Microsoft Exchange Server dialog box.

  • A store is removed through the Data Files tab of the Account Manager dialog box when Outlook is not running.

  • An IMAP Store is removed from the profile.

You can use this event to determine that a store has been removed, and take appropriate actions if the store is required for your application (such as remounting the store). Otherwise you would have to resort to polling the Stores collection.

See also

Concepts

Stores Object

Other resources

Stores Object Members


Stores.StoreAdd Event (Outlook)

 Copy code hover
[image]

Stores.StoreAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a Store has been added to the current session either programmatically or through user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .StoreAdd(Store)

expression A variable that represents a Stores object.

Parameters

Name | Required/Optional | Data Type | Description
Store | Required | Store | The Store to be added to the current session.

Remarks

Outlook must be running in order for this event to fire. This event will fire when any of the following occur:

  • A store is added through the Open Outlook Data File dialog box, by selecting Open and then Outlook Data File on the File menu.

  • A store is added through the Data Files tab of the Account Manager dialog box.

  • A store is added successfully by calling the Namespace.AddStore method.

This event will not fire when any of the following occurs:

  • When Outlook starts and opens a primary or delegate store.

  • If a store is added through the Mail applet in the Microsoft Windows Control Panel and Outlook is not running.

  • A delegate store is added through the Advanced tab of the Microsoft Exchange Server dialog box.

You can use this event to determine whether a store has been added and take appropriate actions on items in that store. Otherwise, you would have to resort to polling the Stores collection.

See also

Concepts

Stores Object

Other resources

Stores Object Members


SyncObject Object (Outlook)

 Copy code hover
[image]

SyncObject Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a Send\Receive group for a user.

Remarks

A Send\Receive group lets users configure different synchronization scenarios, selecting which folders and which filters apply.

Use the Item method to retrieve the SyncObject object from a SyncObjects object. Because the Name property is the default property of the SyncObject object, you can identify the group by name.

The SyncObject object is read-only; you cannot change its properties or create new ones. However, note that you can add one Send/Receive group using the SyncObjects.AppFolders property which will create a Send/Receive group called Application Folders.

Example

The following example retrieves a SyncObject object by name.

VBA Copy code Copy code
Set mySyncObject = mySyncObjects.Item("Daily")

See also

Concepts

Outlook Object Model Reference

Other resources

SyncObject Object Members


SyncObject Members (Outlook)

 Copy code hover
[image]

SyncObject Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a Send\Receive group for a user.

Events

Name | Description
OnError | Occurs when Microsoft Outlook encounters an error while synchronizing a user's folders using the specified Send\Receive group.
Progress | Occurs periodically while Microsoft Outlook is synchronizing a user's folders using the specified Send\Receive group.
SyncEnd | Occurs immediately after Microsoft Outlook finishes synchronizing a user's folders using the specified Send/Receive group.
SyncStart | Occurs when Microsoft Outlook begins synchronizing a user's folders using the specified Send\Receive group.

Methods

Name | Description
Start | Begins synchronizing a user's folders using the specified Send\Receive group.
Stop | Immediately ends synchronizing a user's folders using the specified Send/Receive group.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SyncObject Properties (Outlook)

 Copy code hover
[image]

SyncObject Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SyncObject.Application Property (Outlook)

 Copy code hover
[image]

SyncObject.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a SyncObject object.

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Class Property (Outlook)

 Copy code hover
[image]

SyncObject.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a SyncObject object.

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Name Property (Outlook)

 Copy code hover
[image]

SyncObject.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents a SyncObject object.

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Parent Property (Outlook)

 Copy code hover
[image]

SyncObject.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a SyncObject object.

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Session Property (Outlook)

 Copy code hover
[image]

SyncObject.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a SyncObject object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject Methods (Outlook)

 Copy code hover
[image]

SyncObject Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Start | Begins synchronizing a user's folders using the specified Send\Receive group.
Stop | Immediately ends synchronizing a user's folders using the specified Send/Receive group.


SyncObject.Start Method (Outlook)

 Copy code hover
[image]

SyncObject.Start Method (Outlook)
See also Send feedback

Published: July 16, 2012

Begins synchronizing a user's folders using the specified Send\Receive group.

Syntax

expression .Start

expression An expression that returns a SyncObject object.

Example

This Microsoft Visual Basic for Applications (VBA) example displays all the Send\Receive groups set up for the user and starts the synchronization based on user's response.

VBA Copy code Copy code
Public Sub Sync()
 Dim nsp As Outlook.NameSpace
 Dim sycs As Outlook.SyncObjects
 Dim syc As Outlook.SyncObject
 Dim i As Integer
 Dim strPrompt As Integer
 Set nsp = Application.GetNamespace("MAPI")
 Set sycs = nsp.SyncObjects
 For i = 1 To sycs.Count
Set syc = sycs.Item(i)
strPrompt = MsgBox( _
 "Do you wish to synchronize " & syc.Name &"?", vbYesNo)
If strPrompt = vbYes Then
 syc.Start
End If
 Next
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Stop Method (Outlook)

 Copy code hover
[image]

SyncObject.Stop Method (Outlook)
See also Send feedback

Immediately ends synchronizing a user's folders using the specified Send/Receive group.

Syntax

expression .Stop

expression A variable that represents a SyncObject object.

Remarks

This method does not undo any synchronization that has already occurred.

Example

This Microsoft Visual Basic for Applications (VBA) example displays all the Send/Receive groups set up for the user and starts the synchronization based on the user's response. The subroutine following the one below immediately stops the synchronization. The syc variable is declared as a public variable so it can be referenced by both the subroutines.

VBA Copy code Copy code
Public syc As Outlook.SyncObject

Public Sub Sync()
 Dim nsp As Outlook.NameSpace
 Dim sycs As Outlook.SyncObjects
 Dim i As Integer
 Dim strPrompt As Integer
 Set nsp = Application.GetNamespace("MAPI")
 Set sycs = nsp.SyncObjects
 For i = 1 To sycs.Count
Set syc = sycs.Item(i)
strPrompt = MsgBox("Do you wish to synchronize " & syc.Name &"?", vbYesNo)
If strPrompt = vbYes Then
 syc.Start
End If
 Next
End Sub

Private Sub StopSync()
 MsgBox "Synchronization stopped by the user."
 syc.Stop
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject Events (Outlook)

 Copy code hover
[image]

SyncObject Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
OnError | Occurs when Microsoft Outlook encounters an error while synchronizing a user's folders using the specified Send\Receive group.
Progress | Occurs periodically while Microsoft Outlook is synchronizing a user's folders using the specified Send\Receive group.
SyncEnd | Occurs immediately after Microsoft Outlook finishes synchronizing a user's folders using the specified Send/Receive group.
SyncStart | Occurs when Microsoft Outlook begins synchronizing a user's folders using the specified Send\Receive group.


SyncObject.OnError Event (Outlook)

 Copy code hover
[image]

SyncObject.OnError Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when Microsoft Outlook encounters an error while synchronizing a user's folders using the specified Send\Receive group.

Syntax

expression .OnError(Code, Description)

expression A variable that represents a SyncObject object.

Parameters

Name | Required/Optional | Data Type | Description
Code | Required | Long | A unique value that identifies the error.
Description | Required | String | A textual description of the error.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example displays a message box describing the synchronization error when an error occurs during synchronization. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents mySync As Outlook.SyncObject

Sub Initialize_handler()
 Set mySync = Application.Session.SyncObjects.Item(1)
 mySync.Start
 mySync.Stop
End Sub

Private Sub mySync_OnError(ByVal Code As Long, ByVal Description As String)
 MsgBox "Unexpected sync error" & Code & ": " & Description
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.Progress Event (Outlook)

 Copy code hover
[image]

SyncObject.Progress Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs periodically while Microsoft Outlook is synchronizing a user's folders using the specified Send\Receive group.

Syntax

expression .Progress(State, Description, Value, Max)

expression A variable that represents a SyncObject object.

Parameters

Name | Required/Optional | Data Type | Description
State | Required | OlSyncState | A value that identifies the current state of the synchronization process.
Description | Required | String | A textual description of the current state of the synchronization process.
Value | Required | Long | Specifies the current value of the synchronization process (such as the number of items synchronized).
Max | Required | Long | The maximum that Value can reach. The ratio of Value to Max represents the percent complete of the synchronization process.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example shows the progress of synchronization. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents mySync As Outlook.SyncObject

Sub Initialize_handler()
 Set mySync = Application.Session.SyncObjects.Item(1)
 mySync.Start
End Sub

Private Sub mySync_Progress(ByVal State As Outlook.OlSyncState, ByVal Description As String, ByVal Value As Long, ByVal Max As Long)
 If Not Description = "" Then
 MsgBox Description
 End If
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.SyncEnd Event (Outlook)

 Copy code hover
[image]

SyncObject.SyncEnd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs immediately after Microsoft Outlook finishes synchronizing a user's folders using the specified Send/Receive group.

Syntax

expression .SyncEnd

expression A variable that represents a SyncObject object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Microsoft Visual Basic for Applications (VBA) example displays a message when synchronization is complete. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents mySync As Outlook.SyncObject

Sub Initialize_handler()
 Set mySync = Application.Session.SyncObjects.Item(1)
 mySync.Start
End Sub

Private Sub mySync_SyncEnd()
 MsgBox "Synchronization is complete."
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObject.SyncStart Event (Outlook)

 Copy code hover
[image]

SyncObject.SyncStart Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when Microsoft Outlook begins synchronizing a user's folders using the specified Send\Receive group.

Syntax

expression .SyncStart

expression A variable that represents a SyncObject object.

Remarks

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).

Example

This Visual Basic for Applications (VBA) example displays a message telling the user that the synchronization might take a long time. The sample code must be placed in a class module, and the Initialize_handler routine must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Dim WithEvents mySync As Outlook.SyncObject

Sub Initialize_handler()
 Set mySync = Application.Session.SyncObjects.Item(1)
 mySync.Start
End Sub

Private Sub mySync_SyncStart()
 MsgBox "Synchronization is about to start. It might take a long time to complete."
End Sub

See also

Concepts

SyncObject Object

Other resources

SyncObject Object Members


SyncObjects Object (Outlook)

 Copy code hover
[image]

SyncObjects Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of SyncObject objects representing the Send/Receive groups for a user.

Remarks

Use the SyncObjects property to return the SyncObjects object from a NameSpace object.

The SyncObjects object is read-only. You cannot add an item to the collection. However, note that you can add one Send/Receive group using the AppFolders property which will create a Send/Receive group called Application Folders.

Example

The following Microsoft Visual Basic for Applications (VBA) example retrieves the SyncObjects object for the MAPI NameSpace object.

Copy code Copy code
Set mySyncObjects = Application.GetNameSpace("MAPI").SyncObjects

See also

Concepts

Outlook Object Model Reference

Other resources

SyncObjects Object Members


SyncObjects Members (Outlook)

 Copy code hover
[image]

SyncObjects Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of SyncObject objects representing the Send/Receive groups for a user.

Methods

Name | Description
Item | Returns a SyncObject object from the collection.

Properties

Name | Description
AppFolders | This property returns the SyncObject object for application folders. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SyncObjects Properties (Outlook)

 Copy code hover
[image]

SyncObjects Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AppFolders | This property returns the SyncObject object for application folders. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


SyncObjects.AppFolders Property (Outlook)

 Copy code hover
[image]

SyncObjects.AppFolders Property (Outlook)
See also Send feedback

Published: July 16, 2012

This property returns the SyncObject object for application folders. Read-only.

Syntax

expression .AppFolders

expression A variable that represents a SyncObjects object.

Remarks

The SyncObject is where folders are automatically added when the InAppFolderSyncObject property of the Folder object is set to True. The SyncObject allows users to synchronize Microsoft Outlook folders, address books, and folder home pages for offline use.

Example

The following example sets the SyncObject for the application folders and synchronizes the user's Inbox.

VBA Copy code Copy code
Public Sub SetAppfolders()

 Dim nsp As Outlook.NameSpace

 Dim objSycs As Outlook.SyncObjects

 Dim objSyc As Outlook.SyncObject

 Dim mpfInbox As Outlook.Folder

 Set nsp = Application.GetNamespace("MAPI")

 Set objSycs = nsp.SyncObjects

 Set objSyc = objSycs.AppFolders

 Set mpfInbox = nsp.GetDefaultFolder(olFolderInbox)

 mpfInbox.InAppFolderSyncObject = True

 objSyc.Start

End Sub

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects.Application Property (Outlook)

 Copy code hover
[image]

SyncObjects.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a SyncObjects object.

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects.Class Property (Outlook)

 Copy code hover
[image]

SyncObjects.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a SyncObjects object.

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects.Count Property (Outlook)

 Copy code hover
[image]

SyncObjects.Count Property (Outlook)
See also Send feedback

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a SyncObjects object.

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects.Parent Property (Outlook)

 Copy code hover
[image]

SyncObjects.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a SyncObjects object.

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects.Session Property (Outlook)

 Copy code hover
[image]

SyncObjects.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a SyncObjects object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


SyncObjects Methods (Outlook)

 Copy code hover
[image]

SyncObjects Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Item | Returns a SyncObject object from the collection.


SyncObjects.Item Method (Outlook)

 Copy code hover
[image]

SyncObjects.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a SyncObject object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a SyncObjects object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A SyncObject object that represents the specified object.

See also

Concepts

SyncObjects Object

Other resources

SyncObjects Object Members


Table Object (Outlook)

 Copy code hover
[image]

Table Object (Outlook)
See also Send feedback

Represents a set of item data from a Folder or Search object, with items as rows of the table and properties as columns of the table.

Version Information

Version Added: Outlook 2007

Remarks

The Table represents a read-only dynamic rowset of data in a Folder or Search object. You can use Folder.GetTable or Search.GetTable to obtain a Table object that represents a set of items in a folder or search folder. If the Table object is obtained from Folder.GetTable, you can further specify a filter (in Table.Restrict) to obtain a subset of the items in the folder. If you do not specify any filter, you will obtain all the items in the folder.

By default, each item in the returned Table contains only a default subset of its properties. You can regard each row of a Table as an item in the folder, each column as a property of the item, and the Table as an in-memory lightweight rowset that allows fast enumeration and filtering of items in the folder. Although additions and deletions of the underlying folder are reflected by the rows in the Table, the Table does not support any events for adding, changing, and removing of rows. If you require a writeable object from the Table row, obtain the Entry ID for that row from the default EntryID column in the Table and then use the GetItemFromID method of the NameSpace object to obtain a full item, such as a MailItem or ContactItem, that supports read-write operations. For more information on default columns in a Table, see Default Properties Displayed in a Table Object.

For more information on the Table object, see Enumerating, Searching, and Filtering Items in a Folder.

Example

The following code sample illustrates how the Table object can return a filtered set of items based on their LastModificationTime property. It also shows how to list the default properties as well as specific properties of the items.

VBA Copy code Copy code
Sub DemoTable()

 'Declarations

 Dim Filter As String

 Dim oRow As Outlook.Row

 Dim oTable As Outlook.Table

 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox

 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after May 1, 2005

 Filter = "[LastModificationTime] > '5/1/2005'"

 'Restrict with Filter

 Set oTable = oFolder.GetTable(Filter)

 'Remove all columns in the default column set

 oTable.Columns.RemoveAll

 'Specify desired properties

 With oTable.Columns

 .Add ("Subject")

 .Add ("LastModificationTime")

 'PR_ATTR_HIDDEN referenced by the MAPI proptag namespace

 .Add ("http://schemas.microsoft.com/mapi/proptag/0x10F4000B")

 End With

 'Enumerate the table using test for EndOfTable

 Do Until (oTable.EndOfTable)

 Set oRow = oTable.GetNextRow()

 Debug.Print (oRow("Subject"))

 Debug.Print (oRow("LastModificationTime"))

 Debug.Print (oRow("http://schemas.microsoft.com/mapi/proptag/0x10F4000B"))

 Loop

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Table Object Members


Table Members (Outlook)

 Copy code hover
[image]

Table Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a set of item data from a Folder or Search object, with items as rows of the table and properties as columns of the table.

Methods

Name | Description
FindNextRow | Finds the next row in the Table that meets the criteria specified in a preceding Table.FindRow.
FindRow | Finds the first row in the Table that meets the criteria specified in Filter.
GetArray | Obtains a two-dimensional array that contains a set of row and column values from the Table.
GetNextRow | Moves the current row to the next row in the Table and obtains that row in the Table.
GetRowCount | Obtains the number of rows in the Table.
MoveToStart | Moves the current row of the Table to just before the first row of the Table.
Restrict | Applies a filter to the rows in the Table and obtains a new Table object.
Sort | Sorts the rows of the Table by the property specified in SortProperty and resets the current row to just before the first row in the Table.

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Table object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Table object. Read-only.
Columns | Returns a Columns collection object that contains the columns defined for the Table. Read-only.
EndOfTable | Returns a Boolean that indicates whether the current row is positioned after the last row in the Table object. Read-only.
Parent | Returns the parent Object of the Table object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Table Properties (Outlook)

 Copy code hover
[image]

Table Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent application (Outlook) for the Table object. Read-only.
Class | Returns a constant in the OlObjectClass enumeration indicating the class of the Table object. Read-only.
Columns | Returns a Columns collection object that contains the columns defined for the Table. Read-only.
EndOfTable | Returns a Boolean that indicates whether the current row is positioned after the last row in the Table object. Read-only.
Parent | Returns the parent Object of the Table object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Table.Application Property (Outlook)

 Copy code hover
[image]

Table.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent application (Outlook) for the Table object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a Table object.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Class Property (Outlook)

 Copy code hover
[image]

Table.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant in the OlObjectClass enumeration indicating the class of the Table object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a Table object.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Columns Property (Outlook)

 Copy code hover
[image]

Table.Columns Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Columns collection object that contains the columns defined for the Table. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Columns

expression A variable that represents a Table object.

Remarks

The Columns collection object is the default member of the Table object.

While rows in a Table correspond to items in the parent Folder or Search object of the Table, Columns in a Table correspond to the properties of these items. Default columns are defined for all folders depending on the parent folder of the Table object. For example, the default properties for the Inbox are: EntryID, Subject, CreationTime, LastModificationTime, and MessageClass. For more information on default properties for a Table, see Default Properties Displayed in a Table Object.

To add Column objects to the Columns collection of a Table, use Columns.Add. To remove the default column set, use Columns.RemoveAll. For more information on adjusting columns of a Table, see Adding Columns to a Table Object.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.EndOfTable Property (Outlook)

 Copy code hover
[image]

Table.EndOfTable Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates whether the current row is positioned after the last row in the Table object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndOfTable

expression A variable that represents a Table object.

Remarks

When you open a Table using Folder.GetTable, Search.GetTable, or Table.Restrict, the value of EndOfTable depends on the number of rows in the Table. If there are no rows, EndOfTable returns True. If there are rows, EndOfTable returns False until the cursor moves beyond the last row in the Table.

The Table has two virtual Null rows, one before the first row and one after the last row in the Table. Each call to Table.GetNextRow moves the current row to the next row in the Table and returns a Row object that represents the current row.

The EndOfTable property returns True if the current row is after the last row and False if the current row is on or before the last row.

Example

The following code sample applies a Jet filter on items in the Inbox to obtain a Table of items that have a LastModificationTime greater than November 1, 2005. It then uses the EndOfTable property to enumerate the items in the Table and print the values of the default properties for each item in the Table.

Copy code Copy code
Sub DemoTable()
 'Declarations
 Dim Filter As String
 Dim oRow As Outlook.Row
 Dim oTable As Outlook.Table
 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after November 1, 2005
 Filter = "[LastModificationTime] > '11/1/2005'"
 'Restrict with Filter
 Set oTable = oFolder.GetTable(Filter)

 'Enumerate the table using test for EndOfTable
 Do Until (oTable.EndOfTable)
 Set oRow = oTable.GetNextRow()
 Debug.Print (oRow("EntryID"))
 Debug.Print (oRow("Subject"))
 Debug.Print (oRow("CreationTime"))
 Debug.Print (oRow("LastModificationTime"))
 Debug.Print (oRow("MessageClass"))
 Loop
End Sub

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Parent Property (Outlook)

 Copy code hover
[image]

Table.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the Table object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a Table object.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Session Property (Outlook)

 Copy code hover
[image]

Table.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a Table object.

Remarks

The Session property and the Application.GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Table Object

Other resources

Table Object Members


Table Methods (Outlook)

 Copy code hover
[image]

Table Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
FindNextRow | Finds the next row in the Table that meets the criteria specified in a preceding Table.FindRow.
FindRow | Finds the first row in the Table that meets the criteria specified in Filter.
GetArray | Obtains a two-dimensional array that contains a set of row and column values from the Table.
GetNextRow | Moves the current row to the next row in the Table and obtains that row in the Table.
GetRowCount | Obtains the number of rows in the Table.
MoveToStart | Moves the current row of the Table to just before the first row of the Table.
Restrict | Applies a filter to the rows in the Table and obtains a new Table object.
Sort | Sorts the rows of the Table by the property specified in SortProperty and resets the current row to just before the first row in the Table.


Table.FindNextRow Method (Outlook)

 Copy code hover
[image]

Table.FindNextRow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Finds the next row in the Table that meets the criteria specified in a preceding Table.FindRow.

Version Information

Version Added: Outlook 2007

Syntax

expression .FindNextRow

expression A variable that represents a Table object.

Return Value

A Row object that represents the next row in the Table that meets the filter condition in the preceding call to FindRow. Returns Null (Nothing in Visual Basic) if FindNextRow cannot find another row that meets the criteria specified in FindRow. Also returns Null if FindRow has not been called before FindNextRow.

Remarks

FindNextRow finds the next row based on the row returned by the preceding FindRow or FindNextRow. It does not depend on the current row (as the current row may have been repositioned since the preceding FindRow or FindNextRow, for example, by Table.MoveToStart).

If FindNextRow finds a row, it will position the current row to that row. If it does not find another row, it will not reposition the current row.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.FindRow Method (Outlook)

 Copy code hover
[image]

Table.FindRow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Finds the first row in the Table that meets the criteria specified in Filter.

Version Information

Version Added: Outlook 2007

Syntax

expression .FindRow(Filter)

expression A variable that represents a Table object.

Parameters

Name | Required/Optional | Data Type | Description
Filter | Required | String | Specifies the condition that a row in the Table has to meet.

Return Value

A Row object that represents the first row in the Table that meets the filter criteria. Returns Null (Nothing in Visual Basic) if no such row can be found, or the Table does not contain any rows.

Remarks

FindRow always starts from the first row in the Table.

FindRow returns Null (Nothing in Visual Basic) if a property in Filter does not exist in the specified namespace. The property is considered a named property in the MAPI property set, PS_PUBLIC_STRINGS. FindRow does not return an error in this case.

FindRow returns an error if Filter is a blank string or an invalid restriction. In cases where FindRow does not find any row, the current row will not be repositioned to where it was before the call to FindRow.

To use content indexing search in a Table, use the Restrict method. FindRow returns an error if Filter contains content indexing keywords.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.GetArray Method (Outlook)

 Copy code hover
[image]

Table.GetArray Method (Outlook)
See also Send feedback

Obtains a two-dimensional array that contains a set of row and column values from the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetArray(MaxRows)

expression A variable that represents a Table object.

Parameters

Name | Required/Optional | Data Type | Description
MaxRows | Required | Long | Specifies the maximum number of rows to return from the Table.

Return Value

A Variant value that is a two-dimensional array representing a set of row and column values from the Table. The array is zero-based; an array index (i, j) indexes into the i-th column and j-th row in the array. Columns in the array correspond to columns in the Table, and rows in the array correspond to rows in the Table. The number of rows in the returned array is the lesser value of MaxRows and the actual number of rows in the Table.

Remarks

The GetArray method offers a conceptually simple means to get values from a Table by copying all or part of the data in the Table (based on the current row) to an array and indexing into the array.

GetArray always starts at the current row of the Table. It returns an array with MaxRows number of rows if there are at least MaxRows number of rows in the Table starting at the current position. If MaxRows is not larger than the total number of rows in the Table, and there are fewer than MaxRows number of elements in the Table starting at the current row, it will return an array that contains only the remaining rows in the Table. If GetArray is called and there are no remaining rows, then GetArray returns an empty array with zero elements.

After obtaining the appropriate rows from the Table and before it returns, GetArray always repositions the current row to the next row in the Table, if there exists a next row. GetArray(n) operates as if Table.GetNextRow is called n times.

The values in the columns map to columns in the Table, and are therefore determined by the format of the property name used for the column. For more information, see Factors Affecting Property Value Representation in the Table and View Classes.

Example

The following code sample obtains a Table by filtering on all items in the Inbox that contain "Office" in the subject. It then uses the Table.GetArray method to copy the data from the Table to an array, and prints the property value of each item returned.

For more information on specifying property names in a filter by namespace reference, see Referencing Properties by Namespace.

VBA Copy code Copy code
Sub DemoTableUsingGetArray()
 'Declarations
 Dim Filter As String
 Dim i, ubRows As Long
 Dim j, ubCols As Integer
 Dim varArray
 Dim oTable As Outlook.Table
 Dim oFolder As Outlook.Folder
 Const SchemaPropTag As String = _
 "http://schemas.microsoft.com/mapi/proptag/"

 On Error Resume Next
 'Get a Folder object for the Inbox
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)
 'Filter on the subject containing "Office"
 Filter = "@SQL=" & Chr(34) & SchemaPropTag & "0x0037001E" _
 & Chr(34) & " like '%Office%'"
 'Get all items in Inbox that meet the filter
 Set oTable = oFolder.GetTable(Filter)

 On Error GoTo Err_Trap
 varArray = oTable.GetArray(oTable.GetRowCount)

 'Number of rows is the second dimension of the array
 ubRows = UBound(varArray, 2)
 'Number of columns is the first dimension of the array
 ubCols = UBound(varArray)

 'Array is zero-based
 'Rows corrspond to items in the table, so for each item...
 For j = 0 To ubRows
 'Columns correspond to properties in the table, print the value of each property
 For i = 0 To ubCols
 Debug.Print varArray(i, j)
 Next
 Next
 Exit Sub

Err_Trap:
 Debug.Print "Error#:" & Err.Number & " Desc: " & Err.Description
 Resume Next
End Sub

See also

Concepts

Table Object

Other resources

Table Object Members


Table.GetNextRow Method (Outlook)

 Copy code hover
[image]

Table.GetNextRow Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves the current row to the next row in the Table and obtains that row in the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetNextRow

expression A variable that represents a Table object.

Return Value

A Row object that represents the next valid row in the Table if there are additional rows available. If there are no additional rows available (where Table.EndOfTable is True), GetNextRow will return Null (Nothing in Visual Basic).

See also

Concepts

Table Object

Other resources

Table Object Members


Table.GetRowCount Method (Outlook)

 Copy code hover
[image]

Table.GetRowCount Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains the number of rows in the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .GetRowCount

expression A variable that represents a Table object.

Return Value

A Long value that represents the number of rows in the Table.

Remarks

GetRowCount on a large table will result in a performance impact. Due to MAPI restrictions (for example, memory constraints for large tables, simultaneous operations on the Table), GetRowCount may not be able to determine the number of rows in the Table, or it may only only return an approximate row count. In these cases, GetRowCount will return an error. You should use appropriate error detection for GetRowCount to determine if the call returns an error.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.MoveToStart Method (Outlook)

 Copy code hover
[image]

Table.MoveToStart Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves the current row of the Table to just before the first row of the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .MoveToStart

expression A variable that represents a Table object.

Remarks

MoveToStart is equivalent to resetting the Table. If you call GetNextRow after you call MoveToStart, you will return a row representing the first row in the Table.

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Restrict Method (Outlook)

 Copy code hover
[image]

Table.Restrict Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies a filter to the rows in the Table and obtains a new Table object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Restrict(Filter)

expression A variable that represents a Table object.

Parameters

Name | Required/Optional | Data Type | Description
Filter | Required | String | Specifies the criteria for rows in the Table object.

Return Value

A Table object that is returned by applying Filter to the rows in the parent Table object.

Remarks

You can only use Table.Restrict to apply another filter to that Table if the parent object of the Table is a Folder object. If the parent object is a Search object, Restrict will return an error.

Since the filter is applied to the rows in the Table object, this is equivalent to applying a filter that is a logical AND of Filter and all preceding filters applied to the same Table object.

Filter is a query on specified properties of items that are represented as rows in the parent Table. The query uses either the Microsoft Jet syntax or the DAV Searching and Locating (DASL) syntax. For example, the following Jet filter and DASL filter specify the same criteria for items with LastModificationTime earlier than 3:30pm of June 12, 2005:

Copy code Copy code
criteria = "[LastModificationTime] < '" & Format$("6/12/2005 3:30PM","General Date") & "'"criteria = "@SQL=" & Chr(34) & "DAV:getlastmodified" & Chr(34)
 & " < '" & Format$("6/12/2005 3:30PM","General Date") & "'"

For more information on specifying filters for the Table object, see Filtering Items.

If Filter contains custom properties, those properties must exist in the parent folder of the Table object in order for the restriction to work correctly. Certain properties are not supported in a Table filter, including binary properties, computed properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter.

If Filter is a blank string, Restrict returns a Table object that is identical to the parent Table object.

Example

The following code sample applies a Jet filter on items in the Inbox to obtain items with a LastModificationTime greater than November 1, 2005. It then prints the values of the default properties for these items in the Inbox: EntryID, Subject, CreationTime, LastModificationTime, and MessageClass.

Note Note

Since heterogeneous items can exist in the same folder in Outlook, the items returned from applying the filter to the Inbox may be of different types. In general, before accessing any properties that are not among the default properties for items in the Inbox, you should check the MessageClass of the item.

VBA Copy code Copy code
Sub RestrictTable()
 'Declarations
 Dim Filter As String
 Dim oRow As Outlook.Row
 Dim oTable As Outlook.Table
 Dim oFolder As Outlook.Folder

 'Get a Folder object for the Inbox
 Set oFolder = Application.Session.GetDefaultFolder(olFolderInbox)

 'Define Filter to obtain items last modified after November 1, 2005
 Filter = "[LastModificationTime] > '11/1/2005'"
 'Restrict with Filter
 Set oTable = oFolder.GetTable(Filter)

 'Enumerate the table using test for EndOfTable
 Do Until (oTable.EndOfTable)
 Set oRow = oTable.GetNextRow()
 Debug.Print (oRow("EntryID"))
 Debug.Print (oRow("Subject"))
 Debug.Print (oRow("CreationTime"))
 Debug.Print (oRow("LastModificationTime"))
 Debug.Print (oRow("MessageClass"))
 Loop
End Sub

See also

Concepts

Table Object

Other resources

Table Object Members


Table.Sort Method (Outlook)

 Copy code hover
[image]

Table.Sort Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sorts the rows of the Table by the property specified in SortProperty and resets the current row to just before the first row in the Table.

Version Information

Version Added: Outlook 2007

Syntax

expression .Sort(SortProperty, Descending)

expression A variable that represents a Table object.

Parameters

Name | Required/Optional | Data Type | Description
SortProperty | Required | String | Specifies the property to use to sort the rows of the Table.
Descending | Optional | Boolean | Whether to sort the Table in descending order.

Remarks

SortProperty can be any explicit built-in property or custom property, with the exception of binary and multi-valued properties. The property must be referenced by its explicit string name; it cannot be referenced by namespace. For futher information on specifying sort properties, see Sorting Items in a Folder.

Sorting the table is equivalent to calling a MoveToStart method. The cursor will be positioned to the start of the Table.

If Table.Sort and then Table.Restrict are called, the filtered items in the new Table will be sorted by the same SortProperty and SortOrder.

Table.Sort only supports sorting on a single column.

Example

The following code sample shows how to sort the rows in a Table based on the ReceivedTime property, and prints the value of the MAPI normalized subject property for each row in the sorted table.

Copy code Copy code
Sub SortTableByReceivedTime()

 Dim oT As Outlook.Table

 Dim oRow As Outlook.Row

 Set oT = Session.GetDefaultFolder(olFolderInbox).GetTable

 'Add normalized subject (subject without RE:, FW: and other prefixes)to the column set

 oT.Columns.Add ("http://schemas.microsoft.com/mapi/proptag/0x0E1D001E")

 'Sort by ReceivedTime in descending order

 oT.Sort "[ReceivedTime]", True

 Do Until oT.EndOfTable

 Set oRow = oT.GetNextRow

 'Print the normalized subject of each row

 Debug.Print oRow("http://schemas.microsoft.com/mapi/proptag/0x0E1D001E")

 Loop

End Sub

See also

Concepts

Table Object

Other resources

Table Object Members


TableView Object (Outlook)

 Copy code hover
[image]

TableView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items in a table, with each item in a row and the details of the item in the columns.

Version Information

Version Added: Outlook 2007

Remarks

The TableView object, derived from the View object, allows you to create customizable views that allow you to display Outlook items in a table.

Outlook provides several built-in TableView objects, and you can also create custom TableView objects. Use the Add method of the Views collection to add a new TableView to a Folder object. Use the Standard property to determine if an existing TableView object is built-in or custom.

You can configure the appearance and functionality of the TableView object. Use the AutomaticColumnSizing property to determine whether the view automatically resizes columns and the AutomaticGrouping property to determine if the view automatically groups Outlook items. Use the AutoPreview property to determine whether preview information is displayed within the row for an Outlook item in the view, and the AutoPreviewFont property to specify the font used to display preview information. Use the Multiline property to determine whether to show Outlook items in multiline mode.

You can also configure how Outlook items appear within the TableView object. Use the ColumnFont property to specify the font used for column headers and the RowFont property to specify the font used for Outlook items in the view. Use the AllowInCellEditing property to allow editing of Outlook item property values in the view. Use the Filter property to determine which Outlook items to display in the view and the ViewFields collection to specify the Outlook item properties to display for each Outlook item. Use the GroupByFields to specify the Outlook item properties by which Outlook items are grouped, and the SortFields collection to specify the Outlook item properties by which Outlook items are sorted in the view.

The definition for each TableView object is stored in Extensible Markup Language (XML) format. Use the XML property to work with the XML definition for the TableView object.

Use the Apply method to apply any changes made to the TableView object to the current view. Use the Save method to persist any changes made to the TableView object. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

You can change built-in TableView objects, but you cannot delete them. Use the Delete method to delete a custom TableView object. Use the Reset method to reset the properties of a built-in TableView object to their default values.

See also

Concepts

Outlook Object Model Reference

Other resources

TableView Object Members


TableView Members (Outlook)

 Copy code hover
[image]

TableView Members (Outlook)
Send feedback

Represents a view that displays Outlook items in a table, with each item in a row and the details of the item in the columns.

Methods

Name | Description
Apply | Applies the TableView object to the current view.
Copy | Creates a new View object based on the existing TableView object.
Delete | Deletes an object from a collection.
GetTable | Returns a Table object that represents all of the Microsoft Outlook items that are contained in a TableView object.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
AllowInCellEditing | Returns or sets a Boolean value that determines whether in-cell editing is allowed in the TableView object. Read/write.
AlwaysExpandConversation | Returns or sets a Boolean value that indicates whether conversations are always fully expanded in the table view. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the TableView object. Read-only.
AutomaticColumnSizing | Returns or sets a Boolean value that indicates whether the columns in the TableView object are automatically sized by Outlook. Read/write.
AutomaticGrouping | Returns or sets a Boolean value that indicates whether the automatic grouping is active in the TableView object. Read/write.
AutoPreview | Returns or sets an OlAutoPreview constant that determines how items are automatically previewed by the TableView object. Read/write.
AutoPreviewFont | Returns a ViewFont object that represents the font used when automatically previewing Outlook items in the TableView object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ColumnFont | Returns a ViewFont object that represents the font used when displaying column headers in the TableView object. Read-only.
DefaultExpandCollapseSetting | Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TableView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
GridLineStyle | Returns or sets an OlGridLineStyle constant that represents the line style used for grid lines in the TableView object. Read/write.
GroupByFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are grouped. Read-only.
HideReadingPaneHeaderInfo | Returns or sets a Boolean value that determines whether the header for an Outlook item is displayed in the Reading Pane for the TableView object. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MaxLinesInMultiLineView | Returns or sets a Long value that determines the maximum number of lines displayed in multiline mode for the TableView object. Read/write.
MultiLine | Returns or sets an OlMultiLine constant that determines how multiple lines are displayed in the TableView object. Read/write.
MultiLineWidth | Returns or sets a Long value that represents the text width (in characters) needed to trigger multiline mode in the TableView object . Read/write
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RowFont | Returns a ViewFont object that represents the font used when displaying rows in the TableView object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowConversationByDate | Returns or sets a Boolean value that indicates whether items in a conversation are organized vertically left-aligned and ordered by the received date and time, with the most recent item on top. Read/write.
ShowConversationSendersAboveSubject | Returns or sets a Boolean value that indicates whether the table view displays the participating senders above the subject line in the conversation header, or below it. Read/write.
ShowFullConversations | Returns or sets a Boolean value that indicates whether to display conversation items from other folders, such as the Sent Items folder, as part of the conversation in the table view. Read/write.
ShowItemsInGroups | Returns or sets a Boolean value that determines whether Outlook items are shown in groups within the TableView object. Read/write.
ShowNewItemRow | Returns or sets a Boolean value that determines if the new item row is displayed in the TableView object. Read/write
ShowReadingPane | Returns or sets a Boolean value that indicates whether the Reading Pane is displayed in the TableView object. Read/write.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the TableView object is a built-in Outlook view. Read-only.
ViewFields | Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the TableView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


TableView Properties (Outlook)

 Copy code hover
[image]

TableView Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
AllowInCellEditing | Returns or sets a Boolean value that determines whether in-cell editing is allowed in the TableView object. Read/write.
AlwaysExpandConversation | Returns or sets a Boolean value that indicates whether conversations are always fully expanded in the table view. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
AutoFormatRules | Returns an AutoFormatRules object that represents the set of formatting rules applicable to the TableView object. Read-only.
AutomaticColumnSizing | Returns or sets a Boolean value that indicates whether the columns in the TableView object are automatically sized by Outlook. Read/write.
AutomaticGrouping | Returns or sets a Boolean value that indicates whether the automatic grouping is active in the TableView object. Read/write.
AutoPreview | Returns or sets an OlAutoPreview constant that determines how items are automatically previewed by the TableView object. Read/write.
AutoPreviewFont | Returns a ViewFont object that represents the font used when automatically previewing Outlook items in the TableView object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ColumnFont | Returns a ViewFont object that represents the font used when displaying column headers in the TableView object. Read-only.
DefaultExpandCollapseSetting | Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TableView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
GridLineStyle | Returns or sets an OlGridLineStyle constant that represents the line style used for grid lines in the TableView object. Read/write.
GroupByFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are grouped. Read-only.
HideReadingPaneHeaderInfo | Returns or sets a Boolean value that determines whether the header for an Outlook item is displayed in the Reading Pane for the TableView object. Read/write.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
MaxLinesInMultiLineView | Returns or sets a Long value that determines the maximum number of lines displayed in multiline mode for the TableView object. Read/write.
MultiLine | Returns or sets an OlMultiLine constant that determines how multiple lines are displayed in the TableView object. Read/write.
MultiLineWidth | Returns or sets a Long value that represents the text width (in characters) needed to trigger multiline mode in the TableView object . Read/write
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
RowFont | Returns a ViewFont object that represents the font used when displaying rows in the TableView object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowConversationByDate | Returns or sets a Boolean value that indicates whether items in a conversation are organized vertically left-aligned and ordered by the received date and time, with the most recent item on top. Read/write.
ShowConversationSendersAboveSubject | Returns or sets a Boolean value that indicates whether the table view displays the participating senders above the subject line in the conversation header, or below it. Read/write.
ShowFullConversations | Returns or sets a Boolean value that indicates whether to display conversation items from other folders, such as the Sent Items folder, as part of the conversation in the table view. Read/write.
ShowItemsInGroups | Returns or sets a Boolean value that determines whether Outlook items are shown in groups within the TableView object. Read/write.
ShowNewItemRow | Returns or sets a Boolean value that determines if the new item row is displayed in the TableView object. Read/write
ShowReadingPane | Returns or sets a Boolean value that indicates whether the Reading Pane is displayed in the TableView object. Read/write.
SortFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are ordered. Read-only.
Standard | Returns a Boolean value that indicates whether the TableView object is a built-in Outlook view. Read-only.
ViewFields | Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the TableView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


TableView.AllowInCellEditing Property (Outlook)

 Copy code hover
[image]

TableView.AllowInCellEditing Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether in-cell editing is allowed in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AllowInCellEditing

expression A variable that represents a TableView object.

Remarks

If this property is set to True, then the Multiline property of the TableView object is automatically set to olAlwaysSingleLine.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AlwaysExpandConversation Property (Outlook)

 Copy code hover
[image]

TableView.AlwaysExpandConversation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether conversations are always fully expanded in the table view. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .AlwaysExpandConversation

expression A variable that represents a TableView object.

Remarks

The AlwaysExpandConversation property is analogous to selecting Always Expand Conversations in the Conversations menu of the Arrangement group on the View tab of the ribbon.

True indicates that conversation groups are fully expanded in the table view by default; False indicates conversation groups are only partially expanded.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Application Property (Outlook)

 Copy code hover
[image]

TableView.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AutoFormatRules Property (Outlook)

 Copy code hover
[image]

TableView.AutoFormatRules Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an AutoFormatRules object that represents the set of formatting rules applicable to the TableView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoFormatRules

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AutomaticColumnSizing Property (Outlook)

 Copy code hover
[image]

TableView.AutomaticColumnSizing Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the columns in the TableView object are automatically sized by Outlook. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutomaticColumnSizing

expression A variable that represents a TableView object.

Remarks

If this property is set to False, then the Multiline property of the TableView object is automatically set to olAlwaysSingleLine.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AutomaticGrouping Property (Outlook)

 Copy code hover
[image]

TableView.AutomaticGrouping Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the automatic grouping is active in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutomaticGrouping

expression A variable that represents a TableView object.

Remarks

If this property is set to True, items are automatically grouped in the view according to the arrangement specified in the Outlook user interface. If this property is set to False, items are grouped in the view according to the contents of the GroupByFields property.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AutoPreview Property (Outlook)

 Copy code hover
[image]

TableView.AutoPreview Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlAutoPreview constant that determines how items are automatically previewed by the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoPreview

expression A variable that represents a TableView object.

Example

The following Visual Basic for Applications (VBA) example sets the AutoPreview property to olAutoPreviewUnread for every TableView object associated with the current Folder object.

Copy code Copy code
Private Sub PreviewUnreadOnly()

 Dim objFolder As Folder

 Dim objView As View

 Dim objTableView As TableView

 ' Retrieve a Folder object reference

 ' for the current folder

 Set objFolder = Application.ActiveExplorer.CurrentFolder

 ' Enumerate through the Views collection for the

 ' Folder object.

 For Each objView In objFolder.Views

 ' Check if the view is a table view.

 If objView.ViewType = olTableView Then

 ' Cast the View object to a TableView object.

 Set objTableView = objView

 ' Set the view so that only unread messages

 ' are automatically previewed.

 objTableView.AutoPreview = olAutoPreviewUnread

 ' Save the table view.

 objTableView.Save

 End If

 Next

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.AutoPreviewFont Property (Outlook)

 Copy code hover
[image]

TableView.AutoPreviewFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used when automatically previewing Outlook items in the TableView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .AutoPreviewFont

expression A variable that represents a TableView object.

Example

The following Visual Basic for Applications (VBA) sample decrements the value of the Size property for the ViewFont object returned from the AutoPreviewFont property for the current TableView object.

Copy code Copy code
Private Sub ReduceAutoPreviewFontSize()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Decrement the Size property of the

 ' ViewFont object obtained from the

 ' AutoPreviewFont property, but only

 ' if the font is 6 points or larger.

 If objTableView.AutoPreviewFont.Size > 5 Then

 objTableView.AutoPreviewFont.Size = _

 objTableView.AutoPreviewFont.Size - 1

 ' Save the table view.

 objTableView.Save

 End If

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Class Property (Outlook)

 Copy code hover
[image]

TableView.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ColumnFont Property (Outlook)

 Copy code hover
[image]

TableView.ColumnFont Property (Outlook)
See also Send feedback

Returns a ViewFont object that represents the font used when displaying column headers in the TableView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ColumnFont

expression A variable that represents a TableView object.

Example

The following Visual Basic for Applications (VBA) sample increments the value of the Size property for the ViewFont object returned from the ColumnFont property for the current TableView object.

Copy code Copy code
Private Sub IncreaseColumnFontSize()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Increment the Size property of the

 ' ViewFont object obtained from the

 ' ColumnFont property, but only

 ' if the font is less than 24 points

 ' in size.

 If objTableView.ColumnFont.Size < 24 Then

 objTableView.ColumnFont.Size = _

 objTableView.ColumnFont.Size + 1

 ' Save the table view.

 objTableView.Save

 End If

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.DefaultExpandCollapseSetting Property (Outlook)

 Copy code hover
[image]

TableView.DefaultExpandCollapseSetting Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultExpandCollapseSetting

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Filter Property (Outlook)

 Copy code hover
[image]

TableView.Filter Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents a TableView object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.GridLineStyle Property (Outlook)

 Copy code hover
[image]

TableView.GridLineStyle Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlGridLineStyle constant that represents the line style used for grid lines in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .GridLineStyle

expression A variable that represents a TableView object.

Example

The following Visual Basic for Applications (VBA) example sets the GridLineStyle property of the current TableView object to display the grid with small dotted lines.

Copy code Copy code
Private Sub SetDottedGridLines()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 With objTableView

 ' Set the GridLineStyle property so that

 ' the grid in the table view are

 ' displayed with thin dotted lines.

 .GridLineStyle = olGridLineSmallDots

 ' Save the table view.

 .Save

 End With

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.GroupByFields Property (Outlook)

 Copy code hover
[image]

TableView.GroupByFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are grouped. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GroupByFields

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.HideReadingPaneHeaderInfo Property (Outlook)

 Copy code hover
[image]

TableView.HideReadingPaneHeaderInfo Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the header for an Outlook item is displayed in the Reading Pane for the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .HideReadingPaneHeaderInfo

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Language Property (Outlook)

 Copy code hover
[image]

TableView.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the language setting for the view. Read/write.

Syntax

expression .Language

expression A variable that represents a TableView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the language type of all View objects of type olTableView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olTableVIew then set language.

 If objView.ViewType = olTableView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

TableView.LockUserChanges Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression A variable that represents a TableView object.

Remarks

If True, the user can modify the settings of the specified view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.MaxLinesInMultiLineView Property (Outlook)

 Copy code hover
[image]

TableView.MaxLinesInMultiLineView Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that determines the maximum number of lines displayed in multiline mode for the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MaxLinesInMultiLineView

expression A variable that represents a TableView object.

Remarks

This property can be set to a value between 2 and 20. If this property is set to a value less than 2, the property is set to 2. If this property is set to a value greater than 20, the property is set to 20. The default value for this property is 2.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.MultiLine Property (Outlook)

 Copy code hover
[image]

TableView.MultiLine Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlMultiLine constant that determines how multiple lines are displayed in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Multiline

expression A variable that represents a TableView object.

Remarks

If the value of the AutomaticColumnSizing property is set to False or if the value of the AllowInCellEditing property is set to True, the value of this property is automatically set to olAlwaysSingleLine.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.MultiLineWidth Property (Outlook)

 Copy code hover
[image]

TableView.MultiLineWidth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the text width (in characters) needed to trigger multiline mode in the TableView object . Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .MultiLineWidth

expression A variable that represents a TableView object.

Remarks

This property can be set to a value between 1 and 999. If this property is set to a value less than 1, the property is set to 1. If this property is set to a value greater than 999, the property is set to 999. The default value for this property is 100.

This property only applies if the Multiline property of the TableView object is set to olWidthMultiLine. The value of this property determines the point at which the TableView object displays text for an Outlook item in multiline mode.

Example

The following Visual Basic for Applications (VBA) example configures the current TableView object so that, if text in the view is longer than 50 characters, the text is displayed in multiline mode. The MultiLine property cannot be set to olWidthMultiLine unless the AutomaticColumnSizing property is set to True.

Copy code Copy code
Private Sub ConfigureMultiLineView()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 With objTableView

 ' Set the TableView object so that,

 ' if the text in the view is longer

 ' than 50 characters, the text is

 ' displayed in multiline mode.

 .AutomaticColumnSizing = True

 .MultiLine = olWidthMultiLine

 .MultiLineWidth = 50

 ' Save the table view.

 .Save

 End With

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Name Property (Outlook)

 Copy code hover
[image]

TableView.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Parent Property (Outlook)

 Copy code hover
[image]

TableView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.RowFont Property (Outlook)

 Copy code hover
[image]

TableView.RowFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used when displaying rows in the TableView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .RowFont

expression A variable that represents a TableView object.

Example

The following Visual Basic for Applications (VBA) sample increments the value of the Size property for the ViewFont object returned from the RowFont property for the current TableView object.

Copy code Copy code
Private Sub IncreaseRowFontSize()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Increment the Size property of the

 ' ViewFont object obtained from the

 ' RowFont property, but only

 ' if the font is less than 24 points

 ' in size.

 If objTableView.RowFont.Size < 24 Then

 objTableView.RowFont.Size = _

 objTableView.RowFont.Size + 1

 ' Save the table view.

 objTableView.Save

 End If

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.SaveOption Property (Outlook)

 Copy code hover
[image]

TableView.SaveOption Property (Outlook)
See also Send feedback

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression A variable that represents a TableView object.

Remarks

The value of the SaveOption property is set when the TableView object is created using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = _

 olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Session Property (Outlook)

 Copy code hover
[image]

TableView.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TableView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowConversationByDate Property (Outlook)

 Copy code hover
[image]

TableView.ShowConversationByDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether items in a conversation are organized vertically left-aligned and ordered by the received date and time, with the most recent item on top. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .ShowConversationByDate

expression A variable that represents a TableView object.

Remarks

If the table view is not organized by conversation, setting the ShowConversationByDate property does not reorganize any items in the view. To display items by conversation, in the Conversations group of the View tab in the ribbon, select Show as Conversations.

Setting the ShowConversationByDate property to True vertically left-aligns conversation items and orders them by their received date and time, with the most recent item on top. This organization in the conversation view is the same as having cleared the Use Classic Indented View setting in the Conversations Settings menu in the Conversations group of the ribbon.

Setting the ShowConversationByDate property to False indents conversation items and orders them by their received date and time, with the earliest item on top. The root of each thread of the conversation is displayed first, followed by items belonging to that thread, each left-indented from the last. This organization in the conversation view is the same as having selected the Use Classic Indented View setting in the Conversations Settings menu in the Conversations group of the ribbon.

To apply a change to the ShowConversationByDate property to the view, call the Apply method. Conversations are then displayed as collapsed in the conversation view. If you expand a conversation, you will see items in the conversation reorganized and displayed the way you set the ShowConversationByDate property.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) checks if the current view of the current folder is a table view, assumes items are displayed by conversation, sets the ShowConversationByDate property to true, and calls the Apply method to apply the organization to the current view.

VBA Copy code Copy code
Sub GetConversationViewSettings()

 Dim oCurrentFolder As Outlook.folder

 Dim oView As Outlook.tableView

 Set oCurrentFolder = Application.ActiveExplorer.currentfolder

 If oCurrentFolder.currentView.ViewType = olTableView Then

 Set oView = oCurrentFolder.currentView

 oView.ShowConversationByDate = True

 oView.Apply

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowConversationSendersAboveSubject Property (Outlook)

 Copy code hover
[image]

TableView.ShowConversationSendersAboveSubject Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that indicates whether the table view displays the participating senders above the subject line in the conversation header, or below it. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .ShowConversationSendersAboveSubject

expression A variable that represents a TableView object.

Remarks

True indicates that the table view displays the participating senders above the subject line in the conversation header. False indicates that the table view displays the participating senders below the subject line in the conversation header.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowFullConversations Property (Outlook)

 Copy code hover
[image]

TableView.ShowFullConversations Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether to display conversation items from other folders, such as the Sent Items folder, as part of the conversation in the table view. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .ShowFullConversations

expression A variable that represents a TableView object.

Remarks

The ShowFullConversations property takes effect only if the current table view displays items by date and conversation.

True indicates that items of the same conversation are displayed by default as part of the conversation in the table view. False indicates that only conversation items in the current folder are displayed in the table view.

The ShowFullConversations property is analogous to selecting Show Messages from Other Folders in the Conversations menu of the Arrangement group on the View tab of the ribbon.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowItemsInGroups Property (Outlook)

 Copy code hover
[image]

TableView.ShowItemsInGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether Outlook items are shown in groups within the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowItemsInGroups

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowNewItemRow Property (Outlook)

 Copy code hover
[image]

TableView.ShowNewItemRow Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines if the new item row is displayed in the TableView object. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowNewItemRow

expression A variable that represents a TableView object.

Remarks

The value of this property applies only if the AllowInCellEditing property is set to True.

Example

The following Visual Basic for Applications (VBA) example configures the current TableView object so that in-cell editing is allowed and the new item row is displayed in the view.

Copy code Copy code
Private Sub ConfigureEditableView()

 Dim objTableView As TableView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 With objTableView

 ' ShowNewItemRow is ignored if

 ' AllowInCellEditing is set to

 ' False.

 .AllowInCellEditing = True

 ' Display the new item row in

 ' the table view.

 .ShowNewItemRow = True

 ' Save the table view.

 .Save

 End With

 End If

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ShowReadingPane Property (Outlook)

 Copy code hover
[image]

TableView.ShowReadingPane Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether the Reading Pane is displayed in the TableView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowReadingPane

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.SortFields Property (Outlook)

 Copy code hover
[image]

TableView.SortFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields object that represents the set of fields by which the items displayed in the TableView object are ordered. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SortFields

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Standard Property (Outlook)

 Copy code hover
[image]

TableView.Standard Property (Outlook)
See also Send feedback

Returns a Boolean value that indicates whether the TableView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression A variable that represents a TableView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object, using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ViewFields Property (Outlook)

 Copy code hover
[image]

TableView.ViewFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFields object that represents the set of fields with which Outlook items are displayed in the TableView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewFields

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.ViewType Property (Outlook)

 Copy code hover
[image]

TableView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.XML Property (Outlook)

 Copy code hover
[image]

TableView.XML Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression A variable that represents a TableView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView Methods (Outlook)

 Copy code hover
[image]

TableView Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Apply | Applies the TableView object to the current view.
Copy | Creates a new View object based on the existing TableView object.
Delete | Deletes an object from a collection.
GetTable | Returns a Table object that represents all of the Microsoft Outlook items that are contained in a TableView object.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


TableView.Apply Method (Outlook)

 Copy code hover
[image]

TableView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the TableView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Copy Method (Outlook)

 Copy code hover
[image]

TableView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing TableView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents a TableView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Delete Method (Outlook)

 Copy code hover
[image]

TableView.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.GetTable Method (Outlook)

 Copy code hover
[image]

TableView.GetTable Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Table object that represents all of the Microsoft Outlook items that are contained in a TableView object.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetTable

expression A variable that represents a TableView object.

Return Value

A Table whose rows represent items in the current table view.

Remarks

The GetTable method of the TableView object returns a table of items from one or more folders in the same store or spanning over multiple stores, in an aggregated view. For example, an aggregated view obtained by a search across all mail items by using Instant Search. This behavior differs from the GetTable method of the Folder object, which obtains a table object that contains items from the same folder.

The parent TableView object must be based on the current folder of the active explorer, as indicated by the CurrentFolder property of the active Explorer object. If the folder is not a current folder of a visible explorer, or if the view of that folder, which is indicated by the Folder.CurrentView property, is not a table view, Outlook returns an error.

The filter for the resultant table is set by the Filter property of the TableView object. If the Filter property of the TableView object is not empty, GetTable returns a Table object with rows that represent the filtered subset of items available in the view. If subsequently, the Table.Restrict method is called on the resultant table, applying the Restrict method is equivalent to a logical AND operation with the filter represented by TableView.Filter.

GetTable returns a Table with the default column set. GetTable does not return a Table that contains columns for each field in the ViewFields collection of the current view. For more information on the default column set of a table based on the folder type, see Default Properties Displayed in a Table Object. To modify the default column set, use the Add, Remove, or RemoveAll methods of the Columns collection object. Properties that you cannot add to a table as columns are listed in Unsupported Properties in a Table Object or Table Filter.

The order of rows in the resultant table is not guaranteed to be the same as the order of items in the current view on which GetTable is based. For example, GetTable does not return a table with a row that represents a group-by header in the view. To sort the rows in the table returned from GetTable, use the Sort method of the Table object.

The parent object of the Table object returned by GetTable is the TableView object. The parent object of the TableView object is the Views collection, and the parent object of the Views collection is the Folder object.

Example

The following managed code is written in C#. To run a .NET Framework managed code sample that needs to call into a Component Object Model (COM), you must use an interop assembly that defines and maps managed interfaces to the COM objects in the object model type library. For Outlook, you can use Visual Studio and the Outlook Primary Interop Assembly (PIA). Before you run managed code samples for Outlook 2013, ensure that you have installed the Outlook 2013 PIA and have added a reference to the Microsoft Outlook 15.0 Object Library component in Visual Studio. You should use the following code in the ThisAddIn class of an Outlook add-in (using Office Developer Tools for Visual Studio). The Application object in the code must be a trusted Outlook Application object provided by ThisAddIn.Globals. For more information about using the Outlook PIA to develop managed Outlook solutions, see the Welcome to the Outlook 2013 Primary Interop Assembly Reference on MSDN.

The following code example obtains a Table object from the current view of the Inbox folder. The code sample sets the current folder of the active explorer to the Inbox, and then checks that the current view of the Inbox is a table view. After assuring these two conditions, the code sample calls the TableView.GetTable method and displays each item represented by each row in the returned Table.

C# Copy code Copy code
private void DemoViewGetTable()
{
 // Obtain the Inbox folder.
 Outlook.Folder inbox =
 Application.Session.GetDefaultFolder(
 Outlook.OlDefaultFolders.olFolderInbox)
 as Outlook.Folder;

 // Set ActiveExplorer.CurrentFolder to Inbox.
 // Inbox must be the current folder
 // for TableView.GetTable to work correctly.
 Application.ActiveExplorer().CurrentFolder = inbox;

 // Ensure that the current view is a table view.
 if (inbox.CurrentView.ViewType ==
 Outlook.OlViewType.olTableView)
 {
 Outlook.TableView view =
 inbox.CurrentView as Outlook.TableView;

 // No arguments are needed for View.GetTable.
 Outlook.Table table = view.GetTable();

 Debug.WriteLine("View Count="
 + table.GetRowCount().ToString());
 while (!table.EndOfTable)
 {
 // First row in Table.
 Outlook.Row nextRow = table.GetNextRow();
 Debug.WriteLine(nextRow["Subject"]
 + " Modified: "
 + nextRow["LastModificationTime"]);
 }
 }
}

See also

Concepts

How to: Search and Obtain Items in an Aggregated View
TableView Object

Other resources

TableView Object Members


TableView.GoToDate Method (Outlook)

 Copy code hover
[image]

TableView.GoToDate Method (Outlook)
See also Send feedback

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents a TableView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Reset Method (Outlook)

 Copy code hover
[image]

TableView.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression A variable that represents a TableView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

TableView Object

Other resources

TableView Object Members


TableView.Save Method (Outlook)

 Copy code hover
[image]

TableView.Save Method (Outlook)
See also Send feedback

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a TableView object.

See also

Concepts

TableView Object

Other resources

TableView Object Members


TaskItem Object (Outlook)

 Copy code hover
[image]

TaskItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a task (an assigned, delegated, or self-imposed task to be performed within a specified time frame) in a Tasks folder.

Remarks

Use the CreateItem method to create a TaskItem object that represents a new task.

Use Items(index), where index is the index number of a task or a value used to match the default property of a task, to return a single TaskItem object from a Tasks folder.

Example

The following Visual Basic for Applications (VBA) example returns a new task.

VBA Copy code Copy code
Set myItem = Application.CreateItem(olTaskItem)

See also

Concepts

Outlook Object Model Reference

Other resources

TaskItem Object Members


TaskItem Members (Outlook)

 Copy code hover
[image]

TaskItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a task (an assigned, delegated, or self-imposed task to be performed within a specified time frame) in a Tasks folder.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Assign | Assigns a task and returns a TaskItem object that represents it.
CancelResponseState | Resets an unsent response to a task request back to a simple task.
ClearRecurrencePattern | Removes the recurrence settings and restores the single-occurrence state for an appointment or task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetRecurrencePattern | Returns a RecurrencePattern object that represents the recurrence attributes of a task. If there is no existing recurrence pattern, a new empty RecurrencePattern object is returned.
MarkComplete | Marks the task as completed.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Respond | Responds to a task request.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the task.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
SkipRecurrence | Clears the current instance of a recurring task and sets the recurrence to the next instance of that task.
StatusReport | Sends a status report to all Cc recipients (recipients returned by the StatusUpdateRecipients property) with the current status for the task and returns an Object representing the status report.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
ActualWork | Returns or sets a Long indicating the actual effort spent on the task. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
CardData | Returns or sets a String representing the text of the card data for the task. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Complete | Returns a Boolean value that indicates whether the task is completed. Read/write Boolean.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ContactNames | Returns or sets a String representing the contact names associated with the Outlook item. Read/write.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DateCompleted | Returns or sets a Date indicating the completion date of the task. Read/write.
DelegationState | Returns an OlTaskDelegationState constant indicating the delegation state of the task. Read-only.
Delegator | Returns a String representing the display name of the delegator for the task. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
DueDate | Returns or sets a Date indicating the due date for the task. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsRecurring | Returns a Boolean value that is True if the task is a recurring task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
Ordinal | Returns or sets a Long specifying the position in the view (ordinal) for the task. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Owner | Returns or sets a String indicating the owner for the task.
Ownership | Returns an OlTaskOwnership specifying the ownership state of the task. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PercentComplete | Returns or sets a Long indicating the percentage of the task completed at the current date and time. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
ResponseState | Returns an OlTaskResponse constant indicating the overall status of the response to the specified task request. Read-only.
Role | Returns or sets a String containing the free-form text string associating the owner of a task with a role for the task. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SchedulePlusPriority | Returns or sets a String representing the Microsoft Schedule+ priority for the task. Read/write.
SendUsingAccount | Returns or sets an Account object that represents the account under which the TaskItem object is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
StartDate | Returns or sets a Date indicating the start date for the task. Read/write.
Status | Returns or sets an OlTaskStatus constant specifying the status for the task. Corresponds to the Status field of a TaskItem . Read/write.
StatusOnCompletionRecipients | Returns or sets a semicolon-delimited String of display names for recipients who will receive status upon completion of the task. Read/write.
StatusUpdateRecipients | Returns a semicolon-delimited String of display names for recipients who receive status updates for the task. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TeamTask | Returns a Boolean that indicates True if the task is a team task. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the TaskItem. Read/write.
TotalWork | Returns or sets a Long indicating the total work for the task. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskItem Properties (Outlook)

 Copy code hover
[image]

TaskItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
ActualWork | Returns or sets a Long indicating the actual effort spent on the task. Read/write.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
CardData | Returns or sets a String representing the text of the card data for the task. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Complete | Returns a Boolean value that indicates whether the task is completed. Read/write Boolean.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ContactNames | Returns or sets a String representing the contact names associated with the Outlook item. Read/write.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DateCompleted | Returns or sets a Date indicating the completion date of the task. Read/write.
DelegationState | Returns an OlTaskDelegationState constant indicating the delegation state of the task. Read-only.
Delegator | Returns a String representing the display name of the delegator for the task. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
DueDate | Returns or sets a Date indicating the due date for the task. Read/write.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
InternetCodepage | Returns or sets a Long that determines the Internet code page used by the item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
IsRecurring | Returns a Boolean value that is True if the task is a recurring task. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
Ordinal | Returns or sets a Long specifying the position in the view (ordinal) for the task. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Owner | Returns or sets a String indicating the owner for the task.
Ownership | Returns an OlTaskOwnership specifying the ownership state of the task. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PercentComplete | Returns or sets a Long indicating the percentage of the task completed at the current date and time. Read/write.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskItem object. Read-only.
Recipients | Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.
ReminderOverrideDefault | Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.
ReminderPlaySound | Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.
ReminderSet | Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.
ReminderSoundFile | Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.
ReminderTime | Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.
ResponseState | Returns an OlTaskResponse constant indicating the overall status of the response to the specified task request. Read-only.
Role | Returns or sets a String containing the free-form text string associating the owner of a task with a role for the task. Read/write.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
SchedulePlusPriority | Returns or sets a String representing the Microsoft Schedule+ priority for the task. Read/write.
SendUsingAccount | Returns or sets an Account object that represents the account under which the TaskItem object is to be sent. Read/write.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
StartDate | Returns or sets a Date indicating the start date for the task. Read/write.
Status | Returns or sets an OlTaskStatus constant specifying the status for the task. Corresponds to the Status field of a TaskItem . Read/write.
StatusOnCompletionRecipients | Returns or sets a semicolon-delimited String of display names for recipients who will receive status upon completion of the task. Read/write.
StatusUpdateRecipients | Returns a semicolon-delimited String of display names for recipients who receive status updates for the task. Read/write.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
TeamTask | Returns a Boolean that indicates True if the task is a team task. Read/write.
ToDoTaskOrdinal | Returns or sets a Date value that represents the ordinal value of the task for the TaskItem. Read/write.
TotalWork | Returns or sets a Long indicating the total work for the task. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskItem.Actions Property (Outlook)

 Copy code hover
[image]

TaskItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ActualWork Property (Outlook)

 Copy code hover
[image]

TaskItem.ActualWork Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the actual effort spent on the task. Read/write.

Syntax

expression .ActualWork

expression A variable that represents a TaskItem object.

Remarks

ActualWork is stored in units of minutes. The ActualWork field on the standard task form is bound to the ActualWork property; by default the field assumes an 8-hour day and 40-hour week.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Application Property (Outlook)

 Copy code hover
[image]

TaskItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Attachments Property (Outlook)

 Copy code hover
[image]

TaskItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

TaskItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a TaskItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its TaskItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

TaskItem.BillingInformation Property (Outlook)
See also Send feedback

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a TaskItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Body Property (Outlook)

 Copy code hover
[image]

TaskItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.CardData Property (Outlook)

 Copy code hover
[image]

TaskItem.CardData Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the text of the card data for the task. Read/write.

Syntax

expression .CardData

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Categories Property (Outlook)

 Copy code hover
[image]

TaskItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a TaskItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Class Property (Outlook)

 Copy code hover
[image]

TaskItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Companies Property (Outlook)

 Copy code hover
[image]

TaskItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a TaskItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Complete Property (Outlook)

 Copy code hover
[image]

TaskItem.Complete Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the task is completed. Read/write Boolean.

Syntax

expression .Complete

expression A variable that represents a TaskItem object.

Remarks

True indicates that the task was completed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Conflicts Property (Outlook)

 Copy code hover
[image]

TaskItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ContactNames Property (Outlook)

 Copy code hover
[image]

TaskItem.ContactNames Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the contact names associated with the Outlook item. Read/write.

Syntax

expression .ContactNames

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ConversationID Property (Outlook)

 Copy code hover
[image]

TaskItem.ConversationID Property (Outlook)
See also Send feedback

Returns a String that uniquely identifies a Conversation object that the TaskItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a TaskItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the TaskItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

TaskItem.ConversationIndex Property (Outlook)
See also Send feedback

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

TaskItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.CreationTime Property (Outlook)

 Copy code hover
[image]

TaskItem.CreationTime Property (Outlook)
See also Send feedback

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.DateCompleted Property (Outlook)

 Copy code hover
[image]

TaskItem.DateCompleted Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the completion date of the task. Read/write.

Syntax

expression .DateCompleted

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.DelegationState Property (Outlook)

 Copy code hover
[image]

TaskItem.DelegationState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlTaskDelegationState constant indicating the delegation state of the task. Read-only.

Syntax

expression .DelegationState

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Delegator Property (Outlook)

 Copy code hover
[image]

TaskItem.Delegator Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the display name of the delegator for the task. Read-only.

Syntax

expression .Delegator

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.DownloadState Property (Outlook)

 Copy code hover
[image]

TaskItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a TaskItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.DueDate Property (Outlook)

 Copy code hover
[image]

TaskItem.DueDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the due date for the task. Read/write.

Syntax

expression .DueDate

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.EntryID Property (Outlook)

 Copy code hover
[image]

TaskItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.FormDescription Property (Outlook)

 Copy code hover
[image]

TaskItem.FormDescription Property (Outlook)
See also Send feedback

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.GetInspector Property (Outlook)

 Copy code hover
[image]

TaskItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a TaskItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Importance Property (Outlook)

 Copy code hover
[image]

TaskItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.InternetCodepage Property (Outlook)

 Copy code hover
[image]

TaskItem.InternetCodepage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long that determines the Internet code page used by the item. Read/write.

Syntax

expression .InternetCodepage

expression A variable that represents a TaskItem object.

Remarks

The Internet code page defines the text encoding scheme used by the item.

The following table lists the values that are supported by the InternetCodePage property.

Name | Character Set | Code Page
Arabic (ISO) | iso-8859-6 | 28596
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Baltic (Windows) | windows-1257 | 1257
Central European (ISO) | iso-8859-2 | 28592
Central European (Windows) | windows-1250 | 1250
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Simplified (HZ) | hz-gb-2312 | 52936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (ISO) | iso-8859-5 | 28595
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (KOI8-U) | koi8-u | 21866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Greek (Windows) | windows-1253 | 1253
Hebrew (ISO-Logical) | iso-8859-8-i | 38598
Hebrew (Windows) | windows-1255 | 1255
Japanese (EUC) | euc-jp | 51932
Japanese (JIS) | iso-2022-jp | 50220
Japanese (JIS-Allow 1 byte Kana) | csISO2022JP | 50221
Japanese (Shift-JIS) | iso-2022-jp | 932
Korean | ks_c_5601-1987 | 949
Korean (EUC) | euc-kr | 51949
Latin 3 (ISO) | iso-8859-3 | 28593
Latin 9 (ISO) | iso-8859-15 | 28605
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Turkish (Windows) | windows-1254 | 1254
Unicode (UTF-7) | utf-7 | 65000
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591
Western European (Windows) | Windows-1252 | 1252

The following table lists the code pages Microsoft recommends that you use for the best compatiblity with older e-mail systems.

Name | Character Set | Code Page
Arabic (Windows) | windows-1256 | 1256
Baltic (ISO) | iso-8859-4 | 28594
Central European (ISO) | iso-8859-2 | 28592
Chinese Simplified (GB2312) | gb2312 | 936
Chinese Traditional (Big5) | big5 | 950
Cyrillic (KOI8-R) | koi8-r | 20866
Cyrillic (Windows) | windows-1251 | 1251
Greek (ISO) | iso-8859-7 | 28597
Hebrew (Windows) | windows-1255 | 1255
Japanese (JIS) | iso-2022-jp | 50220
Korean | ks_c_5601-1987 | 949
Thai (Windows) | windows-874 | 874
Turkish (ISO) | iso-8859-9 | 28599
Unicode (UTF-8) | utf-8 | 65001
US-ASCII | us-ascii | 20127
Vietnamese (Windows) | windows-1258 | 1258
Western European (ISO) | iso-8859-1 | 28591

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.IsConflict Property (Outlook)

 Copy code hover
[image]

TaskItem.IsConflict Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a TaskItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.IsRecurring Property (Outlook)

 Copy code hover
[image]

TaskItem.IsRecurring Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the task is a recurring task. Read-only.

Syntax

expression .IsRecurring

expression A variable that represents a TaskItem object.

Remarks

When the GetRecurrencePattern method is used with a TaskItem object, this property is set to True.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

TaskItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a TaskItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

TaskItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

TaskItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a TaskItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.MessageClass Property (Outlook)

 Copy code hover
[image]

TaskItem.MessageClass Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Mileage Property (Outlook)

 Copy code hover
[image]

TaskItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a TaskItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.NoAging Property (Outlook)

 Copy code hover
[image]

TaskItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Ordinal Property (Outlook)

 Copy code hover
[image]

TaskItem.Ordinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long specifying the position in the view (ordinal) for the task. Read/write.

Syntax

expression .Ordinal

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

TaskItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

TaskItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Owner Property (Outlook)

 Copy code hover
[image]

TaskItem.Owner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the owner for the task.

Syntax

expression .Owner

expression A variable that represents a TaskItem object.

Remarks

This is a free-form string field. Setting this property to someone other than the current user does not have the effect of delegating the task. Read/write if the task is stored on the Exchange Server public folder. Read-only if it's stored in a user's mailbox or personal folders file.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Ownership Property (Outlook)

 Copy code hover
[image]

TaskItem.Ownership Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlTaskOwnership specifying the ownership state of the task. Read-only.

Syntax

expression .Ownership

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Parent Property (Outlook)

 Copy code hover
[image]

TaskItem.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.PercentComplete Property (Outlook)

 Copy code hover
[image]

TaskItem.PercentComplete Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the percentage of the task completed at the current date and time. Read/write.

Syntax

expression .PercentComplete

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

TaskItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Recipients Property (Outlook)

 Copy code hover
[image]

TaskItem.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents all the recipients for the Outlook item. Read-only.

Syntax

expression .Recipients

expression A variable that represents a TaskItem object.

Remarks

A recipient can be specified by a string representing the recipient's display name, alias, or full SMTP e-mail address.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReminderOverrideDefault Property (Outlook)

 Copy code hover
[image]

TaskItem.ReminderOverrideDefault Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder overrides the default reminder behavior for the item. Read/write.

Syntax

expression .ReminderOverrideDefault

expression A variable that represents a TaskItem object.

Remarks

You must set the ReminderOverrideDefault property to validate the ReminderPlaySound and the ReminderSoundFile properties.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReminderPlaySound Property (Outlook)

 Copy code hover
[image]

TaskItem.ReminderPlaySound Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True if the reminder should play a sound when it occurs for this item. Read/write.

Syntax

expression .ReminderPlaySound

expression A variable that represents a TaskItem object.

Remarks

The ReminderPlaySound property must be set in order to validate the ReminderSoundFile property.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReminderSet Property (Outlook)

 Copy code hover
[image]

TaskItem.ReminderSet Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if a reminder has been set for this item. Read/write.

Syntax

expression .ReminderSet

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReminderSoundFile Property (Outlook)

 Copy code hover
[image]

TaskItem.ReminderSoundFile Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the path and file name of the sound file to play when the reminder occurs for the Outlook item. Read/write.

Syntax

expression .ReminderSoundFile

expression A variable that represents a TaskItem object.

Remarks

This property is only valid if the ReminderOverrideDefault and ReminderPlaySound properties are set to True.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReminderTime Property (Outlook)

 Copy code hover
[image]

TaskItem.ReminderTime Property (Outlook)
See also Send feedback

Returns or sets a Date indicating the date and time at which the reminder should occur for the specified item. Read/write.

Syntax

expression .ReminderTime

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ResponseState Property (Outlook)

 Copy code hover
[image]

TaskItem.ResponseState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlTaskResponse constant indicating the overall status of the response to the specified task request. Read-only.

Syntax

expression .ResponseState

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Role Property (Outlook)

 Copy code hover
[image]

TaskItem.Role Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String containing the free-form text string associating the owner of a task with a role for the task. Read/write.

Syntax

expression .Role

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.RTFBody Property (Outlook)

 Copy code hover
[image]

TaskItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a TaskItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Saved Property (Outlook)

 Copy code hover
[image]

TaskItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.SchedulePlusPriority Property (Outlook)

 Copy code hover
[image]

TaskItem.SchedulePlusPriority Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the Microsoft Schedule+ priority for the task. Read/write.

Syntax

expression .SchedulePlusPriority

expression A variable that represents a TaskItem object.

Remarks

Can be 1 through 9, A through Z, or A1 through Z9. Priority 1 is the highest.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.SendUsingAccount Property (Outlook)

 Copy code hover
[image]

TaskItem.SendUsingAccount Property (Outlook)
See also Send feedback

Returns or sets an Account object that represents the account under which the TaskItem object is to be sent. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .SendUsingAccount

expression An expression that returns a TaskItem object.

Remarks

The SendUsingAccount property can be used to specify the account that should be used to send the TaskItem object when the Send method is called. This property returns Null (Nothing in Visual Basic) if the account specified for the TaskItem object no longer exists.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

TaskItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Session Property (Outlook)

 Copy code hover
[image]

TaskItem.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TaskItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Size Property (Outlook)

 Copy code hover
[image]

TaskItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.StartDate Property (Outlook)

 Copy code hover
[image]

TaskItem.StartDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date indicating the start date for the task. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartDate

expression An expression that returns a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Status Property (Outlook)

 Copy code hover
[image]

TaskItem.Status Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTaskStatus constant specifying the status for the task. Corresponds to the Status field of a TaskItem . Read/write.

Syntax

expression .Status

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.StatusOnCompletionRecipients Property (Outlook)

 Copy code hover
[image]

TaskItem.StatusOnCompletionRecipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a semicolon-delimited String of display names for recipients who will receive status upon completion of the task. Read/write.

Syntax

expression .StatusOnCompletionRecipients

expression A variable that represents a TaskItem object.

Remarks

This property is calculated from the Recipients property. Recipients returned by the StatusOnCompletionRecipients property correspond to BCC recipients in the Recipients collection.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.StatusUpdateRecipients Property (Outlook)

 Copy code hover
[image]

TaskItem.StatusUpdateRecipients Property (Outlook)
See also Send feedback

Returns a semicolon-delimited String of display names for recipients who receive status updates for the task. Read/write.

Syntax

expression .StatusUpdateRecipients

expression A variable that represents a TaskItem object.

Remarks

This property is calculated from the Recipients property. Recipients returned by the StatusUpdateRecipients property correspond to CC recipients in the Recipients collection.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Subject Property (Outlook)

 Copy code hover
[image]

TaskItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a TaskItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.TeamTask Property (Outlook)

 Copy code hover
[image]

TaskItem.TeamTask Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that indicates True if the task is a team task. Read/write.

Syntax

expression .TeamTask

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ToDoTaskOrdinal Property (Outlook)

 Copy code hover
[image]

TaskItem.ToDoTaskOrdinal Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Date value that represents the ordinal value of the task for the TaskItem. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ToDoTaskOrdinal

expression An expression that returns a TaskItem object.

Remarks

This property is used to indicate how the task should be ordered within the parent groups, such as the Today group or the Tomorrow group, of the To-Do Bar.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.TotalWork Property (Outlook)

 Copy code hover
[image]

TaskItem.TotalWork Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long indicating the total work for the task. Read/write.

Syntax

expression .TotalWork

expression A variable that represents a TaskItem object.

Remarks

TotalWork corresponds to the Total work field on the Details tab of a Task item. It is stored in units of minutes. The Total work field on the standard task form is bound to the TotalWork property; by default the field assumes an 8-hour day and 40-hour week.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.UnRead Property (Outlook)

 Copy code hover
[image]

TaskItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.UserProperties Property (Outlook)

 Copy code hover
[image]

TaskItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem Methods (Outlook)

 Copy code hover
[image]

TaskItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Assign | Assigns a task and returns a TaskItem object that represents it.
CancelResponseState | Resets an unsent response to a task request back to a simple task.
ClearRecurrencePattern | Removes the recurrence settings and restores the single-occurrence state for an appointment or task.
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
GetRecurrencePattern | Returns a RecurrencePattern object that represents the recurrence attributes of a task. If there is no existing recurrence pattern, a new empty RecurrencePattern object is returned.
MarkComplete | Marks the task as completed.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Respond | Responds to a task request.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
Send | Sends the task.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.
SkipRecurrence | Clears the current instance of a recurring task and sets the recurrence to the next instance of that task.
StatusReport | Sends a status report to all Cc recipients (recipients returned by the StatusUpdateRecipients property) with the current status for the task and returns an Object representing the status report.


TaskItem.Assign Method (Outlook)

 Copy code hover
[image]

TaskItem.Assign Method (Outlook)
See also Send feedback

Published: July 16, 2012

Assigns a task and returns a TaskItem object that represents it.

Syntax

expression .Assign

expression A variable that represents a TaskItem object.

Return Value

A TaskItem object that represents the task.

Remarks

This method allows a task to be assigned (delegated) to another user. You must create a task before you can assign it, and you must assign a task before you can send it. An assigned task is sent as a TaskRequestItem object.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create a simple task and delegate it as a task request to another user. To run this example, replace 'Dan Wilson' with a valid recipient name.

VBA Copy code Copy code
Sub AssignTask()

 Dim myItem As Outlook.TaskItem

 Dim myDelegate As Outlook.Recipient

 Set MyItem = Application.CreateItem(olTaskItem)

 MyItem.Assign

 Set myDelegate = MyItem.Recipients.Add("Dan Wilson")

 myDelegate.Resolve

 If myDelegate.Resolved Then

 myItem.Subject = "Prepare Agenda For Meeting"

 myItem.DueDate = Now + 30

 myItem.Display

 myItem.Send

 End If

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.CancelResponseState Method (Outlook)

 Copy code hover
[image]

TaskItem.CancelResponseState Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets an unsent response to a task request back to a simple task.

Syntax

expression .CancelResponseState

expression A variable that represents a TaskItem object.

Remarks

After you receive a task request and respond to it, but before sending the response, you can use this method to revert the task to its state before you responded.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ClearRecurrencePattern Method (Outlook)

 Copy code hover
[image]

TaskItem.ClearRecurrencePattern Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the recurrence settings and restores the single-occurrence state for an appointment or task.

Syntax

expression .ClearRecurrencePattern

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Close Method (Outlook)

 Copy code hover
[image]

TaskItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Copy Method (Outlook)

 Copy code hover
[image]

TaskItem.Copy Method (Outlook)
See also Send feedback

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a TaskItem object.

Example

This Visual Basic for Applications example creates an e-mail message, sets the Subject to "Speeches", uses the Copy method to copy it, then moves the copy into a newly created e-mail folder named "Saved Mail" within the Inbox folder.

VBA Copy code Copy code
Sub CopyItem()

 Dim myNameSpace As Outlook.NameSpace

 Dim myFolder As Outlook.Folder

 Dim myNewFolder As Outlook.Folder

 Dim myItem As Outlook.MailItem

 Dim myCopiedItem As Outlook.MailItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myFolder = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set myNewFolder = myFolder.Folders.Add("Saved Mail", olFolderDrafts)

 Set myItem = Application.CreateItem(olMailItem)

 myItem.Subject = "Speeches"

 Set myCopiedItem = myItem.Copy

 myCopiedItem.Move myNewFolder

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Delete Method (Outlook)

 Copy code hover
[image]

TaskItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a TaskItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

TaskItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

TaskItem Object Members


TaskItem.Display Method (Outlook)

 Copy code hover
[image]

TaskItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.GetConversation Method (Outlook)

 Copy code hover
[image]

TaskItem.GetConversation Method (Outlook)
See also Send feedback

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a TaskItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.GetRecurrencePattern Method (Outlook)

 Copy code hover
[image]

TaskItem.GetRecurrencePattern Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a RecurrencePattern object that represents the recurrence attributes of a task. If there is no existing recurrence pattern, a new empty RecurrencePattern object is returned.

Syntax

expression .GetRecurrencePattern

expression A variable that represents a TaskItem object.

Return Value

A RecurrencePattern that represents the recurrence attributes of the task.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.MarkComplete Method (Outlook)

 Copy code hover
[image]

TaskItem.MarkComplete Method (Outlook)
See also Send feedback

Marks the task as completed.

Syntax

expression .MarkComplete

expression A variable that represents a TaskItem object.

Remarks

Sets PercentComplete to "100%", Complete to True, and DateCompleted to the current date.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Move Method (Outlook)

 Copy code hover
[image]

TaskItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.PrintOut Method (Outlook)

 Copy code hover
[image]

TaskItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Respond Method (Outlook)

 Copy code hover
[image]

TaskItem.Respond Method (Outlook)
See also Send feedback

Published: July 16, 2012

Responds to a task request.

Syntax

expression .Respond(Response, fNoUI, fAdditionalTextDialog)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | OlTaskResponse | The response to the request.
fNoUI | Required | Variant | True to not display a dialog box; the response is sent automatically. False to display the dialog box for responding.
fAdditionalTextDialog | Required | Variant | False to not prompt the user for input; the response is displayed in the inspector for editing. True to prompt the user to either send or send with comments. This argument is valid only if fNoUI is False.

Return Value

A TaskItem that represents the response to the task request.

Remarks

When you call the Respond method with the olTaskAccept parameter, Outlook creates a new TaskItem that duplicates the task request item. The new item has a different Entry ID. Outlook then removes the original item.

The following table describes the behavior of the Respond method depending on the parent object, and the fNoUI and fAdditionalTextDialog parameters.

fNoUI, fAdditionalTextDialog | Result
True, True | Response item is returned with no user interface. To send the response, you must call the Send method.
True, False | Same result as with True, True .
False, True | If the Display method has been called, the user prompt appears. Otherwise, the item is sent without prompting and the resulting item is nothing.
False, False | Does nothing.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Save Method (Outlook)

 Copy code hover
[image]

TaskItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a TaskItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.SaveAs Method (Outlook)

 Copy code hover
[image]

TaskItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

Example

This Visual Basic for Applications (VBA) example uses the SaveAs method to save the currently open item as a text file in the Documents folder, using the subject as the file name. To run this example, make sure a mail item in plain text format is open in the active window.

VBA Copy code Copy code
Sub SaveAsTXT()
 Dim myItem As Outlook.Inspector
 Dim objItem As Object

 Set myItem = Application.ActiveInspector
 If Not TypeName(myItem) = "Nothing" Then
 Set objItem = myItem.CurrentItem
 strname = objItem.Subject
 'Prompt the user for confirmation
 Dim strPrompt As String
 strPrompt = "Are you sure you want to save the item?" & _
 "If a file with the same name already exists, " & _
 "it will be overwritten with this copy of the file."
 If MsgBox(strPrompt, vbYesNo + vbQuestion) = vbYes Then
 objItem.SaveAs Environ("HOMEPATH") & "\My Documents\" & strname & ".txt", olTXT
 End If
 Else
 MsgBox "There is no current active inspector."
 End If
End Sub

This Visual Basic for Applications example shows you how to create a template using the SaveAs method.

VBA Copy code Copy code
Sub CreateTemplate()
 Dim MyItem As Outlook.TaskItem

 Set MyItem = Application.CreateItem(olTaskItem)
 MyItem.Subject = "Status Report"
 MyItem.Display
 MyItem.SaveAs Environ("HOMEPATH") & "\My Documents\statusrep.oft", OlSaveAsType.olTemplate
End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Send Method (Outlook)

 Copy code hover
[image]

TaskItem.Send Method (Outlook)
See also Send feedback

Sends the task.

Syntax

expression .Send

expression A variable that represents a TaskItem object.

Example

This Visual Basic for Applications (VBA) example uses CreateItem to create a simple task and delegate it as a task request to another user. Replace 'Dan Wilson' with a valid recipient name before running this example.

VBA Copy code Copy code
Sub AssignTask()

 Dim myItem As Outlook.TaskItem

 Dim myDelegate As Outlook.Recipient

 Set MyItem = Application.CreateItem(olTaskItem)

 MyItem.Assign

 Set myDelegate = MyItem.Recipients.Add("Dan Wilson")

 myDelegate.Resolve

 If myDelegate.Resolved Then

 myItem.Subject = "Prepare Agenda for Meeting"

 myItem.DueDate = Now + 30

 myItem.Display

 myItem.Send

 End If

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

TaskItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a TaskItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a new task item, displays the item on the screen, and opens up the Show Categories dialog box.

VBA Copy code Copy code
Sub TaskItem()

 'Creates a task item to access ShowCategoriesDialog

 Dim olmyTaskItem As Outlook.TaskItem

 'Create task item

 Set olmyTaskItem = Application.CreateItem(olTaskItem)

 olmyTaskItem.Subject = "Sales Reports"

 'Display the item

 olmyTaskItem.Display

 'Display the Show categories dialog

 olmyTaskItem.ShowCategoriesDialog

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.SkipRecurrence Method (Outlook)

 Copy code hover
[image]

TaskItem.SkipRecurrence Method (Outlook)
See also Send feedback

Published: July 16, 2012

Clears the current instance of a recurring task and sets the recurrence to the next instance of that task.

Syntax

expression .SkipRecurrence

expression A variable that represents a TaskItem object.

Return Value

False indicates that the task was the last task in the recurrence, so there is no task to set the recurrence to. True indicates that the recurrence was successfully set to the next instance of that task.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.StatusReport Method (Outlook)

 Copy code hover
[image]

TaskItem.StatusReport Method (Outlook)
See also Send feedback

Published: July 16, 2012

Sends a status report to all Cc recipients (recipients returned by the StatusUpdateRecipients property) with the current status for the task and returns an Object representing the status report.

Syntax

expression .StatusReport

expression A variable that represents a TaskItem object.

Return Value

An Object value that represents the status report.

Example

This Visual Basic for Applications (VBA) example uses the StatusReport method to report the status of the currently open task.

VBA Copy code Copy code
Sub SendStatusReport()
 Dim myTask As Outlook.TaskItem
 Dim myinspector As Outlook.Inspector
 Dim myReport As Object

 Set myinspector = Application.ActiveInspector
 If Not TypeName(myinspector) = "Nothing" Then
 If TypeName(myinspector.CurrentItem) = "TaskItem" Then
 Set myTask = myinspector.CurrentItem
 Set myReport = myTask.StatusReport
 myReport.Send
 Else
 MsgBox "No task item is currently open."
 End If
 Else
 MsgBox "No inspector is currently open."
 End If
End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem Events (Outlook)

 Copy code hover
[image]

TaskItem Events (Outlook)
Send feedback

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


TaskItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

TaskItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a TaskItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskItem.AttachmentAdd Event (Outlook)
See also Send feedback

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

Example

This Visual Basic for Applications (VBA) example checks the size of the item after an attachment has been added and displays a warning if the size exceeds 500,000 bytes. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAttachAdd() procedure should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents newItem As Outlook.MailItem

Private Sub newItem_AttachmentAdd(ByVal newAttachment As Attachment)

 If newAttachment.Type = olByValue Then

 newItem.Save

 If newItem.Size > 500000 Then

 MsgBox "Warning: Item size is now " & newItem.Size & " bytes."

 End If

 End If

End Sub

Public Sub TestAttachAdd()

 Dim atts As Outlook.Attachments

 Dim newAttachment As Outlook.Attachment

 Set newItem = Application.CreateItem(olMailItem)

 newItem.Subject = "Test attachment"

 Set atts = newItem.Attachments

 Set newAttachment = atts.Add("C:\Test.txt", olByValue)

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

TaskItem.AttachmentRemove Event (Outlook)
See also Send feedback

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel, )

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the TaskItem to be saved.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeDelete Event (Outlook)
See also Send feedback

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

TaskItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a TaskItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Close Event (Outlook)

 Copy code hover
[image]

TaskItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.CustomAction Event (Outlook)

 Copy code hover
[image]

TaskItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

TaskItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Forward Event (Outlook)

 Copy code hover
[image]

TaskItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Open Event (Outlook)

 Copy code hover
[image]

TaskItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

TaskItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Read Event (Outlook)

 Copy code hover
[image]

TaskItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a TaskItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

TaskItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Reply Event (Outlook)

 Copy code hover
[image]

TaskItem.Reply Event (Outlook)
See also Send feedback

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

TaskItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Send Event (Outlook)

 Copy code hover
[image]

TaskItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item, or when the Send method is called for the item, which is an instance of the parent object.

Syntax

expression .Send(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Unload Event (Outlook)

 Copy code hover
[image]

TaskItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a TaskItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskItem.Write Event (Outlook)

 Copy code hover
[image]

TaskItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a TaskItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

TaskItem Object

Other resources

TaskItem Object Members


TaskRequestAcceptItem Object (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a response to a TaskRequestItem sent by the initiating user.

Remarks

If the delegated user accepts the task, the ResponseState property is set to olTaskAccept. The associated TaskItem is received by the delegator as a TaskRequestAcceptItem object.

Unlike other Microsoft Outlook objects, you cannot create this object.

Use the GetAssociatedTask method to return the TaskItem object that is associated with this TaskRequestAcceptItem. Work directly with the TaskItem object.

See also

Concepts

Outlook Object Model Reference

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem Members (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a response to a TaskRequestItem sent by the initiating user.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestAcceptItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestAcceptItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestAcceptItem Properties (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestAcceptItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestAcceptItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestAcceptItem.Actions Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Application Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Attachments Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its TaskRequestAcceptItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Body Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Categories Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Class Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Companies Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Conflicts Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ConversationID Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the TaskRequestAcceptItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the TaskRequestAcceptItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.CreationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.DownloadState Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.DownloadState Property (Outlook)
See also Send feedback

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a TaskRequestAcceptItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.EntryID Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.EntryID Property (Outlook)
See also Send feedback

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.FormDescription Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.GetInspector Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Importance Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.IsConflict Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.IsConflict Property (Outlook)
See also Send feedback

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ItemProperties Property (Outlook)
See also Send feedback

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.MarkForDownload Property (Outlook)
See also Send feedback

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.MessageClass Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Mileage Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.NoAging Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.OutlookVersion Property (Outlook)
See also Send feedback

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Parent Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.PropertyAccessor Property (Outlook)
See also Send feedback

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestAcceptItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.RTFBody Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Saved Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Session Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Size Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Subject Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Subject Property (Outlook)
See also Send feedback

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.UnRead Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.UserProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem Methods (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


TaskRequestAcceptItem.Close Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Copy Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Delete Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

TaskRequestAcceptItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

TaskRequestAcceptItemObject Members


TaskRequestAcceptItem.Display Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.GetAssociatedTask Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.GetAssociatedTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TaskItem object that represents the requested task.

Syntax

expression .GetAssociatedTask(AddToTaskList)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
AddToTaskList | Required | Boolean | True if the task is added to the default Tasks folder.

Return Value

A TaskItem object that represents the requested task.

Remarks

The GetAssociatedTask method will not work unless the TaskItem is processed before the method is called. To do so, call the Display method before calling GetAssociatedTask.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.GetConversation Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.GetConversation Method (Outlook)
See also Send feedback

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a TaskRequestAcceptItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Move Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.PrintOut Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Save Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Save Method (Outlook)
See also Send feedback

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.SaveAs Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.SaveAs Method (Outlook)
See also Send feedback

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a TaskRequestAcceptItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem Events (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


TaskRequestAcceptItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.AttachmentRead Event (Outlook)
See also Send feedback

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the TaskRequestAcceptItem to be saved.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Close Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.CustomAction Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)
 Select Case myPropName
 Case "RespondBy"
 Set myPages = Item.GetInspector.ModifiedFormPages
 Set myCtrl = myPages("P.2").Controls("DateToRespond")
 If Item.UserProperties("RespondBy").Value Then
 myCtrl.Enabled = True
 myCtrl.Backcolor = 65535 'Yellow
 Else
 myCtrl.Enabled = False
 myCtrl.Backcolor = 0 'Black
 End If
 Case Else
 End Select
End Sub

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Forward Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Open Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Open Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Read Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Reply Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Send Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

Example

This Visual Basic for Applications (VBA) example uses the Send event and sends an item with an automatic expiration date. The sample code must be placed in a class module such as ThisOutlookSession, and the SendMyMail procedure must be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents myItem As Outlook.MailItem

Sub SendMyMail()

 Set myItem = Outlook.CreateItem(olMailItem)

 myItem.To = "Dan Wilson"

 myItem.Subject = "Data files information"

 myItem.Send

End Sub

Private Sub myItem_Send(Cancel As Boolean)

 myItem.ExpiryTime = #2/2/2003 4:00:00 PM#

End Sub

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Unload Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a TaskRequestAcceptItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestAcceptItem.Write Event (Outlook)

 Copy code hover
[image]

TaskRequestAcceptItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a TaskRequestAcceptItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

TaskRequestAcceptItem Object

Other resources

TaskRequestAcceptItem Object Members


TaskRequestDeclineItem Object (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a response to a TaskRequestItem sent by the initiating user.

Remarks

If the delegated user declines the task, the ResponseState property is set to olTaskDecline. The associated TaskItem is received by the delegator as a TaskRequestDeclineItem object.

Unlike other Microsoft Outlook objects, you cannot create this object.

Use the GetAssociatedTask method to return the TaskItem object that is associated with this TaskRequestDeclineItem. Work directly with the TaskItem object.

See also

Concepts

Outlook Object Model Reference

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem Members (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a response to a TaskRequestItem sent by the initiating user.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the displayed Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestDeclineItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestDeclineItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestDeclineItem Properties (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestDeclineItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestDeclineItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestDeclineItem.Actions Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Application Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Attachments Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its TaskRequestDeclineItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Body Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Body Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Categories Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Class Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Companies Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Conflicts Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ConversationID Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the TaskRequestDeclineItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the TaskRequestDeclineItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ConversationTopic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.CreationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.DownloadState Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a TaskRequestDeclineItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.EntryID Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.FormDescription Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.GetInspector Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Importance Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.IsConflict Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.MessageClass Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Mileage Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.NoAging Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Parent Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestDeclineItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.RTFBody Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Saved Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Session Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Size Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Subject Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.UnRead Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.UserProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.UserProperties Property (Outlook)
See also Send feedback

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem Methods (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem Methods (Outlook)
Send feedback

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the displayed Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


TaskRequestDeclineItem.Close Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the displayed Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Copy Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Delete Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Delete Method (Outlook)
See also Send feedback

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

TaskRequestDeclineItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Display Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Display Method (Outlook)
See also Send feedback

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.GetAssociatedTask Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.GetAssociatedTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TaskItem object that represents the requested task.

Syntax

expression .GetAssociatedTask(AddToTaskList)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
AddToTaskList | Required | Boolean | True if the task is added to the default Tasks folder.

Return Value

A TaskItem object that represents the requested task.

Remarks

The GetAssociatedTask method will not work unless the TaskItem is processed before the method is called. To do so, call the Display method before calling GetAssociatedTask.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.GetConversation Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a TaskRequestDeclineItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Move Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.PrintOut Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.PrintOut Method (Outlook)
See also Send feedback

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Save Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.SaveAs Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a TaskRequestDeclineItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem Events (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


TaskRequestDeclineItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.AttachmentAdd Event (Outlook)
See also Send feedback

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.AttachmentRead Event (Outlook)
See also Send feedback

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

Example

This Visual Basic for Applications (VBA) example displays a message when the user tries to read an attachment. The sample code must be placed in a class module such as ThisOutlookSession, and the TestAttachRead() procedure should be called before the event procedure can be called by Microsoft Outlook. For this example to run, there has to be at least one item in the Inbox with subject as 'Test' and containing at least one attachment.

VBA Copy code Copy code
Public WithEvents myItem As outlook.MailItem

Private Sub myItem_AttachmentRead(ByVal myAttachment As Outlook.Attachment)

 If myAttachment.Type = olByValue Then

 MsgBox "If you change this file, also save your changes to the original file."

 End If

End Sub

Public Sub TestAttachRead()

 Dim atts As Outlook.Attachments

 Dim myAttachment As Outlook.Attachment

 Set myItem = Application.ActiveExplorer.CurrentFolder.Items("Test")

 Set atts = myItem.Attachments

 myItem.Display

End Sub

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the TaskRequestDeclineItem to be saved.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Close Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Close Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.CustomAction Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Forward Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Open Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Read Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Read Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Reply Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.ReplyAll Event (Outlook)
See also Send feedback

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Send Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Send Event (Outlook)
See also Send feedback

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Unload Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a TaskRequestDeclineItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestDeclineItem.Write Event (Outlook)

 Copy code hover
[image]

TaskRequestDeclineItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a TaskRequestDeclineItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

TaskRequestDeclineItem Object

Other resources

TaskRequestDeclineItem Object Members


TaskRequestItem Object (Outlook)

 Copy code hover
[image]

TaskRequestItem Object (Outlook)
See also Send feedback

Represents a change to the recipient's Tasks list initiated by another party or as a result of a group tasking.

Remarks

Unlike other Microsoft Outlook objects, you cannot create this object. When the sender applies the Assign and Send methods to a TaskItem object to assign (delegate) the associated task to another user, the TaskRequestItem object is created when the item is received in the recipient's Inbox.

Use the GetAssociatedTask method to return the TaskItem object, and work directly with the TaskItem object to respond to the request.

Example

The following Visual Basic for Applications (VBA) example creates a simple task, assigns it to another user, and sends it. When the task request arrives in the recipient's Inbox, it is received as a TaskRequestItem.

VBA Copy code Copy code
Sub SendTask()

 Dim myItem As Outlook.TaskItem

 Dim myDelegate As Outlook.Recipient

 Set myItem = Application.CreateItem(olTaskItem)

 myItem.Assign

 Set myDelegate = myItem.Recipients.Add("Jeff Smith")

 myItem.Subject = "Prepare Agenda For Meeting"

 myItem.DueDate = #9/20/97#

 myItem.Send

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

TaskRequestItem Object Members


TaskRequestItem Members (Outlook)

 Copy code hover
[image]

TaskRequestItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a change to the recipient's Tasks list initiated by another party or as a result of a group tasking.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestItem Properties (Outlook)

 Copy code hover
[image]

TaskRequestItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestItem.Actions Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Application Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Attachments Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a TaskRequestItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its TaskRequestItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.BillingInformation Property (Outlook)
See also Send feedback

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a TaskRequestItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Body Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Categories Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a TaskRequestItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Class Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Companies Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a TaskRequestItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Conflicts Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ConversationID Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.ConversationID Property (Outlook)
See also Send feedback

Returns a String that uniquely identifies a Conversation object that the TaskRequestItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a TaskRequestItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the TaskRequestItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.ConversationTopic Property (Outlook)
See also Send feedback

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.CreationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.DownloadState Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a TaskRequestItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.EntryID Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.FormDescription Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.FormDescription Property (Outlook)
See also Send feedback

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.GetInspector Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a TaskRequestItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Importance Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Importance Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.IsConflict Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a TaskRequestItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a TaskRequestItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a TaskRequestItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.MessageClass Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Mileage Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Mileage Property (Outlook)
See also Send feedback

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a TaskRequestItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.NoAging Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.NoAging Property (Outlook)
See also Send feedback

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Parent Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.RTFBody Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a TaskRequestItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Saved Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Saved Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Sensitivity Property (Outlook)
See also Send feedback

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Session Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TaskRequestItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Size Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Subject Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a TaskRequestItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.UnRead Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.UserProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem Methods (Outlook)

 Copy code hover
[image]

TaskRequestItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


TaskRequestItem.Close Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Copy Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Copy Method (Outlook)
See also Send feedback

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Delete Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a TaskRequestItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

TaskRequestItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

TaskRequestItem Object Members


TaskRequestItem.Display Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.GetAssociatedTask Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.GetAssociatedTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TaskItem object that represents the requested task.

Syntax

expression .GetAssociatedTask(AddToTaskList)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
AddToTaskList | Required | Boolean | True if the task is added to the default Tasks folder.

Return Value

A TaskItem object that represents the requested task.

Remarks

The GetAssociatedTask method will not work unless the TaskItem is processed before the method is called. To do so, call the Display method before calling GetAssociatedTask.

Example

This Microsoft Visual Basic for Applications (VBA) example accepts a TaskRequestItem, sending the response without displaying the inspector.

VBA Copy code Copy code
Sub AcceptTask()

 Dim myNameSpace As Outlook.NameSpace

 Dim myTasks As Outlook.Folder

 Dim myNewTaskItem As Outlook.TaskItem

 Dim mytaskreqItem As Outlook.TaskRequestItem

 Dim myItem As Outlook.TaskItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myTasks = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set mytaskreqItem = myTasks.Items.Find("[Subject] = ""Meeting w/ Nate Sun""")

 If Not TypeName(mytaskreqItem) = "Nothing" Then

 Set myNewTaskItem = mytaskreqItem.GetAssociatedTask(True)

 Set myItem = myNewTaskItem.Respond(olTaskAccept, True, True)

 myItem.Send

 End If

End Sub

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.GetConversation Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a TaskRequestItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Move Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.PrintOut Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Save Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.SaveAs Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

TaskRequestItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a TaskRequestItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem Events (Outlook)

 Copy code hover
[image]

TaskRequestItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


TaskRequestItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.AfterWrite Event (Outlook)
See also Send feedback

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a TaskRequestItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.AttachmentRemove Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the TaskRequestItem to be saved.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a TaskRequestItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Members


TaskRequestItem.Close Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Close Event (Outlook)
See also Send feedback

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.CustomAction Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Forward Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Open Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.PropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Read Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a TaskRequestItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Reply Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Send Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Unload Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a TaskRequestItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestItem.Write Event (Outlook)

 Copy code hover
[image]

TaskRequestItem.Write Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a TaskRequestItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

TaskRequestItem Object

Other resources

TaskRequestItem Object Members


TaskRequestUpdateItem Object (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem Object (Outlook)
See also Send feedback

Represents a response to a TaskRequestItem sent by the initiating user.

Remarks

If the delegated user updates the task by changing properties such as the DueDate or the Status, and then sends it, the associated TaskItem is received by the delegator as a TaskRequestUpdateItem object.

Unlike other Microsoft Outlook objects, you cannot create this object.

Use the GetAssociatedTask method to return the TaskItem object that is associated with this TaskRequestUpdateItem. Work directly with the TaskItem object

See also

Concepts

Outlook Object Model Reference

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem Members (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a response to a TaskRequestItem sent by the initiating user.

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestUpdateItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestUpdateItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestUpdateItem Properties (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Actions | Returns an Actions collection that represents all the available actions for the item. Read-only.
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Attachments | Returns an Attachments object that represents all the attachments for the specified item. Read-only.
AutoResolvedWinner | Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.
BillingInformation | Returns or sets a String representing the billing information associated with the Outlook item. Read/write.
Body | Returns or sets a String representing the clear-text body of the Outlook item. Read/write.
Categories | Returns or sets a String representing the categories assigned to the Outlook item. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Companies | Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.
Conflicts | Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.
ConversationID | Returns a String that uniquely identifies a Conversation object that the TaskRequestUpdateItem object belongs to. Read-only.
ConversationIndex | Returns a String that indicates the relative position of the item within the conversation thread. Read-only.
ConversationTopic | Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.
CreationTime | Returns a Date indicating the creation time for the Outlook item. Read-only.
DownloadState | Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.
EntryID | Returns a String representing the unique Entry ID of the object. Read-only.
FormDescription | Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.
GetInspector | Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.
Importance | Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.
IsConflict | Returns a Boolean that determines if the item is in conflict. Read-only.
ItemProperties | Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.
LastModificationTime | Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.
MarkForDownload | Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.
MessageClass | Returns or sets a String representing the message class for the Outlook item. Read/write.
Mileage | Returns or sets a String representing the mileage for an item. Read/write.
NoAging | Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.
OutlookInternalVersion | Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.
OutlookVersion | Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
PropertyAccessor | Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestUpdateItem object. Read-only.
RTFBody | Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.
Saved | Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.
Sensitivity | Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.
Subject | Returns or sets a String indicating the subject for the Outlook item. Read/write.
UnRead | Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.
UserProperties | Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.


TaskRequestUpdateItem.Actions Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Actions Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Actions collection that represents all the available actions for the item. Read-only.

Syntax

expression .Actions

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Application Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Attachments Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Attachments Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Attachments object that represents all the attachments for the specified item. Read-only.

Syntax

expression .Attachments

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.AutoResolvedWinner Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.AutoResolvedWinner Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is a winner of an automatic conflict resolution. Read-only.

Syntax

expression .AutoResolvedWinner

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

A value of False does not necessarily indicate that the item is a loser of an automatic conflict resolution. The item could be in conflict with another item.

If an item has Conflicts.Count of its TaskRequestUpdateItem.Conflicts property greater than zero and if its AutoResolvedWinner property is True, it is a winner of an automatic conflict resolution. On the other hand, if the item is in conflict and has its AutoResolvedWinner property as False, it is a loser in an automatic conflict resolution.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BillingInformation Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BillingInformation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the billing information associated with the Outlook item. Read/write.

Syntax

expression .BillingInformation

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Body Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Body Property (Outlook)
See also Send feedback

Returns or sets a String representing the clear-text body of the Outlook item. Read/write.

Syntax

expression .Body

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Categories Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Categories Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the categories assigned to the Outlook item. Read/write.

Syntax

expression .Categories

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

Categories is a delimited string of category names that have been assigned to an Outlook item. This property uses the character specified in the value name, sList, under HKEY_CURRENT_USER\Control Panel\International in the Windows registry, as the delimiter for multiple categories. To convert the string of category names to an array of category names, use the Microsoft Visual Basic function Split.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Class Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Companies Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Companies Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the names of the companies associated with the Outlook item. Read/write.

Syntax

expression .Companies

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This is a free-form text field.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Conflicts Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Conflicts Property (Outlook)
See also Send feedback

Published: July 16, 2012

Return the Conflicts object that represents the items that are in conflict for any Outlook item object. Read-only.

Syntax

expression .Conflicts

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ConversationID Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ConversationID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that uniquely identifies a Conversation object that the TaskRequestUpdateItem object belongs to. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ConversationID

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property associates items with a conversation. These items and the conversation all have the same value in their ConversationID property.

This property corresponds with the MAPI property PidTagConversationId.

If the TaskRequestUpdateItem object is created in a version of Microsoft Outlook earlier than Microsoft Outlook 2010, or if Outlook is running in online mode against a version of Microsoft Exchange Server earlier than Microsoft Exchange Server 2010, this property returns the same value as the ConversationTopic property.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ConversationIndex Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ConversationIndex Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that indicates the relative position of the item within the conversation thread. Read-only.

Syntax

expression .ConversationIndex

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagConversationIndex.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ConversationTopic Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ConversationTopic Property (Outlook)
See also Send feedback

Returns a String representing the topic of the conversation thread of the Outlook item. Read-only.

Syntax

expression .ConversationTopic

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.CreationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.CreationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date indicating the creation time for the Outlook item. Read-only.

Syntax

expression .CreationTime

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagCreationTime.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.DownloadState Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.DownloadState Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant that belongs to the OlDownloadState enumeration indicating the download state of the item. Read-only.

Syntax

expression .DownloadState

expression A variable that represents a TaskRequestUpdateItem object.

Example

The following Microsoft Visual Basic for Applications (VBA) example searches through the user's Inbox for items that have not yet been fully downloaded. If any not yet fully downloaded items are found, a message is displayed to the user, and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim objItems As Outlook.Items

 Dim obj As Object

 Dim i As Integer

 Dim iCount As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 Set objItems = mpfInbox.Items

 iCount = objItems.Count

 'Loop all items in the Inbox folder

 For i = 1 To iCount

 Set obj = objItems.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox "This item has not been fully downloaded."

 'Mark the item to be downloaded

 obj.MarkForDownload = olMarkedForDownload

 obj.Save

 End If

 Next

End Sub

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.EntryID Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.EntryID Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String representing the unique Entry ID of the object. Read-only.

Syntax

expression .EntryID

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagEntryId.

A MAPI store provider assigns a unique ID string when an item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The Entry ID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. Solutions should not depend on the EntryID property to be unique unless items will not be moved. The EntryID property returns a MAPI long-term Entry ID. For more information about long- and short-term EntryIDs, search http://msdn.microsoft.com for PidTagEntryId.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.FormDescription Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.FormDescription Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the FormDescription object that represents the form description for the specified Outlook item. Read-only.

Syntax

expression .FormDescription

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.GetInspector Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.GetInspector Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Inspector object that represents an inspector initialized to contain the specified item. Read-only.

Syntax

expression .GetInspector

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property is useful for returning an Inspector object in which to display the item, as opposed to using the Application.ActiveInspector method and setting the Inspector.CurrentItem property. If an Inspector object already exists for the item, the GetInspector property will return that Inspector object instead of creating a new one.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Importance Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Importance Property (Outlook)
See also Send feedback

Returns or sets an OlImportance constant indicating the relative importance level for the Outlook item. Read/write.

Syntax

expression .Importance

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagImportance.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.IsConflict Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.IsConflict Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that determines if the item is in conflict. Read-only.

Syntax

expression .IsConflict

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

Whether or not an item is in conflict is determined by the state of the application. For example, when a user is offline and tries to access an online folder the action will fail. In this scenario, the IsConflict property will return True.

If True, the specified item is in conflict.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ItemProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ItemProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an ItemProperties collection that represents all standard and user-defined properties associated with the Outlook item. Read-only.

Syntax

expression .ItemProperties

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The ItemProperties collection is a zero-based collection, meaning that the first object in the collection is referenced by the index 0.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.LastModificationTime Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.LastModificationTime Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date specifying the date and time that the Outlook item was last modified. Read-only.

Syntax

expression .LastModificationTime

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagLastModificationTime.

Example

This Visual Basic for Applications example uses the Items.Restrict method to apply a filter to contact items based on the item's LastModificationTime property. You can apply a similar approach to filter on the LastModificationTime property of other Outlook items.

VBA Copy code Copy code
Public Sub ContactDateCheck()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItems As Outlook.Items

 Dim myItem As Object

 Set myNamespace = Application.GetNamespace("MAPI")

 Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items

 Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")

 For Each myItem In myItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

VBA Copy code Copy code
Public Sub ContactDateCheck2()

 Dim myNamespace As Outlook.NameSpace

 Dim myContacts As Outlook.Items

 Dim myItem As Object

 Dim DateStart As Date

 Dim DateToCheck As String

 Dim myRestrictItems As Outlook.Items

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items

 DateStart = #01/1/2003#

 DateToCheck = "[LastModificationTime] >= """ & DateStart & """"

 Set myRestrictItems = myContacts.Restrict(DateToCheck)

 For Each myItem In myRestrictItems

 If (myItem.Class = olContact) Then

 MsgBox myItem.FullName & ": " & myItem.LastModificationTime

 End If

 Next

End Sub

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.MarkForDownload Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.MarkForDownload Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlRemoteStatus constant that determines the status of an item once it is received by a remote user. Read/write.

Syntax

expression .MarkForDownload

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property gives remote users with less-than-ideal data-transfer capabilities increased messaging flexibility.

Example

The following example searches through the user's Inbox for items that have not yet been fully downloaded. If any items are found that are not fully downloaded, a message is displayed and the item is marked for download.

VBA Copy code Copy code
Sub DownloadItems()

 Dim mpfInbox As Outlook.Folder

 Dim obj As Object

 Dim i As Integer

 Set mpfInbox = Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox)

 'Loop all items in the Inbox folder

 For i = 1 To mpfInbox.Items.Count

 Set obj = mpfInbox.Items.Item(i)

 'Verify if the state of the item is olHeaderOnly

 If obj.DownloadState = olHeaderOnly Then

 MsgBox ("This item has not been fully downloaded.")

 'Mark the item to be downloaded.

 obj.MarkForDownload = olMarkedForDownload

 End If

 Next

End Sub

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.MessageClass Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.MessageClass Property (Outlook)
See also Send feedback

Returns or sets a String representing the message class for the Outlook item. Read/write.

Syntax

expression .MessageClass

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagMessageClass. The MessageClass property links the item to the form on which it is based. When an item is selected, Outlook uses the message class to locate the form and expose its properties, such as Reply commands.

See also

Concepts

Item Types and Message Classes
TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Mileage Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Mileage Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the mileage for an item. Read/write.

Syntax

expression .Mileage

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This is a free-form string field and can be used to store mileage information associated with the item (for example, 100 miles documented for an appointment, contact, or task) for purposes of reimbursement.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.NoAging Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.NoAging Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True to not age the Outlook item. Read/write.

Syntax

expression .NoAging

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.OutlookInternalVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.OutlookInternalVersion Property (Outlook)
See also Send feedback

Returns a Long representing the build number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookInternalVersion

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.OutlookVersion Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.OutlookVersion Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String indicating the major and minor version number of the Outlook application for an Outlook item. Read-only.

Syntax

expression .OutlookVersion

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Parent Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.PropertyAccessor Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.PropertyAccessor Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a PropertyAccessor object that supports creating, getting, setting, and deleting properties of the parent TaskRequestUpdateItem object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .PropertyAccessor

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.RTFBody Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.RTFBody Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Byte array that represents the body of the Microsoft Outlook item in Rich Text Format. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .RTFBody

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

You can use the StrConv function in Microsoft Visual Basic for Applications (VBA), or the System.Text.Encoding.AsciiEncoding.GetString() method in C# or Visual Basic to convert an array of bytes to a string.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Saved Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Saved Property (Outlook)
See also Send feedback

Returns a Boolean value that is True if the Outlook item has not been modified since the last save. Read-only.

Syntax

expression .Saved

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Sensitivity Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Sensitivity Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a constant in the OlSensitivity enumeration indicating the sensitivity for the Outlook item. Read/write.

Syntax

expression .Sensitivity

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagSensitivity.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Session Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Size Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Size Property (Outlook)
See also Send feedback

Returns a Long indicating the size (in bytes) of the Outlook item. Read-only.

Syntax

expression .Size

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Subject Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Subject Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String indicating the subject for the Outlook item. Read/write.

Syntax

expression .Subject

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This property corresponds to the MAPI property PidTagSubject. The Subject property is the default property for Outlook items.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.UnRead Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.UnRead Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that is True if the Outlook item has not been opened (read). Read/write.

Syntax

expression .UnRead

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.UserProperties Property (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.UserProperties Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the UserProperties collection that represents all the user properties for the Outlook item. Read-only.

Syntax

expression .UserProperties

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem Methods (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Close | Closes and optionally saves changes to the Outlook item.
Copy | Creates another instance of an object.
Delete | Removes the item from the folder that contains the item.
Display | Displays a new Inspector object for the item.
GetAssociatedTask | Returns a TaskItem object that represents the requested task.
GetConversation | Obtains a Conversation object that represents the conversation to which this item belongs.
Move | Moves a Microsoft Outlook item to a new folder.
PrintOut | Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.
Save | Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.
SaveAs | Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.
ShowCategoriesDialog | Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.


TaskRequestUpdateItem.Close Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Close Method (Outlook)
See also Send feedback

Published: July 16, 2012

Closes and optionally saves changes to the Outlook item.

Syntax

expression .Close(SaveMode)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
SaveMode | Required | OlInspectorClose | The close behavior. If the item displayed within the inspector has not been changed, this argument has no effect.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Copy Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates another instance of an object.

Syntax

expression .Copy

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Delete Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Delete Method (Outlook)
See also Send feedback

Removes the item from the folder that contains the item.

Syntax

expression .Delete

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The Delete method deletes a single item in a collection. To delete all items in the Items collection of a folder, you must delete each item starting with the last item in the folder. For example, in the items collection of a folder, AllItems, if there are n number of items in the folder, start deleting the item at AllItems.Item(n), decrementing the index each time until you delete AllItems.Item(1).

The Delete method moves the item from the containing folder to the Deleted Items folder. If the containing folder is the Deleted Items folder, the Delete method removes the item permanently.

See also

Concepts

TaskRequestUpdateItemObject
How to: Delete All Items and Subfolders in the Deleted Items Folder

Other resources

TaskRequestUpdateItemObject Members


TaskRequestUpdateItem.Display Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Display Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays a new Inspector object for the item.

Syntax

expression .Display(Modal)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Modal | Optional | Variant | True to make the window modal. The default value is False.

Remarks

The Display method is supported for explorer and inspector windows for the sake of backward compatibility. To activate an explorer or inspector window, use the Activate method.

If you attempt to open an "unsafe" file system object (or "freedoc" file) by using the Microsoft Outlook object model, you receive the E_FAIL return code in the C or C++ programming languages. In Outlook 2000 and earlier, you could open an "unsafe" file system object by using the Display method.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.GetAssociatedTask Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.GetAssociatedTask Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TaskItem object that represents the requested task.

Syntax

expression .GetAssociatedTask(AddToTaskList)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
AddToTaskList | Required | Boolean | True if the task is added to the default Tasks folder.

Return Value

A TaskItem object that represents the requested task.

Remarks

The GetAssociatedTask method will not work unless the TaskItem is processed before the method is called. To do so, call the Display method before calling GetAssociatedTask.

Example

This Microsoft Visual Basic for Applications (VBA) example accepts a TaskRequestUpdateItem Object, sending the response without displaying the inspector.

VBA Copy code Copy code
Sub AcceptTask()

 Dim myNameSpace As Outlook.NameSpace

 Dim myTasks As Outlook.Folder

 Dim myNewTaskItem As Outlook.TaskItem

 Dim mytaskrequpdateItem As Outlook.TaskRequestUpdateItem

 Dim myItem As Outlook.TaskItem

 Set myNameSpace = Application.GetNamespace("MAPI")

 Set myTasks = myNameSpace.GetDefaultFolder(olFolderInbox)

 Set mytaskrequdpateItem = myTasks.Items.Find("[Subject] = ""Meeting w/ Nate Sun""")

 If Not TypeName(mytaskrequpdateItem) = "Nothing" Then

 Set myNewTaskItem = mytaskrequpdateItem.GetAssociatedTask(True)

 Set myItem = myNewTaskItem.Respond(olTaskAccept, True, True)

 myItem.Send

 End If

End Sub

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.GetConversation Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.GetConversation Method (Outlook)
See also Send feedback

Published: July 16, 2012

Obtains a Conversation object that represents the conversation to which this item belongs.

Version Information

Version Added: Outlook 2010

Syntax

expression .GetConversation

expression A variable that represents a TaskRequestUpdateItem object.

Return Value

A Conversation object that represents the conversation to which this item belongs.

Remarks

GetConversation returns Null (Nothing in Visual Basic) if no conversation exists for the item. No conversation exists for an item in the following scenarios:

  • The item has not been saved. An item can be saved programmatically, by user action, or by auto-save.

  • For an item that can be sent (for example, a mail item, appointment item, or contact item), the item has not been sent.

  • Conversations have been disabled through the Windows registry.

  • The store does not support Conversation view (for example, Outlook is running in classic online mode against a version of Microsoft Exchange earlier than Microsoft Exchange Server 2010). Use the IsConversationEnabled property of the Store object to determine whether the store supports Conversation view.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Move Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Move Method (Outlook)
See also Send feedback

Published: July 16, 2012

Moves a Microsoft Outlook item to a new folder.

Syntax

expression .Move(DestFldr)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
DestFldr | Required | Folder | An expression that returns a Folder object. The destination folder.

Return Value

An Object value that represents the item which has been moved to the designated folder.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.PrintOut Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.PrintOut Method (Outlook)
See also Send feedback

Published: July 16, 2012

Prints the Outlook item using all default settings.The PrintOut method is the only Outlook method that can be used for printing.

Syntax

expression .PrintOut

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Save Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the current folder or, if this is a new item, to the Outlook default folder for the item type.

Syntax

expression .Save

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.SaveAs Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.SaveAs Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Syntax

expression .SaveAs(Path, Type)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Path | Required | String | The path in which to save the item.
Type | Optional | Variant | The file type to save. Can be one of the following OlSaveAsType constants: olHTML, olMSG, olRTF, olTemplate, olDoc, olTXT, olVCal, olVCard, olICal, or olMSGUnicode.

Remarks

Also note that even though olDoc is a valid OlSaveAsType constant, messages in HTML format cannot be saved in Document format, and the olDoc constant works only if Microsoft Word is set up as the default email editor.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ShowCategoriesDialog Method (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ShowCategoriesDialog Method (Outlook)
See also Send feedback

Published: July 16, 2012

Displays the Show Categories dialog box, which allows you to select categories that correspond to the subject of the item.

Syntax

expression .ShowCategoriesDialog

expression A variable that represents a TaskRequestUpdateItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem Events (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
AfterWrite | Occurs after Microsoft Outlook has saved the item.
AttachmentAdd | Occurs when an attachment has been added to an instance of the parent object.
AttachmentRead | Occurs when an attachment in an instance of the parent object has been opened for reading.
AttachmentRemove | Occurs when an attachment has been removed from an instance of the parent object.
BeforeAttachmentAdd | Occurs before an attachment is added to an instance of the parent object.
BeforeAttachmentPreview | Occurs before an attachment associated with an instance of the parent object is previewed.
BeforeAttachmentRead | Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.
BeforeAttachmentSave | Occurs just before an attachment is saved.
BeforeAttachmentWriteToTempFile | Occurs before an attachment associated with an instance of the parent object is written to a temporary file.
BeforeAutoSave | Occurs before the item is automatically saved by Outlook.
BeforeCheckNames | Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).
BeforeDelete | Occurs before an item (which is an instance of the parent object) is deleted.
BeforeRead | Occurs before Microsoft Outlook begins to read the properties for the item.
Close | Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.
CustomAction | Occurs when a custom action of an item (which is an instance of the parent object) executes.
CustomPropertyChange | Occurs when a custom property of an item (which is an instance of the parent object) is changed.
Forward | Occurs when the user selects the Forward action for an item (which is an instance of the parent object).
Open | Occurs when an instance of the parent object is being opened in an Inspector.
PropertyChange | Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.
Read | Occurs when an instance of the parent object is opened for editing by the user.
ReadComplete | Occurs when Outlook has completed reading the properties of the item.
Reply | Occurs when the user selects the Reply action for an item (which is an instance of the parent object).
ReplyAll | Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).
Send | Occurs when the user selects the Send action for an item (which is an instance of the parent object).
Unload | Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.
Write | Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).


TaskRequestUpdateItem.AfterWrite Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.AfterWrite Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs after Microsoft Outlook has saved the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .AfterWrite

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The AfterWrite event occurs after the Write event. This event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The AfterWrite event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnWriteComplete.

Only the following members of the item object can be accessed in the AfterWrite event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

The object obtained from the MAPIOBJECT property in this event must contain all the changes persisted by Outlook. The implementer can call the SaveChanges method on the IMessage object to persist changes to the underlying IMessage object represented by MAPIOBJECT, and Outlook will not revert those changes.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.AttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.AttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment has been added to an instance of the parent object.

Syntax

expression .AttachmentAdd(Attachment)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was added to the item.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.AttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.AttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an attachment in an instance of the parent object has been opened for reading.

Syntax

expression .AttachmentRead(Attachment)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was opened.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.AttachmentRemove Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.AttachmentRemove Event (Outlook)
See also Send feedback

Occurs when an attachment has been removed from an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .AttachmentRemove(Attachment, )

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment that was removed from the item.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAttachmentAdd Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAttachmentAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment is added to an instance of the parent object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentAdd(Attachment, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be added to the item.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be added.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAttachmentPreview Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAttachmentPreview Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is previewed.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentPreview(Attachment, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be previewed.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be previewed.

Remarks

This event occurs before an attachment is previewed, either from the attachment strip in the Reading Pane of the active explorer or from the active inspector.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAttachmentRead Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAttachmentRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is read from the file system, an attachment stream, or an Attachment object.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentRead(Attachment, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be read.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be read.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAttachmentSave Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAttachmentSave Event (Outlook)
See also Send feedback

Occurs just before an attachment is saved.

Syntax

expression .BeforeAttachmentSave(Attachment, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be saved.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed and the attachment is not changed.

Remarks

This event corresponds to when attachments are saved to the messaging store. The BeforeAttachmentSave event occurs just before an attachment is saved when an item is saved. If a user edits an attachment and then saves those changes, the BeforeAttachmentSave event will not occur at that time; instead it will occur when the item itself is later saved. It also does not occur when the attachment is saved on the hard disk using the SaveAsFile method.

In VBScript, if you set the return value of this function to False, the save operation is cancelled and the attachment is not changed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAttachmentWriteToTempFile Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAttachmentWriteToTempFile Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an attachment associated with an instance of the parent object is written to a temporary file.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAttachmentWriteToTempFile(Attachment, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Attachment | Required | Attachment | The Attachment to be written.
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the Attachment to be written.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeAutoSave Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeAutoSave Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before the item is automatically saved by Outlook.

Version Information

Version Added: Outlook 2007

Syntax

expression .BeforeAutoSave(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | Set to True to cancel the operation; otherwise, set to False to allow the TaskRequestUpdateItem to be saved.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeCheckNames Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeCheckNames Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs just before Microsoft Outlook starts resolving names in the recipient collection for an item (which is an instance of the parent object).

Syntax

expression .BeforeCheckNames(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the name resolution process is not completed.

Remarks

You use the BeforeCheckNames event in VBScript, but the event does not fire when an e-mail name is resolved on the form.

The event does not fire under the following circumstances:

  • You customized a Journal Entry form and then resolved a contact in the Contacts field.

  • You customized a Contact form and then resolved a contact in the Contacts field.

  • You customized any type of form and Outlook automatically resolved the name in the background.

  • You programmatically created and resolved a recipient.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeDelete Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeDelete Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an item (which is an instance of the parent object) is deleted.

Syntax

expression .BeforeDelete(Item, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Item | Required | Object | The item being deleted.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the operation is not completed and the item is not deleted.

Remarks

In order for this event to fire when an e-mail message, distribution list, journal entry, task, contact, or post are deleted through an action, an inspector must be open.

The event occurs each time an item is deleted.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.BeforeRead Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.BeforeRead Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before Microsoft Outlook begins to read the properties for the item.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeRead

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The BeforeRead event occurs before the Read event. Unlike other events with the Before prefix, this event is not cancelable. To determine when the item is unloaded from memory, use the Unload event.

The BeforeRead event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnRead.

Only the following members of the item object can be accessed in the BeforeRead event:

  • Class

  • MessageClass

  • MAPIOBJECT

The MAPIOBJECT property is a hidden property in the Outlook object model. This property provides access to the underlying MAPI IMessage object, and can be invoked only via the IUnknown interface. The property is accessible to programs written in languages such as C or C++ that support IUnknown. MAPIOBJECT is not available through the IDispatch interface. Development languages such as Visual Basic for Applications (VBA), Visual C#, and Visual Basic support the IDispatch interface and not IUnknown, and therefore, they cannot access MAPIOBJECT. If other properties or methods of the parent item are accessed in this event, Outlook raises an error.

If the implementer accesses the underlying IMessage object and changes properties on that object, Outlook will render that item reflecting the changes to the IMessage object. The implementer does not have to call SaveChanges on the IMessage object to cause the changes to be reflected in Outlook.

Implementers must release the object obtained from the MAPIOBJECT property in the event before the event completes. Attempting to use that object outside the context of the event is unsupported and will lead to unpredictable behavior.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Close Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Close Event (Outlook)
See also Send feedback

Occurs when the inspector associated with an item (which is an instance of the parent object) is being closed.

Syntax

expression .Close(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the close operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the close operation isn't completed and the inspector is left open.

If you use the Close method to fire this event, it can only be canceled if the Close method uses the olPromptForSave argument.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.CustomAction Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.CustomAction Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom action of an item (which is an instance of the parent object) executes.

Syntax

expression .CustomAction(Action, Response, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Action | Required | Object | The Action object.
Response | Required | Object | The newly created item resulting from the custom action.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the custom action is not completed.

Remarks

The Action object and the newly created item resulting from the custom action are passed to the event.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the custom action operation is not completed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.CustomPropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.CustomPropertyChange Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a custom property of an item (which is an instance of the parent object) is changed.

Syntax

expression .CustomPropertyChange(Name)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the custom property that was changed.

Remarks

The property name is passed to the procedure so that you can determine which custom property changed.

Example

This Microsoft Visual Basic Scripting Edition (VBScript) example uses the CustomPropertyChange event to enable a control when a Boolean field is set to True.

For this example, create two custom fields on the second page of a form. The first, a Boolean field, is named "RespondBy". The second field is named "DateToRespond".

Copy code Copy code
Sub Item_CustomPropertyChange(ByVal myPropName)

 Select Case myPropName

 Case "RespondBy"

 Set myPages = Item.GetInspector.ModifiedFormPages

 Set myCtrl = myPages("P.2").Controls("DateToRespond")

 If Item.UserProperties("RespondBy").Value Then

 myCtrl.Enabled = True

 myCtrl.Backcolor = 65535 'Yellow

 Else

 myCtrl.Enabled = False

 myCtrl.Backcolor = 0 'Black

 End If

 Case Else

 End Select

End Sub

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Forward Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Forward Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Forward action for an item (which is an instance of the parent object).

Syntax

expression .Forward(Forward, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Forward | Required | Object | The new item being forwarded.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the forward operation is not completed and the new item is not displayed.

Remarks

In VBScript, if you set the return value of this function to False, the forward action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Open Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Open Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when an instance of the parent object is being opened in an Inspector.

Syntax

expression .Open(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the open operation is not completed and the inspector is not displayed.

Remarks

When this event occurs, the Inspector object is initialized but not yet displayed. The Open event differs from the Read event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an inspector.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the open operation is not completed and the inspector is not displayed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.PropertyChange Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.PropertyChange Event (Outlook)
See also Send feedback

Occurs when an explicit built-in property (for example, Subject) of an instance of the parent object is changed.

Syntax

expression .PropertyChange(Name)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property that was changed.

Remarks

The property name is passed to the event so that you can determine which property was changed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Read Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Read Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is opened for editing by the user.

Syntax

expression .Read

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

The Read event differs from the Open event in that Read occurs whenever the user selects the item in a view that supports in-cell editing as well as when the item is being opened in an Inspector.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ReadComplete Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ReadComplete Event (Outlook)
See also Send feedback

Occurs when Outlook has completed reading the properties of the item.

Version information

Version Added: Outlook 2013

Syntax

expression .ReadComplete(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the read operation is not completed and the item is not displayed in the Reading Pane or inspector.

Remarks

The ReadComplete event occurs after the BeforeRead event and before the Read event for the item.

To determine when the item is unloaded from memory, use the Unload event.

The ReadComplete event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Reply Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Reply Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Reply action for an item (which is an instance of the parent object).

Syntax

expression .Reply(Response, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the reply operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the reply action is not completed and the new item is not displayed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.ReplyAll Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.ReplyAll Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the ReplyAll action for an item (which is an instance of the parent object).

Syntax

expression .ReplyAll(Response, Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Response | Required | Object | The new item being sent in response to the original message.
Cancel | Required | Boolean | False when the event occurs. If the event procedure sets this argument to True, the reply all operation is not completed and the new item is not displayed.

Remarks

Returns the reply as a MailItem object.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Send Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Send Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when the user selects the Send action for an item (which is an instance of the parent object).

Syntax

expression .Send(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the send operation is not completed and the inspector is left open.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the item is not sent.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Unload Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Unload Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs before an Outlook item is unloaded from memory, either programmatically or by user action.

Version Information

Version Added: Outlook 2007

Syntax

expression .Unload

expression A variable that represents a TaskRequestUpdateItem object.

Remarks

This event occurs after the Close event for the Outlook item occurs, but before the Outlook item is unloaded from memory, allowing an add-in to release any resources related to the object. Although the event occurs before the Outlook item is unloaded from memory, this event cannot be canceled.

Note Note

This event is meant only as a notification event, so that an add-in can dereference the object. An error occurs if any property or method for this object is called within the Unload event.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TaskRequestUpdateItem.Write Event (Outlook)

 Copy code hover
[image]

TaskRequestUpdateItem.Write Event (Outlook)
See also Send feedback

Occurs when an instance of the parent object is saved, either explicitly (for example, using the Save or SaveAs methods) or implicitly (for example, in response to a prompt when closing the item's inspector).

Syntax

expression .Write(Cancel)

expression A variable that represents a TaskRequestUpdateItem object.

Parameters

Name | Required/Optional | Data Type | Description
Cancel | Required | Boolean | (Not used in VBScript). False when the event occurs. If the event procedure sets this argument to True, the save operation is not completed.

Remarks

In Microsoft Visual Basic Scripting Edition (VBScript), if you set the return value of this function to False, the save operation is not completed.

See also

Concepts

TaskRequestUpdateItem Object

Other resources

TaskRequestUpdateItem Object Members


TasksModule Object (Outlook)

 Copy code hover
[image]

TasksModule Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the Tasks navigation module in the Navigation Pane of an explorer.

Version Information

Version Added: Outlook 2007

Remarks

The TasksModule object, derived from the NavigationModule object, provides access to the navigation groups contained in the Tasks navigation module of the Navigation Pane for an explorer. Use the GetNavigationModule method or the Item method of the NavigationModules collection for the parent NavigationPane object to retrieve a NavigationModule object, then use the NavigationModuleType property of the NavigationModule object to retrieve the navigation module type. If the NavigationModuleType property is set to olModuleTasks, you can then cast the NavigationModule object reference as a TasksModule object to access the NavigationGroups property for that navigation module.

You can use the Visible property to determine if the navigation module is visible and the Position property to return or set the display position of the navigation module within the Navigation Pane. You can use the Name property to return the display name of the Tasks navigation module within the Navigation Pane.

See also

Concepts

Outlook Object Model Reference

Other resources

TasksModule Object Members


TasksModule Members (Outlook)

 Copy code hover
[image]

TasksModule Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the Tasks navigation module in the Navigation Pane of an explorer.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the TasksModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the TasksModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the TasksModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the TasksModule object is displayed in the Navigation Pane. Read/write.


TasksModule Properties (Outlook)

 Copy code hover
[image]

TasksModule Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Name | Returns a String value that represents the localized display name for the TasksModule object. Read-only.
NavigationGroups | Returns a NavigationGroups object that contains the set of navigation groups associated with the TasksModule object. Read-only.
NavigationModuleType | Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Position | Returns or sets a Long value that represents the ordinal position of the TasksModule object when it is displayed in the Navigation Pane. Read/write.
Session | Returns the NameSpace object for the current session. Read-only.
Visible | Returns or sets a Boolean value that determines whether the TasksModule object is displayed in the Navigation Pane. Read/write.


TasksModule.Application Property (Outlook)

 Copy code hover
[image]

TasksModule.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Class Property (Outlook)

 Copy code hover
[image]

TasksModule.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a TasksModule object.

Remarks

This property returns olTasksModule for the TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Name Property (Outlook)

 Copy code hover
[image]

TasksModule.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the localized display name for the TasksModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.NavigationGroups Property (Outlook)

 Copy code hover
[image]

TasksModule.NavigationGroups Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a NavigationGroups object that contains the set of navigation groups associated with the TasksModule object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationGroups

expression A variable that represents a TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.NavigationModuleType Property (Outlook)

 Copy code hover
[image]

TasksModule.NavigationModuleType Property (Outlook)
See also Send feedback

Returns an OlNavigationModuleType constant that represents the navigation module type for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .NavigationModuleType

expression An expression that returns a TasksModule object.

Remarks

This property returns olModuleTasks for the TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Parent Property (Outlook)

 Copy code hover
[image]

TasksModule.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Position Property (Outlook)

 Copy code hover
[image]

TasksModule.Position Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the ordinal position of the TasksModule object when it is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Position

expression A variable that represents a TasksModule object.

Remarks

This property can only be set to a value between 1 and 9. An error occurs if you attempt to set this property to a value outside that range.

Changing the value of this property for a given TasksModule object changes the Position values of other navigation modules in a NavigationModules collection, depending on the relative change between the new value and the original value.

  • If the new value is less than the original value, the specified TasksModule object moves up to the new position and the other navigation modules that are already at or below that new position move down.

  • If the new value is greater than the original value, the specified TasksModule object moves down to the new position and the other navigation modules that are between the old position and the new position move up, filling the old position.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Session Property (Outlook)

 Copy code hover
[image]

TasksModule.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a TasksModule object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TasksModule.Visible Property (Outlook)

 Copy code hover
[image]

TasksModule.Visible Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines whether the TasksModule object is displayed in the Navigation Pane. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Visible

expression A variable that represents a TasksModule object.

See also

Concepts

TasksModule Object

Other resources

TasksModule Object Members


TextRuleCondition Object (Outlook)

 Copy code hover
[image]

TextRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that the part of the message, which can be the body, header, or subject, as specified by TextRuleCondition.ConditionType, contains the words specified in TextRuleCondition.Text.

Version Information

Version Added: Outlook 2007

Remarks

TextRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has the following properties: Body, BodyOrSubject, MessageHeader, and Subject. Each of these properties always returns a TextRuleCondition object. TextRuleCondition.ConditionType distinguishes among these rule conditions. If the rule has any of these rule conditions enabled, then TextRuleCondition.Enabled would be True.

For more information on specifying rule conditions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

TextRuleCondition Object Members


TextRuleCondition Members (Outlook)

 Copy code hover
[image]

TextRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that the part of the message, which can be the body, header, or subject, as specified by TextRuleCondition.ConditionType, contains the words specified in TextRuleCondition.Text.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Text | Returns or sets an array of String elements that represents the text to be evaluated by the rule condition. Read/write.


TextRuleCondition Properties (Outlook)

 Copy code hover
[image]

TextRuleCondition Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Text | Returns or sets an array of String elements that represents the text to be evaluated by the rule condition. Read/write.


TextRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a TextRuleCondition object.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a TextRuleCondition object.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a TextRuleCondition object.

Remarks

The value of ConditionType depends on the type of rule condition, as several types of rule conditions use the TextRuleCondition object: olConditionBody, olConditionBodyOrSubject, olConditionMessageHeader, and olConditionSubject. Except for olConditionMessageHeader, which is supported only by rules for receiving messages, all these types of conditions are supported by rules for receiving messages as well as rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean that determines if the rule condition is enabled. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a TextRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it have been saved successfully.

Returns an error if you attempt to enable a rule condition that is supported only on a rule of type olRuleSend for a rule of type olRuleReceive, or vice versa. For more information on suppport by rules for receiving messages or rules for sending messages, see Specify Rule Conditions.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a TextRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a TextRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TextRuleCondition.Text Property (Outlook)

 Copy code hover
[image]

TextRuleCondition.Text Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an array of String elements that represents the text to be evaluated by the rule condition. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Text

expression A variable that represents a TextRuleCondition object.

Remarks

You can assign an array with one string or multiple strings for evaluation. Multiple text strings assigned in an array are evaluated using the logical OR operation.

See also

Concepts

TextRuleCondition Object

Other resources

TextRuleCondition Object Members


TimelineView Object (Outlook)

 Copy code hover
[image]

TimelineView Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items in a timeline.

Version Information

Version Added: Outlook 2007

Remarks

The TimelineView object, derived from the View object, allows you to create customizable views that allow you to display Outlook items within a timeline.

Outlook provides several built-in TimelineView objects, and you can also create custom TimelineView objects. Use the Add method of the Views collection to add a new TimelineView to a Folder object. Use the Standard property to determine if an existing TimelineView object is built-in or custom.

The TimelineView object supports several different view modes, depending on the desired layout and time period in which to display Outlook items. Use the TimelineViewMode property to set the view mode, the StartField property to specify the Outlook item property that contains the start date, and the EndField property to specify the Outlook item property that contains the end date for Outlook items to be displayed.

You can configure the appearance of the TimelineView, depending on the view mode. Use the ShowWeekNumbers property to indicate whether week numbers are displayed in the time scale for the view. Use the UpperScaleFont and LowerScaleFont properties to specify the font used when displaying, respectively, the upper and lower portions of the time scale for the view.

You can also configure how Outlook items appear within the TimelineView object. Use the ItemFont property to specify the font used to display Outlook item labels and the MaxLabelWidth property to specify the length of labels for Outlook items in the view. Use the DefaultExpandCollapseSetting property to determine if Outlook items are expanded by default in the view. Use the Filter property to determine which Outlook items to display in the view and the GroupByFields collection to specify the Outlook item properties by which Outlook items are grouped in the view. If you set the TimelineViewMode to olTimelineViewMonth, you can use the ShowLabelWhenViewingByMonth property to determine if labels for Outlook items are displayed in the view.

The definition for each TimelineView object is stored in Extensible Markup Language (XML) format. Use the XML property to work with the XML definition for the TimelineView object.

Use the Apply method to apply any changes made to the TimelineView object to the current view. Use the Save method to persist any changes made to the TimelineView object. Use the LockUserChanges property to allow or prevent changes to the user interface for the view.

You can change built-in TimelineView objects, but you cannot delete them. Use the Delete method to delete a custom TimelineView object. Use the Reset method to reset the properties of a built-in TimelineView object to their default values.

Example

The following Visual Basic for Applications (VBA) example configures the current TimelineView object to display Outlook items by month, with week number labels on the lower portion of the timeline scale, with labels no longer than 40 characters.

Copy code Copy code
Private Sub ConfigureMonthTimelineView()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Configure the TimelineView object so that it displays

 ' Outlook items by month and week, displaying labels

 ' no larger than 40 characters for Outlook items

 ' displayed in the view.

 With objTimelineView

 ' Display items by month.

 .TimelineViewMode = olTimelineViewMonth

 ' Display week numbers. If this value is

 ' set to False when TimelineViewMode is

 ' set to olTimelineViewMonth, the day

 ' numbers are displayed instead.

 .ShowWeekNumbers = True

 ' Display labels for Outlook items

 ' while TimelineViewMode is set to

 ' olTimelineViewMonth.

 .ShowLabelWhenViewingByMonth = True

 ' Show no more than the first 40 characters

 ' for each Outlook item in the view.

 .MaxLabelWidth = 40

 ' Save and apply the view.

 .Save

 .Apply

 End With

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

TimelineView Object Members


TimelineView Members (Outlook)

 Copy code hover
[image]

TimelineView Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view that displays Outlook items in a timeline.

Methods

Name | Description
Apply | Applies the TimelineView object to the current view.
Copy | Creates a new View object based on the existing TimelineView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DefaultExpandCollapseSetting | Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TimelineView object. Read/write.
EndField | Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the TimelineView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
GroupByFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TimelineView object are grouped. Read-only.
ItemFont | Returns a ViewFont object that represents the font used when displaying Outlook items in the TimelineView object. Read-only.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
LowerScaleFont | Returns a ViewFont object that represents the font used to display the lower portion of the timeline scale for a TimelineView object. Read-only.
MaxLabelWidth | Returns or sets a Long value that represents the maximum length (in characters) for the label of an Outlook item in the TimelineView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowLabelWhenViewingByMonth | Returns or sets a Boolean value that determines if labels for Outlook items are displayed when viewing by month in the TimelineView object. Read/write.
ShowWeekNumbers | Returns or sets a Boolean value that indicates whether week number labels are displayed in the timeline scale for the TimelineView object. Read/write.
Standard | Returns a Boolean value that indicates whether the TimelineView object is a built-in Outlook view. Read-only.
StartField | Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the TimelineView object. Read/write.
TimelineViewMode | Returns or sets an OlTimelineViewMode constant that indicates the view mode for the TimelineView object. Read/write.
UpperScaleFont | Returns a ViewFont object that represents the font used to display the upper portion of the timeline scale for a TimelineView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


TimelineView Properties (Outlook)

 Copy code hover
[image]

TimelineView Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DefaultExpandCollapseSetting | Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TimelineView object. Read/write.
EndField | Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the TimelineView object. Read/write.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
GroupByFields | Returns an OrderFields object that represents the set of fields by which the items displayed in the TimelineView object are grouped. Read-only.
ItemFont | Returns a ViewFont object that represents the font used when displaying Outlook items in the TimelineView object. Read-only.
Language | Returns or sets a String value that represents the language setting for the view. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.
LowerScaleFont | Returns a ViewFont object that represents the font used to display the lower portion of the timeline scale for a TimelineView object. Read-only.
MaxLabelWidth | Returns or sets a Long value that represents the maximum length (in characters) for the label of an Outlook item in the TimelineView object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ShowLabelWhenViewingByMonth | Returns or sets a Boolean value that determines if labels for Outlook items are displayed when viewing by month in the TimelineView object. Read/write.
ShowWeekNumbers | Returns or sets a Boolean value that indicates whether week number labels are displayed in the timeline scale for the TimelineView object. Read/write.
Standard | Returns a Boolean value that indicates whether the TimelineView object is a built-in Outlook view. Read-only.
StartField | Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the TimelineView object. Read/write.
TimelineViewMode | Returns or sets an OlTimelineViewMode constant that indicates the view mode for the TimelineView object. Read/write.
UpperScaleFont | Returns a ViewFont object that represents the font used to display the upper portion of the timeline scale for a TimelineView object. Read-only.
ViewType | Returns an OlViewType constant that indicates the view type of the view. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the view. Read/write.


TimelineView.Application Property (Outlook)

 Copy code hover
[image]

TimelineView.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Class Property (Outlook)

 Copy code hover
[image]

TimelineView.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.DefaultExpandCollapseSetting Property (Outlook)

 Copy code hover
[image]

TimelineView.DefaultExpandCollapseSetting Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlDefaultExpandCollapseSetting constant that determines the default expansion setting for groups in the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .DefaultExpandCollapseSetting

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.EndField Property (Outlook)

 Copy code hover
[image]

TimelineView.EndField Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the name of the property that ends the time duration for Outlook items displayed in the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .EndField

expression A variable that represents a TimelineView object.

Remarks

The values of the StartField and EndField properties indicate which Outlook item properties are used by the TimelineView object to represent the duration of an Outlook item. Both custom and built-in properties can be specified, but only date/time properties are allowed.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Filter Property (Outlook)

 Copy code hover
[image]

TimelineView.Filter Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents a TimelineView object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.GroupByFields Property (Outlook)

 Copy code hover
[image]

TimelineView.GroupByFields Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OrderFields object that represents the set of fields by which the items displayed in the TimelineView object are grouped. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .GroupByFields

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.ItemFont Property (Outlook)

 Copy code hover
[image]

TimelineView.ItemFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used when displaying Outlook items in the TimelineView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ItemFont

expression A variable that represents a TimelineView object.

Example

The following Visual Basic for Applications (VBA) sample increments the value of the Size property for the ViewFont object returned from the ItemFont property for the current TimelineView object.

Copy code Copy code
Private Sub IncreaseItemFontSize()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Increment the Size property of the

 ' ViewFont object obtained from the

 ' ItemFont property, but only

 ' if the font is less than 24 points

 ' in size.

 If objTimelineView.ItemFont.Size < 24 Then

 objTimelineView.ItemFont.Size = _

 objTimelineView.ItemFont.Size + 1

 ' Save the timeline view.

 objTimelineView.Save

 End If

 End If

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Language Property (Outlook)

 Copy code hover
[image]

TimelineView.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the language setting for the view. Read/write.

Syntax

expression .Language

expression A variable that represents a TimelineView object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

Example

The following Microsoft Visual Basic for Applications (VBA) example sets the language type of all View objects of type olTableView to U.S. English.

VBA Copy code Copy code
Sub SetLanguage()

 'Sets the language of all table views to U.S. English.

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Iterate through each view in the collection.

 For Each objView In objViews

 Debug.Print objView.Name

 'If view is of type olTableVIew then set language.

 If objView.ViewType = olTableView And objView.Standard = False Then

 objView.Language = "EN-US"

 End If

 Next objView

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.LockUserChanges Property (Outlook)

 Copy code hover
[image]

TimelineView.LockUserChanges Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a user can modify the settings of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .LockUserChanges

expression A variable that represents a TimelineView object.

Remarks

If True, the user can modify the settings of the specified view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.LowerScaleFont Property (Outlook)

 Copy code hover
[image]

TimelineView.LowerScaleFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display the lower portion of the timeline scale for a TimelineView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .LowerScaleFont

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.MaxLabelWidth Property (Outlook)

 Copy code hover
[image]

TimelineView.MaxLabelWidth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the maximum length (in characters) for the label of an Outlook item in the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .MaxLabelWidth

expression A variable that represents a TimelineView object.

Remarks

This property can be set to a value between 0 and 132. If this property is set to a value less than 0, the property is set to 0. If this property is set to a value greater than 132, the property is set to 132. The default value for this property is 80.

If this property is set to 0, labels for Outlook items are not displayed in the view.

Example

The following Visual Basic for Applications (VBA) example configures the current TimelineView object to display Outlook items by month, with week number labels on the lower portion of the timeline scale, with labels no longer than 40 characters.

Copy code Copy code
Private Sub ConfigureMonthTimelineView()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Configure the TimelineView object so that it displays

 ' Outlook items by month and week, displaying labels

 ' no larger than 40 characters for Outlook items

 ' displayed in the view.

 With objTimelineView

 ' Display items by month.

 .TimelineViewMode = olTimelineViewMonth

 ' Display week numbers. If this value is

 ' set to False when TimelineViewMode is

 ' set to olTimelineViewMonth, the day

 ' numbers are displayed instead.

 .ShowWeekNumbers = True

 ' Display labels for Outlook items

 ' while TimelineViewMode is set to

 ' olTimelineViewMonth.

 .ShowLabelWhenViewingByMonth = True

 ' Show no more than the first 40 characters

 ' for each Outlook item in the view.

 .MaxLabelWidth = 40

 ' Save and apply the view.

 .Save

 .Apply

 End With

 End If

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Name Property (Outlook)

 Copy code hover
[image]

TimelineView.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Parent Property (Outlook)

 Copy code hover
[image]

TimelineView.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.SaveOption Property (Outlook)

 Copy code hover
[image]

TimelineView.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .SaveOption

expression A variable that represents a TimelineView object.

Remarks

The value of the SaveOption property is set when the TimelineView object is created by using the Add method of the Views collection.

Example

The following Visual Basic for Applications (VBA) example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View user interface will be locked. In this example, the procedure is always called with the Boolean value set to True.

Copy code Copy code
Sub LockPublicViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection for the Contacts default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderContacts).Views

 ' Enumerate the Views collection and lock the user

 ' interface for any view that can be accessed by

 ' all users who have access to the Notes default folder.

 For Each objView In objViews

 If objView.SaveOption = _

 olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 ' Examine the view object.

 With objView

 If blnAns = True Then

 ' Lock the user interface and

 ' save the view

 .LockUserChanges = True

 .Save

 Else

 ' Unlock the user interface of the view.

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Session Property (Outlook)

 Copy code hover
[image]

TimelineView.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a TimelineView object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.ShowLabelWhenViewingByMonth Property (Outlook)

 Copy code hover
[image]

TimelineView.ShowLabelWhenViewingByMonth Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that determines if labels for Outlook items are displayed when viewing by month in the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowLabelWhenViewingByMonth

expression A variable that represents a TimelineView object.

Remarks

This property is applicable only if the TimelineViewMode property is set to olTimelineViewMonth.

Example

The following Visual Basic for Applications (VBA) example configures the current TimelineView object to display Outlook items by month, with week number labels on the lower portion of the timeline scale, with labels no longer than 40 characters.

Copy code Copy code
Private Sub ConfigureMonthTimelineView()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Configure the TimelineView object so that it displays

 ' Outlook items by month and week, displaying labels

 ' no larger than 40 characters for Outlook items

 ' displayed in the view.

 With objTimelineView

 ' Display items by month.

 .TimelineViewMode = olTimelineViewMonth

 ' Display week numbers. If this value is

 ' set to False when TimelineViewMode is

 ' set to olTimelineViewMonth, the day

 ' numbers are displayed instead.

 .ShowWeekNumbers = True

 ' Display labels for Outlook items

 ' while TimelineViewMode is set to

 ' olTimelineViewMonth.

 .ShowLabelWhenViewingByMonth = True

 ' Show no more than the first 40 characters

 ' for each Outlook item in the view.

 .MaxLabelWidth = 40

 ' Save and apply the view.

 .Save

 .Apply

 End With

 End If

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.ShowWeekNumbers Property (Outlook)

 Copy code hover
[image]

TimelineView.ShowWeekNumbers Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether week number labels are displayed in the timeline scale for the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .ShowWeekNumbers

expression A variable that represents a TimelineView object.

Remarks

If this property is set to True, the location in which week number labels are displayed in the timeline scale for the TimelineView object depends on the value of the TimelineViewMode property.

Property value | Label location
olTimelineViewDay | Displayed in the upper portion of the timeline scale, prefacing the date label.
olTimelineViewWeek | Displayed in the upper portion of the timeline scale, prefacing the week label.
olTimelineViewMonth | Displayed in the lower portion of the timeline scale, replacing the day and date labels.

Example

The following Visual Basic for Applications (VBA) example configures the current TimelineView object to display Outlook items by month, with week number labels on the lower portion of the timeline scale, with labels no longer than 40 characters.

Copy code Copy code
Private Sub ConfigureMonthTimelineView()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Configure the TimelineView object so that it displays

 ' Outlook items by month and week, displaying labels

 ' no larger than 40 characters for Outlook items

 ' displayed in the view.

 With objTimelineView

 ' Display items by month.

 .TimelineViewMode = olTimelineViewMonth

 ' Display week numbers. If this value is

 ' set to False when TimelineViewMode is

 ' set to olTimelineViewMonth, the day

 ' numbers are displayed instead.

 .ShowWeekNumbers = True

 ' Display labels for Outlook items

 ' while TimelineViewMode is set to

 ' olTimelineViewMonth.

 .ShowLabelWhenViewingByMonth = True

 ' Show no more than the first 40 characters

 ' for each Outlook item in the view.

 .MaxLabelWidth = 40

 ' Save and apply the view.

 .Save

 .Apply

 End With

 End If

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Standard Property (Outlook)

 Copy code hover
[image]

TimelineView.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the TimelineView object is a built-in Outlook view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Standard

expression A variable that represents a TimelineView object.

Remarks

The Reset method can only be used on a view if the value of this property is set to True.

Example

The following Visual Basic for Applications (VBA) example enumerates through the Views collection of the current Folder object, using the Standard property to determine if a View object is a built-in Outlook view. If the View object is a built-in Outlook view, the sample calls the Reset method to reset the view to its default settings. Otherwise, the sample uses the Delete method to delete the view.

Copy code Copy code
Private Sub RemoveAllViewCustomization()

 Dim objView As View

 ' Enumerate each View object in the Views collection

 ' of the current Folder object.

 For Each objView In Application.ActiveExplorer.CurrentFolder.Views

 ' If the View object is a built-in Outlook view, reset

 ' the view to its default settings. If the View object

 ' is a custom view, delete it.

 If objView.Standard Then

 objView.Reset

 Else

 objView.Delete

 End If

 Next

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.StartField Property (Outlook)

 Copy code hover
[image]

TimelineView.StartField Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the name of the property that starts the time duration for Outlook items displayed in the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .StartField

expression A variable that represents a TimelineView object.

Remarks

The values of the StartField and EndField properties indicate which Outlook item properties are used by the TimelineView object to represent the duration of an Outlook item. Both custom and built-in properties can be specified, but only date/time properties are allowed.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.TimelineViewMode Property (Outlook)

 Copy code hover
[image]

TimelineView.TimelineViewMode Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlTimelineViewMode constant that indicates the view mode for the TimelineView object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .TimelineViewMode

expression A variable that represents a TimelineView object.

Example

The following Visual Basic for Applications (VBA) example configures the current TimelineView object to display Outlook items by month, with week number labels on the lower portion of the timeline scale, with labels no longer than 40 characters.

Copy code Copy code
Private Sub ConfigureMonthTimelineView()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Configure the TimelineView object so that it displays

 ' Outlook items by month and week, displaying labels

 ' no larger than 40 characters for Outlook items

 ' displayed in the view.

 With objTimelineView

 ' Display items by month.

 .TimelineViewMode = olTimelineViewMonth

 ' Display week numbers. If this value is

 ' set to False when TimelineViewMode is

 ' set to olTimelineViewMonth, the day

 ' numbers are displayed instead.

 .ShowWeekNumbers = True

 ' Display labels for Outlook items

 ' while TimelineViewMode is set to

 ' olTimelineViewMonth.

 .ShowLabelWhenViewingByMonth = True

 ' Show no more than the first 40 characters

 ' for each Outlook item in the view.

 .MaxLabelWidth = 40

 ' Save and apply the view.

 .Save

 .Apply

 End With

 End If

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.UpperScaleFont Property (Outlook)

 Copy code hover
[image]

TimelineView.UpperScaleFont Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewFont object that represents the font used to display the upper portion of the timeline scale for a TimelineView object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .UpperScaleFont

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.ViewType Property (Outlook)

 Copy code hover
[image]

TimelineView.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant that indicates the view type of the view. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewType

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.XML Property (Outlook)

 Copy code hover
[image]

TimelineView.XML Property (Outlook)
See also Send feedback

Returns or sets a String value that specifies the XML definition of the view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .XML

expression A variable that represents a TimelineView object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView Methods (Outlook)

 Copy code hover
[image]

TimelineView Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the TimelineView object to the current view.
Copy | Creates a new View object based on the existing TimelineView object.
Delete | Deletes an object from a collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


TimelineView.Apply Method (Outlook)

 Copy code hover
[image]

TimelineView.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the TimelineView object to the current view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Apply

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Copy Method (Outlook)

 Copy code hover
[image]

TimelineView.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new View object based on the existing TimelineView object.

Version Information

Version Added: Outlook 2007

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents a TimelineView object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new view.
SaveOption | Optional | OlViewSaveOption | The save option for the new view.

Return Value

A View object that represents the new view.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Delete Method (Outlook)

 Copy code hover
[image]

TimelineView.Delete Method (Outlook)
See also Send feedback

Deletes an object from a collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.GoToDate Method (Outlook)

 Copy code hover
[image]

TimelineView.GoToDate Method (Outlook)
See also Send feedback

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents a TimelineView object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Reset Method (Outlook)

 Copy code hover
[image]

TimelineView.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Version Information

Version Added: Outlook 2007

Syntax

expression .Reset

expression A variable that represents a TimelineView object.

Remarks

This method works only on built-in Outlook views.

Example

The following Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox default folder to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetInboxViews()

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 ' Get the Views collection of the Inbox default folder.

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 ' Enumerate the Views collection, calling the Reset

 ' method for each View object with its Standard

 ' property value set to True.

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimelineView.Save Method (Outlook)

 Copy code hover
[image]

TimelineView.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Save

expression A variable that represents a TimelineView object.

See also

Concepts

TimelineView Object

Other resources

TimelineView Object Members


TimeZone Object (Outlook)

 Copy code hover
[image]

TimeZone Object (Outlook)
See also Send feedback

Represents information for a time zone as supported by Microsoft Windows.

Version Information

Version Added: Outlook 2007

Remarks

The TimeZone object is an Outlook wrapper for time zone data.

This data can be obtained from the Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones. In this case, some properties of this object are parts of in the TZI value for the time zone in the registry. A TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

See also

Concepts

Outlook Object Model Reference

Other resources

TimeZone Object Members


TimeZone Members (Outlook)

 Copy code hover
[image]

TimeZone Members (Outlook)
Send feedback

Published: July 16, 2012

Represents information for a time zone as supported by Microsoft Windows.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Bias | Returns a Long value that represents the difference in minutes of between the local time in this time zone and the Coordinated Universal Time (UTC). Read-only.
Class | Returns an OlObjectClass constant that represents the object's class. Read-only.
DaylightBias | Returns a Long value that represents the time offset in minutes from the Bias to account for daylight time in this time zone. Read-only.
DaylightDate | Returns a Date value that represents the date and time in this time zone when time changes over to daylight time in the current year. Read-only.
DaylightDesignation | Returns a String that identifies the time zone in daylight time. Read-only.
ID | Returns a String that uniquely identifies the time zone. Read-only.
Name | Returns a String that represents the identifier of the time zone. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StandardBias | Returns a Long value that represents the time offset in minutes from the Bias to account for standard time in this time zone. Read-only.
StandardDate | Returns a Date value that represents the date and time in this time zone when time changes over to standard time. Read-only.
StandardDesignation | Returns a String that identifies the time zone in standard time. Read-only.


TimeZone Properties (Outlook)

 Copy code hover
[image]

TimeZone Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Bias | Returns a Long value that represents the difference in minutes of between the local time in this time zone and the Coordinated Universal Time (UTC). Read-only.
Class | Returns an OlObjectClass constant that represents the object's class. Read-only.
DaylightBias | Returns a Long value that represents the time offset in minutes from the Bias to account for daylight time in this time zone. Read-only.
DaylightDate | Returns a Date value that represents the date and time in this time zone when time changes over to daylight time in the current year. Read-only.
DaylightDesignation | Returns a String that identifies the time zone in daylight time. Read-only.
ID | Returns a String that uniquely identifies the time zone. Read-only.
Name | Returns a String that represents the identifier of the time zone. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
StandardBias | Returns a Long value that represents the time offset in minutes from the Bias to account for standard time in this time zone. Read-only.
StandardDate | Returns a Date value that represents the date and time in this time zone when time changes over to standard time. Read-only.
StandardDesignation | Returns a String that identifies the time zone in standard time. Read-only.


TimeZone.Application Property (Outlook)

 Copy code hover
[image]

TimeZone.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a TimeZone object.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.Bias Property (Outlook)

 Copy code hover
[image]

TimeZone.Bias Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value that represents the difference in minutes of between the local time in this time zone and the Coordinated Universal Time (UTC). Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Bias

expression A variable that represents a TimeZone object.

Remarks

This value is stored as part of the value for TZI for that time zone in the Windows registry. The TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

Bias does not take into account any time offset for daylight time or standard time in the time zone. To account for any daylight time offset, use DaylightBias. In general, when the local time zone is adopting daylight time, UTC time is the result of adding the Bias and DaylightBias to the local time. To account for any standard time offset, use StandardBias. In general, when the local time zone is adopting standard time, UTC time is the result of adding the Bias and StandardBias to the local time.

For example, in a state adopting daylight time in the Pacific time zone, the Bias is 480 minutes and DaylightBias is -60 minutes. To determine the time in UTC for June 11, 2 A.M. PST, add a Bias of (480/60) hours and a DaylightBias of -(60/60) hours to the local time June 11, 2 A.M. The time in UTC is June 11, 9 A.M.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.Class Property (Outlook)

 Copy code hover
[image]

TimeZone.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that represents the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a TimeZone object.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.DaylightBias Property (Outlook)

 Copy code hover
[image]

TimeZone.DaylightBias Property (Outlook)
See also Send feedback

Returns a Long value that represents the time offset in minutes from the Bias to account for daylight time in this time zone. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DaylightBias

expression A variable that represents a TimeZone object.

Remarks

This value is stored as part of the value for TZI for that time zone in the Windows registry. The TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

In relation to the UTC time and the local time of the time zone, UTC time is the result of adding the Bias and DaylightBias to the local time. For example, in a state adopting daylight time in the Pacific time zone, the Bias is 480 minutes and DaylightBias is -60 minutes. To determine the time in UTC for June 11, 2 A.M. PST, add a Bias of (480/60) hours and a DaylightBias of -(60/60) hours to the local time June 11, 2 A.M. The time in UTC is June 11, 9 A.M.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.DaylightDate Property (Outlook)

 Copy code hover
[image]

TimeZone.DaylightDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date value that represents the date and time in this time zone when time changes over to daylight time in the current year. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DaylightDate

expression A variable that represents a TimeZone object.

Remarks

This value is stored as part of the TZI value for the time zone in the Windows registry. The TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.DaylightDesignation Property (Outlook)

 Copy code hover
[image]

TimeZone.DaylightDesignation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that identifies the time zone in daylight time. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DaylightDesignation

expression A variable that represents a TimeZone object.

Remarks

This property is stored as the Dlt value for the time zone in the registry.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.ID Property (Outlook)

 Copy code hover
[image]

TimeZone.ID Property (Outlook)
See also Send feedback

Returns a String that uniquely identifies the time zone. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ID

expression A variable that represents a TimeZone object.

Remarks

The ID of a time zone is globally the same for that time zone. It is the name of the Windows registry key that contains the time zone information. Unlike the Name property, the value of ID is not localized.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.Name Property (Outlook)

 Copy code hover
[image]

TimeZone.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that represents the identifier of the time zone. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a TimeZone object.

Remarks

The Name usually includes the offset value from Coordinated Universal Time (UTC), the official time zone name, and regions where the time zone is used. It is stored as the Display value in the registry key for a time zone.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.Parent Property (Outlook)

 Copy code hover
[image]

TimeZone.Parent Property (Outlook)
See also Send feedback

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a TimeZone object.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.Session Property (Outlook)

 Copy code hover
[image]

TimeZone.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a TimeZone object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.StandardBias Property (Outlook)

 Copy code hover
[image]

TimeZone.StandardBias Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value that represents the time offset in minutes from the Bias to account for standard time in this time zone. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .StandardBias

expression A variable that represents a TimeZone object.

Remarks

This value is stored as part of the value for TZI for the time zone in the Windows registry. The TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

In relation to the UTC time and the local time of the time zone, UTC time is the result of adding the Bias and StandardBias to the local time. For example, in a state adopting standard time in the Pacific time zone, the Bias is 480 minutes and StandardBias is 0 minutes. To determine the time in UTC for June 11, 2 A.M. PST, add a Bias of (480/60) hours and a StandardBias of 0 hours to the local time June 11, 2 A.M. The time in UTC is June 11, 10 A.M.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.StandardDate Property (Outlook)

 Copy code hover
[image]

TimeZone.StandardDate Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Date value that represents the date and time in this time zone when time changes over to standard time. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .StandardDate

expression A variable that represents a TimeZone object.

Remarks

This value is stored as part of the TZI value for the time zone in the Windows registry. The TZI value is mapped to the Windows TIME_ZONE_INFORMATION structure.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZone.StandardDesignation Property (Outlook)

 Copy code hover
[image]

TimeZone.StandardDesignation Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String that identifies the time zone in standard time. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .StandardDesignation

expression A variable that represents a TimeZone object.

Remarks

This property is stored as the Std value for the time zone in the registry.

See also

Concepts

TimeZone Object

Other resources

TimeZone Object Members


TimeZones Object (Outlook)

 Copy code hover
[image]

TimeZones Object (Outlook)
See also Send feedback

Published: July 16, 2012

A collection of TimeZone objects.

Version Information

Version Added: Outlook 2007

Remarks

This collection is read-only, and serves the purpose of enumerating time zones supported by Microsoft Windows and thus Outlook. Its value is accessible through the property Application.TimeZones and is based on the data stored in the Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones.

See also

Concepts

Outlook Object Model Reference

Other resources

TimeZones Object Members


TimeZones Members (Outlook)

 Copy code hover
[image]

TimeZones Members (Outlook)
Send feedback

Published: July 16, 2012

A collection of TimeZone objects.

Methods

Name | Description
ConvertTime | Converts a date/time value from one time zone to another time zone.
Item | Returns a TimeZone object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that represents the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
CurrentTimeZone | Returns a TimeZone value that represents the current Windows system local time zone. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


TimeZones Properties (Outlook)

 Copy code hover
[image]

TimeZones Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant that represents the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
CurrentTimeZone | Returns a TimeZone value that represents the current Windows system local time zone. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


TimeZones.Application Property (Outlook)

 Copy code hover
[image]

TimeZones.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a TimeZones object.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.Class Property (Outlook)

 Copy code hover
[image]

TimeZones.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant that represents the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a TimeZones object.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.Count Property (Outlook)

 Copy code hover
[image]

TimeZones.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a TimeZones object.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.CurrentTimeZone Property (Outlook)

 Copy code hover
[image]

TimeZones.CurrentTimeZone Property (Outlook)
See also Send feedback

Returns a TimeZone value that represents the current Windows system local time zone. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .CurrentTimeZone

expression A variable that represents a TimeZones object.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.Parent Property (Outlook)

 Copy code hover
[image]

TimeZones.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a TimeZones object.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.Session Property (Outlook)

 Copy code hover
[image]

TimeZones.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a TimeZones object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones Methods (Outlook)

 Copy code hover
[image]

TimeZones Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
ConvertTime | Converts a date/time value from one time zone to another time zone.
Item | Returns a TimeZone object from the collection.


TimeZones.ConvertTime Method (Outlook)

 Copy code hover
[image]

TimeZones.ConvertTime Method (Outlook)
See also Send feedback

Published: July 16, 2012

Converts a date/time value from one time zone to another time zone.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConvertTime(SourceDateTime, SourceTimeZone, DestinationTimeZone)

expression A variable that represents a TimeZones object.

Parameters

Name | Required/Optional | Data Type | Description
SourceDateTime | Required | Date | A date/time value expressed in the original time zone.
SourceTimeZone | Required | TimeZone | The original time zone of the date/time value that is to be converted.
DestinationTimeZone | Required | TimeZone | The target time zone to which the date/time value is to be converted.

Return Value

A Date value that represents the date and time expressed in the DestinationTimeZone.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


TimeZones.Item Method (Outlook)

 Copy code hover
[image]

TimeZones.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a TimeZone object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a TimeZones object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | An Integer representing a one-based index into the TimeZones collection.

Return Value

A TimeZone object that represents the specified object in the collection.

See also

Concepts

TimeZones Object

Other resources

TimeZones Object Members


ToOrFromRuleCondition Object (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a rule condition that the sender or the recipeints of the message, as specified by ToOrFromRuleCondition.ConditionType, is in the recipients list specified in ToOrFromRuleCondition.Recipients.

Version Information

Version Added: Outlook 2007

Remarks

ToOrFromRuleCondition is derived from the RuleCondition object. Each rule is associated with a RuleConditions object which has a SentTo property and a From. Each of these properties always returns a ToOrFromRuleCondition object. ToOrFromRuleCondition.ConditionType distinguishes between these rule conditions. If the rule has any of these rule conditions enabled, then ToOrFromRuleCondition.Enabled would be True.

For more information on specifying rule conditions, see Specify Rule Conditions.

See also

Concepts

Outlook Object Model Reference

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition Members (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a rule condition that the sender or the recipeints of the message, as specified by ToOrFromRuleCondition.ConditionType, is in the recipients list specified in ToOrFromRuleCondition.Recipients.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns a Boolean value that indicates whether the rule condition is enabled. Read/write
Parent | Returns the parent Object of the specified object. Read-only.
Recipients | Returns a Recipients collection that represents the recipient list for the evaluation of the rule condition. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ToOrFromRuleCondition Properties (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ConditionType | Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.
Enabled | Returns a Boolean value that indicates whether the rule condition is enabled. Read/write
Parent | Returns the parent Object of the specified object. Read-only.
Recipients | Returns a Recipients collection that represents the recipient list for the evaluation of the rule condition. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ToOrFromRuleCondition.Application Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a ToOrFromRuleCondition object.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.Class Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a ToOrFromRuleCondition object.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.ConditionType Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.ConditionType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a constant from the OlRuleConditionType enumeration that indicates the type of rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ConditionType

expression A variable that represents a ToOrFromRuleCondition object.

Remarks

ConditionType depends on the type of rule condition, as two types of rule conditions use the ToOrFromRuleCondition object: olConditionFrom and olConditionSentTo. olConditionFrom is supported only by rules for receiving messages, while olConditionSentTo is supported by rules for receiving messages as well as rules for sending messages. For more information, see Specify Rule Conditions.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.Enabled Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Enabled Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean value that indicates whether the rule condition is enabled. Read/write

Version Information

Version Added: Outlook 2007

Syntax

expression .Enabled

expression A variable that represents a ToOrFromRuleCondition object.

Remarks

After you enable a rule condition, you must also save the rule by using Rules.Save so that the rule condition and its enabled state will persist beyond the current session. A rule condition is only enabled after it have been saved successfully.

Returns an error if you attempt to enable a rule condition that is supported only on a rule of type olRuleSend for a rule of type olRuleReceive, or vice versa. For more information on suppport by rules for receiving messages or rules for sending messages, see Specify Rule Conditions.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.Parent Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a ToOrFromRuleCondition object.

Remarks

The parent object is the RuleCondition object.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.Recipients Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Recipients Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Recipients collection that represents the recipient list for the evaluation of the rule condition. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Recipients

expression A variable that represents a ToOrFromRuleCondition object.

Remarks

Multiple recipients are evaluated using the logical OR operation.

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


ToOrFromRuleCondition.Session Property (Outlook)

 Copy code hover
[image]

ToOrFromRuleCondition.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a ToOrFromRuleCondition object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ToOrFromRuleCondition Object

Other resources

ToOrFromRuleCondition Object Members


UserDefinedProperties Object (Outlook)

 Copy code hover
[image]

UserDefinedProperties Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a set of UserDefinedProperty objects representing the user-defined properties defined for a Folder object.

Version Information

Version Added: Outlook 2007

Remarks

The members of the UserDefinedProperties collection correspond to the fields under User-defined fields in folder that you get in the Show Fields dialog.

Use the UserDefinedProperties property to retrieve the UserDefinedProperties object from a Folder object.

Use the Add method to define and add a user-defined property to, and the Remove method to remove an existing user-defined property from, the UserDefinedProperties collection. Use the Item method to retrieve by name or index, or the Find method to locate and retrieve by name, a UserDefinedProperty object from the UserDefinedProperties collection. Use the Refresh method to reload the UserDefinedProperties collection from the store.

The UserDefinedProperties collection contains only the definitions of user-defined properties, which are applicable to all Outlook items contained by the folder. To retrieve or change user-defined property values for an Outlook item in that folder, use the UserProperties property of the Outlook item, such as a MailItem object, to retrieve the UserProperties collection for that item. You can then use the UserProperty object for the appropriate user-defined property to retrieve or change the value of that user-defined property for the Outlook item.

Example

The following Visual Basic for Applications (VBA) example uses the Add method to create and add several UserDefinedProperty objects to the Inbox default folder.

VBA Copy code Copy code
Sub AddStatusProperties()

 Dim objNamespace As NameSpace

 Dim objFolder As Folder

 Dim objProperty As UserDefinedProperty

 ' Obtain a Folder object reference to the

 ' Inbox default folder.

 Set objNamespace = Application.GetNamespace("MAPI")

 Set objFolder = objNamespace.GetDefaultFolder(olFolderInbox)

 ' Add five user-defined properties, used to identify and

 ' track customer issues.

 With objFolder.UserDefinedProperties

 Set objProperty = .Add("Issue?", olYesNo, olFormatYesNoIcon)

 Set objProperty = .Add("Issue Research Time", olDuration)

 Set objProperty = .Add("Issue Resolution Time", olDuration)

 Set objProperty = .Add("Customer Follow-Up", olYesNo, olFormatYesNoYesNo)

 Set objProperty = .Add("Issue Closed", olYesNo, olFormatYesNoYesNo)

 End With

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

UserDefinedProperties Object Members


UserDefinedProperties Members (Outlook)

 Copy code hover
[image]

UserDefinedProperties Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a set of UserDefinedProperty objects representing the user-defined properties defined for a Folder object.

Methods

Name | Description
Add | Creates a new UserDefinedProperty object and appends it to the collection.
Find | Locate a UserDefinedProperty contained in the collection.
Item | Returns an object from the collection.
Refresh | Refreshes the contents of the collection from the store, retrieving any changes performed in remote explorers.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value that indicates the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


UserDefinedProperties Properties (Outlook)

 Copy code hover
[image]

UserDefinedProperties Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value that indicates the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


UserDefinedProperties.Application Property (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a UserDefinedProperties object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Class Property (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Class Property (Outlook)
See also Send feedback

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a UserDefinedProperties object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Count Property (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value that indicates the count of objects in the specified collection. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Count

expression A variable that represents a UserDefinedProperties object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Parent Property (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a UserDefinedProperties object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Session Property (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a UserDefinedProperties object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties Methods (Outlook)

 Copy code hover
[image]

UserDefinedProperties Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new UserDefinedProperty object and appends it to the collection.
Find | Locate a UserDefinedProperty contained in the collection.
Item | Returns an object from the collection.
Refresh | Refreshes the contents of the collection from the store, retrieving any changes performed in remote explorers.
Remove | Removes an object from the collection.


UserDefinedProperties.Add Method (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new UserDefinedProperty object and appends it to the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(Name, Type, DisplayFormat, Formula)

expression A variable that represents a UserDefinedProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the new user-defined property.
Type | Required | OlUserPropertyType | The type of the new user-defined property.
DisplayFormat | Optional | Variant | The display format of the new user-defined property. This parameter can be set to a value from one of several different enumerations, determined by the OlUserPropertyType constant specified in the Type parameter. For more information on how Type and DisplayFormat interact, see DisplayFormat Property.
Formula | Optional | Variant | The formula used to calculate values for the new user-defined property. This parameter is ignored if the Type parameter is set to any value other than olCombination or olFormula.

Return Value

A UserDefinedProperty object that represents the new user-defined property.

Remarks

You can create a property of a type that is defined by the OlUserPropertyType enumeration, except for the following types: olEnumeration, olOutlookInternal, and olSmartFrom.

Example

The following Visual Basic for Applications (VBA) example uses the Add method to create and add several UserDefinedProperty objects to the Inbox default folder.

VBA Copy code Copy code
Sub AddStatusProperties()
 Dim objNamespace As NameSpace
 Dim objFolder As Folder
 Dim objProperty As UserDefinedProperty

 ' Obtain a Folder object reference to the
 ' Inbox default folder.
 Set objNamespace = Application.GetNamespace("MAPI")
 Set objFolder = objNamespace.GetDefaultFolder(olFolderInbox)

 ' Add five user-defined properties, used to identify and
 ' track customer issues.
 With objFolder.UserDefinedProperties
 Set objProperty = .Add("Issue?", olYesNo, olFormatYesNoIcon)
 Set objProperty = .Add("Issue Research Time", olDuration)
 Set objProperty = .Add("Issue Resolution Time", olDuration)
 Set objProperty = .Add("Customer Follow-Up", olYesNo, olFormatYesNoYesNo)
 Set objProperty = .Add("Issue Closed", olYesNo, olFormatYesNoYesNo)
 End With
End Sub

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Find Method (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Find Method (Outlook)
See also Send feedback

Published: July 16, 2012

Locate a UserDefinedProperty contained in the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Find(Name)

expression A variable that represents a UserDefinedProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The Name property value of the UserDefinedProperty object to find in the collection.

Return Value

A UserDefinedProperty object that represents the located object, if successful; otherwise, Null (Nothing in Visual Basic).

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Item Method (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a UserDefinedProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either a Long value that represents the 1-based index number of an object in the collection, or a String value that represents the Name property value of an object in the collection.

Return Value

A UserDefinedProperty object that represents the specified object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Refresh Method (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Refresh Method (Outlook)
See also Send feedback

Published: July 16, 2012

Refreshes the contents of the collection from the store, retrieving any changes performed in remote explorers.

Version Information

Version Added: Outlook 2007

Syntax

expression .Refresh

expression A variable that represents a UserDefinedProperties object.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperties.Remove Method (Outlook)

 Copy code hover
[image]

UserDefinedProperties.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents a UserDefinedProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

UserDefinedProperties Object

Other resources

UserDefinedProperties Object Members


UserDefinedProperty Object (Outlook)

 Copy code hover
[image]

UserDefinedProperty Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the definition of a user-defined property for a Folder object.

Version Information

Version Added: Outlook 2007

Remarks

Use UserDefinedProperties(index), where index is a name or index number, to return a single UserDefinedProperty object.

Use the Add method of the UserDefinedProperties collection for a Folder object to define a user-defined property for that folder.

Use the Type property to return the user-defined property type and the DisplayFormat property to return the display format for the user-defined property. If the Type property is set to olCombination or olFormula, use the Formula property to return the formula used to generate values for the user-defined property.

The UserDefinedProperty object represents only the definition of a user-defined property, which is applicable to all Outlook items contained by the folder. To retrieve or change user-defined property values for an Outlook item in that folder, use the UserProperties property of the Outlook item, such as a MailItem object, to retrieve the UserProperties collection for that item. You can then use the UserProperty object for the appropriate user-defined property to retrieve or change the value of that user-defined property for the Outlook item.

Example

The following Visual Basic for Applications (VBA) example displays the name of a specified Folder object, as well as the name and type of every UserDefinedProperty object contained in the UserDefinedProperties collection of the specified Folder object, to the Immediate window.

Copy code Copy code
Sub DisplayUserProperties(ByRef FolderToCheck As Folder)
 Dim objProperty As UserDefinedProperty

 ' Print the name of the specified Folder object
 ' reference to the Immediate window.
 Debug.Print "--- Folder: " & FolderToCheck.Name

 ' Check if there are any user-defined properties
 ' associated with the Folder object reference.
 If FolderToCheck.UserDefinedProperties.Count = 0 Then
 ' No user-defined properties are present.
 Debug.Print " No user-defined properties."
 Else
 ' Iterate through every user-defined property in
 ' the folder.
 For Each objProperty In FolderToCheck.UserDefinedProperties
 ' Retrieve the name of the user-defined property.
 strPropertyInfo = objProperty.Name
 ' Retrieve the type of the user-defined property.
 Select Case objProperty.Type
 Case OlUserPropertyType.olCombination
 strPropertyInfo = strPropertyInfo & " (Combination)"
 Case OlUserPropertyType.olCurrency
 strPropertyInfo = strPropertyInfo & " (Currency)"
 Case OlUserPropertyType.olDateTime
 strPropertyInfo = strPropertyInfo & " (Date/Time)"
 Case OlUserPropertyType.olDuration
 strPropertyInfo = strPropertyInfo & " (Duration)"
 Case OlUserPropertyType.olEnumeration
 strPropertyInfo = strPropertyInfo & " (Enumeration)"
 Case OlUserPropertyType.olFormula
 strPropertyInfo = strPropertyInfo & " (Formula)"
 Case OlUserPropertyType.olInteger
 strPropertyInfo = strPropertyInfo & " (Integer)"
 Case OlUserPropertyType.olKeywords
 strPropertyInfo = strPropertyInfo & " (Keywords)"
 Case OlUserPropertyType.olNumber
 strPropertyInfo = strPropertyInfo & " (Number)"
 Case OlUserPropertyType.olOutlookInternal
 strPropertyInfo = strPropertyInfo & " (Outlook Internal)"
 Case OlUserPropertyType.olPercent
 strPropertyInfo = strPropertyInfo & " (Percent)"
 Case OlUserPropertyType.olSmartFrom
 strPropertyInfo = strPropertyInfo & " (Smart From)"
 Case OlUserPropertyType.olText
 strPropertyInfo = strPropertyInfo & " (Text)"
 Case OlUserPropertyType.olYesNo
 strPropertyInfo = strPropertyInfo & " (Yes/No)"
 Case Else
 strPropertyInfo = strPropertyInfo & " (Unknown)"
 End Select

 ' Print the name and type of the user-defined property
 ' to the Immediate window.
 Debug.Print strPropertyInfo
 Next
 End If
End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

UserDefinedProperty Object Members


UserDefinedProperty Members (Outlook)

 Copy code hover
[image]

UserDefinedProperty Members (Outlook)
Send feedback

Published: July 16, 2012

Represents the definition of a user-defined property for a Folder object.

Methods

Name | Description
Delete | Deletes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayFormat | Returns a Long value that represents the display format for the UserDefinedProperty object. Read-only.
Formula | Returns a String value that represents the formula for the UserDefinedProperty object. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the UserDefinedProperty object. Read-only.


UserDefinedProperty Properties (Outlook)

 Copy code hover
[image]

UserDefinedProperty Properties (Outlook)
Send feedback

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
DisplayFormat | Returns a Long value that represents the display format for the UserDefinedProperty object. Read-only.
Formula | Returns a String value that represents the formula for the UserDefinedProperty object. Read-only.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the UserDefinedProperty object. Read-only.


UserDefinedProperty.Application Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Application

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Class Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Class

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.DisplayFormat Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.DisplayFormat Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value that represents the display format for the UserDefinedProperty object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .DisplayFormat

expression A variable that represents a UserDefinedProperty object.

Remarks

The value of this property is a constant from an enumeration, where the enumeration is dependent on the value of the Type property for the UserDefinedProperty object:

Type value | DisplayFormat enumeration
olCombination | No enumeration available. This property always returns 1 for olCombination.
olCurrency | OlFormatCurrency
olDateTime | OlFormatDateTime
olDuration | OlFormatDuration
olEnumeration | OlFormatEnumeration
olFormula | No enumeration available. This property always returns 1 for olFormula.
olInteger | OlFormatInteger
olKeywords | OlFormatKeywords
olNumber | OlFormatNumber
olOutlookInternal | No enumeration available. This property always returns 1 for olOutlookInternal.
olPercent | OlFormatPercent
olSmartFrom | OlFormatSmartFrom
olText | OlFormatText
olYesNo | OlFormatYesNo

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Formula Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Formula Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the formula for the UserDefinedProperty object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Formula

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Name Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the display name for the object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Name

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Parent Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Parent

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Session Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Session

expression A variable that represents a UserDefinedProperty object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty.Type Property (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlUserPropertyType constant indicating the type of the UserDefinedProperty object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .Type

expression A variable that represents a UserDefinedProperty object.

Example

The following Visual Basic for Applications (VBA) example displays the name of a specified Folder object, as well as the name and type of every UserDefinedProperty object contained in the UserDefinedProperties collection of the specified Folder object, to the Immediate window.

Copy code Copy code
Sub DisplayUserProperties(ByRef FolderToCheck As Folder)

 Dim objProperty As UserDefinedProperty

 ' Print the name of the specified Folder object

 ' reference to the Immediate window.

 Debug.Print "--- Folder: " & FolderToCheck.Name

 ' Check if there are any user-defined properties

 ' associated with the Folder object reference.

 If FolderToCheck.UserDefinedProperties.Count = 0 Then

 ' No user-defined properties are present.

 Debug.Print " No user-defined properties."

 Else

 ' Iterate through every user-defined property in

 ' the folder.

 For Each objProperty In FolderToCheck.UserDefinedProperties

 ' Retrieve the name of the user-defined property.

 strPropertyInfo = objProperty.Name

 ' Retrieve the type of the user-defined property.

 Select Case objProperty.Type

 Case OlUserPropertyType.olCombination

 strPropertyInfo = strPropertyInfo & " (Combination)"

 Case OlUserPropertyType.olCurrency

 strPropertyInfo = strPropertyInfo & " (Currency)"

 Case OlUserPropertyType.olDateTime

 strPropertyInfo = strPropertyInfo & " (Date/Time)"

 Case OlUserPropertyType.olDuration

 strPropertyInfo = strPropertyInfo & " (Duration)"

 Case OlUserPropertyType.olEnumeration

 strPropertyInfo = strPropertyInfo & " (Enumeration)"

 Case OlUserPropertyType.olFormula

 strPropertyInfo = strPropertyInfo & " (Formula)"

 Case OlUserPropertyType.olInteger

 strPropertyInfo = strPropertyInfo & " (Integer)"

 Case OlUserPropertyType.olKeywords

 strPropertyInfo = strPropertyInfo & " (Keywords)"

 Case OlUserPropertyType.olNumber

 strPropertyInfo = strPropertyInfo & " (Number)"

 Case OlUserPropertyType.olOutlookInternal

 strPropertyInfo = strPropertyInfo & " (Outlook Internal)"

 Case OlUserPropertyType.olPercent

 strPropertyInfo = strPropertyInfo & " (Percent)"

 Case OlUserPropertyType.olSmartFrom

 strPropertyInfo = strPropertyInfo & " (Smart From)"

 Case OlUserPropertyType.olText

 strPropertyInfo = strPropertyInfo & " (Text)"

 Case OlUserPropertyType.olYesNo

 strPropertyInfo = strPropertyInfo & " (Yes/No)"

 Case Else

 strPropertyInfo = strPropertyInfo & " (Unknown)"

 End Select

 ' Print the name and type of the user-defined property

 ' to the Immediate window.

 Debug.Print strPropertyInfo

 Next

 End If

End Sub

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserDefinedProperty Methods (Outlook)

 Copy code hover
[image]

UserDefinedProperty Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.


UserDefinedProperty.Delete Method (Outlook)

 Copy code hover
[image]

UserDefinedProperty.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Delete

expression A variable that represents a UserDefinedProperty object.

See also

Concepts

UserDefinedProperty Object

Other resources

UserDefinedProperty Object Members


UserProperties Object (Outlook)

 Copy code hover
[image]

UserProperties Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains UserProperty objects that represent the custom properties of an Outlook item.

Remarks

Use the UserProperties property to return the UserProperties object for an Outlook item. This applies to all Outlook items except for the NoteItem.

Use the Add method to create a new UserProperty for an item and add it to the UserProperties object. The Add method allows you to specify a name and type for the new property. When you create a new property, it can also be added as a custom field to the folder that contains the item (using the same name as the property) by setting the AddToFolderFields parameter to True when calling the Add method. That field can then be used as a column in folder views.

Use UserProperties(index), where index is a name or one-based index number, to return a single UserProperty object.

You can use the UserDefinedProperties property of the Folder object to retrieve and examine the definitions of custom item-level properties that a folder can display in a view.

To get or set multiple custom properties, use the PropertyAccessor object instead of the UserProperties object for better performance.

Example

The following example adds a custom text property named MyPropName to myItem.

VBA Copy code Copy code
Set myProp = myItem.UserProperties.Add("MyPropName", olText)

See also

Concepts

Outlook Object Model Reference

Other resources

UserProperties Object Members


UserProperties Members (Outlook)

 Copy code hover
[image]

UserProperties Members (Outlook)
Send feedback

Contains UserProperty objects that represent the custom properties of an Outlook item.

Methods

Name | Description
Add | Creates a new user property in the UserProperties collection.
Find | Locates and returns a UserProperty object for the requested property name, if it exists.
Item | Returns a UserProperty object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


UserProperties Properties (Outlook)

 Copy code hover
[image]

UserProperties Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


UserProperties.Application Property (Outlook)

 Copy code hover
[image]

UserProperties.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a UserProperties object.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Class Property (Outlook)

 Copy code hover
[image]

UserProperties.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a UserProperties object.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Count Property (Outlook)

 Copy code hover
[image]

UserProperties.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a UserProperties object.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Parent Property (Outlook)

 Copy code hover
[image]

UserProperties.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a UserProperties object.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Session Property (Outlook)

 Copy code hover
[image]

UserProperties.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a UserProperties object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties Methods (Outlook)

 Copy code hover
[image]

UserProperties Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new user property in the UserProperties collection.
Find | Locates and returns a UserProperty object for the requested property name, if it exists.
Item | Returns a UserProperty object from the collection.
Remove | Removes an object from the collection.


UserProperties.Add Method (Outlook)

 Copy code hover
[image]

UserProperties.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new user property in the UserProperties collection.

Syntax

expression .Add(Name, Type, AddToFolderFields, DisplayFormat)

expression A variable that represents an UserProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the property. The maximum length is 64 characters. The characters, '[', ']', '_' and '#', are not permitted in the name.
Type | Required | OlUserPropertyType | The type of the new property.
AddToFolderFields | Optional | Boolean | True if the property will be added as a custom field to the folder that the item is in. This field can be displayed in the folder's view. False if the property will be added as a custom field to the item but not to the folder. The default value is True.
DisplayFormat | Optional | Long | Specifies how the property will be displayed in the Outlook user interface. This parameter can be set to a value from one of several different enumerations, determined by the OlUserPropertyType constant specified in the Type parameter. For more information on how Type and DisplayFormat interact, see DisplayFormat Property.

Return Value

A UserProperty object that represents the new property.

Remarks

You can define custom properties by calling either the UserProperties.Add method for an Outlook item or folder, or the UserDefinedProperties.Add method for a folder.

You can create a property of a type that is defined by the OlUserPropertyType enumeration, except for the following types: olEnumeration, olOutlookInternal, and olSmartFrom.

To set for the first time a property created by the UserProperties.Add method, use the UserProperty.Value property instead of the SetProperties and SetProperty methods of the PropertyAccessor object.

If you want to view a custom property on an item, you must use the UserProperties.Add method to create that property. Custom properties created by the PropertyAccessor are not supported in a custom view.

You cannot add custom properties to Office document items such as Word, Excel, or PowerPoint files. You will receive an error when you try to programmatically add a user-defined field to a DocumentItem object.

Example

This VBA example creates a new ContactItem object and adds "LastDateSpokenWith" as a custom property.

VBA Copy code Copy code
Sub AddUserProperty()
 Dim myItem As Outlook.ContactItem
 Dim myUserProperty As Outlook.UserProperty

 Set myItem = Application.CreateItem(olContactItem)
 Set myUserProperty = myItem.UserProperties _
 .Add("LastDateSpokenWith", olDateTime)
 myItem.Display
End Sub

This VBA example creates a new ContactItem object and adds "Details" as a user property. The value is set by changing the Value property of the UserProperty object.

VBA Copy code Copy code
Sub AddUserProperty()
 Dim myItem As Outlook.ContactItem
 Dim myUserProperty As Outlook.UserProperty

 Set myItem = Application.CreateItem(olContactItem)
 Set myUserProperty = myItem.UserProperties _
 .Add("Details", olText)
 myUserProperty.Value = "Neighbor"
 myItem.Display
End Sub

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Find Method (Outlook)

 Copy code hover
[image]

UserProperties.Find Method (Outlook)
See also Send feedback

Published: July 16, 2012

Locates and returns a UserProperty object for the requested property name, if it exists.

Syntax

expression .Find(Name, Custom)

expression A variable that represents an UserProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | The name of the requested property.
Custom | Optional | Variant | True if custom properties on the item should be searched, False if built-in properties should be searched.

Return Value

If you use UserProperties.Find to look for a custom property and the call succeeds, it will return a UserProperty object. If it fails, it will return Null (Nothing in Visual Basic). If you use UserProperties.Find to look for a built-in property, specify False for the Custom parameter. If the call succeeds, it will return the property as a UserProperty object. If the call fails, it will return Null (Nothing in Visual Basic). If you specify True for Custom, the call will not find the built-in property and will return Null (Nothing in Visual Basic).

Remarks

If Custom parameter is True, only custom user properties will be searched. The default value is True. To find a non custom property such as Subject, specify Custom parameter as False, otherwise will return Nothing.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Item Method (Outlook)

 Copy code hover
[image]

UserProperties.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a UserProperty object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents an UserProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the one-based index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A UserProperty object that represents the specified object.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperties.Remove Method (Outlook)

 Copy code hover
[image]

UserProperties.Remove Method (Outlook)
See also Send feedback

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents an UserProperties object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long | The 1-based index value of the object within the collection.

See also

Concepts

UserProperties Object

Other resources

UserProperties Object Members


UserProperty Object (Outlook)

 Copy code hover
[image]

UserProperty Object (Outlook)
See also Send feedback

Represents a custom property of an Outlook item.

Remarks

Use UserProperties(index), where index is a name or index number, to return a single UserProperty object.

Use the Add method to create a new UserProperty for an item and add it to the UserProperties object. The Add method allows you to specify a name and type for the new property.

Note Note

When you create a custom property, a field is added in the folder that contains the item (using the same name as the property). That field can be used as a column in folder views.

Example

The following example adds a custom text property named MyPropName.

Copy code Copy code
Set myProp = myItem.UserProperties.Add("MyPropName", olText)

See also

Concepts

Outlook Object Model Reference

Other resources

UserProperty Object Members


UserProperty Members (Outlook)

 Copy code hover
[image]

UserProperty Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a custom property of an Outlook item.

Methods

Name | Description
Delete | Deletes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Formula | Returns or sets a String representing the formula for the user property. Read/write.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.
ValidationFormula | Returns or sets a String indicating the validation formula for the user property. Read/write.
ValidationText | Returns or sets a String specifying the validation text for the specified user property. Read/write.
Value | Returns or sets a Variant indicating the value for the specified custom property. Read/write.


UserProperty Properties (Outlook)

 Copy code hover
[image]

UserProperty Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Formula | Returns or sets a String representing the formula for the user property. Read/write.
Name | Returns a String value that represents the display name for the object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Type | Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.
ValidationFormula | Returns or sets a String indicating the validation formula for the user property. Read/write.
ValidationText | Returns or sets a String specifying the validation text for the specified user property. Read/write.
Value | Returns or sets a Variant indicating the value for the specified custom property. Read/write.


UserProperty.Application Property (Outlook)

 Copy code hover
[image]

UserProperty.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Class Property (Outlook)

 Copy code hover
[image]

UserProperty.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Formula Property (Outlook)

 Copy code hover
[image]

UserProperty.Formula Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String representing the formula for the user property. Read/write.

Syntax

expression .Formula

expression A variable that represents a UserProperty object.

Example

The following Visual Basic for Applications (VBA) example shows how to use the Formula property.

VBA Copy code Copy code
Sub TestFormula()

 Dim tki As Outlook.TaskItem

 Dim uprs As Outlook.UserProperties

 Dim upr As Outlook.UserProperty

 Set tki = Application.CreateItem(olTaskItem)

 tki.Subject = "Work hours - Test Formula"

 ' TotalWork and ActualWork are in units of minutes

 tki.TotalWork = 4 * 60

 tki.ActualWork = 3 * 60

 Set uprs = tki.UserProperties

 Set upr = uprs.Add("Total&ActualWork", olFormula)

 upr.Formula = "[Total Work] + [Actual Work]"

 tki.Save

 tki.Display

 MsgBox "The Work Hours are: " & upr.Value / 60

End Sub

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Name Property (Outlook)

 Copy code hover
[image]

UserProperty.Name Property (Outlook)
See also Send feedback

Returns a String value that represents the display name for the object. Read-only.

Syntax

expression .Name

expression A variable that represents a UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Parent Property (Outlook)

 Copy code hover
[image]

UserProperty.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Session Property (Outlook)

 Copy code hover
[image]

UserProperty.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a UserProperty object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Type Property (Outlook)

 Copy code hover
[image]

UserProperty.Type Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlUserPropertyType constant indicating the type of the specified object. Read-only.

Syntax

expression .Type

expression A variable that represents a UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.ValidationFormula Property (Outlook)

 Copy code hover
[image]

UserProperty.ValidationFormula Property (Outlook)
See also Send feedback

Returns or sets a String indicating the validation formula for the user property. Read/write.

Syntax

expression .ValidationFormula

expression A variable that represents a UserProperty object.

Remarks

The validation formula is used by Outlook to validate the Value property when an item is saved.

Example

The following Visual Basic for Applications (VBA) example demonstrates the use of ValidationText and ValidationFormula properties.

VBA Copy code Copy code
Sub TestValidation()

 Dim tki As Outlook.TaskItem

 Dim uprs As Outlook.UserProperties

 Dim upr As Outlook.UserProperty

 Set tki = Application.CreateItem(olTaskItem)

 tki.Subject = "Work hours"

 tki.TotalWork = 3000

 Set uprs = tki.UserProperties

 Set upr = uprs.Add("TotalWork", olFormula)

 upr.Formula = "[Total Work]"

 upr.ValidationFormula = ">= 2400"

 upr.ValidationText = """The WorkHours (Total Work) should be equal or greater than 5 days """

 tki.Save

 tki.Display

 MsgBox "The Work Hours are: " & upr.Value

End Sub

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.ValidationText Property (Outlook)

 Copy code hover
[image]

UserProperty.ValidationText Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String specifying the validation text for the specified user property. Read/write.

Syntax

expression .ValidationText

expression A variable that represents a UserProperty object.

Remarks

The validation text is the error message that a user receives when the Value does not meet the criteria specified in ValidationFormula.

Example

The following Visual Basic for Applications (VBA) example demonstrates the use of ValidationText and ValidationFormula properties.

VBA Copy code Copy code
Sub TestValidation()

 Dim tki As Outlook.TaskItem

 Dim uprs As Outlook.UserProperties

 Dim upr As Outlook.UserProperty

 Set tki = Application.CreateItem(olTaskItem)

 tki.Subject = "Work hours"

 ' TotalWork is stored in units of minutes

 tki.TotalWork = 3000

 Set uprs = tki.UserProperties

 Set upr = uprs.Add("TotalWork", olFormula)

 upr.Formula = "[Total Work]"

 upr.ValidationFormula = ">= 2400"

 upr.ValidationText = """The Work Hours (TotalWork) should be equal or greater than 5 days """

 tki.Save

 tki.Display

 MsgBox "The Work Hours are: " & upr.Value / 60

End Sub

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty.Value Property (Outlook)

 Copy code hover
[image]

UserProperty.Value Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Variant indicating the value for the specified custom property. Read/write.

Syntax

expression .Value

expression A variable that represents a UserProperty object.

Remarks

To set for the first time a property created by the UserProperties.Add method, use the UserProperty.Value property instead of the SetProperties or SetProperty method of the PropertyAccessor object.

For more information on accessing properties in Outlook, see Properties Overview.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


UserProperty Methods (Outlook)

 Copy code hover
[image]

UserProperty Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Delete | Deletes an object from the collection.


UserProperty.Delete Method (Outlook)

 Copy code hover
[image]

UserProperty.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents an UserProperty object.

See also

Concepts

UserProperty Object

Other resources

UserProperty Object Members


View Object (Outlook)

 Copy code hover
[image]

View Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a customizable view used to sort, group, and view data.

Remarks

The View object allows you to create customizable views that allow you to better sort, group and ultimately view data of all different types. There are a variety of different view types that provide the flexibility needed to create and maintain your important data.

  • The table view type (olTableView) allows you to view data in a simple field-based table.

  • The Calendar view type (olCalendarView) allows you to view data in a calendar format.

  • The card view type (olCardView) allows you to view data in a series of cards. Each card displays the information contained by the item and can be sorted.

  • The icon view type (olIconView) allows you to view data as icons, similar to a Windows folder or explorer.

  • The timeline view type (olTimelineView) allows you to view data as it is received in a customizable linear time line.

Views are defined and customized using the View object's XML property. The XML property allows you to create and set a customized XML schema that defines the various features of a view.

Use Views(index), where index is the name of the View object or its ordinal value, to return a single View object.

Use the Add method of the Views collection to create a new view.

Always use Save to save a view after you change any property of the view.

Example

The following example returns a view called Table View and stores it in a variable of type View called objView. Before running this example, make sure a view by the name 'Table View' exists.

VBA Copy code Copy code
Sub GetView()

 'Creates a new view

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 'Return a view called Table View

 Set objView = objViews.Item("Table View")

End Sub

The following example creates a new view of type olTableView called New Table.

VBA Copy code Copy code
Sub CreateView()

 'Creates a new view

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objNewView As View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 Set objNewView = objViews.Add(Name:="New Table", _

 ViewType:=olTableView, SaveOption:=olViewSaveOptionThisFolderEveryone)

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

View Object Members


View Members (Outlook)

 Copy code hover
[image]

View Members (Outlook)
Send feedback

Represents a customizable view used to sort, group, and view data.

Methods

Name | Description
Apply | Applies the view to the Microsoft Outlook user interface.
Copy | Creates a new instance of a View object.
Delete | Deletes an object from the collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean that specifies whether or not the view is a built-in Outlook view. Read-only
ViewType | Returns an OlViewType constant representing the view type of a View object. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the current view. Read/write.


View Properties (Outlook)

 Copy code hover
[image]

View Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Filter | Returns or sets a String value that represents the filter for a view. Read/write.
Language | Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.
LockUserChanges | Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
SaveOption | Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Standard | Returns a Boolean that specifies whether or not the view is a built-in Outlook view. Read-only
ViewType | Returns an OlViewType constant representing the view type of a View object. Read-only.
XML | Returns or sets a String value that specifies the XML definition of the current view. Read/write.


View.Application Property (Outlook)

 Copy code hover
[image]

View.Application Property (Outlook)
See also Send feedback

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.Class Property (Outlook)

 Copy code hover
[image]

View.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.Filter Property (Outlook)

 Copy code hover
[image]

View.Filter Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the filter for a view. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Filter

expression A variable that represents a View object.

Remarks

The value of this property is a string, in DAV Searching and Locating (DASL) syntax, that represents the current filter for the view. For more information about using DASL syntax to filter items in a view, see Filtering Items.

Example

The following Visual Basic for Applications (VBA) example obtains a View object by using the CurrentView property of the Explorer object, then sets the Filter property of the View object to display only those Outlook items that were received last week.

VBA Copy code Copy code
Private Sub FilterViewToLastWeek()

 Dim objView As View

 ' Obtain a View object reference to the current view.

 Set objView = Application.ActiveExplorer.CurrentView

 ' Set a DASL filter string, using a DASL macro, to show

 ' only those items that were received last week.

 objView.Filter = "%lastweek(""urn:schemas:httpmail:datereceived"")%"

 ' Save and apply the view.

 objView.Save

 objView.Apply

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Language Property (Outlook)

 Copy code hover
[image]

View.Language Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the language setting for the object that defines the language used in the menu. Read/write.

Syntax

expression .Language

expression A variable that represents a View object.

Remarks

The Language property uses a String to represent an ISO language tag. For example, the string "EN-US" represents the ISO code for "United States - English."

If a valid language code is specified, the object will only be available in the View menu for the specified language type. If no value is specified, the object item is available for all language types. The default value for this property is an empty string.

See also

Concepts

View Object

Other resources

View Object Members


View.LockUserChanges Property (Outlook)

 Copy code hover
[image]

View.LockUserChanges Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates whether a user can modify the settings of the current view. Read/write.

Syntax

expression .LockUserChanges

expression A variable that represents a View object.

Remarks

If True, the user can modify the settings of the current view. However, changes made to the interface will not be saved. If False (the default), any changes will be saved.

Example

The following example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View interface will be locked. In this example the procedure is always called with the Boolean value set to True.

VBA Copy code Copy code
Sub LocksPublicViews()
 'Locks the interface of all views that are available to
 'all users of this folder.
 Dim objName As Outlook.NameSpace
 Dim objViews As Outlook.Views
 Dim objView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")
 Set objViews = objName.GetDefaultFolder(olFolderNotes).Views
 For Each objView In objViews
 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then
 Call LockView(objView, True)
 End If
 Next objView
End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)
 'Locks the user interface of the view.
 'Accepts and returns a View object and user response.
 With objView
 If blnAns = True Then
 'if true lock UI
 .LockUserChanges = True
 .Save
 Else
 'if false don't lock UI
 .LockUserChanges = False
 End If
 End With
End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Name Property (Outlook)

 Copy code hover
[image]

View.Name Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.Parent Property (Outlook)

 Copy code hover
[image]

View.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.SaveOption Property (Outlook)

 Copy code hover
[image]

View.SaveOption Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewSaveOption constant that specifies the folders in which the specified view is available and the read permissions attached to the view. Read-only.

Syntax

expression .SaveOption

expression A variable that represents a View object.

Remarks

The SaveOption property is set when the View object is created by using the Views.Add method.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the names of all views that can be accessed by all users in the Notes folder.

The following example locks the user interface for all views that are available to all users. The subroutine LockView accepts the View object and a Boolean value that indicates if the View interface will be locked. In this example the procedure is always called with the Boolean value set to True.

VBA Copy code Copy code
Sub LocksPublicViews()

 'Locks the interface of all views that are available to

 'all users of this folder.

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderNotes).Views

 For Each objView In objViews

 If objView.SaveOption = olViewSaveOptionThisFolderEveryone Then

 Call LockView(objView, True)

 End If

 Next objView

End Sub

Sub LockView(ByRef objView As View, ByVal blnAns As Boolean)

 'Locks the user interface of the view.

 'Accepts and returns a View object and user response.

 With objView

 If blnAns = True Then

 'if true lock UI

 .LockUserChanges = True

 .Save

 Else

 'if false don't lock UI

 .LockUserChanges = False

 End If

 End With

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Session Property (Outlook)

 Copy code hover
[image]

View.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a View object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

View Object

Other resources

View Object Members


View.Standard Property (Outlook)

 Copy code hover
[image]

View.Standard Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Boolean that specifies whether or not the view is a built-in Outlook view. Read-only

Syntax

expression .Standard

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.ViewType Property (Outlook)

 Copy code hover
[image]

View.ViewType Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlViewType constant representing the view type of a View object. Read-only.

Syntax

expression .ViewType

expression An expression that returns a View object.

Remarks

This property does not have any effect on the icons displayed in the Shortcuts pane. Large icons have been removed and if this property is set to olLargeIcon, it will not have any effect.

Example

The following Visual Basic for Applicatons (VBA) example displays the name and type of all views in the user's Inbox.

VBA Copy code Copy code
Sub DisplayViewMode()

 'Displays the names and view modes for all views

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Dim strTypes As String

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 'Collect names and view types for all views

 For Each objView In objViews

 strTypes = strTypes & objView.Name & vbTab & vbTab & objView.ViewType & vbCr

 Next objView

 'Display message box

 MsgBox "Current Inbox Views and Viewtypes:" & vbCr & _

 vbCr & strTypes

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.XML Property (Outlook)

 Copy code hover
[image]

View.XML Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a String value that specifies the XML definition of the current view. Read/write.

Syntax

expression .XML

expression A variable that represents a View object.

Remarks

The XML definition describes the view type by using a series of tags and keywords corresponding to various properties of the view itself. When the view is created, the XML definition is parsed to render the settings for the new view.

To determine how the XML should be structured when creating views, you can create a view by using the Outlook user interface and then you can retrieve the XML property for that view.

To programmatically add a custom field to a view, use the Add method of the ViewFields object. This is the recommended way to dynamically change the view over setting the XML property of the View object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates an instance of the Views collection and displays the XML definition of a view called "Table View". If the view does not exist, it creates one.

VBA Copy code Copy code
Sub DisplayViewDef()

 'Displays the XML definition of a View object

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 'Return a view called Table View if it already exists, else create one

 Set objView = objViews.Item("Table View")

 If objView Is Nothing Then

 Set objView = objViews.Add("Table View", olTableView, olViewSaveOptionAllFoldersOfType)

 End If

 MsgBox objView.XML

End Sub

The following are the modified properties that are visible in the following XML source code. In addition to the property definitions, the XML source also defines any objects that make up the view. The following example displays the XML definition of columns that appear in the above view.

XML Copy code Copy code
<heading>Flag Status</heading>
     <prop>http://schemas.microsoft.com/mapi/proptag/0x10900003</prop>
     <type>i4</type>
     <bitmap>1</bitmap>
     <style>padding-left:3px;text-align:center;padding-left:3px</style>
 </column>
 <column>
     <format>boolicon</format>
     <heading>Attachment</heading>
     <prop>urn:schemas:httpmail:hasattachment</prop>
     <type>boolean</type>
     <bitmap>1</bitmap>
     <style>padding-left:3px;text-align:center;padding-left:3px</style>
     <displayformat>3</displayformat>
 </column>

See also

Concepts

View Object

Other resources

View Object Members


View Methods (Outlook)

 Copy code hover
[image]

View Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Apply | Applies the view to the Microsoft Outlook user interface.
Copy | Creates a new instance of a View object.
Delete | Deletes an object from the collection.
GoToDate | Changes the date used by the current view to display information.
Reset | Resets a built-in Microsoft Outlook view to its original settings.
Save | Saves the view, or saves the changes to a view.


View.Apply Method (Outlook)

 Copy code hover
[image]

View.Apply Method (Outlook)
See also Send feedback

Published: July 16, 2012

Applies the view to the Microsoft Outlook user interface.

Syntax

expression .Apply

expression A variable that represents a View object.

Remarks

To properly reset the current view, you must do a View.Reset and then a View.Apply. The code sample below illustrates the order of the calls:

VBA Copy code Copy code
Sub ResetView()

 Dim v as Outlook.View

 ' Save a reference to the current view object

 Set v = Application.ActiveExplorer.CurrentView

 ' Reset and then apply the current view

 v.Reset

 v.Apply

End Sub

Example

The following Visual Basic for Applications (VBA) example creates a new view called New Table and applies it.

VBA Copy code Copy code
Sub CreateView()

 'Creates a new view

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objNewView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 Set objNewView = objViews.Add(Name:="New Table", _

 ViewType:=olTableView)

 objNewView.Save

 objNewView.Apply

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Copy Method (Outlook)

 Copy code hover
[image]

View.Copy Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new instance of a View object.

Syntax

expression .Copy(Name, SaveOption)

expression A variable that represents a View object.

Parameters

Name | Required/Optional | Data Type | Description
Name | Required | String | Represents the name of the new View object.
SaveOption | Optional | OlViewSaveOption | The save option that defines the permissions of the View object.

Example

The following Microsoft Visual Basic for Applications (VBA) example creates a copy of a view called "New Table View" and saves it in the current folder. To run this example, you need to first create a view called 'New Table View' programmatically or by using the Outlook user interface.

VBA Copy code Copy code
Sub CopyView()

 'Copies a view

 Dim objViews As Outlook.Views

 Dim objNewView As Outlook.View

 Set objViews = _

 Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Views

 'Create copy of View object

 Set objNewView = objViews("New Table View").Copy(Name:="Table View Copy", _

 SaveOption:=olViewSaveOptionThisFolderEveryone)

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Delete Method (Outlook)

 Copy code hover
[image]

View.Delete Method (Outlook)
See also Send feedback

Published: July 16, 2012

Deletes an object from the collection.

Syntax

expression .Delete

expression A variable that represents a View object.

See also

Concepts

View Object

Other resources

View Object Members


View.GoToDate Method (Outlook)

 Copy code hover
[image]

View.GoToDate Method (Outlook)
See also Send feedback

Published: July 16, 2012

Changes the date used by the current view to display information.

Version Information

Version Added: Outlook 2007

Syntax

expression .GoToDate(Date)

expression A variable that represents a View object.

Parameters

Name | Required/Optional | Data Type | Description
Date | Required | Date | The date to which the view should be changed.

Remarks

To specify a date to go to in a current view, such as a CalendarView object, you should first obtain a View object for the current view by using Explorer.CurrentView instead of Folder.CurrentView. The following code sample demonstrates how to perform this action.

VBA Copy code Copy code
Sub TestGoToDate()

 Dim oCV As Outlook.CalendarView

 Dim oExpl As Outlook.Explorer

 Dim datGoTo As Date

 datGoTo = "11/7/2005"

 ' Display the contents of the Calendar default folder.

 Set oExpl = Application.Explorers.Add( _

 Application.Session.GetDefaultFolder(olFolderCalendar), olFolderDisplayFolderOnly)

 oExpl.Display

 ' Retrieve the current view by calling the

 ' CurrentView property of the Explorer object.

 Set oCV = oExpl.CurrentView

 ' Set the CalendarViewMode property of the

 ' current view to display items by day.

 oCV.CalendarViewMode = olCalendarViewDay

 ' Call the GoToDate method to set the date

 ' for which information is displayed in the view.

 oCV.GoToDate datGoTo

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Reset Method (Outlook)

 Copy code hover
[image]

View.Reset Method (Outlook)
See also Send feedback

Published: July 16, 2012

Resets a built-in Microsoft Outlook view to its original settings.

Syntax

expression .Reset

expression A variable that represents a View object.

Remarks

This method works only on built-in Outlook views.

To properly reset the current view, you must do a View.Reset and then a View.Apply. The code sample below illustrates the order of the calls:

VBA Copy code Copy code
Sub ResetView()

 Dim v as Outlook.View

 ' Save a reference to the current view object

 Set v = Application.ActiveExplorer.CurrentView

 ' Reset and then apply the current view

 v.Reset

 v.Apply

End Sub

Example

The following Microsoft Visual Basic for Applications (VBA) example resets all built-in views in the user's Inbox to their original settings. The Standard property is returned to determine if the view is a built-in Outlook view.

VBA Copy code Copy code
Sub ResetViews()

 'Resets all standard views in the user's Inbox

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 For Each objView In objViews

 If objView.Standard = True Then

 objView.Reset

 End If

 Next objView

End Sub

See also

Concepts

View Object

Other resources

View Object Members


View.Save Method (Outlook)

 Copy code hover
[image]

View.Save Method (Outlook)
See also Send feedback

Published: July 16, 2012

Saves the view, or saves the changes to a view.

Syntax

expression .Save

expression A variable that represents a View object.

Remarks

Always use Save to save a view after you change any property of the view.

Example

The following VBA example creates a new view called New Table and applies it.

VBA Copy code Copy code
Sub CreateView()

 'Creates a new view

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objNewView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 Set objNewView = objViews.Add(Name:="New Table", _

 ViewType:=olTableView)

 objNewView.Save

 objNewView.Apply

End Sub

See also

Concepts

View Object

Other resources

View Object Members


ViewField Object (Outlook)

 Copy code hover
[image]

ViewField Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents a view field, used to display information in a view.

Version Information

Version Added: Outlook 2007

Remarks

Use the Add method of the ViewFields collection to add an Outlook item property to the following objects derived from the View object:

  • CardView

  • TableView

Use the ColumnFormat property to access the ColumnFormat object representing the display properties associated with the view field. Use the ViewXMLSchemaName property to obtain the name of the view field as referenced in the XML definition of the view.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ViewField Object Members


ViewField Members (Outlook)

 Copy code hover
[image]

ViewField Members (Outlook)
Send feedback

Published: July 16, 2012

Represents a view field, used to display information in a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ColumnFormat | Returns a ColumnFormat object that represents the formatting information for the ViewField object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ViewXMLSchemaName | Returns a String value that represents the XML schema name for the property referenced by the ViewField object. Read-only.


ViewField Properties (Outlook)

 Copy code hover
[image]

ViewField Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
ColumnFormat | Returns a ColumnFormat object that represents the formatting information for the ViewField object. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
ViewXMLSchemaName | Returns a String value that represents the XML schema name for the property referenced by the ViewField object. Read-only.


ViewField.Application Property (Outlook)

 Copy code hover
[image]

ViewField.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ViewField object.

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewField.Class Property (Outlook)

 Copy code hover
[image]

ViewField.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ViewField object.

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewField.ColumnFormat Property (Outlook)

 Copy code hover
[image]

ViewField.ColumnFormat Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ColumnFormat object that represents the formatting information for the ViewField object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ColumnFormat

expression A variable that represents a ViewField object.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewField.Parent Property (Outlook)

 Copy code hover
[image]

ViewField.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ViewField object.

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewField.Session Property (Outlook)

 Copy code hover
[image]

ViewField.Session Property (Outlook)
See also Send feedback

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ViewField object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewField.ViewXMLSchemaName Property (Outlook)

 Copy code hover
[image]

ViewField.ViewXMLSchemaName Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a String value that represents the XML schema name for the property referenced by the ViewField object. Read-only.

Version Information

Version Added: Outlook 2007

Syntax

expression .ViewXMLSchemaName

expression A variable that represents a ViewField object.

Remarks

The value of this property contains the name of the property as it is included within the XML definition of the view containing the ViewField object. This value may not match the name used to refer to the property when the ViewField object was defined.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

VBA Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

ViewField Object

Other resources

ViewField Object Members


ViewFields Object (Outlook)

 Copy code hover
[image]

ViewFields Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the collection of ViewField objects in a view.

Version Information

Version Added: Outlook 2007

Remarks

The ViewFields collection represents the Outlook item properties available for display in the view. Use the Add method of the ViewFields collection to add a view field for the following objects derived from the View object:

  • CardView

  • TableView

In a table view, the order of ViewField objects in the ViewFields collection is not the same as the order that field columns are displayed in the table view. A workaround to obtain the column order is to parse the string returned by the View.XML property.

Example

The following Visual Basic for Applications (VBA) example iterates through the ViewFields collection of the current TableView object, displaying the label and XML schema names of each ViewField object in the collection.

VBA Copy code Copy code
Private Sub DisplayTableViewFields()

 Dim objTableView As TableView

 Dim objViewField As ViewField

 Dim strOutput As String

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTableView Then

 ' Obtain a TableView object reference for the

 ' current table view.

 Set objTableView = _

 Application.ActiveExplorer.CurrentView

 ' Iterate through the ViewFields collection for

 ' the table view, obtaining the label and the

 ' XML schema name for each field included in

 ' the view.

 For Each objViewField In objTableView.ViewFields

 With objViewField

 strOutput = strOutput & .ColumnFormat.Label & _

 " (" & .ViewXMLSchemaName & ")" & vbCrLf

 End With

 Next

 ' Display a dialog box containing the concatenated

 ' view field information.

 MsgBox strOutput

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ViewFields Object Members


ViewFields Members (Outlook)

 Copy code hover
[image]

ViewFields Members (Outlook)
Send feedback

Represents the collection of ViewField objects in a view.

Methods

Name | Description
Add | Adds the specified field to the end of the ViewFields collection for the view.
Insert | Creates a new ViewField object and inserts it at the specified index within the ViewFields collection.
Item | Returns a ViewField object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of ViewField objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ViewFields Properties (Outlook)

 Copy code hover
[image]

ViewFields Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long value indicating the count of ViewField objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


ViewFields.Application Property (Outlook)

 Copy code hover
[image]

ViewFields.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ViewFields object.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Class Property (Outlook)

 Copy code hover
[image]

ViewFields.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ViewFields object.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Count Property (Outlook)

 Copy code hover
[image]

ViewFields.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long value indicating the count of ViewField objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a ViewFields object.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Parent Property (Outlook)

 Copy code hover
[image]

ViewFields.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ViewFields object.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Session Property (Outlook)

 Copy code hover
[image]

ViewFields.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ViewFields object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields Methods (Outlook)

 Copy code hover
[image]

ViewFields Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Adds the specified field to the end of the ViewFields collection for the view.
Insert | Creates a new ViewField object and inserts it at the specified index within the ViewFields collection.
Item | Returns a ViewField object from the collection.
Remove | Removes an object from the collection.


ViewFields.Add Method (Outlook)

 Copy code hover
[image]

ViewFields.Add Method (Outlook)
See also Send feedback

Adds the specified field to the end of the ViewFields collection for the view.

Version Information

Version Added: Outlook 2007

Syntax

expression .Add(PropertyName)

expression A variable that represents a ViewFields object.

Parameters

Name | Required/Optional | Data Type | Description
PropertyName | Required | String | The name of the property to which the new object is associated. This property can be referenced by field name (displayed in the Field Chooser) or by namespace (represented by ViewField.ViewXMLSchemaName).

Return Value

A ViewField object that represents the new view field.

Remarks

To programmatically add a custom field to a view, use the ViewFields.Add method. This is the recommended way to dynamically change the view over setting the XML property of the View object.

Referencing the property in PropertyName by its field name requires the localized name in the corresponding locale. For more information on referencing properties by namespace, see Referencing Properties by Namespace.

If you are adding a custom property to the ViewFields collection, the property must exist in the UserDefinedProperties collection for the View's parent folder.

If the property already exists in the ViewFields collection, Outlook will raise an error.

Certain properties cannot be added to a view using ViewFields.Add, including binary properties, computed properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter.

Example

The following code sample in Microsoft Visual Basic for Applications (VBA) adds the Subject field to the current view of the Inbox, referencing it by its field name. To avoid Outlook raising an error, it tests for the presence of the field in the ViewFields collection representing the current view of the Inbox before adding it.

VBA Copy code Copy code
Sub DemoViewFieldsAdd()

 Dim oTableView As Outlook.TableView

 Dim oViewFields As Outlook.ViewFields

 Dim oViewField As Outlook.ViewField

 Dim oInbox As Outlook.folder

 Set oInbox = Application.Session.GetDefaultFolder(olFolderInbox)

 On Error GoTo Err_Handler

 If oInbox.CurrentView.ViewType = olTableView Then

 Set oTableView = oInbox.CurrentView

 Set oViewField = oTableView.ViewFields("Subject")

 If oViewField Is Nothing Then

 Set oViewField = oTableView.ViewFields.Add("Subject")

 End If

 End If

 Exit Sub

Err_Handler:

 MsgBox Err.Description, vbExclamation

 Resume Next

End Sub

The following code sample in VBA assumes the current view is a TableView, references the Message Class property by namespace and adds it to the current view of the current folder. To avoid Outlook raising an error, the code checks for the existence of this property in the view before calling ViewFields.Add.

VBA Copy code Copy code
Sub ViewFieldsAdd()

 Dim oFolder As Outlook.Folder

 Dim oView As Outlook.TableView

 Dim oViewField As Outlook.ViewField

 On Error Resume Next

 Dim PR_MESSAGE_CLASS As String

 PR_MESSAGE_CLASS = "http://schemas.microsoft.com/mapi/proptag/0x001a001e"

 Set oFolder = Application.ActiveExplorer.CurrentFolder

 If oFolder.CurrentView.ViewType = olTableView Then

 Set oView = oFolder.CurrentView

 'Determine if the ViewField exists in ViewFields collection

 If oView.ViewFields(PR_MESSAGE_CLASS) Is Nothing Then

 Set oViewField = oView.ViewFields.Add(PR_MESSAGE_CLASS)

 'Persist the changes

 oView.Save

 End If

 End If

End Sub

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Insert Method (Outlook)

 Copy code hover
[image]

ViewFields.Insert Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new ViewField object and inserts it at the specified index within the ViewFields collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Insert(PropertyName, Index)

expression A variable that represents a ViewFields object.

Parameters

Name | Required/Optional | Data Type | Description
PropertyName | Required | String | The name of the property to which the new object is associated.
Index | Required | Variant | Either a one-based index number at which to insert the new object, or a value used to match the ViewXMLSchemaName property value of an object in the collection where the new object is to be inserted.

Return Value

A ViewField object that represents the new view field.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Item Method (Outlook)

 Copy code hover
[image]

ViewFields.Item Method (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a ViewField object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Item(Index)

expression A variable that represents a ViewFields object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The value can be a one-based integer that indexes an ViewField object in the ViewFields collection, a string that matches the ViewXMLSchemaName property value of an ViewField object in the collection, or a field name as displayed in the Field Chooser.

Return Value

A ViewField object that represents the specified object.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFields.Remove Method (Outlook)

 Copy code hover
[image]

ViewFields.Remove Method (Outlook)
See also Send feedback

Removes an object from the collection.

Version Information

Version Added: Outlook 2007

Syntax

expression .Remove(Index)

expression A variable that represents a ViewFields object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the ViewXMLSchemaName property value of an object in the collection.

See also

Concepts

ViewFields Object

Other resources

ViewFields Object Members


ViewFont Object (Outlook)

 Copy code hover
[image]

ViewFont Object (Outlook)
See also Send feedback

Published: July 16, 2012

Represents the font used when formatting text in various portions of a view.

Version Information

Version Added: Outlook 2007

Remarks

The ViewFont object is used by the following objects to represent font formatting information applied to the text in various portions of a view:

  • The HeadingsFont property of the BusinessCardView object.

  • The DayWeekFont, DayWeekTimeFont, and MonthFont properties of the CalendarView object.

  • The BodyFont and HeadingsFont properties of the CardView object.

  • The AutoPreviewFont, ColumnFont, and RowFont properties of the TableView object.

  • The ItemFont, LowerScaleFont, and UpperScaleFont properties of the TimelineView object.

Example

The following Visual Basic for Applications (VBA) sample increments the value of the Size property for the ViewFont object returned from the ItemFont property for the current TimelineView object.

Copy code Copy code
Private Sub IncreaseItemFontSize()

 Dim objTimelineView As TimelineView

 If Application.ActiveExplorer.CurrentView.ViewType = _

 olTimelineView Then

 ' Obtain a TimelineView object reference for the

 ' current timeline view.

 Set objTimelineView = _

 Application.ActiveExplorer.CurrentView

 ' Increment the Size property of the

 ' ViewFont object obtained from the

 ' ItemFont property, but only

 ' if the font is less than 24 points

 ' in size.

 If objTimelineView.ItemFont.Size < 24 Then

 objTimelineView.ItemFont.Size = _

 objTimelineView.ItemFont.Size + 1

 ' Save the timeline view.

 objTimelineView.Save

 End If

 End If

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

ViewFont Object Members


ViewFont Members (Outlook)

 Copy code hover
[image]

ViewFont Members (Outlook)
Send feedback

Represents the font used when formatting text in various portions of a view.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Bold | Returns or sets a Boolean value that indicates if the font is bold in the ViewFont object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Color | Returns or sets an OlColor constant that indicates the color of the font in the ViewFont object. Read/write.
ExtendedColor | Returns or sets an OlCategoryColor constant as the font color of the view. Read/write
Italic | Returns or sets a Boolean value that indicates if the font is italicized in the ViewFont object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns or sets a Long value that represents the size (in points) of the font in the view. Read-only.
Strikethrough | Returns or sets a Boolean value that indicates if the font is struck through with a horizontal line in the ViewFont object. Read/write.
Underline | Returns or sets a Boolean value that indicates if the font is underlined in the ViewFont object. Read/write.


ViewFont Properties (Outlook)

 Copy code hover
[image]

ViewFont Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Bold | Returns or sets a Boolean value that indicates if the font is bold in the ViewFont object. Read/write.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Color | Returns or sets an OlColor constant that indicates the color of the font in the ViewFont object. Read/write.
ExtendedColor | Returns or sets an OlCategoryColor constant as the font color of the view. Read/write
Italic | Returns or sets a Boolean value that indicates if the font is italicized in the ViewFont object. Read/write.
Name | Returns or sets a String value that represents the display name for the object. Read/write.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.
Size | Returns or sets a Long value that represents the size (in points) of the font in the view. Read-only.
Strikethrough | Returns or sets a Boolean value that indicates if the font is struck through with a horizontal line in the ViewFont object. Read/write.
Underline | Returns or sets a Boolean value that indicates if the font is underlined in the ViewFont object. Read/write.


ViewFont.Application Property (Outlook)

 Copy code hover
[image]

ViewFont.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Bold Property (Outlook)

 Copy code hover
[image]

ViewFont.Bold Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates if the font is bold in the ViewFont object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Bold

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Class Property (Outlook)

 Copy code hover
[image]

ViewFont.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Color Property (Outlook)

 Copy code hover
[image]

ViewFont.Color Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets an OlColor constant that indicates the color of the font in the ViewFont object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Color

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.ExtendedColor Property (Outlook)

 Copy code hover
[image]

ViewFont.ExtendedColor Property (Outlook)
See also Send feedback

Returns or sets an OlCategoryColor constant as the font color of the view. Read/write

Version Information

Version Added: Outlook 2010

Syntax

expression .ExtendedColor

expression A variable that represents a ViewFont object.

Remarks

You can use the Color property or the ExtendedColor property to set the font color in a view. For a calendar view in particular, you must use the ExtendedColor property to set the font color.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Italic Property (Outlook)

 Copy code hover
[image]

ViewFont.Italic Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates if the font is italicized in the ViewFont object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Italic

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Name Property (Outlook)

 Copy code hover
[image]

ViewFont.Name Property (Outlook)
See also Send feedback

Returns or sets a String value that represents the display name for the object. Read/write.

Syntax

expression .Name

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Parent Property (Outlook)

 Copy code hover
[image]

ViewFont.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Session Property (Outlook)

 Copy code hover
[image]

ViewFont.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a ViewFont object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements perform the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Size Property (Outlook)

 Copy code hover
[image]

ViewFont.Size Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Long value that represents the size (in points) of the font in the view. Read-only.

Syntax

expression .Size

expression A variable that represents a ViewFont object.

Remarks

This property can be set to a value between 1 and 127. If this property is set to a value less than 1, the property is set to 1. If this property is set to a value greater than 127, the property is set to 127.

The default value for this property is determined by the operating system.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Strikethrough Property (Outlook)

 Copy code hover
[image]

ViewFont.Strikethrough Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates if the font is struck through with a horizontal line in the ViewFont object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Strikethrough

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


ViewFont.Underline Property (Outlook)

 Copy code hover
[image]

ViewFont.Underline Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns or sets a Boolean value that indicates if the font is underlined in the ViewFont object. Read/write.

Version Information

Version Added: Outlook 2007

Syntax

expression .Underline

expression A variable that represents a ViewFont object.

See also

Concepts

ViewFont Object

Other resources

ViewFont Object Members


Views Object (Outlook)

 Copy code hover
[image]

Views Object (Outlook)
See also Send feedback

Published: July 16, 2012

Contains a collection of all View objects in the current folder.

Remarks

Use the Views property of the Folder object to return the Views collection. Use Views(index),where index is the object's name or position within the collection, to return a single View object.

Use the Add method of the views collection to add a new view to the collection.

Use the Remove method to remove a view from the collection.

Example

The following example returns a View object of type olTableView called Table View. Before running this example, make sure a view by the name 'Table View' exists.

VBA Copy code Copy code
Sub GetView()

 'Returns a view called Table View

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objView As View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views

 'Return a view called Table View

 Set objView = objViews.Item("Table View")

End Sub

The following example adds a new view of type olIconView in the user's Notes folder.

Note Note

The Add method will fail if a view with the same name already exists.

VBA Copy code Copy code
Sub CreateView()

 'Creates a new view

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objNewView As View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderNotes).Views

 Set objNewView = objViews.Add(Name:="New Icon View Type", _

 ViewType:=olIconView, SaveOption:=olViewSaveOptionThisFolderEveryone)

End Sub

The following example removes the above view, "New Icon View Type", from the collection.

VBA Copy code Copy code
Sub DeleteView()

 'Deletes a view from the collection

 Dim objName As NameSpace

 Dim objViews As Views

 Dim objNewView As View

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderNotes).Views

 objViews.Remove ("New Icon View Type")

End Sub

See also

Concepts

Outlook Object Model Reference

Other resources

Views Object Members


Views Members (Outlook)

 Copy code hover
[image]

Views Members (Outlook)
Send feedback

Published: July 16, 2012

Contains a collection of all View objects in the current folder.

Events

Name | Description
ViewAdd | Occurs when a view is added to the collection. Microsoft Outlook creates the new view and passes it to this event.
ViewRemove | Occurs when a view has been removed from the specified collection.

Methods

Name | Description
Add | Creates a new view in the Views collection.
Item | Returns an View object from the collection.
Remove | Removes an object from the collection.

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Views Properties (Outlook)

 Copy code hover
[image]

Views Properties (Outlook)
Send feedback

Published: July 16, 2012

This object has the following properties:

Properties

Name | Description
Application | Returns an Application object that represents the parent Outlook application for the object. Read-only.
Class | Returns an OlObjectClass constant indicating the object's class. Read-only.
Count | Returns a Long indicating the count of objects in the specified collection. Read-only.
Parent | Returns the parent Object of the specified object. Read-only.
Session | Returns the NameSpace object for the current session. Read-only.


Views.Application Property (Outlook)

 Copy code hover
[image]

Views.Application Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an Application object that represents the parent Outlook application for the object. Read-only.

Syntax

expression .Application

expression A variable that represents a Views object.

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Class Property (Outlook)

 Copy code hover
[image]

Views.Class Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns an OlObjectClass constant indicating the object's class. Read-only.

Syntax

expression .Class

expression A variable that represents a Views object.

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Count Property (Outlook)

 Copy code hover
[image]

Views.Count Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns a Long indicating the count of objects in the specified collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Views object.

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Parent Property (Outlook)

 Copy code hover
[image]

Views.Parent Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the parent Object of the specified object. Read-only.

Syntax

expression .Parent

expression A variable that represents a Views object.

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Session Property (Outlook)

 Copy code hover
[image]

Views.Session Property (Outlook)
See also Send feedback

Published: July 16, 2012

Returns the NameSpace object for the current session. Read-only.

Syntax

expression .Session

expression A variable that represents a Views object.

Remarks

The Session property and the GetNamespace method can be used interchangeably to obtain the NameSpace object for the current session. Both members serve the same purpose. For example, the following statements do the same function:

VBA Copy code Copy code
Set objNamespace = Application.GetNamespace("MAPI")
VBA Copy code Copy code
Set objSession = Application.Session

See also

Concepts

Views Object

Other resources

Views Object Members


Views Methods (Outlook)

 Copy code hover
[image]

Views Methods (Outlook)
Send feedback

Published: July 16, 2012

This object has the following methods:

Methods

Name | Description
Add | Creates a new view in the Views collection.
Item | Returns an View object from the collection.
Remove | Removes an object from the collection.


Views.Add Method (Outlook)

 Copy code hover
[image]

Views.Add Method (Outlook)
See also Send feedback

Published: July 16, 2012

Creates a new view in the Views collection.

Syntax

expression .Add(Name, ViewType, SaveOption)

expression A variable that represents a Views object.

Parameters

Name

Required/Optional

Data Type

Description

Name

Required

String

The name of the new view.

ViewType

Required

OlViewType

The type of the new view.

SaveOption

Optional

OlViewSaveOption

The save option that specifies the permissions of the new view.

  • olViewSaveOptionAllFoldersOfType The view can be accessed in all folders of this type.

  • olViewSaveOptionThisFolderEveryOne The view can be accessed by all users in this folder only.

  • olViewSaveOptionThisFolderOnlyMe The view can be accessed in this folder only by the user.

Return Value

A View object that represents the new view.

Remarks

If you add a View to a Views collection of a folder that is not the current folder, you must first save a copy of the Views collection object and then add the View to this collection object, as shown in the code sample below. This is a work-around for an existing problem which will otherwise cause a call to View.Apply for the added View to fail.

Copy code Copy code
Sub CalendarView()
 Dim calView As Outlook.View
 Dim vws As Views

 Set Application.ActiveExplorer.CurrentFolder = Application.Session.GetDefaultFolder(olFolderInbox)
 ' Current folder is Inbox; add a View to the Calendar folder which is not the current folder
 ' Keep a copy of the object for the Views collection for the Calendar
 Set vws = Application.Session.GetDefaultFolder(olFolderCalendar).Views
 ' Add the View to this Views collection object
 Set calView = vws.Add("New Calendar", olCalendarView, olViewSaveOptionThisFolderEveryone)
 calView.Save
 ' This Apply call will be fine
 calView.Apply
End Sub

Example

The following Visual Basic for Applications (VBA) example creates a new view called New Table and stores it in a variable called objNewView.

VBA Copy code Copy code
Sub CreateView()
 'Creates a new view
 Dim objName As Outlook.NameSpace
 Dim objViews As Outlook.Views
 Dim objNewView As Outlook.View

 Set objName = Application.GetNamespace("MAPI")
 Set objViews = objName.GetDefaultFolder(olFolderInbox).Views
 Set objNewView = objViews.Add(Name:="New Table", _
 ViewType:=olTableView, SaveOption:=olViewSaveOptionThisFolderEveryone)
End Sub

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Item Method (Outlook)

 Copy code hover
[image]

Views.Item Method (Outlook)
See also Send feedback

Returns an View object from the collection.

Syntax

expression .Item(Index)

expression A variable that represents a Views object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | Either the index number of the object, or a value used to match the default property of an object in the collection.

Return Value

A View object that represents the specified object.

See also

Concepts

Views Object

Other resources

Views Object Members


Views.Remove Method (Outlook)

 Copy code hover
[image]

Views.Remove Method (Outlook)
See also Send feedback

Published: July 16, 2012

Removes an object from the collection.

Syntax

expression .Remove Index

expression A variable that represents a Views object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Variant | The name or 1-based index value of an object within a collection.

Example

The following example removes a View object from the Views collection.

VBA Copy code Copy code
Sub DeleteView()

 'Deletes a view from the collection

 Dim objName As Outlook.NameSpace

 Dim objViews As Outlook.Views

 Dim objView As Outlook.View

 Dim strName As String

 strName = "New Icon View"

 Set objName = Application.GetNamespace("MAPI")

 Set objViews = objName.GetDefaultFolder(olFolderNotes).Views

 For Each objView In objViews

 If objView.Name = strName Then

 objViews.Remove (strName)

 End If

 Next objView

End Sub

See also

Concepts

Views Object

Other resources

Views Object Members


Views Events (Outlook)

 Copy code hover
[image]

Views Events (Outlook)
Send feedback

Published: July 16, 2012

This object has the following events:

Events

Name | Description
ViewAdd | Occurs when a view is added to the collection. Microsoft Outlook creates the new view and passes it to this event.
ViewRemove |


Views.ViewAdd Event (Outlook)

 Copy code hover
[image]

Views.ViewAdd Event (Outlook)
See also Send feedback

Published: July 16, 2012

Occurs when a view is added to the collection. Microsoft Outlook creates the new view and passes it to this event.

Syntax

expression .ViewAdd(View)

expression A variable that represents a Views object.

Parameters

Name | Required/Optional | Data Type | Description
View | Required | View | The new view added to the collection prior to this event.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the view's name and saves it when the ViewAdd event is fired. Use the Save method after the properties have been modified to save the changes to the view. The sample code must be placed in a class module such as ThisOutlookSession, and the AddView() procedure should be called before the event procedure can be called by Outlook.

VBA Copy code Copy code
Public WithEvents objViews As Outlook.Views

Sub AddView()

 Dim objView As Outlook.View

 Set objViews = Application.ActiveExplorer.CurrentFolder.Views

 Set objView = objViews.Add("Latest View1", olTableView, olViewSaveOptionAllFoldersOfType)

End Sub

Sub objViews_ViewAdd(ByVal View As View)

'Displays name of new view

 With View

 Msgbox .Name & " was created programmatically."

 .Save

 End With

End Sub

See also

Concepts

Views Object

Other resources

Views Object Members


Views.ViewRemove Event (Outlook)

 Copy code hover
[image]

Views.ViewRemove Event (Outlook)
Send feedback

Published: July 16, 2012

Occurs when a view has been removed from the specified collection.

Syntax

expression .ViewRemove(View)

expression A variable that represents a Views object.

Parameters

Name | Required/Optional | Data Type | Description
View | Required | View | The view which was removed from the collection prior to this event.

Example

The following Microsoft Visual Basic for Applications (VBA) example displays the name of the view that has been removed from the collection when the ViewRemove event is fired. The sample code must be placed in a class module such as ThisOutlookSession, and the DeleteView() procedure should be called before the event procedure can be called by Microsoft Outlook.

VBA Copy code Copy code
Public WithEvents objViews As Outlook.Views

Sub DeleteView()
 Set objViews = Application.ActiveExplorer.CurrentFolder.Views
 objViews.Item("New Table View").Delete
End Sub

Sub objViews_ViewRemove(ByVal View As View)
 'Displays view name
 MsgBox "The view: " & View.Name & " was removed programmatically."
End Sub


Enumerations (Outlook)

 Copy code hover
[image]

Enumerations (Outlook)
Send feedback

Published: July 16, 2012

This section contains documentation for the enumerations in the Outlook object model.


OlAccountType Enumeration (Outlook)

 Copy code hover
[image]

OlAccountType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of an Account.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olEas | 4 | An account that uses Exchange ActiveSync (EAS) on mobile devices.
olExchange | 0 | An Exchange account.
olHttp | 3 | An HTTP account.
olImap | 1 | An IMAP account.
olOtherAccount | 5 | Other or unknown account.
olPop3 | 2 | A POP3 account.


OlActionCopyLike Enumeration (Outlook)

 Copy code hover
[image]

OlActionCopyLike Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how item properties will be copied.

Name | Value | Description
olForward | 2 | Properties of the new item will be set such that the new item is a forward of the original item. If creating a new MailItem, the value of the To and CC properties in the new item will be empty and the Subject property of the new item will be the original Subject with a prefix such as "FW:" (see Prefix property) added. The attachments on the original item will be copied to the new item.
olReply | 0 | Properties of the new item will be set such that the new item is a reply to the original item. If creating a new MailItem, the value of the original To field will be copied to the SenderEmailAddress property of the new item, the CC field will be blank and the Subject field of the new item will be the original Subject with a prefix such as "RE:" (see Prefix property) added.
olReplyAll | 1 | Properties of the new item will be set such that the new item is a reply to all of the senders of the original item. If creating a new MailItem, the value of the SenderEmailAddress and CC properties will be copied to the To property of the new item and the Subject property of the new item will be the Subject of the original item with a prefix such as "RE:" (see Prefix property) added.
olReplyFolder | 3 | If creating a new PostItem based on an old one, the Post To property of the new item will contain the active folder address, the Subject property of the original item will be copied to the ConversationTopic property of the new item, and the Subject property of the new item will be empty.
olRespond | 4 | Used exclusively for voting button actions.

Remarks

Used by the CopyLike property of an Action to specify how item properties will be copied to the new item that is created when the Action is executed.


OlActionReplyStyle Enumeration (Outlook)

 Copy code hover
[image]

OlActionReplyStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the reply style.

Name | Value | Description
olEmbedOriginalItem | 1 | The reply will include the original item embedded in it.
olIncludeOriginalText | 2 | The reply will include the text of the original item.
olIndentOriginalText | 3 | The reply will include the indented text of the original item.
olLinkOriginalItem | 4 | The reply will include a link to the original item.
olOmitOriginalText | 0 | The reply will not include any references to the original item or its text.
olReplyTickOriginalText | 1000 | The reply will include the original text with each line preceded by a symbol such as ">".
olUserPreference | 5 | The reply style will be set based on the user's preference.

Remarks

Used by the ReplyStyle property of an Action to specify the reply style that will be used when the Action is executed.


OlActionResponseStyle Enumeration (Outlook)

 Copy code hover
[image]

OlActionResponseStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the response style.

Name | Value | Description
olOpen | 0 | Indicates that a form will be opened.
olPrompt | 2 | Indicates that the user will be prompted to open or send the form.
olSend | 1 | Indicates that the form will be sent immediately.

Remarks

Used by the ResponseStyle property of an Action to specify the response style that will be used when the Action is executed.


OlActionShowOn Enumeration (Outlook)

 Copy code hover
[image]

OlActionShowOn Enumeration (Outlook)
Send feedback

Identifies where an Action is displayed as an available action.

Name | Value | Description
olDontShow | 0 | Indicates that the action will not be displayed on the menu or toolbar.
olMenu | 1 | Indicates that the action will be displayed as an available action on the menu.
olMenuAndToolbar | 2 | Indicates that the action will be displayed as an available action on the menu and the toolbar.

Remarks

Displaying an action on a toolbar is only supported in versions of Outlook without the Office Fluent ribbon, before Microsoft Office Outlook 2007. In versions of Outlook that contain the Ribbon, custom actions are displayed only on the Custom Actions menu on the ribbon for an inspector, and on the context menu of an item.


OlAddressEntryUserType Enumeration (Outlook)

 Copy code hover
[image]

OlAddressEntryUserType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Represents the type of user for the AddressEntry or object derived from AddressEntry.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olExchangeAgentAddressEntry | 3 | An address entry that is an Exchange agent.
olExchangeDistributionListAddressEntry | 1 | An address entry that is an Exchange distribution list.
olExchangeOrganizationAddressEntry | 4 | An address entry that is an Exchange organization.
olExchangePublicFolderAddressEntry | 2 | An address entry that is an Exchange public folder.
olExchangeRemoteUserAddressEntry | 5 | An Exchange user that belongs to a different Exchange forest.
olExchangeUserAddressEntry | 0 | An Exchange user that belongs to the same Exchange forest.
olLdapAddressEntry | 20 | An address entry that uses the Lightweight Directory Access Protocol (LDAP).
olOtherAddressEntry | 40 | A custom or some other type of address entry such as FAX.
olOutlookContactAddressEntry | 10 | An address entry in an Outlook Contacts folder.
olOutlookDistributionListAddressEntry | 11 | An address entry that is an Outlook distribution list.
olSmtpAddressEntry | 30 | An address entry that uses the Simple Mail Transfer Protocol (SMTP).


OlAddressListType Enumeration (Outlook)

 Copy code hover
[image]

OlAddressListType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Represents the type of AddressList.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olCustomAddressList | 4 | A custom address book provider.
olExchangeContainer | 1 | A container for address lists on an Exchange server.
olExchangeGlobalAddressList | 0 | An Exchange Global Address List.
olOutlookAddressList | 2 | An address list that corresponds to the Outlook Contacts Address Book.
olOutlookLdapAddressList | 3 | An address list that uses the Lightweight Directory Access Protocol (LDAP).


OlAlign Enumeration (Outlook)

 Copy code hover
[image]

OlAlign Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the alignment for the Label property of the ColumnFormat object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAlignCenter | 1 | Indicates that the label for the specified column should be centered.
olAlignLeft | 0 | Indicates that the label for the specified column should be left-aligned.
olAlignRight | 2 | Indicates that the label for the specified column should be right-aligned.


OlAlignment Enumeration (Outlook)

 Copy code hover
[image]

OlAlignment Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how a caption is aligned with the edge of a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAlignmentLeft | 0 | Places the caption to the left of the control.
olAlignmentRight | 1 | Places the caption to the right of the control.


OlAlwaysDeleteConversation Enumeration (Outlook)

 Copy code hover
[image]

OlAlwaysDeleteConversation Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies constants that determine whether new items of the conversation are always moved to the Deleted Items folder of the specified delivery store.

Name | Value | Description
olAlwaysDelete | 1 | New items of the conversation are always moved to the Deleted Items folder for the store that contains the items
olAlwaysDeleteUnsupported | 2 | The specified store does not support the action of always moving items to the Deleted Items folder of that store.
olDoNotDelete | 0 | New items joining the conversation are not moved to the Deleted Items folder on the specified delivery store, and existing conversation items in the Deleted Items folder are moved to the Inbox.

Remarks

This enumeration is used by the GetAlwaysDelete method of the Conversation Object (Outlook).


OlAppointmentCopyOptions Enumeration (Outlook)

 Copy code hover
[image]

OlAppointmentCopyOptions Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies what actions to take when copying an AppointmentItem object to a folder.

Version Information

Version Added: Outlook 2010

Name | Value | Description
olCopyAsAccept | 2 | Creates an appointment in the destination folder and accepts the meeting request automatically.
olCreateAppointment | 1 | Creates an appointment in the destination folder without defaulting to a response or prompting for a response.
olPromptUser | 0 | Copies the appointment to the destination folder and prompts the user to accept the request before completing the copy operation.


OlAppointmentTimeField Enumeration (Outlook)

 Copy code hover
[image]

OlAppointmentTimeField Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the time field in an appointment that the control is bound to.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAppointmentTimeFieldEnd | 3 | The control is bound to the end time of the appointment.
olAppointmentTimeFieldNone | 1 | The control is not bound.
olAppointmentTimeFieldStart | 2 | The control is bound to the start time of the appointment.


OlAttachmentBlockLevel Enumeration (Outlook)

 Copy code hover
[image]

OlAttachmentBlockLevel Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies whether there is any restriction on the type of attachments for an item.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAttachmentBlockLevelNone | 0 | There is no restriction on the type of the attachment based on its file extension.
olAttachmentBlockLevelOpen | 1 | There is a restriction on the type of the attachment based on its file extension such that users must first save the attachment to disk before opening it.

Remarks

Attachments with the BlockLevel equal to olAttachmentBlockLevelOpen are on the Level 2 list of attachments that administrators maintain for attachment security. For more information on attachment security in Outlook, see the Office Resource Kit Web site.


OlAttachmentType Enumeration (Outlook)

 Copy code hover
[image]

OlAttachmentType Enumeration (Outlook)
See also Send feedback

Published: July 16, 2012

Specifies the attachment type.

Name | Value | Description
olByReference | 4 | This value is no longer supported since Microsoft Outlook 2007. Use olByValue to attach a copy of a file in the file system.
olByValue | 1 | The attachment is a copy of the original file and can be accessed even if the original file is removed.
olEmbeddeditem | 5 | The attachment is an Outlook message format file (.msg) and is a copy of the original message.
olOLE | 6 | The attachment is an OLE document.

Remarks

Used as an optional parameter to the Attachments.Add Method (Outlook) to specify the attachment type.

See also

Concepts

How to: Attach a File to a Mail Item
How to: Attach an Outlook Contact Item to an Email Message
How to: Limit the Size of an Attachment to an Outlook Email Message
How to: Modify an Attachment of an Outlook Email Message


OlAutoDiscoverConnectionMode Enumeration (Outlook)

 Copy code hover
[image]

OlAutoDiscoverConnectionMode Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of connection to the Exchange server for the auto-discovery service.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAutoDiscoverConnectionExternal | 1 | Connection is over the Internet.
olAutoDiscoverConnectionInternal | 2 | Connection is over the Intranet.
olAutoDiscoverConnectionInternalDomain | 3 | Connection is in the same domain over the Intranet.
olAutoDiscoverConnectionUnknown | 0 | Other or unknown connection, or no connection.


OlAutoPreview Enumeration (Outlook)

 Copy code hover
[image]

OlAutoPreview Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates how items will be automatically previewed.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAutoPreviewAll | 0 | All items are automatically previewed.
olAutoPreviewNone | 2 | No items are automatically previewed.
olAutoPreviewUnread | 1 | Only unread items are automatically previewed.

Remarks

Used by the TableView.AutoPreview Property (Outlook) to determine how items are automatically previewed.


OlBackStyle Enumeration (Outlook)

 Copy code hover
[image]

OlBackStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how the background of a control is rendered.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olBackStyleOpaque | 1 | Indicates the background color of the control is rendered.
olBackStyleTransparent | 0 | Indicates that the background color of the control is the background color of the parent control. It is not a truly transparent display.


OlBodyFormat Enumeration (Outlook)

 Copy code hover
[image]

OlBodyFormat Enumeration (Outlook)
Send feedback

Specifies the format of the body text of an item.

Name | Value | Description
olFormatHTML | 2 | HTML format
olFormatPlain | 1 | Plain format
olFormatRichText | 3 | Rich text format
olFormatUnspecified | 0 | Unspecified format


OlBorderStyle Enumeration (Outlook)

 Copy code hover
[image]

OlBorderStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how the border of a control is rendered.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olBorderStyleNone | 0 | The control is rendered without any border.
olBorderStyleSingle | 1 | The control is rendered with a single-line border.


OlBusinessCardType Enumeration (Outlook)

 Copy code hover
[image]

OlBusinessCardType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Identifies the type of Electronic Business Card (EBC) format associated with a ContactItem object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olBusinessCardTypeInterConnect | 1 | Indicates that the ContactItem uses the Microsoft Office InterConnect format for the associated Electronic Business Card.
olBusinessCardTypeOutlook | 0 | Indicates that the ContactItem object uses the Microsoft Outlook format for the associated Electronic Business Card.


OlBusyStatus Enumeration (Outlook)

 Copy code hover
[image]

OlBusyStatus Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates a user's availability.

Name | Value | Description
olBusy | 2 | The user is busy.
olFree | 0 | The user is available.
olOutOfOffice | 3 | The user is out of office.
olTentative | 1 | The user has a tentative appointment scheduled.
olWorkingElsewhere | 4 | The user is working in a location away from the office.

Remarks

The user's availability is based on scheduled appointments. See AppointmentItem.BusyStatus Property (Outlook).


OlCalendarDetail Enumeration (Outlook)

 Copy code hover
[image]

OlCalendarDetail Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the level of detail for calendar items that will be exported to an iCalendar (.ics) file.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFreeBusyAndSubject | 1 | Free/busy information and the appointment subjects are exported to the iCalendar file.
olFreeBusyOnly | 0 | Only free/busy information is exported to the iCalendar file.
olFullDetails | 2 | Full details of each appointment item are exported to the iCalendar file.

Remarks

This enumeration is used by the CalendarDetail property of the CalendarSharing Object (Outlook) to determine the level of detail for calendar items stored in the iCalendar file created by the ForwardAsICal and SaveAsICal methods.


OlCalendarMailFormat Enumeration (Outlook)

 Copy code hover
[image]

OlCalendarMailFormat Enumeration (Outlook)
Send feedback

Determines the format of the calendar information in the body of the MailItem created by the ForwardAsICal method.

Name | Value | Description
olCalendarMailFormatDailySchedule | 0 | The calendar information is formatted as a daily schedule of appointments, containing an hour-by-hour breakdown of the calendar, showing both free and busy time blocks along with working-hour information. This layout is intended to help show recipients which times you are available.
olCalendarMailFormatEventList | 1 | The calendar information is formatted as a list of events, containing a list of the calendar appointments without showing any time blocks. This layout is intended to help show recipients the events scheduled for a given time period.

Remarks

For more information, see Sharing Calendars and How to: Export a Calendar using Payload Sharing.


OlCalendarViewMode Enumeration (Outlook)

 Copy code hover
[image]

OlCalendarViewMode Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the view mode specified in the CalendarViewMode property of the CalendarView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olCalendarView5DayWeek | 4 | Displays a 5-day week.
olCalendarViewDay | 0 | Displays a single day.
olCalendarViewMonth | 2 | Displays a month.
olCalendarViewMultiDay | 3 | Displays a number of days equal to the DaysInMultiDayMode property value of the CalendarView object.
olCalendarViewWeek | 1 | Displays a 7-day week.


OlCategoryColor Enumeration (Outlook)

 Copy code hover
[image]

OlCategoryColor Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the color that is specified for a category or a font in a view.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olCategoryColorBlack | 15 | Black
olCategoryColorBlue | 8 | Blue
olCategoryColorDarkBlue | 23 | Dark Blue
olCategoryColorDarkGray | 14 | Dark Gray
olCategoryColorDarkGreen | 20 | Dark Green
olCategoryColorDarkMaroon | 25 | Dark Maroon
olCategoryColorDarkOlive | 22 | Dark Olive
olCategoryColorDarkOrange | 17 | Dark Orange
olCategoryColorDarkPeach | 18 | Dark Peach
olCategoryColorDarkPurple | 24 | Dark Purple
olCategoryColorDarkRed | 16 | Dark Red
olCategoryColorDarkSteel | 12 | Dark Steel
olCategoryColorDarkTeal | 21 | Dark Teal
olCategoryColorDarkYellow | 19 | Dark Yellow
olCategoryColorGray | 13 | Gray
olCategoryColorGreen | 5 | Green
olCategoryColorMaroon | 10 | Maroon
olCategoryColorNone | 0 | No color assigned.
olCategoryColorOlive | 7 | Olive
olCategoryColorOrange | 2 | Orange
olCategoryColorPeach | 3 | Peach
olCategoryColorPurple | 9 | Purple
olCategoryColorRed | 1 | Red
olCategoryColorSteel | 11 | Steel
olCategoryColorTeal | 6 | Teal
olCategoryColorYellow | 4 | Yellow

Remarks

Used by the Color property of the Category Object (Outlook), and the ExtendedColor property of the ViewFont Object (Outlook).

The color constants provided here are approximations of the actual colors used by the Category object. Use the CategoryBorderColor, CategoryGradientBottomColor, and CategoryGradientTopColor properties to retrieve the OLE_COLOR color values that are used to represent the Category object, after setting the Color property to the appropriate constant.


OlCategoryShortcutKey Enumeration (Outlook)

 Copy code hover
[image]

OlCategoryShortcutKey Enumeration (Outlook)
Send feedback

Identifies the shortcut key specified for the ShortcutKey property of the Category object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olCategoryShortcutKeyCtrlF10 | 10 | CTRL+F10
olCategoryShortcutKeyCtrlF11 | 11 | CTRL+F11
olCategoryShortcutKeyCtrlF12 | 12 | CTRL+F12
olCategoryShortcutKeyCtrlF2 | 2 | CTRL+F2
olCategoryShortcutKeyCtrlF3 | 3 | CTRL+F3
olCategoryShortcutKeyCtrlF4 | 4 | CTRL+F4
olCategoryShortcutKeyCtrlF5 | 5 | CTRL+F5
olCategoryShortcutKeyCtrlF6 | 6 | CTRL+F6
olCategoryShortcutKeyCtrlF7 | 7 | CTRL+F7
olCategoryShortcutKeyCtrlF8 | 8 | CTRL+F8
olCategoryShortcutKeyCtrlF9 | 9 | CTRL+F9
olCategoryShortcutKeyNone | 0 | No shortcut key specified.


OlColor Enumeration (Outlook)

 Copy code hover
[image]

OlColor Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Constants that represent colors.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAutoColor | 0 | Color is based on system preferences
olColorAqua | 15 | Aqua
olColorBlack | 1 | Black
olColorBlue | 13 | Blue
olColorFuchsia | 14 | Fuschsia
olColorGray | 8 | Gray
olColorGreen | 3 | Green
olColorLime | 11 | Lime
olColorMaroon | 2 | Maroon
olColorNavy | 5 | Navy
olColorOlive | 4 | Olive
olColorPurple | 6 | Purple
olColorRed | 10 | Red
olColorSilver | 9 | Silver
olColorTeal | 7 | Teal
olColorWhite | 16 | White
olColorYellow | 12 | Yellow

Remarks

Used by the Color property of the ViewFont Object (Outlook) to indicate the font color.


OlComboBoxStyle Enumeration (Outlook)

 Copy code hover
[image]

OlComboBoxStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the behavior of a combo box control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olComboBoxStyleCombo | 0 | Indicates that the combo box behaves like a traditional combo box in which the user can type a value in the edit box or select a value from the drop-down list.
olComboBoxStyleList | 1 | Indicates that the combo box behaves like a drop-down list from which the user can only select a value.


OlContactPhoneNumber Enumeration (Outlook)

 Copy code hover
[image]

OlContactPhoneNumber Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specfies the telephone number type.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olContactPhoneAssistant | 0 | Telephone number of the person who is the assistant for the contact
olContactPhoneBusiness | 1 | Business telephone number
olContactPhoneBusiness2 | 2 | Second business telephone number
olContactPhoneBusinessFax | 3 | Business fax number
olContactPhoneCallback | 4 | Callback telephone number
olContactPhoneCar | 5 | Car telephone number
olContactPhoneCompany | 6 | Main company telephone number
olContactPhoneHome | 7 | Home telephone number
olContactPhoneHome2 | 8 | Second home telephone number
olContactPhoneHomeFax | 9 | Home fax number
olContactPhoneISDN | 10 | Integrated Services Digital Network (ISDN) phone number
olContactPhoneMobile | 11 | Mobile telephone number
olContactPhoneOther | 12 | Other telephone number
olContactPhoneOtherFax | 13 | Other fax number
olContactPhonePager | 14 | Pager telephone number
olContactPhonePrimary | 15 | Primary telephone number
olContactPhoneRadio | 16 | Radio telephone number
olContactPhoneTelex | 17 | Telex telephone number
olContactPhoneTTYTTD | 18 | TTD/TTY (Teletypewriting Device for the Deaf/Teletypewriter) telephone number

Remarks

See ContactItem Object (Outlook).


OlDaysOfWeek Enumeration (Outlook)

 Copy code hover
[image]

OlDaysOfWeek Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Constants representing days of the week.

Name | Value | Description
olFriday | 32 | Friday
olMonday | 2 | Monday
olSaturday | 64 | Saturday
olSunday | 1 | Sunday
olThursday | 16 | Thursday
olTuesday | 4 | Tuesday
olWednesday | 8 | Wednesday


OlDayWeekTimeScale Enumeration (Outlook)

 Copy code hover
[image]

OlDayWeekTimeScale Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the scale of time periods used to display Outlook items in a CalendarView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olTimeScale10Minutes | 2 | Indicates that each time period represents 10 minutes.
olTimeScale15Minutes | 3 | Indicates that each time period represents 15 minutes.
olTimeScale30Minutes | 4 | Indicates that each time period represents 30 minutes.
olTimeScale5Minutes | 0 | Indicates that each time period represents 5 minutes.
olTimeScale60Minutes | 5 | Indicates that each time period represents 60 minutes.
olTimeScale6Minutes | 1 | Indicates that each time period represents 6 minutes.


OlDefaultExpandCollapseSetting Enumeration (Outlook)

 Copy code hover
[image]

OlDefaultExpandCollapseSetting Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the expand/collapse default value specified in the DefaultExpandCollapseSetting property of the TableView and TimelineView objects.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAllCollapsed | 1 | All groups are collapsed when the view is initially displayed.
olAllExpanded | 0 | All groups are expanded when the view is initially displayed.
olLastViewed | 2 | Groups are displayed expanded or collapsed depending on the state the groups were in when the view was last closed.


OlDefaultFolders Enumeration (Outlook)

 Copy code hover
[image]

OlDefaultFolders Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the folder type for a specified folder.

Name | Value | Description
olFolderCalendar | 9 | The Calendar folder.
olFolderConflicts | 19 | The Conflicts folder (subfolder of the Sync Issues folder). Only available for an Exchange account.
olFolderContacts | 10 | The Contacts folder.
olFolderDeletedItems | 3 | The Deleted Items folder.
olFolderDrafts | 16 | The Drafts folder.
olFolderInbox | 6 | The Inbox folder.
olFolderJournal | 11 | The Journal folder.
olFolderJunk | 23 | The Junk E-Mail folder.
olFolderLocalFailures | 21 | The Local Failures folder (subfolder of the Sync Issues folder). Only available for an Exchange account.
olFolderManagedEmail | 29 | The top-level folder in the Managed Folders group. For more information on Managed Folders, see the Help in Microsoft Outlook. Only available for an Exchange account.
olFolderNotes | 12 | The Notes folder.
olFolderOutbox | 4 | The Outbox folder.
olFolderSentMail | 5 | The Sent Mail folder.
olFolderServerFailures | 22 | The Server Failures folder (subfolder of the Sync Issues folder). Only available for an Exchange account.
olFolderSuggestedContacts | 30 | The Suggested Contacts folder.
olFolderSyncIssues | 20 | The Sync Issues folder. Only available for an Exchange account.
olFolderTasks | 13 | The Tasks folder.
olFolderToDo | 28 | The To Do folder.
olPublicFoldersAllPublicFolders | 18 | The All Public Folders folder in the Exchange Public Folders store. Only available for an Exchange account.
olFolderRssFeeds | 25 | The RSS Feeds folder.

Remarks

Used as a parameter to the NameSpace.GetSharedDefaultFolder, NameSpace.GetDefaultFolder, Store.GetDefaultFolder, and Folder.Add methods. Also used by the SharingItem.RequestFolder property.


OlDefaultSelectNamesDisplayMode Enumeration (Outlook)

 Copy code hover
[image]

OlDefaultSelectNamesDisplayMode Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the default caption, the number of buttons, the button labels, and the address lists to display in the Select Names dialog box without requiring a resource file for any localized caption and labels.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olDefaultDelegates | 6 | Displays one edit box for To recipients, uses localized string representing "Add" for the To button, and localized string representing "Add Users" for the caption. CcLabel and BccLabel are set to an empty string. Sets SelectNamesDialog.AllowMultipleSelection to True and SelectNamesDialog.NumberOfRecipientSelectors to olTo.
olDefaultMail | 1 | Displays three edit boxes for To, Cc, and Bcc recipients, uses localized strings representing "To", "Cc", and "Bcc" for To, Cc, and Bcc buttons, and localized string representing "Select Names" for the caption. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olToCcBcc.
olDefaultMeeting | 2 | Displays three edit boxes for Required, Optional, and Resource recipients, uses localized strings representing "Required", "Optional", and "Resources" for the To, Cc, and Bcc buttons, and localized string representing "Select Attendees and Resources" for the caption. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olToCcBcc.
olDefaultMembers | 5 | Displays one edit box for To recipients, uses localized string representing "To" for the To button, and localized string representing "Select Members" for caption. CcLabel and BccLabel are set to an empty string. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olTo.
olDefaultPickRooms | 8 | Displays one edit box for Resource recipients, uses localized string representing "Rooms" for To button, and localized string representing "Select Rooms" for caption. CcLabel and BccLabel are set to an empty string. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olShowTo. InitialDisplayList is set to the Global Address List.
olDefaultSharingRequest | 4 | Displays one edit box for To recipients, uses localized string representing "To" for To button, and localized string representing "Select Names" for caption. CcLabel and BccLabel are set to an empty string. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olTo.
olDefaultSingleName | 7 | Displays no edit boxes for recipients, uses localized string representing "Select Name" for caption. ToLabel, CcLabel, and Bcclabel are set to an empty string. Sets AllowMultipleSelection to False and NumberOfRecipientSelectors to olNone.
olDefaultTask | 3 | Displays one edit box for To recipients, uses localized string representing "To" for To button, and localized string representing "Select Task Recipient" for caption. CcLabel and BccLabel are set to an empty string. Sets AllowMultipleSelection to True and NumberOfRecipientSelectors to olTo.


OlDisplayType Enumeration (Outlook)

 Copy code hover
[image]

OlDisplayType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Describes the nature of the address.

Name | Value | Description
olAgent | 3 | Agent address
olDistList | 1 | Exchange distribution list
olForum | 2 | Forum address
olOrganization | 4 | Organization address
olPrivateDistList | 5 | Outlook private distribution list
olRemoteUser | 6 | Remote user address
olUser | 0 | User address

Remarks

Used by the DisplayType property of the ExchangeDistributionList, ExchangeUser, and Recipient objects.


OlDownloadState Enumeration (Outlook)

 Copy code hover
[image]

OlDownloadState Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the download state.

Name | Value | Description
olFullItem | 1 | Full item has been downloaded.
olHeaderOnly | 0 | Only the header has been downloaded.

Remarks

Used by the DownLoadState property of an item to indicate the download state.


OlDragBehavior Enumeration (Outlook)

 Copy code hover
[image]

OlDragBehavior Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the drag behavior of a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olDragBehaviorDisabled | 0 | The control does not support drag-and-drop activities. It will always display the "no" cursor when an item is dragged over the control.
olDragBehaviorEnabled | 1 | The control can support drag-and-drop activities. Use the drag and drop events to control this behavior.


OlEditorType Enumeration (Outlook)

 Copy code hover
[image]

OlEditorType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the editor type.

Name | Value | Description
olEditorHTML | 2 | HTML editor
olEditorRTF | 3 | Real Text Format (RTF) editor
olEditorText | 1 | Text editor
olEditorWord | 4 | Microsoft Office Word editor

Remarks

Used by the EditorType property of Inspector objects.


OlEnterFieldBehavior Enumeration (Outlook)

 Copy code hover
[image]

OlEnterFieldBehavior Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the behavior when focus enters a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olEnterFieldBehaviorRecallSelection | 1 | The previous selection is displayed.
olEnterFieldBehaviorSelectAll | 0 | The contents of the control are selected and any previous selection is ignored.


OlExchangeConnectionMode Enumeration (Outlook)

 Copy code hover
[image]

OlExchangeConnectionMode Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies whether the account is connected to an Exchange server and if so, the connection mode.

Name | Value | Description
olCachedConnectedDrizzle | 600 | The account is using cached Exchange mode such that headers are downloaded first, followed by the bodies and attachments of full items.
olCachedConnectedFull | 700 | The account is using cached Exchange mode on a Local Area Network or a fast connection with the Exchange server. The user can also select this state manually, disabling auto-detect logic and always downloading full items regardless of connection speed.
olCachedConnectedHeaders | 500 | The account is using cached Exchange mode on a dial-up or slow connection with the Exchange server, such that only headers are downloaded. Full item bodies and attachments remain on the server. The user can also select this state manually regardless of connection speed.
olCachedDisconnected | 400 | The account is using cached Exchange mode with a disconnected connection to the Exchange server.
olCachedOffline | 200 | The account is using cached Exchange mode and the user has selected Work Offline from the File menu.
olDisconnected | 300 | The account has a disconnected connection to the Exchange server.
olNoExchange | 0 | The account does not use an Exchange server.
olOffline | 100 | The account is not connected to an Exchange server and is in the classic offline mode. This also occurs when the user selects Work Offline from the File menu.
olOnline | 800 | The account is connected to an Exchange server and is in the classic online mode.


OlExchangeStoreType Enumeration (Outlook)

 Copy code hover
[image]

OlExchangeStoreType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of Exchange store.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olExchangeMailbox | 1 | Specifies an Exchange delegate mailbox store.
olExchangePublicFolder | 2 | Specifies an Exchange Public Folder store.
olNotExchange | 3 | Specifies that the store is not an Exchange store.
olPrimaryExchangeMailbox | 0 | Specifies a primary Exchange mailbox store.
olAdditionalExchangeMailbox | 4 | Specifies an additional Exchange mailbox store.

Remarks

Used by the ExchangeStoreType property of the Store object.


OlFlagIcon Enumeration (Outlook)

 Copy code hover
[image]

OlFlagIcon Enumeration (Outlook)
Send feedback

Members

Name | Value | Description
olBlueFlagIcon | 5 |
olGreenFlagIcon | 3 |
olNoFlagIcon | 0 |
olOrangeFlagIcon | 2 |
olPurpleFlagIcon | 1 |
olRedFlagIcon | 6 |
olYellowFlagIcon | 4 |


OlFlagStatus Enumeration (Outlook)

 Copy code hover
[image]

OlFlagStatus Enumeration (Outlook)
Send feedback

Members

Name | Value | Description
olFlagComplete | 1 |
olFlagMarked | 2 |
olNoFlag | 0 |


OlFolderDisplayMode Enumeration (Outlook)

 Copy code hover
[image]

OlFolderDisplayMode Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the folder display mode.

Name | Value | Description
olFolderDisplayFolderOnly | 1 | Only the contents of the selected folder are displayed.
olFolderDisplayNoNavigation | 2 | Folder contents are displayed but no navigation pane is shown.
olFolderDisplayNormal | 0 | Folder is displayed with navigation pane on the left and folder contents on the right.

Remarks

Used as an optional parameter to the Explorers.Add method.


OlFormatCurrency Enumeration (Outlook)

 Copy code hover
[image]

OlFormatCurrency Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display currency Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatCurrencyDecimal | 1 | Displays currency values with decimal places.
olFormatCurrencyNonDecimal | 2 | Displays currency values without decimal places, rounding the currency value to the nearest integer.


OlFormatDateTime Enumeration (Outlook)

 Copy code hover
[image]

OlFormatDateTime Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display date/time Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatDateTimeBestFit | 17 | Displays the date/time value using the best fit for the data contained in the column.
olFormatDateTimeLongDate | 6 | Displays a long date, without the day name, according to your locale's format.
olFormatDateTimeLongDateReversed | 7 | Displays a long date, reversing the day number and month name, according to your locale's format.
OlFormatDateTimeLongDayDate | 5 | Displays a long date, with the day name, according to your locale's format.
olFormatDateTimeLongDayDateTime | 1 | Displays a long date and long time according to your locale's format.
olFormatDateTimeLongTime | 15 | Displays a long time according to your locale's format.
olFormatDateTimeShortDate | 8 | Displays a short date according to your locale's format.
olFormatDateTimeShortDateNumOnly | 9 | Displays a short date, using numeric representations of the day, month, and year, according to your locale's format.
olFormatDateTimeShortDateTime | 2 | Displays a short date and short time according to your locale's format.
olFormatDateTimeShortDayDate | 13 | Displays a short date, with the day abbreviation, according to your locale's format.
olFormatDateTimeShortDayDateTime | 3 | Displays a day abbreviation, short date, and short time according to your locale's format.
olFormatDateTimeShortDayMonth | 10 | Displays the month and the day of a date, with the day abbreviation, according to your locale's format.
olFormatDateTimeShortDayMonthDateTime | 4 | Displays a day abbreviation, day number, month number, and short time according to your locale's format.
olFormatDateTimeShortMonthYear | 11 | Displays the month and year of a date, according to your locale's format.
olFormatDateTimeShortMonthYearNumOnly | 12 | Displays the month and year of a date, using numeric representations of the month and year, according to your locale's format.
olFormatDateTimeShortTime | 16 | Displays a short time according to your locale's format.


OlFormatDuration Enumeration (Outlook)

 Copy code hover
[image]

OlFormatDuration Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display duration Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatDurationLong | 2 | Displays duration values using full names for time period descriptions.
olFormatDurationLongBusiness | 4 | Displays duration values, taking into consideration specified calendar work week settings and using full names for time period descriptions.
olFormatDurationShort | 1 | Displays duration values using abbreviations for time period descriptions.
olFormatDurationShortBusiness | 3 | Displays duration values, taking into consideration specified calendar work week settings and using abbreviations for time period descriptions.

Remarks

Used by the FieldFormat property of the ColumnFormat object, and the DisplayFormat property of the UserDefinedProperty object.


OlFormatEnumeration Enumeration (Outlook)

 Copy code hover
[image]

OlFormatEnumeration Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display enumeration Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatEnumBitmap | 1 | Display as a bitmap with a pop-up list.
olFormatEnumText | 2 | Display as text with a pop-up list.


OlFormatInteger Enumeration (Outlook)

 Copy code hover
[image]

OlFormatInteger Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display integer Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatIntegerComputer1 | 2 | Displays integer values, representing bytes, as kilobytes (with the abbreviation "K") depending on the value. For example, the integer value of 1048576 is displayed as "1,024 K".
olFormatIntegerComputer2 | 3 | Displays integer values, representing bytes, as either kilobytes (with the abbreviation "K"), megabytes (with the abbreviation "M"), or gigabytes (with the abbreviation "G"), depending on the value. For example, the integer value of 2048 is displayed as "2 K".
olFormatIntegerComputer3 | 4 | Displays integer values, representing bytes, as either bytes (with the abbreviation "B"), kilobytes (with the abbreviation "KB"), megabytes (with the abbreviation "MB"), or gigabytes (with the abbreviation "GB"), depending on the value. For example, the integer value of 1000 is displayed as "1,000 B".
olFormatIntegerPlain | 1 | Displays integer values using the number format specified in your computer's regional settings.


OlFormatKeywords Enumeration (Outlook)

 Copy code hover
[image]

OlFormatKeywords Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display keyword Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatKeywordsText | 1 | Displays values as text.


OlFormatNumber Enumeration (Outlook)

 Copy code hover
[image]

OlFormatNumber Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display number Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatNumber1Decimal | 3 | Displays formatted number values, including one fixed decimal place, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.2".
olFormatNumber2Decimal | 4 | Displays formatted number values, including two fixed decimal places, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.16".
olFormatNumberAllDigits | 1 | Displays formatted number values, including any decimal places specified in the value, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.155".
olFormatNumberComputer1 | 6 | Displays formatted number values, representing bytes, as kilobytes (with the abbreviation "K") depending on the value. For example, the integer value of 1048576 is displayed as "1,024 K".
olFormatNumberComputer2 | 7 | Displays formatted number values, representing bytes, as either kilobytes (with the abbreviation "K"), megabytes (with the abbreviation "M"), or gigabytes (with the abbreviation "G"), depending on the value. For example, the integer value of 2048 is displayed as "2 K".
olFormatNumberComputer3 | 8 | Displays formatted number values, representing bytes, as either bytes (with the abbreviation "B"), kilobytes (with the abbreviation "KB"), megabytes (with the abbreviation "MB"), or gigabytes (with the abbreviation "GB"), depending on the value. For example, the integer value of 1000 is displayed as "1,000 B".
olFormatNumberRaw | 9 | Displays unformatted number values, including any decimal places specified in the value. For example, the value 1048576 is displayed as "1048576".
olFormatNumberScientific | 5 | Displays formatted number values, using scientific notation. For example, the value 1048576 is displayed as "1.049E+06".
olFormatNumberTruncated | 2 | Displays formatted number values as integers, rounding all decimal values, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.1 is displayed as "4,010".


OlFormatPercent Enumeration (Outlook)

 Copy code hover
[image]

OlFormatPercent Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display percent Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatPercent1Decimal | 2 | Displays formatted number values, including one fixed decimal place, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.2%".
olFormatPercent2Decimal | 3 | Displays formatted number values, including two fixed decimal places, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.16%"
olFormatPercentAllDigits | 4 | Displays formatted number values, including any decimal places specified in the value, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010.155%"
olFormatPercentRounded | 1 | Displays formatted number values as integers, rounding all decimal values, using the group and decimal delimiters specified in the system's regional settings. For example, the value 4010.155 is displayed as "4,010%".


OlFormatSmartFrom Enumeration (Outlook)

 Copy code hover
[image]

OlFormatSmartFrom Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display the From Outlook item property.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatSmartFromFromOnly | 2 | Display the value of the From Outlook item property. If no value is available, display an empty string.
olFormatSmartFromFromTo | 1 | Display the value of the From Outlook item property. If no value is available, display instead the value of the To Outlook item property.


OlFormatText Enumeration (Outlook)

 Copy code hover
[image]

OlFormatText Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display text Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatTextText | 1 | Display values as text.


OlFormatYesNo Enumeration (Outlook)

 Copy code hover
[image]

OlFormatYesNo Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format used to display yes/no Outlook item properties.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormatYesNoIcon | 4 | Displays a check box icon.
olFormatYesNoOnOff | 2 | Displays "On" or "Off".
olFormatYesNoTrueFalse | 3 | Displays "True" or "False".
olFormatYesNoYesNo | 1 | Displays "Yes" or "No".


OlFormRegionIcon Enumeration (Outlook)

 Copy code hover
[image]

OlFormRegionIcon Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Types of icons that Outlook can display for an item that uses a specified replacement form region.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormRegionIconDefault | 1 | The default icon for an item.
olFormRegionIconEncrypted | 9 | The icon to display when an item has been encrypted.
olFormRegionIconForwarded | 5 | The icon to display when an item has been forwarded.
olFormRegionIconPage | 11 | The icon to display in the ribbon for the replacement form region.
olFormRegionIconRead | 3 | The icon to display when an item has been read.
olFormRegionIconRecurring | 12 | The icon to display when an item is a recurring appointment, meeting, or task.
olFormRegionIconReplied | 4 | The icon to display when an item has been replied to.
olFormRegionIconSigned | 8 | The icon to display when an item has been signed with a digital signature.
olFormRegionIconSubmitted | 7 | The icon to display when an item has been sent.
olFormRegionIconUnread | 2 | The icon to display when an item has not been read.
olFormRegionIconUnsent | 6 | The icon to display when an item has not been sent.
olFormRegionIconWindow | 10 | The icon to display on the Inspector when an item has been opened.


OlFormRegionMode Enumeration (Outlook)

 Copy code hover
[image]

OlFormRegionMode Enumeration (Outlook)
Send feedback

Identifies the mode that the form region is being loaded into, which corresponds with the container displaying the form region.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormRegionCompose | 1 | The form region is in a compose page of a message or any unsendable item such as a contact item.
olFormRegionPreview | 2 | The form region is in the Reading Pane.
olFormRegionRead | 0 | The form region is in the read page of a received message or a post note.


OlFormRegionSize Enumeration (Outlook)

 Copy code hover
[image]

OlFormRegionSize Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Identifies the type of form region.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olFormRegionTypeAdjoining | 1 | The form region is an adjoining form region.
olFormRegionTypeSeparate | 0 | The form region is a separate form region. This includes a separate form region that is added to a standard form as a custom page, a separate form region that replaces the default page of a standard form, or a separate form region that replaces all pages in a standard form.


OlFormRegistry Enumeration (Outlook)

 Copy code hover
[image]

OlFormRegistry Enumeration (Outlook)
Send feedback

Indicates the form registry (library) where the Form is stored.

Name | Value | Description
olDefaultRegistry | 0 | The Form is registered in the user's default form registry.
olFolderRegistry | 3 | The Form is registered in a form registry specific to a particular folder, and can only be accessed from that folder.
olOrganizationRegistry | 4 | The Form is registered in the organizational form registry. The form is available to all users.
olPersonalRegistry | 2 | The Form is registered in the user's personal registry and is only accessible to that user.

Remarks

Used as a parameter to the FormDescription.PublishForm method to specify the form registry (library) in which to register the Form.


OlGender Enumeration (Outlook)

 Copy code hover
[image]

OlGender Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Constants representing gender.

Name | Value | Description
olFemale | 1 | Female
olMale | 2 | Male
olUnspecified | 0 | Unspecified gender

Remarks

Used by the ContactItem.Gender property.


OlGridLineStyle Enumeration (Outlook)

 Copy code hover
[image]

OlGridLineStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the line style used to display grid lines for TableView objects.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olGridLineDashes | 3 | Dashed lines are used to draw the grid.
olGridLineLargeDots | 2 | Lines using large dots are used to draw the grid.
olGridLineNone | 0 | No lines are displayed.
olGridLineSmallDots | 1 | Lines using small dots are used to draw the grid.
olGridLineSolid | 4 | Solid lines are used to draw the grid.


OlGroupType Enumeration (Outlook)

 Copy code hover
[image]

OlGroupType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Identifies the group type of a NavigationGroup object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olCustomFoldersGroup | 0 | Identifies a user-defined navigation group, added using either the Outlook user interface or an add-in.
olFavoriteFoldersGroup | 4 | Identifies the Favorite Folders navigation group. This navigation group exists only within the NavigationGroups collection of a MailModule object and cannot be created in or accessed from other modules.
olMyFoldersGroup | 1 | Identifies a navigation group that, by default, contains any folders that are part of the local store.
olOtherFoldersGroup | 3 | Identifies a navigation group that, by default, contains shared folders from sources other than that of other persons.
olPeopleFoldersGroup | 2 | Identifies a navigation group that, by default, contains shared folders from other persons.
olReadOnlyGroup | 6 | Identifies a navigation group that is, by default, read-only and no folders can be added or removed from that navigation group. This does not imply the folders themselves are read-only, and write access to the folders depends on how the folders are set up.
olRoomsGroup | 5 | Identifies the Rooms navigation group in the Calendar navigation module.


OlHorizontalLayout Enumeration (Outlook)

 Copy code hover
[image]

OlHorizontalLayout Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the alignment of controls in the horizontal direction.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olHorizontalLayoutAlignCenter | 1 | Align controls horizontally by the center of each control.
olHorizontalLayoutGrow | 3 | Resize control horizontally with the form.
olHorizontalLayoutAlignLeft | 0 | Align controls horizontally by the left edge of each control.
olHorizontalLayoutAlignRight | 2 | Align controls horizontally by the right edge of each control.


OlIconViewPlacement Enumeration (Outlook)

 Copy code hover
[image]

OlIconViewPlacement Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates how icons are arranged in an IconView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olIconAutoArrange | 2 | Icons are automatically lined up and arranged to prevent gaps or overlaps, but are not sorted.
olIconDoNotArrange | 0 | Icons are not automatically sorted, lined up, or arranged.
olIconLineUp | 1 | Icons are automatically lined up, but are not sorted or arranged.
olIconSortAndAutoArrange | 3 | Icons are automatically sorted, lined up, and arranged to prevent gaps or overlaps.


OlIconViewType Enumeration (Outlook)

 Copy code hover
[image]

OlIconViewType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the view mode when using an IconView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olIconViewLarge | 0 | Displays Outlook items as large icons, with the description for the Outlook item below the icon.
olIconViewList | 2 | Displays Outlook items as a list of small icons, with the description for the Outlook item next to the icon.
olIconViewSmall | 1 | Displays Outlook items as a collection of small icons, with the description for the Outlook item next to the icon.

Remarks

For olIconViewLarge and olIconViewSmall, the actual placement and orientation of icons displayed in the IconView object is determined by the OlIconViewPlacement constant specified in the IconPlacement property of the IconView object. The IconPlacement property value is ignored when olIconViewList is selected.


OlImportance Enumeration (Outlook)

 Copy code hover
[image]

OlImportance Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the level of importance for an item marked by the creator of the item.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olImportanceHigh | 2 | Item is marked as high importance.
olImportanceLow | 0 | Item is marked as low importance.
olImportanceNormal | 1 | Item is marked as medium importance.


OlInspectorClose Enumeration (Outlook)

 Copy code hover
[image]

OlInspectorClose Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the save mode.

Name | Value | Description
olDiscard | 1 | Changes to the document are discarded.
olPromptForSave | 2 | User is prompted to save documents.
olSave | 0 | Documents are saved.

Remarks

Used as a parameter to the Close method of item objects and the Inspector.Close Method (Outlook) to indicate the save mode.


OlItemType Enumeration (Outlook)

 Copy code hover
[image]

OlItemType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the Outlook item type.

Name | Value | Description
olAppointmentItem | 1 | An AppointmentItem object.
olContactItem | 2 | A ContactItem object.
olDistributionListItem | 7 | A DistListItem object.
olJournalItem | 4 | A JournalItem object.
olMailItem | 0 | A MailItem object.
olNoteItem | 5 | A NoteItem object.
olPostItem | 6 | A PostItem object.
olTaskItem | 3 | A TaskItem object.


OlJournalRecipientType Enumeration (Outlook)

 Copy code hover
[image]

OlJournalRecipientType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the recipient type for Journal items.

Name | Value | Description
olAssociatedContact | 1 | The Contact associated with the Journal item.


OlMailingAddress Enumeration (Outlook)

 Copy code hover
[image]

OlMailingAddress Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the address to use as the mailing address.

Name | Value | Description
olBusiness | 2 | Business mailing address
olHome | 1 | Home mailing address
olNone | 0 | No mailing address defined
olOther | 3 | Other mailing address

Remarks

See ContactItem.SelectedMailingAddress Property (Outlook).


OlMailRecipientType Enumeration (Outlook)

 Copy code hover
[image]

OlMailRecipientType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the recipient type for the Item.

Name | Value | Description
olBCC | 3 | The recipient is specified in the BCC property of the Item.
olCC | 2 | The recipient is specified in the CC property of the Item.
olOriginator | 0 | Originator (sender) of the Item.
olTo | 1 | The recipient is specified in the To property of the Item.

Remarks

Used by the Recipient.Type Property (Outlook) of an Item.


OlMarkInterval Enumeration (Outlook)

 Copy code hover
[image]

OlMarkInterval Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the time period for which an Outlook item is marked as a task.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olMarkComplete | 5 | Mark the task as complete.
olMarkNextWeek | 3 | Mark the task due next week.
olMarkNoDate | 4 | Mark the task due with no date.
olMarkThisWeek | 2 | Mark the task due this week.
olMarkToday | 0 | Mark the task due today.
olMarkTomorrow | 1 | Mark the task due tomorrow.

Remarks

This enumeration is used by the MarkAsTask method for the following Outlook items:

  • ContactItem

  • DistListItem

  • MailItem

  • PostItem

  • SharingItem

Depending on the value chosen, the following properties are set to the specified default values.

Enumeration values

Property values

olMarkComplete

TaskCompletedDate is set to the current date and time (Now in Visual Basic) if the item has been marked as a task.

TaskCompletedDate is set to the empty date value (#1/1/4501#) if the item has not been marked as a task, or if the task has already been marked complete.

olMarkNextWeek

IsMarkedAsTask is set to True.

TaskSubject is set to the value of the Subject property for the Outlook item.

TaskStartDate is set to the first working day of next week.

TaskDueDate is set to the last working day of next week.

TaskCompletedDate is set to the empty date value (#1/1/4501#).

ToDoTaskOrdinal is set to the current date and time (Now in Visual Basic).

olMarkNoDate

IsMarkedAsTask is set to True.

TaskSubject is set to the value of the Subject property for the Outlook item.

TaskStartDate, TaskDueDate, and TaskCompletedDate are set to Null (Nothing in Visual Basic).

ToDoTaskOrdinal is set to the current date and time (Now in Visual Basic).

olMarkThisWeek

IsMarkedAsTask is set to True.

TaskSubject is set to the value of the Subject property for the Outlook item.

TaskStartDate is set to a date two working days ahead of the current date. If that value would exceed the value of TaskDueDate, then TaskStartDate is set to the value of TaskDueDate.

TaskDueDate is set to the last working day of the current week.

TaskCompletedDate is set to the empty date value (#1/1/4501#).

ToDoTaskOrdinal is set to the current date and time (Now in Visual Basic).

olMarkToday

IsMarkedAsTask is set to True.

TaskSubject is set to the value of the Subject property for the Outlook item.

TaskStartDate and TaskDueDate are set to the current date.

TaskCompletedDate is set to the empty date value (#1/1/4501#).

ToDoTaskOrdinal is set to the current date and time (Now in Visual Basic).

olMarkTomorrow

IsMarkedAsTask is set to True.

TaskSubject is set to the value of the Subject property for the Outlook item.

TaskStartDate and TaskDueDate are set to one day after the current date.

TaskCompletedDate is set to the empty date value (#1/1/4501#).

ToDoTaskOrdinal is set to the current date and time (Now in Visual Basic).


OlMatchEntry Enumeration (Outlook)

 Copy code hover
[image]

OlMatchEntry Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies if and how extensive entry matching is applied while the user types in a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olMatchEntryComplete | 1 | Extended matching. As each character is typed, the control searches for an entry matching all characters entered.
olMatchEntryFirstLetter | 0 | Basic matching: The control searches for the next entry that starts with the character entered. Repeatedly typing the same letter cycles through all entries beginning with that letter.
olMatchEntryNone | 2 | No matching is performed.


OlMeetingRecipientType Enumeration (Outlook)

 Copy code hover
[image]

OlMeetingRecipientType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the recipient type for the meeting.

Name | Value | Description
olOptional | 2 | Optional attendee
olOrganizer | 0 | Meeting organizer
olRequired | 1 | Required attendee
olResource | 3 | A resource such as a conference room


OlMeetingResponse Enumeration (Outlook)

 Copy code hover
[image]

OlMeetingResponse Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the response to a meeting request.

Name | Value | Description
olMeetingAccepted | 3 | The meeting was accepted.
olMeetingDeclined | 4 | The meeting was declined.
olMeetingTentative | 2 | The meeting was tentatively accepted.

Remarks

See MeetingItem Object (Outlook).


OlMeetingStatus Enumeration (Outlook)

 Copy code hover
[image]

OlMeetingStatus Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the status of the meeting.

Name | Value | Description
olMeeting | 1 | The meeting has been scheduled.
olMeetingCanceled | 5 | The scheduled meeting has been cancelled.
olMeetingReceived | 3 | The meeting request has been received.
olMeetingReceivedAndCanceled | 7 | The scheduled meeting has been cancelled but still appears on the user's calendar.
olNonMeeting | 0 | An Appointment item without attendees has been scheduled. This status can be used to set up holidays on a calendar.

Remarks

See AppointmentItem.MeetingStatus Property (Outlook).


OlMobileFormat Enumeration (Outlook)69204f52-46a2-455c-1903-e63e7b5cd690

 Copy code hover
[image]

OlMobileFormat Enumeration (Outlook)69204f52-46a2-455c-1903-e63e7b5cd690
Send feedback

Members

Name | Value | Description
olMMS | 1 |
olSMS | 0 |


OlMouseButton Enumeration (Outlook)

 Copy code hover
[image]

OlMouseButton Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates which mouse button is pressed during a mouse event.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olMouseButtonLeft | 1 | Indicates that the primary (left) button on a mouse is pressed during the event.
olMouseButtonRight | 2 | Indicates that the secondary (right) button on a mouse is pressed during the event.
olMouseButtonMiddle | 4 | Indicates that the middle button on a mouse is pressed during the event.


OlMousePointer Enumeration (Outlook)

 Copy code hover
[image]

OlMousePointer Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the mouse cursor that is displayed while the mouse is positioned over a control and a drag/drop operation is not being performed.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olMousePointerAppStarting | 13 | The cursor is the arrow and the hourglass, representing that the application is starting.
olMousePointerArrow | 1 | The cursor is the standard arrow.
olMousePointerCross | 2 | The cursor is the cross.
olMousePointerCustom | 99 | The cursor is represented by the custom cursor bitmap.
olMousePointerDefault | 0 | The default cursor.
olMousePointerHelp | 14 | The cursor is the What's This help cursor.
olMousePointerHourGlass | 11 | The cursor is the hourglass, representing that the application is busy.
olMousePointerIBeam | 3 | The cursor is the I-beam text entry cursor.
olMousePointerNoDrop | 12 | The cursor is the no-drop cursor.
olMousePointerSizeAll | 15 | Resize cursor in all directions.
olMousePointerSizeNESW | 6 | Resize cursor from Northeast to Southwest.
olMousePointerSizeNS | 7 | Resize cursor from North to South.
olMousePointerSizeNWSE | 8 | Resize cursor from Northwest to Southeast.
olMousePointerSizeWE | 9 | Resize cursor from West to East.
olMousePointerUpArrow | 10 | The cursor is the vertical arrow.


OlMultiLine Enumeration (Outlook)

 Copy code hover
[image]

OlMultiLine Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates when multiple lines are displayed in a TableView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olAlwaysMultiLine | 2 | Multiple lines are always displayed.
olAlwaysSingleLine | 1 | Single lines are always displayed.
olWidthMultiLine | 0 | Single lines are displayed unless the length of the line, in characters, is greater than the value for the MultiLineWidth property of the TableView object, at which point multiple lines are displayed.


OlMultiSelect Enumeration (Outlook)

 Copy code hover
[image]

OlMultiSelect Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of selection that is supported in a list box control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olMultiSelectExtended | 2 | Supports SHIFT and CTRL to select one or more items at a time. Pressing SHIFT and clicking the mouse, or pressing SHIFT and one of the arrow keys, extends the selection from the previously selected item to the current item. Pressing CTRL and clicking the mouse toggles the selection of an item.
olMultiSelectMulti | 1 | Supports selection of one or more items at a time. Pressing SPACEBAR or clicking the mouse toggles the selection of an item in the list.
olMultiSelectSingle | 0 | Supports selection of only one item at a time.


OlNavigationModuleType Enumeration (Outlook)

 Copy code hover
[image]

OlNavigationModuleType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Identifies the navigation module type of a NavigationModule object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olModuleCalendar | 1 | A CalendarModule object that represents the Calendar navigation module.
olModuleContacts | 2 | A ContactsModule object that represents the Contacts navigation module.
olModuleFolderList | 6 | A NavigationModule object that represents the Folders List navigation module.
olModuleJournal | 4 | A JournalModule object that represents the Journal navigation module.
olModuleMail | 0 | A MailModule object that represents the Mail navigation module.
olModuleNotes | 5 | A NotesModule object that represents the Notes navigation module.
olModuleShortcuts | 7 | A NavigationModule object that represents the Shortcuts navigation module.
olModuleSolutions | 8 | A SolutionsModule object that represents the Solutions navigation module.
olModuleTasks | 3 | A TasksModule object that represents the Tasks navigation module.

Remarks

This enumeration is used by the NavigationModule.NavigationModuleType Property (Outlook) for the following objects to identify the type of navigation module:

  1. CalendarModule

  2. ContactsModule

  3. JournalModule

  4. MailModule

  5. Module

  6. NotesModule

  7. SolutionsModule

  8. TasksModule

The enumeration is also used by the NavigationModules.GetNavigationModule Method (Outlook) to identify the navigation module type of the NavigationModule to retrieve.


OlNetMeetingType Enumeration (Outlook)

 Copy code hover
[image]

OlNetMeetingType Enumeration (Outlook)
Send feedback

Members

Name | Value | Description
olExchangeConferencing | 2 |
olNetMeeting | 0 |
olNetShow | 1 |


OlNoteColor Enumeration (Outlook)

 Copy code hover
[image]

OlNoteColor Enumeration (Outlook)
Send feedback

Members

Name | Value | Description
olBlue | 0 |
olGreen | 1 |
olPink | 2 |
olWhite | 4 |
olYellow | 3 |


OlObjectClass Enumeration (Outlook)

 Copy code hover
[image]

OlObjectClass Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies constants that represent the different Microsoft Outlook object classes.

Name | Value | Description
olAccount | 105 | An Account object.
olAccountRuleCondition | 135 | An AccountRuleCondition object.
olAccounts | 106 | An Accounts object.
olAction | 32 | An Action object.
olActions | 33 | An Actions object.
olAddressEntries | 21 | An AddressEntries object.
olAddressEntry | 8 | An AddressEntry object.
olAddressList | 7 | An AddressList object.
olAddressLists | 20 | An AddressLists object.
olAddressRuleCondition | 170 | An AddressRuleCondition object.
olApplication | 0 | An Application object.
olAppointment | 26 | An AppointmentItem object.
olAssignToCategoryRuleAction | 122 | An AssignToCategoryRuleAction object.
olAttachment | 5 | An Attachment object.
olAttachments | 18 | An Attachments object.
olAttachmentSelection | 169 | An AttachmentSelection object.
olAutoFormatRule | 147 | An AutoFormatRule object.
olAutoFormatRules | 148 | An AutoFormatRules object.
olCalendarModule | 159 | A CalendarModule object.
olCalendarSharing | 151 | A CalendarSharing object.
olCategories | 153 | A Categories object.
olCategory | 152 | A Category object.
olCategoryRuleCondition | 130 | A CategoryRuleCondition object.
olClassBusinessCardView | 168 | A BusinessCardView object.
olClassCalendarView | 139 | A CalendarView object.
olClassCardView | 138 | A CardView object.
olClassIconView | 137 | An IconView object.
olClassNavigationPane | 155 | A NavigationPane object.
olClassPeopleView | 183 | A PeopleView object.
olClassTableView | 136 | A TableView object.
olClassTimeLineView | 140 | A TimelineView object.
olClassTimeZone | 174 | A TimeZone object.
olClassTimeZones | 175 | A TimeZones object.
olColumn | 154 | A Column object.
olColumnFormat | 149 | A ColumnFormat object.
olColumns | 150 | A Columns object.
olConflict | 102 | A Conflict object.
olConflicts | 103 | A Conflicts object.
olContact | 40 | A ContactItem object.
olContactsModule | 160 | A ContactsModule object.
olConversation | 178 | A Conversation object.
olConversationHeader | 182 | A ConversationHeader object.
olDistributionList | 69 | An ExchangeDistributionList object.
olDocument | 41 | A DocumentItem object.
olException | 30 | An Exception object.
olExceptions | 29 | An Exceptions object.
olExchangeDistributionList | 111 | An ExchangeDistributionList object.
olExchangeUser | 110 | An ExchangeUser object.
olExplorer | 34 | An Explorer object.
olExplorers | 60 | An Explorers object.
olFolder | 2 | A Folder object.
olFolders | 15 | A Folders object.
olFolderUserProperties | 172 | A UserDefinedProperties object.
olFolderUserProperty | 171 | A UserDefinedProperty object.
olFormDescription | 37 | A FormDescription object.
olFormNameRuleCondition | 131 | A FormNameRuleCondition object.
olFormRegion | 129 | A FormRegion object.
olFromRssFeedRuleCondition | 173 | A FromRssFeedRuleCondition object.
olFromRuleCondition | 132 | A ToOrFromRuleCondition object.
olImportanceRuleCondition | 128 | An ImportanceRuleCondition object.
olInspector | 35 | An Inspector object.
olInspectors | 61 | An Inspectors object.
olItemProperties | 98 | An ItemProperties object.
olItemProperty | 99 | An ItemProperty object.
olItems | 16 | An Items object.
olJournal | 42 | A JournalItem object.
olJournalModule | 162 | A JournalModule object.
olMail | 43 | A MailItem object.
olMailModule | 158 | A MailModule object.
olMarkAsTaskRuleAction | 124 | A MarkAsTaskRuleAction object.
olMeetingCancellation | 54 | A MeetingItem object that is a meeting cancellation notice.
olMeetingForwardNotification | 181 | A MeetingItem object that is a notice about forwarding the meeting request.
olMeetingRequest | 53 | A MeetingItem object that is a meeting request.
olMeetingResponseNegative | 55 | A MeetingItem object that is a refusal of a meeting request.
olMeetingResponsePositive | 56 | A MeetingItem object that is an acceptance of a meeting request.
olMeetingResponseTentative | 57 | A MeetingItem object that is a tentative acceptance of a meeting request.
olMoveOrCopyRuleAction | 118 | A MoveOrCopyRuleAction object.
olNamespace | 1 | A NameSpace object.
olNavigationFolder | 167 | A NavigationFolder object.
olNavigationFolders | 166 | A NavigationFolders object.
olNavigationGroup | 165 | A NavigationGroup object.
olNavigationGroups | 164 | A NavigationGroups object.
olNavigationModule | 157 | A NavigationModule object.
olNavigationModules | 156 | A NavigationModules object.
olNewItemAlertRuleAction | 125 | A NewItemAlertRuleAction object.
olNote | 44 | A NoteItem object.
olNotesModule | 163 | A NotesModule object.
olOrderField | 144 | An OrderField object.
olOrderFields | 145 | An OrderFields object.
olOutlookBarGroup | 66 | An OutlookBarGroup object.
olOutlookBarGroups | 65 | An OutlookBarGroups object.
olOutlookBarPane | 63 | An OutlookBarPane object.
olOutlookBarShortcut | 68 | An OutlookBarShortcut object.
olOutlookBarShortcuts | 67 | An OutlookBarShortcuts object.
olOutlookBarStorage | 64 | An OutlookBarStorage object.
olOutspace | 180 | An AccountSelector object.
olPages | 36 | A Pages object.
olPanes | 62 | A Panes object.
olPlaySoundRuleAction | 123 | A PlaySoundRuleAction object.
olPost | 45 | A PostItem object.
olPropertyAccessor | 112 | A PropertyAccessor object.
olPropertyPages | 71 | A PropertyPages object.
olPropertyPageSite | 70 | A PropertyPageSite object.
olRecipient | 4 | A Recipient object.
olRecipients | 17 | A Recipients object.
olRecurrencePattern | 28 | A RecurrencePattern object.
olReminder | 101 | A Reminder object.
olReminders | 100 | A Reminders object.
olRemote | 47 | A RemoteItem object.
olReport | 46 | A ReportItem object.
olResults | 78 | A Results object.
olRow | 121 | A Row object.
olRule | 115 | A Rule object.
olRuleAction | 117 | A RuleAction object.
olRuleActions | 116 | A RuleActions object.
olRuleCondition | 127 | A RuleCondition object.
olRuleConditions | 126 | A RuleConditions object.
olRules | 114 | A Rules object.
olSearch | 77 | A Search object.
olSelection | 74 | A Selection object.
olSelectNamesDialog | 109 | A SelectNamesDialog object.
olSenderInAddressListRuleCondition | 133 | A SenderInAddressListRuleCondition object.
olSendRuleAction | 119 | A SendRuleAction object.
olSharing | 104 | A SharingItem object.
olSimpleItems | 179 | A SimpleItems object.
olSolutionsModule | 177 | A SolutionsModule object.
olStorageItem | 113 | A StorageItem object.
olStore | 107 | A Store object.
olStores | 108 | A Stores object.
olSyncObject | 72 | A SyncObject object.
olSyncObjects | 73 | A SyncObjects object.
olTable | 120 | A Table object.
olTask | 48 | A TaskItem object.
olTaskRequest | 49 | A TaskRequestItem object.
olTaskRequestAccept | 51 | A TaskRequestAcceptItem object.
olTaskRequestDecline | 52 | A TaskRequestDeclineItem object.
olTaskRequestUpdate | 50 | A TaskRequestUpdateItem object.
olTasksModule | 161 | A TasksModule object.
olTextRuleCondition | 134 | A TextRuleCondition object.
olUserDefinedProperties | 172 | A UserDefinedProperties object.
olUserDefinedProperty | 171 | A UserDefinedProperty object.
olUserProperties | 38 | A UserProperties object.
olUserProperty | 39 | A UserProperty object.
olView | 80 | A View object.
olViewField | 142 | A ViewField object.
olViewFields | 141 | A ViewFields object.
olViewFont | 146 | A ViewFont object.
olViews | 79 | A Views object.

Remarks

This enumeration is used by the Class property of Outlook objects.


OlOutlookBarViewType Enumeration (Outlook)

 Copy code hover
[image]

OlOutlookBarViewType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of view that is displayed by an OutlookBarGroup object.

Name | Value | Description
olLargeIcon | 0 | The Outlook Bar group displays large icons.
olSmallIcon | 1 | The Outlook Bar group displays small icons.

Remarks

Used by the ViewType property of the OutlookBarGroup object.


OlPageType Enumeration (Outlook)

 Copy code hover
[image]

OlPageType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of page displayed by a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olPageTypePlanner | 0 | The free/busy scheduling grid from a meeting request form.
olPageTypeTracker | 1 | The tracking grid from a meeting request that has been sent.


OlPane Enumeration (Outlook)

 Copy code hover
[image]

OlPane Enumeration (Outlook)
Send feedback

Specifies the pane (window).

Name | Value | Description
olFolderList | 2 | The folder list pane
olNavigationPane | 4 | The navigation pane
olOutlookBar | 1 | The Outlook bar pane
olPreview | 3 | The Preview pane


OlPermission Enumeration (Outlook)

 Copy code hover
[image]

OlPermission Enumeration (Outlook)
Send feedback

Indicates the permission restrictions on an Item.

Name | Value | Description
olDoNotForward | 1 | Item cannot be forwarded.
olPermissionTemplate | 2 | Outlook will use an Information Rights Management (IRM) template to determine the access and usage permissions for the item. See MailItem.PermissionService and SharingItem.PermissionService properties.
olUnrestricted | 0 | Item has no permission restrictions.

Remarks

Used by the SharingItem.Permission Property (Outlook) and MailItem.Permission Property (Outlook) to specify the permissions that the recipients will have on the item.


OlPermissionService Enumeration (Outlook)

 Copy code hover
[image]

OlPermissionService Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the permission service used when sending an Information Rights Management (IRM) protected MailItem object.

Name | Value | Description
olPassport | 2 | Microsoft Passport Network permissions will be used.
olUnknown | 0 | Permission service is unknown.
olWindows | 1 | Microsoft Windows permissions will be used.

Remarks

See SharingItem.PermissionService Property (Outlook) and MailItem.PermissionService Property (Outlook).


OlPictureAlignment Enumeration (Outlook)

 Copy code hover
[image]

OlPictureAlignment Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how an image is aligned with respect to text on a button.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olPictureAlignmentLeft | 0 | The image is aligned to the left of the text and vertically centered on the button.
olPictureAlignmentTop | 1 | The image is aligned to the right of the text and horizontally centered on the button.

Remarks

In bidirectional text, olPictureAlignmentLeft specifies that the image should be aligned to the right of the text and vertically centered on the button.


OlRecipientSelectors Enumeration (Outlook)

 Copy code hover
[image]

OlRecipientSelectors Enumeration (Outlook)
Send feedback

Specifies the edit boxes (for To, Cc, Bcc), if any, to be displayed in the Select Names dialog box.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olShowNone | 0 | No edit box will be displayed.
olShowTo | 1 | Only an edit box for To recipients will be displayed.
olShowToCc | 2 | Only edit boxes for To and Cc recipients will be displayed.
olShowToCcBcc | 3 | Edit boxes for To, Cc, and Bcc recipients will be displayed.


OlRecurrenceState Enumeration (Outlook)

 Copy code hover
[image]

OlRecurrenceState Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the recurrence state of an AppointmentItem.

Name | Value | Description
olApptException | 3 | The appointment is an exception to a recurrence pattern defined by a master appointment.
olApptMaster | 1 | The appointment is a master appointment.
olApptNotRecurring | 0 | The appointment is not a recurring appointment.
olApptOccurrence | 2 | The appointment is an occurrence of a recurring appointment defined by a master appointment.

Remarks

See AppointmentItem.RecurrenceState Property (Outlook).


OlRecurrenceType Enumeration (Outlook)

 Copy code hover
[image]

OlRecurrenceType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the recurrence pattern type.

Name | Value | Description
olRecursDaily | 0 | Represents a daily recurrence pattern.
olRecursMonthly | 2 | Represents a monthly recurrence pattern.
olRecursMonthNth | 3 | Represents a MonthNth recurrence pattern. See RecurrencePattern.Instance property.
olRecursWeekly | 1 | Represents a weekly recurrence pattern.
olRecursYearly | 5 | Represents a yearly recurrence pattern.
olRecursYearNth | 6 | Represents a YearNth recurrence pattern. See RecurrencePattern.Instance property.

Remarks

Used by the RecurrencePattern.RecurrenceType Property (Outlook) of an AppointmentItem Object (Outlook) to specify the frequency of occurrences of the appointment.


OlReferenceType Enumeration (Outlook)

 Copy code hover
[image]

OlReferenceType Enumeration (Outlook)
Send feedback

Indicates the reference type.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olStrong | 1 | Strong reference
olWeak | 0 | Weak reference

Remarks

Used as a parameter to the Application.GetObjectReference Method (Outlook).


OlRemoteStatus Enumeration (Outlook)

 Copy code hover
[image]

OlRemoteStatus Enumeration (Outlook)
Send feedback

Indicates the status of an item after it is received by a remote user.

Name | Value | Description
olMarkedForCopy | 3 | Item is marked to be copied.
olMarkedForDelete | 4 | Item is marked for deletion.
olMarkedForDownload | 2 | Item is marked for download.
olRemoteStatusNone | 0 | No remote status has been set.
olUnMarked | 1 | Item is not marked.

Remarks

See MarkForDownLoad property.


OlResponseStatus Enumeration (Outlook)

 Copy code hover
[image]

OlResponseStatus Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the response to a meeting request.

Name | Value | Description
olResponseAccepted | 3 | Meeting accepted.
olResponseDeclined | 4 | Meeting declined.
olResponseNone | 0 | The appointment is a simple appointment and does not require a response.
olResponseNotResponded | 5 | Recipient has not responded.
olResponseOrganized | 1 | The AppointmentItem is on the Organizer's calendar or the recipient is the Organizer of the meeting.
olResponseTentative | 2 | Meeting tentatively accepted.

Remarks

Used by Recipient.MeetingResponseStatus Property (Outlook) and AppointmentItem.ResponseStatus Property (Outlook).


OlRuleActionType Enumeration (Outlook)

 Copy code hover
[image]

OlRuleActionType Enumeration (Outlook)
Send feedback

Specifies the type of rule action for a rule.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olRuleActionAssignToCategory | 2 | Rule action is to assign categories to the message.
olRuleActionCcMessage | 27 | Rule action is to cc the message to specified recipients.
olRuleActionClearCategories | 30 | Rule action is to clear all the categories assigned to the message.
olRuleActionCopyToFolder | 5 | Rule action is to copy the message to a specified folder.
olRuleActionCustomAction | 22 | Rule action is to perform a custom action.
olRuleActionDefer | 28 | Rule action is to defer delivery of the message by the specified number of minutes.
olRuleActionDelete | 3 | Rule action is to delete the message.
olRuleActionDeletePermanently | 4 | Rule action is to permanently delete the message.
olRuleActionDesktopAlert | 24 | Rule action is to display a desktop alert.
olRuleActionFlagClear | 13 | Rule action is to clear the message flag.
olRuleActionFlagColor | 12 | Rule action is to flag the message with a specified colored flag.
olRuleActionFlagForActionInDays | 11 | Rule action is to flag the message for action in the specified number of days.
olRuleActionForward | 6 | Rule action is to forward the message to the specified recipients.
olRuleActionForwardAsAttachment | 7 | Rule action is to forward the message as an attachment to the specified recipients.
olRuleActionImportance | 14 | Rule action is to mark the message with the specified level of importance.
olRuleActionMarkAsTask | 41 | Rule action is to mark the message as a task.
olRuleActionMarkRead | 19 | Rule action is to mark the message as read.
olRuleActionMoveToFolder | 1 | Rule action is to move the message to the specified folder.
olRuleActionNewItemAlert | 23 | Rule action is to display the specified text in the New Item Alert dialog box.
olRuleActionNotifyDelivery | 26 | Rule action is to request delivery notification for the message being sent.
olRuleActionNotifyRead | 25 | Rule action is to request read notification for the message being sent.
olRuleActionPlaySound | 17 | Rule action is to play a sound file.
olRuleActionPrint | 16 | Rule action is to print the message on the default printer.
olRuleActionRedirect | 8 | Rule action is to redirect the message to the specified recipients.
olRuleActionRunScript | 20 | Rule action is to run a script.
olRuleActionSensitivity | 15 | Rule action is to mark the message with the specified level of sensitivity.
olRuleActionServerReply | 9 | Rule action is to request the server to reply with the specified mail item.
olRuleActionStartApplication | 18 | Rule action is to run an .exe file.
olRuleActionStop | 21 | Rule action is to stop processing more rules.
olRuleActionTemplate | 10 | Rule action is to use the specified template (.oft) file as a form template.
olRuleActionUnknown | 0 | Unrecognized rule action.

Remarks

The list of rule action types in this enumeration includes all the rule actions that the Rules and Alerts Wizard supports. Note that while you can programmatically enumerate all the rule actions for a rule, you can programmatically create a rule with only the most commonly used rule actions. For more information, see Specifying Rule Actions.


OlRuleConditionType Enumeration (Outlook)

 Copy code hover
[image]

OlRuleConditionType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of rule condition or exception condition of a rule.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olConditionAccount | 3 | Account is the account specified in AccountRuleCondition.Account.
olConditionAnyCategory | 29 | Message is assigned to any category.
olConditionBody | 13 | Body contains words specified in TextRuleCondition.Text.
olConditionBodyOrSubject | 14 | Body or subject contains words specified by TextRuleCondition.Text.
olConditionCategory | 18 | Category is the category specified in CategoryRuleCondition.Categories.
olConditionCc | 9 | Message has my name in the Cc box.
olConditionDateRange | 22 | Message was received between x and y, where x and y are Date values.
olConditionFlaggedForAction | 8 | Message is flagged for the specified action.
olConditionFormName | 23 | Message uses the form specified in FormNameRuleCondition.FormName.
olConditionFrom | 1 | Sender is in the recipient list specified in ToOrFromRuleCondition.Recipients.
olConditionFromAnyRssFeed | 31 | Message is generated from any RSS subscription.
olConditionFromRssFeed | 30 | Message is generated from a specific RSS subscription.
olConditionHasAttachment | 20 | Message has one or more attachments.
olConditionImportance | 6 | Message is marked with the specified level of importance.
olConditionLocalMachineOnly | 27 | Rule can run only on the local machine.
olConditionMeetingInviteOrUpdate | 26 | Message is a meeting invitation or update.
olConditionMessageHeader | 15 | Message header contains words specified in TextRuleCondition.Text.
olConditionNotTo | 11 | Message does not have my name in the To box.
olConditionOnlyToMe | 4 | Message is sent only to me.
olConditionOOF | 19 | Message is an out-of-office message.
olConditionOtherMachine | 28 | Rule can run only on a specific machine that is not the current machine.
olConditionProperty | 24 | Document property is exactly, contains, or does not contain specified properties.
olConditionRecipientAddress | 16 | Recipient address contains words specified in TextRuleCondition.Text.
olConditionSenderAddress | 17 | Sender address contains words specified in TextRuleCondition.Text.
olConditionSenderInAddressBook | 25 | Sender is in the address list specified in AddressRuleCondition.Address.
olConditionSensitivity | 7 | Message is marked with the specified level of sensitivity.
olConditionSentTo | 12 | Sent to recipients (To, Cc) are in the recipient list specified in ToOrFromRuleCondition.Recipients.
olConditionSizeRange | 21 | Message size is between x and y in units of KB, where x and y are Integer values.
olConditionSubject | 2 | Subject contains words specified in TextRuleCondition.Text.
olConditionTo | 5 | My name is in the To box.
olConditionToOrCc | 10 | Message has my name in the To or Cc box.
olConditionUnknown | 0 | Unrecognized condition.

Remarks

The list of rule condition types in this enumeration includes all the rule conditions and exception conditions that the Rules and Alerts Wizard supports. Note that while you can programmatically enumerate all the rule conditions and exception conditions for a rule, you can programmatically create a rule with only the most commonly used conditions. For more information, see Specifying Rule Conditions.

For example, the rule condition types olConditionDateRange and olConditionSizeRange are supported only for enumeration and enabling or disabling in an existing rule. You cannot programmatically create a rule with such conditions. You cannot programmatically get or set the values of x and y that represent the range.


OlRuleExecuteOption Enumeration (Outlook)

 Copy code hover
[image]

OlRuleExecuteOption Enumeration (Outlook)
Send feedback

Specifies the type of messages in the specified folder or folders that a rule should be applied to.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olRuleExecuteAllMessages | 0 | Executes a rule against all messages in the specified folder or folders.
olRuleExecuteReadMessages | 1 | Executes a rule against messages that have been read in the specified folder or folders.
olRuleExecuteUnreadMessages | 2 | Executes a rule against messages that have not been read in the specified folder or folders.


OlRuleType Enumeration (Outlook)

 Copy code hover
[image]

OlRuleType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates if a rule is applied to messages that are being sent or received.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olRuleReceive | 0 | Indicates that the rule is applied to messages that are being received.
olRuleSend | 1 | Indicates that the rule is being applied to messages being sent.


OlSaveAsType Enumeration (Outlook)

 Copy code hover
[image]

OlSaveAsType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the file format.

Name | Value | Description
olDoc | 4 | Microsoft Office Word format (.doc)
olHTML | 5 | HTML format (.html)
olICal | 8 | iCal format (.ics)
olMHTML | 10 | MIME HTML format (.mht)
olMSG | 3 | Outlook message format (.msg)
olMSGUnicode | 9 | Outlook Unicode message format (.msg)
olRTF | 1 | Rich Text format (.rtf)
olTemplate | 2 | Microsoft Outlook template (.oft)
olTXT | 0 | Text format (.txt)
olVCal | 7 | VCal format (.vcs)
olVCard | 6 | VCard format (.vcf)

Remarks

Used as an optional parameter to the SaveAs method for Outlook items.


OlScrollBars Enumeration (Outlook)

 Copy code hover
[image]

OlScrollBars Enumeration (Outlook)
Send feedback

Specifies which, if any, scroll bars to display for a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olScrollBarsBoth | 3 | Display both the horizontal and vertical scroll bars as necessary.
olScrollBarsHorizontal | 1 | Display a horizontal scroll bar only.
olScrollBarsNone | 0 | Display no scroll bars.
olScrollBarsVertical | 2 | Display a vertical scroll bar only.


OlSearchScope Enumeration (Outlook)

 Copy code hover
[image]

OlSearchScope Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the scope in terms of folders for the search.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olSearchScopeAllFolders | 1 | The search scope is across all folders that have the same folder type as the current folder (Folder.DefaultItemType), and all stores that have been selected for search.
olSearchScopeAllOutlookItems | 2 | The search scope is all Outlook items in all folders in stores that have been selected for search.
olSearchScopeCurrentFolder | 0 | The search scope is the folder represented by Explorer.CurrentFolder, and only that folder.
olSearchScopeCurrentStore | 4 | The search scope is the store for the current folder, which contains the item displayed in the active explorer.
olSearchScopeSubfolders | 3 | The search scope is the folder represented by Explorer.CurrentFolder and its subfolders.

Remarks

You can select stores to search in the Locations to Search menu by clicking Search Tools in the Options group of the Search contextual tab in the Microsoft Office Fluent ribbon.

By default, search does not include the Deleted Items folder. To search the Deleted Items folder, set that folder as your current folder and search by olSearchScopeCurrentFolder.


OlSelectionContents Enumeration (Outlook)

 Copy code hover
[image]

OlSelectionContents Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the kinds of objects selected in the active explorer.

Version Information

Version Added: Outlook 2010

Name | Value | Description
olConversationHeaders | 1 | Conversation header or headers in a selection.

Remark

Used by the GetSelection method of the Selection object.


OlSelectionLocation Enumeration (Outlook)

 Copy code hover
[image]

OlSelectionLocation Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the location of a selection in the Microsoft Outlook user interface.

Version Information

Version Added: Outlook 2010

Name | Value | Description
olAttachmentWell | 4 | The selection is an attachment of an item in the Reading Pane or inspector.
olDailyTaskList | 3 | The selection is in the daily Tasks list in the calendar view.
olToDoBarAppointmentList | 2 | The selection is in the list of appointments in the To-Do Bar.
olToDoBarTaskList | 1 | The selection is in the list of tasks in the To-Do Bar.
olViewList | 0 | The selection is in a list of items in an explorer.

Remark

Used by the Location property of the Selection object.


OlSensitivity Enumeration (Outlook)

 Copy code hover
[image]

OlSensitivity Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Represents the sensitivity for the Microsoft Outlook item.

Name | Value | Description
olConfidential | 3 | Confidential
olNormal | 0 | Normal sensitivity
olPersonal | 1 | Personal
olPrivate | 2 | Private

Remarks

Used by the Sensitivity property of Outlook items.


OlSharingMsgType Enumeration (Outlook)

 Copy code hover
[image]

OlSharingMsgType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the type of sharing message represented by a SharingItem object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olSharingMsgTypeInvite | 2 | Represents a sharing invitation.
olSharingMsgTypeInviteAndRequest | 3 | Represents both a sharing invitation and a sharing request.
olSharingMsgTypeRequest | 1 | Represents a sharing request.
olSharingMsgTypeResponseAllow | 4 | Represents a sharing response, which indicates that a sharing request or sharing invitation has been allowed.
olSharingMsgTypeResponseDeny | 5 | Represents a sharing response, which indicates that a sharing request or sharing invitation has been denied.
olSharingMsgTypeUnknown | 0 | Represents an unknown type of sharing message.


OlSharingProvider Enumeration (Outlook)

 Copy code hover
[image]

OlSharingProvider Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the sharing provider associated with a SharingItem object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olProviderExchange | 1 | Represents the Exchange sharing provider.
olProviderFederate | 7 | Represents a federated sharing provider. A SharingItem object with this type of provider is used for sharing relationships across organizational boundares (for example, between two organizations using Microsoft Exchange Server 2010).
olProviderICal | 4 | Represents the iCalendar sharing provider.
olProviderPubCal | 3 | Represents the PubCal sharing provider.
olProviderRSS | 6 | Represents the Really Simple Syndication (RSS) sharing provider.
olProviderSharePoint | 5 | Represents the SharePoint sharing provider.
olProviderUnknown | 0 | Represents an unknown sharing provider. This value is used if the sharing provider GUID in the sharing message does not match the GUID of any of the sharing providers represented in this enumeration.
olProviderWebCal | 2 | Represents the WebCal sharing provider.


OlShiftState Enumeration (Outlook)

 Copy code hover
[image]

OlShiftState Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Represents a bitmask to indicate which modifier key is pressed during a keyboard or mouse event of a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olShiftStateShiftMask | 1 | Indicates that the SHIFT key is pressed during the event.
olShiftStateCtrlMask | 2 | Indicates that the CTRL key is pressed during the event.
olShiftStateAltMask | 4 | Indicates that the ALT key is pressed during the event.


OlShowItemCount Enumeration (Outlook)

 Copy code hover
[image]

OlShowItemCount Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates which type of Microsoft Outlook item count is displayed for folders in the Outlook navigation pane.

Name | Value | Description
olNoItemCount | 0 | No item count displayed.
olShowTotalItemCount | 2 | Shows count of total number of items.
olShowUnreadItemCount | 1 | Shows count of unread items.

Remarks

Used by the Folder.ShowItemCount Property (Outlook).


OlSolutionScope Enumeration (Outlook)

 Copy code hover
[image]

OlSolutionScope Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies whether the solution root and its subfolders are shown in their default modules.

Version Information

Version Added: Outlook 2010

Name | Value | Description
olHideInDefaultModules | 0 | The solution root and its subfolders are displayed in the Solutions module and the Folder List.
olShowInDefaultModules | 1 | The solution root and its subfolders are displayed in the Solutions module and the Folder List, as well as in their respective default modules.


OlSortOrder Enumeration (Outlook)

 Copy code hover
[image]

OlSortOrder Enumeration (Outlook)
Send feedback

Indicates the sort order.

Name | Value | Description
olAscending | 1 | Ascending order
olDescending | 2 | Descending order
olSortNone | 0 | Not sorted

Remarks

Used as an optional parameter to the AddressEntries.Sort Method (Outlook) to specify the order that address entries should be sorted by the Property parameter.


OlSpecialFolders Enumeration (Outlook)

 Copy code hover
[image]

OlSpecialFolders Enumeration (Outlook)
Send feedback

Specifies the types of special folders in a store.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olSpecialFolderAllTasks | 0 | Specifies the All Tasks search folder for a store.
olSpecialFolderReminders | 1 | Specifies the Reminders search folder for a store.

Remarks

Not all special folders exist in all stores.


OlStorageIdentifierType Enumeration (Outlook)

 Copy code hover
[image]

OlStorageIdentifierType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of identifier for a StorageItem object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olIdentifyByEntryID | 1 | Identifies a StorageItem by EntryID.
olIdentifyByMessageClass | 2 | Identifies a StorageItem by message class.
olIdentifyBySubject | 0 | Identifies a StorageItem by Subject.

Remarks

The message class of a StorageItem Object (Outlook) is not exposed as an explicit built-in property. You can access the message class property through the PropertyAccessor Object (Outlook) that is provided by StorageItem.PropertyAccessor Property (Outlook).


OlStoreType Enumeration (Outlook)

 Copy code hover
[image]

OlStoreType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the format in which the data file should be created.

Name | Value | Description
olStoreANSI | 3 | ANSI format personal folders file (.pst) compatible with all previous versions of Microsoft Outlook format.
olStoreDefault | 1 | Default format compatible with the mailbox mode in which Outlook runs on the Microsoft Exchange Server.
olStoreUnicode | 2 | Unicode format personal folders file (.pst) compatible with Microsoft Office Outlook 2003 and later.

Remarks

Used as a parameter to the NameSpace.AddStoreEx Method (Outlook).


OlSyncState Enumeration (Outlook)

 Copy code hover
[image]

OlSyncState Enumeration (Outlook)
Send feedback

Indicates the synchronization state.

Name | Value | Description
olSyncStarted | 1 | Synchronization started
olSyncStopped | 0 | Synchronization stopped

Remarks

See SyncObject.Progress Event (Outlook).


OlTableContents Enumeration (Outlook)

 Copy code hover
[image]

OlTableContents Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies the type of items in a folder.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olHiddenItems | 1 | Only the hidden items in the folder.
olUserItems | 0 | Only the non-hidden user items in the folder.


OlTaskDelegationState Enumeration (Outlook)

 Copy code hover
[image]

OlTaskDelegationState Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the delegation state of a task.

Name | Value | Description
olTaskDelegationAccepted | 2 | The delegate accepted the task.
olTaskDelegationDeclined | 3 | The delegate declined the task.
olTaskDelegationUnknown | 1 | The delegate response to the task is unknown.
olTaskNotDelegated | 0 | The task has not been delegated.

Remarks

Used by the TaskItem.DelegationState Property (Outlook).


OlTaskOwnership Enumeration (Outlook)

 Copy code hover
[image]

OlTaskOwnership Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the ownership state of the task.

Name | Value | Description
olDelegatedTask | 1 | Task has been delegated to another user.
olNewTask | 0 | Task has not yet been assigned to a user.
olOwnTask | 2 | Task is assigned to the current Outlook user.

Remarks

Used by the TaskItem.Ownership Property (Outlook).


OlTaskRecipientType Enumeration (Outlook)

 Copy code hover
[image]

OlTaskRecipientType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the task recipient type.

Name | Value | Description
olFinalStatus | 3 | Indicates that the recipient will receive completion reports for the task.
olUpdate | 2 | Indicates that the recipient will receive status updates for the task.

Remarks

Used by the Recipient.Type Property (Outlook) for TaskItem recipients.


OlTaskResponse Enumeration (Outlook)

 Copy code hover
[image]

OlTaskResponse Enumeration (Outlook)
Send feedback

Indicates the response to a task request.

Name | Value | Description
olTaskAccept | 2 | Task accepted.
olTaskAssign | 1 | Task reassigned.
olTaskDecline | 3 | Task declined.
olTaskSimple | 0 | Task is a simple task and cannot be accepted, declined, or assigned. This constant is not a valid parameter to the TaskItem.Respond method.

Remarks

Used by the TaskItem.ResponseState Property (Outlook) and as a parameter to the TaskItem.Respond Method (Outlook).


OlTaskStatus Enumeration (Outlook)

 Copy code hover
[image]

OlTaskStatus Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the task status.

Name | Value | Description
olTaskComplete | 2 | The task is complete.
olTaskDeferred | 4 | The task is deferred.
olTaskInProgress | 1 | The task is in progress.
olTaskNotStarted | 0 | The task has not yet started.
olTaskWaiting | 3 | The task is waiting on someone else.

Remarks

Used by the TaskItem.Status Property (Outlook).


OlTextAlign Enumeration (Outlook)

 Copy code hover
[image]

OlTextAlign Enumeration (Outlook)
Send feedback

Specifies the alignment of text in a control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olTextAlignCenter | 2 | Text rendered in the control will be aligned to the center of the control.
olTextAlignLeft | 1 | Text rendered in the control will be aligned to the left edge of the control.
olTextAlignRight | 3 | Text rendered in the control will be aligned to the right edge of the control.


OlTimelineViewMode Enumeration (Outlook)

 Copy code hover
[image]

OlTimelineViewMode Enumeration (Outlook)
Send feedback

Indicates the view mode when using a TimelineView object.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olTimelineViewDay | 0 | Displays a timeline in which the upper scale represents days and the lower scale represents hours.
olTimelineViewMonth | 2 | Displays a timeline in which the upper scale represents months and the lower scale represents days.
olTimelineViewWeek | 1 | Displays a timeline in which the upper scale represents weeks and the lower scale represents days.


OlTimeStyle Enumeration (Outlook)

 Copy code hover
[image]

OlTimeStyle Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Specifies how time values are displayed and how entries of time values are interpreted by a time control.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olTimeStyleShortDuration | 4 | The drop-down portion of the time control displays only duration values with the interval set by the OlkTimeControl.IntervalTime property.
olTimeStyleTimeDuration | 1 | The drop-down portion of the time control displays time values starting from the ReferenceTime and uses the OlkTimeControl.IntervalTime property as the increment. The edit box of the time control displays the duration from the ReferenceTime to the selected time.
olTimeStyleTimeOnly | 0 | The drop-down portion of the time control displays only time values with the interval set by the OlkTimeControl.IntervalTime property.

Remarks

Use the time control with the olTimeStyleShortDuration style for duration fields, such as the Duration of a JournalItem. Use the time control with the olTimeStyleTimeDuration style for the end time of an appointment item. Use the time control with the olTimeStyleTimeOnly style for the start time of an appointment item.


OlTrackingStatus Enumeration (Outlook)

 Copy code hover
[image]

OlTrackingStatus Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the most recent tracking status change for the recipient.

Name | Value | Description
olTrackingDelivered | 1 | The item has been delivered to the recipient.
olTrackingNone | 0 | No tracking information is available for the recipient.
olTrackingNotDelivered | 2 | The item has not been delivered to the recipient.
olTrackingNotRead | 3 | The item has not been read by the recipient.
olTrackingRead | 6 | The item has been read by the recipient.
olTrackingRecallFailure | 4 | The sender of the item attempted to recall the item but was unsuccessful.
olTrackingRecallSuccess | 5 | The sender of the item recalled the item.
olTrackingReplied | 7 | The recipient replied to the item.

Remarks

Used by the Recipient.TrackingStatus Property (Outlook).


OlUserPropertyType Enumeration (Outlook)

 Copy code hover
[image]

OlUserPropertyType Enumeration (Outlook)
Send feedback

Indicates the user property type.

Name | Value | Description
olCombination | 19 | The property type is a combination of other types. It corresponds to the MAPI type PT_STRING8.
olCurrency | 14 | Represents a Currency property type. It corresponds to the MAPI type PT_CURRENCY.
olDateTime | 5 | Represents a DateTime property type. It corresponds to the MAPI type PT_SYSTIME.
olDuration | 7 | Represents a time duration property type. It corresponds to the MAPI type PT_LONG.
olEnumeration | 21 | Represents an enumeration property type. It corresponds to the MAPI type PT_LONG.
olFormula | 18 | Represents a formula property type. It corresponds to the MAPI type PT_STRING8. See UserDefinedProperty.Formula property.
olInteger | 20 | Represents an Integer number property type. It corresponds to the MAPI type PT_LONG.
olKeywords | 11 | Represents a String array property type used to store keywords. It corresponds to the MAPI type PT_MV_STRING8.
olNumber | 3 | Represents a Double number property type. It corresponds to the MAPI type PT_DOUBLE.
olOutlookInternal | 0 | Represents an Outlook internal property type.
olPercent | 12 | Represents a Double number property type used to store a percentage. It corresponds to the MAPI type PT_LONG.
olSmartFrom | 22 | Represents a smart from property type. This property indicates that if the From property of an Outlook item is empty, then the To property should be used instead.
olText | 1 | Represents a String property type. It corresponds to the MAPI type PT_STRING8.
olYesNo | 6 | Represents a yes/no (Boolean) property type. It corresponds to the MAPI type PT_BOOLEAN.

Remarks

Used by the ItemProperties.Add, UserDefinedProperties.Add, and UserProperties.Add methods, and ColumnFormat.FieldType, ItemProperty.Type, and UserDefinedProperty.Type properties.


OlVerticalLayout Enumeration (Outlook)

 Copy code hover
[image]

OlVerticalLayout Enumeration (Outlook)
Send feedback

Specifies the alignment of controls in the vertical direction.

Version Information

Version Added: Outlook 2007

Name | Value | Description
olVerticalLayoutAlignBottom | 2 | Align controls vertically by the bottom edge of each control.
olVerticalLayoutAlignGrow | 3 | Resize control vertically with the form.
olVerticalLayoutAlignMiddle | 1 | Align controls vertically by the center of each control.
olVerticalLayoutAlignTop | 0 | Align controls vertically by the top edge of each control.


OlViewSaveOption Enumeration (Outlook)

 Copy code hover
[image]

OlViewSaveOption Enumeration (Outlook)
Send feedback

Specifies the folders in which the view is available and the read permissions attached to the view.

Name | Value | Description
olViewSaveOptionAllFoldersOfType | 2 | Indicates that the view is available in all folders of the same type.
olViewSaveOptionThisFolderEveryone | 0 | Indicates that the view is only available in the current folder and is available to all users.
olViewSaveOptionThisFolderOnlyMe | 1 | Indicates that the view is only available in the current folder and is only available to the current Outlook user.

Remarks

Used by the Copy method and SaveOption property of View objects.


OlViewType Enumeration (Outlook)

 Copy code hover
[image]

OlViewType Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the view object type.

Name | Value | Description
olBusinessCardView | 5 | Represents a BusinessCardView object.
olCalendarView | 2 | Represents a CalendarView object.
olCardView | 1 | Represents a CardView object.
olDailyTaskListView | 1 | Represents the TableView object that contains the daily task list in a calendar view.
olIconView | 3 | Represents an IconView object.
olPeopleView | 7 | Represents a PeopleView object.
olTableView | 0 | Represents a TableView object.
olTimelineView | 4 | Represents a TimelineView object.

Remarks

Used by the ViewType property of View objects and as a parameter to the Views.Add Method (Outlook).


OlWindowState Enumeration (Outlook)

 Copy code hover
[image]

OlWindowState Enumeration (Outlook)
Send feedback

Published: July 16, 2012

Indicates the window state.

Name | Value | Description
olMaximized | 0 | The window is maximized.
olMinimized | 1 | The window is minimized.
olNormalWindow | 2 | The window is in the normal state (not minimized or maximized).

Remarks

Used by the WindowState property of Inspector and Explorer objects.


Outlook View Control reference (Outlook 2013)

 Copy code hover
[image]

Outlook View Control reference (Outlook 2013)
Send feedback

In this section

  • Outlook View Control Object Model Reference

  • ViewCtl Object (Outlook View Control)

  • OlxDefaultFolders Enumeration (Outlook View Control)


Outlook View Control Object Model Reference

 Copy code hover
[image]

Outlook View Control Object Model Reference
Send feedback

This section of the Outlook 2013 Developer Reference contains documentation for all of the objects, properties, methods, and events contained in the Outlook View Control object model. You can use the table of contents to navigate through the documentation.


ViewCtl Object (Outlook View Control)

 Copy code hover
[image]

ViewCtl Object (Outlook View Control)
Send feedback

Displays information about a specific folder and can be integrated into a Microsoft Outlook form or folder home page that provides access to Outlook data.

Version Information

Version Added: Outlook 2010

Remarks

The ViewCtl object provides programmatic access to the View Control. Use this control only within Outlook, in an HTML folder home page that is hosted in Outlook, or a custom Outlook form that is displayed by an Outlook add-in. This makes sure that Outlook is running and that the View Control is not subject to other factors that may adversely affect the Outlook process from continuing to be available for the View Control's use. Do not use the View Control in any scenario outside the Outlook process, such as in an HTML page hosted in a browser. Out-of-process scenarios are not supported. For more information, see Known issues when you use Outlook View Control with Outlook 2010.

You can set the control's properties programmatically to customize the folder and the view that is displayed in the control. You can use the control to create a variety of solutions that integrate Outlook data.

For example, you can place multiple View Controls on an HTML page so that a user can view the contents of more than one folder in a single window. This can be useful in a scenario where you want to display calendar information for more than one user at a time.

To use the ViewCtl object in your code, you must set a reference to the View Control's type library.

To set a reference to the View Control's type library:

  1. In the Visual Basic for Applications Code Editor, on the Tools menu, click References. The References command on the Tools menu is available only when a Module window is open and active in Design view.

  2. Select the Microsoft Outlook View Control check box.


ViewCtl Members (Outlook View Control)

 Copy code hover
[image]

ViewCtl Members (Outlook View Control)
Send feedback

The Microsoft Outlook View Control displays information about a specific folder and can be integrated into solutions that provide access to Outlook data. The ViewCtl object provides programmatic access to the View Control. The control can be placed in any container that supports ActiveX® controls, including an HTML page that is hosted in Outlook as a Folder Home Page, or a custom Outlook form. If the View Control is placed in an HTML page that is hosted in a browser such as Internet Explorer, some functions of the control are disabled for security.

Methods

Name | Description
AddressBook | Displays the Microsoft Outlook Address Book dialog box.
AddToPFFavorites | Adds the current public folder to the user's Microsoft Exchange Server Favorites public folder.
AdvancedFind | Displays the Microsoft Outlook Advanced Find dialog box.
Categories | Displays the Microsoft Outlook Categories dialog box for the currently selected item or items in the control.
CollapseAllGroups | Collapses (closes) all groups that are displayed in the control.
CollapseGroup | Collapses (closes) the group that is currently selected in the control.
CustomizeView | Displays the Microsoft Outlook View Summary dialog box.
Delete | After prompting the user to confirm, deletes the groups or items that are currently selected in the control.
ExpandAllGroups | Expands (opens) all groups that are displayed in the control.
ExpandGroup | Expands (opens) the group that is currently selected in the control.
FlagItem | Displays the Microsoft Outlook Flag for Follow Up dialog box for the selected item.
ForceUpdate | Refreshes the view in the control, applying any property changes made since the DeferUpdate property was set to True.
Forward | Executes the Forward action for the item or items that are selected in the control.
GoToDate | Opens a calendar view of a specific date.
NewAppointment | Creates and displays a new appointment.
NewContact | Creates and displays a new contact.
NewDefaultItem | Creates and displays a new Microsoft Outlook item.
NewDistributionList | Creates and displays a new distribution list.
NewForm | Displays the Microsoft Outlook Choose Form dialog box.
NewJournalEntry | Creates and displays a new journal entry.
NewMeetingRequest | Creates and displays a new meeting request.
NewMessage | Creates and displays a new e-mail message.
NewNote | Creates and displays a new note item.
NewPost | Creates and displays a new post item.
NewTask | Creates and displays a new task.
NewTaskRequest | Creates and displays a new task request.
Open | Opens the item or items that are currently selected in the control.
OpenSharedDefaultFolder | Displays a specified user's default folder in the control.
PrintItem | Prints the items that are currently selected in the control.
Reply | Executes the Reply action for the item or items selected in the control.
ReplyAll | Executes the ReplyAll action for the item or items that are selected in the control.
ReplyInFolder | Creates a post item for each message that is currently selected in the control.
SaveAs | Saves the items that are selected in the control as a single file.
SendAndReceive | Sends all messages that are in the Outbox folder and checks for new messages.
ShowFields | Displays the Microsoft Outlook Show Fields dialog box.
Sort | Displays the Microsoft Outlook Sort dialog box.
SynchFolder | Synchronizes the online and offline folders that are displayed in the control.

Properties

Name | Description
ActiveFolder | Returns an object that represents the folder displayed in the control. Read-only.
DeferUpdate | Gets or sets a Boolean value that indicates whether property changes affect the control display. Read/write.
EnableRowPersistance | Gets or sets a value that indicates whether the View Control retains state information about the last selected row. Read/write.
Filter | Gets or sets a String that represents the Distributed Authoring and Versioning (DAV) Searching and Locating (DASL) statement used to restrict the display to a specified subset of data. Read/write.
FilterAppend | Gets or sets a String that represents the additional criteria to add to the filter settings. Read/write.
Folder | Gets or sets a String that represents the path of the folder displayed by the control.
ItemCount | Returns a Long that indicates the count of objects in the current folder displayed in the control. Read-only.
Namespace | Returns or sets a String that represents the namespace property of the control. Read/write.
OutlookApplication | Returns an object that represents the container object for the control. Read-only.
Restriction | Sets or returns a String that represents a filter to the items that are displayed in the control. As a result, the control displays only those items that match the filter. Read/write.
SelectedDate | Returns or sets the selected date. Read-only.
Selection | Returns a Selection object that consists of one or more items that are selected in the current view. Read-only.
View | Returns or sets a String that represents the name of the view in the control. Read/write.
ViewXML | Returns or sets a String that represents the view implementation via XML. Read/write.

Events

Name | Description
Activate | Occurs when a View Control becomes the active element on the page, either as a result of user action or through program code.
BeforeViewSwitch | Occurs before Microsoft Outlook changes the view that is applied to the folder displayed in the View Control element, either as a result of user action or through program code.
SelectionChange | Occurs when the selection of the current view changes.
ViewSwitch | Occurs when Microsoft Outlook changes the view that is applied to the folder displayed in the View Control element, either as a result of user action or through program code.


ViewCtl Properties (Outlook View Control)

 Copy code hover
[image]

ViewCtl Properties (Outlook View Control)
Send feedback

In this section

  • ViewCtl.ActiveFolder Property (Outlook View Control)

  • ViewCtl.DeferUpdate Property (Outlook View Control)

  • ViewCtl.EnableRowPersistance Property (Outlook View Control)

  • ViewCtl.Filter Property (Outlook View Control)

  • ViewCtl.FilterAppend Property (Outlook View Control)

  • ViewCtl.Folder Property (Outlook View Control)

  • ViewCtl.ItemCount Property (Outlook View Control)

  • ViewCtl.Namespace Property (Outlook View Control)

  • ViewCtl.OutlookApplication Property (Outlook View Control)

  • ViewCtl.Restriction Property (Outlook View Control)

  • ViewCtl.SelectedDate Property (Outlook View Control)

  • ViewCtl.Selection Property (Outlook View Control)

  • ViewCtl.View Property (Outlook View Control)

  • ViewCtl.ViewXML Property (Outlook View Control)


ViewCtl.ActiveFolder Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ActiveFolder Property (Outlook View Control)
Send feedback

Returns an Object that represents the folder displayed in the control. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ActiveFolder

expression A variable that represents a ViewCtl object.

Remarks

If the control is not hosted in a Microsoft Outlook folder home page, this property returns nothing.


ViewCtl.DeferUpdate Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.DeferUpdate Property (Outlook View Control)
Send feedback

Returns or sets a Boolean value that indicates whether property changes affect the control display. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .DeferUpdate

expression A variable that represents a ViewCtl object.

Remarks

When set to True, this property prevents changes to control properties from being displayed in the control. When set to False, the control updates to reflect current property settings.


ViewCtl.EnableRowPersistance Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.EnableRowPersistance Property (Outlook View Control)
Send feedback

Returns or sets a Boolean value that indicates whether the View Control retains state information about the last selected row. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .EnableRowPersistance

expression A variable that represents a ViewCtl object.

Remarks

This property is effective only when Microsoft Outlook hosts the View Control. When set to True, the View Control retains the information. When set to False, it does not. The default value is False.


ViewCtl.Filter Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Filter Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the Distributed Authoring and Versioning (DAV) Searching and Locating (DASL) statement used to restrict the display to a specified subset of data. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Filter

expression A variable that represents a ViewCtl object.

Remarks

To reset a filter back to its default value, type the following line of code.

VBA Copy code Copy code
object.Filter = " ""DAV:isfolder"" = False And ""DAV:ishidden"" = False "


ViewCtl.FilterAppend Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.FilterAppend Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the additional criteria to add to the filter settings. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .FilterAppend

expression A variable that represents a ViewCtl object.


ViewCtl.Folder Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Folder Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the path of the folder displayed by the control. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Folder

expression A variable that represents a ViewCtl object.

Remarks

For security reasons, the return value includes the name of the root message store of the folder only if the folder is not in the user's personal mailbox.

If neither the Namespace property nor the Folder property is set and the control is contained in a Microsoft Outlook folder home page, the control displays the current folder. If the Namespace property is set to "MAPI" and the Folder property is not set, the control displays the user's Inbox.

In addition to accepting a string that represents a valid folder path, you can also set the Folder property to the EntryID of the folder that you want to display in the View Control.


ViewCtl.ItemCount Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ItemCount Property (Outlook View Control)
Send feedback

Returns a Long that indicates the count of objects in the current folder displayed in the control. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .ItemCount

expression A variable that represents a ViewCtl object.

Remarks

The ItemCount property always returns the number of items that are in the current folder displayed in the control, and not the number of items that are visible in the view. Setting the Filter or the FilterAppend property has no effect on the value of the ItemCount property.


ViewCtl.Namespace Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Namespace Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the namespace property of the control. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Namespace

expression A variable that represents a ViewCtl object.

Remarks

If neither the Namespace nor the Folder properties are set and the control is contained in a Microsoft Outlook folder home page, the control displays the current folder. If the Namespace property is set to "MAPI" and the Folder property is not set, the control displays the user's Inbox.

The namespace represents an abstract root object for any data source.


ViewCtl.OutlookApplication Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.OutlookApplication Property (Outlook View Control)
Send feedback

Returns an object that represents the container object for the control. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .OutlookApplication

expression A variable that represents a ViewCtl object.

Remarks

If the control is not hosted in a Microsoft Outlook folder home page, this property returns nothing.


ViewCtl.Restriction Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Restriction Property (Outlook View Control)
Send feedback

Returns or sets a String value that represents a filter to the items that are displayed in the control. As a result, the control displays only those items that match the filter. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .Restriction

expression A variable that represents a ViewCtl object.

Remarks

The filter is a string expression that contains one or more filter clauses that are joined by the logical operators Or, Not, or And.

A filter clause is a simple expression that evaluates to True or False; for example, [CompanyName] = "Microsoft"

Note that property names can be used in the expression and are identified and delimited by square brackets. Except for these bracketed property names, only literals are allowed within the expression; variables and constants are not evaluated as part of the expression.

Comparison operators allowed within the filter expression include >, <, >=, <=, = and <>. Comparisons are not case sensitive and do not include subject prefixes that are added when a message is replied to or forwarded.

Note that "=" is not interpreted as "equals" in String comparisons, but as "contains" instead, so that [Subject] = 'Outlook' matches all items that have "Outlook" or "outlook" anywhere in the Subject field. To create a true equality filter, you must use <= and >= together, as in the following example.

Copy code Copy code
OvCtl1.Restriction "[Subject] <= 'outlook'

and

Copy code Copy code
[Subject] >= 'outlook'

In this example, the control displays only those items whose Subject field contains only "outlook" or "Outlook."

The setting of the Restriction property does not persist if the view or current folder changes.

The Restriction property only works correctly if you use Table or Card views. This is a limitation of the Microsoft Outlook View Control.


ViewCtl.SelectedDate Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.SelectedDate Property (Outlook View Control)
Send feedback

Returns or sets a Date value that represents the selected date. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectedDate

expression A variable that represents a ViewCtl object.


ViewCtl.Selection Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Selection Property (Outlook View Control)
Send feedback

Returns a Selection object that consists of one or more items that are selected in the current view. Read-only.

Version Information

Version Added: Outlook 2010

Syntax

expression .Selection

expression A variable that represents a ViewCtl object.

Remarks

If the current folder is a file system folder, or if Outlook Today or any folder with a current Web view is currently displayed, this property returns an empty collection.


ViewCtl.View Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.View Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the name of the view in the control. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .View

expression A variable that represents a ViewCtl object.


ViewCtl.ViewXML Property (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ViewXML Property (Outlook View Control)
Send feedback

Returns or sets a String that represents the view implementation via XML. Read/write.

Version Information

Version Added: Outlook 2010

Syntax

expression .ViewXML

expression A variable that represents a ViewCtl object.


ViewCtl Methods (Outlook View Control)

 Copy code hover
[image]

ViewCtl Methods (Outlook View Control)
Send feedback

In this section

  • ViewCtl.AddressBook Method (Outlook View Control)

  • ViewCtl.AddToPFFavorites Method (Outlook View Control)

  • ViewCtl.AdvancedFind Method (Outlook View Control)

  • ViewCtl.Categories Method (Outlook View Control)

  • ViewCtl.CollapseAllGroups Method (Outlook View Control)

  • ViewCtl.CollapseGroup Method (Outlook View Control)

  • ViewCtl.CustomizeView Method (Outlook View Control)

  • ViewCtl.Delete Method (Outlook View Control)

  • ViewCtl.ExpandAllGroups Method (Outlook View Control)

  • ViewCtl.ExpandGroup Method (Outlook View Control)

  • ViewCtl.FlagItem Method (Outlook View Control)

  • ViewCtl.ForceUpdate Method (Outlook View Control)

  • ViewCtl.Forward Method (Outlook View Control)

  • ViewCtl.GoToDate Method (Outlook View Control)

  • ViewCtl.GoToToday Method (Outlook View Control)

  • ViewCtl.GroupBy Method (Outlook View Control)

  • ViewCtl.MarkAllAsRead Method (Outlook View Control)

  • ViewCtl.MarkAsRead Method (Outlook View Control)

  • ViewCtl.MarkAsUnread Method (Outlook View Control)

  • ViewCtl.MoveItem Method (Outlook View Control)

  • ViewCtl.NewAppointment Method (Outlook View Control)

  • ViewCtl.NewContact Method (Outlook View Control)

  • ViewCtl.NewDefaultItem Method (Outlook View Control)

  • ViewCtl.NewDistributionList Method (Outlook View Control)

  • ViewCtl.NewForm Method (Outlook View Control)

  • ViewCtl.NewJournalEntry Method (Outlook View Control)

  • ViewCtl.NewMeetingRequest Method (Outlook View Control)

  • ViewCtl.NewMessage Method (Outlook View Control)

  • ViewCtl.NewNote Method (Outlook View Control)

  • ViewCtl.NewPost Method (Outlook View Control)

  • ViewCtl.NewTask Method (Outlook View Control)

  • ViewCtl.NewTaskRequest Method (Outlook View Control)

  • ViewCtl.Open Method (Outlook View Control)

  • ViewCtl.OpenSharedDefaultFolder Method (Outlook View Control)

  • ViewCtl.PrintItem Method (Outlook View Control)

  • ViewCtl.Reply Method (Outlook View Control)

  • ViewCtl.ReplyAll Method (Outlook View Control)

  • ViewCtl.ReplyInFolder Method (Outlook View Control)

  • ViewCtl.SaveAs Method (Outlook View Control)

  • ViewCtl.SendAndReceive Method (Outlook View Control)

  • ViewCtl.ShowFields Method (Outlook View Control)

  • ViewCtl.Sort Method (Outlook View Control)

  • ViewCtl.SynchFolder Method (Outlook View Control)


ViewCtl.AddressBook Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.AddressBook Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Address Book dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .AddressBook

expression A variable that represents a ViewCtl object.


ViewCtl.AddToPFFavorites Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.AddToPFFavorites Method (Outlook View Control)
Send feedback

Adds the current public folder to the user's Microsoft Exchange Server Favorites public folder.

Version Information

Version Added: Outlook 2010

Syntax

expression .AddToPFFavorites

expression A variable that represents a ViewCtl object.


ViewCtl.AdvancedFind Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.AdvancedFind Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Advanced Find dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .AdvancedFind

expression A variable that represents a ViewCtl object.


ViewCtl.Categories Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Categories Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Categories dialog box for the currently selected item or items in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .Categories

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to select categories for the selected items or to modify the master category list.


ViewCtl.CollapseAllGroups Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.CollapseAllGroups Method (Outlook View Control)
Send feedback

Collapses (closes) all groups that are displayed in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .CollapseAllGroups

expression A variable that represents a ViewCtl object.

Remarks

If the view displayed in the control does not group items, this method has no effect.


ViewCtl.CollapseGroup Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.CollapseGroup Method (Outlook View Control)
Send feedback

Collapses (closes) the group that is currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .CollapseGroup

expression A variable that represents a ViewCtl object.

Remarks

If the view displayed in the control does not group items, or if an item in the view is selected, this method has no effect.


ViewCtl.CustomizeView Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.CustomizeView Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook View Summary dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .CustomizeView

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to customize the current view in the control.


ViewCtl.Delete Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Delete Method (Outlook View Control)
Send feedback

After prompting the user to confirm, deletes the groups or items that are currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .Delete

expression A variable that represents a ViewCtl object.

Remarks

If the selection includes one or more groups, the groups and all items in the groups are deleted.


ViewCtl.ExpandAllGroups Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ExpandAllGroups Method (Outlook View Control)
Send feedback

Expands (opens) all groups that are displayed in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .ExpandAllGroups

expression A variable that represents a ViewCtl object.

Remarks

If the view displayed in the control does not group items, this method has no effect.


ViewCtl.ExpandGroup Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ExpandGroup Method (Outlook View Control)
Send feedback

Expands (opens) the group that is currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .ExpandGroup

expression A variable that represents a ViewCtl object.

Remarks

If the view displayed in the control does not group items, or if an item in the view is selected, this method has no effect.


ViewCtl.FlagItem Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.FlagItem Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Flag for Follow Up dialog box for the selected item.

Version Information

Version Added: Outlook 2010

Syntax

expression .FlagItem

expression A variable that represents a ViewCtl object.

Remarks

If the selection includes more than one item, the dialog box applies to the last item in the selection.


ViewCtl.ForceUpdate Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ForceUpdate Method (Outlook View Control)
Send feedback

Refreshes the view in the control, applying any property changes made since the DeferUpdate property was set to True.

Version Information

Version Added: Outlook 2010

Syntax

expression .ForceUpdate

expression A variable that represents a ViewCtl object.


ViewCtl.Forward Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Forward Method (Outlook View Control)
Send feedback

Executes the Forward action for the item or items that are selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .Forward

expression A variable that represents a ViewCtl object.


ViewCtl.GoToDate Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.GoToDate Method (Outlook View Control)
Send feedback

Opens a calendar view of a specific date.

Version Information

Version Added: Outlook 2010

Syntax

expression.GoToDate(newDate)

expression A variable that represents a ViewCtl object.

Parameters

Name | Required/Optional | Data type | Description
newDate | Required | String | The specific date in the calendar to view.


ViewCtl.GoToToday Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.GoToToday Method (Outlook View Control)
Send feedback

Sets the day that is displayed in the control to the current day.

Version Information

Version Added: Outlook 2010

Syntax

expression .GoToToday

expression A variable that represents a ViewCtl object.

Remarks

This method affects only day, week, and month views.


ViewCtl.GroupBy Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.GroupBy Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Group By dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression.GroupBy

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to group items in the current view.

This method is valid only for table-type views.


ViewCtl.MarkAllAsRead Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.MarkAllAsRead Method (Outlook View Control)
Send feedback

Marks as read all items in the folder displayed in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .MarkAllAsRead

expression A variable that represents a ViewCtl object.

Remarks

The user is prompted to confirm any changes.


ViewCtl.MarkAsRead Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.MarkAsRead Method (Outlook View Control)
Send feedback

Marks as read all selected items in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .MarkAsRead

expression A variable that represents a ViewCtl object.

Remarks

The user is prompted to confirm any changes.


ViewCtl.MarkAsUnread Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.MarkAsUnread Method (Outlook View Control)
Send feedback

Marks as unread all selected items in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .MarkAsUnread

expression A variable that represents a ViewCtl object.

Remarks

The user is prompted to confirm any changes.


ViewCtl.MoveItem Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.MoveItem Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Move Items dialog box for the items that are selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .MoveItem

expression A variable that represents a ViewCtl object.


ViewCtl.NewAppointment Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewAppointment Method (Outlook View Control)
Send feedback

Creates and displays a new appointment.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewAppointment

expression A variable that represents a ViewCtl object.

Remarks

When the new appointment is saved, it is saved to the folder, if any, that is displayed in the control. If there is no folder displayed in the control, the appointment is saved to the user's default Calendar folder.


ViewCtl.NewContact Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewContact Method (Outlook View Control)
Send feedback

Creates and displays a new contact.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewContact

expression A variable that represents a ViewCtl object.

Remarks

When the new contact is saved, it is saved to the Contact folder, if any, that is displayed in the control. If there is no Contact folder displayed in the control, the contact is saved to the user's default Contacts folder.


ViewCtl.NewDefaultItem Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewDefaultItem Method (Outlook View Control)
Send feedback

Creates and displays a new Microsoft Outlook item.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewDefaultItem

expression A variable that represents a ViewCtl object.

Remarks

The item type that the method creates is the default item type for the folder that is displayed in the control.


ViewCtl.NewDistributionList Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewDistributionList Method (Outlook View Control)
Send feedback

Creates and displays a new distribution list.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewDistributionList

expression A variable that represents a ViewCtl object.

Remarks

When the new distribution list is saved, it is saved to the Contacts folder, if any, that is displayed in the control. If there is no Contacts folder displayed in the control, the distribution list is saved to the user's default Contacts folder.


ViewCtl.NewForm Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewForm Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Choose Form dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewForm

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to create a new Outlook item by selecting a form from a forms library.


ViewCtl.NewJournalEntry Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewJournalEntry Method (Outlook View Control)
Send feedback

Creates and displays a new journal entry.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewJournalEntry

expression A variable that represents a ViewCtl object.


ViewCtl.NewMeetingRequest Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewMeetingRequest Method (Outlook View Control)
Send feedback

Creates and displays a new meeting request.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewMeetingRequest

expression A variable that represents a ViewCtl object.

Remarks

When the meeting request is sent, the corresponding appointment is saved to the Calendar folder, if any, that is displayed in the control. If there is no folder displayed in the control, the appointment is saved to the user's default Calendar folder.

Responses to the meeting request are tallied only if the appointment is saved to the user's default Calendar folder.


ViewCtl.NewMessage Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewMessage Method (Outlook View Control)
Send feedback

Creates and displays a new e-mail message.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewMessage

expression A variable that represents a ViewCtl object.


ViewCtl.NewNote Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewNote Method (Outlook View Control)
Send feedback

Creates and displays a new note item.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewNote

expression A variable that represents a ViewCtl object.

Remarks

When the new note is saved, it is saved to the Notes folder, if any, that is displayed in the control. If there is no Notes folder displayed in the control, the note is saved to the user's default Notes folder.


ViewCtl.NewPost Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewPost Method (Outlook View Control)
Send feedback

Creates and displays a new post item.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewPost

expression A variable that represents a ViewCtl object.

Remarks

When the user posts the message, it is posted to the folder that is displayed in the control.

This method has no effect if the folder displayed in the control does not support messages.


ViewCtl.NewTask Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewTask Method (Outlook View Control)
Send feedback

Creates and displays a new task.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewTask

expression A variable that represents a ViewCtl object.

Remarks

When the new task is saved it is saved to the Tasks folder, if any, that is displayed in the control. If there is no Tasks folder displayed in the control, the task is saved to the user's default Tasks folder.


ViewCtl.NewTaskRequest Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.NewTaskRequest Method (Outlook View Control)
Send feedback

Creates and displays a new task request.

Version Information

Version Added: Outlook 2010

Syntax

expression .NewTaskRequest

expression A variable that represents a ViewCtl object.


ViewCtl.Open Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Open Method (Outlook View Control)
Send feedback

Opens the item or items that are currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .Open

expression A variable that represents a ViewCtl object.


ViewCtl.OpenSharedDefaultFolder Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.OpenSharedDefaultFolder Method (Outlook View Control)
Send feedback

Displays a specified user's default folder in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression. OpenSharedDefaultFolder(bstrRecipient, FolderType)

expression A variable that represents a ViewCtl object.

Parameters

Name | Required/Optional | Data Type | Description
bstrRecipient | Required | String | The owner of the folder. The string must contain a display name or alias that can be resolved to a valid recipient.
FolderType | Required | OlxDefaultFolders | The type of folder. Can be one of the following OlxDefaultFolders constants: olxFolderDeletedItems(3), olxFolderOutbox(4), olxFolderSentMail(5), olxFolderInbox(6), olxFolderCalendar(9), olxFolderContacts(10), olxFolderJournal(11), olxFolderNotes(12), olxFolderTasks(13), or olxFolderDrafts(16).

Remarks

An error occurs if the user running the control does not have permission to access the specified folder.


ViewCtl.PrintItem Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.PrintItem Method (Outlook View Control)
Send feedback

Prints the items that are currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .PrintItem

expression A variable that represents a ViewCtl object.

Remarks

Selecting a group automatically selects and prints all items in the group. The Print dialog box is displayed so that the user can specify how to print the items.


ViewCtl.Reply Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Reply Method (Outlook View Control)
Send feedback

Executes the Reply action for the item or items selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .Reply

expression A variable that represents a ViewCtl object.


ViewCtl.ReplyAll Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ReplyAll Method (Outlook View Control)
Send feedback

Executes the ReplyAll action for the item or items that are selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .ReplyAll

expression A variable that represents a ViewCtl object.


ViewCtl.ReplyInFolder Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ReplyInFolder Method (Outlook View Control)
Send feedback

Creates a post item for each message that is currently selected in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .ReplyInFolder

expression A variable that represents a ViewCtl object.

Remarks

Along with the reply, the post item retains the text from the original message and its Subject field.


ViewCtl.SaveAs Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.SaveAs Method (Outlook View Control)
Send feedback

Saves the items that are selected in the control as a single file.

Version Information

Version Added: Outlook 2010

Syntax

expression .SaveAs

expression A variable that represents a ViewCtl object.

Remarks

The Save As dialog box is displayed so that the user can select the location and format of the resulting file. By default, if more than one item is selected, the items are concatenated and saved as a text file.


ViewCtl.SendAndReceive Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.SendAndReceive Method (Outlook View Control)
Send feedback

Sends all messages that are in the Outbox folder and checks for new messages.

Version Information

Version Added: Outlook 2010

Syntax

expression .SendAndReceive

expression A variable that represents a ViewCtl object.


ViewCtl.ShowFields Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ShowFields Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Show Fields dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .ShowFields

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to select the fields to display in the current view of the control.

This method has no effect if the current view does not allow the user to change the fields displayed in the view.


ViewCtl.Sort Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Sort Method (Outlook View Control)
Send feedback

Displays the Microsoft Outlook Sort dialog box.

Version Information

Version Added: Outlook 2010

Syntax

expression .Sort

expression A variable that represents a ViewCtl object.

Remarks

This method gives the user the ability to sort the contents of the control by using one or more criteria.


ViewCtl.SynchFolder Method (Outlook View Control)

 Copy code hover
[image]

ViewCtl.SynchFolder Method (Outlook View Control)
Send feedback

Synchronizes the online and offline folders that are displayed in the control.

Version Information

Version Added: Outlook 2010

Syntax

expression .SynchFolder

expression A variable that represents a ViewCtl object.


ViewCtl Events (Outlook View Control)

 Copy code hover
[image]

ViewCtl Events (Outlook View Control)
Send feedback

In this section

  • ViewCtl.Activate Event (Outlook View Control)

  • ViewCtl.BeforeViewSwitch Event (Outlook View Control)

  • ViewCtl.SelectionChange Event (Outlook View Control)

  • ViewCtl.ViewSwitch Event (Outlook View Control)


ViewCtl.Activate Event (Outlook View Control)

 Copy code hover
[image]

ViewCtl.Activate Event (Outlook View Control)
Send feedback

Occurs when a View Control becomes the active element on the page, either as a result of user action or through program code.

Version Information

Version Added: Outlook 2010

Syntax

expression .Activate

expression A variable that represents a ViewCtl object.

Remarks

This event does not occur when the control is placed on a Visual Basic Application UserForm.


ViewCtl.BeforeViewSwitch Event (Outlook View Control)

 Copy code hover
[image]

ViewCtl.BeforeViewSwitch Event (Outlook View Control)
Send feedback

Occurs before Microsoft Outlook changes the view that is applied to the folder displayed in the View Control element, either as a result of user action or through program code.

Version Information

Version Added: Outlook 2010

Syntax

expression .BeforeViewSwitch(newView, Cancel)

expression A variable that represents a ViewCtl object.

Parameters

Name | Required/Optional | Data Type | Description
newView | Required | String | The name of the view that the View Control is switching to.
Cancel | Optional | Boolean | False when the event occurs. If the event procedure sets this parameter to True, it cancels the switch and retains the current view.

Remarks

You can cancel this event to prevent the user from changing the view in the View Control.

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).


ViewCtl.SelectionChange Event (Outlook View Control)

 Copy code hover
[image]

ViewCtl.SelectionChange Event (Outlook View Control)
Send feedback

Occurs when the selection of the current view changes.

Version Information

Version Added: Outlook 2010

Syntax

expression .SelectionChange

expression A variable that represents a ViewCtl object.

Remarks

Other selection changes (such as the selected folder) do not cause this event to occur.

This event does not occur if the current folder is a file system folder or if Outlook Today or any folder with a current Web view is displayed.

This event is not available in Microsoft Visual Basic Scripting Edition (VBScript).


ViewCtl.ViewSwitch Event (Outlook View Control)

 Copy code hover
[image]

ViewCtl.ViewSwitch Event (Outlook View Control)
Send feedback

Occurs when Microsoft Outlook changes the view that is applied to the folder displayed in the View Control element, either as a result of user action or through program code.

Version Information

Version Added: Outlook 2010

Syntax

expression .ViewSwitch

expression A variable that represents a ViewCtl object.


OlxDefaultFolders Enumeration (Outlook View Control)

 Copy code hover
[image]

OlxDefaultFolders Enumeration (Outlook View Control)
Send feedback

Specifies the folder type for a specified folder.

Name | Value | Description
olFolderCalendar | 9 | The Calendar folder.
olFolderContacts | 10 | The Contacts folder.
olFolderDeletedItems | 3 | The Deleted Items folder.
olFolderDrafts | 16 | The Drafts folder.
olFolderInbox | 6 | The Inbox folder.
olFolderJournal | 11 | The Journal folder.
olFolderNotes | 12 | The Notes folder.
olFolderOutbox | 4 | The Outbox folder.
olFolderSentMail | 5 | The Sent Mail folder.
olFolderTasks | 13 | The Tasks folder.


Outlook forms script reference (Outlook 2013)

 Copy code hover
[image]

Outlook forms script reference (Outlook 2013)
Send feedback

In this section

  • CheckBox Object Reference (Outlook Forms Script)

  • ComboBox Object Reference (Outlook Forms Script)

  • CommandButton Object Reference (Outlook Forms Script)

  • Font Object Reference (Outlook Forms Script)

  • Frame Object Reference (Outlook Forms Script)

  • Image Object Reference (Outlook Forms Script)

  • Label Object Reference (Outlook Forms Script)

  • ListBox Object Reference (Outlook Forms Script)

  • MultiPage Object Reference (Outlook Forms Script)

  • OptionButton Object Reference (Outlook Forms Script)

  • Page Object Reference (Outlook Forms Script)

  • Pages Object Reference (Outlook Forms Script)

  • ScrollBar Object Reference (Outlook Forms Script)

  • SpinButton Object Reference (Outlook Forms Script)

  • Tab Object Reference (Outlook Forms Script)

  • Tabs Object Reference (Outlook Forms Script)

  • TabStrip Object Reference (Outlook Forms Script)

  • TextBox Object Reference (Outlook Forms Script)

  • ToggleButton Object Reference (Outlook Forms Script)


CheckBox Object Reference (Outlook Forms Script)

 Copy code hover
[image]

CheckBox Object Reference (Outlook Forms Script)
Send feedback

In this section

  • CheckBox Object (Outlook Forms Script)

  • CheckBox Members (Outlook Forms Script)

  • CheckBox Properties (Outlook Forms Script)

  • CheckBox Events (Outlook Forms Script)


CheckBox Object (Outlook Forms Script)

 Copy code hover
[image]

CheckBox Object (Outlook Forms Script)
Send feedback

Displays the selection state of an item.

Remarks

Use a CheckBox to give the user a choice between two values such as Yes/No, True/False, or On/Off. When the user selects a CheckBox, it displays a special mark (such as an X) and its current setting is Yes, True, or On. If the user does not select the CheckBox, it is empty and its setting is No, False, or Off. Depending on the value of the TripleState property, a CheckBox can also have a Null value.

If a CheckBox is bound to a data source, changing the setting changes the value of that source. A disabled CheckBox shows the current value, but is dimmed and does not allow changes to the value from the user interface.

You can also use check boxes inside a group box to select one or more of a group of related items. For example, you can create an order form that contains a list of available items, with a CheckBox preceding each item. The user can select a particular item or items by checking the corresponding CheckBox.

The default property of a CheckBox is the Value property.

The ListBox also lets you put a check mark by selected options. Depending on your application, you can use the ListBox instead of using a group of CheckBox controls.


CheckBox Members (Outlook Forms Script)

 Copy code hover
[image]

CheckBox Members (Outlook Forms Script)
Send feedback

Displays the selection state of an item.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for a control. Read/write.
Alignment | Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
GroupName | Returns or sets a String that identifies a group of mutually exclusive CheckBox controls. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PicturePosition | Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TripleState | Returns or sets a Boolean that determines whether a user can specify, from the user interface, the Null state for a CheckBox. Read/write.
Value | Returns or sets a Variant that specifies whether the check box is selected. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


CheckBox Properties (Outlook Forms Script)

 Copy code hover
[image]

CheckBox Properties (Outlook Forms Script)
Send feedback

In this section

  • CheckBox.Accelerator Property (Outlook Forms Script)

  • CheckBox.Alignment Property (Outlook Forms Script)

  • CheckBox.AutoSize Property (Outlook Forms Script)

  • CheckBox.BackColor Property (Outlook Forms Script)

  • CheckBox.BackStyle Property (Outlook Forms Script)

  • CheckBox.Caption Property (Outlook Forms Script)

  • CheckBox.Enabled Property (Outlook Forms Script)

  • CheckBox.ForeColor Property (Outlook Forms Script)

  • CheckBox.GroupName Property (Outlook Forms Script)

  • CheckBox.Locked Property (Outlook Forms Script)

  • CheckBox.MouseIcon Property (Outlook Forms Script)

  • CheckBox.MousePointer Property (Outlook Forms Script)

  • CheckBox.Picture Property (Outlook Forms Script)

  • CheckBox.PicturePosition Property (Outlook Forms Script)

  • CheckBox.SpecialEffect Property (Outlook Forms Script)

  • CheckBox.TextAlign Property (Outlook Forms Script)

  • CheckBox.TripleState Property (Outlook Forms Script)

  • CheckBox.Value Property (Outlook Forms Script)

  • CheckBox.WordWrap Property (Outlook Forms Script)


CheckBox.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for a control. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a CheckBox object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the control's property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.

When an accelerator key is used, there is no visual feedback (other than focus) to indicate that the control initiated the Click event. For example, if the accelerator key applies to a CommandButton, the user will not see the button pressed in the interface. The button receives the focus, however, when the user presses the accelerator key.


CheckBox.Alignment Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Alignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.

Syntax

expression .Alignment

expression A variable that represents a CheckBox object.

Remarks

The possible values of Alignment is 0 or 1. A value of 0 places the caption to the left of the control. A value of 1 places the caption to the right of the control (default).

The caption text for a control is left-aligned.


CheckBox.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a CheckBox object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls with captions, the AutoSize property specifies whether the control automatically adjusts to display the entire caption.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


CheckBox.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a CheckBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


CheckBox.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a CheckBox object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


CheckBox.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Syntax

expression .Caption

expression A variable that represents a CheckBox object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.

Setting AutoSize to True automatically adjusts the size of the control to frame the entire caption.


CheckBox.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a CheckBox object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


CheckBox.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a CheckBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


CheckBox.GroupName Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.GroupName Property (Outlook Forms Script)
Send feedback

Returns or sets a String that identifies a group of mutually exclusive CheckBox controls. Read/write.

Syntax

expression .GroupName

expression A variable that represents a CheckBox object.

Remarks

Use the same GroupName for all check boxes in the group. The default setting is an empty string.

To create a group of mutually exclusive CheckBox controls, you can put the check boxes in a Frame on your form, or you can use the GroupName property. GroupName is more efficient for the following reasons:

  • You do not have to include a Frame for each group. By not using a Frame, you reduce the number of controls on the form, and in turn, improve performance and reduce the size of the form.

  • You have more design flexibility. If you use a Frame to create the group, all the check boxes must be inside the Frame. If you want more than one group, you must have one Frame for each group. However, if you use GroupName to create the group, the group can include check boxes anywhere on the form. If you want more than one group, specify a unique name for each group; you can still place the individual controls anywhere on the form.

  • You can create check boxes with transparent backgrounds, which can improve the visual appearance of your form. The Frame is not a transparent control.

Regardless of which method you use to create the group of check boxes, clicking one check box in a group sets all other check boxes in the same group to False. All check boxes with the same GroupName within a single container are mutually exclusive. You can use the same group name in two containers, but doing so creates two groups (one in each container) rather than one group that includes both containers.

For example, assume your form includes some check boxes and a MultiPage that also includes option buttons. The check boxes on the MultiPage are one group and the buttons on the form are another group. The two groups do not affect each other. Changing the setting of a check box on the MultiPage does not affect the check boxes on the form.


CheckBox.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a CheckBox object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


CheckBox.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a CheckBox object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


CheckBox.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a CheckBox object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


CheckBox.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a CheckBox object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

For controls with captions, use the PicturePosition property to specify where to display the picture on the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


CheckBox.PicturePosition Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.PicturePosition Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.

Syntax

expression .PicturePosition

expression A variable that represents a CheckBox object.

Remarks

The settings for PicturePosition are:

Value | Description
0 | The picture appears to the left of the caption. The caption is aligned with the top of the picture.
1 | The picture appears to the left of the caption. The caption is centered relative to the picture.
2 | The picture appears to the left of the caption. The caption is aligned with the bottom of the picture.
3 | The picture appears to the right of the caption. The caption is aligned with the top of the picture.
4 | The picture appears to the right of the caption. The caption is centered relative to the picture.
5 | The picture appears to the right of the caption. The caption is aligned with the bottom of the picture.
6 | The picture appears above the caption. The caption is aligned with the left edge of the picture.
7 | The picture appears above the caption. The caption is centered below the picture (default).
8 | The picture appears above the caption. The caption is aligned with the right edge of the picture.
9 | The picture appears below the caption. The caption is aligned with the left edge of the picture.
10 | The picture appears below the caption. The caption is centered above the picture.
11 | The picture appears below the caption. The caption is aligned with the right edge of the picture.
12 | The picture appears in the center of the control. The caption is centered horizontally and vertically on top of the picture.

The picture and the caption, as a unit, are centered on the control. If no caption exists, the picture's location is relative to the center of the control.

This property is ignored if the Picture property does not specify a picture.


CheckBox.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a CheckBox object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them. Default for CheckBox.

SpecialEffect uses the system colors to define its borders.


CheckBox.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a CheckBox object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.


CheckBox.TripleState Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.TripleState Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that determines whether a user can specify, from the user interface, the Null state for a CheckBox. Read/write.

Syntax

expression .TripleState

expression A variable that represents a CheckBox object.

Remarks

True if the control clicks through three states, False if the control only supports two states, True and False (default).

When the TripleState property is True, a user can choose from the values of Null, True, and False. The Null value is displayed as a shaded button.

When TripleState is False, the user can choose either True or False.

A control set to Null does not initiate the Click event.

Regardless of the property setting, the Null value can always be assigned programmatically to a CheckBox, causing that control to appear shaded.


CheckBox.Value Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies whether the check box is selected. Read/write.

Syntax

expression .Value

expression A variable that represents a CheckBox object.

Remarks

The settings for Value are:

Control | Description
Null | Indicates the item is in a null state, neither selected nor cleared.
True | Indicates the item is selected.
False | Indicates the item is cleared.
Zero (0) | Indicates the first page. The maximum value is one less than the number of pages.


CheckBox.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents a CheckBox object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.


CheckBox Events (Outlook Forms Script)

 Copy code hover
[image]

CheckBox Events (Outlook Forms Script)
Send feedback

In this section

  • CheckBox.Click Event (Outlook Forms Script)


CheckBox.Click Event (Outlook Forms Script)

 Copy code hover
[image]

CheckBox.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click

expression A variable that represents a CheckBox object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

For some controls, the Click event occurs when the Value property changes. However, using the PropertyChange or CustomPropertyChange event is the preferred technique for detecting a new value for a property. The following are examples of actions that initiate the Click event due to assigning a new value to a control: clicking a CheckBox, pressing the SPACEBAR when the check box has the focus, pressing the accelerator key, or changing the value of the control in code.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.

If you bind a CheckBox to a field, then the Click event does not fire. You need to use the PropertyChange or CustomPropertyChange event to detect the change via code, as in the following code sample:

Copy code Copy code
Sub Item_PropertyChange(ByVal Name)
Set MyListBox = Item.GetInspector.ModifiedFormPages("Message").Controls("CheckBox1")
Select Case Name
    Case "Mileage"
        Item.CC = MyCheckBox.Value
        Item.Subject = MyCheckBox.Value
    Case Else
End Select
End Sub


ComboBox Object Reference (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Object Reference (Outlook Forms Script)
Send feedback

In this section

  • ComboBox Object (Outlook Forms Script)

  • ComboBox Members (Outlook Forms Script)

  • ComboBox Properties (Outlook Forms Script)

  • ComboBox Methods (Outlook Forms Script)

  • ComboBox Events (Outlook Forms Script)


ComboBox Object (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Object (Outlook Forms Script)
Send feedback

Combines the features of a ListBox and a TextBox.

Remarks

The user can enter a new value, as with a TextBox, or the user can select an existing value as with a ListBox.

If a ComboBox is bound to a data source, the ComboBox inserts the value entered or selected by the user into that data source. If a multicolumn combo box is bound, then the BoundColumn property determines which value is stored in the bound data source.

The list in a ComboBox consists of rows of data. Each row can have one or more columns, which can appear with or without headings. Some applications do not support column headings, others provide only limited support.

The default property of a ComboBox is the Value property.

If you want more than a single line of the list to appear at all times, you might want to use a ListBox instead of a ComboBox. If you want to use a ComboBox and limit values to those in the list, you can set the Style property of the ComboBox so the control looks like a drop-down list box.


ComboBox Members (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Members (Outlook Forms Script)
Send feedback

Combines the features of a ListBox and a TextBox.

Methods

Name | Description
AddItem | For a single-column ComboBox, the AddItem method adds an item to the list. For a multicolumn ComboBox, this method adds a row to the list.
Clear | Removes all entries in the list in a ComboBox.
Copy | Copies the contents of an object to the Clipboard.
Cut | Removes selected information from an object and transfers it to the Clipboard.
DropDown | Displays the list portion of a ComboBox.
Paste | Transfers the contents of the Clipboard to an object.
RemoveItem | Removes a row from the list in a ComboBox.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies whether an automatic tab occurs when a user enters the maximum allowable number of characters into the text box portion of a ComboBox. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether the basic unit used to extend a selection is a word or a single character. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
BoundColumn | Returns or sets a Variant that identifies the source of data in a multicolumn ComboBox. Read/write.
CanPaste | Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.
Column | Returns or sets a Variant that represents a single value, a column of values, or a two-dimensional array to load into a ComboBox. Read/write.
ColumnCount | Returns or sets a Long that represents the number of columns to display in a combo box. Read/write.
ColumnHeads | Returns or sets a Boolean that specifies whether a single row of column headings are displayed. Read/write.
ColumnWidths | Returns or sets a String that specifies the width of each column in a multicolumn ComboBox. Read/write.
CurTargetX | Returns a Long that represents the preferred horizontal position of the insertion point in a multiline ComboBox. Read-only.
CurX | Returns or sets a Long that represents the current horizontal position of the insertion point in a multiline ComboBox. Read/write.
DragBehavior | Returns or sets an Integer that specifies whether the system enables the drag-and-drop feature for the control. Read/write.
DropButtonStyle | Returns or sets a fmDropButtonStyle value that represents the symbol displayed on the drop button in a ComboBox. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
EnterFieldBehavior | Returns or sets an Integer that specifies the selection behavior when entering a ComboBox. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
HideSelection | Returns or sets a Boolean that specifies whether selected text remains highlighted when a control does not have the focus. Read/write.
IMEMode | Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.
LineCount | Returns a Long that specifies the number of text lines in a ComboBox. Read-only.
List | Returns or sets a Variant that represents the specified entry in a ComboBox. Read/write.
ListCount | Returns a Long that represents the number of list entries in a control. Read-only.
ListIndex | Returns or sets a Variant that represents the currently selected item in a ComboBox. Read/write.
ListRows | Returns or sets a Long that specifies the maximum number of rows to display in the list. Read/write.
ListStyle | Returns or sets an Integer that specifies the visual appearance of the list in a ComboBox. Read/write.
ListWidth | Returns or sets a Variant that specifies the width of the list in a ComboBox. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MatchEntry | Returns or sets an Integer that indicates how a ComboBox searches its list as the user types. Read/write.
MatchFound | Returns a Boolean value that indicates whether the text that a user has typed into a ComboBox matches any of the entries in the list. Read-only.
MatchRequired | Returns or sets a Boolean that specifies whether a value entered in the text portion of a ComboBox must match an entry in the existing list portion of the control. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters a user can enter in a ComboBox. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that represents the number of characters selected in the text portion of a ComboBox. Read/write.
SelStart | Returns or sets a Long that represents the starting point of selected text, or the insertion point if no text is selected. Read/write.
SelText | Returns or sets a String that represents the selected text of a control. Read/write.
ShowDropButtonWhen | Returns or sets a fmShowDropButtonWhen value that specifies when to show the drop-down button for a ComboBox. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
Style | Returns or sets an Integer that specifies how the user can choose or set the control's value. Read/write.
Text | Returns or sets a String that specifies text in a ComboBox, changing the selected row in the control. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TextColumn | Returns or sets a Variant that identifies the column in a ComboBox to display to the user. Read/write.
TextLength | Returns a Long that represents the length, in number of characters, of text in the edit region of a ComboBox. Read-only.
TopIndex | Returns or sets a Long that represents the index of the item displayed in the topmost position in the list portion of the ComboBox. Read/write.
Value | Returns or sets a Variant that specifies the value in the BoundColumn of the currently selected rows. Read/write.

Events

Name | Description
Click | Occurs when the user definitively selects a value for the control that has more than one possible value.


ComboBox Properties (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Properties (Outlook Forms Script)
Send feedback

In this section

  • ComboBox.AutoSize Property (Outlook Forms Script)

  • ComboBox.AutoTab Property (Outlook Forms Script)

  • ComboBox.AutoWordSelect Property (Outlook Forms Script)

  • ComboBox.BackColor Property (Outlook Forms Script)

  • ComboBox.BackStyle Property (Outlook Forms Script)

  • ComboBox.BorderColor Property (Outlook Forms Script)

  • ComboBox.BorderStyle Property (Outlook Forms Script)

  • ComboBox.BoundColumn Property (Outlook Forms Script)

  • ComboBox.CanPaste Property (Outlook Forms Script)

  • ComboBox.Column Property (Outlook Forms Script)

  • ComboBox.ColumnCount Property (Outlook Forms Script)

  • ComboBox.ColumnHeads Property (Outlook Forms Script)

  • ComboBox.ColumnWidths Property (Outlook Forms Script)

  • ComboBox.CurTargetX Property (Outlook Forms Script)

  • ComboBox.CurX Property (Outlook Forms Script)

  • ComboBox.DragBehavior Property (Outlook Forms Script)

  • ComboBox.DropButtonStyle Property (Outlook Forms Script)

  • ComboBox.Enabled Property (Outlook Forms Script)

  • ComboBox.EnterFieldBehavior Property (Outlook Forms Script)

  • ComboBox.ForeColor Property (Outlook Forms Script)

  • ComboBox.HideSelection Property (Outlook Forms Script)

  • ComboBox.IMEMode Property (Outlook Forms Script)

  • ComboBox.LineCount Property (Outlook Forms Script)

  • ComboBox.List Property (Outlook Forms Script)

  • ComboBox.ListCount Property (Outlook Forms Script)

  • ComboBox.ListIndex Property (Outlook Forms Script)

  • ComboBox.ListRows Property (Outlook Forms Script)

  • ComboBox.ListStyle Property (Outlook Forms Script)

  • ComboBox.ListWidth Property (Outlook Forms Script)

  • ComboBox.Locked Property (Outlook Forms Script)

  • ComboBox.MatchEntry Property (Outlook Forms Script)

  • ComboBox.MatchFound Property (Outlook Forms Script)

  • ComboBox.MatchRequired Property (Outlook Forms Script)

  • ComboBox.MaxLength Property (Outlook Forms Script)

  • ComboBox.MouseIcon Property (Outlook Forms Script)

  • ComboBox.MousePointer Property (Outlook Forms Script)

  • ComboBox.SelectionMargin Property (Outlook Forms Script)

  • ComboBox.SelLength Property (Outlook Forms Script)

  • ComboBox.SelStart Property (Outlook Forms Script)

  • ComboBox.SelText Property (Outlook Forms Script)

  • ComboBox.ShowDropButtonWhen Property (Outlook Forms Script)

  • ComboBox.SpecialEffect Property (Outlook Forms Script)

  • ComboBox.Style Property (Outlook Forms Script)

  • ComboBox.Text Property (Outlook Forms Script)

  • ComboBox.TextAlign Property (Outlook Forms Script)

  • ComboBox.TextColumn Property (Outlook Forms Script)

  • ComboBox.TextLength Property (Outlook Forms Script)

  • ComboBox.TopIndex Property (Outlook Forms Script)

  • ComboBox.Value Property (Outlook Forms Script)


ComboBox.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a ComboBox object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls without captions, this property specifies whether the control automatically adjusts to display the information stored in the control. In a ComboBox, for example, setting AutoSize to True automatically sets the width of the display area to match the length of the current text.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


ComboBox.AutoTab Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.AutoTab Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an automatic tab occurs when a user enters the maximum allowable number of characters into the text box portion of a ComboBox. Read/write.

Syntax

expression .AutoTab

expression A variable that represents a ComboBox object.

Remarks

True if tab occurs, False otherwise (default).

The MaxLength property specifies the maximum number of characters allowed in the text box portion of a ComboBox.

You can specify the AutoTab property for a ComboBox on a form for which you usually enter a set number of characters. Once a user enters the maximum number of characters, the focus automatically moves to the next control in the tab order. For example, if a ComboBox displays inventory stock numbers that are always five characters long, you can use MaxLength to specify the maximum number of characters to enter into the ComboBox and AutoTab to automatically tab to the next control after the user enters five characters.


ComboBox.AutoWordSelect Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.AutoWordSelect Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the basic unit used to extend a selection is a word or a single character. Read/write.

Syntax

expression .AutoWordSelect

expression A variable that represents a ComboBox object.

Remarks

True if uses a word as the basic unit (default), False if uses a character as the basic unit.

The AutoWordSelect property specifies how the selection extends or contracts in the edit region of a ComboBox.

If the user places the insertion point in the middle of a word and then extends the selection while AutoWordSelect is True, the selection includes the entire word.


ComboBox.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a ComboBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


ComboBox.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a ComboBox object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


ComboBox.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents a ComboBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


ComboBox.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents a ComboBox object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for a ComboBox is 0 (None).

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


ComboBox.BoundColumn Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.BoundColumn Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that identifies the source of data in a multicolumn ComboBox. Read/write.

Syntax

expression .BoundColumn

expression A variable that represents a ComboBox object.

Remarks

The possible values of BoundColumn are 0 and 1. 0 assigns the value of the ListIndex property to the control. 1 assigns the value from the specified column to the control. Columns are numbered from 1 when using this property (default).

When the user chooses a row in a multicolumn ComboBox, the BoundColumn property identifies which item from that row to store as the value of the control. For example, if each row contains 8 items and BoundColumn is 3, the system stores the information in the third column of the currently-selected row as the value of the object.

You can display one set of data to users but store different, associated values for the object by using the BoundColumn and the TextColumn properties. TextColumn identifies the column of data displayed in a ComboBox; BoundColumn identifies the column of associated data values stored for the control. For example, you could set up a multicolumn ComboBox that contains the names of holidays in one column and dates for the holidays in a second column. To present the holiday names to users, specify the first column as the TextColumn. To store the dates of the holidays, specify the second column as the BoundColumn.

The ListIndex value retrieves the number of the selected row. For example, if you want to know the row of the selected item, set BoundColumn to 0 to assign the number of the selected row as the value of the control. Be sure to retrieve a current value, rather than relying on a previously saved value, if you are referencing a list whose contents might change.

The Column, List, and ListIndex properties all use zero-based numbering. That is, the value of the first item (column or row) is zero; the value of the second item is one, and so on. This means that if BoundColumn is set to 3, you could access the value stored in that column using the expression Column(2).


ComboBox.CanPaste Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.CanPaste Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.

Syntax

expression .CanPaste

expression A variable that represents a ComboBox object.

Remarks

True if the object can receive information pasted from the Clipboard, False if the object cannot receive information pasted from the Clipboard.

CanPaste is read-only.

If the Clipboard data is in a format that the object does not support, the CanPaste property is False. For example, if you try to paste a bitmap into an object that only supports text, CanPaste will be False.


ComboBox.Column Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Column Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents a single value, a column of values, or a two-dimensional array to load into a ComboBox. Read/write.

Syntax

expression .Column(pvargColumn, pvargIndex)

expression A variable that represents a ComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargColumn | Optional | Variant | An integer with a range from 0 to one less than the total number of columns.
pvargIndex | Optional | Variant | An integer with a range from 0 to one less than the total number of rows.

Remarks

If you specify both the column and row values, Column reads or writes a specific item.

If you specify only the column value, the Column property reads or writes the specified column in the current row of the object. For example, MyComboBox.Column (3) reads or writes the third column in MyComboBox.

Column returns a Variant from the cursor. When a built-in cursor provides the value for Variant (such as when using the AddItem method), the value is a String. When an external cursor provides the value for Variant, formatting associated with the data is not included in the Variant.

You can use Column to assign the contents of a combo box to another control, such as a text box.

If the user makes no selection when you refer to a column in a combo box or list box, the Column setting is Null. You can check for this condition by using the IsNull function.

You can also use Column to copy an entire two-dimensional array of values to a control. This syntax lets you quickly load a list of choices rather than individually loading each element of the list using AddItem.

When copying data from a two-dimensional array, Column transposes the contents of the array in the control so that the contents of ComboBox1.Column(X, Y) is the same as MyArray(Y, X). You can also use the List property to copy an array without transposing it.


ComboBox.ColumnCount Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ColumnCount Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the number of columns to display in a combo box. Read/write.

Syntax

expression .ColumnCount

expression A variable that represents a ComboBox object.

Remarks

Setting ColumnCount to 0 displays zero columns, and setting it to -1 displays all the available columns. For an unbound data source, there is a 10-column limit (0 to 9).

You can use the ColumnWidths property to set the width of the columns displayed in the control.


ComboBox.ColumnHeads Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ColumnHeads Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a single row of column headings are displayed. Read/write.

Syntax

expression .ColumnHeads

expression A variable that represents a ComboBox object.

Remarks

True if column headings are to be displayed, False otherwise (default).

Headings in combo boxes appear only when the list drops down.

Setting this property to True displays a blank row as column headings. However, currently there is no way to specify the text for column headings.


ComboBox.ColumnWidths Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ColumnWidths Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the width of each column in a multicolumn ComboBox. Read/write.

Syntax

expression .ColumnWidths

expression A variable that represents a ComboBox object.

Remarks

ColumnWidths sets the column width in points. A setting of -1 or blank results in a calculated width. A width of 0 hides a column. To specify a different unit of measurement, include the unit of measure. A value greater than 0 explicitly specifies the width of the column.

To separate column entries, use semicolons (;) as list separators. Or use the list separator specified in Regional Settings of the Windows Control Panel.

Any or all of the ColumnWidths property settings can be blank. You create a blank setting by typing a list separator without a preceding value.

If you specify a -1 in the property page, the displayed value in the property page is a blank.

To calculate column widths when ColumnWidths is blank or -1, the width of the control is divided equally among all columns of the list. If the sum of the specified column widths exceeds the width of the control, the list is left-aligned within the control and one or more of the rightmost columns are not displayed. Users can scroll the list using the horizontal scroll bar to display the rightmost columns.

The minimum calculated column width is 72 points (1 inch). To produce columns narrower than this, you must specify the width explicitly.

Unless specified otherwise, column widths are measured in points. To specify another unit of measure, include the units as part of the values. The following examples specify column widths in several units of measure and describe how the various settings would fit in a three-column list box that is 4 inches wide.

Setting | Effect
90;72;90 | The first column is 90 points (1.25 inch); the second column is 72 points (1 inch); the third column is 90 points.
6 cm;0;6 cm | The first column is 6 centimeters; the second column is hidden; the third column is 6 centimeters. Because part of the third column is visible, a horizontal scroll bar appears.
1.5 in;0;2.5 in | The first column is 1.5 inches, the second column is hidden, and the third column is 2.5 inches.
2 in;;2 in | The first column is 2 inches, the second column is 1 inch (default), and the third column is 2 inches. Because only half of the third column is visible, a horizontal scroll bar appears.
(Blank) | All three columns are the same width (1.33 inches).

In a ComboBox, the system displays the column designated by the TextColumn property in the text box portion of the control. Setting TextColumn to -1 displays the first column that has a ColumnWidths value greater than 0.


ComboBox.CurTargetX Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.CurTargetX Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the preferred horizontal position of the insertion point in a multiline ComboBox. Read-only.

Syntax

expression .CurTargetX

expression A variable that represents a ComboBox object.

Remarks

The CurTargetX property retrieves the preferred position, measured in himetric units. A himetric is 0.0001 meter.

The target position is relative to the left edge of the control. If the length of a line is less than the value of the CurTargetX property, you can place the insertion point at the end of the line. The value of CurTargetX changes when the user sets the insertion point or when the CurX property is set. CurTargetX is read-only.

The return value is valid when the object has focus.

You can use CurTargetX and CurX to move the insertion point as the user scrolls through the contents of a multiline ComboBox. When the user moves the insertion point to another line of text by scrolling the content of the object, CurTargetX specifies the preferred position for the insertion point. CurX is set to this value if the line of text is longer than the value of CurTargetX. Otherwise, CurX is set to the end of the line of text.


ComboBox.CurX Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.CurX Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the current horizontal position of the insertion point in a multiline ComboBox. Read/write.

Syntax

expression .CurX

expression A variable that represents a ComboBox object.

Remarks

The CurX property applies to a multiline ComboBox. The return value is valid when the object has the focus.

You can use CurTargetX and CurX to position the insertion point as the user scrolls through the contents of a multiline ComboBox. When the user moves the insertion point to another line of text by scrolling the content of the object, CurTargetX specifies the preferred position for the insertion point. CurX is set to this value if the line of text is longer than the value of CurTargetX. Otherwise, CurX is set to the end of the line of text.


ComboBox.DragBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.DragBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether the system enables the drag-and-drop feature for the control. Read/write.

Syntax

expression .DragBehavior

expression A variable that represents a ComboBox object.

Remarks

The possible values of DragBehavior are 0 and 1. 0 represents that drag-and-drop action is not allowed. 1 represents that drag-and-drop action is allowed.

If the DragBehavior property is enabled, dragging in a combo box starts a drag-and-drop operation on the selected text. If DragBehavior is disabled, dragging in a combo box selects text.

The drop-down portion of a ComboBox does not support drag-and-drop processes, nor does it support selection of list items within the text.

DragBehavior has no effect on a ComboBox whose Style property is set to 2.

You can combine the effects of the EnterFieldBehavior property and DragBehavior to create a large number of combo box styles.


ComboBox.DropButtonStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.DropButtonStyle Property (Outlook Forms Script)
Send feedback

Returns or sets a fmDropButtonStyle value that represents the symbol displayed on the drop button in a ComboBox. Read/write.

Syntax

expression .DropButtonStyle

expression A variable that represents a ComboBox object.

Remarks

The possible values for DropButtonStyle are:

Value | Description
0 | Displays a plain button, with no symbol.
1 | Displays a down arrow (default).
2 | Displays an ellipsis (...).
3 | Displays a horizontal line like an underscore character.

The recommended setting for showing items in a list is 1.


ComboBox.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a ComboBox object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


ComboBox.EnterFieldBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.EnterFieldBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the selection behavior when entering a ComboBox. Read/write.

Syntax

expression .EnterFieldBehavior

expression A variable that represents a ComboBox object.

Remarks

The possible values of EnterFieldBehavior are 0 and 1. 0 represents selecting the entire contents of the edit region when entering the control (default). 1 represents leaving the selection unchanged. Visually, this uses the selection that was in effect the last time the control was active.

The EnterFieldBehavior property controls the way text is selected when the user tabs to the control, not when the control receives focus as a result of the SetFocus method. Following SetFocus, the contents of the control are not selected and the insertion point appears after the last character in the control's edit region.

You can combine the effects of the EnterFieldBehavior property and DragBehavior to create a large number of combo box styles.


ComboBox.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a ComboBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


ComboBox.HideSelection Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.HideSelection Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether selected text remains highlighted when a control does not have the focus. Read/write.

Syntax

expression .HideSelection

expression A variable that represents a ComboBox object.

Remarks

True if selected text is not highlighted unless the control has the focus (default). False if selected text always appears highlighted.

You can use the HideSelection property to maintain highlighted text when another form or a dialog box receives the focus, such as in a spell-checking procedure.


ComboBox.IMEMode Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.IMEMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.

Syntax

expression .IMEMode

expression A variable that represents a ComboBox object.

Remarks

This property applies only to applications written for Asian languages and is ignored in other applications.

The settings for fmIMEMode are:

Value | Description
0 | Does not control IME (default).
1 | IME on.
2 | IME off. English mode.
3 | IME off. User can't turn on IME by keyboard.
4 | IME on with Full-width Hiragana mode.
5 | IME on with Full-width Katakana mode.
6 | IME on with Half-width Katakana mode.
7 | IME on with Full-width Alphanumeric mode.
8 | IME on with Half-width Alphanumeric mode.
9 | IME on with Full-width Hangul mode.
10 | IME on with Half-width Hangul mode.

A setting of 0 indicates that the mode of the IME does not change when the control receives focus at run time. For any other value, the mode of the IME is set to the value specified by the IMEMode property when the control receives focus at run time.


ComboBox.LineCount Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.LineCount Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the number of text lines in a ComboBox. Read-only.

Syntax

expression .LineCount

expression A variable that represents a ComboBox object.

Remarks

A ComboBox only has one line.


ComboBox.List Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.List Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents the specified entry in a ComboBox. Read/write.

Syntax

expression .List(pvargIndex, pvargColumn)

expression A variable that represents a ComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargIndex | Optional | Variant | An integer with a range from 0 to one less than the number of entries in the list of the ComboBox.
pvargColumn | Optional | Variant | An integer with a range from 0 to one less than the number of columns in the list of the ComboBox.

Remarks

Row and column numbering begins with zero. That is, the row number of the first row in the list is zero; the column number of the first column is zero. The number of the second row or column is 1, and so on.

The List property works with the ListCount and ListIndex properties. Use List to access list items. A list is a variant array; each item in the list has a row number and a column number.

Initially, a ComboBox contains an empty list.

To specify items you want to display in a ComboBox, use the AddItem method. To remove items, use the RemoveItem method.

Use List to copy an entire two-dimensional array of values to a control. Use AddItem to load a one-dimensional array or to load an individual element.


ComboBox.ListCount Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ListCount Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the number of list entries in a control. Read-only.

Syntax

expression .ListCount

expression A variable that represents a ComboBox object.

Remarks

ListCount is the number of rows over which you can scroll. ListCount is always one greater than the largest value for the ListIndex property, because index numbers begin with 0 and the count of items begins with 1. If no item is selected, ListCount is 0 and ListIndex is -1.


ComboBox.ListIndex Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ListIndex Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents the currently selected item in a ComboBox. Read/write.

Syntax

expression .ListIndex

expression A variable that represents a ComboBox object.

Remarks

The ListIndex property contains an index of the selected row in a list. Values of ListIndex range from -1 to one less than the total number of rows in a list (that is, ListCount - 1). When no rows are selected, ListIndex returns -1. When the user selects a row in a ListBox or ComboBox, the system sets the ListIndex value. The ListIndex value of the first row in a list is 0, the value of the second row is 1, and so on.

The ListIndex value is also available by setting the BoundColumn property to 0 for a combo box. If BoundColumn is 0, the underlying data source to which the combo box is bound contains the same list index value as ListIndex.


ComboBox.ListRows Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ListRows Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum number of rows to display in the list. Read/write.

Syntax

expression .ListRows

expression A variable that represents a ComboBox object.

Remarks

The default value is 8.

If the number of items in the list exceeds the value of the ListRows property, a scroll bar appears at the right edge of the list-box portion of the combo box.


ComboBox.ListStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ListStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of the list in a ComboBox. Read/write.

Syntax

expression .ListStyle

expression A variable that represents a ComboBox object.

Remarks

The settings for ListStyle are:

Value | Description
0 | Looks like a regular combo box, with the background of items highlighted.
1 | Shows option buttons, or check boxes for a multi-select list of the combo box (default). When the user selects an item from the group, the option button associated with that item is selected and the option buttons for the other items in the group are deselected.

The ListStyle property lets you change the visual presentation of a ComboBox. By specifying a setting other than 0, you can present the contents of either control as a group of individual items, with each item including a visual cue to indicate whether it is selected.


ComboBox.ListWidth Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ListWidth Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies the width of the list in a ComboBox. Read/write.

Syntax

expression .ListWidth

expression A variable that represents a ComboBox object.

Remarks

A value of zero makes the list as wide as the ComboBox. The default value is to make the list as wide as the text portion of the control.

If you want to display a multicolumn list, enter a value that will make the list box wide enough to fit all the columns.

When designing combo boxes, be sure to leave enough space to display your data and for a vertical scroll bar.


ComboBox.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a ComboBox object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


ComboBox.MatchEntry Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MatchEntry Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates how a ComboBox searches its list as the user types. Read/write.

Syntax

expression .MatchEntry

expression A variable that represents a ComboBox object.

Remarks

The settings for MatchEntry are:

Value | Description
0 | Basic matching. The control searches for the next entry that starts with the character entered. Repeatedly typing the same letter cycles through all entries beginning with that letter.
1 | Extended matching. As each character is typed, the control searches for an entry matching all characters entered (default).
2 | No matching.

The MatchEntry property searches entries from the TextColumn property of a ListBox or ComboBox.

The control searches the column identified by TextColumn for an entry that matches the user's typed entry. Upon finding a match, the row containing the match is selected, the contents of the column are displayed, and the contents of its BoundColumn property become the value of the control. If the match is unambiguous, finding the match initiates the Click event.

The control initiates the Click event as soon as the user types a sequence of characters that match exactly one entry in the list. As the user types, the entry is compared with the current row in the list and with the next row in the list. When the entry matches only the current row, the match is unambiguous.

In Microsoft Forms, this is true regardless of whether the list is sorted. This means the control finds the first occurrence that matches the entry, based on the order of items in the list. For example, entering either "abc" or "bc" will initiate the Click event for the following list:

Copy code Copy code
abcde
bcdef
abcxyz
bchij

Note that in either case, the matched entry is not unique; however, it is sufficiently different from the adjacent entry that the control interprets the match as unambiguous and initiates the Click event.


ComboBox.MatchFound Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MatchFound Property (Outlook Forms Script)
Send feedback

Returns a Boolean value that indicates whether the text that a user has typed into a ComboBox matches any of the entries in the list. Read-only.

Syntax

expression .MatchFound

expression A variable that represents a ComboBox object.

Remarks

True if the contents of the Value property matches one of the records in the list. False if the contents of Value does not match any of the records in the list (default).

The MatchFound property is read-only. It is not applicable when the MatchEntry property is set to 2.


ComboBox.MatchRequired Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MatchRequired Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a value entered in the text portion of a ComboBox must match an entry in the existing list portion of the control. Read/write.

Syntax

expression .MatchRequired

expression A variable that represents a ComboBox object.

Remarks

The user can enter non-matching values, but may not leave the control until a matching value is entered.

True if the text entered must match an existing list entry. False if the text entered can be different from all existing list entries (default).

If the MatchRequired property is True, the user cannot exit the ComboBox until the text entered matches an entry in the existing list. MatchRequired maintains the integrity of the list by requiring the user to select an existing entry.

Not all containers enforce this property.


ComboBox.MaxLength Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MaxLength Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum number of characters a user can enter in a ComboBox. Read/write.

Syntax

expression .MaxLength

expression A variable that represents a ComboBox object.

Remarks

Setting the MaxLength property to 0 indicates there is no limit other than that created by memory constraints.


ComboBox.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a ComboBox object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


ComboBox.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a ComboBox object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


ComboBox.SelectionMargin Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.SelectionMargin Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.

Syntax

expression .SelectionMargin

expression A variable that represents a ComboBox object.

Remarks

True if clicking in margin causes selection of text (default), False if clicking in margin does not cause selection of text.

When the SelectionMargin property is True, the selection margin occupies a thin strip along the left edge of a control's edit region. When set to False, the entire edit region can store text.

If the SelectionMargin property is set to True when a control is printed, the selection margin also prints.


ComboBox.SelLength Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.SelLength Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the number of characters selected in the text portion of a ComboBox. Read/write.

Syntax

expression .SelLength

expression A variable that represents a ComboBox object.

Remarks

For SelLength and SelStart, the valid range of settings is 0 to the total number of characters in the edit area of a ComboBox.

The SelLength property is always valid, even when the control does not have focus. Setting SelLength to a value less than zero creates an error. Attempting to set SelLength to a value greater than the number of characters available in a control results in a value equal to the number of characters in the control.

Changing the value of the SelStart property cancels any existing selection in the control, places an insertion point in the text, and sets SelLength to zero.

The default value, zero, means that no text is currently selected.


ComboBox.SelStart Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.SelStart Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the starting point of selected text, or the insertion point if no text is selected. Read/write.

Syntax

expression .SelStart

expression A variable that represents a ComboBox object.

Remarks

For SelLength and SelStart, the valid range of settings is 0 to the total number of characters in the edit area of a ComboBox. The default value is zero.

The SelStart property is always valid, even when the control does not have focus. Setting SelStart to a value less than zero creates an error. Attempting to set SelStart to a value greater than the number of characters available in a control results in a value equal to the number of characters in the control.

Changing the value of SelStart cancels any existing selection in the control, places an insertion point in the text, and sets the SelLength property to zero.


ComboBox.SelText Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.SelText Property (Outlook Forms Script)
Send feedback

Returns or sets a String that represents the selected text of a control. Read/write.

Syntax

expression .SelText

expression A variable that represents a ComboBox object.

Remarks

If no characters are selected in the edit region of the control, the SelText property returns a zero length string. This property is valid regardless of whether the control has the focus.


ComboBox.ShowDropButtonWhen Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.ShowDropButtonWhen Property (Outlook Forms Script)
Send feedback

Returns or sets a fmShowDropButtonWhen value that specifies when to show the drop-down button for a ComboBox. Read/write.

Syntax

expression .ShowDropButtonWhen

expression A variable that represents a ComboBox object.

Remarks

The settings for ShowDropButtonWhen are:

Value | Description
0 | Do not show the drop-down button under any circumstances.
1 | Show the drop-down button when the control has the focus.
2 | Always show the drop-down button. This is the default value.


ComboBox.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a ComboBox object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

SpecialEffect uses the system colors to define its borders.


ComboBox.Style Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Style Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how the user can choose or set the control's value. Read/write.

Syntax

expression .Style

expression A variable that represents a ComboBox object.

Remarks

The settings of the Style property are:

Value | Description
0 | The ComboBox behaves as a drop-down combo box. The user can type a value in the edit region or select a value from the drop-down list (default).
2 | The ComboBox behaves as a list box. The user must choose a value from the list.


ComboBox.Text Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Text Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies text in a ComboBox, changing the selected row in the control. Read/write.

Syntax

expression .Text

expression A variable that represents a ComboBox object.

Remarks

The default value is a zero-length string ("").

You can use Text to update the value of the control. If the value of Text matches an existing list entry, the value of the ListIndex property (the index of the current row) is set to the row that matches Text. If the value of Text does not match a row, ListIndex is set to -1.

When the Text property of a ComboBox changes (such as when a user types an entry into the control), the new text is compared to the column of data specified by TextColumn.

You cannot use Text to change the value of an entry in a ComboBox; use the Column or List property for this purpose.

The ForeColor property determines the color of the text.


ComboBox.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a ComboBox object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.

The TextAlign property only affects the edit region; this property has no effect on the alignment of text in the list.


ComboBox.TextColumn Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.TextColumn Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that identifies the column in a ComboBox to display to the user. Read/write.

Syntax

expression .TextColumn

expression A variable that represents a ComboBox object.

Remarks

Values for the TextColumn property range from -1 to the number of columns in the list. The TextColumn value for the first column is 1, the value of the second column is 2, and so on. Setting TextColumn to 0 displays the ListIndex values. Setting TextColumn to -1 displays the first column that has a ColumnWidths value greater than 0.

When the user selects a row from a ComboBox, the column referenced by TextColumn is stored in the Text property. For example, you could set up a multicolumn ComboBox that contains the names of holidays in one column and dates for the holidays in a second column. To present the holiday names to users, specify the first column as the TextColumn. To store the dates of the holidays, specify the second column as the BoundColumn.

When the Text property of a ComboBox changes (such as when a user types an entry into the control), the new text is compared to the column of data specified by TextColumn.


ComboBox.TextLength Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.TextLength Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the length, in number of characters, of text in the edit region of a ComboBox. Read-only.

Syntax

expression .TextLength

expression A variable that represents a ComboBox object.


ComboBox.TopIndex Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.TopIndex Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the index of the item displayed in the topmost position in the list portion of the ComboBox. Read/write.

Syntax

expression .TopIndex

expression A variable that represents a ComboBox object.

Remarks

The default is 0, which identifies the first item in the list.

Returns the value -1 if the list is empty or not displayed.


ComboBox.Value Property (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies the value in the BoundColumn of the currently selected rows. Read/write.

Syntax

expression .Value

expression A variable that represents a ComboBox object.

Remarks

Changing the contents of Value does not change the value of BoundColumn. To add or delete entries in a ComboBox, you can use the AddItem or RemoveItem method.


ComboBox Methods (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Methods (Outlook Forms Script)
Send feedback

In this section

  • ComboBox.AddItem Method (Outlook Forms Script)

  • ComboBox.Clear Method (Outlook Forms Script)

  • ComboBox.Copy Method (Outlook Forms Script)

  • ComboBox.Cut Method (Outlook Forms Script)

  • ComboBox.DropDown Method (Outlook Forms Script)

  • ComboBox.Paste Method (Outlook Forms Script)

  • ComboBox.RemoveItem Method (Outlook Forms Script)


ComboBox.AddItem Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.AddItem Method (Outlook Forms Script)
Send feedback

For a single-column ComboBox, the AddItem method adds an item to the list. For a multicolumn ComboBox, this method adds a row to the list.

Syntax

expression .AddItem(pvargItem, pvargIndex)

expression A variable that represents a ComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargItem | Optional | Variant | Specifies the item or row to add. The number of the first item or row is 0; the number of the second item or row is 1, and so on.
pvargIndex | Optional | Variant | Integer specifying the position within the object where the new item or row is placed.

Remarks

If you supply a valid value for varIndex, the AddItem method places the item or row at that position within the list. If you omit varIndex, the method adds the item or row at the end of the list.

The value of varIndex must not be greater than the value of the ListCount property.

For a multicolumn ComboBox, AddItem inserts an entire row, that is, it inserts an item for each column of the control. To assign values to an item beyond the first column, use the List or Column property and specify the row and column of the item.

If the control is bound to data, the AddItem method fails.

You can add more than one row at a time to a ComboBox by using List.


ComboBox.Clear Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Clear Method (Outlook Forms Script)
Send feedback

Removes all entries in the list in a ComboBox.

Syntax

expression .Clear

expression A variable that represents a ComboBox object.

Remarks

If the control is bound to data, the Clear method fails.


ComboBox.Copy Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Copy Method (Outlook Forms Script)
Send feedback

Copies the contents of an object to the Clipboard.

Syntax

expression .Copy

expression A variable that represents a ComboBox object.

Remarks

The original content remains on the object.

The actual content that is copied depends on the object. For example, on a TextBox or ComboBox, it copies the currently selected text.


ComboBox.Cut Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Cut Method (Outlook Forms Script)
Send feedback

Removes selected information from an object and transfers it to the Clipboard.

Syntax

expression .Cut

expression A variable that represents a ComboBox object.

Remarks

The Cut method removes currently selected text in the control to the Clipboard. This method does not require that the control have the focus.


ComboBox.DropDown Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.DropDown Method (Outlook Forms Script)
Send feedback

Displays the list portion of a ComboBox.

Syntax

expression .DropDown

expression A variable that represents a ComboBox object.

Remarks

Use the DropDown method to open the list in a combo box.


ComboBox.Paste Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Paste Method (Outlook Forms Script)
Send feedback

Transfers the contents of the Clipboard to an object.

Syntax

expression .Paste

expression A variable that represents a ComboBox object.

Remarks

Data pasted into a ComboBox is treated as text.


ComboBox.RemoveItem Method (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.RemoveItem Method (Outlook Forms Script)
Send feedback

Removes a row from the list in a ComboBox.

Syntax

expression .RemoveItem(pvargIndex)

expression A variable that represents a ComboBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargIndex | Required | Variant | Specifies the row to delete. The number of the first row is 0; the number of the second row is 1, and so on.

Return Value

A Boolean that returns True if the method succeeds, False otherwise.


ComboBox Events (Outlook Forms Script)

 Copy code hover
[image]

ComboBox Events (Outlook Forms Script)
Send feedback

In this section

  • ComboBox.Click Event (Outlook Forms Script)


ComboBox.Click Event (Outlook Forms Script)

 Copy code hover
[image]

ComboBox.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user definitively selects a value for the control that has more than one possible value.

Syntax

expression .Click

expression A variable that represents a ComboBox object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

For some controls, the Click event occurs when the Value property changes. However, using the PropertyChange or CustomPropertyChange event is the preferred technique for detecting a new value for a property. The following are examples of actions that initiate the Click event due to assigning a new value to a control: selecting a value for a ComboBox so that it unquestionably matches an item in the control's drop-down list. For example, if a list is not sorted, the first match for characters typed in the edit region may not be the only match in the list, so choosing such a value does not initiate the Click event. In a sorted list, you can use entry-matching to ensure that a selected value is a unique match for text the user types.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.

If you bind a ComboBox to a field, then the Click event does not fire. You need to use the PropertyChange or CustomPropertyChange event to detect the change via code, as in the following code sample:

Copy code Copy code
Sub Item_PropertyChange(ByVal Name)
Set MyListBox = Item.GetInspector.ModifiedFormPages("Message").Controls("ComboBox1")
Select Case Name
 Case "Mileage"
 Item.CC = MyComboBox.Value
 Item.Subject = MyComboBox.Value
 Case Else
End Select
End Sub


CommandButton Object Reference (Outlook Forms Script)

 Copy code hover
[image]

CommandButton Object Reference (Outlook Forms Script)
Send feedback

In this section

  • CommandButton Object (Outlook Forms Script)

  • CommandButton Members (Outlook Forms Script)

  • CommandButton Properties (Outlook Forms Script)

  • CommandButton Events (Outlook Forms Script)


CommandButton Object (Outlook Forms Script)

 Copy code hover
[image]

CommandButton Object (Outlook Forms Script)
Send feedback

Starts, ends, or interrupts an action or series of actions.

Remarks

The macro or event procedure assigned to the CommandButton control's Click event determines what the CommandButton does. For example, you can create a CommandButton that opens another form. You can also display text, a picture, or both on a CommandButton.

The only event for a CommandButton is the Click event.


CommandButton Members (Outlook Forms Script)

 Copy code hover
[image]

CommandButton Members (Outlook Forms Script)
Send feedback

Starts, ends, or interrupts an action or series of actions.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for a control. Read/write.
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
Caption | Returns or sets a String that appears on the button to describe what it does. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PicturePosition | Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.
TakeFocusOnClick | Returns or sets a Boolean that specifies whether a control takes the focus when clicked. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


CommandButton Properties (Outlook Forms Script)

 Copy code hover
[image]

CommandButton Properties (Outlook Forms Script)
Send feedback

In this section

  • CommandButton.Accelerator Property (Outlook Forms Script)

  • CommandButton.AutoSize Property (Outlook Forms Script)

  • CommandButton.BackColor Property (Outlook Forms Script)

  • CommandButton.BackStyle Property (Outlook Forms Script)

  • CommandButton.Caption Property (Outlook Forms Script)

  • CommandButton.Enabled Property (Outlook Forms Script)

  • CommandButton.ForeColor Property (Outlook Forms Script)

  • CommandButton.Locked Property (Outlook Forms Script)

  • CommandButton.MouseIcon Property (Outlook Forms Script)

  • CommandButton.MousePointer Property (Outlook Forms Script)

  • CommandButton.Picture Property (Outlook Forms Script)

  • CommandButton.PicturePosition Property (Outlook Forms Script)

  • CommandButton.TakeFocusOnClick Property (Outlook Forms Script)

  • CommandButton.WordWrap Property (Outlook Forms Script)


CommandButton.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for a control. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a CommandButton object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the control's property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.

When an accelerator key is used, there is no visual feedback (other than focus) to indicate that the control initiated the Click event. For example, if the accelerator key applies to a CommandButton, the user will not see the button pressed in the interface. The button receives the focus, however, when the user presses the accelerator key.


CommandButton.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a CommandButton object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls with captions, the AutoSize property specifies whether the control automatically adjusts to display the entire caption.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


CommandButton.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a CommandButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


CommandButton.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a CommandButton object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


CommandButton.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on the button to describe what it does. Read/write.

Syntax

expression .Caption

expression A variable that represents a CommandButton object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.

Setting AutoSize to True automatically adjusts the size of the control to frame the entire caption.


CommandButton.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a CommandButton object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

You can combine the settings of the Enabled and the TabStop properties to prevent the user from selecting a CommandButton with TAB, while still allowing the user to click the button. Setting TabStop to False means that the CommandButton won't appear in the tab order. However, if Enabled is True, then the user can still click the command button, as long as TakeFocusOnClick is set to True.


CommandButton.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a CommandButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


CommandButton.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a CommandButton object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


CommandButton.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a CommandButton object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


CommandButton.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a CommandButton object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


CommandButton.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a CommandButton object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

For controls with captions, use the PicturePosition property to specify where to display the picture on the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


CommandButton.PicturePosition Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.PicturePosition Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.

Syntax

expression .PicturePosition

expression A variable that represents a CommandButton object.

Remarks

The settings for PicturePosition are:

Value | Description
0 | The picture appears to the left of the caption. The caption is aligned with the top of the picture.
1 | The picture appears to the left of the caption. The caption is centered relative to the picture.
2 | The picture appears to the left of the caption. The caption is aligned with the bottom of the picture.
3 | The picture appears to the right of the caption. The caption is aligned with the top of the picture.
4 | The picture appears to the right of the caption. The caption is centered relative to the picture.
5 | The picture appears to the right of the caption. The caption is aligned with the bottom of the picture.
6 | The picture appears above the caption. The caption is aligned with the left edge of the picture.
7 | The picture appears above the caption. The caption is centered below the picture (default).
8 | The picture appears above the caption. The caption is aligned with the right edge of the picture.
9 | The picture appears below the caption. The caption is aligned with the left edge of the picture.
10 | The picture appears below the caption. The caption is centered above the picture.
11 | The picture appears below the caption. The caption is aligned with the right edge of the picture.
12 | The picture appears in the center of the control. The caption is centered horizontally and vertically on top of the picture.

The picture and the caption, as a unit, are centered on the control. If no caption exists, the picture's location is relative to the center of the control.

This property is ignored if the Picture property does not specify a picture.


CommandButton.TakeFocusOnClick Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.TakeFocusOnClick Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control takes the focus when clicked. Read/write.

Syntax

expression .TakeFocusOnClick

expression A variable that represents a CommandButton object.

Remarks

True if the button takes the focus when clicked (default). False if the button does not take the focus when clicked.

The TakeFocusOnClick property defines only what happens when the user clicks a control. If the user tabs to the control, the control takes the focus regardless of the value of TakeFocusOnClick.

Use this property to complete actions that affect a control without requiring that control to give up focus. For example, assume your form includes a TextBox and a CommandButton that checks for correct spelling of text. You would like to be able to select text in the TextBox, then click the CommandButton and run the spelling checker without taking focus away from the TextBox. You can do this by setting the TakeFocusOnClick property of the CommandButton to False.


CommandButton.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents a CommandButton object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.


CommandButton Events (Outlook Forms Script)

 Copy code hover
[image]

CommandButton Events (Outlook Forms Script)
Send feedback

In this section

  • CommandButton.Click Event (Outlook Forms Script)


CommandButton.Click Event (Outlook Forms Script)

 Copy code hover
[image]

CommandButton.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click

expression A variable that represents a CommandButton object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a CommandButton.

  • Pressing the SPACEBAR when a CommandButton has the focus.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing ENTER on a form that has a command button whose Default property is set to True, as long as no other command button has the focus.

  • Pressing ESC on a form that has a command button whose Cancel property is set to True, as long as no other command button has the focus.

  • Pressing a control's accelerator key.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


Font Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Font Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Font Object (Outlook Forms Script)

  • Font Members (Outlook Forms Script)

  • Font Properties (Outlook Forms Script)


Font Object (Outlook Forms Script)

 Copy code hover
[image]

Font Object (Outlook Forms Script)
Send feedback

Defines the characteristics of the text used by a control.

Remarks

Each control has its own Font object to let you set its text characteristics independently of the characteristics defined for other controls. Use font properties to specify the font name, to set bold, italic, or underlined text, or to adjust the size of the text.


Font Members (Outlook Forms Script)

 Copy code hover
[image]

Font Members (Outlook Forms Script)
Send feedback

Defines the characteristics of the text used by a control.

Properties

Name | Description
Bold | Returns or sets a Boolean that specifies whether text is normal or bold. Read/write.
Italic | Returns or sets a Boolean that specifies whether text is normal or italic. Read/write.
Size | Returns or sets a Currency that indicates the height, in points, of displayed text. Read/write.
Strikethrough | Returns or sets a Boolean that specifies whether the text appears with strikethrough marks. Read/write.
Underline | Returns or sets a Boolean that specifies whether text is underlined. Read/write.
Weight | Returns or sets an Integer that specifies the darkness of the type. Read/write.


Font Properties (Outlook Forms Script)

 Copy code hover
[image]

Font Properties (Outlook Forms Script)
Send feedback

In this section

  • Font.Bold Property (Outlook Forms Script)

  • Font.Italic Property (Outlook Forms Script)

  • Font.Size Property (Outlook Forms Script)

  • Font.Strikethrough Property (Outlook Forms Script)

  • Font.Underline Property (Outlook Forms Script)

  • Font.Weight Property (Outlook Forms Script)


Font.Bold Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Bold Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether text is normal or bold. Read/write.

Syntax

expression .Bold

expression A variable that represents a Font object.

Remarks

True to indicate that the text with this font is bold, False otherwise.

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.

Changing the value of Bold also changes the value of Weight. Setting Bold to True sets Weight to 700; setting Bold to False sets Weight to 400. Conversely, setting Weight to anything over 550 sets Bold to True; setting Weight to 550 or less sets Bold to False.


Font.Italic Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Italic Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether text is normal or italic. Read/write.

Syntax

expression .Italic

expression A variable that represents a Font object.

Remarks

True to indicate that the text with this font is italic, False otherwise.

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.


Font.Size Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Size Property (Outlook Forms Script)
Send feedback

Returns or sets a Currency that indicates the height, in points, of displayed text. Read/write.

Syntax

expression .Size

expression A variable that represents a Font object.

Remarks

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.

The default point size is determined by the operating system.


Font.Strikethrough Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Strikethrough Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the text appears with strikethrough marks. Read/write.

Syntax

expression .Strikethrough

expression A variable that represents a Font object.

Remarks

True to indicate that the text appears with strikethrough marks, False otherwise.

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.


Font.Underline Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Underline Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether text is underlined. Read/write.

Syntax

expression .Underline

expression A variable that represents a Font object.

Remarks

True to indicate that the text is underlined, False otherwise.

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.


Font.Weight Property (Outlook Forms Script)

 Copy code hover
[image]

Font.Weight Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the lthe darkness of the type. Read/write.

Syntax

expression .Weight

expression A variable that represents a Font object.

Remarks

The Weight property accepts values from 0 to 1000. A value of zero allows the system to pick the most appropriate weight. A value from 1 to 1000 indicates a specific weight, where 1 represents the lightest type and 1000 represents the darkest type.

The font's appearance on screen and in print may differ, depending on your computer and printer. If you select a font that your system can't display with the specified attribute or that isn't installed, Windows substitutes a similar font. The substitute font will be as similar as possible to the font originally requested.

Changing the value of Bold also changes the value of Weight. Setting Bold to True sets Weight to 700; setting Bold to False sets Weight to 400. Conversely, setting Weight to anything over 550 sets Bold to True; setting Weight to 550 or less sets Bold to False.


Frame Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Frame Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Frame Object (Outlook Forms Script)

  • Frame Members (Outlook Forms Script)

  • Frame Properties (Outlook Forms Script)

  • Frame Methods (Outlook Forms Script)

  • Frame Events (Outlook Forms Script)


Frame Object (Outlook Forms Script)

 Copy code hover
[image]

Frame Object (Outlook Forms Script)
Send feedback

Represents a functional and visual control group.

Remarks

All option buttons in a Frame are mutually exclusive, so you can use the Frame to create an option group. You can also use a Frame to group controls with closely related contents.For example, in an application that processes customer orders, you might use a Frame to group the name, address, and account number of customers.

You can also use a Frame to create a group of ToggleButton controls, but the toggle buttons are not mutually exclusive.

To create a group of mutually exclusive OptionButton controls, you can put the buttons in a Frame on your form, or you can use the OptionButton.GroupName property.


Frame Members (Outlook Forms Script)

 Copy code hover
[image]

Frame Members (Outlook Forms Script)
Send feedback

Represents a functional and visual control group.

Methods

Name | Description
Copy | Copies the contents of an object to the Clipboard.
Cut | Removes selected information from an object and transfers it to the Clipboard.
Paste | Transfers the contents of the Clipboard to an object.
RedoAction | Reverses the effect of the most recent Undo action.
Repaint | Updates the display by redrawing the frame.
Scroll | Moves the scroll bar on an object.
SetDefaultTabOrder | Sets the TabIndex property of each control on a frame or page, using a default top-to-bottom, left-to-right tab order.
UndoAction | Reverses the most recent action that supports the Undo command.

Properties

Name | Description
ActiveControl | Returns an Object that has the focus. Read-only.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
CanPaste | Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.
CanRedo | Returns a Boolean that specifies if the most recent Undo can be reversed. Read-only.
CanUndo | Returns a Boolean that specifies whether the last user action can be undone. Read-only.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Cycle | Returns or sets an Integer that specifies whether cycling includes controls nested in a Frame. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
InsideHeight | Returns a Long that specifies the height, in points, of the client region inside a Frame. Read-only.
InsideWidth | Returns a Long that specifies the width, in points, of the client region inside a Frame. Read-only.
KeepScrollBarsVisible | Returns or sets an Integer that specifies whether scroll bars remain visible when not required. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PictureAlignment | Returns or sets an Integer that specifies the location of a background picture. Read/write.
PictureSizeMode | Returns or sets an Integer that specifies how to display the background picture on a Frame. Read/write.
PictureTiling | Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.
ScrollBars | Returns or sets an Integer that specifies whether a control has vertical scroll bars, horizontal scroll bars, or both. Read/write.
ScrollHeight | Returns or sets a Single that specifies the height, in points, of the total area that can be viewed by moving the scroll bars on the Frame. Read/write.
ScrollLeft | Returns or sets a Single that specifies the distance, in points, of the left edge of the visible form from the left edge of the Frame. Read/write.
ScrollTop | Returns or sets a Single that specifies the distance, in points, of the top edge of the visible form from the top edge of the Frame. Read/write.
ScrollWidth | Returns or sets a Single that specifies the width, in points, of the total area that can be viewed by moving the scroll bars on the Frame. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
VerticalScrollBarSide | Returns or sets an Integer that specifies whether a vertical scroll bar appears on the right or left side of a frame. Read/write.
Zoom | Returns or sets an Integer that specifies the percentage to increase or decrease the displayed image. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


Frame Properties (Outlook Forms Script)

 Copy code hover
[image]

Frame Properties (Outlook Forms Script)
Send feedback

In this section

  • Frame.ActiveControl Property (Outlook Forms Script)

  • Frame.BackColor Property (Outlook Forms Script)

  • Frame.BorderColor Property (Outlook Forms Script)

  • Frame.BorderStyle Property (Outlook Forms Script)

  • Frame.CanPaste Property (Outlook Forms Script)

  • Frame.CanRedo Property (Outlook Forms Script)

  • Frame.CanUndo Property (Outlook Forms Script)

  • Frame.Caption Property (Outlook Forms Script)

  • Frame.Cycle Property (Outlook Forms Script)

  • Frame.Enabled Property (Outlook Forms Script)

  • Frame.ForeColor Property (Outlook Forms Script)

  • Frame.InsideHeight Property (Outlook Forms Script)

  • Frame.InsideWidth Property (Outlook Forms Script)

  • Frame.KeepScrollBarsVisible Property (Outlook Forms Script)

  • Frame.MouseIcon Property (Outlook Forms Script)

  • Frame.MousePointer Property (Outlook Forms Script)

  • Frame.Picture Property (Outlook Forms Script)

  • Frame.PictureAlignment Property (Outlook Forms Script)

  • Frame.PictureSizeMode Property (Outlook Forms Script)

  • Frame.PictureTiling Property (Outlook Forms Script)

  • Frame.ScrollBars Property (Outlook Forms Script)

  • Frame.ScrollHeight Property (Outlook Forms Script)

  • Frame.ScrollLeft Property (Outlook Forms Script)

  • Frame.ScrollTop Property (Outlook Forms Script)

  • Frame.ScrollWidth Property (Outlook Forms Script)

  • Frame.SpecialEffect Property (Outlook Forms Script)

  • Frame.VerticalScrollBarSide Property (Outlook Forms Script)

  • Frame.Zoom Property (Outlook Forms Script)


Frame.ActiveControl Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ActiveControl Property (Outlook Forms Script)
Send feedback

Returns an Object that has the focus. Read-only.

Syntax

expression .ActiveControl

expression A variable that represents a Frame object.

Remarks

The ActiveControl property is read-only and is set when you select a control or object in the interface. You can use ActiveControl as a substitute for the control name when setting properties or calling methods.


Frame.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a Frame object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


Frame.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents a Frame object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


Frame.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents a Frame object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for a Frame is 0 (None).

For a Frame, the BorderStyle property is ignored if the SpecialEffect property is zero.

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


Frame.CanPaste Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.CanPaste Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.

Syntax

expression .CanPaste

expression A variable that represents a Frame object.

Remarks

True if the object can receive information pasted from the Clipboard, False if the object cannot receive information pasted from the Clipboard.

CanPaste is read-only.

If the Clipboard data is in a format that the object does not support, the CanPaste property is False. For example, if you try to paste a bitmap into an object that only supports text, CanPaste will be False.


Frame.CanRedo Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.CanRedo Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies if the most recent Undo can be reversed. Read-only.

Syntax

expression .CanRedo

expression A variable that represents a Frame object.

Remarks

True if the most recent Undo can be reversed, False otherwise.

CanRedo is read-only.

To Redo means to reverse an Undo; it does not necessrily mean to repeat the last user action.


Frame.CanUndo Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.CanUndo Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the last user action can be undone. Read-only.

Syntax

expression .CanUndo

expression A variable that represents a Frame object.

Remarks

True if the most recent user action can be undone, False if the most recent user action cannot be undone.

CanUndo is read-only.

Many user actions can be undone with the Undo command. The CanUndo property indicates whether the most recent action can be undone.


Frame.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Syntax

expression .Caption

expression A variable that represents a Frame object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.


Frame.Cycle Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.Cycle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether cycling includes controls nested in a Frame. Read/write.

Syntax

expression .Cycle

expression A variable that represents a Frame object.

Remarks

The possible values for Cycle are 0 and 2. 0 represents cycling through the controls on the form and the controls of the Frame that are currently displayed on the form. 2 represents cycling through the controls on the form and the Frame. The focus stays within the form and the Frame until the focus is explicitly set to a control outside the form and the Frame.

If you specify a non-integer value for Cycle, the value is rounded up to the nearest integer.

The tab order identifies the order in which controls receive the focus as the user tabs through a form or subform. The Cycle property determines the action to take when a user tabs from the last control in the tab order.

The 0 setting transfers the focus to the first control of the next Frame on the form when the user tabs from the last control in the tab order.

The 2 setting transfers the focus to the first control of the same form or the Frame when the user tabs from the last control in the tab order.


Frame.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a Frame object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

If a Frame is disabled, all controls that it contains are disabled.


Frame.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a Frame object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.

The ForeColor changes the color of the caption.


Frame.InsideHeight Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.InsideHeight Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the height, in points, of the client region inside a Frame. Read-only.

Syntax

expression .InsideHeight

expression A variable that represents a Frame object.


Frame.InsideWidth Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.InsideWidth Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the width, in points, of the client region inside a Frame. Read-only.

Syntax

expression .InsideWidth

expression A variable that represents a Frame object.


Frame.KeepScrollBarsVisible Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.KeepScrollBarsVisible Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether scroll bars remain visible when not required. Read/write.

Syntax

expression .KeepScrollBarsVisible

expression A variable that represents a Frame object.

Remarks

The settings for KeepScrollBarsVisible are:

Value | Description
0 | Displays no scroll bars.
1 | Displays a horizontal scroll bar.
2 | Displays a vertical scroll bar.
3 | Displays both a horizontal and a vertical scroll bar (default).

If the visible region is large enough to display all the controls on an object such as a Page object, scroll bars are not required. The KeepScrollBarsVisible property determines whether the scroll bars remain visible when they are not required.

If the scroll bars are visible when they are not required, they appear normal in size, and the scroll box fills the entire width or height of the scroll bar.

If the KeepScrollBarsVisible property is True, any scroll bar on a form or page is always visible, regardless of whether the object's contents fit within the object's borders.


Frame.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a Frame object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


Frame.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a Frame object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


Frame.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a Frame object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

Use the PictureSizeMode property to determine how the picture fills the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


Frame.PictureAlignment Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.PictureAlignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of a background picture. Read/write.

Syntax

expression .PictureAlignment

expression A variable that represents a Frame object.

Remarks

The settings for PictureAlignment are:

Value | Description
0 | The top left corner.
1 | The top right corner.
2 | The center.
3 | The bottom left corner.
4 | The bottom right corner.

The PictureAlignment property identifies which corner of the picture is the same as the corresponding corner of the control or container where the picture is used.

For example, setting PictureAlignment to 0 means that the top left corner of the picture coincides with the top left corner of the control or container. Setting PictureAlignment to 2 positions the picture in the middle, relative to the height as well as the width of the control or container.

If you tile an image on a control or container, the setting of PictureAlignment affects the tiling pattern. For example, if PictureAlignment is set to 0, the first copy of the image is laid in the upper left corner of the control or container and additional copies are tiled from left to right across each row. If PictureAlignmentPictureAlignment is 2, the first copy of the image is laid at the center of the control or container, additional copies are laid to the left and right to complete the row, and additional rows are added to fill the control or container.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Frame.PictureSizeMode Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.PictureSizeMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how to display the background picture on a Frame. Read/write.

Syntax

expression .PictureSizeMode

expression A variable that represents a Frame object.

Remarks

The settings for PictureSizeMode are:

Value | Description
0 | Crops any part of the picture that is larger than the form or page (default).
1 | Stretches the picture to fill the form or page. This setting distorts the picture in either the horizontal or vertical direction.
3 | Enlarges the picture, but does not distort the picture in either the horizontal or vertical direction.

The 1 and 3 settings both enlarge the image, but 1 causes distortion. The 1 setting enlarges the image horizontally and vertically until the image reaches the corresponding edges of the container or control. The 3 setting enlarges the image until it reaches either the horizontal or vertical edges of the container or control. If the image reaches the horizontal edges first, any remaining distance to the vertical edges remains blank. If it reaches the vertical edges first, any remaining distance to the horizontal edges remains blank.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Frame.PictureTiling Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.PictureTiling Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.

Syntax

expression .PictureTiling

expression A variable that represents a Frame object.

Remarks

True if the picture is tiled across the background, False otherwise (default).

If a picture is smaller than the form or page that contains it, you can tile the picture on the form or page.

The tiling pattern depends on the current setting of the PictureAlignment and PictureSizeMode properties. For example, if PictureAlignment is set to 0, the tiling pattern starts at the upper left and repeats the picture across the form or page and down the height of the form or page. If PictureSizeMode is set to 0, the tiling pattern crops the last tile if it doesn't completely fit on the form or page.


Frame.ScrollBars Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ScrollBars Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether a control has vertical scroll bars, horizontal scroll bars, or both. Read/write.

Syntax

expression .ScrollBars

expression A variable that represents a Frame object.

Remarks

The settings for ScrollBars are:

Value | Description
0 | Displays no scroll bars (default).
1 | Displays a horizontal scroll bar.
2 | Displays a vertical scroll bar.
3 | Displays both a horizontal and a vertical scroll bar.

If the KeepScrollBarsVisible property is True, any scroll bar on a form or page is always visible, regardless of whether the object's contents fit within the object's borders.

If visible, a scroll bar constrains its scroll box to the visible region of the scroll bar. It also modifies the scroll position as needed to keep the entire scroll bar visible. The range of a scroll bar changes when the value of the ScrollBars property changes, the scroll size changes, or the visible size changes.

If a scroll bar is not visible, then you can set its scroll position to any value. Negative values and values greater than the scroll size are both valid.


Frame.ScrollHeight Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ScrollHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specify the height, in points, of the total area that can be viewed by moving the scroll bars on the Frame. Read/write.

Syntax

expression .ScrollHeight

expression A variable that represents a Frame object.


Frame.ScrollLeft Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ScrollLeft Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specifies the distance, in points, of the left edge of the visible form from the left edge of the Frame. Read/write.

Syntax

expression .ScrollLeft

expression A variable that represents a Frame object.

Remarks

The minimum value is zero; the maximum value is the difference between the value of the ScrollWidth property and the value of the Width property for the form or page.


Frame.ScrollTop Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ScrollTop Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specifies the distance, in points, of the top edge of the visible form from the top edge of the Frame. Read/write.

Syntax

expression .ScrollTop

expression A variable that represents a Frame object.


Frame.ScrollWidth Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.ScrollWidth Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specify the width, in points, of the total area that can be viewed by moving the scroll bars on the Frame. Read/write.

Syntax

expression .ScrollWidth

expression A variable that represents a Frame object.


Frame.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a Frame object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

The default value is 2.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

BorderStyle is ignored if SpecialEffect is 0.

SpecialEffect uses the system colors to define its borders.


Frame.VerticalScrollBarSide Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.VerticalScrollBarSide Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether a vertical scroll bar appears on the right or left side of a frame. Read/write.

Syntax

expression .VerticalScrollBarSide

expression A variable that represents a Frame object.

Remarks

The settings for VerticalScrollBarSide are:

Value | Description
0 | Puts the scroll bar on the right side (default).
1 | Puts the scroll bar on the left side.


Frame.Zoom Property (Outlook Forms Script)

 Copy code hover
[image]

Frame.Zoom Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the percentage to increase or decrease the displayed image. Read/write.

Syntax

expression .Zoom

expression A variable that represents a Frame object.

Remarks

The value of the Zoom property specifies a percentage of image enlargement or reduction by which an image display should change. Values from 10 to 400 are valid. The value specified is a percentage of the object's original size; thus, a setting of 400 means you want to enlarge the image to four times its original size (or 400 percent), while a setting of 10 means you want to reduce the image to one-tenth of its original size (or 10 percent).


Frame Methods (Outlook Forms Script)

 Copy code hover
[image]

Frame Methods (Outlook Forms Script)
Send feedback

In this section

  • Frame.Copy Method (Outlook Forms Script)

  • Frame.Cut Method (Outlook Forms Script)

  • Frame.Paste Method (Outlook Forms Script)

  • Frame.RedoAction Method (Outlook Forms Script)

  • Frame.Repaint Method (Outlook Forms Script)

  • Frame.Scroll Method (Outlook Forms Script)

  • Frame.SetDefaultTabOrder Method (Outlook Forms Script)

  • Frame.UndoAction Method (Outlook Forms Script)


Frame.Copy Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.Copy Method (Outlook Forms Script)
Send feedback

Copies the contents of an object to the Clipboard.

Syntax

expression .Copy

expression A variable that represents a Frame object.

Remarks

The original content remains on the object.

The actual content that is copied depends on the object. Using Copy for a form, Frame, or Page copies the currently active control.


Frame.Cut Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.Cut Method (Outlook Forms Script)
Send feedback

Removes selected information from an object and transfers it to the Clipboard.

Syntax

expression .Cut

expression A variable that represents a Frame object.

Remarks

Cut removes currently selected controls to the Clipboard. This method only removes controls created at run time.


Frame.Paste Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.Paste Method (Outlook Forms Script)
Send feedback

Transfers the contents of the Clipboard to an object.

Syntax

expression .Paste

expression A variable that represents a Frame object.


Frame.RedoAction Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.RedoAction Method (Outlook Forms Script)
Send feedback

Reverses the effect of the most recent Undo action.

Syntax

expression .RedoAction

expression A variable that represents a Frame object.

Return Value

A Boolean that specifies True if the method succeeds, False otherwise.

Remarks

Redo reverses the last Undo, which is not necessarily the last action taken. Not all actions can be undone.


Frame.Repaint Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.Repaint Method (Outlook Forms Script)
Send feedback

Updates the display by redrawing the frame.

Syntax

expression .Repaint

expression A variable that represents a Frame object.

Return Value

A Boolean that returns True if the method succeeds; returns False otherwise.

Remarks

The Repaint method is useful if the contents or appearance of an object changes significantly, and you don't want to wait until the system automatically repaints the area.


Frame.Scroll Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.Scroll Method (Outlook Forms Script)
Send feedback

Moves the scroll bar on an object.

Syntax

expression .Scroll(xAction, yAction)

expression A variable that represents a Frame object.

Parameters

Name | Required/Optional | Data Type | Description
xAction | Optional | Variant | Identifies the action to occur in the horizontal direction.
yAction | Optional | Variant | Identifies the action to occur in the vertical direction.

Remarks

The settings for xAction and yAction are:

Value | Description
0 | Do not scroll in the specified direction.
1 | Move up on a vertical scroll bar or left on a horizontal scroll bar. Movement is equivalent to pressing the up or left arrow key on the keyboard to move the scroll bar.
2 | Move down on a vertical scroll bar or right on a horizontal scroll bar. Movement is equivalent to pressing the right or down arrow key on the keyboard to move the scroll bar.
3 | Move one pageup on a vertical scroll bar or one page left on a horizontal scroll bar. Movement is equivalent to pressing PAGE UP on the keyboard to move the scroll bar.
4 | Move one pagedown on a vertical scroll bar or one page right on a horizontal scroll bar. Movement is equivalent to pressing PAGE DOWN on the keyboard to move the scroll bar.
5 | Move to the top of a vertical scroll bar or to the left end of a horizontal scroll bar.
6 | Move to the bottom of a vertical scroll bar or to the right end of a horizontal scroll bar.

The Scroll method applies scroll bars that appear on a Frame that is larger than its display area. This method does not apply to the stand-alone ScrollBar control or to scroll bars that appear on a TextBox.


Frame.SetDefaultTabOrder Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.SetDefaultTabOrder Method (Outlook Forms Script)
Send feedback

Sets the TabIndex property of each control on a frame or page, using a default top-to-bottom, left-to-right tab order.

Syntax

expression .SetDefaultTabOrder

expression A variable that represents a Frame object.

Remarks

The TabIndex property of a control is a Microsoft Forms 2.0 property.


Frame.UndoAction Method (Outlook Forms Script)

 Copy code hover
[image]

Frame.UndoAction Method (Outlook Forms Script)
Send feedback

Reverses the most recent action that supports the Undo command.

Syntax

expression .UndoAction

expression A variable that represents a Frame object.

Return Value

A Boolean that is True if the method succeeds, False otherwise.

Remarks

Not all user actions can be undone. If an action cannot be undone, the Undo command is unavailable following the action.

You must apply this method before the form or control is updated. You may want to include this method in a form's PropertyChange event.


Frame Events (Outlook Forms Script)

 Copy code hover
[image]

Frame Events (Outlook Forms Script)
Send feedback

In this section

  • Frame.Click Event (Outlook Forms Script)


Frame.Click Event (Outlook Forms Script)

 Copy code hover
[image]

Frame.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click

expression A variable that represents a Frame object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


Image Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Image Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Image Object (Outlook Forms Script)

  • Image Members (Outlook Forms Script)

  • Image Properties (Outlook Forms Script)

  • Image Events (Outlook Forms Script)


Image Object (Outlook Forms Script)

 Copy code hover
[image]

Image Object (Outlook Forms Script)
Send feedback

Displays a picture on a form.

Remarks

The Image control lets you display a picture as part of the data in a form. For example, you might use an Image to display employee photographs in a personnel form.

The Image lets you crop, size, or zoom a picture, but does not allow you to edit the contents of the picture. For example, you cannot use the Image to change the colors in the picture, to make the picture transparent, or to refine the image of the picture. You must use image editing software for these purposes.

The Image supports the following file formats:

  • *.bmp

  • *.cur

  • *.gif

  • *.ico

  • *.jpg

  • *.wmf

You can also display a picture on a Label. However, a Label does not let you crop, size, or zoom the picture.<P>


Image Members (Outlook Forms Script)

 Copy code hover
[image]

Image Members (Outlook Forms Script)
Send feedback

Displays a picture on a form.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PictureAlignment | Returns or sets an Integer that specifies the location of a background picture. Read/write.
PictureSizeMode | Returns or sets an Integer that specifies how to display the background picture on a control. Read/write.
PictureTiling | Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


Image Properties (Outlook Forms Script)

 Copy code hover
[image]

Image Properties (Outlook Forms Script)
Send feedback

In this section

  • Image.AutoSize Property (Outlook Forms Script)

  • Image.BackColor Property (Outlook Forms Script)

  • Image.BackStyle Property (Outlook Forms Script)

  • Image.BorderColor Property (Outlook Forms Script)

  • Image.BorderStyle Property (Outlook Forms Script)

  • Image.Enabled Property (Outlook Forms Script)

  • Image.MouseIcon Property (Outlook Forms Script)

  • Image.MousePointer Property (Outlook Forms Script)

  • Image.Picture Property (Outlook Forms Script)

  • Image.PictureAlignment Property (Outlook Forms Script)

  • Image.PictureSizeMode Property (Outlook Forms Script)

  • Image.PictureTiling Property (Outlook Forms Script)

  • Image.SpecialEffect Property (Outlook Forms Script)


Image.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

Image.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents an Image object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls without captions, this property specifies whether the control automatically adjusts to display the information stored in the control. In a ComboBox, for example, setting AutoSize to True automatically sets the width of the display area to match the length of the current text.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


Image.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

Image.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents an Image object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


Image.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

Image.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents an Image object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


Image.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

Image.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents an Image object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


Image.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

Image.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents an Image object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for an Image is 1 (Single).

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


Image.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

Image.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents an Image object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed. If Enabled is False for an Image, the control does not initiate events but does not appear dimmed.


Image.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

Image.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents an Image object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


Image.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

Image.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents an Image object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


Image.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

Image.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents an Image object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

Use the PictureSizeMode property to determine how the picture fills the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


Image.PictureAlignment Property (Outlook Forms Script)

 Copy code hover
[image]

Image.PictureAlignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of a background picture. Read/write.

Syntax

expression .PictureAlignment

expression A variable that represents an Image object.

Remarks

The settings for PictureAlignment are:

Value | Description
0 | The top left corner.
1 | The top right corner.
2 | The center.
3 | The bottom left corner.
4 | The bottom right corner.

The PictureAlignment property identifies which corner of the picture is the same as the corresponding corner of the control or container where the picture is used.

For example, setting PictureAlignment to 0 means that the top left corner of the picture coincides with the top left corner of the control or container. Setting PictureAlignment to 2 positions the picture in the middle, relative to the height as well as the width of the control or container.

If you tile an image on a control or container, the setting of PictureAlignment affects the tiling pattern. For example, if PictureAlignment is set to 0, the first copy of the image is laid in the upper left corner of the control or container and additional copies are tiled from left to right across each row. If PictureAlignmentPictureAlignment is 2, the first copy of the image is laid at the center of the control or container, additional copies are laid to the left and right to complete the row, and additional rows are added to fill the control or container.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Image.PictureSizeMode Property (Outlook Forms Script)

 Copy code hover
[image]

Image.PictureSizeMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how to display the background picture on a control. Read/write.

Syntax

expression .PictureSizeMode

expression A variable that represents an Image object.

Remarks

The settings for PictureSizeMode are:

Value | Description
0 | Crops any part of the picture that is larger than the form or page (default).
1 | Stretches the picture to fill the form or page. This setting distorts the picture in either the horizontal or vertical direction.
3 | Enlarges the picture, but does not distort the picture in either the horizontal or vertical direction.

The 1 and 3 settings both enlarge the image, but 1 causes distortion. The 1 setting enlarges the image horizontally and vertically until the image reaches the corresponding edges of the container or control. The 3 setting enlarges the image until it reaches either the horizontal or vertical edges of the container or control. If the image reaches the horizontal edges first, any remaining distance to the vertical edges remains blank. If it reaches the vertical edges first, any remaining distance to the horizontal edges remains blank.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Image.PictureTiling Property (Outlook Forms Script)

 Copy code hover
[image]

Image.PictureTiling Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.

Syntax

expression .PictureTiling

expression A variable that represents an Image object.

Remarks

True if the picture is tiled across the background, False otherwise (default).

If a picture is smaller than the form or page that contains it, you can tile the picture on the form or page.

The tiling pattern depends on the current setting of the PictureAlignment and PictureSizeMode properties. For example, if PictureAlignment is set to 0, the tiling pattern starts at the upper left and repeats the picture across the form or page and down the height of the form or page. If PictureSizeMode is set to 0, the tiling pattern crops the last tile if it doesn't completely fit on the form or page.


Image.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

Image.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents an Image object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both. Default for Image.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

SpecialEffect uses the system colors to define its borders.


Image Events (Outlook Forms Script)

 Copy code hover
[image]

Image Events (Outlook Forms Script)
Send feedback

In this section

  • Image.Click Event (Outlook Forms Script)


Image.Click Event (Outlook Forms Script)

 Copy code hover
[image]

Image.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click

expression A variable that represents an Image object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


Label Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Label Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Label Object (Outlook Forms Script)

  • Label Members (Outlook Forms Script)

  • Label Properties (Outlook Forms Script)

  • Label Events (Outlook Forms Script)


Label Object (Outlook Forms Script)

 Copy code hover
[image]

Label Object (Outlook Forms Script)
Send feedback

Displays descriptive text.

Remarks

A Label control on a form displays descriptive text such as titles, captions, pictures, or brief instructions. For example, labels for an address book might include a Label for a name, street, or city.

The default property for a Label is the Caption property.

You can also display a picture on a Label. However, a Label does not let you crop, size, or zoom the picture.


Label Members (Outlook Forms Script)

 Copy code hover
[image]

Label Members (Outlook Forms Script)
Send feedback

Displays descriptive text.

Section Heading

Name | Description
Accelerator | Returns or sets the accelerator key for a control. Read/write.
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PicturePosition | Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


Label Properties (Outlook Forms Script)

 Copy code hover
[image]

Label Properties (Outlook Forms Script)
Send feedback

In this section

  • Label.Accelerator Property (Outlook Forms Script)

  • Label.AutoSize Property (Outlook Forms Script)

  • Label.BackColor Property (Outlook Forms Script)

  • Label.BackStyle Property (Outlook Forms Script)

  • Label.BorderColor Property (Outlook Forms Script)

  • Label.BorderStyle Property (Outlook Forms Script)

  • Label.Caption Property (Outlook Forms Script)

  • Label.Enabled Property (Outlook Forms Script)

  • Label.ForeColor Property (Outlook Forms Script)

  • Label.MouseIcon Property (Outlook Forms Script)

  • Label.MousePointer Property (Outlook Forms Script)

  • Label.Picture Property (Outlook Forms Script)

  • Label.PicturePosition Property (Outlook Forms Script)

  • Label.SpecialEffect Property (Outlook Forms Script)

  • Label.TextAlign Property (Outlook Forms Script)

  • Label.WordWrap Property (Outlook Forms Script)


Label.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

Label.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for a control. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a Label object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the control's property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.

When an accelerator key is used, there is no visual feedback (other than focus) to indicate that the control initiated the Click event. For example, if the accelerator key applies to a CommandButton, the user will not see the button pressed in the interface. The button receives the focus, however, when the user presses the accelerator key.


Label.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

Label.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a Label object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls with captions, the AutoSize property specifies whether the control automatically adjusts to display the entire caption.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


Label.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

Label.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a Label object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


Label.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

Label.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a Label object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


Label.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

Label.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents a Label object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


Label.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

Label.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents a Label object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for a Label is 0 (None).

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


Label.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

Label.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Syntax

expression .Caption

expression A variable that represents a Label object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.

Setting AutoSize to True automatically adjusts the size of the control to frame the entire caption.


Label.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

Label.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a Label object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.


Label.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

Label.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a Label object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


Label.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

Label.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a Label object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


Label.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

Label.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a Label object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


Label.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

Label.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a Label object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

For controls with captions, use the PicturePosition property to specify where to display the picture on the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


Label.PicturePosition Property (Outlook Forms Script)

 Copy code hover
[image]

Label.PicturePosition Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.

Syntax

expression .PicturePosition

expression A variable that represents a Label object.

Remarks

The settings for PicturePosition are:

Value | Description
0 | The picture appears to the left of the caption. The caption is aligned with the top of the picture.
1 | The picture appears to the left of the caption. The caption is centered relative to the picture.
2 | The picture appears to the left of the caption. The caption is aligned with the bottom of the picture.
3 | The picture appears to the right of the caption. The caption is aligned with the top of the picture.
4 | The picture appears to the right of the caption. The caption is centered relative to the picture.
5 | The picture appears to the right of the caption. The caption is aligned with the bottom of the picture.
6 | The picture appears above the caption. The caption is aligned with the left edge of the picture.
7 | The picture appears above the caption. The caption is centered below the picture (default).
8 | The picture appears above the caption. The caption is aligned with the right edge of the picture.
9 | The picture appears below the caption. The caption is aligned with the left edge of the picture.
10 | The picture appears below the caption. The caption is centered above the picture.
11 | The picture appears below the caption. The caption is aligned with the right edge of the picture.
12 | The picture appears in the center of the control. The caption is centered horizontally and vertically on top of the picture.

The picture and the caption, as a unit, are centered on the control. If no caption exists, the picture's location is relative to the center of the control.

This property is ignored if the Picture property does not specify a picture.


Label.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

Label.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a Label object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both. Default for Label.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

SpecialEffect uses the system colors to define its borders.


Label.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

Label.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a Label object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.

For stand-alone labels, TextAlign determines the alignment of the label's caption.


Label.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

Label.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents a Label object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.


Label Events (Outlook Forms Script)

 Copy code hover
[image]

Label Events (Outlook Forms Script)
Send feedback

In this section

  • Label.Click Event (Outlook Forms Script)


Label.Click Event (Outlook Forms Script)

 Copy code hover
[image]

Label.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click

expression A variable that represents a Label object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


ListBox Object Reference (Outlook Forms Script)

 Copy code hover
[image]

ListBox Object Reference (Outlook Forms Script)
Send feedback

In this section

  • ListBox Object (Outlook Forms Script)

  • ListBox Members (Outlook Forms Script)

  • ListBox Properties (Outlook Forms Script)

  • ListBox Methods (Outlook Forms Script)

  • ListBox Events (Outlook Forms Script)


ListBox Object (Outlook Forms Script)

 Copy code hover
[image]

ListBox Object (Outlook Forms Script)
Send feedback

Displays a list of values and lets you select one or more.

Remarks

If the ListBox is bound to a data source, the ListBox stores the selected value in that data source.

The ListBox can either appear as a list or as a group of OptionButton controls or CheckBox controls.

The default property for a ListBox is the Value property.

The default event for a ListBox is the Click event.

You can't drop text into a drop-down ListBox.

ListBox styles

You can choose between two presentation styles for a ListBox. This is expressed by the ListStyle property. Each style provides different ways for users to select items in the list.

If the style is 0, each item is on a separate row; the user selects an item by highlighting one or more rows.

If the style is 1, an OptionButton or CheckBox appears at the beginning of each row. With this style, the user selects an item by clicking the option button or check box. Check boxes appear only when the MultiSelect property is True.


ListBox Members (Outlook Forms Script)

 Copy code hover
[image]

ListBox Members (Outlook Forms Script)
Send feedback

Displays a list of values and lets you select one or more.

Methods

Name | Description
AddItem | For a single-column ListBox, the AddItem method adds an item to the list. For a multicolumn ListBox, this method adds a row to the list.
Clear | Removes all entries in the list in a ListBox.
RemoveItem | Removes a row from the list in a ListBox.

Properties

Name | Description
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
BoundColumn | Returns or sets a Variant that identifies the source of data in a multicolumn ListBox. Read/write.
Column | Returns or sets a Variant that represents a single value, a column of values, or a two-dimensional array to load into a ListBox. Read/write.
ColumnCount | Returns or sets a Long that represents the number of columns to display in a list box. Read/write.
ColumnHeads | Returns or sets a Boolean that specifies whether a single row of column headings are displayed. Read/write.
ColumnWidths | Returns or sets a String that specifies the width of each column in a multicolumn ListBox. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
IMEMode | Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.
IntegralHeight | Returns or sets a Boolean that specifies whether a ListBox displays full lines of text in a list or partial lines. Read/write.
List | Returns or sets a Variant that represents the specified entry in a ListBox. Read/write.
ListCount | Returns a Long that represents the number of list entries in a control. Read-only.
ListIndex | Returns or sets a Variant that represents the currently selected item in a ListBox. Read/write.
ListStyle | Returns or sets an Integer that specifies the visual appearance of the list in a ListBox. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MatchEntry | Returns or sets an Integer that indicates how a ListBox searches its list as the user types. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
MultiSelect | Returns or sets an Integer that indicates whether the object permits multiple selections. Read/write.
Selected | Returns or sets a Boolean that indicates the selection state of items in a ListBox. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
Text | Returns or sets a String that specifies text in a ListBox, changing the selected row in the control. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TextColumn | Returns or sets a Variant that identifies the column in a ListBox to display to the user. Read/write.
TopIndex | Returns or sets a Long that represents the index of the list item displayed in the topmost position in the list. Read/write.
Value | Returns or sets a Variant that specifies the value in the BoundColumn of the currently selected rows. Read/write.

Events

Name | Description
Click | Occurs when the user definitively selects a value for the control that has more than one possible value.


ListBox Properties (Outlook Forms Script)

 Copy code hover
[image]

ListBox Properties (Outlook Forms Script)
Send feedback

In this section

  • ListBox.BackColor Property (Outlook Forms Script)

  • ListBox.BorderColor Property (Outlook Forms Script)

  • ListBox.BorderStyle Property (Outlook Forms Script)

  • ListBox.BoundColumn Property (Outlook Forms Script)

  • ListBox.Column Property (Outlook Forms Script)

  • ListBox.ColumnCount Property (Outlook Forms Script)

  • ListBox.ColumnHeads Property (Outlook Forms Script)

  • ListBox.ColumnWidths Property (Outlook Forms Script)

  • ListBox.Enabled Property (Outlook Forms Script)

  • ListBox.ForeColor Property (Outlook Forms Script)

  • ListBox.IMEMode Property (Outlook Forms Script)

  • ListBox.IntegralHeight Property (Outlook Forms Script)

  • ListBox.List Property (Outlook Forms Script)

  • ListBox.ListCount Property (Outlook Forms Script)

  • ListBox.ListIndex Property (Outlook Forms Script)

  • ListBox.ListStyle Property (Outlook Forms Script)

  • ListBox.Locked Property (Outlook Forms Script)

  • ListBox.MatchEntry Property (Outlook Forms Script)

  • ListBox.MouseIcon Property (Outlook Forms Script)

  • ListBox.MousePointer Property (Outlook Forms Script)

  • ListBox.MultiSelect Property (Outlook Forms Script)

  • ListBox.Selected Property (Outlook Forms Script)

  • ListBox.SpecialEffect Property (Outlook Forms Script)

  • ListBox.Text Property (Outlook Forms Script)

  • ListBox.TextAlign Property (Outlook Forms Script)

  • ListBox.TextColumn Property (Outlook Forms Script)

  • ListBox.TopIndex Property (Outlook Forms Script)

  • ListBox.Value Property (Outlook Forms Script)


ListBox.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a ListBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


ListBox.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents a ListBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


ListBox.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents a ListBox object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for a ListBox is 0 (None).

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


ListBox.BoundColumn Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.BoundColumn Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that identifies the source of data in a multicolumn ListBox. Read/write.

Syntax

expression .BoundColumn

expression A variable that represents a ListBox object.

Remarks

The possible values of BoundColumn are 0 and 1. 0 assigns the value of the ListIndex property to the control. 1 assigns the value from the specified column to the control. Columns are numbered from 1 when using this property (default).

When the user chooses a row in a multicolumn ListBox or ComboBox, the BoundColumn property identifies which item from that row to store as the value of the control. For example, if each row contains 8 items and BoundColumn is 3, the system stores the information in the third column of the currently-selected row as the value of the object.

You can display one set of data to users but store different, associated values for the object by using the BoundColumn and the TextColumn properties. TextColumn identifies the column of data displayed in a ComboBox or ListBox; BoundColumn identifies the column of associated data values stored for the control. For example, you could set up a multicolumn ListBox that contains the names of holidays in one column and dates for the holidays in a second column. To present the holiday names to users, specify the first column as the TextColumn. To store the dates of the holidays, specify the second column as the BoundColumn.

The ListIndex value retrieves the number of the selected row. For example, if you want to know the row of the selected item, set BoundColumn to 0 to assign the number of the selected row as the value of the control. Be sure to retrieve a current value, rather than relying on a previously saved value, if you are referencing a list whose contents might change.

The Column, List, and ListIndex properties all use zero-based numbering. That is, the value of the first item (column or row) is zero; the value of the second item is one, and so on. This means that if BoundColumn is set to 3, you could access the value stored in that column using the expression Column(2).


ListBox.Column Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Column Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents a single value, a column of values, or a two-dimensional array to load into a ListBox. Read/write.

Syntax

expression .Column(pvargColumn, pvargIndex)

expression A variable that represents a ListBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargColumn | Optional | Variant | An integer with a range from 0 to one less than the total number of columns.
pvargIndex | Optional | Variant | An integer with a range from 0 to one less than the total number of rows.

Remarks

If you specify both the column and row values, Column reads or writes a specific item.

If you specify only the column value, the Column property reads or writes the specified column in the current row of the object. For example, MyListBox.Column (3) reads or writes the third column in MyListBox.

Column returns a Variant from the cursor. When a built-in cursor provides the value for Variant (such as when using the AddItem method), the value is a String. When an external cursor provides the value for Variant, formatting associated with the data is not included in the Variant.

You can use Column to assign the contents of a combo box or list box to another control, such as a text box.

If the user makes no selection when you refer to a column in a combo box or list box, the Column setting is Null. You can check for this condition by using the IsNull function.

You can also use Column to copy an entire two-dimensional array of values to a control. This syntax lets you quickly load a list of choices rather than individually loading each element of the list using AddItem.

When copying data from a two-dimensional array, Column transposes the contents of the array in the control so that the contents of ListBox1.Column(X, Y) is the same as MyArray(Y, X). You can also use the List property to copy an array without transposing it.


ListBox.ColumnCount Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ColumnCount Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the number of columns to display in a list box. Read/write.

Syntax

expression .ColumnCount

expression A variable that represents a ListBox object.

Remarks

If you set the ColumnCount property for a list box to 3 on an employee form, one column can list last names, another can list first names, and the third can list employee ID numbers.

Setting ColumnCount to 0 displays zero columns, and setting it to -1 displays all the available columns. For an unbound data source, there is a 10-column limit (0 to 9).

You can use the ColumnWidths property to set the width of the columns displayed in the control.


ListBox.ColumnHeads Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ColumnHeads Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a single row of column headings are displayed. Read/write.

Syntax

expression .ColumnHeads

expression A variable that represents a ListBox object.

Remarks

True if column headings are to be displayed, False otherwise (default).

Setting this property to True displays a blank row as column headings. However, currently there is no way to specify the text for column headings.


ListBox.ColumnWidths Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ColumnWidths Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the width of each column in a multicolumn ListBox. Read/write.

Syntax

expression .ColumnWidths

expression A variable that represents a ListBox object.

Remarks

ColumnWidths sets the column width in points. A setting of -1 or blank results in a calculated width. A width of 0 hides a column. To specify a different unit of measurement, include the unit of measure. A value greater than 0 explicitly specifies the width of the column.

To separate column entries, use semicolons (;) as list separators. Or use the list separator specified in Regional Settings of the Windows Control Panel.

Any or all of the ColumnWidths property settings can be blank. You create a blank setting by typing a list separator without a preceding value.

If you specify a -1 in the property page, the displayed value in the property page is a blank.

To calculate column widths when ColumnWidths is blank or -1, the width of the control is divided equally among all columns of the list. If the sum of the specified column widths exceeds the width of the control, the list is left-aligned within the control and one or more of the rightmost columns are not displayed. Users can scroll the list using the horizontal scroll bar to display the rightmost columns.

The minimum calculated column width is 72 points (1 inch). To produce columns narrower than this, you must specify the width explicitly.

Unless specified otherwise, column widths are measured in points. To specify another unit of measure, include the units as part of the values. The following examples specify column widths in several units of measure and describe how the various settings would fit in a three-column list box that is 4 inches wide.

Setting | Effect
90;72;90 | The first column is 90 points (1.25 inch); the second column is 72 points (1 inch); the third column is 90 points.
6 cm;0;6 cm | The first column is 6 centimeters; the second column is hidden; the third column is 6 centimeters. Because part of the third column is visible, a horizontal scroll bar appears.
1.5 in;0;2.5 in | The first column is 1.5 inches, the second column is hidden, and the third column is 2.5 inches.
2 in;;2 in | The first column is 2 inches, the second column is 1 inch (default), and the third column is 2 inches. Because only half of the third column is visible, a horizontal scroll bar appears.
(Blank) | All three columns are the same width (1.33 inches).


ListBox.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a ListBox object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

Clicking a disabled ListBox does not initiate the Click event.


ListBox.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a ListBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


ListBox.IMEMode Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.IMEMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.

Syntax

expression .IMEMode

expression A variable that represents a ListBox object.

Remarks

This property applies only to applications written for Asian languages and is ignored in other applications.

The settings for fmIMEMode are:

Value | Description
0 | Does not control IME (default).
1 | IME on.
2 | IME off. English mode.
3 | IME off. User can't turn on IME by keyboard.
4 | IME on with Full-width Hiragana mode.
5 | IME on with Full-width Katakana mode.
6 | IME on with Half-width Katakana mode.
7 | IME on with Full-width Alphanumeric mode.
8 | IME on with Half-width Alphanumeric mode.
9 | IME on with Full-width Hangul mode.
10 | IME on with Half-width Hangul mode.

A setting of 0 indicates that the mode of the IME does not change when the control receives focus at run time. For any other value, the mode of the IME is set to the value specified by the IMEMode property when the control receives focus at run time.


ListBox.IntegralHeight Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.IntegralHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a ListBox displays full lines of text in a list or partial lines. Read/write.

Syntax

expression .IntegralHeight

expression A variable that represents a ListBox object.

Remarks

True indicates that the list resizes itself to display only complete items (default). False indicates that the list does not resize itself even if the item is too tall to display completely.

The IntegralHeight property relates to the height of the list, just as the AutoSize property relates to the width of the list.

If IntegralHeight is True, the list box automatically resizes when necessary to show full rows. If False, the list remains a fixed size; if items are taller than the available space in the list, the entire item is not shown.


ListBox.List Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.List Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents the specified entry in a ListBox. Read/write.

Syntax

expression .List(pvargIndex, pvargColumn)

expression A variable that represents a ListBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargIndex | Optional | Variant | An integer with a range from 0 to one less than the number of entries in the list.
pvargColumn | Optional | Variant | An integer with a range from 0 to one less than the number of columns in the list.

Remarks

Row and column numbering begins with zero. That is, the row number of the first row in the list is zero; the column number of the first column is zero. The number of the second row or column is 1, and so on.

The List property works with the ListCount and ListIndex properties. Use List to access list items. A list is a variant array; each item in the list has a row number and a column number.

Initially, a ListBox contains an empty list.

To specify items you want to display in a ListBox, use the AddItem method. To remove items, use the RemoveItem method.

Use List to copy an entire two-dimensional array of values to a control. Use AddItem to load a one-dimensional array or to load an individual element.


ListBox.ListCount Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ListCount Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the number of list entries in a control. Read-only.

Syntax

expression .ListCount

expression A variable that represents a ListBox object.

Remarks

ListCount is the number of rows over which you can scroll. ListCount is always one greater than the largest value for the ListIndex property, because index numbers begin with 0 and the count of items begins with 1. If no item is selected, ListCount is 0 and ListIndex is -1.


ListBox.ListIndex Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ListIndex Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that represents the currently selected item in a ListBox. Read/write.

Syntax

expression .ListIndex

expression A variable that represents a ListBox object.

Remarks

The ListIndex property contains an index of the selected row in a list. Values of ListIndex range from -1 to one less than the total number of rows in a list (that is, ListCount - 1). When no rows are selected, ListIndex returns -1. When the user selects a row in a ListBox or ComboBox, the system sets the ListIndex value. The ListIndex value of the first row in a list is 0, the value of the second row is 1, and so on.

If you use the MultiSelect property to create a ListBox that allows multiple selections, the Selected property of the ListBox (rather than the ListIndex property) identifies the selected rows. The Selected property is an array with the same number of values as the number of rows in the ListBox. For each row in the list box, Selected is True if the row is selected and False if it is not. In a ListBox that allows multiple selections, ListIndex returns the index of the row that has focus, regardless of whether that row is currently selected.

The ListIndex value is also available by setting the BoundColumn property to 0 for a list box. If BoundColumn is 0, the underlying data source to which the list box is bound contains the same list index value as ListIndex.


ListBox.ListStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.ListStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of the list in a ListBox. Read/write.

Syntax

expression .ListStyle

expression A variable that represents a ListBox object.

Remarks

The settings for ListStyle are:

Value | Description
0 | Looks like a regular list box, with the background of items highlighted.
1 | Shows option buttons, or check boxes for a multi-select list (default). When the user selects an item from the group, the option button associated with that item is selected and the option buttons for the other items in the group are deselected.

The ListStyle property lets you change the visual presentation of a ListBox. By specifying a setting other than 0, you can present the contents of either control as a group of individual items, with each item including a visual cue to indicate whether it is selected.

If the list box supports a single selection (the MultiSelect property is set to 0), the user can press one button in the group. If the control supports multi-select, the user can press two or more buttons in the group.


ListBox.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a ListBox object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


ListBox.MatchEntry Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.MatchEntry Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates how a ListBox searches its list as the user types. Read/write.

Syntax

expression .MatchEntry

expression A variable that represents a ListBox object.

Remarks

The settings for MatchEntry are:

Value | Description
0 | Basic matching. The control searches for the next entry that starts with the character entered. Repeatedly typing the same letter cycles through all entries beginning with that letter.
1 | Extended matching. As each character is typed, the control searches for an entry matching all characters entered (default).
2 | No matching.

The MatchEntry property searches entries from the TextColumn property of a ListBox or ComboBox.

The control searches the column identified by TextColumn for an entry that matches the user's typed entry. Upon finding a match, the row containing the match is selected, the contents of the column are displayed, and the contents of its BoundColumn property become the value of the control. If the match is unambiguous, finding the match initiates the Click event.

The control initiates the Click event as soon as the user types a sequence of characters that match exactly one entry in the list. As the user types, the entry is compared with the current row in the list and with the next row in the list. When the entry matches only the current row, the match is unambiguous.

In Microsoft Forms, this is true regardless of whether the list is sorted. This means the control finds the first occurrence that matches the entry, based on the order of items in the list. For example, entering either "abc" or "bc" will initiate the Click event for the following list:

Copy code Copy code
abcde
bcdef
abcxyz
bchij

Note that in either case, the matched entry is not unique; however, it is sufficiently different from the adjacent entry that the control interprets the match as unambiguous and initiates the Click event.


ListBox.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a ListBox object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


ListBox.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a ListBox object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


ListBox.MultiSelect Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.MultiSelect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates whether the object permits multiple selections. Read/write.

Syntax

expression .MultiSelect

expression A variable that represents a ListBox object.

Remarks

The settings for MultiSelect are:

Value | Description
0 | Only one item can be selected (default).
1 | Pressing the SPACEBAR or clicking selects or deselects an item in the list.
2 | Pressing SHIFT and clicking the mouse, or pressing SHIFT and one of the arrow keys, extends the selection from the previously selected item to the current item. Pressing CTRL and clicking the mouse selects or deselects an item.

When the MultiSelect property is set to 1 or 2, you must use the list box's Selected property to determine the selected items. Also, the Value property of the control is always Null.

The ListIndex property returns the index of the row with the keyboard focus.


ListBox.Selected Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Selected Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that indicates the selection state of items in a ListBox. Read/write.

Syntax

expression .Selected(pvargIndex)

expression A variable that represents a ListBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargIndex | Required | Variant | An integer with a range from 0 to one less than the number of items in the list.

Remarks

True to indicate that the specified item is selected, False if it is not selected.

The Selected property is useful when users can make multiple selections. You can use this property to determine the selected rows in a multi-select list box. You can also use this property to select or deselect rows in a list from code.

The default value of this property is based on the current selection state of the ListBox.

For single-selection list boxes, the Value or ListIndex properties are recommended for getting and setting the selection. In this case, ListIndex returns the index of the selected item. However, in a multiple selection, ListIndex returns the index of the row contained within the focus rectangle, regardless of whether the row is actually selected.

When a list box control's MultiSelect property is set to 0, only one row can have its Selected property set to True.

Entering a value that is out of range for the index does not generate an error message, but does not set a property for any item in the list.


ListBox.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a ListBox object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

SpecialEffect uses the system colors to define its borders.


ListBox.Text Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Text Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies text in a ListBox, changing the selected row in the control. Read/write.

Syntax

expression .Text

expression A variable that represents a ListBox object.

Remarks

The default value is a zero-length string ("").

The value of Text must match an existing list entry. Specifying a value that does not match an existing list entry causes an error.

You cannot use Text to change the value of an entry in a ListBox; use the Column or List property for this purpose.

The ForeColor property determines the color of the text.


ListBox.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a ListBox object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.


ListBox.TextColumn Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.TextColumn Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that identifies the column in a ListBox to display to the user. Read/write.

Syntax

expression .TextColumn

expression A variable that represents a ListBox object.

Remarks

Values for the TextColumn property range from -1 to the number of columns in the list. The TextColumn value for the first column is 1, the value of the second column is 2, and so on. Setting TextColumn to 0 displays the ListIndex values. Setting TextColumn to -1 displays the first column that has a ColumnWidths value greater than 0.

When the user selects a row from a ComboBox or ListBox, the column referenced by TextColumn is stored in the Text property. For example, you could set up a multicolumn ListBox that contains the names of holidays in one column and dates for the holidays in a second column. To present the holiday names to users, specify the first column as the TextColumn. To store the dates of the holidays, specify the second column as the BoundColumn.

When the Text property of a ComboBoxComboBox changes (such as when a user types an entry into the control), the new text is compared to the column of data specified by TextColumn.


ListBox.TopIndex Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.TopIndex Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the index of the list item displayed in the topmost position in the list. Read/write.

Syntax

expression .TopIndex

expression A variable that represents a ListBox object.

Remarks

The default is 0, which identifies the first item in the list.

Returns the value -1 if the list is empty or not displayed.


ListBox.Value Property (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies the value in the BoundColumn of the currently selected rows. Read/write.

Syntax

expression .Value

expression A variable that represents a ListBox object.

Remarks

Value cannot be used with a multi-select ListBox.


ListBox Methods (Outlook Forms Script)

 Copy code hover
[image]

ListBox Methods (Outlook Forms Script)
Send feedback

In this section

  • ListBox.AddItem Method (Outlook Forms Script)

  • ListBox.Clear Method (Outlook Forms Script)

  • ListBox.RemoveItem Method (Outlook Forms Script)


ListBox.AddItem Method (Outlook Forms Script)

 Copy code hover
[image]

ListBox.AddItem Method (Outlook Forms Script)
Send feedback

For a single-column ListBox, the AddItem method adds an item to the list. For a multicolumn ListBox, this method adds a row to the list.

Syntax

expression .AddItem(pvargItem, pvargIndex)

expression A variable that represents a ListBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargItem | Optional | Variant | Specifies the item or row to add. The number of the first item or row is 0; the number of the second item or row is 1, and so on.
pvargIndex | Optional | Variant | Integer specifying the position within the object where the new item or row is placed.

Remarks

If you supply a valid value for varIndex, the AddItem method places the item or row at that position within the list. If you omit varIndex, the method adds the item or row at the end of the list.

The value of varIndex must not be greater than the value of the ListCount property.

For a multicolumn ListBox, AddItem inserts an entire row, that is, it inserts an item for each column of the control. To assign values to an item beyond the first column, use the List or Column property and specify the row and column of the item.

If the control is bound to data, the AddItem method fails.

You can add more than one row at a time to a ListBox by using List.


ListBox.Clear Method (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Clear Method (Outlook Forms Script)
Send feedback

Removes all entries in the list in a ListBox.

Syntax

expression .Clear

expression A variable that represents a ListBox object.

Remarks

If the control is bound to data, the Clear method fails.


ListBox.RemoveItem Method (Outlook Forms Script)

 Copy code hover
[image]

ListBox.RemoveItem Method (Outlook Forms Script)
Send feedback

Removes a row from the list in a ListBox.

Syntax

expression .RemoveItem(pvargIndex)

expression A variable that represents a ListBox object.

Parameters

Name | Required/Optional | Data Type | Description
pvargIndex | Required | Variant | Specifies the row to delete. The number of the first row is 0; the number of the second row is 1, and so on.

Return Value

A Boolean that returns True if the method succeeds, False otherwise.

Remarks

This method will not remove a row from the list if the ListBox is data bound.


ListBox Events (Outlook Forms Script)

 Copy code hover
[image]

ListBox Events (Outlook Forms Script)
Send feedback

In this section

  • ListBox.Click Event (Outlook Forms Script)


ListBox.Click Event (Outlook Forms Script)

 Copy code hover
[image]

ListBox.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user definitively selects a value for the control that has more than one possible value.

Syntax

expression .Click

expression A variable that represents a ListBox object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

For some controls, the Click event occurs when the Value property changes. However, using the PropertyChange or CustomPropertyChange event is the preferred technique for detecting a new value for a property. The following are examples of actions that initiate the Click event due to assigning a new value to a control: selecting a value for a ListBox so that it unquestionably matches an item in the control's drop-down list. For example, if a list is not sorted, the first match for characters typed in the edit region may not be the only match in the list, so choosing such a value does not initiate the Click event. In a sorted list, you can use entry-matching to ensure that a selected value is a unique match for text the user types.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.

If you bind a ListBox to a field, then the Click event does not fire. You need to use the PropertyChange or CustomPropertyChange event to detect the change via code, as in the following code sample:

Copy code Copy code
Sub Item_PropertyChange(ByVal Name)
Set MyListBox = Item.GetInspector.ModifiedFormPages("Message").Controls("ListBox1")
Select Case Name
 Case "Mileage"
 Item.CC = MyListBox.Value
 Item.Subject = MyListBox.Value
 Case Else
End Select
End Sub


MultiPage Object Reference (Outlook Forms Script)

 Copy code hover
[image]

MultiPage Object Reference (Outlook Forms Script)
Send feedback

In this section

  • MultiPage Object (Outlook Forms Script)

  • MultiPage Members (Outlook Forms Script)

  • MultiPage Properties (Outlook Forms Script)

  • MultiPage Events (Outlook Forms Script)


MultiPage Object (Outlook Forms Script)

 Copy code hover
[image]

MultiPage Object (Outlook Forms Script)
Send feedback

Presents multiple screens of information as a single set.

Remarks

A MultiPage is useful when you work with a large amount of information that can be sorted into several categories. For example, use a MultiPage to display information from an employment application. One page might contain personal information such as name and address; another page might list previous employers; a third page might list references. The MultiPage lets you visually combine related information, while keeping the entire record readily accessible.

New pages are added to the right of the currently selected page rather than adjacent to it.

A MultiPage is a control that contains a collection of one or more pages.

Each Page of a MultiPage is a form that contains its own controls, and as such, can have a unique layout. Typically, the pages in a MultiPage have tabs so the user can select the individual pages.

By default, a MultiPage includes two pages, called Page1 and Page2. Each of these is a Page object, and together they represent the Pages collection of the MultiPage. If you add more pages, they become part of the same Pages collection.

The default property for a MultiPage is the Value property, which returns the index of the currently active Page in the Pages collection of the MultiPage.

The MultiPage control does not support the Click event.


MultiPage Members (Outlook Forms Script)

 Copy code hover
[image]

MultiPage Members (Outlook Forms Script)
Send feedback

Presents multiple screens of information as a single set.

Properties

Name | Description
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
MultiRow | Returns or sets a Boolean that specifies whether the control has more than one row of tabs. Read/write.
SelectedItem | Returns an Object that indicates the currently selected Page object. Read-only.
Style | Returns or sets an Integer that identifies the style of the tabs on the control. Read/write.
TabFixedHeight | Returns or sets a Single that represents the height in points of the tabs on a MultiPage. Read/write.
TabFixedWidth | Returns or sets a Single that represents the width in points of the tabs on a MultiPage. Read/write.
TabOrientation | Returns or sets an Integer that specifies the location of the tabs on a MultiPage. Read/write.
Value | Returns or sets a Variant that indicates the currently active page. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


MultiPage Properties (Outlook Forms Script)

 Copy code hover
[image]

MultiPage Properties (Outlook Forms Script)
Send feedback

In this section

  • MultiPage.BackColor Property (Outlook Forms Script)

  • MultiPage.Enabled Property (Outlook Forms Script)

  • MultiPage.ForeColor Property (Outlook Forms Script)

  • MultiPage.MultiRow Property (Outlook Forms Script)

  • MultiPage.SelectedItem Property (Outlook Forms Script)

  • MultiPage.Style Property (Outlook Forms Script)

  • MultiPage.TabFixedHeight Property (Outlook Forms Script)

  • MultiPage.TabFixedWidth Property (Outlook Forms Script)

  • MultiPage.TabOrientation Property (Outlook Forms Script)

  • MultiPage.Value Property (Outlook Forms Script)


MultiPage.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a MultiPage object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


MultiPage.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a MultiPage object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

When the user tabs into an enabled MultiPage, the first page in the control receives the focus. If the first page of a MultiPage is disabled, the first enabled page of that control receives the focus. If all pages of a MultiPage are disabled, the control is disabled and cannot receive the focus.


MultiPage.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a MultiPage object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


MultiPage.MultiRow Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.MultiRow Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the control has more than one row of tabs. Read/write.

Syntax

expression .MultiRow

expression A variable that represents a MultiPage object.

Remarks

True to allow more than one row of tabs, False to restrict tabs to a single row (default).

The width and number of tabs determines the number of rows. Changing the control's size also changes the number of rows. This allows the developer to resize the control and ensure that tabs wrap to fit the control. If the MultiRow property is False, then truncation occurs if the width of the tabs exceeds the width of the control.


MultiPage.SelectedItem Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.SelectedItem Property (Outlook Forms Script)
Send feedback

Returns an Object that indicates the currently selected Page object. Read-only.

Syntax

expression .SelectedItem

expression A variable that represents a MultiPage object.

Remarks

The SelectedItem property is read-only. Use SelectedItem to programmatically control the currently selected Page object. For example, you can use SelectedItem to assign values to properties of a Page object.


MultiPage.Style Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.Style Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that identifies the style of the tabs on the control. Read/write.

Syntax

expression .Style

expression A variable that represents a MultiPage object.

Remarks

The settings of the Style property are:

Value | Description
0 | Displays tabs on the tab bar (default).
1 | Displays buttons on the tab bar.
2 | Does not display the tab bar.


MultiPage.TabFixedHeight Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.TabFixedHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that represents the height in points of the tabs on a MultiPage. Read/write.

Syntax

expression .TabFixedHeight

expression A variable that represents a MultiPage object.

Remarks

The minimum size is 4 points.


MultiPage.TabFixedWidth Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.TabFixedWidth Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that represents the width in points of the tabs on a MultiPage. Read/write.

Syntax

expression .TabFixedWidth

expression A variable that represents a MultiPage object.

Remarks

If the value is 0, tab widths are automatically adjusted so that each tab is wide enough to accommodate its contents and each row of tabs spans the width of the control.

If the value is greater than 0, all tabs have an identical width as specified by this property.

The minimum size is 4 points.


MultiPage.TabOrientation Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.TabOrientation Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the tabs on a MultiPage. Read/write.

Syntax

expression .TabOrientation

expression A variable that represents a MultiPage object.

Remarks

The settings for TabOrientation are:

Value | Description
0 | The tabs appear at the top of the control (default).
1 | The tabs appear at the bottom of the control.
2 | The tabs appear at the left side of the control.
3 | The tabs appear at the right side of the control.

If you use TrueType fonts, the text rotates when the TabOrientation property is set to 2 or 3. If you use bitmapped fonts, the text does not rotate.


MultiPage.Value Property (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that indicates the currently active page. Read/write.

Syntax

expression .Value

expression A variable that represents a MultiPage object.

Remarks

Zero (0) indicates the first page. The maximum value is one less than the number of pages.


MultiPage Events (Outlook Forms Script)

 Copy code hover
[image]

MultiPage Events (Outlook Forms Script)
Send feedback

In this section

  • MultiPage.Click Event (Outlook Forms Script)


MultiPage.Click Event (Outlook Forms Script)

 Copy code hover
[image]

MultiPage.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click(Index, )

expression A variable that represents a MultiPage object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long |

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


OptionButton Object Reference (Outlook Forms Script)

 Copy code hover
[image]

OptionButton Object Reference (Outlook Forms Script)
Send feedback

In this section

  • OptionButton Object (Outlook Forms Script)

  • OptionButton Members (Outlook Forms Script)

  • OptionButton Properties (Outlook Forms Script)

  • OptionButton Events (Outlook Forms Script)


OptionButton Object (Outlook Forms Script)

 Copy code hover
[image]

OptionButton Object (Outlook Forms Script)
Send feedback

Shows the selection status of one item in a group of choices.

Remarks

Use an OptionButton to show whether a single item in a group is selected. Note that each OptionButton in a Frame is mutually exclusive.

If an OptionButton is bound to a data source, the OptionButton can show the value of that data source as either Yes/No, True/False, or On/Off. If the user selects the OptionButton, the current setting is Yes, True, or On. If the user does not select the OptionButton, the setting is No, False, or Off. For example, an OptionButton in an inventory-tracking application might show whether an item is discontinued. If the OptionButton is bound to a data source, then changing the setting changes the value of that data source. A disabled OptionButton is dimmed and does not show a value.

Depending on the value of the TripleState property, an OptionButton can also have a Null value.

You can also use an OptionButton inside a group box to select one or more of a group of related items. For example, you can create an order form with a list of available items, with an OptionButton preceding each item. The user can select a particular item by checking the corresponding OptionButtonOptionButton.

The default property for an OptionButton is the Value property.


OptionButton Members (Outlook Forms Script)

 Copy code hover
[image]

OptionButton Members (Outlook Forms Script)
Send feedback

Shows the selection status of one item in a group of choices.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for a control. Read/write.
Alignment | Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
GroupName | Returns or sets a String that identifies a group of mutually exclusive OptionButton controls. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PicturePosition | Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TripleState | Returns or sets a Boolean that determines whether the OptionButton supports the Null state. Read/write.
Value | Returns or sets a Variant that specifies whether the option button is selected. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Events

Name | Description
Click | Occurs when the user definitively selects a value for the control that has more than one possible value, or when the value changes to True.


OptionButton Properties (Outlook Forms Script)

 Copy code hover
[image]

OptionButton Properties (Outlook Forms Script)
Send feedback

In this section

  • OptionButton.Accelerator Property (Outlook Forms Script)

  • OptionButton.Alignment Property (Outlook Forms Script)

  • OptionButton.AutoSize Property (Outlook Forms Script)

  • OptionButton.BackColor Property (Outlook Forms Script)

  • OptionButton.BackStyle Property (Outlook Forms Script)

  • OptionButton.Caption Property (Outlook Forms Script)

  • OptionButton.Enabled Property (Outlook Forms Script)

  • OptionButton.ForeColor Property (Outlook Forms Script)

  • OptionButton.GroupName Property (Outlook Forms Script)

  • OptionButton.Locked Property (Outlook Forms Script)

  • OptionButton.MouseIcon Property (Outlook Forms Script)

  • OptionButton.MousePointer Property (Outlook Forms Script)

  • OptionButton.Picture Property (Outlook Forms Script)

  • OptionButton.PicturePosition Property (Outlook Forms Script)

  • OptionButton.SpecialEffect Property (Outlook Forms Script)

  • OptionButton.TextAlign Property (Outlook Forms Script)

  • OptionButton.TripleState Property (Outlook Forms Script)

  • OptionButton.Value Property (Outlook Forms Script)

  • OptionButton.WordWrap Property (Outlook Forms Script)


OptionButton.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for a control. Read/write.

Syntax

expression .Accelerator

expression A variable that represents an OptionButton object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the control's property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.

When an accelerator key is used, there is no visual feedback (other than focus) to indicate that the control initiated the Click event. For example, if the accelerator key applies to a CommandButton, the user will not see the button pressed in the interface. The button receives the focus, however, when the user presses the accelerator key.


OptionButton.Alignment Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Alignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.

Syntax

expression .Alignment

expression A variable that represents an OptionButton object.

Remarks

The possible values of Alignment is 0 or 1. A value of 0 places the caption to the left of the control. A value of 1 places the caption to the right of the control (default).

The caption text for a control is left-aligned.


OptionButton.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents an OptionButton object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls with captions, the AutoSize property specifies whether the control automatically adjusts to display the entire caption.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


OptionButton.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents an OptionButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


OptionButton.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents an OptionButton object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


OptionButton.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Syntax

expression .Caption

expression A variable that represents an OptionButton object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.

Setting AutoSize to True automatically adjusts the size of the control to frame the entire caption.


OptionButton.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents an OptionButton object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


OptionButton.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents an OptionButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


OptionButton.GroupName Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.GroupName Property (Outlook Forms Script)
Send feedback

Returns or sets a String that identifies a group of mutually exclusive OptionButton controls. Read/write.

Syntax

expression .GroupName

expression A variable that represents an OptionButton object.

Remarks

Use the same GroupName for all buttons in the group. The default setting is an empty string.

To create a group of mutually exclusive OptionButton controls, you can put the buttons in a Frame on your form, or you can use the GroupName property. GroupName is more efficient for the following reasons:

  • You do not have to include a Frame for each group. By not using a Frame, you reduce the number of controls on the form, and in turn, improve performance and reduce the size of the form.

  • You have more design flexibility. If you use a Frame to create the group, all the buttons must be inside the Frame. If you want more than one group, you must have one Frame for each group. However, if you use GroupName to create the group, the group can include option buttons anywhere on the form. If you want more than one group, specify a unique name for each group; you can still place the individual controls anywhere on the form.

  • You can create buttons with transparent backgrounds, which can improve the visual appearance of your form. The Frame is not a transparent control.

Regardless of which method you use to create the group of buttons, clicking one button in a group sets all other buttons in the same group to False. All option buttons with the same GroupName within a single container are mutually exclusive. You can use the same group name in two containers, but doing so creates two groups (one in each container) rather than one group that includes both containers.

For example, assume your form includes some option buttons and a MultiPage that also includes option buttons. The option buttons on the MultiPage are one group and the buttons on the form are another group. The two groups do not affect each other. Changing the setting of a button on the MultiPage does not affect the buttons on the form.


OptionButton.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents an OptionButton object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


OptionButton.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents an OptionButton object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


OptionButton.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents an OptionButton object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


OptionButton.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents an OptionButton object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

For controls with captions, use the PicturePosition property to specify where to display the picture on the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


OptionButton.PicturePosition Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.PicturePosition Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.

Syntax

expression .PicturePosition

expression A variable that represents an OptionButton object.

Remarks

The settings for PicturePosition are:

Value | Description
0 | The picture appears to the left of the caption. The caption is aligned with the top of the picture.
1 | The picture appears to the left of the caption. The caption is centered relative to the picture.
2 | The picture appears to the left of the caption. The caption is aligned with the bottom of the picture.
3 | The picture appears to the right of the caption. The caption is aligned with the top of the picture.
4 | The picture appears to the right of the caption. The caption is centered relative to the picture.
5 | The picture appears to the right of the caption. The caption is aligned with the bottom of the picture.
6 | The picture appears above the caption. The caption is aligned with the left edge of the picture.
7 | The picture appears above the caption. The caption is centered below the picture (default).
8 | The picture appears above the caption. The caption is aligned with the right edge of the picture.
9 | The picture appears below the caption. The caption is aligned with the left edge of the picture.
10 | The picture appears below the caption. The caption is centered above the picture.
11 | The picture appears below the caption. The caption is aligned with the right edge of the picture.
12 | The picture appears in the center of the control. The caption is centered horizontally and vertically on top of the picture.

The picture and the caption, as a unit, are centered on the control. If no caption exists, the picture's location is relative to the center of the control.

This property is ignored if the Picture property does not specify a picture.


OptionButton.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents an OptionButton object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them. Default for OptionButton, valid for all controls (default).

SpecialEffect uses the system colors to define its borders.


OptionButton.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents an OptionButton object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.


OptionButton.TripleState Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.TripleState Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that determines whether the OptionButton supports the Null state. Read/write.

Syntax

expression .TripleState

expression A variable that represents an OptionButton object.

Remarks

True if the control clicks through three states, False if the control only supports two states, True and False (default).

Although the TripleState property exists on the OptionButton, the property does not affect the action of the control. Regardless of the value of TripleState, you cannot set the control to Null through the user interface.

Regardless of the property setting, the Null value can always be assigned programmatically to an OptionButton, causing that control to appear shaded.

When the TripleState property is True, a user can choose from the values of Null, True, and False. The null value is displayed as a shaded button.

When TripleState is False, the user can choose either True or False.

A control set to Null does not initiate the Click event.


OptionButton.Value Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies whether the option button is selected. Read/write.

Syntax

expression .Value

expression A variable that represents an OptionButton object.

Remarks

The settings for Value are:

Control | Description
Null | Indicates the item is in a null state, neither selected nor cleared.
True | Indicates the item is selected.
False | Indicates the item is cleared.
Zero (0) | Indicates the first page. The maximum value is one less than the number of pages.


OptionButton.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents an OptionButton object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.


OptionButton Events (Outlook Forms Script)

 Copy code hover
[image]

OptionButton Events (Outlook Forms Script)
Send feedback

In this section

  • OptionButton.Click Event (Outlook Forms Script)


OptionButton.Click Event (Outlook Forms Script)

 Copy code hover
[image]

OptionButton.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user definitively selects a value for the control that has more than one possible value, or when the value changes to True.

Syntax

expression .Click

expression A variable that represents an OptionButton object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

For some controls, the Click event occurs when the Value property changes. However, using the PropertyChange or CustomPropertyChange event is the preferred technique for detecting a new value for a property. The following are examples of actions that initiate the Click event due to assigning a new value to a control: changing the value of an OptionButton to True, and setting one OptionButton in a group to True sets all other buttons in the group to False, but the Click event occurs only for the button whose value changes to True.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.

If you bind an OptionButton to a field, then the Click event does not fire. You need to use the PropertyChange or CustomPropertyChange event to detect the change via code, as in the following code sample:

Copy code Copy code
Sub Item_PropertyChange(ByVal Name)
Set MyListBox = Item.GetInspector.ModifiedFormPages("Message").Controls("OptionButton1")
Select Case Name
    Case "Mileage"
        Item.CC = MyOptionButton.Value
        Item.Subject = MyOptionButton.Value
    Case Else
End Select
End Sub


Page Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Page Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Page Object (Outlook Forms Script)

  • Page Members (Outlook Forms Script)

  • Page Properties (Outlook Forms Script)

  • Page Methods (Outlook Forms Script)


Page Object (Outlook Forms Script)

 Copy code hover
[image]

Page Object (Outlook Forms Script)
Send feedback

Represents one page of a MultiPage or a single member of a Pages collection.

Remarks

Each Page object contains its own set of controls and does not necessarily rely on other pages in the collection for information. A Page inherits some properties from its container; the value of each inherited property is set by the container.

You can reference a Page by its index value. The index value reflects the ordinal position of the Page within the collection. The index of the first Page in a collection is 0; the index of the second Page is 1; and so on.

The default name for the first Page is Page1. The default name for the second Page is Page2.


Page Members (Outlook Forms Script)

 Copy code hover
[image]

Page Members (Outlook Forms Script)
Send feedback

Represents one page of a MultiPage or a single member of a Pages collection.

Methods

Name | Description
Copy | Copies the contents of an object to the Clipboard.
Cut | Removes selected information from an object and transfers it to the Clipboard.
Paste | Transfers the contents of the Clipboard to an object.
RedoAction | Reverses the effect of the most recent Undo action.
Repaint | Updates the display by redrawing the page.
Scroll | Moves the scroll bar on an object.
SetDefaultTabOrder | Sets the TabIndex property of each control on a frame or page, using a default top-to-bottom, left-to-right tab order.
UndoAction | Reverses the most recent action that supports the Undo command.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for the page. Read/write.
ActiveControl | Returns an Object that has the focus. Read-only.
CanPaste | Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.
CanRedo | Returns a Boolean that specifies if the most recent Undo can be reversed. Read-only.
CanUndo | Returns a Boolean that specifies whether the last user action can be undone. Read-only.
Caption | Returns or sets a String that specifies the text that appears on the page. Read/write.
ControlTipText | Returns and sets a String that specifies text that appears when the user briefly holds the mouse pointer over a control without clicking. Read/write.
Cycle | Returns or sets an Integer that specifies whether cycling includes controls nested in a MultiPage. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
Index | Returns or sets an Integer that specifies the position of a Page object in a Pages collection. Read/write.
InsideHeight | Returns a Long that specifies the height, in points, of the client region inside a Page. Read-only.
InsideWidth | Returns a Long that specifies the width, in points, of the client region inside a Page. Read-only.
KeepScrollBarsVisible | Returns or sets an Integer that specifies whether scroll bars remain visible when not required. Read/write.
Name | Returns or sets a String that specifies the name of an object. Read/write.
Parent | Returns an Object that represents the parent object of the specified page. Read-only.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PictureAlignment | Returns or sets an Integer that specifies the location of a background picture. Read/write.
PictureSizeMode | Returns or sets an Integer that specifies how to display the background picture on a page. Read/write.
PictureTiling | Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.
ScrollBars | Returns or sets an Integer that specifies whether a page has vertical scroll bars, horizontal scroll bars, or both. Read/write.
ScrollHeight | Returns or sets a Single that specifies the height, in points, of the total area that can be viewed by moving the scroll bars on the Page. Read/write.
ScrollLeft | Returns or sets a Single that specifies the distance, in points, of the left edge of the visible form from the left edge of the Page. Read/write.
ScrollTop | Returns or sets a Single that specifies the distance, in points, of the top edge of the visible form from the top edge of the Page. Read/write.
ScrollWidth | Returns or sets a Single that specifies the width, in points, of the total area that can be viewed by moving the scroll bars on the Page. Read/write.
Tag | Returns or sets a String that specifies additional information about an object. Read/write.
VerticalScrollBarSide | Returns or sets an Integer that specifies whether a vertical scroll bar appears on the right or left side of a page. Read/write.
Visible | Returns or sets a Boolean that specifies whether a Page is visible or hidden. Read/write.
Zoom | Returns or sets an Integer that specifies the percentage to increase or decrease the displayed image. Read/write.


Page Properties (Outlook Forms Script)

 Copy code hover
[image]

Page Properties (Outlook Forms Script)
Send feedback

In this section

  • Page.Accelerator Property (Outlook Forms Script)

  • Page.ActiveControl Property (Outlook Forms Script)

  • Page.CanPaste Property (Outlook Forms Script)

  • Page.CanRedo Property (Outlook Forms Script)

  • Page.CanUndo Property (Outlook Forms Script)

  • Page.Caption Property (Outlook Forms Script)

  • Page.ControlTipText Property (Outlook Forms Script)

  • Page.Cycle Property (Outlook Forms Script)

  • Page.Enabled Property (Outlook Forms Script)

  • Page.Index Property (Outlook Forms Script)

  • Page.InsideHeight Property (Outlook Forms Script)

  • Page.InsideWidth Property (Outlook Forms Script)

  • Page.KeepScrollBarsVisible Property (Outlook Forms Script)

  • Page.Name Property (Outlook Forms Script)

  • Page.Parent Property (Outlook Forms Script)

  • Page.Picture Property (Outlook Forms Script)

  • Page.PictureAlignment Property (Outlook Forms Script)

  • Page.PictureSizeMode Property (Outlook Forms Script)

  • Page.PictureTiling Property (Outlook Forms Script)

  • Page.ScrollBars Property (Outlook Forms Script)

  • Page.ScrollHeight Property (Outlook Forms Script)

  • Page.ScrollLeft Property (Outlook Forms Script)

  • Page.ScrollTop Property (Outlook Forms Script)

  • Page.ScrollWidth Property (Outlook Forms Script)

  • Page.Tag Property (Outlook Forms Script)

  • Page.VerticalScrollBarSide Property (Outlook Forms Script)

  • Page.Visible Property (Outlook Forms Script)

  • Page.Zoom Property (Outlook Forms Script)


Page.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for the page. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a Page object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.


Page.ActiveControl Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ActiveControl Property (Outlook Forms Script)
Send feedback

Returns an Object that has the focus. Read-only.

Syntax

expression .ActiveControl

expression A variable that represents a Page object.

Remarks

The ActiveControl property is read-only and is set when you select a control or object in the interface. You can use ActiveControl as a substitute for the control name when setting properties or calling methods.


Page.CanPaste Property (Outlook Forms Script)

 Copy code hover
[image]

Page.CanPaste Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.

Syntax

expression .CanPaste

expression A variable that represents a Page object.

Remarks

True if the object can receive information pasted from the Clipboard, False if the object cannot receive information pasted from the Clipboard.

CanPaste is read-only.

If the Clipboard data is in a format that the object does not support, the CanPaste property is False. For example, if you try to paste a bitmap into an object that only supports text, CanPaste will be False.


Page.CanRedo Property (Outlook Forms Script)

 Copy code hover
[image]

Page.CanRedo Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies if the most recent Undo can be reversed. Read-only.

Syntax

expression .CanRedo

expression A variable that represents a Page object.

Remarks

True if the most recent Undo can be reversed, False otherwise.

CanRedo is read-only.

To Redo means to reverse an Undo; it does not necessrily mean to repeat the last user action.


Page.CanUndo Property (Outlook Forms Script)

 Copy code hover
[image]

Page.CanUndo Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the last user action can be undone. Read-only.

Syntax

expression .CanUndo

expression A variable that represents a Page object.

Remarks

True if the most recent user action can be undone, False if the most recent user action cannot be undone.

CanUndo is read-only.

Many user actions can be undone with the Undo command. The CanUndo property indicates whether the most recent action can be undone.


Page.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the text that appears on the page. Read/write.

Syntax

expression .Caption

expression A variable that represents a Page object.

Remarks

The default caption for an object is a unique name based on the type of object. For example, CommandButton1 is the default caption for the first command button in a form.

If an object's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.


Page.ControlTipText Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ControlTipText Property (Outlook Forms Script)
Send feedback

Returns and sets a String that specifies text that appears when the user briefly holds the mouse pointer over a control without clicking. Read/write.

Syntax

expression .ControlTipText

expression A variable that represents a Page object.

Remarks

The ControlTipText property lets you give users tips about a control in a running form. The property can be set during design time but only appears by the control during run time.

The default value of ControlTipText is an empty string. When the value of ControlTipText is set to an empty string, no tip is available for that control.


Page.Cycle Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Cycle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether cycling includes controls nested in a MultiPage. Read/write.

Syntax

expression .Cycle

expression A variable that represents a Page object.

Remarks

The possible values for Cycle are 0 and 2. 0 represents cycling through the controls on the form and the controls of the MultiPage that are currently displayed on the form. 2 represents cycling through the controls on the form and the MultiPage. The focus stays within the form and the MultiPage until the focus is explicitly set to a control outside the form and the MultiPage.

If you specify a non-integer value for Cycle, the value is rounded up to the nearest integer.

The tab order identifies the order in which controls receive the focus as the user tabs through a form or subform. The Cycle property determines the action to take when a user tabs from the last control in the tab order.

The 0 setting transfers the focus to the first control of the next MultiPage on the form when the user tabs from the last control in the tab order.

The 2 setting transfers the focus to the first control of the same form or the MultiPage when the user tabs from the last control in the tab order.


Page.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a Page object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

When the user tabs into an enabled MultiPage, the first page in the control receives the focus. If the first page of a MultiPage is disabled, the first enabled page of that control receives the focus. If all pages of a MultiPage are disabled, the control is disabled and cannot receive the focus.


Page.Index Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Index Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the position of a Page object in a Pages collection. Read/write.

Syntax

expression .Index

expression A variable that represents a Page object.

Remarks

The Index property specifies the order in which tabs appear. Changing the value of Index visually changes the order of pages in a MultiPage. The index value for the first page is zero, the index value of the second page is one, and so on.

In a MultiPage, Index refers to a Page as well as the page's Tab.


Page.InsideHeight Property (Outlook Forms Script)

 Copy code hover
[image]

Page.InsideHeight Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the height, in points, of the client region inside a Page. Read-only.

Syntax

expression .InsideHeight

expression A variable that represents a Page object.


Page.InsideWidth Property (Outlook Forms Script)

 Copy code hover
[image]

Page.InsideWidth Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the width, in points, of the client region inside a Page. Read-only.

Syntax

expression .InsideWidth

expression A variable that represents a Page object.


Page.KeepScrollBarsVisible Property (Outlook Forms Script)

 Copy code hover
[image]

Page.KeepScrollBarsVisible Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether scroll bars remain visible when not required. Read/write.

Syntax

expression .KeepScrollBarsVisible

expression A variable that represents a Page object.

Remarks

The settings for KeepScrollBarsVisible are:

Value | Description
0 | Displays no scroll bars.
1 | Displays a horizontal scroll bar.
2 | Displays a vertical scroll bar.
3 | Displays both a horizontal and a vertical scroll bar (default).

If the visible region is large enough to display all the controls on an object such as a Page object, scroll bars are not required. The KeepScrollBarsVisible property determines whether the scroll bars remain visible when they are not required.

If the scroll bars are visible when they are not required, they appear normal in size, and the scroll box fills the entire width or height of the scroll bar.

If the KeepScrollBarsVisible property is True, any scroll bar on a form or page is always visible, regardless of whether the object's contents fit within the object's borders.


Page.Name Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Name Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the name of an object. Read/write.

Syntax

expression .Name

expression A variable that represents a Page object.

Remarks

Guidelines for assigning a string to Name, such as the maximum length of the name, vary from one application to another.

For objects, the default value of Name consists of the object's class name followed by an integer. For example, the default name for the first TextBox you place on a form is TextBox1. The default name for the second TextBox is TextBox2.

You can set the Name property for a control from the control's property sheet or, for controls added at run time, by using program statements. If you add a control at design time, you cannot modify its Name property at run time.


Page.Parent Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Parent Property (Outlook Forms Script)
Send feedback

Returns an Object that represents the parent object of the specified page. Read-only.

Syntax

expression .Parent

expression A variable that represents a Page object.

Remarks

Use the Parent property to access the controls on the parent object of a given page.


Page.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a Page object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

Use the PictureSizeMode property to determine how the picture fills the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


Page.PictureAlignment Property (Outlook Forms Script)

 Copy code hover
[image]

Page.PictureAlignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of a background picture. Read/write.

Syntax

expression .PictureAlignment

expression A variable that represents a Page object.

Remarks

The settings for PictureAlignment are:

Value | Description
0 | The top left corner.
1 | The top right corner.
2 | The center.
3 | The bottom left corner.
4 | The bottom right corner.

The PictureAlignment property identifies which corner of the picture is the same as the corresponding corner of the control or container where the picture is used.

For example, setting PictureAlignment to 0 means that the top left corner of the picture coincides with the top left corner of the control or container. Setting PictureAlignment to 2 positions the picture in the middle, relative to the height as well as the width of the control or container.

If you tile an image on a control or container, the setting of PictureAlignment affects the tiling pattern. For example, if PictureAlignment is set to 0, the first copy of the image is laid in the upper left corner of the control or container and additional copies are tiled from left to right across each row. If PictureAlignmentPictureAlignment is 2, the first copy of the image is laid at the center of the control or container, additional copies are laid to the left and right to complete the row, and additional rows are added to fill the control or container.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Page.PictureSizeMode Property (Outlook Forms Script)

 Copy code hover
[image]

Page.PictureSizeMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how to display the background picture on a page. Read/write.

Syntax

expression .PictureSizeMode

expression A variable that represents a Page object.

Remarks

The settings for PictureSizeMode are:

Value | Description
0 | Crops any part of the picture that is larger than the form or page (default).
1 | Stretches the picture to fill the form or page. This setting distorts the picture in either the horizontal or vertical direction.
3 | Enlarges the picture, but does not distort the picture in either the horizontal or vertical direction.

The 1 and 3 settings both enlarge the image, but 1 causes distortion. The 1 setting enlarges the image horizontally and vertically until the image reaches the corresponding edges of the container or control. The 3 setting enlarges the image until it reaches either the horizontal or vertical edges of the container or control. If the image reaches the horizontal edges first, any remaining distance to the vertical edges remains blank. If it reaches the vertical edges first, any remaining distance to the horizontal edges remains blank.

Setting the PictureSizeMode property to 2 overrides PictureAlignment. When PictureSizeMode is set to 2, the picture fills the entire control or container.


Page.PictureTiling Property (Outlook Forms Script)

 Copy code hover
[image]

Page.PictureTiling Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a picture is repeated across the background of the object. Read/write.

Syntax

expression .PictureTiling

expression A variable that represents a Page object.

Remarks

True if the picture is tiled across the background, False otherwise (default).

If a picture is smaller than the form or page that contains it, you can tile the picture on the form or page.

The tiling pattern depends on the current setting of the PictureAlignment and PictureSizeMode properties. For example, if PictureAlignment is set to 0, the tiling pattern starts at the upper left and repeats the picture across the form or page and down the height of the form or page. If PictureSizeMode is set to 0, the tiling pattern crops the last tile if it doesn't completely fit on the form or page.


Page.ScrollBars Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ScrollBars Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether a page has vertical scroll bars, horizontal scroll bars, or both. Read/write.

Syntax

expression .ScrollBars

expression A variable that represents a Page object.

Remarks

The settings for ScrollBars are:

Value | Description
0 | Displays no scroll bars (default).
1 | Displays a horizontal scroll bar.
2 | Displays a vertical scroll bar.
3 | Displays both a horizontal and a vertical scroll bar.

If the KeepScrollBarsVisible property is True, any scroll bar on a form or page is always visible, regardless of whether the object's contents fit within the object's borders.

If visible, a scroll bar constrains its scroll box to the visible region of the scroll bar. It also modifies the scroll position as needed to keep the entire scroll bar visible. The range of a scroll bar changes when the value of the ScrollBars property changes, the scroll size changes, or the visible size changes.

If a scroll bar is not visible, then you can set its scroll position to any value. Negative values and values greater than the scroll size are both valid.


Page.ScrollHeight Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ScrollHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specify the height, in points, of the total area that can be viewed by moving the scroll bars on the Page. Read/write.

Syntax

expression .ScrollHeight

expression A variable that represents a Page object.


Page.ScrollLeft Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ScrollLeft Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specifies the distance, in points, of the left edge of the visible form from the left edge of the Page. Read/write.

Syntax

expression .ScrollLeft

expression A variable that represents a Page object.

Remarks

The minimum value is zero; the maximum value is the difference between the value of the ScrollWidth property and the value of the Width property for the form or page.


Page.ScrollTop Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ScrollTop Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specifies the distance, in points, of the top edge of the visible form from the top edge of the Page. Read/write.

Syntax

expression .ScrollTop

expression A variable that represents a Page object.


Page.ScrollWidth Property (Outlook Forms Script)

 Copy code hover
[image]

Page.ScrollWidth Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that specify the width, in points, of the total area that can be viewed by moving the scroll bars on the Page. Read/write.

Syntax

expression .ScrollWidth

expression A variable that represents a Page object.


Page.Tag Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Tag Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies additional information about an object. Read/write.

Syntax

expression .Tag

expression A variable that represents a Page object.

Remarks

The default is a zero-length string ("").

Use the Tag property to assign an identification string to an object without affecting other property settings or attributes.

For example, you can use Tag to check the identity of a form or control that is passed as a variable to a procedure.


Page.VerticalScrollBarSide Property (Outlook Forms Script)

 Copy code hover
[image]

Page.VerticalScrollBarSide Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether a vertical scroll bar appears on the right or left side of a page. Read/write.

Syntax

expression .VerticalScrollBarSide

expression A variable that represents a Page object.

Remarks

The settings for VerticalScrollBarSide are:

Value | Description
0 | Puts the scroll bar on the right side (default).
1 | Puts the scroll bar on the left side.


Page.Visible Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Visible Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a Page is visible or hidden. Read/write.

Syntax

expression .Visible

expression A variable that represents a Page object.

Remarks

True to specify the page is visible (default), False to specify the page is hidden.

Use the Visible property to control access to information without displaying it. For example, you could use the value of a control on a hidden form as the criteria for a query.

All pages are visible at design time.


Page.Zoom Property (Outlook Forms Script)

 Copy code hover
[image]

Page.Zoom Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the percentage to increase or decrease the displayed image. Read/write.

Syntax

expression .Zoom

expression A variable that represents a Page object.

Remarks

The value of the Zoom property specifies a percentage of image enlargement or reduction by which an image display should change. Values from 10 to 400 are valid. The value specified is a percentage of the object's original size; thus, a setting of 400 means you want to enlarge the image to four times its original size (or 400 percent), while a setting of 10 means you want to reduce the image to one-tenth of its original size (or 10 percent).


Page Methods (Outlook Forms Script)

 Copy code hover
[image]

Page Methods (Outlook Forms Script)
Send feedback

In this section

  • Page.Copy Method (Outlook Forms Script)

  • Page.Cut Method (Outlook Forms Script)

  • Page.Paste Method (Outlook Forms Script)

  • Page.RedoAction Method (Outlook Forms Script)

  • Page.Repaint Method (Outlook Forms Script)

  • Page.Scroll Method (Outlook Forms Script)

  • Page.SetDefaultTabOrder Method (Outlook Forms Script)

  • Page.UndoAction Method (Outlook Forms Script)


Page.Copy Method (Outlook Forms Script)

 Copy code hover
[image]

Page.Copy Method (Outlook Forms Script)
Send feedback

Copies the contents of an object to the Clipboard.

Syntax

expression .Copy

expression A variable that represents a Page object.

Remarks

The original content remains on the object.

The actual content that is copied depends on the object. Using Copy for a form, Frame, or Page copies the currently active control.


Page.Cut Method (Outlook Forms Script)

 Copy code hover
[image]

Page.Cut Method (Outlook Forms Script)
Send feedback

Removes selected information from an object and transfers it to the Clipboard.

Syntax

expression .Cut

expression A variable that represents a Page object.

Remarks

Cut removes currently selected controls to the Clipboard. This method only removes controls created at run time.


Page.Paste Method (Outlook Forms Script)

 Copy code hover
[image]

Page.Paste Method (Outlook Forms Script)
Send feedback

Transfers the contents of the Clipboard to an object.

Syntax

expression .Paste

expression A variable that represents a Page object.


Page.RedoAction Method (Outlook Forms Script)

 Copy code hover
[image]

Page.RedoAction Method (Outlook Forms Script)
Send feedback

Reverses the effect of the most recent Undo action.

Syntax

expression .RedoAction

expression A variable that represents a Page object.

Return Value

A Boolean that specifies True if the method succeeds, False otherwise.

Remarks

Redo reverses the last Undo, which is not necessarily the last action taken. Not all actions can be undone.


Page.Repaint Method (Outlook Forms Script)

 Copy code hover
[image]

Page.Repaint Method (Outlook Forms Script)
Send feedback

Updates the display by redrawing the page.

Syntax

expression .Repaint

expression A variable that represents a Page object.

Return Value

A Boolean that returns True if the method succeeds; returns False otherwise.

Remarks

The Repaint method is useful if the contents or appearance of an object changes significantly, and you don't want to wait until the system automatically repaints the area.


Page.Scroll Method (Outlook Forms Script)

 Copy code hover
[image]

Page.Scroll Method (Outlook Forms Script)
Send feedback

Moves the scroll bar on an object.

Syntax

expression .Scroll(xAction, yAction)

expression A variable that represents a Page object.

Parameters

Name | Required/Optional | Data Type | Description
xAction | Optional | Variant | Identifies the action to occur in the horizontal direction.
yAction | Optional | Variant | Identifies the action to occur in the vertical direction.

Remarks

The settings for xAction and yAction are:

Value | Description
0 | Do not scroll in the specified direction.
1 | Move up on a vertical scroll bar or left on a horizontal scroll bar. Movement is equivalent to pressing the up or left arrow key on the keyboard to move the scroll bar.
2 | Move down on a vertical scroll bar or right on a horizontal scroll bar. Movement is equivalent to pressing the right or down arrow key on the keyboard to move the scroll bar.
3 | Move one pageup on a vertical scroll bar or one page left on a horizontal scroll bar. Movement is equivalent to pressing PAGE UP on the keyboard to move the scroll bar.
4 | Move one pagedown on a vertical scroll bar or one page right on a horizontal scroll bar. Movement is equivalent to pressing PAGE DOWN on the keyboard to move the scroll bar.
5 | Move to the top of a vertical scroll bar or to the left end of a horizontal scroll bar.
6 | Move to the bottom of a vertical scroll bar or to the right end of a horizontal scroll bar.

The Scroll method applies scroll bars that appear on a Page that is larger than its display area. This method does not apply to the stand-alone ScrollBar control or to scroll bars that appear on a TextBox.


Page.SetDefaultTabOrder Method (Outlook Forms Script)

 Copy code hover
[image]

Page.SetDefaultTabOrder Method (Outlook Forms Script)
Send feedback

Sets the TabIndex property of each control on a frame or page, using a default top-to-bottom, left-to-right tab order.

Syntax

expression .SetDefaultTabOrder

expression A variable that represents a Page object.

Remarks

The TabIndex property of a control is a Microsoft Forms 2.0 property.


Page.UndoAction Method (Outlook Forms Script)

 Copy code hover
[image]

Page.UndoAction Method (Outlook Forms Script)
Send feedback

Reverses the most recent action that supports the Undo command.

Syntax

expression .UndoAction

expression A variable that represents a Page object.

Remarks

Not all user actions can be undone. If an action cannot be undone, the Undo command is unavailable following the action.

You must apply this method before the form or control is updated. You may want to include this method in a form's PropertyChange event.


Pages Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Pages Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Pages Object (Outlook Forms Script)

  • Pages Members (Outlook Forms Script)

  • Pages Properties (Outlook Forms Script)

  • Pages Methods (Outlook Forms Script)


Pages Object (Outlook Forms Script)

 Copy code hover
[image]

Pages Object (Outlook Forms Script)
See also Send feedback

Represents all the pages of a MultiPage.

Remarks

Each Pages collection provides the features to manage the number of pages in the collection and to identify the page that is currently in use.

The default value of the Pages collection identifies the current Page of a collection.

You can reference a Page by its index value. The index value reflects the ordinal position of the Page within the collection. The index of the first Page in a collection is 0; the index of the second Page is 1; and so on.

See also

Concepts

Outlook Object Model Reference

Other resources

Pages Object Members


Pages Members (Outlook Forms Script)

 Copy code hover
[image]

Pages Members (Outlook Forms Script)
Send feedback

Represents all the pages of a MultiPage.

Methods

Name | Description
Add | Adds a Page to a Pages collection.
Clear | Removes pages from the collection.
Item | Returns a member of a collection, either by position or by name.
Remove | Removes a member from a collection.

Properties

Name | Description
Count | Returns a Long that represents the number of objects in a collection. Read-only.


Pages Properties (Outlook Forms Script)

 Copy code hover
[image]

Pages Properties (Outlook Forms Script)
Send feedback

In this section

  • Pages.Count Property (Outlook Forms Script)


Pages.Count Property (Outlook Forms Script)

 Copy code hover
[image]

Pages.Count Property (Outlook Forms Script)
See also Send feedback

Returns a Long that represents the number of objects in a collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Pages object.

Remarks

The Count property is read only.

Note that the index value for the first page of a collection is zero, the value for the second page is one, and so on. For example, if a MultiPage contains two pages, the indexes of the pages are 0 and 1, and the value of Count is 2.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages Methods (Outlook Forms Script)

 Copy code hover
[image]

Pages Methods (Outlook Forms Script)
Send feedback

In this section

  • Pages.Add Method (Outlook Forms Script)

  • Pages.Clear Method (Outlook Forms Script)

  • Pages.Item Method (Outlook Forms Script)

  • Pages.Remove Method (Outlook Forms Script)


Pages.Add Method (Outlook Forms Script)

 Copy code hover
[image]

Pages.Add Method (Outlook Forms Script)
See also Send feedback

Adds a Page to a Pages collection.

Syntax

expression .Add(bstrName, bstrCaption, lIndex)

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
bstrName | Optional | Variant | Specifies the name of the object being added. If a name is not specified, the system generates a default name based on the rules of the application where the form is used.
bstrCaption | Optional | Variant | Specifies the caption to appear on a page. If a caption is not specified, the system generates a default caption based on the rules of the application where the form is used.
lIndex | Optional | Variant | Identifies the position of a page within a Pages collection. If an index is not specified, the system appends the page to the end of the Pages collection and assigns the appropriate index value.

Return Value

A Page object that represents the added page.

Remarks

The index value for the first Page of a collection is 0, the value for the second Page is 1, and so on.

You can change the Name property of the object at run time only if you added that control at run time with the Add method.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages.Clear Method (Outlook Forms Script)

 Copy code hover
[image]

Pages.Clear Method (Outlook Forms Script)
Send feedback

Removes pages from the collection.

Syntax

expression .Clear

expression A variable that represents a Pages object.

Remarks

If the control is bound to data, the Clear method fails.


Pages.Item Method (Outlook Forms Script)

 Copy code hover
[image]

Pages.Item Method (Outlook Forms Script)
See also Send feedback

Returns a member of a collection, either by position or by name.

Syntax

expression .Item(varg)

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
varg | Required | Variant | A member's name or index within a collection.

Return Value

An Object that corresponds to the specified member in the collection.

Remarks

The varg can be either a String or an Integer. If it is a String, it must be a valid member name. If it is an Integer, the minimum value is 0 and the maximum value is one less than the number of items in the collection.

If an invalid index or name is specified, an error occurs.

See also

Concepts

Pages Object

Other resources

Pages Object Members


Pages.Remove Method (Outlook Forms Script)

 Copy code hover
[image]

Pages.Remove Method (Outlook Forms Script)
See also Send feedback

Removes a member from a collection.

Syntax

expression .Remove(varg)

expression A variable that represents a Pages object.

Parameters

Name | Required/Optional | Data Type | Description
varg | Required | Variant | A member's position, or index, within a collection. Numeric as well as string values are acceptable. If the value is a number, the minimum value is zero, and the maximum value is one less than the number of members in the collection. If the value is a string, it must correspond to a valid member name.

See also

Concepts

Pages Object

Other resources

Pages Object Members


ScrollBar Object Reference (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar Object Reference (Outlook Forms Script)
Send feedback

In this section

  • ScrollBar Object (Outlook Forms Script)

  • ScrollBar Members (Outlook Forms Script)

  • ScrollBar Properties (Outlook Forms Script)


ScrollBar Object (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar Object (Outlook Forms Script)
Send feedback

Returns or sets the value of another control based on the position of the scroll box.

Remarks

A ScrollBar is a stand-alone control you can place on a form. It is visually like the scroll bar you see in certain objects such as a ListBox or the drop-down portion of a ComboBox. However, unlike the scroll bars in these controls, the stand-alone ScrollBar is not an integral part of any other control.

To use the ScrollBar to set or read the value of another control, you must write code that uses the ScrollBar control's Value property. For example, to use the ScrollBar to update the value of a TextBox, you can write code that reads the Value property of the ScrollBar and then sets the Value property of the TextBox.

The default property for a ScrollBar is the Value property.

To create a horizontal or vertical ScrollBar, drag the sizing handles of the ScrollBar horizontally or vertically on the form.


ScrollBar Members (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar Members (Outlook Forms Script)
Send feedback

Returns or sets the value of another control based on the position of the scroll box.

Properties

Name | Description
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
Delay | Returns or sets a Long that specifies the delay in milliseconds, between events on a ScrollBar. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
LargeChange | Returns or sets a Long that specifies the amount of movement that occurs when the user clicks between the scroll box and scroll arrow. Read/write.
Max | Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a ScrollBar. Read/write.
Min | Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a ScrollBar. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Orientation | Returns or sets an Integer that specifies whether the control is oriented vertically or horizontally. Read/write.
ProportionalThumb | Returns or sets a Boolean that specifies whether the size of the scroll box is proportional to the scrolling region or fixed. Read/write.
SmallChange | Returns or sets an Integer that specifies the amount of movement that occurs when the user clicks either scroll arrow in a ScrollBar. Read/write.
Value | Returns or sets a Variant that specifies the state of a ScrollBar. Read/write.


ScrollBar Properties (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar Properties (Outlook Forms Script)
Send feedback

In this section

  • ScrollBar.BackColor Property (Outlook Forms Script)

  • ScrollBar.Delay Property (Outlook Forms Script)

  • ScrollBar.Enabled Property (Outlook Forms Script)

  • ScrollBar.ForeColor Property (Outlook Forms Script)

  • ScrollBar.LargeChange Property (Outlook Forms Script)

  • ScrollBar.Max Property (Outlook Forms Script)

  • ScrollBar.Min Property (Outlook Forms Script)

  • ScrollBar.MouseIcon Property (Outlook Forms Script)

  • ScrollBar.MousePointer Property (Outlook Forms Script)

  • ScrollBar.Orientation Property (Outlook Forms Script)

  • ScrollBar.ProportionalThumb Property (Outlook Forms Script)

  • ScrollBar.SmallChange Property (Outlook Forms Script)

  • ScrollBar.Value Property (Outlook Forms Script)


ScrollBar.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a ScrollBar object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


ScrollBar.Delay Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Delay Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the delay in milliseconds, between events on a ScrollBar. Read/write.

Syntax

expression .Delay

expression A variable that represents a ScrollBar object.

Remarks

The Delay property affects the amount of time between consecutive SpinUp, SpinDown, and Change events generated when the user clicks and holds down a button on a ScrollBar. The first event occurs immediately. The delay to the second occurrence of the event is five times the value of the specified Delay. This initial lag makes it easy to generate a single event rather than a stream of events.

After the initial lag, the interval between events is the value specified for Delay.

The default value of Delay is 50 milliseconds. This means the object initiates the first event after 250 milliseconds (5 times the specified value) and initiates each subsequent event after 50 milliseconds.


ScrollBar.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a ScrollBar object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.


ScrollBar.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a ScrollBar object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.

The ForeColor sets the color of the arrows.


ScrollBar.LargeChange Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.LargeChange Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the amount of movement that occurs when the user clicks between the scroll box and scroll arrow. Read/write.

Syntax

expression .LargeChange

expression A variable that represents a ScrollBar object.

Remarks

The LargeChange property specifies the amount of change to the Value property.

The LargeChange property applies only to the ScrollBar. It does not apply to the scrollbars in other controls such as a TextBox or a drop-down ComboBox.

The value of LargeChange is the amount by which the ScrollBar control's Value property changes when the user clicks the area between the scroll box and scroll arrow. The direction of the movement is always toward the place where the user clicks. For example, in a horizontal ScrollBar, clicking to the left of the scroll box moves the scroll box to the left. In a vertical ScrollBar, clicking above the scroll box moves the scroll box up.

LargeChange does not have units. Any integer is a valid setting for LargeChange. The recommended range of values is from -32,767 to +32,767, and the value must be between the values of the Max and Min properties of the ScrollBar.


ScrollBar.Max Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Max Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a ScrollBar. Read/write.

Syntax

expression .Max

expression A variable that represents a ScrollBar object.

Remarks

Moving the scroll box in a ScrollBar changes the Value property of the control.

The value for the Max property corresponds to the lowest position of a vertical ScrollBar or the rightmost position of a horizontal ScrollBar.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.

Max refer to locations, not to relative values, on the ScrollBar. That is, the value of Max could be less than the value of Min. If this is the case, moving toward the Max (bottom) position means decreasing Value; moving toward the Min (top) position means increasing Value.


ScrollBar.Min Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Min Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a ScrollBar. Read/write.

Syntax

expression .Min

expression A variable that represents a ScrollBar object.

Remarks

Moving the scroll box in a ScrollBar changes the Value property of the control.

The value for the Min property corresponds to the highest position of a vertical ScrollBar or the leftmost position of a horizontal ScrollBar.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.

Min and Max refer to locations, not to relative values, on the ScrollBar. That is, the value of Max could be less than the value of Min. If this is the case, moving toward the Max (bottom) position means decreasing Value; moving toward the Min (top) position means increasing Value.


ScrollBar.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a ScrollBar object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


ScrollBar.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a ScrollBar object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


ScrollBar.Orientation Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Orientation Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether the control is oriented vertically or horizontally. Read/write.

Syntax

expression .Orientation

expression A variable that represents a ScrollBar object.

Remarks

The settings for Orientation are:

Value | Description
-1 | Automatically determines the orientation based upon the dimensions of the control (default).
0 | Control is rendered vertically.
1 | Control is rendered horizontally.

If you specify automatic orientation, the height and width of the control determine whether it appears horizontally or vertically. For example, if the control is wider than it is tall, it appears horizontally; if it is taller than it is wide, the control appears vertically.


ScrollBar.ProportionalThumb Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.ProportionalThumb Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the size of the scroll box is proportional to the scrolling region or fixed. Read/write.

Syntax

expression .ProportionalThumb

expression A variable that represents a ScrollBar object.

Remarks

True if the scroll box is proportional in size to the scrolling region (default).False if the scroll box is a fixed size.

The size of a proportional scroll box graphically represents the percentage of the object that is visible in the window. For example, if 75 percent of an object is visible, the scroll box covers three-fourths of the scrolling region in the scroll bar.

If the scroll box is a fixed size, the system determines its size based on the height and width of the scroll bar.


ScrollBar.SmallChange Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.SmallChange Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the amount of movement that occurs when the user clicks either scroll arrow in a ScrollBar. Read/write.

Syntax

expression .SmallChange

expression A variable that represents a ScrollBar object.

Remarks

The SmallChange property specifies the amount of change to the Value property.

The SmallChange property does not have units.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.


ScrollBar.Value Property (Outlook Forms Script)

 Copy code hover
[image]

ScrollBar.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies the state of a ScrollBar. Read/write.

Syntax

expression .Value

expression A variable that represents a ScrollBar object.

Remarks

The Value property is an integer between the values specified for the Max and Min properties.


SpinButton Object Reference (Outlook Forms Script)

 Copy code hover
[image]

SpinButton Object Reference (Outlook Forms Script)
Send feedback

In this section

  • SpinButton Object (Outlook Forms Script)

  • SpinButton Members (Outlook Forms Script)

  • SpinButton Properties (Outlook Forms Script)


SpinButton Object (Outlook Forms Script)

 Copy code hover
[image]

SpinButton Object (Outlook Forms Script)
Send feedback

Increments and decrements a value.

Remarks

Clicking a SpinButton changes only the value of the SpinButton. You can write code that uses the SpinButton to update the displayed value of another control. For example, you can use a SpinButton to change the month, the day, or the year shown on a date. You can also use a SpinButton to scroll through a range of values or a list of items, or to change the value displayed in a text box.

To display a value updated by a SpinButton, you must assign the value of the SpinButton to the displayed portion of a control, such as the Caption property of a Label or the Text property of a TextBox. To create a horizontal or vertical SpinButton, drag the sizing handles of the SpinButton horizontally or vertically on the form.

The default property for a SpinButton is the Value property.


SpinButton Members (Outlook Forms Script)

 Copy code hover
[image]

SpinButton Members (Outlook Forms Script)
Send feedback

Increments and decrements a value.

Properties

Name | Description
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
Delay | Returns or sets a Long that specifies the delay in milliseconds, between events on a SpinButton. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
Max | Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a SpinButton. Read/write.
Min | Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a SpinButton. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Orientation | Returns or sets an Integer that specifies whether the control is oriented vertically or horizontally. Read/write.
SmallChange | Returns or sets an Integer that specifies the amount of movement that occurs when the user clicks either scroll arrow in a SpinButton. Read/write.
Value | Returns or sets a Variant that specifies the state of a SpinButton. Read/write.


SpinButton Properties (Outlook Forms Script)

 Copy code hover
[image]

SpinButton Properties (Outlook Forms Script)
Send feedback

In this section

  • SpinButton.BackColor Property (Outlook Forms Script)

  • SpinButton.Delay Property (Outlook Forms Script)

  • SpinButton.Enabled Property (Outlook Forms Script)

  • SpinButton.ForeColor Property (Outlook Forms Script)

  • SpinButton.Max Property (Outlook Forms Script)

  • SpinButton.Min Property (Outlook Forms Script)

  • SpinButton.MouseIcon Property (Outlook Forms Script)

  • SpinButton.MousePointer Property (Outlook Forms Script)

  • SpinButton.Orientation Property (Outlook Forms Script)

  • SpinButton.SmallChange Property (Outlook Forms Script)

  • SpinButton.Value Property (Outlook Forms Script)


SpinButton.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a SpinButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


SpinButton.Delay Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Delay Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the delay in milliseconds, between events on a SpinButton. Read/write.

Syntax

expression .Delay

expression A variable that represents a SpinButton object.

Remarks

The Delay property affects the amount of time between consecutive SpinUp, SpinDown, and Change events generated when the user clicks and holds down a button on a SpinButton. The first event occurs immediately. The delay to the second occurrence of the event is five times the value of the specified Delay. This initial lag makes it easy to generate a single event rather than a stream of events.

After the initial lag, the interval between events is the value specified for Delay.

The default value of Delay is 50 milliseconds. This means the object initiates the first event after 250 milliseconds (5 times the specified value) and initiates each subsequent event after 50 milliseconds.


SpinButton.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a SpinButton object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.


SpinButton.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a SpinButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.

The ForeColor sets the color of the arrows.


SpinButton.Max Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Max Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a SpinButton. Read/write.

Syntax

expression .Max

expression A variable that represents a SpinButton object.

Remarks

Clicking a SpinButton changes the Value property of the control.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.


SpinButton.Min Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Min Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum and minimum acceptable values for the Value property of a SpinButton. Read/write.

Syntax

expression .Min

expression A variable that represents a SpinButton object.

Remarks

Clicking a SpinButton changes the Value property of the control.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.


SpinButton.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a SpinButton object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


SpinButton.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a SpinButton object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


SpinButton.Orientation Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Orientation Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether the control is oriented vertically or horizontally. Read/write.

Syntax

expression .Orientation

expression A variable that represents a SpinButton object.

Remarks

The settings for Orientation are:

Value | Description
-1 | Automatically determines the orientation based upon the dimensions of the control (default).
0 | Control is rendered vertically.
1 | Control is rendered horizontally.

If you specify automatic orientation, the height and width of the control determine whether it appears horizontally or vertically. For example, if the control is wider than it is tall, it appears horizontally; if it is taller than it is wide, the control appears vertically.


SpinButton.SmallChange Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.SmallChange Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the amount of movement that occurs when the user clicks either scroll arrow in a SpinButton. Read/write.

Syntax

expression .SmallChange

expression A variable that represents a SpinButton object.

Remarks

The SmallChange property specifies the amount of change to the Value property.

The SmallChange property does not have units.

Any integer is an acceptable setting for this property. The recommended range of values is from -32,767 to +32,767. The default value is 1.


SpinButton.Value Property (Outlook Forms Script)

 Copy code hover
[image]

SpinButton.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies the state of a SpinButton. Read/write.

Syntax

expression .Value

expression A variable that represents a SpinButton object.

Remarks

The Value property is an integer between the values specified for the Max and Min properties.


Tab Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Tab Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Tab Object (Outlook Forms Script)

  • Tab Members (Outlook Forms Script)

  • Tab Properties (Outlook Forms Script)


Tab Object (Outlook Forms Script)

 Copy code hover
[image]

Tab Object (Outlook Forms Script)
Send feedback

Represents an individual member of a Tabs collection.

Remarks

Visually, a Tab object appears as a rectangle protruding from a larger rectangular area, or as a button adjacent to a rectangular area.

In contrast to a Page, a Tab does not contain any controls. Controls that appear within the region bounded by a TabStrip are contained on the form, as is the TabStrip.

You can reference a Tab by its index value. The index value reflects the ordinal position of the Tab within the collection. The index of the first Tab in a collection is 0; the index of the second Tab is 1; and so on.


Tab Members (Outlook Forms Script)

 Copy code hover
[image]

Tab Members (Outlook Forms Script)
Send feedback

Represents an individual member of a Tabs collection.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for the tab. Read/write.
Caption | Returns or sets a String that specifies the text that appears on the tab. Read/write.
ControlTipText | Returns and sets a String that specifies text that appears when the user briefly holds the mouse pointer over a control without clicking. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
Index | Returns or sets an Integer that specifies the position of a Tab object within a Tabs collection. Read/write.
Name | Returns or sets a String that specifies the name of a control. Read/write.
Tag | Returns or sets a String that specifies additional information about an object. Read/write.
Visible | Returns or sets a Boolean that specifies whether a Tab is visible or hidden. Read/write.


Tab Properties (Outlook Forms Script)

 Copy code hover
[image]

Tab Properties (Outlook Forms Script)
Send feedback

In this section

  • Tab.Accelerator Property (Outlook Forms Script)

  • Tab.Caption Property (Outlook Forms Script)

  • Tab.ControlTipText Property (Outlook Forms Script)

  • Tab.Enabled Property (Outlook Forms Script)

  • Tab.Index Property (Outlook Forms Script)

  • Tab.Name Property (Outlook Forms Script)

  • Tab.Tag Property (Outlook Forms Script)

  • Tab.Visible Property (Outlook Forms Script)


Tab.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for the tab. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a Tab object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.


Tab.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the text that appears on the tab. Read/write.

Syntax

expression .Caption

expression A variable that represents a Tab object.

Remarks

The default caption for an object is a unique name based on the type of object. For example, CommandButton1 is the default caption for the first command button in a form.

If an object's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.


Tab.ControlTipText Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.ControlTipText Property (Outlook Forms Script)
Send feedback

Returns and sets a String that specifies text that appears when the user briefly holds the mouse pointer over a control without clicking. Read/write.

Syntax

expression .ControlTipText

expression A variable that represents a Tab object.

Remarks

The ControlTipText property lets you give users tips about a control in a running form. The property can be set during design time but only appears by the control during run time.

The default value of ControlTipText is an empty string. When the value of ControlTipText is set to an empty string, no tip is available for that control.


Tab.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a Tab object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

When the user tabs into an enabled TabStrip, the first tab in the control receives the focus. If the first tab of a TabStrip is disabled, the first enabled tab of that control receives the focus. If all tabs of a TabStrip are disabled, the control is disabled and cannot receive the focus.


Tab.Index Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Index Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the position of a Tab object within a Tabs collection. Read/write.

Syntax

expression .Index

expression A variable that represents a Tab object.

Remarks

The Index property specifies the order in which tabs appear. Changing the value of Index visually changes the order of tabs on a TabStrip. The index value for the first tab is zero, the index value of the second tab is one, and so on.

In a MultiPage, Index refers to a Page as well as the page's Tab. In a TabStrip, Index refers to the tab only.


Tab.Name Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Name Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies the name of a control. Read/write.

Syntax

expression .Name

expression A variable that represents a Tab object.

Remarks

Guidelines for assigning a string to Name, such as the maximum length of the name, vary from one application to another.

For objects, the default value of Name consists of the object's class name followed by an integer. For example, the default name for the first TextBox you place on a form is TextBox1. The default name for the second TextBox is TextBox2.

You can set the Name property for a control from the control's property sheet or, for controls added at run time, by using program statements. If you add a control at design time, you cannot modify its Name property at run time.

Each control added to a form at design time must have a unique name.


Tab.Tag Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Tag Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies additional information about an object. Read/write.

Syntax

expression .Tag

expression A variable that represents a Tab object.

Remarks

The default is a zero-length string ("").

Use the Tag property to assign an identification string to an object without affecting other property settings or attributes.

For example, you can use Tag to check the identity of a form or control that is passed as a variable to a procedure.


Tab.Visible Property (Outlook Forms Script)

 Copy code hover
[image]

Tab.Visible Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a Tab is visible or hidden. Read/write.

Syntax

expression .Visible

expression A variable that represents a Tab object.

Remarks

True to specify the tab is visible (default), False to specify the tab is hidden.

Use the Visible property to control access to information without displaying it. For example, you could use the value of a control on a hidden form as the criteria for a query.

All tabs are visible at design time.


Tabs Object Reference (Outlook Forms Script)

 Copy code hover
[image]

Tabs Object Reference (Outlook Forms Script)
Send feedback

In this section

  • Tabs Object (Outlook Forms Script)

  • Tabs Members (Outlook Forms Script)

  • Tabs Properties (Outlook Forms Script)

  • Tabs Methods (Outlook Forms Script)


Tabs Object (Outlook Forms Script)

 Copy code hover
[image]

Tabs Object (Outlook Forms Script)
Send feedback

Represents all the Tab controls of a TabStrip.

Remarks

Each Tabs collection provides the features to manage the number of tabs in the collection and to identify the tab that is currently in use.

The default value of the Tabs collection identifies the current Tab of a collection.

You can reference a Tab by its index value. The index value reflects the ordinal position of the Tab within the collection. The index of the first Tab in a collection is 0; the index of the second Tab is 1; and so on.


Tabs Members (Outlook Forms Script)

 Copy code hover
[image]

Tabs Members (Outlook Forms Script)
Send feedback

Represents all the Tab Object (Outlook Forms Script) controls of a TabStrip.

Methods

Name | Description
Add | Adds a Tab to a Tabs collection.
Clear | Removes all tabs from a Tabs collection.
Item | Returns a member of a collection, either by position or by name.
Remove | Removes a member from a collection.

Properties

Name | Description
Count | Returns a Long that represents the number of objects in a collection. Read-only.


Tabs Properties (Outlook Forms Script)

 Copy code hover
[image]

Tabs Properties (Outlook Forms Script)
Send feedback

In this section

  • Tabs.Count Property (Outlook Forms Script)


Tabs.Count Property (Outlook Forms Script)

 Copy code hover
[image]

Tabs.Count Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the number of objects in a collection. Read-only.

Syntax

expression .Count

expression A variable that represents a Tabs object.

Remarks

Note that the index value for the first tab of a collection is zero, the value for the second tab is one, and so on. For example, if a TabStrip contains two tabs, the indexes of the tabs are 0 and 1, and the value of Count is 2.


Tabs Methods (Outlook Forms Script)

 Copy code hover
[image]

Tabs Methods (Outlook Forms Script)
Send feedback

In this section

  • Tabs.Add Method (Outlook Forms Script)

  • Tabs.Clear Method (Outlook Forms Script)

  • Tabs.Item Method (Outlook Forms Script)

  • Tabs.Remove Method (Outlook Forms Script)


Tabs.Add Method (Outlook Forms Script)

 Copy code hover
[image]

Tabs.Add Method (Outlook Forms Script)
Send feedback

Adds a Tab to a Tabs collection.

Syntax

expression .Add(bstrName, bstrCaption, lIndex)

expression A variable that represents a Tabs object.

Parameters

Name | Required/Optional | Data Type | Description
bstrName | Optional | Variant | Specifies the name of the object being added. If a name is not specified, the system generates a default name based on the rules of the application where the form is used.
bstrCaption | Optional | Variant | Specifies the caption to appear on a tab. If a caption is not specified, the system generates a default caption based on the rules of the application where the form is used.
lIndex | Optional | Variant | Identifies the position of a tab within a Tabs collection. If an index is not specified, the system appends the page to the end of the Tabs collection and assigns the appropriate index value.

Return Value

A Tab object that represents the added tab.

Remarks

The index value for the first Tab of a collection is 0, the value for the second Tab is 1, and so on.

You can change the Name property of the object at run time only if you added that control at run time with the Add method.


Tabs.Clear Method (Outlook Forms Script)

 Copy code hover
[image]

Tabs.Clear Method (Outlook Forms Script)
Send feedback

Removes all tabs from a Tabs collection.

Syntax

expression .Clear

expression A variable that represents a Tabs object.

Remarks

If the control is bound to data, the Clear method fails.


Tabs.Item Method (Outlook Forms Script)

 Copy code hover
[image]

Tabs.Item Method (Outlook Forms Script)
Send feedback

Returns a member of a collection, either by position or by name.

Syntax

expression .Item(varg)

expression A variable that represents a Tabs object.

Parameters

Name | Required/Optional | Data Type | Description
varg | Required | Variant | A member's name or index within a collection.

Return Value

An Object that corresponds to the specified member in the collection.

Remarks

The varg can be either a String or an Integer. If it is a String, it must be a valid member name. If it is an Integer, the minimum value is 0 and the maximum value is one less than the number of items in the collection.

If an invalid index or name is specified, an error occurs.


Tabs.Remove Method (Outlook Forms Script)

 Copy code hover
[image]

Tabs.Remove Method (Outlook Forms Script)
Send feedback

Removes a member from a collection.

Syntax

expression .Remove(varg)

expression A variable that represents a Tabs object.

Parameters

Name | Required/Optional | Data Type | Description
varg | Required | Variant | A member's position, or index, within a collection. Numeric as well as string values are acceptable. If the value is a number, the minimum value is zero, and the maximum value is one less than the number of members in the collection. If the value is a string, it must correspond to a valid member name.


TabStrip Object Reference (Outlook Forms Script)

 Copy code hover
[image]

TabStrip Object Reference (Outlook Forms Script)
Send feedback

In this section

  • TabStrip Object (Outlook Forms Script)

  • TabStrip Members (Outlook Forms Script)

  • TabStrip Properties (Outlook Forms Script)

  • TabStrip Events (Outlook Forms Script)


TabStrip Object (Outlook Forms Script)

 Copy code hover
[image]

TabStrip Object (Outlook Forms Script)
Send feedback

Presents a set of related controls as a visual group.

Remarks

You can use a TabStrip to view different sets of information for related controls.

A TabStrip is a control that contains a collection of one or more tabs.

Each Tab of a TabStrip is a separate object that users can select. Visually, a TabStrip also includes a client area that all the tabs in the TabStrip share.

By default, a TabStrip includes two pages, called Tab1 and Tab2. Each of these is a Tab object, and together they represent the Tabs collection of the TabStrip. If you add more pages, they become part of the same Tabs collection.

For example, the controls might represent information about a daily schedule for a group of individuals, with each set of information corresponding to a different individual in the group. Set the title of each tab to show one individual's name. Then, you can write code that, after you click a tab, updates the controls to show information about the person identified on the tab.

The TabStrip is implemented as a container of a Tabs collection, which in turn contains a group of Tab objects. The TabStrip control does not support the Click event.

The default property for a TabStrip is the SelectedItem property.


TabStrip Members (Outlook Forms Script)

 Copy code hover
[image]

TabStrip Members (Outlook Forms Script)
Send feedback

Presents a set of related controls as a visual group.

Properties

Name | Description
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
ClientHeight | Returns a Single value that represents the height dimension of the display area of a TabStrip. Read-only.
ClientLeft | Returns a Single value that represents the location of the left edge of the display area of a TabStrip. Read-only.
ClientTop | Returns a Single value that represents the location of the top edge of the display area of a TabStrip. Read-only.
ClientWidth | Returns a Single value that represents the width dimension of the display area of a TabStrip. Read-only.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
MultiRow | Returns or sets a Boolean that specifies whether the control has more than one row of tabs. Read/write.
SelectedItem | Returns an Object that indicates the currently selected Tab object. Read-only.
Style | Returns or sets an Integer that identifies the style of the tabs on the control. Read/write.
TabFixedHeight | Returns or sets a Single that represents the height in points of the tabs on a TabStrip. Read/write.
TabFixedWidth | Returns or sets a Single that represents the width in points of the tabs on a TabStrip. Read/write.
TabOrientation | Returns or sets an Integer that specifies the location of the tabs on a TabStrip. Read/write.
Value | Returns or sets a Variant that indicates the currently active tab. Read/write.

Events

Name | Description
Click | Occurs when the user clicks inside the control.


TabStrip Properties (Outlook Forms Script)

 Copy code hover
[image]

TabStrip Properties (Outlook Forms Script)
Send feedback

In this section

  • TabStrip.BackColor Property (Outlook Forms Script)

  • TabStrip.ClientHeight Property (Outlook Forms Script)

  • TabStrip.ClientLeft Property (Outlook Forms Script)

  • TabStrip.ClientTop Property (Outlook Forms Script)

  • TabStrip.ClientWidth Property (Outlook Forms Script)

  • TabStrip.Enabled Property (Outlook Forms Script)

  • TabStrip.ForeColor Property (Outlook Forms Script)

  • TabStrip.MouseIcon Property (Outlook Forms Script)

  • TabStrip.MousePointer Property (Outlook Forms Script)

  • TabStrip.MultiRow Property (Outlook Forms Script)

  • TabStrip.SelectedItem Property (Outlook Forms Script)

  • TabStrip.Style Property (Outlook Forms Script)

  • TabStrip.TabFixedHeight Property (Outlook Forms Script)

  • TabStrip.TabFixedWidth Property (Outlook Forms Script)

  • TabStrip.TabOrientation Property (Outlook Forms Script)

  • TabStrip.Value Property (Outlook Forms Script)


TabStrip.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a TabStrip object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)


TabStrip.ClientHeight Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.ClientHeight Property (Outlook Forms Script)
Send feedback

Returns a Single value that represents the height dimension of the display area of a TabStrip. Read-only.

Syntax

expression .ClientHeight

expression A variable that represents a TabStrip object.

Remarks

For ClientHeight and ClientWidth, specifies the distance, in points, from respectively the top and left edge of the TabStrip's container. For ClientLeft and ClientTop, specifies the location, in points, of respectively the top and left edges of the TabStrip's container.

At run time, ClientLeft, ClientTop, ClientHeight, and ClientWidth automatically store the coordinates and dimensions of the TabStrip control's internal area, which is shared by objects in the TabStrip.


TabStrip.ClientLeft Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.ClientLeft Property (Outlook Forms Script)
Send feedback

Returns a Single value that represents the location of the left edge of the display area of a TabStrip. Read-only.

Syntax

expression .ClientLeft

expression A variable that represents a TabStrip object.

Remarks

For ClientHeight and ClientWidth, specifies the distance, in points, from respectively the top and left edge of the TabStrip's container. For ClientLeft and ClientTop, specifies the location, in points, of respectively the top and left edges of the TabStrip's container.

At run time, ClientLeft, ClientTop, ClientHeight, and ClientWidth automatically store the coordinates and dimensions of the TabStrip control's internal area, which is shared by objects in the TabStrip.


TabStrip.ClientTop Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.ClientTop Property (Outlook Forms Script)
Send feedback

Returns a Single value that represents the location of the top edge of the display area of a TabStrip. Read-only.

Syntax

expression .ClientTop

expression A variable that represents a TabStrip object.

Remarks

For ClientHeight and ClientWidth, specifies the distance, in points, from respectively the top and left edge of the TabStrip's container. For ClientLeft and ClientTop, specifies the location, in points, of respectively the top and left edges of the TabStrip's container.

At run time, ClientLeft, ClientTop, ClientHeight, and ClientWidth automatically store the coordinates and dimensions of the TabStrip control's internal area, which is shared by objects in the TabStrip.


TabStrip.ClientWidth Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.ClientWidth Property (Outlook Forms Script)
Send feedback

Returns a Single value that represents the width dimension of the display area of a TabStrip. Read-only.

Syntax

expression .ClientWidth

expression A variable that represents a TabStrip object.

Remarks

For ClientHeight and ClientWidth, specifies the distance, in points, from respectively the top and left edge of the TabStrip's container. For ClientLeft and ClientTop, specifies the location, in points, of respectively the top and left edges of the TabStrip's container.

At run time, ClientLeft, ClientTop, ClientHeight, and ClientWidth automatically store the coordinates and dimensions of the TabStrip control's internal area, which is shared by objects in the TabStrip.


TabStrip.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a TabStrip object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

When the user tabs into an enabled TabStrip, the first tab in the control receives the focus. If the first tab of a TabStrip is disabled, the first enabled tab of that control receives the focus. If all tabs of a TabStrip are disabled, the control is disabled and cannot receive the focus.


TabStrip.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a TabStrip object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


TabStrip.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a TabStrip object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


TabStrip.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a TabStrip object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


TabStrip.MultiRow Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.MultiRow Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the control has more than one row of tabs. Read/write.

Syntax

expression .MultiRow

expression A variable that represents a TabStrip object.

Remarks

True to allow more than one row of tabs, False to restrict tabs to a single row (default).

The width and number of tabs determines the number of rows. Changing the control's size also changes the number of rows. This allows the developer to resize the control and ensure that tabs wrap to fit the control. If the MultiRow property is False, then truncation occurs if the width of the tabs exceeds the width of the control.

If MultiRow is False and tabs are truncated, there will be a small scroll bar on the TabStrip to allow scrolling to the other tabs or pages.


TabStrip.SelectedItem Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.SelectedItem Property (Outlook Forms Script)
Send feedback

Returns an Object that indicates the currently selected Tab object. Read-only.

Syntax

expression .SelectedItem

expression A variable that represents a TabStrip object.

Remarks

The SelectedItem property is read-only. Use SelectedItem to programmatically control the currently selected Tab object. For example, you can use SelectedItem to assign values to properties of a Tab object.


TabStrip.Style Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.Style Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that identifies the style of the tabs on the control. Read/write.

Syntax

expression .Style

expression A variable that represents a TabStrip object.

Remarks

The settings of the Style property are:

Value | Description
0 | Displays tabs on the tab bar (default).
1 | Displays buttons on the tab bar.
2 | Does not display the tab bar.


TabStrip.TabFixedHeight Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.TabFixedHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that represents the height in points of the tabs on a TabStrip. Read/write.

Syntax

expression .TabFixedHeight

expression A variable that represents a TabStrip object.

Remarks

The minimum size is 4 points.


TabStrip.TabFixedWidth Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.TabFixedWidth Property (Outlook Forms Script)
Send feedback

Returns or sets a Single that represents the width in points of the tabs on a TabStrip. Read/write.

Syntax

expression .TabFixedWidth

expression A variable that represents a TabStrip object.

Remarks

If the value is 0, tab widths are automatically adjusted so that each tab is wide enough to accommodate its contents and each row of tabs spans the width of the control.

If the value is greater than 0, all tabs have an identical width as specified by this property.

The minimum size is 4 points.


TabStrip.TabOrientation Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.TabOrientation Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the tabs on a TabStrip. Read/write.

Syntax

expression .TabOrientation

expression A variable that represents a TabStrip object.

Remarks

The settings for TabOrientation are:

Value | Description
0 | The tabs appear at the top of the control (default).
1 | The tabs appear at the bottom of the control.
2 | The tabs appear at the left side of the control.
3 | The tabs appear at the right side of the control.

If you use TrueType fonts, the text rotates when the TabOrientation property is set to 2 or 3. If you use bitmapped fonts, the text does not rotate.


TabStrip.Value Property (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that indicates the currently active tab. Read/write.

Syntax

expression .Value

expression A variable that represents a TabStrip object.

Remarks

Zero (0) indicates the first tab. The maximum value is one less than the number of tabs.


TabStrip Events (Outlook Forms Script)

 Copy code hover
[image]

TabStrip Events (Outlook Forms Script)
Send feedback

In this section

  • TabStrip.Click Event (Outlook Forms Script)


TabStrip.Click Event (Outlook Forms Script)

 Copy code hover
[image]

TabStrip.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user clicks inside the control.

Syntax

expression .Click(Index, )

expression A variable that represents a TabStrip object.

Parameters

Name | Required/Optional | Data Type | Description
Index | Required | Long |

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


TextBox Object Reference (Outlook Forms Script)

 Copy code hover
[image]

TextBox Object Reference (Outlook Forms Script)
Send feedback

In this section

  • TextBox Object (Outlook Forms Script)

  • TextBox Members (Outlook Forms Script)

  • TextBox Properties (Outlook Forms Script)

  • TextBox Methods (Outlook Forms Script)


TextBox Object (Outlook Forms Script)

 Copy code hover
[image]

TextBox Object (Outlook Forms Script)
Send feedback

Displays information from a user or from an organized set of data.

Remarks

A TextBox is the control most commonly used to display information entered by a user. Also, it can display a set of data, such as a table, query, worksheet, or a calculation result. If a TextBox is bound to a data source, then changing the contents of the TextBox also changes the value of the bound data source.

Formatting applied to any piece of text in a TextBox will affect all text in the control. For example, if you change the font or point size of any character in the control, the change will affect all characters in the control.

The default property for a TextBox is the Value property.

Tips on using text boxes

The TextBox is a flexible control governed by the following properties: Text, MultiLine, WordWrap, and AutoSize.

Text contains the text that's displayed in the text box.

MultiLine controls whether the TextBox can display text as a single line or as multiple lines. Newline characters identify where one line ends and another begins. If MultiLine is False (the default value), the text is truncated instead of wrapped.

WordWrap allows the TextBox to wrap lines of text that are longer than the width of the TextBox into shorter lines that fit. The default value is True.

If you do not use WordWrap, the TextBox starts a new line of text when it encounters a newline character in the text. If WordWrap is turned off, you can have text lines that do not fit completely in the TextBox. The TextBox displays the portions of text that fit inside its width and truncates the portions of text that do not fit. WordWrap is not applicable unless MultiLine is True.

AutoSize controls whether the TextBox adjusts to display all of the text. When using AutoSize with a TextBox, the width of the TextBox shrinks or expands according to the amount of text in the TextBox and the font size used to display the text. The default value is False.

AutoSize works well in the following situations:

  • Displaying a caption of one or more lines.

  • Displaying the contents of a single-line TextBox.

  • Displaying the contents of a multiline TextBox that is read-only to the user.

Avoid using AutoSize with an empty TextBox that also uses the MultiLine and WordWrap properties. When the user enters text into a TextBox with these properties, the TextBox automatically sizes to a long narrow box one character wide and as long as the line of text.


TextBox Members (Outlook Forms Script)

 Copy code hover
[image]

TextBox Members (Outlook Forms Script)
Send feedback

Displays information from a user or from an organized set of data.

Methods

Name | Description
Copy | Copies the contents of an object to the Clipboard.
Cut | Removes selected information from an object and transfers it to the Clipboard.
Paste | Transfers the contents of the Clipboard to an object.

Properties

Name | Description
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
AutoTab | Returns or sets a Boolean that specifies whether an automatic tab occurs when a user enters the maximum allowable number of characters into a TextBox. Read/write.
AutoWordSelect | Returns or sets a Boolean that specifies whether the basic unit used to extend a selection is a word or a single character. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
BorderColor | Returns or sets a Long that specifies the border color of an object. Read/write.
BorderStyle | Returns or sets an Integer that specifies the type of border of the control. Read/write.
CanPaste | Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.
CurLine | Returns or sets a Long that represents the current line of a control. Read/write.
CurTargetX | Returns a Long that represents the preferred horizontal position of the insertion point in a multiline TextBox. Read-only.
CurX | Returns or sets a Long that represents the current horizontal position of the insertion point in a multiline TextBox. Read/write.
DragBehavior | Returns or sets an Integer that specifies whether the system enables the drag-and-drop feature for the control. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
EnterFieldBehavior | Returns or sets an Integer that specifies the selection behavior when entering a TextBox. Read/write.
EnterKeyBehavior | Returns or sets a Boolean that defines the effect of pressing ENTER in a TextBox. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
HideSelection | Returns or sets a Boolean that specifies whether selected text remains highlighted when a control does not have the focus. Read/write.
IMEMode | Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.
IntegralHeight | Returns or sets a Boolean that specifies whether a TextBox displays full lines of text or partial lines. Read/write.
LineCount | Returns a Long that specifies the number of text lines in a TextBox. Read-only.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MaxLength | Returns or sets a Long that specifies the maximum number of characters a user can enter in a TextBox. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
MultiLine | Returns or sets a Boolean that specifies whether a control can accept and display multiple lines of text. Read/write.
PasswordChar | Returns or sets a String that specifies a placeholder character to be displayed instead of the characters actually entered in a TextBox. Read/write.
ScrollBars | Returns or sets an Integer that specifies whether a control has vertical scroll bars, horizontal scroll bars, or both. Read/write.
SelectionMargin | Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.
SelLength | Returns or sets a Long that represents the number of characters selected in a TextBox. Read/write.
SelStart | Returns or sets a Long that represents the starting point of selected text, or the insertion point if no text is selected. Read/write.
SelText | Returns or sets a String that represents the selected text of a control. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
TabKeyBehavior | Returns or sets a Boolean that specifies whether tabs are allowed in the edit region. Read/write.
Text | Returns or sets a String that specifies text in the control. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TextLength | Returns a Long that represents the length, in number of characters, of text in the edit region of a TextBox. Read-only.
Value | Returns or sets a Variant that specifies text in the edit region. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.


TextBox Properties (Outlook Forms Script)

 Copy code hover
[image]

TextBox Properties (Outlook Forms Script)
Send feedback

In this section

  • TextBox.AutoSize Property (Outlook Forms Script)

  • TextBox.AutoTab Property (Outlook Forms Script)

  • TextBox.AutoWordSelect Property (Outlook Forms Script)

  • TextBox.BackColor Property (Outlook Forms Script)

  • TextBox.BackStyle Property (Outlook Forms Script)

  • TextBox.BorderColor Property (Outlook Forms Script)

  • TextBox.BorderStyle Property (Outlook Forms Script)

  • TextBox.CanPaste Property (Outlook Forms Script)

  • TextBox.CurLine Property (Outlook Forms Script)

  • TextBox.CurTargetX Property (Outlook Forms Script)

  • TextBox.CurX Property (Outlook Forms Script)

  • TextBox.DragBehavior Property (Outlook Forms Script)

  • TextBox.Enabled Property (Outlook Forms Script)

  • TextBox.EnterFieldBehavior Property (Outlook Forms Script)

  • TextBox.EnterKeyBehavior Property (Outlook Forms Script)

  • TextBox.ForeColor Property (Outlook Forms Script)

  • TextBox.HideSelection Property (Outlook Forms Script)

  • TextBox.IMEMode Property (Outlook Forms Script)

  • TextBox.IntegralHeight Property (Outlook Forms Script)

  • TextBox.LineCount Property (Outlook Forms Script)

  • TextBox.Locked Property (Outlook Forms Script)

  • TextBox.MaxLength Property (Outlook Forms Script)

  • TextBox.MouseIcon Property (Outlook Forms Script)

  • TextBox.MousePointer Property (Outlook Forms Script)

  • TextBox.MultiLine Property (Outlook Forms Script)

  • TextBox.PasswordChar Property (Outlook Forms Script)

  • TextBox.ScrollBars Property (Outlook Forms Script)

  • TextBox.SelectionMargin Property (Outlook Forms Script)

  • TextBox.SelLength Property (Outlook Forms Script)

  • TextBox.SelStart Property (Outlook Forms Script)

  • TextBox.SelText Property (Outlook Forms Script)

  • TextBox.SpecialEffect Property (Outlook Forms Script)

  • TextBox.TabKeyBehavior Property (Outlook Forms Script)

  • TextBox.Text Property (Outlook Forms Script)

  • TextBox.TextAlign Property (Outlook Forms Script)

  • TextBox.TextLength Property (Outlook Forms Script)

  • TextBox.Value Property (Outlook Forms Script)

  • TextBox.WordWrap Property (Outlook Forms Script)


TextBox.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a TextBox object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls without captions, this property specifies whether the control automatically adjusts to display the information stored in the control. In a ComboBox, for example, setting AutoSize to True automatically sets the width of the display area to match the length of the current text.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.

For a single-line TextBox, setting AutoSize to True automatically sets the width of the display area to the length of the text in the text box.

For a multiline TextBox that contains no text, setting AutoSize to True automatically displays the text as a column. The width of the text column is set to accommodate the widest letter of that font size. The height of the text column is set to display the entire text of the TextBox.

For a multiline TextBox that contains text, setting AutoSize to True automatically enlarges the TextBox vertically to display the entire text. The width of the TextBox does not change.


TextBox.AutoTab Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.AutoTab Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an automatic tab occurs when a user enters the maximum allowable number of characters into a TextBox. Read/write.

Syntax

expression .AutoTab

expression A variable that represents a TextBox object.

Remarks

True if tab occurs, False otherwise (default).

The MaxLength property specifies the maximum number of characters allowed in a TextBox.

You can specify the AutoTab property for a TextBox on a form for which you usually enter a set number of characters. Once a user enters the maximum number of characters, the focus automatically moves to the next control in the tab order. For example, if a TextBox displays inventory stock numbers that are always five characters long, you can use MaxLength to specify the maximum number of characters to enter into the TextBox and AutoTab to automatically tab to the next control after the user enters five characters.


TextBox.AutoWordSelect Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.AutoWordSelect Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the basic unit used to extend a selection is a word or a single character. Read/write.

Syntax

expression .AutoWordSelect

expression A variable that represents a TextBox object.

Remarks

True if uses a word as the basic unit (default), False if uses a character as the basic unit.

The AutoWordSelect property specifies how the selection extends or contracts in the edit region of a TextBox.

If the user places the insertion point in the middle of a word and then extends the selection while AutoWordSelect is True, the selection includes the entire word.


TextBox.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a TextBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


TextBox.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a TextBox object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


TextBox.BorderColor Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.BorderColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the border color of an object. Read/write.

Syntax

expression .BorderColor

expression A variable that represents a TextBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

To use the BorderColor property, the BorderStyle property must be set to a value other than 0.

BorderStyle uses BorderColor to define the border colors. The SpecialEffect property uses system colors exclusively to define its border colors. For Windows operating systems, system color settings are set using the Display icon in Control Panel.


TextBox.BorderStyle Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.BorderStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of border of the control. Read/write.

Syntax

expression .BorderStyle

expression A variable that represents a TextBox object.

Remarks

The possible values of BorderStyle are 0 and 1. 0 represents no visible border line, 1 represents a single-line border (default).

The default value for a TextBox is 0 (None).

You can use either BorderStyle or SpecialEffect to specify the border for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set BorderStyle to 1, the system sets SpecialEffect to zero (Flat). If you specify a nonzero value for SpecialEffect, the system sets BorderStyle to zero.

BorderStyle uses BorderColor to define the colors of its borders. To use the BorderColor property, the BorderStyle property must be set to a value other than 0.


TextBox.CanPaste Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.CanPaste Property (Outlook Forms Script)
Send feedback

Returns a Boolean that specifies whether the Clipboard contains data that the object supports. Read-only.

Syntax

expression .CanPaste

expression A variable that represents a TextBox object.

Remarks

True if the object can receive information pasted from the Clipboard, False if the object cannot receive information pasted from the Clipboard.

CanPaste is read-only.

If the Clipboard data is in a format that the object does not support, the CanPaste property is False. For example, if you try to paste a bitmap into an object that only supports text, CanPaste will be False.


TextBox.CurLine Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.CurLine Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the current line of a control. Read/write.

Syntax

expression .CurLine

expression A variable that represents a TextBox object.

Remarks

The current line of a control is the line that contains the insertion point. The number of the first line is 0.

The CurLine property is valid when the control has focus.


TextBox.CurTargetX Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.CurTargetX Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the preferred horizontal position of the insertion point in a multiline TextBox. Read-only.

Syntax

expression .CurTargetX

expression A variable that represents a TextBox object.

Remarks

The CurTargetX property retrieves the preferred position, measured in himetric units. A himetric is 0.0001 meter.

The target position is relative to the left edge of the control. If the length of a line is less than the value of the CurTargetX property, you can place the insertion point at the end of the line. The value of CurTargetX changes when the user sets the insertion point or when the CurX property is set. CurTargetX is read-only.

The return value is valid when the object has focus.

You can use CurTargetX and CurX to move the insertion point as the user scrolls through the contents of a multiline TextBox. When the user moves the insertion point to another line of text by scrolling the content of the object, CurTargetX specifies the preferred position for the insertion point. CurX is set to this value if the line of text is longer than the value of CurTargetX. Otherwise, CurX is set to the end of the line of text.


TextBox.CurX Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.CurX Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the current horizontal position of the insertion point in a multiline TextBox. Read/write.

Syntax

expression .CurX

expression A variable that represents a TextBox object.

Remarks

The CurX property applies to a multiline TextBox. The return value is valid when the object has the focus.

You can use CurTargetX and CurX to position the insertion point as the user scrolls through the contents of a multiline TextBox. When the user moves the insertion point to another line of text by scrolling the content of the object, CurTargetX specifies the preferred position for the insertion point. CurX is set to this value if the line of text is longer than the value of CurTargetX. Otherwise, CurX is set to the end of the line of text.


TextBox.DragBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.DragBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether the system enables the drag-and-drop feature for the control. Read/write.

Syntax

expression .DragBehavior

expression A variable that represents a TextBox object.

Remarks

The possible values of DragBehavior are 0 and 1. 0 represents that drag-and-drop action is not allowed. 1 represents that drag-and-drop action is allowed.

If the DragBehavior property is enabled, dragging in a text box starts a drag-and-drop operation on the selected text. If DragBehavior is disabled, dragging in a text box selects text.

You can combine the effects of the EnterFieldBehavior property and DragBehavior to create a large number of text box styles.


TextBox.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a TextBox object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


TextBox.EnterFieldBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.EnterFieldBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the selection behavior when entering a TextBox. Read/write.

Syntax

expression .EnterFieldBehavior

expression A variable that represents a TextBox object.

Remarks

The possible values of EnterFieldBehavior are 0 and 1. 0 represents selecting the entire contents of the edit region when entering the control (default). 1 represents leaving the selection unchanged. Visually, this uses the selection that was in effect the last time the control was active.

The EnterFieldBehavior property controls the way text is selected when the user tabs to the control, not when the control receives focus as a result of the SetFocus method. Following SetFocus, the contents of the control are not selected and the insertion point appears after the last character in the control's edit region.

You can combine the effects of the EnterFieldBehavior property and DragBehavior to create a large number of text box styles.


TextBox.EnterKeyBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.EnterKeyBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that defines the effect of pressing ENTER in a TextBox. Read/write.

Syntax

expression .EnterKeyBehavior

expression A variable that represents a TextBox object.

Remarks

True if pressing ENTER creates a new line, False if pressing ENTER moves the focus to the next object in the tab order (default).

The EnterKeyBehavior and MultiLine properties are closely related. The values described above only apply if MultiLine is True. If MultiLine is False, pressing ENTER always moves the focus to the next control in the tab order regardless of the value of EnterKeyBehavior.

The effect of pressing CTRL+ENTER also depends on the value of MultiLine. If MultiLine is True, pressing CTRL+ENTER creates a new line regardless of the value of EnterKeyBehavior. If MultiLine is False, pressing CTRL+ENTER has no effect.


TextBox.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a TextBox object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


TextBox.HideSelection Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.HideSelection Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether selected text remains highlighted when a control does not have the focus. Read/write.

Syntax

expression .HideSelection

expression A variable that represents a TextBox object.

Remarks

True if selected text is not highlighted unless the control has the focus (default). False if selected text always appears highlighted.

You can use the HideSelection property to maintain highlighted text when another form or a dialog box receives the focus, such as in a spell-checking procedure.


TextBox.IMEMode Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.IMEMode Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the default run-time mode of the Input Method Editor (IME) for a control. Read/write.

Syntax

expression .IMEMode

expression A variable that represents a TextBox object.

Remarks

This property applies only to applications written for Asian languages and is ignored in other applications.

The settings for fmIMEMode are:

Value | Description
0 | Does not control IME (default).
1 | IME on.
2 | IME off. English mode.
3 | IME off. User can't turn on IME by keyboard.
4 | IME on with Full-width Hiragana mode.
5 | IME on with Full-width Katakana mode.
6 | IME on with Half-width Katakana mode.
7 | IME on with Full-width Alphanumeric mode.
8 | IME on with Half-width Alphanumeric mode.
9 | IME on with Full-width Hangul mode.
10 | IME on with Half-width Hangul mode.

A setting of 0 indicates that the mode of the IME does not change when the control receives focus at run time. For any other value, the mode of the IME is set to the value specified by the IMEMode property when the control receives focus at run time.


TextBox.IntegralHeight Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.IntegralHeight Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a TextBox displays full lines of text or partial lines. Read/write.

Syntax

expression .IntegralHeight

expression A variable that represents a TextBox object.

Remarks

True indicates that the text box resizes itself to display only complete items (default). False indicates that the text box does not resize itself even if the item is too tall to display completely.

The IntegralHeight property relates to the height of the text box, just as the AutoSize property relates to the width of the text box.

If IntegralHeight is True, the text box automatically resizes when necessary to show full rows. If False, the text box remains a fixed size; if items are taller than the available space in the text box, the entire item is not shown.


TextBox.LineCount Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.LineCount Property (Outlook Forms Script)
Send feedback

Returns a Long that specifies the number of text lines in a TextBox. Read-only.

Syntax

expression .LineCount

expression A variable that represents a TextBox object.


TextBox.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a TextBox object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


TextBox.MaxLength Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.MaxLength Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the maximum number of characters a user can enter in a TextBox. Read/write.

Syntax

expression .MaxLength

expression A variable that represents a TextBox object.

Remarks

Setting the MaxLength property to 0 indicates there is no limit other than that created by memory constraints.


TextBox.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a TextBox object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


TextBox.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a TextBox object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


TextBox.MultiLine Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.MultiLine Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can accept and display multiple lines of text. Read/write.

Syntax

expression .MultiLine

expression A variable that represents a TextBox object.

Remarks

True if the text is displayed across multiple lines (default). Falase if the text is not displayed across multiple lines.

A multiline TextBox allows absolute line breaks and adjusts its quantity of lines to accommodate the amount of text it holds. If needed, a multiline control can have vertical scroll bars.

A single-line TextBox doesn't allow absolute line breaks and doesn't use vertical scroll bars.

For controls that support the MultiLine property as well as the WordWrap property, WordWrap is ignored when MultiLine is False.

Single-line controls ignore the value of the WordWrap property.

If you change MultiLine to False in a multiline TextBox, all the characters in the TextBox will be combined into one line, including non-printing characters (such as carriage returns and new-lines).

The EnterKeyBehavior and MultiLine properties are closely related. The EnterKeyBehavior values of True and False only apply if MultiLine is True. If MultiLine is False, pressing ENTER always moves the focus to the next control in the tab order regardless of the value of EnterKeyBehavior.

The effect of pressing CTRL+ENTER also depends on the value of MultiLine. If MultiLine is True, pressing CTRL+ENTER creates a new line regardless of the value of EnterKeyBehavior. If MultiLine is False, pressing CTRL+ENTER has no effect.

The TabKeyBehavior and MultiLine properties are closely related. The values described above only apply if MultiLine is True. If MultiLine is False, pressing TAB always moves the focus to the next control in the tab order regardless of the value of TabKeyBehavior.

The effect of pressing CTRL+TAB also depends on the value of MultiLine. If MultiLine is True, pressing CTRL+TAB creates a new line regardless of the value of TabKeyBehavior. If MultiLine is False, pressing CTRL+TAB has no effect.


TextBox.PasswordChar Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.PasswordChar Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies a placeholder character to be displayed instead of the characters actually entered in a TextBox. Read/write.

Syntax

expression .PasswordChar

expression A variable that represents a TextBox object.

Remarks

You can use the PasswordChar property to protect sensitive information, such as passwords or security codes. The value of PasswordChar is the character (usually an asterisk) that appears in a control instead of the actual characters that the user types. If you don't specify a character, the control displays the characters that the user types.


TextBox.ScrollBars Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.ScrollBars Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies whether a control has vertical scroll bars, horizontal scroll bars, or both. Read/write.

Syntax

expression .ScrollBars

expression A variable that represents a TextBox object.

Remarks

The settings for ScrollBars are:

Value | Description
0 | Displays no scroll bars (default).
1 | Displays a horizontal scroll bar.
2 | Displays a vertical scroll bar.
3 | Displays both a horizontal and a vertical scroll bar.

A scroll bar constrains its scroll box to the visible region of the scroll bar. It also modifies the scroll position as needed to keep the entire scroll bar visible. The range of a scroll bar changes when the value of the ScrollBars property changes, the scroll size changes, or the visible size changes.

For a single-line control, you can display a horizontal scroll bar by using the ScrollBars and AutoSize properties. Scroll bars are hidden or displayed according to the following rules:

  1. When ScrollBars is set to 0, no scroll bar is displayed.

  2. When ScrollBars is set to 1 or 3, the control displays a horizontal scroll bar if the text is longer than the edit region and if the control has enough room to include the scroll bar underneath its edit region.

  3. When AutoSize is True, the control enlarges itself to accommodate the addition of a scroll bar unless the control is at or near its maximum size.

For a multiline TextBox, you can display scroll bars by using the ScrollBars, WordWrap, and AutoSize properties. Scroll bars are hidden or displayed according to the following rules:

  1. When ScrollBars is set to 0, no scroll bar is displayed.

  2. When ScrollBars is set to 2 or 3, the control displays a vertical scroll bar if the text is longer than the edit region and if the control has enough room to include the scroll bar at the right edge of its edit region.

  3. When WordWrap is True, the multiline control will not display a horizontal scroll bar. Most multiline controls do not use a horizontal scroll bar.

  4. A multiline control can display a horizontal scroll bar if the following conditions occur simultaneously:

    • The edit region contains a word that is longer than the edit region's width.

    • The control has enabled horizontal scroll bars.

    • The control has enough room to include the scroll bar under the edit region.

    • The WordWrap property is set to False.


TextBox.SelectionMargin Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.SelectionMargin Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the user can select a line of text by clicking in the region to the left of the text. Read/write.

Syntax

expression .SelectionMargin

expression A variable that represents a TextBox object.

Remarks

True if clicking in margin causes selection of text (default), False if clicking in margin does not cause selection of text.

When the SelectionMargin property is True, the selection margin occupies a thin strip along the left edge of a control's edit region. When set to False, the entire edit region can store text.

If the SelectionMargin property is set to True when a control is printed, the selection margin also prints.


TextBox.SelLength Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.SelLength Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the number of characters selected in a TextBox. Read/write.

Syntax

expression .SelLength

expression A variable that represents a TextBox object.

Remarks

For SelLength and SelStart, the valid range of settings is 0 to the total number of characters in the edit area of a TextBox.

The SelLength property is always valid, even when the control does not have focus. Setting SelLength to a value less than zero creates an error. Attempting to set SelLength to a value greater than the number of characters available in a control results in a value equal to the number of characters in the control.

Changing the value of the SelStart property cancels any existing selection in the control, places an insertion point in the text, and sets SelLength to zero.

The default value, zero, means that no text is currently selected.


TextBox.SelStart Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.SelStart Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that represents the starting point of selected text, or the insertion point if no text is selected. Read/write.

Syntax

expression .SelStart

expression A variable that represents a TextBox object.

Remarks

For SelLength and SelStart, the valid range of settings is 0 to the total number of characters in the edit area of a TextBox. The default value is zero.

The SelStart property is always valid, even when the control does not have focus. Setting SelStart to a value less than zero creates an error. Attempting to set SelStart to a value greater than the number of characters available in a control results in a value equal to the number of characters in the control.

Changing the value of SelStart cancels any existing selection in the control, places an insertion point in the text, and sets the SelLength property to zero.


TextBox.SelText Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.SelText Property (Outlook Forms Script)
Send feedback

Returns or sets a String that represents the selected text of a control. Read/write.

Syntax

expression .SelText

expression A variable that represents a TextBox object.

Remarks

If no characters are selected in the edit region of the control, the SelText property returns a zero length string. This property is valid regardless of whether the control has the focus.


TextBox.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a TextBox object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
1 | Object has a highlight on the top and left and a shadow on the bottom and right.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them.
3 | Border appears to be carved around the edge of the control.
6 | Object has a ridge on the bottom and right and appears flat on the top and left.

You can use either the SpecialEffect or the BorderStyle property to specify the edging for a control, but not both. If you specify a nonzero value for one of these properties, the system sets the value of the other property to zero. For example, if you set SpecialEffect to 1, the system sets BorderStyle to 0.

SpecialEffect uses the system colors to define its borders.


TextBox.TabKeyBehavior Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.TabKeyBehavior Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether tabs are allowed in the edit region. Read/write.

Syntax

expression .TabKeyBehavior

expression A variable that represents a TextBox object.

Remarks

True if pressing TAB inserts a tab character in the edit region. False if pressing TAB moves the focus to the next object in the tab order (default).

The TabKeyBehavior and MultiLine properties are closely related. The values described above only apply if MultiLine is True. If MultiLine is False, pressing TAB always moves the focus to the next control in the tab order regardless of the value of TabKeyBehavior.

The effect of pressing CTRL+TAB also depends on the value of MultiLine. If MultiLine is True, pressing CTRL+TAB creates a new line regardless of the value of TabKeyBehavior. If MultiLine is False, pressing CTRL+TAB has no effect.


TextBox.Text Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Text Property (Outlook Forms Script)
Send feedback

Returns or sets a String that specifies text in the control. Read/write.

Syntax

expression .Text

expression A variable that represents a TextBox object.

Remarks

The default value is a zero-length string ("").

Any value you assign to the Text property is also assigned to the Value property.

The ForeColor property determines the color of the text.


TextBox.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a TextBox object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.


TextBox.TextLength Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.TextLength Property (Outlook Forms Script)
Send feedback

Returns a Long that represents the length, in number of characters, of text in the edit region of a TextBox. Read-only.

Syntax

expression .TextLength

expression A variable that represents a TextBox object.

Remarks

For a multiline TextBox, TextLength includes LF (line feed) and CR (carriage return) characters.


TextBox.Value Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies text in the edit region. Read/write.

Syntax

expression .Value

expression A variable that represents a TextBox object.

Remarks

Any value you assign to the Text property is also assigned to the Value property.


TextBox.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

TextBox.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents a TextBox object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.

For controls that support the MultiLine property as well as the WordWrap property, WordWrap is ignored when MultiLine is False.


TextBox Methods (Outlook Forms Script)

 Copy code hover
[image]

TextBox Methods (Outlook Forms Script)
Send feedback

In this section

  • TextBox.Copy Method (Outlook Forms Script)

  • TextBox.Cut Method (Outlook Forms Script)

  • TextBox.Paste Method (Outlook Forms Script)


TextBox.Copy Method (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Copy Method (Outlook Forms Script)
Send feedback

Copies the contents of an object to the Clipboard.

Syntax

expression .Copy

expression A variable that represents a TextBox object.

Remarks

The original content remains on the object.

The actual content that is copied depends on the object. For example, on a TextBox or ComboBox, it copies the currently selected text.


TextBox.Cut Method (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Cut Method (Outlook Forms Script)
Send feedback

Removes selected information from an object and transfers it to the Clipboard.

Syntax

expression .Cut

expression A variable that represents a TextBox object.

Remarks

The Cut method removes currently selected text in the control to the Clipboard. This method does not require that the control have the focus.


TextBox.Paste Method (Outlook Forms Script)

 Copy code hover
[image]

TextBox.Paste Method (Outlook Forms Script)
Send feedback

Transfers the contents of the Clipboard to an object.

Syntax

expression .Paste

expression A variable that represents a TextBox object.

Remarks

Data pasted into a TextBox is treated as text.


ToggleButton Object Reference (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton Object Reference (Outlook Forms Script)
Send feedback

In this section

  • ToggleButton Object (Outlook Forms Script)

  • ToggleButton Members (Outlook Forms Script)

  • ToggleButton Properties (Outlook Forms Script)

  • ToggleButton Events (Outlook Forms Script)


ToggleButton Object (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton Object (Outlook Forms Script)
Send feedback

Shows the selection state of an item.

Remarks

Use a ToggleButton to show whether an item is selected. If a ToggleButton is bound to a data source, the ToggleButton shows the current value of that data source as either Yes/No, True/False, On/Off, or some other choice of two settings. If the user selects the ToggleButton, the current setting is Yes, True, or On. If the user does not select the ToggleButton, the setting is No, False, or Off. If the ToggleButton is bound to a data source, changing the setting changes the value of that data source. A disabled ToggleButton shows a value, but is dimmed and does not allow changes from the user interface.

You can also use a ToggleButton inside a Frame to select one or more of a group of related items. For example, you can create an order form with a list of available items, with a ToggleButton preceding each item. The user can select a particular item by selecting the appropriate ToggleButton.

The default property of a ToggleButton is the Value property.

The only event for a ToggleButton is the Click event.


ToggleButton Members (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton Members (Outlook Forms Script)
Send feedback

Shows the selection state of an item.

Properties

Name | Description
Accelerator | Returns or sets the accelerator key for a control. Read/write.
Alignment | Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.
AutoSize | Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.
BackColor | Returns or sets a Long that specifies the background color of the object. Read/write.
BackStyle | Returns or sets an Integer that specifies the background style for an object. Read/write.
Caption | Returns or sets a String that appears on an object to identify or describe it. Read/write.
Enabled | Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.
ForeColor | Returns or sets a Long that specifies the foreground color of an object. Read/write.
GroupName | Returns or sets a String that identifies a group of mutually exclusive ToggleButton controls. Read/write.
Locked | Returns or sets a Boolean that specifies whether a control can be edited. Read/write.
MouseIcon | Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.
MousePointer | Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.
Picture | Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.
PicturePosition | Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.
SpecialEffect | Returns or sets an Integer that specifies the visual appearance of an object. Read/write.
TextAlign | Returns or sets an Integer that specifies how text is aligned in a control. Read/write.
TripleState | Returns or sets a Boolean that determines whether a user can specify, from the user interface, the Null state for a ToggleButton. Read/write.
Value | Returns or sets a Variant that specifies whether the toggle button is selected. Read/write.
WordWrap | Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Events

Name | Description
Click | Occurs when the user definitively selects a value for the control that has more than one possible value.


ToggleButton Properties (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton Properties (Outlook Forms Script)
Send feedback

In this section

  • ToggleButton.Accelerator Property (Outlook Forms Script)

  • ToggleButton.Alignment Property (Outlook Forms Script)

  • ToggleButton.AutoSize Property (Outlook Forms Script)

  • ToggleButton.BackColor Property (Outlook Forms Script)

  • ToggleButton.BackStyle Property (Outlook Forms Script)

  • ToggleButton.Caption Property (Outlook Forms Script)

  • ToggleButton.Enabled Property (Outlook Forms Script)

  • ToggleButton.ForeColor Property (Outlook Forms Script)

  • ToggleButton.GroupName Property (Outlook Forms Script)

  • ToggleButton.Locked Property (Outlook Forms Script)

  • ToggleButton.MouseIcon Property (Outlook Forms Script)

  • ToggleButton.MousePointer Property (Outlook Forms Script)

  • ToggleButton.Picture Property (Outlook Forms Script)

  • ToggleButton.PicturePosition Property (Outlook Forms Script)

  • ToggleButton.SpecialEffect Property (Outlook Forms Script)

  • ToggleButton.TextAlign Property (Outlook Forms Script)

  • ToggleButton.TripleState Property (Outlook Forms Script)

  • ToggleButton.Value Property (Outlook Forms Script)

  • ToggleButton.WordWrap Property (Outlook Forms Script)


ToggleButton.Accelerator Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Accelerator Property (Outlook Forms Script)
Send feedback

Returns or sets the accelerator key for a control. Read/write.

Syntax

expression .Accelerator

expression A variable that represents a ToggleButton object.

Remarks

To designate an accelerator key, enter a single character for the Accelerator property. You can set Accelerator in the control's property sheet or in code. If the value of this property contains more than one character, the first character in the string becomes the value of Accelerator. You cannot use digits in an accelerator.

When an accelerator key is used, there is no visual feedback (other than focus) to indicate that the control initiated the Click event. For example, if the accelerator key applies to a CommandButton, the user will not see the button pressed in the interface. The button receives the focus, however, when the user presses the accelerator key.


ToggleButton.Alignment Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Alignment Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that indicates the position of a control relative to its caption. Read/write.

Syntax

expression .Alignment

expression A variable that represents a ToggleButton object.

Remarks

The possible values of Alignment is 0 or 1. A value of 0 places the caption to the left of the control. A value of 1 places the caption to the right of the control (default).

The caption text for a control is left-aligned.


ToggleButton.AutoSize Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.AutoSize Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether an object automatically resizes to display its entire contents. Read/write.

Syntax

expression .AutoSize

expression A variable that represents a ToggleButton object.

Remarks

True to automatically resize the control to display its entire contents. False to keep the size of the control constant; contents are clipped when they exceed the area of the control (default).

For controls with captions, the AutoSize property specifies whether the control automatically adjusts to display the entire caption.

If you manually change the size of a control while AutoSize is True, the manual change overrides the size previously set by AutoSize.


ToggleButton.BackColor Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.BackColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the background color of the object. Read/write.

Syntax

expression .BackColor

expression A variable that represents a ToggleButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

You can only see the background color of an object if the BackStyle property is set to 1.


ToggleButton.BackStyle Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.BackStyle Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the background style for an object. Read/write.

Syntax

expression .BackStyle

expression A variable that represents a ToggleButton object.

Remarks

The possible values are 0 and 1. 0 represents the background as transparent, 1 represents the background as opaque.

The BackStyle property determines whether a control is transparent. If BackStyle is 1, the control is not transparent and you cannot see anything behind the control on a form. If BackStyle is 0, you can see through the control and look at anything on the form located behind the control. The BackColor property is only valid if the BackStyle property is set to 1.

BackStyle does not affect the transparency of bitmaps. You must use a picture editor such as Paintbrush to make a bitmap transparent. Not all controls support transparent bitmaps.


ToggleButton.Caption Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Caption Property (Outlook Forms Script)
Send feedback

Returns or sets a String that appears on an object to identify or describe it. Read/write.

Syntax

expression .Caption

expression A variable that represents a ToggleButton object.

Remarks

The default caption for a control is a unique name based on the type of control. For example, CommandButton1 is the default caption for the first command button in a form.

If a control's caption is too long, the caption is truncated. If a form's caption is too long for the title bar, the title is displayed with an ellipsis.

The ForeColor property of the control determines the color of the text in the caption.

Setting AutoSize to True automatically adjusts the size of the control to frame the entire caption.


ToggleButton.Enabled Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Enabled Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can receive the focus and respond to user-generated events. Read/write.

Syntax

expression .Enabled

expression A variable that represents a ToggleButton object.

Remarks

True is the control can receive the focus and respond to user-generated events, and is accessible through code (default). False if the user cannot interact with the control by using the mouse, keystrokes, accelerators, or hotkeys. The control is generally still accessible through code.

Use the Enabled property to enable and disable controls. A disabled control appears dimmed, while an enabled control does not. Also, if a control displays a bitmap, the bitmap is dimmed whenever the control is dimmed.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


ToggleButton.ForeColor Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.ForeColor Property (Outlook Forms Script)
Send feedback

Returns or sets a Long that specifies the foreground color of an object. Read/write.

Syntax

expression .ForeColor

expression A variable that represents a ToggleButton object.

Remarks

You can use any integer that represents a valid color. You can also specify a color by using the Visual Basic RGB function with red, green, and blue color components. The value of each color component is an integer that ranges from zero to 255. For example, you can specify teal blue as the integer value 4966415 or as red, green, and blue color components 15, 200, 75, as shown in the following example.

Copy code Copy code
RGB(15,200,75)

Use the ForeColor property for controls on forms to make them easy to read or to convey a special meaning. For example, if a text box reports the number of units in stock, you can change the color of the text when the value falls below the reorder level.


ToggleButton.GroupName Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.GroupName Property (Outlook Forms Script)
Send feedback

Returns or sets a String that identifies a group of mutually exclusive ToggleButton controls. Read/write.

Syntax

expression .GroupName

expression A variable that represents a ToggleButton object.

Remarks

Use the same GroupName for all buttons in the group. The default setting is an empty string.

To create a group of mutually exclusive ToggleButton controls, you can put the buttons in a Frame on your form, or you can use the GroupName property. GroupName is more efficient for the following reasons:

  • You do not have to include a Frame for each group. By not using a Frame, you reduce the number of controls on the form, and in turn, improve performance and reduce the size of the form.

  • You have more design flexibility. If you use a Frame to create the group, all the buttons must be inside the Frame. If you want more than one group, you must have one Frame for each group. However, if you use GroupName to create the group, the group can include toggle buttons anywhere on the form. If you want more than one group, specify a unique name for each group; you can still place the individual controls anywhere on the form.

  • You can create buttons with transparent backgrounds, which can improve the visual appearance of your form. The Frame is not a transparent control.

Regardless of which method you use to create the group of buttons, clicking one button in a group sets all other buttons in the same group to False. All toggle buttons with the same GroupName within a single container are mutually exclusive. You can use the same group name in two containers, but doing so creates two groups (one in each container) rather than one group that includes both containers.

For example, assume your form includes some toggle buttons and a MultiPage that also includes toggle buttons. The toggle buttons on the MultiPage are one group and the buttons on the form are another group. The two groups do not affect each other. Changing the setting of a button on the MultiPage does not affect the buttons on the form.


ToggleButton.Locked Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Locked Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether a control can be edited. Read/write.

Syntax

expression .Locked

expression A variable that represents a ToggleButton object.

Remarks

True represents that the value of the control cannot be edited. False represents that the value can be edited (default).

When a control is locked and enabled, it can still initiate events and can still receive the focus.

The Enabled and Locked properties work together to achieve the following effects:

  • If Enabled and Locked are both True, the control can receive focus and appears normally (not dimmed) in the form. The user can copy, but not edit, data in the control.

  • If Enabled is True and Locked is False, the control can receive focus and appears normally in the form. The user can copy and edit data in the control.

  • If Enabled is False and Locked is True, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.

  • If Enabled and Locked are both False, the control cannot receive focus and is dimmed in the form. The user can neither copy nor edit data in the control.


ToggleButton.MouseIcon Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.MouseIcon Property (Outlook Forms Script)
Send feedback

Returns a String that represents the full path name of a custom icon that is to be assigned to the control. Read-only.

Syntax

expression .MouseIcon

expression A variable that represents a ToggleButton object.

Remarks

The MouseIcon property is valid when the MousePointer property is set to 99. The mouse icon of an object is the image that appears when the user moves the mouse across that object.

To assign an image for the mouse pointer, you can either assign a picture to the MouseIcon property or load a picture from a file using the LoadPicture function in Visual Basic Scripting Edition.


ToggleButton.MousePointer Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.MousePointer Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the type of pointer displayed when the user positions the mouse over a particular object. Read/write.

Syntax

expression .MousePointer

expression A variable that represents a ToggleButton object.

Remarks

The settings for MousePointer are:

Value | Description
0 | Standard pointer. The image is determined by the object (default).
1 | Arrow.
2 | Cross-hair pointer.
3 | I-beam.
6 | Double arrow pointing northeast and southwest.
7 | Double arrow pointing north and south.
8 | Double arrow pointing northwest and southeast.
9 | Double arrow pointing west and east.
10 | Up arrow.
11 | Hourglass.
12 | "Not" symbol (circle with a diagonal line) on top of the object being dragged. Indicates an invalid drop target.
13 | Arrow with an hourglass.
14 | Arrow with a question mark.
15 | Size all cursor (arrows pointing north, south, east, and west).
99 | Uses the icon specified by the MouseIcon property.

Use the MousePointer property when you want to indicate changes in functionality as the mouse pointer passes over controls on a form. For example, the hourglass setting (11) is useful to indicate that the user must wait for a process or operation to finish.

Some icons vary depending on system settings, such as the icons associated with desktop themes.


ToggleButton.Picture Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Picture Property (Outlook Forms Script)
Send feedback

Returns a String that specifies the full path name of a bitmap to display on a control. Read-only.

Syntax

expression .Picture

expression A variable that represents a ToggleButton object.

Remarks

You must use the control's property page to assign a bitmap to the Picture property. You cannot use the Visual Basic LoadPicture function to assign a bitmap to Picture.

To remove a picture that is assigned to a control, click the value of the Picture property in the property page and then press DELETE. Pressing BACKSPACE will not remove the picture.

For controls with captions, use the PicturePosition property to specify where to display the picture on the object.

Transparent pictures sometimes have a hazy appearance. If you do not like this appearance, display the picture on a control that supports opaque images. Image supports opaque images.


ToggleButton.PicturePosition Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.PicturePosition Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the location of the picture relative to its caption. Read/write.

Syntax

expression .PicturePosition

expression A variable that represents a ToggleButton object.

Remarks

The settings for PicturePosition are:

Value | Description
0 | The picture appears to the left of the caption. The caption is aligned with the top of the picture.
1 | The picture appears to the left of the caption. The caption is centered relative to the picture.
2 | The picture appears to the left of the caption. The caption is aligned with the bottom of the picture.
3 | The picture appears to the right of the caption. The caption is aligned with the top of the picture.
4 | The picture appears to the right of the caption. The caption is centered relative to the picture.
5 | The picture appears to the right of the caption. The caption is aligned with the bottom of the picture.
6 | The picture appears above the caption. The caption is aligned with the left edge of the picture.
7 | The picture appears above the caption. The caption is centered below the picture (default).
8 | The picture appears above the caption. The caption is aligned with the right edge of the picture.
9 | The picture appears below the caption. The caption is aligned with the left edge of the picture.
10 | The picture appears below the caption. The caption is centered above the picture.
11 | The picture appears below the caption. The caption is aligned with the right edge of the picture.
12 | The picture appears in the center of the control. The caption is centered horizontally and vertically on top of the picture.

The picture and the caption, as a unit, are centered on the control. If no caption exists, the picture's location is relative to the center of the control.

This property is ignored if the Picture property does not specify a picture.


ToggleButton.SpecialEffect Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.SpecialEffect Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies the visual appearance of an object. Read/write.

Syntax

expression .SpecialEffect

expression A variable that represents a ToggleButton object.

Remarks

The settings for SpecialEffect are:

Value | Description
0 | Object appears flat, distinguished from the surrounding form by a border, a change of color, or both.
2 | Object has a shadow on the top and left and a highlight on the bottom and right. The control and its border appear to be carved into the form that contains them. Default for ToggleButton.

SpecialEffect uses the system colors to define its borders.

Although the SpecialEffect property exists on the ToggleButton, the property is disabled. You cannot set or return a value for this property on the ToggleButtonToggleButton.


ToggleButton.TextAlign Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.TextAlign Property (Outlook Forms Script)
Send feedback

Returns or sets an Integer that specifies how text is aligned in a control. Read/write.

Syntax

expression .TextAlign

expression A variable that represents a ToggleButton object.

Remarks

The settings for TextAlign are:

Value | Description
1 | Aligns the first character of displayed text with the left edge of the control's display or edit area (default).
2 | Centers the text in the control's display or edit area.
3 | Aligns the last character of displayed text with the right edge of the control's display or edit area.


ToggleButton.TripleState Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.TripleState Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that determines whether a user can specify, from the user interface, the Null state for a ToggleButton. Read/write.

Syntax

expression .TripleState

expression A variable that represents a ToggleButton object.

Remarks

True if the control clicks through three states, False if the control only supports two states, True and False (default).

When the TripleState property is True, a user can choose from the values of Null, True, and False. The null value is displayed as a shaded button.

When TripleState is False, the user can choose either True or False.

A control set to Null does not initiate the Click event.

Regardless of the property setting, the Null value can always be assigned programmatically to a ToggleButton, causing that control to appear shaded.


ToggleButton.Value Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Value Property (Outlook Forms Script)
Send feedback

Returns or sets a Variant that specifies whether the toggle button is selected. Read/write.

Syntax

expression .Value

expression A variable that represents a ToggleButton object.

Remarks

The settings for Value are:

Control | Description
Null | Indicates the item is in a null state, neither selected nor cleared.
True | Indicates the item is selected.
False | Indicates the item is cleared.
Zero (0) | Indicates the first page. The maximum value is one less than the number of pages.


ToggleButton.WordWrap Property (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.WordWrap Property (Outlook Forms Script)
Send feedback

Returns or sets a Boolean that specifies whether the contents of a control automatically wrap at the end of a line and the control expands to fit the text. Read/write.

Syntax

expression .WordWrap

expression A variable that represents a ToggleButton object.

Remarks

True to specify that the text wraps (default), False to specify that the text does not.


ToggleButton Events (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton Events (Outlook Forms Script)
Send feedback

In this section

  • ToggleButton.Click Event (Outlook Forms Script)


ToggleButton.Click Event (Outlook Forms Script)

 Copy code hover
[image]

ToggleButton.Click Event (Outlook Forms Script)
Send feedback

Occurs when the user definitively selects a value for the control that has more than one possible value.

Syntax

expression .Click

expression A variable that represents a ToggleButton object.

Remarks

The following are examples of actions that initiate the Click event of the specified control:

  • Clicking a blank area of a form or a disabled control (other than a list box) on the form.

  • Clicking a control with the left mouse button (left-clicking).

  • Pressing a control's accelerator key.

For some controls, the Click event occurs when the Value property changes. However, using the PropertyChange or CustomPropertyChange event is the preferred technique for detecting a new value for a property. The following are examples of actions that initiate the Click event due to assigning a new value to a control: clicking a ToggleButton, pressing the SPACEBAR when a toggle button has the focus, pressing the accelerator key, or changing the value of the control in code.

The Click event is not initiated when Value is set to Null.

Left-clicking changes the value of a control, thus it initiates the Click event. Right-clicking does not change the value of the control, so it does not initiate the Click event.


Outlook Social Connector 2013 provider reference

 Copy code hover
[image]

Outlook Social Connector 2013 provider reference
Send feedback

Published: July 16, 2012

The Outlook Social Connector 2013 provides a communication hub for personal and professional communications. The Outlook Social Connector (OSC) works with SharePoint Server, SharePoint Workspace, Lync client, and all Office client applications that support presence information and the Contact Card support the OSC. In Outlook in particular, just by selecting an Outlook item such as an email or meeting request and clicking the sender or a recipient in that item, without leaving Outlook, users can see in the People Pane activities, photos, and status updates of this person on their favorite social networks. Users can conveniently see all the Outlook emails, attachments, and meetings received from this person. In an organizational environment, users on a SharePoint site can also see in the People Pane document updates and other site activities of this person on the SharePoint site.

A social network can develop a provider for the OSC to synchronize and surface social network updates in supporting servers and applications. Popular social networks such as LinkedIn, Facebook, and Windows Live are offering providers for the OSC.

The Outlook Social Connector 2013 Provider Reference describes how to develop an OSC provider using OSC provider extensibility.

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs.

In This Section

  • Getting Started with Developing an Outlook Social Connector Provider

    Provides an overview of the OSC, including the following: how an OSC provider can be useful, quick steps for learning to develop a provider, technical requirements, best practices for developing a provider, and what's new in this release.

  • OSC Sample Templates

    Describes several Visual Studio templates for developing a provider.

  • OSC Typical Calling Sequences

    Describes a few typical calling sequences by the OSC of members in the OSC provider extensibility interfaces. This should enable you to better understand how to implement these interfaces.

  • Developing a Provider with the OSC XML Schema

    Describes how the OSC provider extensibility interfaces and OSC XML schema are designed to support an OSC provider.

  • Debugging a Provider

    Suggests a few ways to help debug an OSC provider.

  • Deploying a Provider

    Describes registration requirements for an OSC provider, and provides a checklist for installing a provider.

  • Getting Ready to Release an OSC Provider

    Suggests tests you can do before releasing an OSC provider.

  • Outlook Social Connector Provider Reference

    Provides reference information for the OSC provider extensibility interfaces and OSC XML schema, and lists possible error codes.

Additional Resources

  • Outlook Social Connector 2013 Provider Reference Copyright Notice

  • Outlook Developer Center

  • Document Conventions

  • Accessibility in Microsoft Products

  • Microsoft Online Privacy Notice


Getting Started with Developing an Outlook Social Connector Provider

 Copy code hover
[image]

Getting Started with Developing an Outlook Social Connector Provider
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) Provider Reference describes how to develop an OSC provider by using OSC provider extensibility. If you are new to developing solutions for Outlook, see Selecting an API or Technology for Developing Outlook Solutions to identify the APIs and technologies that are most appropriate for your needs. This section gives an overview of the OSC, how an OSC provider can be useful, quick steps for learning to develop a provider, technical requirements, best practices for developing a provider, and what's new in this release.

In this section

What's New for Providers

Compares OSC features in the previous and current release, and describes interface members and XML schema elements that have been added, changed, or deprecated in this release.

Why Develop an Outlook Social Connector Provider

Describes how an OSC provider can be useful for common social network sites and other internal networking tools.

Relating the OSC with Outlook and Social Networks

Provides an architectural view of how the OSC connects Outlook users with social networks. Also defines the way that common terms, like "social networks," "friends," "non-friends," and "contacts" are used in the rest of this reference.

Quick Steps for Learning to Develop a Provider

Provides a summary of steps to learn to develop an OSC provider.

Technical Requirements

Describes the supported programming languages, COM visibility requirements, method return type requirements, and details of the OSC provider extensibility DLL.

Best Practices for Developing a Provider

Provides a list of best practices to follow while developing an OSC provider.

Reference

Outlook Social Connector Provider Reference

Related sections

OSC Sample Templates

OSC Typical Calling Sequences

Developing a Provider with the OSC XML Schema

Debugging a Provider

Deploying a Provider

Getting Ready to Release an OSC Provider

See also

Other resources

Microsoft Outlook Social Connector 32-bit
Update for Outlook Social Connector (KB983403), 32-Bit Edition
Update for Outlook Social Connector (KB983403), 64-bit Edition
Outlook Social Connector 2013: Provider templates


What's New for Providers

 Copy code hover
[image]

What's New for Providers
See also Send feedback

Published: July 16, 2012

This topic lists the major changes in Outlook Social Connector 2013 (OSC). It presents a comparison of the features available between Outlook Social Connector 2013 and Outlook Social Connector 1.1. It also describes interface members and XML elements that have been added, changed, or deprecated.

In Office 2013, the OSC works with not only Outlook, but also SharePoint Server, SharePoint Workspace, Lync client, and all other Office client applications that support presence information and the Contact Card. An OSC provider can surface social information updates in the WHAT'S NEW tab in the Outlook People Pane, as well as in the Contact Card.

A few major changes in Outlook Social Connector 2013 include the following:

  • If a provider supports showing activities, the provider always synchronizes activities on demand and no longer relies on previously cached activities. That means the provider stores activities of friends and non-friends in memory to display more current activities.

  • For security reasons, providers that communicate with servers over the Internet should use the HTTPS (Hypertext Transfer Protocol (HTTP) with Secure Socket Layer (SSL)) protocol. Otherwise, there is a risk that email addresses, social network activities and other user data is intercepted or exposed while in transit.

  • If you have providers that work with an earlier version of Outlook, to support Office 2013, you should update the setup package. See Installation Checklist for more information.

The following table shows the availability of various features in Outlook Social Connector 2013 as compared with Outlook Social Connector 1.1.

Feature | Outlook Social Connector 2013 | Outlook Social Connector 1.1
End user interface | SharePoint Server, SharePoint Workspace, Lync client, Contact Card in all Office client applications, and People Pane in Outlook | People Pane in Outlook
Basic authentication | Yes | Yes
Forms-based authentication | Yes | Yes
Cached authentication | Yes | Yes
Cached sync for friends to contacts folder on default store | Yes | Yes
Cached activities sync for friends to hidden Newsfeed folder | No | Yes
On-demand sync (picture, name, title) for friends and non-friends on network | Yes | Yes
On-demand activities sync for friends and non-friends on network | Yes | Yes
Follow on network | Yes | Yes
Do not follow on network | Yes | Yes
Visit user profile page | Via a link | Via a network badge
Observing privacy settings on social network (for example, displaying profile and activities of non-friends who allow viewing of such) | Yes | Yes
Hashed email addresses passed to provider | Yes | Yes

Changes from the Previous Version of OSC Provider Extensibility

The following table shows the members that have been added or deprecated from the corresponding interface.

Interface and member

Comment

ISocialProfile::GetActivitiesOfFriendsAndColleagues

Deprecated in Outlook Social Connector 2013. Note that ISocialSession::GetActivities has also been deprecated since Outlook Social Connector 1.1.

To synchronize activity feeds, you should implement the ISocialSession2::GetActivitiesEx method. Set dynamicActivitiesLookupEx as true, which will prompt the OSC to call ISocialSession2::GetActivitiesEx instead.

The following table shows the schema elements that have changed.

Schema element | Comment
capabilities | Added in Outlook Social Connector 2013: allowChangesToAutoConfigure element. Deprecated in Outlook Social Connector 2013: cacheActivities element.
person | Added in Outlook Social Connector 2013: askmeabout, businessAddress, businessCity, businessCountryOrRegion, businessState, businessZip, industries, interests, location, otherAddress, otherCity, otherCountryOrRegion, otherState, otherZip, skills, schools, and website elements.

See also

Concepts

XML for Capabilities
XML for Friends

Other resources

Getting Started with Developing an Outlook Social Connector Provider


Why Develop an Outlook Social Connector Provider

 Copy code hover
[image]

Why Develop an Outlook Social Connector Provider
See also Send feedback

Published: July 16, 2012

An Outlook Social Connector (OSC) provider allows Office users to view within an Office client application an aggregation of social information updates applied on a professional or social network site. SharePoint Server, SharePoint Workspace, Lync client, and all Office client applications that support presence information and the Contact Card support the OSC.

Using a social network provider, the OSC shows additional information about a person in the Contact Card or in the Outlook People Pane, as shown in Figure 1. Because the OSC is built on an open provider model, you can conveniently build providers to work with the OSC to display social network data (such as friends, profiles, activities, and relationship information) in Office.

Apart from public social network sites, you can also use OSC provider extensibility to build providers for line-of-business applications or internal corporate web sites and to integrate their services into Office.

Figure 1. Outlook Social Connector pane

Outlook Social Connector pane

See also

Concepts

Quick Steps for Learning to Develop a Provider
Technical Requirements

Other resources

OSC Sample Templates
Getting Started with Developing an Outlook Social Connector Provider


Relating the OSC with Outlook and Social Networks

 Copy code hover
[image]

Relating the OSC with Outlook and Social Networks
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) can display in the Office Contact Card and Outlook People Pane activities, status, or photo updates for a coworker, friend, or any person you are associated with. By default, the OSC displays the Outlook emails, attachments, and meeting requests received from a selected person. If the selected person and the Office user collaborate on a SharePoint site, the OSC also displays document updates and other site activities from that SharePoint site. Depending on the contexts of association that the Office user is interested in, the Office user can install OSC providers for line-of-business applications, internal corporate websites, or a variety of professional and social network sites, such as LinkedIn, Facebook, and Windows Live.

To support sharing of functionality across Office client applications, the OSC core engine is implemented as part of an Office shared component, and the People Pane is implemented as an Outlook add-in. To use the OSC, an Office user must have installed Outlook on that client computer and configured Outlook with a profile, so that the OSC can cache contacts in a Contacts folder.

An OSC provider is a Component Object Model (COM) DLL that allows the OSC to access social network data in a way that is independent of the APIs of each social network. An OSC provider DLL must be installed locally on a client computer. A social network's OSC provider connects the OSC, which is part of Outlook, with the social network on the Internet.

An OSC provider must implement a set of interfaces, defined as part of the OSC provider extensibility, to communicate with the OSC. OSC provider extensibility is available as an open platform.

The provider architecture of the OSC enables multiple providers to work with the OSC core engine and aggregate social information such as friends and activities. Figure 1 illustrates the OSC provider architecture.

Figure 1. Outlook Social Connector provider architecture

Social networks, OSC providers, OSC, and Office

Terminology

In this Outlook Social Connector Provider Reference, a social network is used to refer to the following types of sites:

  • Collaborative sites such as SharePoint.

  • Social network sites such as Facebook and Windows Live.

  • Professional network sites such as LinkedIn.

  • Other line-of-business applications or corporate internal websites used for networking.

The term friend is used generally to include friends, family, colleagues, connections, and anyone else an Office user is associated with in a collaborative context like SharePoint, or has added to the user's social network account. Non-friends are people referenced in friends' activity updates but are not friends who have been added to the Office user's social network account. Contacts are people in an Outlook contact folder.

See also

Other resources

Getting Started with Developing an Outlook Social Connector Provider


Quick Steps for Learning to Develop a Provider

 Copy code hover
[image]

Quick Steps for Learning to Develop a Provider
See also Send feedback

Published: July 16, 2012

This topic suggests a few steps to learn about developing an Outlook Social Connector (OSC) provider.

Summary of Steps to Develop an OSC Provider

To develop an OSC provider, you need to complete the following general steps:

  • Implement the four mandatory interfaces: ISocialProvider, ISocialSession, ISocialProfile, and ISocialPerson. Depending on your social network's support for caching logon credentials, following a person on the social network, or dynamically synchronizing friends and their activities, you might want to implement the ISocialSession2 interface.

  • In parallel with implementing interfaces, test and debug the OSC provider.

  • Deploy the OSC provider.

  • Do final testing before release.

Step A: Implementing Interfaces

An OSC provider implements interfaces so that the OSC can use these interfaces to obtain necessary information about or from the social network, through the OSC provider. Such information includes the following:

  • How to present the account logon dialog to a user.

  • Whether the provider supports showing friends or activities as displayed on the social network.

  • How to display friends and activities in the Contact Card or Outlook People Pane.

  • When to refresh friends or activities information on the Contact Card or People Pane.

The information is typically passed from the provider to the OSC, in the form of XML strings as output parameters of interface methods. Both the OSC and an OSC provider comply with the OSC provider XML schema. Therefore, in the course of implementing the interfaces, you need a good understanding of how the XML schema allows you to specify information as listed above. The following resources explain how to specify XML for provider capabilities, friends, and activities:

  • OSC Typical Calling Sequences

  • Synchronizing Friends and Activities

  • Capabilities XML Example

  • XML for Capabilities

  • Friends XML Example

  • XML for Friends

  • Activity Feed XML Example

  • XML for Activities

Before you start implementation, also consult the following topics to save you time later in the debugging process:

  • Technical Requirements

  • Best Practices for Developing a Provider

  • OSC Sample Templates

Step B: Debugging

The topic Debugging a Provider suggests debugging procedures you can use while developing an OSC provider.

While you are developing, you can also refer to Getting Ready to Release an OSC Provider to gain a better understanding of the expected behavior in certain scenarios (for example, basic and forms-based authentication).

Step C: Deploying

See the following topics to learn about deployment requirements:

  • Deploying a Provider

  • Registering a Provider

  • Installation Checklist

Step D: Final Testing Before Release

Depending on your social network and the OSC provider, there are usually provider-specific tests you should carry out before you release your provider. For a suggested list of tests, see Getting Ready to Release an OSC Provider.

See also

Other resources

Getting Started with Developing an Outlook Social Connector Provider


Technical Requirements

 Copy code hover
[image]

Technical Requirements
See also Send feedback

Published: July 16, 2012

This topic describes the supported programming languages, COM visibility and method return type requirements, and details of the Outlook Social Connector (OSC) provider extensibility DLL.

Programming Language and COM Requirements

You can create an OSC provider by using managed languages such as Visual C# or Visual Basic, or unmanaged languages such as Visual C++. You can use any tool that can create a COM-visible DLL component to develop an OSC provider. The decision to use a managed or unmanaged language to develop a provider should take into account the download size and dependencies of the provider installation package.

An OSC provider must be COM-visible as defined by the following:

  • After installation, an OSC provider must be registered by using COM self-registration or regsvr32.

  • COM registration of an OSC provider DLL registers the provider under HKCU or HKLM.

  • A provider's ProgID is registered under HKCU\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

  • An OSC provider developed in a managed language is COM-visible.

  • An OSC provider should add values to the Windows registry that indicate that the provider DLL supports both single-threaded apartment (STA) and multithreaded apartment (MTA) threading models. For more information about COM threading models, see Descriptions and Workings of OLE Threading Models.

Methods in OSC provider extensibility must return primitive types such as string or bool. Certain string return values must comply with the schema definition for OSC provider extensibility. Only XML is supported as a return value.

Details of the OSC Provider Extensibility DLL

The component that supports OSC provider extensibility is the OSC provider extensibility DLL. Third-party developers can build OSC provider DLLs by using these extensibility interfaces. The following list shows the details of the OSC provider extensibility DLL:

  • Extensibility DLL file name: socialprovider.dll

  • Extensibility DLL friendly name: Microsoft Outlook Social Provider Extensibility

  • Extensibility DLL major version: 15.0

  • Extensibiilty DLL TypeLib version: 1.1

Miscellaneous Technical Information

JavaScript Object Notation (JSON) is not supported in the OSC provider extensibility model.

There are no dependencies on an XML parser. The OSC provider can use an XML parser that is included with Office, such as Microsoft XML Core Services (MSXML), use the XML parsing capabilities built into the Microsoft .NET Framework, or use a third-party XML parser.

See also

Concepts

Best Practices for Developing a Provider
Quick Steps for Learning to Develop a Provider

Other resources

Deploying a Provider
Getting Started with Developing an Outlook Social Connector Provider


Best Practices for Developing a Provider

 Copy code hover
[image]

Best Practices for Developing a Provider
See also Send feedback

Published: July 16, 2012

You should adhere to the following practices when you develop an Outlook Social Connector 2013 (OSC) provider:

  • For security reasons, providers that communicate with servers over the Internet should use the HTTPS (Hypertext Transfer Protocol (HTTP) with Secure Socket Layer (SSL)) protocol. Otherwise, there is a risk that email addresses, social network activities, and other user data could be intercepted or exposed while in transit.

  • If you are developing an OSC provider for a third-party social network, your provider must adhere to the social network's terms of service.

  • To minimize the size of the provider download package, build the provider by using a native compiler such as C++ or any other tool that can build a COM component.

  • In your provider, create a unique user agent that is sent to the social network to track calls made by the provider to the social network.

  • The ISocialProvider::GetCapabilities method should not rely on calling the social network over the Internet to get the capabilities of the provider. For example, users can start Outlook offline; if the OSC calls GetCapabilities and there is no network connection, the GetCapabilities call will not return valid capabilities XML. The best practice is to store capabilities XML as a resource in your provider.

  • Your OSC provider can generate a significant volume of calls to a social network. Depending on the terms of service for your social network, consider caching friends to an Outlook folder to reduce the number of calls from the OSC to your provider and, in turn, from your provider to the social network.

  • Office 2013 is available in both 32-bit and 64-bit versions. Versions of Office prior to Office 2010 are available only in a 32-bit version. The default installation of Office 2013 on 64-bit Windows is 32-bit. If you intend to support the 64-bit version of the OSC that is installed with 64-bit Office 2013, you must also release a 64-bit version of your provider.

See also

Other resources

OSC Typical Calling Sequences
Developing a Provider with the OSC XML Schema
Deploying a Provider
Getting Started with Developing an Outlook Social Connector Provider


OSC Sample Templates

 Copy code hover
[image]

OSC Sample Templates
Send feedback

Published: July 16, 2012

Accompanying the Outlook Social Connector 2013 Provider Reference are several provider templates in C++, C#, and Visual Basic. You can download the templates at Outlook Social Connector 2013: Provider templates.

The provider templates are available for use when you build a provider in the language of your choice. To minimize the download size of the provider and to minimize provider load time, you should build a production provider by using C++. If you are developing a provider for users who have .NET Framework 3.5 SP1 or a later version of .NET Framework installed on their computers, you can also consider writing a managed provider using C# or Visual Basic.

In this section

Downloading the Samples

Describes how to download and install the sample provider and templates.

Applying a Sample Provider Template

Describes how to use the sample provider templates.

Reference

Outlook Social Connector Provider Reference

Related sections

Getting Started with Developing an Outlook Social Connector Provider

OSC Typical Calling Sequences

Developing a Provider with the OSC XML Schema

Debugging a Provider

Deploying a Provider

Best Practices for Developing a Provider


Downloading the Samples

 Copy code hover
[image]

Downloading the Samples
See also Send feedback

Published: July 16, 2012

This topic describes how to download the code samples that accompany this documentation.

To download the sample code installation package

  1. Download the OSCProviderSamples.zip file from Outlook Social Connector 2013: Provider templates.

  2. Extract the .zip file into the folder of your choice. In Windows 7, the default path for Visual Studio 2010 is C:\Users\user\Documents\Visual Studio 2010\Projects.

  3. After extracting the .zip file, you will find the following projects in your projects folder:

    • OSCProvider_CPP—Contains the C++ provider template.

    • OSCProvider_CS—Contains the C# provider template.

    • OSCProvider_VB—Contains the Visual Basic provider template.

See also

Concepts

Applying a Sample Provider Template

Other resources

OSC Sample Templates


Applying a Sample Provider Template

 Copy code hover
[image]

Applying a Sample Provider Template
See also Send feedback

Published: July 16, 2012

The sample Outlook Social Connector (OSC) provider templates give you a framework for implementing an OSC provider. The provider templates are available in C++, C#, and Visual Basic. These templates are just a starting point for your provider development; the templates do not address writing the implementation code for the provider and creating a setup package for the provider. The following procedure shows how to apply an OSC provider template when you begin to develop a provider.

To apply an OSC provider template

  1. On the Start menu, right-click Microsoft Visual Studio 2010 and click the Run as administrator command. When prompted, click Yes to run Visual Studio as an administrator.

  2. Change the project name and namespace in the template to your project name and namespace identifiers.

  3. Modify the AssemblyInfo class to specify the appropriate assembly information.

  4. Implement the interface members marked as To-Do and add more dependencies and references, as required.

  5. Build the project.

  6. Ensure that the provider assembly ProgID is listed as a key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

  7. To distribute the setup project, create a setup project in Visual Studio or a setup tool of your choice.

  8. Your setup project should complete COM registration for your assembly and also create the ProgID key as listed in step 5.

See also

Concepts

Downloading the Samples

Other resources

OSC Sample Templates


OSC Typical Calling Sequences

 Copy code hover
[image]

OSC Typical Calling Sequences
See also Send feedback

Published: July 16, 2012

This section describes the Outlook Social Connector (OSC) typical calling sequences of members in the OSC provider extensibility interfaces, which an OSC provider implements. The typical calling sequences illustrate how and when the OSC uses such interfaces and methods, to let you better determine how to implement a given member on a provider extensibility interface. The actual calling sequence can vary depending on the capabilities returned by the ISocialProvider::GetCapabilities method. Examples of capabilities include the following:

  • Provider support for getting, caching, or dynamically looking up friends and activities from the social network.

  • The user interface that the OSC should display for user logon.

  • The authentication type (for example, forms-based authentication) that the OSC should use.

In this section

Basic Authentication

Describes the typical calling sequence of the OSC to support an Office user who is logging on to a social network, if the OSC provider supports basic authentication.

Forms-Based Authentication

Describes the typical calling sequence of the OSC to support an Office user who is logging on to a social network, if the OSC provider supports forms-based authentication.

Getting Activities

Describes the typical calling sequence of the OSC to synchronize the activities of the Office user's friends from a social network, if the social network OSC provider supports synchronization of activities.

Getting Friends Information

Describes the typical calling sequence of the OSC to synchronize the Office user's friends list from a social network, if the social network OSC provider supports cached synchronization of contacts.

Reference

Outlook Social Connector Provider Reference

Related sections

Getting Started with Developing an Outlook Social Connector Provider

OSC Sample Templates

Developing a Provider with the OSC XML Schema

Debugging a Provider

Deploying a Provider

Best Practices for Developing a Provider

See also

Concepts

XML for Capabilities


Basic Authentication

 Copy code hover
[image]

Basic Authentication
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) calls the ISocialProvider::GetCapabilities method to determine the capabilities of the OSC provider for a social network. The OSC uses the returned capabilities to determine how to support an Office user who is logging on to this social network. If the useLogonWebAuth element in the returned capabilities XML indicates that the OSC provider supports basic authentication, the OSC can make the following calling sequence to allow a user to log on to that social network:

  1. ISocialProvider::Load—The OSC loads the provider.

  2. ISocialProvider::Version—The OSC gets a string that represents the version number of the OSC provider.

  3. ISocialProvider::SocialNetworkName—The OSC gets a string that represents the social network name.

  4. ISocialProvider::SocialNetworkGuid—The OSC gets an immutable GUID that represents the social network.

  5. ISocialProvider::GetCapabilities—The OSC gets a string that represents the provider's capabilities and that complies with the schema definition for the capabilities element.

  6. ISocialProvider::SocialNetworkIcon—The OSC gets a byte array that represents the icon for the social network site.

  7. ISocialProvider::GetSession—The OSC gets an ISocialSession interface.

  8. ISocialSession::Logon—The OSC logs the user on to the social network site by using the specified user name and password.

  9. ISocialSession::GetLoggedOnUser—The OSC gets an ISocialProfile interface that represents the logged-on user.

  10. ISocialSession::GetNetworkIdentifier—The OSC gets a string that represents a unique identifier for a social network site. The network identifier can be equivalent to the network name.

See also

Concepts

XML for Capabilities

Other resources

OSC Typical Calling Sequences


Forms-Based Authentication

 Copy code hover
[image]

Forms-Based Authentication
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) calls the ISocialProvider::GetCapabilities method to determine the capabilities of the OSC provider for a social network. The OSC uses the returned capabilities to determine how to support an Office user who is logging on to this social network. If the useLogonWebAuth element in the returned capabilities XML indicates that the OSC provider supports forms-based authentication, the OSC can make the following calling sequence to allow a user to log on to that social network:

  1. ISocialProvider::Load—The OSC loads the provider.

  2. ISocialProvider::Version—The OSC gets a string that represents the version number of the provider for this social network.

  3. ISocialProvider::SocialNetworkName—The OSC gets a string that represents the social network name.

  4. ISocialProvider::SocialNetworkGuid—The OSC gets an immutable GUID that represents the social network.

  5. ISocialProvider::GetCapabilities—The OSC gets a string that represents the provider's capabilities and that complies with the schema definition for the capabilities element.

  6. ISocialProvider::SocialNetworkIcon—The OSC gets a byte array that represents the icon for the social network site.

  7. ISocialProvider::GetSession—The OSC gets an ISocialSession interface.

  8. ISocialSession::LogonWeb—The OSC initializes logging on to the social network site by forms-based authentication. For this initial logon call, the OSC passes null for the connectIn parameter.

  9. ISocialSession::GetLogonUrl—The OSC gets the URL to display a browser-based form to the user during web authentication.

  10. ISocialSession::LogonWeb—The OSC completes the logon to the social network site by using forms-based authentication. The OSC calls this method a second time, passing the URL of the logon form to the provider in the connectIn parameter.

  11. ISocialSession::GetLoggedOnUser—The OSC gets an ISocialProfile interface that represents the logged-on user.

  12. ISocialSession::GetNetworkIdentifier—The OSC gets a string that represents a unique identifier for a social network site. The network identifier can be equivalent to the network name.

See also

Concepts

XML for Capabilities

Other resources

OSC Typical Calling Sequences


Getting Friends Information

 Copy code hover
[image]

Getting Friends Information
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) calls the ISocialProvider::GetCapabilities method to determine the capabilities of the OSC provider for a social network. If the getFriends and cacheFriends elements in the returned capabilities XML indicate that the OSC provider supports getting friends and caching friends as Outlook contact items in a corresponding contacts folder, the OSC can make the following calling sequence. The OSC calls methods in this sequence to get information and pictures (as supported by the ISocialPerson interface) for friends on the social network.

Note Note

The OSC refreshes the cache at a default interval. If an error occurs during cache refresh, the OSC retries at another preset interval, which can also be controlled by specifying the contactSyncRestartInterval element in the capabilities XML. For more information about refreshing the contacts cache, see Synchronizing Friends and Activities.

  1. ISocialSession::LoggedOnUserID—The OSC gets the user ID of the Office user who is logged onto the social network.

  2. ISocialSession::GetPerson—Using the user ID of the Office user, the OSC gets an ISocialPerson object for that user.

  3. ISocialPerson::GetFriendsAndColleagues—The OSC gets the user's friend list on the social network.

  4. ISocialSession::GetPerson—For each person in the XML returned by GetFriendsAndColleagues, the OSC gets an ISocialPerson interface.

  5. ISocialPerson::GetPicture—For each person in the XML returned by GetFriendsAndColleagues, the OSC gets a picture resource.

See also

Concepts

XML for Capabilities

Other resources

OSC Typical Calling Sequences


Getting Activities

 Copy code hover
[image]

Getting Activities
See also Send feedback

Published: July 16, 2012

The OSC calls the ISocialProvider::GetCapabilities method to determine the capabilities of the OSC provider for a social network. If the getActivities and dynamicActivitiesLookupEx elements in the returned capabilities XML indicate that the OSC provider supports getting activities on demand and storing activities in memory, the OSC can make the following calling sequence. The OSC also notes the hash function specified in the hashFunction element in the capabilities XML. The OSC calls methods in the following sequence to get activities and information (as supported by the ISocialPerson interface) for friends and non-friends on the social network:

  1. ISocialSession::GetLoggedOnUser—At the end of the authentication process, the OSC calls GetLoggedOnUser to obtain an ISocialProfile interface for the user being authenticated. For more information on authentication, see Basic Authentication and Forms-Based Authentication.

  2. ISocialSession2::GetActivitiesEx—For the persons displayed in the Outlook People Pane, the OSC obtains and hashes their SMTP addresses, calls ISocialSession2::GetActivitiesEx, and stores (in memory) the activities data returned for these persons. The OSC gets in an output parameter, activities, which is a string that contains a collection of activities for friends of the logged-on user. This string conforms to the schema definition for the activityFeed element.

  3. ISocialSession::GetPerson—For each activityDetails element in the activityFeed XML returned by GetActivitiesEx, there is an ownerID element that indicates the person who owns that activity. The OSC uses that ownerID value to call GetPerson to get an ISocialPerson interface for that person.

  4. ISocialPerson::GetDetails—Based on the ISocialPerson object obtained from step 3, the OSC calls GetDetails to get details for that person, such as the first name and last name. The OSC can do the same for each activity specified in an activityDetails element in the activityFeed XML returned by GetActivitiesEx in step 2.

Note Note

The OSC refreshes the activities cache at a default interval. For more information about refreshing the activities cache, see Synchronizing Friends and Activities.

See also

Concepts

XML for Capabilities

Other resources

OSC Typical Calling Sequences


Developing a Provider with the OSC XML Schema

 Copy code hover
[image]

Developing a Provider with the OSC XML Schema
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) provider XML schema defines the format of a significant amount of information that is passed from a social network through the network's OSC provider to the OSC. The XML schema allows an OSC provider to specify capabilities of the provider, friends, and activity feed items on the social network, by using the three main elements, capabilities, friends, and activityFeed, and their child elements. The OSC provider implements interfaces and their methods in the OSC provider extensibility, returning XML strings as output parameters that comply with the OSC provider XML schema. The OSC calls these methods to obtain information that it can understand as defined by the XML schema.

Note Note

OSC provider extensibility supports debugging providers by setting the DebugProviders value of the HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector registry key to 1. When you turn on provider debugging, the OSC validates the provider XML against the version of the OSC XML schema that you specify in the xmlns XML attribute. For OSC 1.1 and versions of the OSC since Outlook Social Connector 2013, specify the xmlns attribute as follows:

xmlns="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd"

In this section

Synchronizing Friends and Activities

Describes the various ways that OSC providers can synchronize friends, non-friends, and activities on a social network.

OSC Provider XML Examples

Includes XML examples that show how to specify capabilities of an OSC provider, friends, and activity feed items on a social network by using the OSC XML schema.

XML for Capabilities

Explains the ISocialProvider::GetCapabilities method that the OSC uses to obtain capabilities information, expressed in capabilities XML, from the OSC provider. This section also describes the XML elements in the OSC provider XML schema that allow an OSC provider to specify its functionality, including how it authenticates users and synchronizes friends and activities.

XML for Friends

Gives examples of the APIs that the OSC uses to obtain friends' information, expressed in friends XML, from the OSC provider. This section also describes elements in the friends XML.

XML for Activities

Gives examples of the APIs that the OSC uses to obtain activities information, expressed in activityFeed XML, from the OSC provider. This section also describes the XML elements in the OSC provider XML schema that allow an OSC provider to specify an activity feed. An activity feed includes the network where the activity feed items originated, details of each activity feed item (such as owner, type, and publish date of the activity), and the template to display the activity.

Reference

Outlook Social Connector Provider Reference

Related sections

Getting Started with Developing an Outlook Social Connector Provider

OSC Sample Templates

OSC Typical Calling Sequences

Debugging a Provider

Deploying a Provider

Best Practices for Developing a Provider

See also

Concepts

Debugging a Provider


Synchronizing Friends and Activities

 Copy code hover
[image]

Synchronizing Friends and Activities
See also Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) supports displaying information from a social network about a person in the Contact Card or in the Outlook People Pane. SharePoint Server, SharePoint Workspace, Lync client, and all Office client applications that support presence information support the Contact Card.

You can use the Contact Card in collaboration scenarios in Office applications to find out more about the people you're collaborating with. Examples of these scenarios include messaging in Outlook and co-authoring a document in Word. When you click the What's new tab of a Contact Card, the displays information about that person.

The Outlook People Pane displays information about a person who can be a sender or recipient of an Outlook item you have selected. Whenever you select another person in the People Pane or another item in the Outlook explorer, or open an Outlook item in an inspector, the Outlook Social Connector (OSC) refreshes the People Pane.

For the Contact Card or People Pane to display current information for the selected person, the OSC synchronizes such information through the OSC providers and some form of caching. This synchronization depends on the OSC providers that are installed on the client computer, the social networks that you have logged onto through their OSC providers, and the synchronization mode that each of the OSC providers for these social networks supports.

The OSC supports synchronizing friends, non-friends, and activities for friends and non-friends in different ways: cached synchronization, on-demand synchronization, and hybrid synchronization. The main difference among these modes of synchronization is where the OSC stores the data—whether it is in a folder in the user's default Outlook store, or in memory on the user's computer. In each case as noted in this topic, there is a default minimum time that the data remains in the folder or memory before the data is refreshed. In some cases, the minimum amount of time can be customized by group policy. For more information about group policies that control the behavior of the OSC, see How to manage the Outlook Social Connector by using Group Policy.

Note that if the selected person is not a member of the social network, the OSC does not display any person or activity information for that person in the Contact Card or People Pane.

Cached Synchronization

An OSC provider can store information for friends on the social network in a specific folder on the user's default Outlook store, and periodically update that cache after a specified length of time has expired. Caching information in a folder has the advantage of reducing traffic to the social network.

Note Note

Starting in Outlook Social Connector 2013, the OSC no longer supports cached synchronization of activities.

Cached Synchronization of Friends

If an OSC provider supports cached synchronization for friends, the OSC caches information for friends of the logged-on user on the social network. The information is cached in an Outlook contacts folder that's specific to that social network in the user's default Outlook store. The contacts folder name is based on the name of the social network, which the OSC obtains by using the ISocialProvider::SocialNetworkName property.

In cached synchronization, the OSC stores information for only the logged-on user's friends on the social network. The OSC does not access information for non-friends.

The default interval for the OSC to refresh the contacts folder for friends' information from the social network is once per day (or once per 1440 minutes). This refresh interval can also be set by group policy, as discussed at the beginning of this topic.

If an error occurs during a refresh, the OSC retries at an interval that is specified by the contactSyncRestartInterval element in the capabilities XML. This retry interval has a default value of 30 minutes, and can also be set by group policy.

When a user opens a Contact Card and selects the What's new tab, the What's new tab refreshes. Similarly, when an Outlook user reselects an item in Outlook or reselects a person on the People Pane, the People Pane refreshes. If the cache refresh interval has not expired, the OSC goes to the cache to obtain any information for the selected user. This avoids the overhead of using OSC provider extensibility to access the social network. If the refresh interval has expired, the OSC calls the ISocialPerson::GetFriendsAndColleagues method to get current friends' information for the logged-on user, and updates the cache in the contacts folder.

The OSC provider informs the OSC that it supports cached synchronization of friends by specifying the following elements in the capabilities XML:

  • getFriends = true

  • cacheFriends = true

  • dynamicContactsLookup = false

On-Demand Synchronization

When a user selects the What's new tab in a Contact Card, or selects a different Outlook item or a different person in the People Pane in Outlook, the OSC refreshes the Contact Card or People Pane respectively. If an OSC provider supports on-demand synchronization of persons or activities, the OSC synchronizes with a cache in memory, and updates details, such as name, title, picture, and activity streams, on the Contact Card or People Pane. For on-demand synchronization, unlike cached synchronization, the OSC attempts to refresh the information for the person regardless of whether that person is a friend or non-friend of the logged-on user on the social network.

On-demand person (or activity) data is stored in memory only. The in-memory data is cleared when the Office client application shuts down, or the user causes a refresh of the Contact Card or People Pane and the data has remained in memory for longer than the refresh interval. Note that the refresh from the social network is always initiated by a user refreshing the Contact Card or People Pane, (for example, by selecting a different user in the People Pane, or selecting a different item in Outlook explorer window). However, the reverse is not always true—not every refresh of the Contact Card or People Pane necessarily incurs a refresh from the social network. If the user refreshes the Contact Card or People Pane, and the person (or activity) data has remained in memory for longer than the refresh interval, the OSC calls ISocialSession2::GetPeopleDetails (or ISocialSession2::GetActivitiesEx) to update the information in memory from the social network. The allowed period for friend and non-friend information in memory is 24 hours, and for activities, 30 minutes.

One important difference between cached and on-demand synchronization is that on-demand synchronization can fetch person and activity information for both friends and non-friends on the network. If the selected person is a non-friend, the OSC refreshes information and activities for that person if either of the following requirements is met:

  • The person is a user on the social network and allows public viewing of profile and activity information.

  • The person is in the same network as the logged-on user on that social network (for example, in the same network for university alumni).

On-demand synchronization of persons and activities results in more calls to the provider from the OSC core engine. Social networks must be able to handle the increased bandwidth requirements of on-demand synchronization.

Specifying XML Elements for On-Demand Synchronization

The OSC provider informs the OSC that it supports on-demand synchronization of friends and non-friends by specifying the following elements in the capabilities XML:

  • getFriends = true

  • cacheFriends = false

  • dynamicContactsLookup = true

The OSC provider informs the OSC that it supports on-demand synchronization of activities by specifying the following elements in the capabilities XML:

  • getActivities = true

  • cacheActivities = false

  • dynamicActivitiesLookupEx = true

Hybrid Synchronization

An OSC provider can support hybrid synchronization of friends and non-friends. This can optimize the calls between the OSC core engine and the OSC provider, the calls to the social network for on-demand synchronization of friends, and the currency of the friends' data. The minimum time the data can remain in a folder or memory, where applicable, is the same as the limits in cached or on-demand synchronization modes.

Note Note

Starting in Outlook Social Connector 2013, the OSC supports only on-demand synchronization of activities and no longer supports hybrid synchronization of activities.

Hybrid Synchronization of Friends and Non-Friends

If an OSC provider supports hybrid synchronization of friends and non-friends, the OSC does the following:

  • The OSC stores information for friends of the logged-on user in the social network-specific contact folder.

  • The OSC stores information for non-friends of the logged-on user in memory.

The OSC provider informs the OSC that it supports hybrid synchronization of friends and non-friends by specifying the following elements in the capabilities XML:

  • getFriends = true

  • cacheFriends = true

  • dynamicContactsLookup = true

Synchronization Intervals

The following table summarizes the synchronization intervals for friends and non-friends information between the corresponding cache (folder or memory) and the social network, depending on the supported synchronization mode. For hybrid synchronization mode, refer to the rows for cached mode for friends, and the row for on-demand mode for non-friends.

Synchronization mode for persons | Where refresh interval is set | Default minimum time before refresh | Group policy override
Cached | Set within OSC | 1440 minutes (24 hours) | Windows registry value NetContactSyncInterval
Cached | contactSyncRestartInterval element in capabilities XML | 30 minutes if contactSyncRestartInterval is not set | Windows registry value contactSyncRestartInterval
On-demand | Set within OSC | 1440 minutes (24 hours) | Windows registry value OnlineSearchExpiryTime

The following table summarizes the synchronization intervals for activities of friends and non-friends between the corresponding cache (folder or memory) and the social network, depending on the supported synchronization modes.

Synchronization mode for activities | Where refresh interval is set | Default minimum time before refresh | Group policy override
On-demand | Set within OSC | 30 minutes | Windows registry value OnlineSearchExpiryTime

The following information applies to the Windows registry values listed in the two tables:

  • Key: HKEY_CURRENT_USER\Software\Policies\Microsoft\Office\Outlook\SocialConnector

  • Value: DWORD value between 1 and 10080

See also

Concepts

Capabilities XML Example
XML for Capabilities

Other resources

Developing a Provider with the OSC XML Schema
How to manage the Outlook Social Connector by using Group Policy


OSC Provider XML Examples

 Copy code hover
[image]

OSC Provider XML Examples
See also Send feedback

Published: July 16, 2012

This section contains XML examples that use the capabilities, friends, and activityFeed XML elements, complying with the Outlook Social Connector (OSC) provider XML schema.

  • Capabilities XML Example shows the capabilities XML of an OSC provider, specifying its capabilities and requirements for the OSC.

  • Friends XML Example shows the friends XML for two persons on the social network.

  • Activity Feed XML Example shows the activityFeed XML of four activities: two profile picture updates, a status update, and a blog post. The XML also specifies three activity display templates for displaying the corresponding activities.

See also

Concepts

Outlook Social Connector Provider XML Schema

Other resources

Developing a Provider with the OSC XML Schema


Capabilities XML Example

 Copy code hover
[image]

Capabilities XML Example
See also Send feedback

Published: July 16, 2012

The XML example in this topic is an XML string returned to the Outlook Social Connector (OSC) after it calls the ISocialProvider::GetCapabilities method for a social network. The XML shows how an OSC provider specifies its capabilities and requirements for the OSC.

Capabilities for Friends

In this example, the OSC provider specifies the following elements to show its capabilities in supporting the friends feature:

  • getFriends as true to indicate the OSC provider supports the ISocialPerson::GetFriendsAndColleagues method to get friends' information programmatically.

  • cacheFriends as true to support caching friends' information in an Outlook contacts folder.

  • contactSyncRestartInterval as 60 to indicate that on error, the OSC should retry refreshing the cache every 60 minutes.

  • followPerson as true to indicate the ability to add friends on the social network.

  • doNotFollowPerson as false to indicate the OSC provider does not support removing a person as a friend on the social network.

  • dynamicContactsLookup as false to indicate that the OSC should not store friends' information in memory.

Capabilities for Activities

The OSC provider specifies the following elements to show its capability to support activities:

  • getActivities as true to indicate that the OSC provider supports the ISocialProfile::GetActivitiesOfFriendsAndColleagues method to get friends' activities programmatically.

  • cacheActivities as false to support caching activities of friends in the hidden Outlook News Feed folder.

  • dynamicActivitiesLookupEx as true to indicate that the OSC should store friends' activities in memory.

Capabilities for Authentication and Account Configuration

The OSC provider specifies the following elements to show its support for authentication and account configuration:

  • useLogonWebAuth as false to indicate that the OSC provider supports basic authentication.

  • supportsAutoConfigure as false to indicate that the OSC should not attempt to automatically configure and log on to the social network for the user.

  • useLogonCached and hideRememberMyPassword as false to indicate that the OSC should prompt for password every time and should not use cached logon credentials to log on.

  • displayUrl as false to indicate that the OSC should not display the URL for the social network in the account configuration dialog box.

  • hideHyperlinks as false to indicate that the OSC provider supports only existing accounts with known passwords, and the OSC should not display the Click here to create an account and Forgot your password? hyperlinks in the account configuration dialog box.

XML Example

The following example shows the capabilities XML of an OSC provider.

XML Copy code Copy code
<?xml version="1.0" encoding="utf-8" ?>
<capabilities xmlns="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd">
  <getFriends>true</getFriends>
  <cacheFriends>true</cacheFriends>
  <followPerson>true</followPerson>
  <doNotFollowPerson>false</doNotFollowPerson>
  <getActivities>true</getActivities>
  <cacheActivities>false</cacheActivities>
  <displayUrl>false</displayUrl>
  <useLogonWebAuth>false</useLogonWebAuth>
  <hideHyperlinks>false</hideHyperlinks>
  <supportsAutoConfigure>false</supportsAutoConfigure>
  <contactSyncRestartInterval>60</contactSyncRestartInterval>
  <dynamicActivitiesLookupEx>true</dynamicActivitiesLookupEx>
  <dynamicContactsLookup>false</dynamicContactsLookup>
  <useLogonCached>false</useLogonCached>
  <hideRememberMyPassword>false</hideRememberMyPassword>
  <createAccountUrl>http://contoso.com/createAccount</createAccountUrl>
  <forgotPasswordUrl>http://contoso.com/forgotPassword</forgotPasswordUrl>
</capabilities>

See also

Concepts

OSC Provider XML Examples
XML for Capabilities
Friends XML Example
Activity Feed XML Example
Outlook Social Connector Provider XML Schema


Friends XML Example

 Copy code hover
[image]

Friends XML Example
See also Send feedback

Published: July 16, 2012

The XML example in this topic is a friend XML string returned to the Outlook Social Connector (OSC) after it calls the ISocialPerson::GetFriendsAndColleagues method. The example shows the friends XML for two friends, each delimited by the person element. Each friend specifies a unique value for the userID element on the social network.

The remaining elements of the friends XML have self-explanatory names. For detailed description of these elements, see XML for Friends.

XML Example

The following example shows the friends XML for two persons on the social network.

XML Copy code Copy code
<?xml version="1.0" encoding="utf-8"?>
<friends xmlns="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd">
  <person>
    <userID>4667647</userID>
    <firstName>Melissa</firstName>
    <lastName>MacBeth</lastName>
    <nickname></nickname>
    <fileAs>MacBeth, Melissa (Contoso Ltd.)</fileAs>
    <company>Contoso Ltd.</company>
    <title>Product Manager</title>
    <anniversary>2005-05-17</anniversary>
    <birthday>1979-08-09</birthday>
    <emailAddress>melissa@contoso.com</emailAddress>
    <emailAddress2>melissa@fabrikam.com</emailAddress2>
    <emailAddress3>melissa@adventureworks.com</emailAddress3>
    <webProfilePage>http://contoso.com/melissa</webProfilePage>
    <phone>800-555-1212</phone>
    <cell>888-555-1212</cell>
    <workPhone>425-555-1212</workPhone>
    <creationTime>2010-01-08T08:30:20-08:00</creationTime>
    <lastModificationTime>2010-01-08T11:40:14-08:00</lastModificationTime>
    <expirationTime>2010-01-09T11:40:14-08:00</expirationTime>
    <gender>female</gender>
    <index>0</index>
  </person>
  <person>
    <userID>5015012</userID>
    <firstName>Michael</firstName>
    <lastName>Affronti</lastName>
    <nickname>Mr. Social</nickname>
    <fileAs>Affronti, Michael (Contoso Ltd.)</fileAs>
    <company>Contoso Ltd.</company>
    <title>Sales Director</title>
    <anniversary>2009-06-21</anniversary>
    <birthday>1980-09-10</birthday>
    <emailAddress>michael@contoso.com</emailAddress>
    <emailAddress2>michael@fabrikam.com</emailAddress2>
    <emailAddress3>michael@adventureworks.com</emailAddress3>
    <webProfilePage>http://contoso.com/michael</webProfilePage>
    <phone>800-555-1212</phone>
    <cell>888-555-1212</cell>
    <workPhone>425-555-1212</workPhone>
    <creationTime>2010-01-08T08:30:20-08:00</creationTime>
    <lastModificationTime>2010-01-08T11:40:14-08:00</lastModificationTime>
    <expirationTime>2010-01-09T11:40:14-08:00</expirationTime>
    <gender>male</gender>
    <index>1</index>
  </person>
</friends>

See also

Concepts

OSC Provider XML Examples
Capabilities XML Example
Activity Feed XML Example
Outlook Social Connector Provider XML Schema


Activity Feed XML Example

 Copy code hover
[image]

Activity Feed XML Example
See also Send feedback

Published: July 16, 2012

The XML example in this topic is an activity feed XML string returned to the Outlook Social Connector (OSC) after it calls the ISocialSession2::GetActivitiesEx method for a social network.

The example shows the activityFeed XML that contains the following four activities, each delimited by the activityDetails element and matching a template for display purposes:

  • A profile picture update by Melissa Macbeth, whose ownerID on the social network is 4667647. This activity specifies three template variables of type publisherVariable, listVariable, and pictureVariable (which is enclosed in listVariable). These variables specify the person who published the activity feed item, and information for the picture to be updated (by using the name, value, altText, and href child elements of pictureVariable).

  • A profile picture update by Michael Affronti whose ownerID on the social network is 5015012. Similar to the last activity, this activity specifies three template variables of type publisherVariable, listVariable, and pictureVariable. These variables specify the person who published the activity feed item and information for the picture to be updated.

  • A status update by Michael Affronti, showing the same ownerID of 5015012 as the last activity. This activity specifies two template variables of type publisherVariable and textVariable. publisherVariable specifies the person who published the activity feed item, and textVariable includes a value of the status line is hiking on Mount Rainier this weekend!

  • A blog post by Michael Affronti, showing the same ownerID of 5015012 as the last two activities. This activity specifies two template variables of type publisherVariable and linkVariable. publisherVariable specifies the person who published the activity feed item, and linkVariable includes further information (specified by the name, text, and value child elements of linkVariable) about the blog post.

Each of the four activities specifies a templateID value, which matches one of the three templates specified by the templates element. Each template is in its own activityTemplateContainer element, identified by a templateID value that is also used to display an activity that has the same templateID value.

For a detailed description of the XML elements used in the example, see the following topics:

  • Overview of XML for an Activity Feed Item

  • activityDetails Element

  • activityTemplateContainer Element

  • Template Variables

XML Example

The following example shows the activityFeed XML of four activities: two profile picture updates, a status update, and a blog post. The XML also specifies three activity display templates for displaying the corresponding activities.

XML Copy code Copy code
<?xml version="1.0" encoding="utf-8"?>
<activityFeed xmlns="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd">
  <network>Contoso</network>
  <activities>
    <activityDetails>
      <ownerID>4667647</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a31</objectID>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <publishDate>2010-03-05T17:19:57</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>4667647</id>
          <nameHint>Melissa Macbeth</nameHint>
          <profileUrl>http://www.contoso.com/</profileUrl>
        </templateVariable>
        <templateVariable type="listVariable">
          <name>ProfilePhoto</name>
          <listItems>
            <simpleTemplateVariable type="pictureVariable">
              <name>Photo</name>
              <value>http://office.microsoft.com/global/images/default.aspx?assetid=ZA103873861033</value>
              <altText>Melissa Macbeth</altText>
              <href>http://office.microsoft.com/global/images/default.aspx?assetid=ZA103873861033</href>
            </simpleTemplateVariable>
          </listItems>
        </templateVariable>
      </templateVariables>
    </activityDetails>
    <activityDetails>
      <ownerID>5015012</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a32</objectID>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <publishDate>2010-03-08T17:19:57</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>5015012</id>
          <nameHint>Michael Affronti</nameHint>
          <profileUrl>http://www.contoso.com/</profileUrl>
        </templateVariable>
        <templateVariable type="listVariable">
          <name>ProfilePhoto</name>
          <listItems>
            <simpleTemplateVariable type="pictureVariable">
              <name>Photo</name>
              <value>http://office.microsoft.com/global/images/default.aspx?assetid=ZA103895491033</value>
              <altText>Michael Affronti</altText>
              <href>http://office.microsoft.com/global/images/default.aspx?assetid=ZA103895491033</href>
            </simpleTemplateVariable>
          </listItems>
        </templateVariable>
      </templateVariables>
    </activityDetails>
    <activityDetails>
      <ownerID>5015012</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a38</objectID>
      <applicationID>2</applicationID>
      <templateID>2</templateID>
      <publishDate>2010-03-08T18:30:00</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>5015012</id>
          <nameHint>Michael Affronti</nameHint>
          <profileUrl>http://www.contoso.com</profileUrl>
        </templateVariable>
        <templateVariable type="textVariable">
          <name>statusText</name>
          <value>is hiking on Mount Rainier this weekend!</value>
        </templateVariable>
      </templateVariables>
    </activityDetails>
    <activityDetails>
      <ownerID>5015012</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a39</objectID>
      <applicationID>2</applicationID>
      <templateID>3</templateID>
      <publishDate>2010-03-04T15:00:00</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>5015012</id>
          <nameHint>Michael Affronti</nameHint>
          <profileUrl>http://www.contoso.com/</profileUrl>
        </templateVariable>
        <templateVariable type="linkVariable">
          <name>blogPost</name>
          <text>Connect your Inbox to Facebook and Windows Live with the Outlook Social Connector</text>
          <value>http://blogs.office.com/b/office_blog/archive/2010/07/13/connect-to-facebook-and-windows-live-with-the-outlook-social-connector.aspx</value>
        </templateVariable>
      </templateVariables>
    </activityDetails>
  </activities>
  <templates>
    <activityTemplateContainer>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <activityTemplate>
        <type>Photo</type>
        <title>{publisher:Publisher} has a new profile photo: </title>
        <data>{list:ProfilePhoto({picture:Photo})}</data>
        <icon>http://www.microsoft.com/about/images/rss_button.gif</icon>
      </activityTemplate>
    </activityTemplateContainer>
    <activityTemplateContainer>
      <applicationID>2</applicationID>
      <templateID>2</templateID>
      <activityTemplate>
        <type>Status Update</type>
        <title>{publisher:Publisher}: {text:statusText}</title>
                <data></data>
        <icon>http://www.microsoft.com/about/images/rss_button.gif</icon>
      </activityTemplate>
    </activityTemplateContainer>
    <activityTemplateContainer>
      <applicationID>2</applicationID>
      <templateID>3</templateID>
      <activityTemplate>
        <type>Other</type>
        <title>{publisher:Publisher} wrote a new blog post {link:blogPost}</title>
                <data></data>
        <icon>http://www.microsoft.com/about/images/rss_button.gif</icon>
      </activityTemplate>
    </activityTemplateContainer>
  </templates>
</activityFeed>

See also

Concepts

OSC Provider XML Examples
XML for Activities
Capabilities XML Example
Friends XML Example
Outlook Social Connector Provider XML Schema


XML for Capabilities

 Copy code hover
[image]

XML for Capabilities
See also Send feedback

Published: July 16, 2012

The capabilities element in the (OSC) provider XML schema allows an OSC provider to specify its functionality. Such functionality includes the following:

  • Whether the provider supports getting, caching, or dynamically looking up friends and activities from the social network.

  • How the OSC should display certain logon user interfaces.

  • Whether the OSC should use forms-based authentication or automatically configure the social network and logs on the user on the social network.

The XML schema for capabilities is critical because it identifies to the OSC the functionality supported by the provider. An OSC provider must implement the ISocialProvider::GetCapabilities method that returns a result string. The OSC calls ISocialProvider::GetCapabilities to obtain information about the capabilities of the OSC provider in the result string, which complies with the XML schema definition for the capabilities element. This information enables subsequent calls from the OSC to the OSC provider to operate correctly.

To specify capabilities of an OSC provider as an output parameter of the ISocialProvider::GetCapabilities method, you must conform to the OSC provider extensibility XML schema. The following figure shows the capabilities XML structure.

Figure 1. <capabilities> XML structure

capabilities XML structure

For detailed descriptions of child elements of the capabilities element, see Capabilities XML Elements. For an example of capabilities XML, see Capabilities XML Example. For a complete definition of the OSC provider XML schema, including which elements are required or optional, see Outlook Social Connector Provider XML Schema.

See also

Concepts

Capabilities XML Example
Synchronizing Friends and Activities
XML for Friends
XML for Activities

Other resources

Developing a Provider with the OSC XML Schema


Capabilities XML Elements

 Copy code hover
[image]

Capabilities XML Elements
See also Send feedback

Published: July 16, 2012

The tables in this topic describe child elements of the capabilities XML and are grouped by the areas they support. The default value of each capabilities element is false. If the element is not specified in the capabilities XML returned by the ISocialProvider::GetCapabilities method, the value of the element is equal to false.

For an overview description of capabilities XML, see XML for Capabilities. For an example of capabilities XML, see Capabilities XML Example. For a complete definition of the Microsoft Outlook Social Connector (OSC) provider XML schema, including which elements are required or optional, see Outlook Social Connector Provider XML Schema.

Capabilities for Supporting Friends

The following table shows elements that apply to any form of synchronization of friends or non-friends.

Element | Description
doNotFollowPerson | Indicates whether the provider supports the ISocialSession::UnFollowPerson method call. followPerson and doNotFollowPerson are independent features of an OSC provider. An OSC provider can indicate the capability of being able to add a person as a friend (setting followPerson to true) or being able to remove a person as a friend on a social network account (setting doNotFollowPerson to true). In general, being able to follow does not imply being able to stop following. followPerson is a capability, and it is not to be misinterpreted as an action to follow a specific person or every person on the social network account. followPerson being true does not imply doNotFollowPerson is false.
followPerson | Indicates whether the provider supports the ISocialSession::FollowPerson method call. The OSC checks followPerson if cacheFriends is true (cached synchronization of friends), dynamicContactsLookup is true (on-demand synchronization of friends and non-friends), or both cacheFriends and dynamicContactsLookup are true (hybrid synchronization of friends and non-friends). If the provider sets followPerson as true, the OSC displays a network badge in the People Pane for people that the user is following, and enables the on <NetworkName> command on the Add (+) menu in the People Pane. If the provider sets followPerson as false, the network badge is not displayed, and the on <NetworkName> command is hidden.
getFriends | Indicates whether the provider supports the ISocialPerson::GetFriendsAndColleagues or ISocialSession2::GetPeopleDetails method call. If the provider sets getFriends as true, the OSC uses the value of cacheFriends or dynamicContactsLookup to determine whether the social network allows storing friends as Outlook contact items or in memory. If the provider sets getFriends as false, the social network does not support friends and the ISocialPerson::GetFriendsAndColleagues and ISocialSession2::GetPeopleDetails methods, and the OSC ignores the values of cacheFriends and dynamicContactsLookup.

The following elements apply only to cached synchronization of friends or hybrid synchronization of friends and non-friends. For more information about synchronizing friends, see Synchronizing Friends and Activities.

Element

Description

cacheFriends

Indicates whether the OSC provider allows storing friends as Outlook contact items. The OSC checks cacheFriends only if getFriends is true. If the provider sets cacheFriends as true, the OSC synchronizes friends by caching, and creates a network-specific contacts folder in the user's default store for friend contacts. The name of the network-specific contacts folder is the value of the ISocialProvider::SocialNetworkName property. If the provider sets cacheFriends as false, the OSC does not create a network-specific contacts folder for friend contacts to store friends.

contactSyncRestartInterval

Determines the retry interval, in minutes, between attempts to synchronize friends' information from the social network, if a synchronization error occurs. The OSC uses this element only if the OSC provider supports cached synchronization or hybrid synchronization of friends to a social network-specific contacts folder (cacheFriends is true).

The default retry interval is 30 minutes, unless the default is overridden by the ContactSyncRestartInterval key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector. If the provider sets contactSyncRestartInterval, the provider value will override the default retry interval of 30 minutes or the registry key value.

For more information about synchronizing friends and non-friends information on demand, see Synchronizing Friends and Activities.

The following elements apply to only on-demand synchronization or hybrid synchronization of friends and non-friends.

Element

Description

dynamicContactsLookup

Indicates whether the OSC provider supports the ISocialSession2::GetPeopleDetails call for on-demand synchronization of friends and non-friends.

The OSC checks dynamicContactsLookup only if getFriends is true.The default setting for dynamicContactsLookup is false.

If the OSC provider specifies dynamicContactsLookup as true and getFriends as true, the OSC calls ISocialSession2::GetPeopleDetails every time the People Pane is refreshed. The People Pane is refreshed when the user selects another user in the People Pane or another item in the Outlook explorer window, or opens an Outlook inspector window. Dynamic contacts lookup ensures that the user always sees the latest user pictures and profile information in the People Pane, but increases the number of calls from the provider to the social network.

If the provider sets dynamicContactsLookup as false, the OSC does not call ISocialSession2::GetPeopleDetails to refresh the People Pane.

showOnDemandContactsWhenMinimized

Indicates if the OSC should carry out on-demand synchronization for friends and non-friends when the People Pane is minimized.

Capabilities for Supporting Activities

The following element applies to any form of synchronization of activities supported by the OSC provider.

Element | Description
getActivities | Indicates whether the provider supports the ISocialSession2::GetActivitiesEx or ISocialPerson::GetActivities method calls. If the provider sets getActivities as true, the OSC uses the value of cacheActivities or dynamicActivitiesLookupEx to determine whether the social network site allows storing activities as Outlook RSS items or as in-memory activities. If the provider sets getActivities as false, the social network does not support activities and the ISocialSession2::GetActivitiesEx and ISocialPerson::GetActivities methods, and the OSC ignores the values of cacheActivities and dynamicActivitiesLookupEx.

The following element applies to only cached synchronization or hybrid synchronization of activities.

Element

Description

cacheActivities

Starting in Outlook Social Connector 2013, the OSC ignores this element since providers can no longer synchronize activities by caching them in a hidden folder in the user's store.

If the provider supports activities, the provider must support synchronize activities on-demand. The provider sets cacheActivities as false and sets dynamicActivitesLookupEx as true. The OSC synchronizes activities on-demand, and caches activities in memory. The activities memory cache is refreshed on a 30-minute interval.

The following elements apply to only on-demand synchronization or hybrid synchronization of activities.

Element

Description

dynamicActivitiesLookup

Deprecated in OSC 1.1.

Starting in OSC 1.1, the OSC no longer calls ISocialSession::GetActivities and ignores the value of dynamicActivitiesLookup. To support on-demand activities lookup, set cacheActivities as false and getActivities and dynamicActivitiesLookupEx as true, and the OSC will call ISocialSession2::GetActivitiesEx.

dynamicActivitiesLookupEx

Indicates whether the OSC provider supports the ISocialSession2::GetActivitiesEx call for on-demand synchronization of activities.

If the OSC provider supports on-demand activities synchronization, it sets getActivities and dynamicActivitiesLookupEx as true, and cacheActivities as false. The OSC calls ISocialSession2::GetActivitiesEx every time the People Pane is refreshed. The People Pane is refreshed when the user changes the selected item in the Outlook explorer window or opens an Outlook inspector window. Dynamic activities lookup ensures that the user will always see the latest activities in the People Pane, but will increase the number of calls from the provider to the social network.

If the provider sets dynamicActivitiesLookupEx as false, the OSC does not call ISocialSession2::GetActivitiesEx for people displayed in the People Pane.

showOnDemandActivitiesWhenMinimized

Indicates whether the OSC should carry out on-demand synchronization for activities when the People Pane is minimized.

Common Capabilities for Supporting On-Demand or Hybrid Synchronization of Friends, Non-Friends, and Activities

Element

Description

hashFunction

Specifies the hash function that the OSC provider supports. To protect personally identifiable information of users who are not on the provider's social network or line-of-business application, the OSC passes hashed email addresses to ISocialSession2::GetPeopleDetails and ISocialSession2::GetActivitiesEx.

If dynamicContactsLookup is set to true or dynamicActivitiesLookupEx is set to true, the provider must set hashFunction to one of the allowed values: SHA1, MD5, or CRC32MD5. If hashFunction is missing or specifies an incorrect value, the OSC returns an error.

SHA1 is Internet Engineering Task Force (IETF) US Secure Hash Algorithm 1 defined by [RFC3174]. For example, the SHA1 hashed value of email address melissa@contoso.com is bb81577b567262a21a4df5f6e335c1250acd7b50.

MD5 is Internet Engineering Task Force (IETF) MD5 Message-Digest Algorithm defined by [RFC1321]. For example, the MD5 hashed value of e-mail address melissa@contoso.com is c8c39e61ca1662477b39b83d7b0a0615.

CRC32MD5 is a combination of CRC32 and MD5 defined as follows:

  1. Normalize the email address by removing leading and trailing whitespace and converting all characters to lowercase.

  2. Compute the CRC32 value for the normalized email address and use the decimal integer representation of this value. If your implementation returns signed integers, you must convert the signed integer to an unsigned integer.

  3. Compute the MD5 value for the normalized email address and use the hex representation of this value (using lowercase for A through F).

  4. Combine these two values with an underscore.

For example, the CRC32MD5 hashed value of email address melissa@contoso.com is 2149665315_c8c39e61ca1662477b39b83d7b0a0615.

Capabilities for Supporting Authentication and Account Configuration

Element

Description

allowChangesToAutoConfigure

Indicates whether the social network allows the user to change auto-configuration settings, such as providing a different URL to log on.

createAccountUrl

If the provider sets hideHyperlinks as false, when the user clicks Click here to create an account in the Account configuration dialog box, the URL specified by createAccountUrl opens in the default browser.

displayUrl

Indicates whether the OSC should display the URL Address text box for the social network in the account configuration dialog box.

forgotPasswordUrl

If the provider sets hideHyperlinks as false, when the user clicks Forgot your password? in the Account configuration dialog box, the URL specified by forgotPasswordUrl opens in the default browser.

hideHyperlinks

Indicates whether the OSC should hide the Click here to create an account and Forgot your password? hyperlinks in the account configuration dialog box.

OSC 1.0 ignores this setting, and the hyperlinks are always hidden. OSC 1.1 observes the value of this setting.

hideRememberMyPassword

Indicates whether the OSC should hide the Remember my password check box in the account configuration dialog box.

If the provider sets hideRememberMyPassword as true, the OSC will act as if the Remember my password box is unchecked and will not save the password.

If the provider sets hideRememberMyPassword as false, the OSC will display the Remember my password check box in the account configuration dialog box.

supportsAutoConfigure

Indicates whether the OSC should call the GetAutoConfiguredSession function on the ISocialProvider interface to attempt automatic configuration and log on to the social network for the user.

useLogonCached

Indicates whether the OSC provider supports the ISocialSession2::LogonCached call to log on with cached credentials.

If the provider sets useLogonCached as true, the OSC ignores the setting for useLogonWebAuth and the OSC calls ISocialSession2::LogonCached for authentication.

If the provider sets dynamicActivitiesLookupEx as false, the OSC does not call ISocialSession2::LogonCached for authentication.

useLogonWebAuth

Indicates whether the OSC should use forms-based authentication and the ISocialSession::LogonWeb method. If the provider sets useLogonWebAuth as false, the OSC uses basic authentication and calls the ISocialSession::Logon method. If the provider sets useLogonWebAuth as true, the OSC uses forms-based authentication and calls ISocialSession::LogonWeb.

Depending on the capabilities XML returned by the provider in the ISocialProvider::GetCapabilities method, the account configuration dialog box changes. For example, Figure 1 shows the account configuration dialog box for a TestProvider example.

Figure 1. TestProvider example in the account configuration dialog box

TestProvider example configuration information

See also

Concepts

XML for Capabilities


XML for Friends

 Copy code hover
[image]

XML for Friends
See also Send feedback

Published: July 16, 2012

The friends element in the Microsoft Outlook Social Connector (OSC) provider XML schema allows an OSC provider to specify information for a list of persons associated with an Outlook user in the social network. If the OSC provider supports cached synchronization, this list of person will contain only friends of the Outlook user on the social network. If the OSC supports on-demand or hybrid synchronization, this list may contain both friends and non-friends of the Outlook user. Each person in the list is represented as a person element in the XML schema, which supports details such as first name, last name, and email addresses. OSC providers use the friends and person elements regardless of how they want the OSC to synchronize friend information from the social network. Note that the child elements of person are similar to some of the properties of an Outlook contact, which facilitates storing friends in an Outlook contacts folder specific to the social network, if the social network supports cached or hybrid synchronization of friends to an Outlook contacts folder.

The following example scenarios show the OSC provider extensibility API calls that an OSC provider implements and the OSC makes to obtain friend information. Information is expressed in XML strings that conform to the OSC provider XML schema.

For an example of friends XML, see Friends XML Example. For more information about synchronizing friends' information, see Synchronizing Friends and Activities.

  • Scenario 1—OSC gets a list of friends, and an ISocialPerson object and a picture for each friend:

    1. An OSC provider that supports showing friends from the social network site and allowing the OSC to cache friend information indicates that to the OSC by using the getFriends and cacheFriends elements, which are child elements of the capabilities element.

    2. The OSC provider also implements the ISocialProvider::GetCapabilities, ISocialSession::GetPerson, ISocialPerson::GetFriendsAndColleagues, and ISocialPerson::GetPicture methods.

    3. The OSC calls ISocialProvider::GetCapabilities to check the value of the following elements: getFriends to verify that the OSC provider supports showing friends from the social network, and cacheFriends to verify that the provider supports caching friends.

    4. The OSC calls ISocialSession::GetPerson to get an ISocialPerson object for the Outlook user.

    5. The OSC calls ISocialPerson::GetFriendsAndColleagues to get the Outlook user's friends list returned in the personCollection parameter string. The personCollection string complies with the XML schema definition for the friends element in the XML schema.

    6. For each friend in the personCollection XML string, the OSC obtains value of the userID element to call ISocialSession::GetPerson to get an ISocialPerson object for that friend.

    7. For each friend in the personCollection XML string, the OSC calls ISocialPerson::GetPicture to get a picture resource for that friend.

    The OSC can make further calls on the ISocialPerson object to obtain activities and details (for example, email addresses) for that friend.

  • Scenario 2—OSC synchronizes friends dynamically:

    1. An OSC provider that supports on-demand synchronization of friends and non-friends indicates that to the OSC by using the getFriends and dynamicContactsLookup elements. The OSC provider also sets the hashFunction element. All three elements are child elements of capabilities.

    2. The OSC provider also implements the ISocialSession2::GetPeopleDetails method.

    3. The OSC calls ISocialProvider::GetCapabilities to check the values of getFriends and dynamicContactsLookup to verify that the OSC provider supports friends and on-demand synchronization of friends and non-friends. The OSC also makes note of the value of hashFunction supported by the OSC provider.

    4. For each user displayed in the People Pane, the OSC collects the user's email address and encrypts it by using the hash function specified in hashFunction. This forms an XML string that conforms to the XML schema definition for the hashedAddresses element.

    5. The OSC calls ISocialSession2::GetPeopleDetails, providing this XML string of hashed addresses as the personAddresses parameter, to dynamically obtain updated details for persons in the personsCollection parameter. The personsCollection parameter string complies with the XML schema definition for the friends element in the XML schema.

The following are the two top-level elements in the friends schema.

Element | Description
friends | Represents the root element of a list of person elements. The ISocialPerson::GetFriendsAndColleagues, ISocialSession::FindPerson, and ISocialSession2::GetPeopleDetails return XML strings that conform to the schema definition of the friends element.
person | Represents one person in a list of person elements. The ISocialPerson::GetDetails method returns an XML string that conforms to the schema definition of the person element.

The following table describes each child element of the person element in the OSC provider XML schema.

For a complete definition of the OSC provider XML schema, including which elements are required or optional, see Outlook Social Connector Provider XML Schema.

Element | Description
address | Physical street address of the person.
anniversary | Anniversary date for an event for the person.
askmeabout | Topics of interest or expertise of the person.
birthday | Date of birth for the person.
businessAddress | Physical street address of the person's workplace.
businessCity | City for the person's workplace.
businessCountryOrRegion | Country or region of the person's workplace.
businessState | State or province of the person's workplace.
businessZip | Zip or postal code of the person's workplace.
cell | Mobile telephone number for the person.
city | City of the physical address for the person.
company | Name of the company associated with the person.
countryOrRegion | Country or region of the physical address of the person.
creationTime | Creation time of the person's profile on the social network.
emailAddress | Primary email address of the person.
emailAddress2 | Secondary email address of the person.
emailAddress3 | Tertiary email address of the person.
expirationTime | Time that the person's profile data expires on the social network.
fileAs | String by which the person is to be filed as a contact in an Outlook contacts file.
firstName | First name or given name of the person.
friendStatus | Friend status of this person with the logged on user on the social network. Must be one of the following values: friend, nonfriend, pending, pendingin, pendingout.
fullName | Full name of the person.
gender | Gender of the person. Must be one of the following values: male, female, unspecified.
homePhone | Home telephone number for the person.
index | Location of the person's hashed address in the personsAddresses string parameter passed to a call to the ISocialSession2::GetPeopleDetails method. It also indicates the person's person XML in the personsCollection string returned by GetPeopleDetails.
industries | Industries that the person is engaged in.
interests | Interests or hobbies of the person.
lastModificationTime | Time that the person's profile was last modified on the social network.
lastName | Last name or surname of the person.
location | The location of the person.
nickname | A shorter name or invented name of the person.
otherAddress | Alternative street address of the person.
otherCity | City of the person's alternative address.
otherCountryOrRegion | Country or region of the person's alternative address.
otherState | State or province of the person's alternative address.
otherZip | Zip or postal code of the person's alternative address.
phone | Primary contact telephone number for the person.
pictureUrl | URL for a profile picture of the person.
relationship | Relationship of this person with the logged on user.
schools | The schools that the person goes or went to.
skills | Personal skills of the person.
state | State or province of the physical address of the person.
title | Designation added to the person's name.
userID | ID to identify the person on the social network.
webProfilePage | Webpage address that contains a profile of the person.
website | The person's web site.
workPhone | Business telephone number for the person.
zip | ZIP code or postal code of the physical address of the person.

See also

Concepts

Friends XML Example
Synchronizing Friends and Activities
XML for Capabilities
XML for Activities

Other resources

Developing a Provider with the OSC XML Schema


XML for Activities

 Copy code hover
[image]

XML for Activities
See also Send feedback

Published: July 16, 2012

This topic contains an example scenario that shows the Outlook Social Connector (OSC) provider extensibility API calls that an OSC provider implements and the OSC makes to obtain activities information. Information is expressed in XML strings that conform to the OSC provider XML schema.

The OSC provider XML schema allows an OSC provider to define activities. Activity information can include the social network where the activity feed items originated, details of each activity feed item (such as owner, type, and publish date of the activity), and the template to display the activity. To support showing activities on the People Pane or Contact Card, a social network's OSC provider must implement and return the correct activities XML. For an example of activity feed XML, see Activity Feed XML Example. For more information about synchronizing friends' activities, see Synchronizing Friends and Activities. For a complete definition of the OSC provider XML schema, including which elements are required or optional, see Outlook Social Connector Provider XML Schema.

In the following scenario, the OSC dynamically synchronizes activities for a person selected in the People Pane, and gets details about that person:

  1. An OSC provider that supports on-demand synchronization of activities indicates that to the OSC by using the getActivities and dynamicActivitiesLookupEx elements. The OSC provider also sets the hashFunction element. All three elements are child elements of capabilities.

  2. The OSC provider implements the ISocialProvider::GetCapabilities and ISocialSession2::GetActivitiesEx methods.

  3. The OSC calls ISocialProvider::GetCapabilities to check the value of getActivities and dynamicActivitiesLookupEx to verify that the OSC provider supports on-demand synchronization of activities. The OSC also notes the value of the hashFunction element supported by the OSC provider.

  4. The OSC refreshes the People Pane or Contact Card to let the user see the latest activities of the selected person. The OSC encrypts the person's SMTP address by using the hash function specified in the hashFunction element, forming an XML string that conforms to the XML schema definition for the hashedAddresses element.

  5. The OSC calls ISocialSession2::GetActivitiesEx, providing this XML string of the hashed address as the hashedAddresses parameter, to get a current collection of activities for that person in the activities parameter. The activities parameter string complies with the XML schema definition of the activityFeed element.

  6. Based on the XML schema definition for activityFeed, the OSC further parses the activities string to find out the type, publish date, and other information about each activity, and how to display the activity.

  7. To get details about the selected person, the OSC calls ISocialSession2::GetPeopleDetails, providing the same XML string of hashed addresses as the argument for the personsAddresses parameter. The details about the person are returned in the personsCollection parameter. These details can include firstName, lastName, and emailAddress. The personsCollection parameter conforms to the XML schema definition for the person element.

You can find more information about specifying XML for activities in the following topics of this section:

  • Overview of XML for an Activity Feed Item

  • activityDetails Element

  • activityTemplateContainer Element

  • Template Variables

  • Guidelines for Properly Displaying Activities

See also

Concepts

Activity Feed XML Example
Synchronizing Friends and Activities
XML for Capabilities
XML for Friends

Other resources

Developing a Provider with the OSC XML Schema


Overview of XML for an Activity Feed Item

 Copy code hover
[image]

Overview of XML for an Activity Feed Item
See also Send feedback

Published: July 16, 2012

An activity feed consists of one or more activities occurring on a social network. Each activity feed is represented by an activityFeed element, and is characterized by these three pieces of information:

  • network—Name of the social network from which the activities originated.

  • activities—Container for activities happening on the logged on user's account on that social network.

  • templates—Container for templates that are used to display the corresponding activity item in activities.

To create an activity feed item, you must conform to the Outlook Social Connector (OSC) provider extensibility XML schema. Figure 1 shows the activity feed XML structure.

Figure 1. Activity feed XML structure

Activity XML structure

For each activity feed item, the two most important parts of this schema are the activityDetails and activityTemplateContainer elements:

  • The activityDetails element stores specific information for each activity feed item, such as the activity owner's name or the URL for the pictures uploaded.

  • The activityTemplateContainer element stores the format or layout for each activity feed item. It consists of templates, represented by individual activityTemplate elements, that can be reused for multiple feed items.

For an individual activity feed item, the activityTemplate element specifies the following four pieces of information:

  • icon—Specifies the URL for the icon to display the activity feed item.

  • title—Describes the activity feed item.

  • type—Specifies the type of activity, such as a status, photo, or document update.

  • data—Specifies any extra information displayed with activity feed item.

Tip Tip

The icon displayed in the activity feed is always the same as the provider icon returned by the ISocialProvider::SocialNetworkIcon property.

See the following topics for more information about the activityDetails element, the activityTemplateContainer element, template tokens, and template variables:

  • activityDetails Element

  • activityTemplateContainer Element

  • Template Variables

  • Guidelines for Properly Displaying Activities

For an example of activity feed XML, see Activity Feed XML Example.

See also

Concepts

XML for Activities
Outlook Social Connector Provider XML Schema

Other resources

Developing a Provider with the OSC XML Schema


activityDetails Element

 Copy code hover
[image]

activityDetails Element
See also Send feedback

Published: July 16, 2012

The activityDetails element stores the raw data for a single activity feed item. Each activity feed item must have its own activityDetails element. Data in the activityDetails element is referenced in activity templates by using name elements. Every piece of data in the activityDetails element must have a name element.

The following table describes the six elements that the activityDetails element requires.

Element | Description
ownerID | The ID of the user on the social network who generated this activity feed item.
objectID | A unique string for the activity feed item to detect duplicate feed items.
applicationId | One of two unique IDs that are used to match the activity feed item with its template. If you have multiple applications or other groupings, this can be used as a first-tier template organizer.
templateId | The second unique ID that is used to match the activity feed item with its template. This can be used as a second-tier template organizer.
publishDate | The date and time that the activity feed item was published.
templateVariables | The data to be used in the tokens for the activity feed item template.

For an example of activity feed XML, see Activity Feed XML Example

See also

Concepts

Overview of XML for an Activity Feed Item
activityTemplateContainer Element
Template Variables
Guidelines for Properly Displaying Activities
XML for Activities
Outlook Social Connector Provider XML Schema

Other resources

Developing a Provider with the OSC XML Schema


activityTemplateContainer Element

 Copy code hover
[image]

activityTemplateContainer Element
See also Send feedback

Published: July 16, 2012

An activityTemplateContainer element is a template that allows you to format your activity feed items and reuse XML that specifies a layout. Use IDs (applicationID and templateID) to match a feed item (activityDetails) to a template (activityTemplateContainer). Store the layout data as part of the activityTemplate element. To reference data that is pulled from the individual activity feed item, use template variables as placeholders for information such as people, links, and text.

The following table describes the three elements that the activityTemplateContainer element requires.

Element | Description
applicationID | One of two unique IDs that are used to match the feed item with its template. If you have multiple applications or other groupings, this can be used as a first-tier template organizer.
templateID | The second unique ID that is used to match the feed item with its template. This can be used as a second-tier template organizer.
activityTemplate | The layout of the template (icon, title, and data elements), and the type of activity (type element).

The following table describes the child elements of activityTemplate, which describe the layout and the type of a template.

Element | Description
icon | A link token, which references the URL for the icon for that feed item.
title | The required information for the feed item.
type | The type of activity, such as an update of status, photo, or document.
data | Any additional information for the feed item, such as pictures, text, or links.

For an example of activity feed XML, see Activity Feed XML Example

See also

Concepts

Overview of XML for an Activity Feed Item
activityDetails Element
Template Variables
Guidelines for Properly Displaying Activities
XML for Activities
Outlook Social Connector Provider XML Schema

Other resources

Developing a Provider with the OSC XML Schema


Template Variables

 Copy code hover
[image]

Template Variables
See also Send feedback

Published: July 16, 2012

Instances of template variables (represented by a templateVariable element) specify the data of an activity feed item in an activity template.

For an example of activity feed XML, see Activity Feed XML Example.

Types of Template Variables

The following table shows the types of supported template variables, each represented by the corresponding XML enumeration value.

Type of template variable | Description
entityVariable | A person, group, or thing.
linkVariable | A link.
listVariable | A group of objects.
pictureVariable | A picture.
publisherVariable | The publisher of the activity feed item.
textVariable | A block of text.

Each type of template variable has required elements to specify the data about that variable. Template variables are specified as follows:

<templateVariable type="variable type">

List Template Variable

You can specify template variables that are contained within a list (delimited by the listVariable and listItems elements) as follows:

<simpleTemplateVariable type="variable type of text, link, or picture">

A template variable of the listVariable type is a container for objects. It can contain comma-delimited items (of the linkVariable or textVariable type) or pictures (of the pictureVariable type). Lists can contain up to five link items, five text items, or five pictures.

The Outlook Social Connector (OSC) localizes link or text list items according to the Windows system locale.

To correctly parse and display pictures in an activity feed item, you must include pictures in a list. All pictures are resized to be 52 pixels high. The width of the picture is not resized.

Template Variable Elements

This section covers the required and optional elements supported for each type of template variable.

entityVariable

Element | Description
name | The name of the variable. Required.
id | The unique ID of the user. Required.
nameHint | The name to be displayed in the feed item. Optional.
profileUrl | The URL of the person's profile that will be used as the hyperlink for the person's name in the feed item, if the person's name is present. Optional.
emailAddress | The email address that is used to update this person's contact information in Outlook. Optional.

linkVariable

Element | Description
name | The name of the variable. Required.
value | The URL for this link. Required.
text | The link text to display instead of the URL itself. Optional.

listVariable

Element | Description
name | The name of the variable. Required.
listItems | A container for items in the list. Required.

pictureVariable

Element | Description
name | The name of the variable. Required.
value | The URL for the picture. Required.
altText | The alternate text to display for accessibility and when the user moves the mouse pointer over the picture. Optional.
href | The hyperlink to use when the user clicks the picture, if the desired target is not the picture URL specified by the value element. Optional.

publisherVariable

Element | Description
name | The name of the variable. Required.
id | The unique ID of the user. Required.
nameHint | The name to be displayed in the feed item. Optional.
profileUrl | The URL of the person's profile that will be used as the hyperlink for the person's name in the feed item, if the person's name is present. Optional.
emailAddress | The email address that is used to update this person's contact information in Outlook. Optional.

textVariable

Element | Description
name | The name of the variable. Required.
value | The text to display. Optional.

See also

Concepts

Overview of XML for an Activity Feed Item
activityDetails Element
activityTemplateContainer Element
Guidelines for Properly Displaying Activities
XML for Activities
Outlook Social Connector Provider XML Schema

Other resources

Developing a Provider with the OSC XML Schema


Guidelines for Properly Displaying Activities

 Copy code hover
[image]

Guidelines for Properly Displaying Activities
See also Send feedback

Published: July 16, 2012

Outlook Social Connector (OSC) providers can set the getActivities and dynamicActivitiesLookupEx elements to have the OSC store activity items in memory. This topic describes the OSC provider extensibility APIs that the OSC calls to get or refresh activities and activity owner details, if the OSC provider supports synchronizing activity feeds from the social network. The topic also lists a few child elements of the activityFeed element that the OSC provider should set for the OSC to display activities properly in the Office Contact Card or Outlook People Pane.

  • The OSC calls the ISocialSession2::GetActivitiesEx method to get and store activities in the News Feed folder for the logged-on user. The OSC provider must implement GetActivitiesEx to return an activities XML string that complies with the OSC provider XML schema definition of the activityFeed element.

  • The OSC provider must set the ownerID element, which is a child element of the activityDetails element. ownerID is an opaque string that identifies the owner of the activity on the social network.

  • The OSC provider should set the nameHint and emailAddress elements in the publisherVariable node of the templateVariables element.

    Note that per the OSC provider XML schema, the nameHint element is an optional element. The OSC uses it to match the display name of the user selected in the Contact Card or People Pane. Similarly, the emailAddress element is an optional element in the XML schema. The OSC uses it to match the SMTP address of the user selected in the Contact Card or People Pane.

    If only the ownerID element is specified, but one or both of nameHint and emailAddress are not specified, the OSC calls the ISocialSession2::GetPeopleDetails method and then the ISocialPerson::GetDetails method to get more information about the person identified by the ownerID. When the OSC calls ISocialPerson::GetDetails, the provider must return person XML that specifies the fullName and emailAddress elements.

See also

Concepts

XML for Activities
XML for Friends
XML for Capabilities


Debugging a Provider

 Copy code hover
[image]

Debugging a Provider
See also Send feedback

Published: July 16, 2012

There are several ways you can debug an Outlook Social Connector (OSC) provider:

  • By using debug commands in the ribbon component of the Office Fluent user interface in Outlook or the supporting Office client application to cause the OSC to take various actions.

  • By using Fiddler to trace API calls and XML sent between a social network and its OSC provider

Debug Buttons

The OSC provider extensibility provides the capability of debugging an OSC provider. To debug a provider, create a DebugProviders value of type DWORD in the Windows registry under the SocialConnector key (as shown in the following line), and set the DebugProviders value to 1.

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector

By default, provider debugging is off. If the DebugProviders value is not present, or it is present and set to a value of 0, provider debugging is turned off.

If provider debugging is turned on, the OSC displays an alert dialog box with verbose error information when an error occurs, and validates any OSC provider XML against the OSC provider XML schema. Based on the namespace specified for an XML string, an OSC provider developed by using OSC 1.0 is validated against the OSC 1.0 schema file, OutlookSocialProvider.xsd. An OSC provider developed by using OSC 1.1 or later is validated against the schema file, OutlookSocialProvider_1.1.xsd. When you use the DebugProviders value, the debug alert appears for all loaded providers instead of a specific provider.

To display debug buttons that can help you debug a provider, create a ShowDebugButtons value of type DWORD in the Windows registry under the SocialConnector key, and set the ShowDebugButtons value to 1. To hide the debug command bar buttons, set the ShowDebugButtons value to 0.

For Outlook 2010 and client applications since Office 2013, the debug buttons appear on the Add-ins tab of the explorer ribbon. For Outlook 2007 and Outlook 2003, the debug buttons appear on the standard command bar of the Outlook explorer window.

The following table describes the debug buttons.

Debug button | Function
Sync Contacts | Causes the OSC to ask the OSC provider for cached contacts only.
GAL Sync | Causes the OSC to populate data from the Exchange Global Address List to Outlook contacts.
Invalidate Category Cache | Causes the OSC to reload the category list for each store when the activity feed is refreshed.

Fiddler

Fiddler is an over-the-wire debugging tool to check the API calls sent from your provider to the social network, and XML sent by the social network to your provider. Fiddler is available for download at Fiddler Web Debugging Proxy.

See also

Concepts

Quick Steps for Learning to Develop a Provider
Synchronizing Friends and Activities
Best Practices for Developing a Provider

Other resources

OSC Typical Calling Sequences
Developing a Provider with the OSC XML Schema
Getting Ready to Release an OSC Provider


Deploying a Provider

 Copy code hover
[image]

Deploying a Provider
See also Send feedback

Published: July 16, 2012

The recommended method of deploying a Outlook Social Connector (OSC) provider is to use a Windows Installer (.msi) package. After downloading the installation package to a local hard disk, the Office end user installs the OSC provider. Once provider installation is complete, the user can connect to the OSC provider and provide logon credentials to the social network account. If the user decides to uninstall the OSC provider, the user can use Programs and Features in Control Panel to uninstall.

In this section

Registering a Provider

Describes registration requirements for an OSC provider.

Installation Checklist

Provides a checklist to ensure that an OSC provider installs successfully.

Reference

Outlook Social Connector Provider Reference

Related sections

Getting Started with Developing an Outlook Social Connector Provider

OSC Sample Templates

OSC Typical Calling Sequences

Developing a Provider with the OSC XML Schema

Debugging a Provider

Best Practices for Developing a Provider

See also

Other resources

How to manage the Outlook Social Connector by using Group Policy


Registering a Provider

 Copy code hover
[image]

Registering a Provider
See also Send feedback

Published: July 16, 2012

This topic describes the Windows registry locations that are used when you install an Outlook Social Connector (OSC) provider.

COM Registration

You must configure the OSC provider DLL to register using COM self-registration or regsvr32 during installation. COM registration of the provider DLL registers the OSC provider under the HKEY_CLASSES_ROOT registry hive.

An OSC provider developed in managed code has a COM-visible provider assembly. You should use a separate application domain for the provider component. Otherwise, the OSC provider uses the default shared application domain that is used by other components, and the provider may not operate as expected.

Registering Provider ProgID

Each OSC provider must register a programmatic identifier (ProgID). The provider installer can choose one of the following locations to add or remove the ProgID:

  • HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders—Your provider installer should use this location if the provider is installed for only the currently logged-on user.

  • HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders—Your provider installer should use this location if the provider is installed for all users on the computer.

The OSC looks for the provider ProgID in the above locations, unless the client computer has 32-bit Outlook running on a 64-bit Windows operating system. In such a case, your provider installer should choose one of the following locations in the HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE hive:

  • HKEY_CURRENT_USER\Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders

  • HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders

See also

Concepts

Installation Checklist
Quick Steps for Learning to Develop a Provider

Other resources

Deploying a Provider


Installation Checklist
See also Send feedback

Published: July 16, 2012

This topic describes prerequisites for successfully installing an Outlook Social Connector (OSC) provider, and the installation checks that your provider installer should complete to work correctly.

Installation Overview

Users should install OSC providers only if a supporting version of Outlook is present and the OSC is installed and enabled on the client computer. Supporting versions of Outlook are Office Outlook 2003, Office Outlook 2007, Outlook 2010 and Outlook 2013 (installed on the client computer or, in the case of Outlook 2010 and Outlook 2013, delivered by Click-to-Run on the client computer). To ensure a successful installation, your provider installer should do the following:

  • Verify whether a supported version of Outlook is present.

  • Verify whether the OSC is installed.

Note Note

Click-to-Run is a virtual environment in which Outlook 2010 (32-bit) or Outlook 2013 (32-bit) can run. For Outlook 2013, verify if the VirtualOutlook key exists in HKEY_LOCAL_MACHINE\Software\Microsoft\Office\15.0\Common\InstallRoot\Virtual\VirtualOutlook of the Windows registry. For more information about delivering Outlook as a Click-to-Run product on a client computer, see How to Verify if Outlook is Available on a Computer as a Click-to-Run Product.

The user, however, has to ensure that the OSC is enabled before installing the provider.

Third parties, including OSC providers, cannot redistribute the OSC. However, if the OSC is not installed, the provider installer can use appropriate g-links to install the OSC on the client computer. A g-link is a specially constructed URL on http://g.live.com that forwards a user to a corresponding webpage to download the OSC. An OSC g-link is formatted as http://g.live.com/0CRLCID/Glink, where LCID and Glink specify the locale, version, and bitness of Outlook on the client computer. Each g-link points to an executable and is specific to the specified LCID and Glink values.

For example, the g-link to install the latest version of the OSC for Outlook 2003 or Outlook 2007 for the LCID 1033 (US English) is as follows:

http://g.live.com/0CR1033/80

For details about Glink values for different versions and bitness of Outlook, and LCID values for supported locales, see #7 in the section Installation Checklist below.

Installation Checklist

The provider setup package should perform a series of installation checks, as shown in Figure 1, to ensure that the provider installs successfully.

Figure 1. Provider installation logic

The following procedure describes the installation checks outlined in Figure 1.

  1. As a prerequisite, detect whether Outlook is installed or present, and if installed or present, determine whether the version of Outlook supports the OSC. For more information about detecting the installed version of Outlook, see How to: Check the Version of Outlook.

    • If the installed version of Outlook is earlier than Outlook 2003, the provider installation procedure cannot complete. Inform the user to obtain a supported version of Outlook and the OSC before proceeding to install the OSC provider.

    • If Outlook is not installed, proceed to step 2.

    • If Outlook 2003 or Outlook 2007 is installed, proceed to step 3.

    • If Outlook 2010 or Outlook 2013 is installed, proceed to step 4.

  2. Proceed with this step if Outlook is not installed on the client computer:

    1. Check whether the OSC is installed as a default component of a Click-to-Run installation of Outlook 2010 or Outlook 2013. Examine the VirtualOutlook key in the following location in the Windows registry:

      • For Outlook 2010, HKEY_LOCAL_MACHINE\Software\Microsoft\Office\14.0\Common\InstallRoot\Virtual\VirtualOutlook

      • For Outlook Social Connector 2013, HKEY_LOCAL_MACHINE\Software\Microsoft\Office\15.0\Common\InstallRoot\Virtual\VirtualOutlook

      The VirtualOutlook key is a REG_SZ value that contains the locale tag, such as "en-us", of the installed product.

    2. If the VirtualOutlook key does not exist, Outlook is not present on the client computer, and the provider installation procedure cannot complete. Inform the user to obtain a supported version of Outlook and the OSC before proceeding to install the OSC provider.

    3. If the VirtualOutlook key does exist, Outlook was delivered by Click-to-Run on the client computer. Proceed to check the installed version of the OSC type library by examining the OSCVersion key in the following location in the Windows registry:

      HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\OSCVersion

      The value of OSCVersion is a string that specifies the type library version number of Socialprovider.dll (for example, "1.0", "1.1", or "15").

    4. If OSCVersion is "1.0", "1.1" or "15", an appropriate version of OSC is installed. Proceed to step 6 to find the current Outlook user interface locale to prepare for installing the latest version of the OSC.

    5. Otherwise, OSCVersion does not contain an expected value. Proceed to step 6 to find the current Outlook user interface locale to prepare for installing an appropriate version of the OSC.

  3. Proceed with this step if Outlook 2003 or Outlook 2007 is installed on the client computer:

    1. Verify whether the OSC is installed by writing an installer custom action to test for the existence of the following qualified component ID:

      {A3B82DA3-8AD9-4935-AEA8-54B754459483}

      The qualified component ID is a GUID that provides a method of single-level indirection, similar to a pointer. For more information about Windows Installer, see Roadmap to Windows Installer Documentation.

    2. If the specified qualified component exists, a version of the OSC is installed. Proceed to step 5 to find the current Outlook user interface locale to prepare for installing the latest version of the OSC.

    3. Otherwise, the OSC is not installed. Proceed to step 6 to find the current Outlook user interface locale to prepare for installing an appropriate version of the OSC.

  4. Proceed with this step if Outlook 2010 or Outlook 2013 is installed on the client computer:

    1. Determine the bitness of the installed version of Outlook by examining the Bitness key in the following location in the Windows registry:

      • For Outlook 2010, look at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\14.0\Outlook

      • For Outlook 2013, look at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\15.0\Outlook

      The Bitness key is "x86" for 32-bit Outlook, or "x64" for 64-bit Outlook.

    2. If your provider is a managed provider, and you compiled the provider component specifying the target platform as Any CPU, proceed with step 6 to find the current Outlook user interface locale to prepare for installing the latest version of the OSC. Your provider will work on both 32-bit and 64-bit versions of the OSC.

    3. If your provider is a native COM component, examine the bitness of the installed version of Outlook:

      • If the installed version of Outlook is 32-bit, your installation procedure will have to install a 32-bit provider (in step 8), after ensuring that an appropriate OSC is installed.

      • Otherwise, the installed version of Outlook is 64-bit, and your installation procedure will have to install a 64-bit provider (in step 8), after ensuring that an appropriate OSC is installed.

    4. Proceed with step 6 to find the current Outlook user interface locale to prepare for installing an appropriate version of the OSC.

  5. Proceed with this step if Outlook 2003 or Outlook 2007 is installed, and the OSC is installed on the client computer: Check the current Outlook user interface locale by examining the OSCLcid key in the following location in the Windows registry:

    HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\OSCLcid

    The OSCLcid key is a DWORD value that specifies the Internet Engineering Task Force (IETF) locale tag (defined by [RFC4646] and [RFC4647]), that represents the current Outlook user interface locale. Proceed with step 7 to install the latest OSC on the client computer.

  6. Proceed with this step if Outlook 2003 or Outlook 2007 is installed, or Outlook 2010 or Outlook 2013 is present, but the latest OSC is not necessarily installed on the client computer:

    Use the LanguageSettings object to determine the LCID of the Outlook user interface locale. The following Visual Basic Scripting Edition (VBScript) code snippet demonstrates how to obtain the LCID of the Outlook user interface locale.

    VBS Copy code Copy code
    Function GetOutlookUI_LCID()
    ' Declare variables.
    Dim msoLanguageIDUI, olApp
    msoLanguageIDUI = 2
    Set olApp = CreateObject("Outlook.Application")
    ' Return Outlook UI LCID.
    GetOutlookUI_LCID = olApp.LanguageSettings.LanguageID(msoLanguageIDUI)
End Function

  7. Proceed with this step if the installer has the LCID of the installed version of Outlook, but the latest OSC is not necessarily installed on the client computer:

    Chain a g-link into your installation package to ensure that the latest version of the OSC is installed on the client computer. The g-link format is as follows:

    http://g.live.com/0CRLCID/Glink

    Refer to Table 1 below for the supported LCID values, and Table 2 for the supported Glink values. For example, the g-link to install the latest version of the 32-bit OSC for 32-bit Outlook Social Connector 2013 (US English) is as follows:

    http://g.live.com/0CR1033/82

  8. Install the provider. The provider installation procedure must register the programmatic identifier (ProgID) in the appropriate Windows registry location. For more information, see Registering a Provider. Also, be sure that the bitness of the provider to be installed is the same as the bitness of the version of Outlook present on the client computer. For example, install a 32-bit provider if 32-bit Outlook 2013 is present, and a 64-bit provider if 64-bit Outlook 2013 is installed. For Outlook 2003 or 2007, only the 32-bit version of your provider applies.

Table 1: Supported locale and corresponding LCID values in hexadecimal for the OSC

Locale | LCID
ar-sa | 1025
bg-bg | 1026
ca-es | 1027
cs-cz | 1029
da-dk | 1030
de-de | 1031
el-gr | 1032
en-us | 1033
es-es | 3082
et-ee | 1061
eu-es | 1069
fi-fi | 1035
fr-fr | 1036
gl-es | 1110
he-il | 1037
hi-in | 1081
hr-hr | 1050
hu-hu | 1038
it-it | 1040
ja-jp | 1041
kk-kz | 1087
ko-kr | 1042
lt-lt | 1063
lv-lv | 1062
nb-no | 1044
nl-nl | 1043
pl-pl | 1045
pt-br | 1046
pt-pt | 2070
ro-ro | 1048
ru-ru | 1049
sk-sk | 1051
sl-si | 1060
sr-cyrl-cs | 3098
sr-latn-cs | 2074
sv-se | 1053
th-th | 1054
tr-tr | 1055
uk-ua | 1058
zh-cn | 2052
zh-tw | 1028

Table 2: Supported Glink values for the OSC

Glink value | Function
80 | Installs the latest version of OSC for Outlook 2003 or Outlook 2007.
82 | Installs the latest patch of 32-bit OSC for Outlook 2007, Outlook 2010, or Outlook Social Connector 2013.
83 | Installs the latest patch of 64-bit OSC for Outlook 2010 or Outlook Social Connector 2013.

See also

Concepts

Registering a Provider
Quick Steps for Learning to Develop a Provider

Other resources

Deploying a Provider


Getting Ready to Release an OSC Provider

 Copy code hover
[image]

Getting Ready to Release an OSC Provider
Send feedback

Published: July 16, 2012

This section suggests tests you can do before you release your Outlook Social Connector (OSC) provider. You can start referring to the topics in this section and carry out some of these tests during your development and testing phases, but you should have completed these tests by the time you release. These tests verify the basic functionality of your implementation of the OSC provider interfaces with respect to the capabilities you specify for the OSC provider. Also, even though the OSC is a feature shared by multiple Office client applications, these tests use Outlook as the client to test the fundamental functionality. You should determine whether other tests are necessary for features specific to your provider.

In this section

Testing Deployment

Describes scenarios you should test for around installing and uninstalling an OSC provider.

Testing Capabilities, Authentication, and Configuration

Describes tests for getting capabilities, and scenarios around configuring an account and authenticating a user for a social network.

Testing Following and Stop-Following Persons

Describes scenarios to test the OSC provider's ability to add a person as a friend, or to remove a friend from the social network.

Testing Friends

Describes tests and scenarios to verify that the OSC provider appropriately returns data of friends and non-friends, where applicable, depending on the synchronization mode that the provider supports.

Testing Activities

Describes tests and scenarios to verify that the OSC provider appropriately returns activities of friends and non-friends, where applicable, depending on the synchronization mode that the provider supports.

Reference

Outlook Social Connector Provider Reference

Related sections

OSC Sample Templates

OSC Typical Calling Sequences

Developing a Provider with the OSC XML Schema

Debugging a Provider

Deploying a Provider


Testing Deployment

 Copy code hover
[image]

Testing Deployment
See also Send feedback

Published: July 16, 2012

This topic describes some scenarios that you should test for regarding installing and uninstalling an Outlook Social Connector (OSC) provider.

Presence of Outlook and the OSC on Client Computer

Factors the affect installing an OSC provider includes the bitness of the operating system, the presence and bitness of Outlook, and the OSC being enabled in Outlook.

An OSC provider can be written for either a 32-bit or 64-bit version of the OSC. Outlook 2010 and Outlook 2013 are available in both 32-bit and 64-bit versions, and Office Outlook 2003 and Office Outlook 2007 are available in only 32-bit versions. On a 64-bit Windows operating system, you can install either 32-bit or 64-bit Outlook. On a 32-bit operating system, you can install only 32-bit, but not 64-bit, Outlook. Depending on the bitness of the installed version of Outlook and the OSC provider itself, the user should use the appropriate installer to install an OSC provider of the appropriate bitness. For example, if 64-bit Outlook is installed, and the OSC provider is a native COM component, a 32-bit OSC provider will not work and the user must use the appropriate installer to install a 64-bit OSC provider.

The deployment code of your OSC provider can assume that the user has a supported version of Outlook on the computer. However, if the current version of OSC is not on the client computer, your deployment code can download and install an appropriate version of the OSC by using specially constructed g-link URLs on http://g.live.com. These g-links depend on the version and bitness of Outlook and the locale of the client computer. For more information about using g-links to install or update the OSC, see Installation Checklist.

Before installing an OSC provider, the Outlook user should ensure that the OSC add-in is enabled in Outlook.

The recommended method of deploying an OSC provider is to use a Windows Installer (.msi) package. Test each of the following scenarios to verify deployment works appropriately for the provider.

Scenario | Expected behavior
Outlook is not present - Outlook 2003 or Outlook 2007 is not installed, and Outlook 2010 or Microsoft Outlook 2013 is not installed nor has it been delivered by Click-to-Run. | The deployment fails.
Outlook 2003 or Outlook 2007 is not installed, but Outlook 2010 or Microsoft Outlook 2013 has been delivered by Click-to-Run. | The 32-bit provider is deployed.
Outlook 2003 or Outlook 2007 is installed, but the OSC is not installed. | The installer installs the OSC and all patches. Once the OSC has been installed successfully, then the installer deploys the provider.
Outlook 2003 or Outlook 2007 is installed, and an earlier version of the OSC is installed. | The installer updates the OSC, via a g-link to patches, and then deploys the provider.
Outlook 2003 or 2007 is installed and the OSC is up-to-date. | The installer deploys the 32-bit provider.
Outlook 2010 or Microsoft Outlook 2013 is installed but the OSC is not installed. | The installer fails with an appropriate error message.
Outlook 2010 or Microsoft Outlook 2013 is installed and an older version of the OSC is installed. | The installer which is appropriate for the bitness of the installed Outlook 2010 or Microsoft Outlook 2013, updates the OSC via the g-link to patches, and then deploys the appropriate provider.
Outlook 2010 or Microsoft Outlook 2013 is installed and the OSC is up-to-date. | The installer that is appropriate for the bitness of the installed Outlook 2010 or Microsoft Outlook 2013 (32-bit or 64-bit) deploys the appropriate provider.

Installed Location and Registry Keys

Verify the file location where your OSC provider has been deployed, and the locations in the Windows registry where registry keys for your provider are created.

File Location for OSC Provider DLLs

Test for the scenarios as listed in the following table. Note that the table lists the default installation paths for OSC provider DLLs. Users can customize where they install these DLLs.

Scenario | Expected behavior
Microsoft Outlook 2013 is installed on the client computer. | Provider DLLs are deployed into the Office15 folder. If the operating system is 64-bit and Microsoft Outlook 2013 is 32-bit, the 32-bit DLLs are deployed under C:\Program Files (x86)\Microsoft Office\Office15. If the operating system is 64-bit and Microsoft Outlook 2013 is 64-bit, the 64-bit DLLs are deployed under C:\Program Files\Microsoft Office\Office15. If the operating system is 32-bit, DLLs are deployed under C:\Program Files\Microsoft Office\Office15.
Outlook 2010 is installed on the client computer. | Provider DLLs are deployed into the Office14 folder. If the operating system is 64-bit and Outlook 2010 is 32-bit, the 32-bit DLLs are deployed under C:\Program Files (x86)\Microsoft Office\Office14. If the operating system is 64-bit and Outlook 2010 is 64-bit, the 64-bit DLLs are deployed under C:\Program Files\Microsoft Office\Office14. If the operating system is 32-bit, DLLs are deployed under C:\Program Files\Microsoft Office\Office14.
Outlook 2007 is installed on the client computer. | Provider DLLs are deployed under C:\Program Files\Microsoft Office\Office14. Installing the OSC creates the Office14 folder, and the OSC should be installed before any provider DLLs. See the previous section Presence of Outlook and the OSC on Client Computer.
Outlook 2003 is installed on the client computer. | Provider DLLs are deployed under C:\Program Files\Microsoft Office\Office14. Installing the OSC creates the Office14 folder, and the OSC should be installed before any provider DLLs. See the previous section Presence of Outlook and the OSC on Client Computer.
Microsoft Outlook 2013 is not installed but delivered by Click-to-Run on the client computer. | Provider DLLs are deployed into the Office15 folder. If the operating system is 64-bit, 32-bit DLLs are deployed under C:\Program Files (x86)\Microsoft Office\Office15 or C:\Program Files\Microsoft Office\Office15. If the operating system is 32-bit, DLLs are deployed under C:\Program Files\Microsoft Office\Office15. If the Office15 folder does not exist, the installation creates the folder.
Outlook 2010 is not installed but delivered by Click-to-Run on the client computer. | Provider DLLs are deployed into the Office14 folder. If the operating system is 64-bit, 32-bit DLLs are deployed under C:\Program Files (x86)\Microsoft Office\Office14 or C:\Program Files\Microsoft Office\Office14. If the operating system is 32-bit, DLLs are deployed under C:\Program Files\Microsoft Office\Office14. If the Office14 folder does not exist, the installation creates the folder.

Windows Registry Locations

Verify the following:

  • The OSC provider installer creates a ProgID value for the OSC provider in the Windows registry, in either HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders or HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

  • The exception is if the client computer has 32-bit Outlook running on a 64-bit Windows operating system. In this case, the ProgID is created in either HKEY_CURRENT_USER\Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders or HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

  • The registry keys should be the same and in the same location if, instead, the DLLs are registered by regsvr32.exe.

Removing the Installation

The following are some tests to verify that the uninstall process works properly for your OSC provider.

Scenario | Expected behavior
User chooses to uninstall the provider. | The provider uninstalls the DLLs and clears the registry.
User chooses to cancel the uninstall process of the provider. | The provider cancels the uninstall process and brings the user back to the state before the uninstall process started.

See also

Concepts

Registering a Provider
Installation Checklist

Other resources

Getting Ready to Release an OSC Provider


Testing Capabilities, Authentication, and Configuration

 Copy code hover
[image]

Testing Capabilities, Authentication, and Configuration
See also Send feedback

Published: July 16, 2012

This topic describes tests for getting capabilities, and scenarios around configuring an account and authenticating a user for a social network.

Getting Capabilities

A Outlook Social Connector (OSC) provider implements ISocialProvider::GetCapabilities, and the OSC calls GetCapabilities to get the functionality supported by the provider. The capabilities that your provider supports for your social network should be known at the point of implementation, and should not depend on a call to the social network in real time. For example, Outlook users can start Outlook offline, and GetCapabilities cannot rely on network connectivity at the time when Outlook starts.

When testing the provider, you should verify that the results string parameter returned by GetCapabilities conforms to the capabilities element as defined by the OSC provider XML schema. For more information, see Capabilities XML Elements.

Configuring an Account

When the OSC configures an account, you should verify whether the social network icon and name are displayed, and that the create-account and forgot-password hyperlinks appear in the account configuration dialog box as specified by the provider.

Social Network Icon and Name

After getting capabilities, the OSC can proceed to get the icon and name for the social network by calling ISocialProvider::SocialNetworkIcon and ISocialProvider::SocialNetworkName. Do the following tests to verify that these method calls succeed.

Item to test

Expected behavior

Social network icon

The social network icon is displayed correctly in the following places in the OSC:

  • In the OSC dialog box for Social Network Accounts.

  • In the drop-down menu when you attempt to add a person as a friend.

  • In the badge when following a friend.

Note Note

You can access the dialog box for Social Network Accounts by clicking the View tab in Outlook, in the People Pane group, clicking People Pane, and then clicking Account Settings.

Social network name

The social network name is displayed correctly in the following places in the OSC:

  • In the OSC dialog box for Social Network Accounts.

  • In the drop-down menu when you attempt to add a person as a friend.

  • As the title of the password dialog box when you attempt to change the existing password.

Showing Hyperlinks in Configuration Dialog

After calling ISocialProvider::GetCapabilities, the OSC uses the value of the hideHyperlinks element in the results parameter to determine whether to hide or display the Click here to create an account and Forgot your password? hyperlinks in the account configuration dialog box. Verify that if hideHyperlinks is false, the account configuration displays these URLs.

Support to Create Account

Verify that if the results parameter from the ISocialProvider::GetCapabilities method call has the hideHyperlinks element set to false and the createAccountUrl element set to true, clicking the URL opens the page in the default web browser.

Support for Forgotten Password

Verify that if the results parameter from the ISocialProvider::GetCapabilities method call has the hideHyperlinks element set to false and the forgotPasswordUrl element set to true, clicking the URL opens the page in the default web browser.

Authenticating Users

Test for the following scenarios regardless of whether your OSC provider supports basic authentication or forms-based authentication.

Scenario | Expected behavior
Logging on for the first time. | The user can successfully log on to the social network.
Logging on with a password made up of a variety of characters, including punctuation and Unicode characters. | The user can successfully log on to the social network, independent of the kind of characters used in the password.
The dialog box for Social Network Accounts displaying the user name or ID. | After the user has successfully logged on to the network, the OSC's dialog box for Social Network Accounts displays the logged-on user name or ID.
Authentication fails. | The OSC displays the error Invalid user name or password.
Cannot connect to the social network. | The OSC displays the error Server cannot be found.
Being able to retrieve items. | Once the user has authenticated, all activity should be allowed. There are no errors getting friends' data or activities.
Logging on to the social network after restarting Outlook. | If the OSC provider allows caching of the password, after the user has authenticated the first time, the user is not subsequently prompted for credentials whenever the OSC attempts to get data from the social network.

In addition, if your OSC provider supports forms-based authentication, test for the following scenario as well.

Scenario | Expected behavior
The OSC getting a URL to a form for the user to log on from calling ISocialSession::GetLogonUrl. | The OSC opens the URL in the user's default browser, and the webpage allows the user to enter credentials to log on to the social network.

See also

Concepts

Capabilities XML Elements
Basic Authentication
Forms-Based Authentication

Other resources

Getting Ready to Release an OSC Provider


Testing Following and Stop-Following Persons

 Copy code hover
[image]

Testing Following and Stop-Following Persons
See also Send feedback

Published: July 16, 2012

This topic describes scenarios to test the Outlook Social Connector (OSC) provider's ability to follow a friend, and to stop following a friend on the social network.

Following a Person

To follow a person is to add a person as a friend on the social network, using the SMTP address provided by the selected Outlook item. Following someone on a social network usually involves requesting permission from that person by an email to that SMTP address. In order to grant permission, that person must either have that SMTP address already included in his or her social network account, or be willing to add that SMTP to a social network account. Test each of the following scenarios to verify that your OSC provider behaves correctly.

Scenario

Expected behavior

Attempting to follow a person on the social network who exists on the social network.

For a social network that does not require permission from the person, the social network immediately adds the person as a friend.

For a network that requires permission from that person, the social network sends a notification. The Outlook People Pane displays a pending icon for that person.

Attempting to follow a person on the social network who does not exist on the social network.

The OSC provider displays the appropriate error in ISocialSession::FollowPerson or ISocialSession2::FollowPersonEx.

Following a friend on the social network.

For the friend selected in the People Pane, the social network's badge and the friend's profile picture for that social network are displayed.

Selecting the link to the profile page of a friend.

The friend's page on the social network opens in the logged-on user's default browser.

Stop Following a Person

To stop following a person is to remove that person as a friend on the social network. Test the following scenario to verify your OSC provider stops following a person properly.

Scenario | Expected behavior
Attempting to remove a person as a friend on the social network. | The social network no longer lists that person as a friend on the logged on user's account.

See also

Other resources

Getting Ready to Release an OSC Provider


Testing Friends

 Copy code hover
[image]

Testing Friends
See also Send feedback

Published: July 16, 2012

This topic describes tests and scenarios to verify that the Outlook Social Connector (OSC) provider appropriately returns data of friends and non-friends, where applicable, depending on the synchronization mode supported by the provider.

Cached Synchronization

An OSC provider implements ISocialProvider::GetCapabilities, which the OSC calls to determine whether the provider supports cached synchronization of friends' data. After calling ISocialPerson::GetFriendsAndColleagues, the OSC stores the returned friends' data in a contacts folder specific to the social network in the logged-on user's default Outlook store. The OSC also calls ISocialSession::GetPerson and ISocialPerson::GetPicture to obtain a profile picture for each friend.

Initiate Synchronization

To initiate synchronization, you can turn on and use the debug button Sync Contacts in the ribbon component of the Microsoft Office Fluent user interface. For more information about OSC debug buttons, see Debugging a Provider.

Test Scenarios

Test the following items to verify that friends' data is cached correctly.

Item to test | Expected behavior
Contacts folder | The social network-specific contacts folder exists in the user's default Outlook store.
Friends' data returned by ISocialPerson::GetFriendsAndColleagues | Each friend corresponds to a contact in the network-specific contacts folder.
Friends' data | Contact fields for each friend have the correct data.
Friends' profile pictures returned by ISocialPerson::GetPicture | The contact item for each friend contains the profile picture.

On-Demand Synchronization

An OSC provider implements ISocialProvider::GetCapabilities, which the OSC calls to determine whether the provider supports on-demand synchronization of friends and non-friends. For the persons displayed in the Outlook People Pane, the OSC obtains and hashes their SMTP addresses, calls ISocialSession2::GetPeopleDetails, and stores (in memory) the data returned for these persons.

Determining Friends and Non-Friends

The hashed SMTP addresses passed to GetPeopleDetails are the key to determining whether a person is a friend or non-friend. If a person does not include that SMTP address in his or her social network account, or even if that person is a friend by a different email address on the social network, GetPeopleDetails still returns nonfriend for that person as the friendStatus in the personsCollection parameter. Also, for a person who is not a friend but specifies the SMTP address in his or her social network account, the data returned includes only what is available to a non-friend as allowed by the privacy settings of that person.

Creating Test Subjects for Friends and Non-Friends

To create a test subject for a friend, identify the SMTP address of a person who includes that address in his or her social network account and who has a friend status with the logged-on user on that network. Create an email message that includes that SMTP address. Similarly, to create a test subject for a non-friend, identify the SMTP address of a person who is not a friend of the logged-on user by that address, and yet who has specified in his or her privacy settings to allow non-friends to view their activities on the social network. Create an email message that includes that SMTP address.

In the Outlook explorer, when you select the email message that includes a friend (or non-friend), the People Pane displays the recipients. Selecting the friend (or non-friend) in the People Pane allows you to test that the provider is providing information about the person.

Test Scenarios

To verify that your provider is providing information about friends and non-friends appropriately, test for the following scenarios.

Scenario | Expected behavior
Person selected in the People Pane is a friend with the logged-on user on the social network. | The People Pane displays that person's activities on the social network.
Person selected in the People Pane is a non-friend of the logged-on user on the social network, but has allowed his or her activities to be viewed by non-friends. | The People Pane displays that person's activities on the social network.

Hybrid Synchronization

If an OSC provider supports hybrid synchronization of friends and non-friends, the OSC does the following:

  • The OSC stores information for friends of the logged-on user in the social network-specific contact folder.

  • The OSC retrieves information for non-friends on-demand from the social network, and stores it only in memory, but not in a folder.

To test hybrid synchronization, follow the testing suggestions in the Cached Synchronization section for friends, and those in the On-Demand Synchronization section for non-friends.

See also

Concepts

Synchronizing Friends and Activities
XML for Friends

Other resources

Getting Ready to Release an OSC Provider


Testing Activities

 Copy code hover
[image]

Testing Activities
See also Send feedback

Published: July 16, 2012

This topic describes tests and scenarios to verify that the Outlook Social Connector (OSC) provider uses on-demand synchronization to appropriately return activities of friends and non-friends.

On-Demand Synchronization

An OSC provider implements ISocialProvider::GetCapabilities, which the OSC calls to determine whether the provider supports on-demand synchronization of activities of friends and non-friends. For the persons displayed in the Outlook People Pane, the OSC obtains and hashes their SMTP addresses, calls ISocialSession2::GetActivitiesEx, and stores (in memory) the activities data returned for these persons.

Determining Activities to Get

The hashed SMTP addresses passed to GetActivitiesEx are the key to determining whether the OSC will get activities for a friend or non-friend. The OSC gets activities for a person if the person specifies that SMTP address in his or her social network account. If the person does not include that SMTP address in his or her social network account, or if that person is a friend but by a different email address on the social network, GetActivitiesEx does not get activities for that person. Also, for a person who is not a friend but specifies the SMTP addresses in his or her social network account, the data returned includes only what is available to a non-friend as allowed by the privacy settings of that person.

Creating Test Subjects for Friends and Non-Friends

To create a test subject for a friend, identify the SMTP address of a person who includes that address in his or her social network account and who has a friend status with the logged-on user on that network. Create an email message that includes that SMTP address. Similarly, to create a test subject for a non-friend, identify the SMTP address of a person who is not a friend of the logged-on user by that address, and who has specified in his or her privacy settings to allow non-friends to view their profile on the social network. Create an email message that includes that SMTP address.

In the Outlook explorer, when you select the email message that includes a friend (or non-friend), the People Pane displays the recipients. Selecting the friend (or non-friend) in the People Pane allows you to test that the provider is providing information about the person.

Test Scenarios

To verify that you are getting appropriate activities for friends and non-friends, test for the following scenarios.

Scenario | Expected behavior
Person selected in the People Pane is a friend with the logged-on user on the social network. | The People Pane displays that person's profile and profile picture as posted on the social network.
Person selected in the People Pane is a non-friend of the logged-on user on the social network, but has allowed his or her profile to be viewed by non-friends. | The People Pane displays that person's profile and profile picture as posted on the social network.

See also

Concepts

Synchronizing Friends and Activities
XML for Activities

Other resources

Getting Ready to Release an OSC Provider


Outlook Social Connector Provider Reference

 Copy code hover
[image]

Outlook Social Connector Provider Reference
Send feedback

Published: July 16, 2012

This section contains reference topics for Outlook Social Connector (OSC) provider extensibility.

In this section

Interfaces

XML Schema

Error Codes

Related sections

Best Practices for Developing a Provider

OSC Sample Templates


Outlook Social Connector Provider Interfaces

 Copy code hover
[image]

Outlook Social Connector Provider Interfaces
Send feedback

Published: July 16, 2012

The Outlook Social Connector (OSC) is an Office feature shared by Office client applications that connects to social and business networks so users can stay in touch with the people in their networks without leaving Office.

An OSC provider is a Component Object Model (COM) DLL that allows the OSC to access social network data in a way that is independent of the APIs of each social network. The following table lists the interfaces in OSC provider extensibility. An OSC provider must implement four of the five interfaces to communicate with the OSC: ISocialPerson, ISocialProfile, ISocialProvider, and ISocialSession. If the OSC provider supports synchronizing activities, on-demand or hybrid synchronization of friends, caching logon credentials and logging on using cached credentials, or the ability to follow a person, the provider should implement ISocialSession2, as well.

Name | Description
ISocialPerson | Represents a person on the social network.
ISocialProfile | Represents the logged-on user.
ISocialProvider | Represents an instance of an OSC provider.
ISocialSession | Represents a connection to a social network site.
ISocialSession2 | Supports synchronizing activities, adding friends, on-demand or hybrid synchronization of friends, or logging on to the social network by using cached credentials.


ISocialPerson : IUnknown

 Copy code hover
[image]

ISocialPerson : IUnknown
See also Send feedback

Published: July 16, 2012

Represents a person on the social network.

Members

The following table shows the members that are available on the ISocialPerson interface.

Name | Member type | Description
GetActivities | Method | This method has been deprecated since Outlook Social Connector 2013.
GetDetails | Method | Gets a string that represents details for the person, such as the first name, last name, and a URL to a profile picture.
GetFriendsAndColleagues | Method | Gets a string that represents a collection of people.
GetFriendsAndColleaguesIDs | Method | This method is currently not supported.
GetPicture | Method | Gets an array of bytes that contains the picture resource for the person.
GetStatus | Method | This method is currently not supported.

Remarks

An Outlook Social Connector (OSC) provider must implement this interface to communicate with the OSC.

See also

Concepts

Outlook Social Connector Provider Interfaces


ISocialPerson::GetActivities

 Copy code hover
[image]

ISocialPerson::GetActivities
See also Send feedback

Published: July 16, 2012

This method has been deprecated in Outlook Social Connector 2013.

C++
HRESULT _stdcall GetActivities([in] DATE startTime, [out, retval] BSTR* activities);

Remarks

Starting in Outlook Social Connector 2013, the OSC supports only on-demand synchronization of activities and not cached or hybrid synchronization of activities. The OSC ignores the cacheActivities setting in the capabilities XML and does not call this method. To support dynamic activities lookup, implement the ISocialSession2::GetActivitiesEx method. Set cacheActivities as false, getActivities and dynamicActivitiesLookupEx as true, which will prompt the OSC to call ISocialSession2::GetActivitiesEx instead.

For more information about how the OSC gets friends' activities, see Synchronizing Friends and Activities.

See also

Reference

ISocialPerson : IUnknown


ISocialPerson::GetDetails

 Copy code hover
[image]

ISocialPerson::GetDetails
See also Send feedback

Published: July 16, 2012

Gets a string that represents details for the person, such as the first name, last name, and a URL to a profile picture.

C++
HRESULT _stdcall GetDetails([out, retval] BSTR* details);

Parameters

details

[out] An XML string value that represents the details for a person.

Remarks

The returned details XML string must comply with the schema definition for person, as defined in the schema for Outlook Social Connector (OSC) provider extensibility.

The OSC calls GetDetails if the OSC provider supports cached or hybrid synchronization of friends on the social network. When the OSC initially gets friends' activities for the logged on user, it calls ISocialPerson::GetFriendsAndColleagues, and stores friends' information in a contacts folder specific to the social network, in the logged on user's default Outlook store. Subsequently the OSC does not call GetFriendsAndColleagues or GetDetails unless the refresh interval for the cache has expired. For more information about how the OSC caches friends' information in a contacts folder, see Synchronizing Friends and Activities.

See also

Reference

ISocialPerson : IUnknown


ISocialPerson::GetFriendsAndColleagues

 Copy code hover
[image]

ISocialPerson::GetFriendsAndColleagues
See also Send feedback

Published: July 16, 2012

Gets a string that represents a collection of people.

C++
HRESULT _stdcall GetFriendsAndColleagues([out, retval] BSTR* personsCollection);

Parameters

personsCollection

[out] An XML string that represents a set of friends of the person, and that complies with the definition of friends as defined in the XML schema for Outlook Social Connector (OSC) provider extensibility.

Remarks

The OSC calls GetFriendsAndColleagues if the OSC provider supports cached or hybrid synchronization of friends on the social network. When the OSC initially calls the GetFriendsAndColleagues method for the Outlook user who is logged on to the social network, GetFriendsAndColleagues returns an XML string that represents friends of the logged-on user on the social network. The XML string complies with the friends XML schema definition and specifies a person element (which also complies with the OSC provider schema definition) for each friend.

When GetFriendsAndColleagues returns the friends information for the logged-on user, the OSC stores that information in a contacts folder. This folder is specific to the social network and resides in the logged-on user's default Outlook store. For more information about how the OSC caches friends' information in a contacts folder, see Synchronizing Friends and Activities.

Information for each friend returned in the personsCollection parameter complies with the XML schema definition for person. The person element supports many pieces of information for each friend, including the SMTP email addresses (which map to the emailAddress, emailAddress2, and emailAddress3 elements) that the friend has specified on the social network, and the user ID (which maps to the userID element) that identifies that friend on the social network.

To show activities for an Outlook user selected in the People Pane, the OSC tries to match the user with each friend returned from GetFriendsAndColleagues. The OSC does this by matching the SMTP address of the selected Outlook user with the email addresses that each friend has specified on the social network. If the OSC finds a matching SMTP email address, the OSC uses the corresponding userID of the friend to call the ISocialSession::GetPerson method. It does this to obtain an ISocialPerson object for that friend, which then enables the OSC to get activities and pictures of that friend from the social network.

However, if the selected Outlook user does not specify that same SMTP address on an account on the social network, or if the Outlook user does not have an account on that social network, the OSC will not be able to find a match for that user and will not display any activities for that user on the social network.

See also

Reference

ISocialPerson : IUnknown

Concepts

Getting Friends Information


ISocialPerson::GetFriendsAndColleaguesIDs

 Copy code hover
[image]

ISocialPerson::GetFriendsAndColleaguesIDs
See also Send feedback

Published: July 16, 2012

This method is currently not supported.

C++
HRESULT _stdcall GetFriendsAndColleaguesIDs([out, retval] SAFEARRAY(BSTR)* friendsIDs);

See also

Reference

ISocialPerson : IUnknown


ISocialPerson::GetPicture

 Copy code hover
[image]

ISocialPerson::GetPicture
See also Send feedback

Published: July 16, 2012

Gets an array of bytes that contains the picture resource for the person.

C++
HRESULT _stdcall GetPicture([out, retval] SAFEARRAY(unsigned char)* picture);

Parameters

picture

[out] A pointer to a structure that specifies an array of bytes that represent the picture resource for a person.

Remarks

Supported picture resources are in .bmp, .jpeg, or .png format.

See also

Reference

ISocialPerson : IUnknown


ISocialPerson::GetStatus

 Copy code hover
[image]

ISocialPerson::GetStatus
See also Send feedback

Published: July 16, 2012

This method is currently not supported.

C++
HRESULT _stdcall GetStatus([out, retval] BSTR* status);

See also

Reference

ISocialPerson : IUnknown


ISocialProfile : ISocialPerson

 Copy code hover
[image]

ISocialProfile : ISocialPerson
See also Send feedback

Published: July 16, 2012

Represents the logged-on user.

Members

The following table shows the members that are available on the ISocialProfile interface.

Name | Member type | Description
AreFriendsOrColleagues | Method | Determines whether the specified users are friends.
GetActivitiesOfFriendsAndColleagues | Method | This method has been deprecated since Outlook Social Connector 2013.
SetStatus | Method | This method is currently not supported.

Remarks

An Outlook Social Connector (OSC) provider must implement this interface to communicate with the OSC.

See also

Concepts

Outlook Social Connector Provider Interfaces


ISocialProfile::AreFriendsOrColleagues

 Copy code hover
[image]

ISocialProfile::AreFriendsOrColleagues
See also Send feedback

Published: July 16, 2012

Determines whether the specified users are friends.

C++
HRESULT _stdcall AreFriendsOrColleagues(SAFEARRAY(BSTR) userIds, [out, retval] SAFEARRAY(VARIANT_BOOL)* results);

Parameters

userIds

[in] A structure that specifies an array of user ID values that correspond to a set of persons on the social network.

results

[out] A pointer to structure that specifies an array of Boolean values, indicating whether the corresponding person in the userIds array is a friend.

Remarks

For each person represented in the input array of the userIds parameter, this method sets the corresponding element in the output array of the results parameter. true indicates that the person is a friend, and false indicates that the person is not a friend.

See also

Reference

ISocialProfile : ISocialPerson


ISocialProfile::GetActivitiesOfFriendsAndColleagues

 Copy code hover
[image]

ISocialProfile::GetActivitiesOfFriendsAndColleagues
See also Send feedback

Published: July 16, 2012

This method has been deprecated in Outlook Social Connector 2013.

C++
HRESULT _stdcall GetActivitiesOfFriendsAndColleagues([in] DATE startTime, [out, retval] BSTR* activitiesCollection);

Remarks

Starting in Outlook Social Connector 2013, the OSC supports only on-demand synchronization of activities and not cached or hybrid synchronization of activities. The OSC ignores the cacheActivities setting in the capabilities XML and no longer calls this method. To support dynamic activities lookup, implement the ISocialSession2::GetActivitiesEx method. Set getActivities and dynamicActivitiesLookupEx as true, which will prompt the OSC to call ISocialSession2::GetActivitiesEx instead.

For more information about how the OSC gets friends' activities, see Synchronizing Friends and Activities.

See also

Reference

ISocialProfile : ISocialPerson


ISocialProfile::SetStatus

 Copy code hover
[image]

ISocialProfile::SetStatus
See also Send feedback

Published: July 16, 2012

This method is currently not supported.

C++
HRESULT _stdcall SetStatus(BSTR status);

See also

Reference

ISocialProfile : ISocialPerson


ISocialProvider : IUnknown

 Copy code hover
[image]

ISocialProvider : IUnknown
See also Send feedback

Published: July 16, 2012

Represents an instance of an Outlook Social Connector (OSC) provider.

Members

The following table shows the members that are available on the ISocialProvider interface.

Name | Member type | Description
DefaultSiteUrls | Property | Returns an array of strings that specify site URLs for the OSC provider.
GetAutoConfiguredSession | Method | Gets an automatically configured ISocialSession interface.
GetCapabilities | Method | Gets a string that describes provider capabilities.
GetSession | Method | Gets an ISocialSession interface.
GetStatusSettings | Method | This method is currently not supported.
Load | Method | Initializes the OSC provider.
SocialNetworkGuid | Property | Returns a GUID that represents a unique identifier for the social network.
SocialNetworkIcon | Property | Returns an array of bytes that represents the icon for the social network.
SocialNetworkName | Property | Returns a string that represents the social network name.
Version | Property | Returns a string that represents the version number of the provider for this social network.

Remarks

An OSC provider must implement this interface to communicate with the OSC.

See also

Concepts

Outlook Social Connector Provider Interfaces


ISocialProvider::DefaultSiteUrls

 Copy code hover
[image]

ISocialProvider::DefaultSiteUrls
See also Send feedback

Published: July 16, 2012

Returns an array of strings that specify site URLs for the Outlook Social Connector (OSC) provider.

C++
[propget] HRESULT _stdcall DefaultSiteUrls([out, retval] SAFEARRAY(BSTR)* siteUrls);

Property Value

A pointer to a structure that specifies an array of strings that represent site URLs for the OSC provider.

Remarks

A provider can support multiple site URLs. The OSC sets the ISocialSession::SiteUrl property to inform the provider of the selected site URL.

The OSC uses the first element of the array as the default site URL. A provider can return additional elements in the site URL array, but the OSC does not use them.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::GetAutoConfiguredSession

 Copy code hover
[image]

ISocialProvider::GetAutoConfiguredSession
See also Send feedback

Published: July 16, 2012

Gets an automatically configured ISocialSession interface.

C++
HRESULT _stdcall GetAutoConfiguredSession([out, retval] ISocialSession** session);

Parameters

session

[out] An ISocialSession interface.

Remarks

The returned ISocialSession interface is automatically logged on to the network, based on a method that is specific to the provider.

The provider should return the OSC_E_NOT_IMPLEMENTED error if the social network does not support automatic configuration. For information about error codes, see Outlook Social Connector Provider Error Codes.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::GetCapabilities

 Copy code hover
[image]

ISocialProvider::GetCapabilities
See also Send feedback

Published: July 16, 2012

Gets a string that describes provider capabilities.

C++
HRESULT _stdcall GetCapabilities([out, retval] BSTR* result);

Parameters

result

[out] An XML string that represents the capabilities of an Outlook Social Connector (OSC) provider.

Remarks

The returned result XML string must comply with the schema definition for the capabilities element, as defined in the XML schema for OSC provider extensibility.

The provider must return a result string to enable subsequent calls from the OSC to the provider to operate correctly.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::GetSession

 Copy code hover
[image]

ISocialProvider::GetSession
See also Send feedback

Published: July 16, 2012

Gets an ISocialSession interface.

C++
HRESULT _stdcall GetSession([out, retval] ISocialSession** session);

Parameters

session

[out] An ISocialSession interface.

Remarks

The Outlook Social Connector (OSC) uses the ISocialSession interface to log on to the social network.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::GetStatusSettings

 Copy code hover
[image]

ISocialProvider::GetStatusSettings
See also Send feedback

Published: July 16, 2012

This method is currently not supported.

C++
HRESULT _stdcall GetStatusSettings([out] BSTR* statusDefault, [out] int* maxStatusLength);

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::Load

 Copy code hover
[image]

ISocialProvider::Load
See also Send feedback

Published: July 16, 2012

Initializes the Outlook Social Connector (OSC) provider.

C++
HRESULT _stdcall Load([in] BSTR socialProviderInterfaceVersion, [in] BSTR languageTag);

Parameters

socialProviderInterfaceVersion

[in] The version of the OSC provider interfaces expected by the OSC.

languageTag

[in] The Internet Engineering Task Force (IETF) language tag, defined by [RFC4646] and [RFC4647], that represents the current Outlook user-interface language.

Remarks

The version format for the socialProviderInterfaceVersion parameter is X.xxxx, where X is the major version and xxxx is the minor version of the OSC. For Office 2013, check for the major version being 15.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::SocialNetworkGuid

 Copy code hover
[image]

ISocialProvider::SocialNetworkGuid
See also Send feedback

Published: July 16, 2012

Returns a GUID that represents a unique identifier for the social network.

C++
[propget] HRESULT _stdcall SocialNetworkGuid([out, retval] GUID* guid);

Property Value

A pointer to a GUID value that represents a unique identifier for the social network.

Remarks

The GUID must be immutable and must not change even if the provider version changes.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::SocialNetworkIcon

 Copy code hover
[image]

ISocialProvider::SocialNetworkIcon
See also Send feedback

Published: July 16, 2012

Returns an array of bytes that represents the icon for the social network.

C++
[propget] HRESULT _stdcall SocialNetworkIcon([out, retval] SAFEARRAY(unsigned char)* networkIcon);

Property Value

A pointer to a structure that specifies an array of bytes that contains the icon for the social network.

Remarks

The supported picture resources are .bmp, .jpeg, and .png formats.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::SocialNetworkName

 Copy code hover
[image]

ISocialProvider::SocialNetworkName
See also Send feedback

Published: July 16, 2012

Returns a string that represents the social network name.

C++
[propget] HRESULT _stdcall SocialNetworkName([out, retval] BSTR* networkName);

Property Value

A string that contains the social network name.

Remarks

Outlook Social Connector (OSC) providers should localize the social network name.

See also

Reference

ISocialProvider : IUnknown


ISocialProvider::Version

 Copy code hover
[image]

ISocialProvider::Version
See also Send feedback

Published: July 16, 2012

Returns a string that represents the version number of the provider for this social network.

C++
[propget] HRESULT _stdcall Version([out, retval] BSTR* Version);

Property Value

A string that contains the version number of the provider.

Remarks

The version string should use the MajorVersion.MinorVersion format (for example, 1.4730).

See also

Reference

ISocialProvider : IUnknown


ISocialSession : IUnknown

 Copy code hover
[image]

ISocialSession : IUnknown
See also Send feedback

Published: July 16, 2012

Represents a connection to a social network site.

Members

The following table shows the members that are available on the ISocialSession interface.

Name | Member type | Description
FindPerson | Method | Gets a string that represents one or more persons who match the userID parameter.
FollowPerson | Method | Adds the person identified by the emailAddress parameter as a friend for the logged-on user on the social network.
GetActivities | Method | This method has been deprecated in Outlook Social Connector (OSC) 1.1.
GetLoggedOnUser | Method | Gets an ISocialProfile interface that represents the logged-on user.
GetLogonUrl | Method | Gets a string that represents a URL that is used for presenting a browser-based form to the user during web authentication.
GetNetworkIdentifier | Method | Gets a string that represents a unique social network identifier for a given social network connection.
GetPerson | Method | Gets an ISocialPerson interface based on the userID parameter.
LoggedOnUserID | Property | Returns a string that represents the social network user ID of the user who is currently logged on.
LoggedOnUserName | Property | Returns a string that represents the user name that is used when logging on.
Logon | Method | Logs on to the social network site by using the specified user name and password.
LogonWeb | Method | Logs on to the social network site by using forms-based authentication.
SiteUrl | Property | Sets the social network site URL.
UnFollowPerson | Method | Removes the person identified by the userID parameter as a friend on the social network.

Remarks

An OSC provider must implement this interface to communicate with the OSC.

See also

Concepts

Outlook Social Connector Provider Interfaces


ISocialSession::FindPerson

 Copy code hover
[image]

ISocialSession::FindPerson
See also Send feedback

Published: July 16, 2012

Gets a string that represents one or more persons who match the userID parameter.

C++
HRESULT _stdcall FindPerson([in] BSTR userId, [out, retval] BSTR* result);

Parameters

userId

[in] A social network user ID, SMTP address, or display name of a person.

result

[out] An XML string that represents one or more persons who match the identification information specified by the userId parameter.

Remarks

If one or more persons match the FindPerson request, this method returns the information for those persons in the result parameter. The result XML string must comply with the schema definition for friends, as defined in the schema for Outlook Social Connector (OSC) provider extensibility.

See also

Reference

ISocialSession : IUnknown


ISocialSession::FollowPerson

 Copy code hover
[image]

ISocialSession::FollowPerson
See also Send feedback

Published: July 16, 2012

Adds the person identified by the emailAddress parameter as a friend for the logged-on user on the social network.

C++
HRESULT _stdcall FollowPerson([in] BSTR emailAddress);

Parameters

emailAddress

[in] A string that contains an email address of a person.

Remarks

The emailAddress parameter must be a valid SMTP address. If the Outlook Social Connector (OSC) provider has set the followPerson method as true in capabilities, and the argument for emailAddress does not match a user on the network, the provider must return the OSC_E_NOT_FOUND error. If the provider has set followPerson as false in capabilities, the provider should return the OSC_E_FAIL error.

If the provider implements the ISocialSession2 interface and has set followPerson as true in capabilities, the OSC will call ISocialSession2::FollowPersonEx instead of ISocialSession::FollowPerson. If the provider does not implement the ISocialSession2 interface, or ISocialSession2::FollowPersonEx returns the OSC_E_NOTIMPL error, the OSC will call ISocialSession::FollowPerson as long as the provider has set followPerson as true in capabilities. For information about error codes, see Outlook Social Connector Provider Error Codes.

In deciding whether to implement ISocalSession::FollowPerson or ISocialSession2::FollowPersonEx, you should consider whether your provider needs the other methods in ISocialSession2, and whether you can use the djsplayName parameter in FollowPersonEx.

See also

Reference

ISocialSession : IUnknown


ISocialSession::GetActivities

 Copy code hover
[image]

ISocialSession::GetActivities
See also Send feedback

Published: July 16, 2012

This method has been deprecated in OSC 1.1.

C++
HRESULT GetActivities([in] SAFEARRAY(BSTR) emailAddresses, [in] DATE startTime, [out, retval] BSTR *activities);

Remarks

Starting in OSC 1.1, the OSC no longer calls GetActivities. The OSC ignores the value of dynamicActivitiesLookup. To support dynamic activities lookup, implement the ISocialSession2::GetActivitiesEx method. Set cacheActivities as false, and getActivities and dynamicActivitiesLookupEx as true, which will prompt the OSC to call ISocialSession2::GetActivitiesEx instead.

See also

Reference

ISocialSession : IUnknown


ISocialSession::GetLoggedOnUser

 Copy code hover
[image]

ISocialSession::GetLoggedOnUser
See also Send feedback

Published: July 16, 2012

Gets an ISocialProfile interface that represents the logged-on user.

C++
HRESULT _stdcall GetLoggedOnUser([out, retval] ISocialProfile** result);

Parameters

result

[out] An ISocialProfile interface.

See also

Reference

ISocialSession : IUnknown


ISocialSession::GetLogonUrl

 Copy code hover
[image]

ISocialSession::GetLogonUrl
See also Send feedback

Published: July 16, 2012

Gets a string that represents a URL that is used for presenting a browser-based form to the user during web authentication.

C++
HRESULT _stdcall GetLogonUrl([out, retval] BSTR* url);

Parameters

url

[out] A string that contains a URL for the form used in web authentication.

Remarks

After the form is presented to the user, the ISocialSession::LogonWeb method is called with an empty string for the connectIn parameter.

See also

Reference

ISocialSession : IUnknown


ISocialSession::GetNetworkIdentifier

 Copy code hover
[image]

ISocialSession::GetNetworkIdentifier
See also Send feedback

Published: July 16, 2012

Gets a string that represents a unique social network identifier for a given social network connection.

C++
HRESULT _stdcall GetNetworkIdentifier([out, retval] BSTR* networkIdentifier);

Parameters

networkIdentifier

[out] A string that contains a unique social network identifier.

Remarks

A unique network identifier is a string that identifies the Outlook Social Connector (OSC) provider social network. This method can also return E_NOTIMPL.

See also

Reference

ISocialSession : IUnknown


ISocialSession::GetPerson

 Copy code hover
[image]

ISocialSession::GetPerson
See also Send feedback

Published: July 16, 2012

Gets an ISocialPerson interface based on the userID parameter.

C++
HRESULT _stdcall GetPerson([in] BSTR userId, [out, retval] ISocialPerson** result);

Parameters

userId

[in] A string that contains a user ID or SMTP address of a person.

result

[out] An ISocialPerson interface.

Remarks

The userID parameter must be a user ID or SMTP address.

See also

Reference

ISocialSession : IUnknown


ISocialSession::LoggedOnUserID

 Copy code hover
[image]

ISocialSession::LoggedOnUserID
See also Send feedback

Published: July 16, 2012

Returns a string that represents the social network user ID of the user who is currently logged on.

C++
[propget] HRESULT _stdcall LoggedOnUserID([out, retval] BSTR* result);

Property Value

A string that contains the social network user ID of the logged-on user.

See also

Reference

ISocialSession::LoggedOnUserName
ISocialSession : IUnknown


ISocialSession::LoggedOnUserName

 Copy code hover
[image]

ISocialSession::LoggedOnUserName
See also Send feedback

Published: July 16, 2012

Returns a string that represents the user name that is used when logging on.

C++
[propget] HRESULT _stdcall LoggedOnUserName([out, retval] BSTR* result);

Property Value

A string that represents the user name of the logged-on user.

See also

Reference

ISocialSession::LoggedOnUserID
ISocialSession : IUnknown


ISocialSession::Logon

 Copy code hover
[image]

ISocialSession::Logon
See also Send feedback

Published: July 16, 2012

Logs on to the social network site by using the specified user name and password.

C++
HRESULT _stdcall Logon([in] BSTR username, [in] BSTR password);

Parameters

username

[in] A string that contains the user name to log on.

password

[in] A string that contains the password to log on.

See also

Reference

ISocialSession : IUnknown


ISocialSession::LogonWeb

 Copy code hover
[image]

ISocialSession::LogonWeb
See also Send feedback

Published: July 16, 2012

Logs on to the social network site by using forms-based authentication.

C++
HRESULT _stdcall LogonWeb([in] BSTR connectIn, [out] BSTR* connectOut);

Parameters

connectIn

[in] A string that is null, an URL to a logon form on the web, or a string that contains logon credentials, depending on the context in the logon process when this method is called.

connectOut

[out] A string that contains logon credentials.

Remarks

The Outlook Social Connector (OSC) calls the LogonWeb method only if the provider indicates that it supports forms-based authentication. The provider indicates that it requires forms-based authentication by setting useLogonWebAuth as true in the XML for capabilities. If the provider sets useLogonWebAuth as false, the OSC uses basic authentication and calls the ISocialSession::Logon method.

Logging on to a social network site by using forms-based authentication involves calling the LogonWeb and ISocialSession::GetLogonUrl methods in a specific order:

  1. The OSC calls LogonWeb the first time, passing null to the connectIn parameter.

  2. The provider raises the OSC_E_AUTH_ERROR error to the OSC.

  3. The OSC next calls GetLogonUrl.

  4. The provider returns the appropriate URL to a logon page in the GetLogonUrl method.

  5. The OSC uses the URL returned by GetLogonUrl to display the forms-based logon page.

  6. The OSC then calls LogonWeb a second time, passing the URL to the logon form in the connectIn parameter.

  7. If authentication succeeds, the provider returns logon credentials in the connectOut parameter to the OSC. If authentication fails, the provider raises the OSC_E_AUTH_ERROR error to the OSC.

If the OSC provider supports logging on using cached credentials, it specifies useLogonCached as true in the capabilities XML. The provider should place any logon credentials in the connectOut string that the provider wants the OSC to store across connections. The OSC does not interpret the connectOut string. After the OSC verifies that useLogonCached is true, the OSC encrypts the string for security before storing it in the Windows registry. The OSC passes this string to the connectIn parameter on subsequent attempts to log on to the social network by calling ISocialSession2::LogonCached.

For information about error codes, see Outlook Social Connector Provider Error Codes.

See also

Reference

ISocialSession : IUnknown

Concepts

Forms-Based Authentication


ISocialSession::SiteUrl

 Copy code hover
[image]

ISocialSession::SiteUrl
See also Send feedback

Published: July 16, 2012

Sets the social network site URL.

C++
[propput] HRESULT _stdcall siteUrl([in] BSTR rhs);

Property Value

A string that represents a social network site URL.

See also

Reference

ISocialSession : IUnknown


ISocialSession::UnFollowPerson

 Copy code hover
[image]

ISocialSession::UnFollowPerson
See also Send feedback

Published: July 16, 2012

Removes the person identified by the userID parameter as a friend on the social network.

C++
HRESULT _stdcall UnFollowPerson([in] BSTR userID);

Parameters

userID

[in] A string that contains a social network user ID for a person.

Remarks

The userID parameter must be a valid user ID for the person on the social network.

If the Outlook Social Connector (OSC) provider has set doNotFollowPerson as true in the XML for capabilities, the provider must return the OSC_E_NOT_FOUND error in the case that the user ID passed in does not match a user on the network. If the provider has set doNotFollowPerson as false in capabilities, the provider should return the OSC_E_FAIL error. For information about error codes, see Outlook Social Connector Provider Error Codes.

See also

Reference

ISocialSession : IUnknown


ISocialSession2 : IUnknown

 Copy code hover
[image]

ISocialSession2 : IUnknown
See also Send feedback

Published: July 16, 2012

Supports adding friends, on-demand or hybrid synchronization of friends, on-demand synchronization of activities, or logging on to the social network by using cached credentials.

Members

The following table shows the members that are available on the ISocialSession2 interface.

Name | Member type | Description
FollowPersonEx | Method | Adds the person identified by the emailAddresses and displayName parameters as a friend for the logged-on user on the social network.
GetActivitiesEx | Method | Gets a string that represents a collection of activities of the users specified by the hashedAddresses parameter.
GetPeopleDetails | Method | Returns a string that contains a collection of person and picture details for the users specified by the personsAddresses parameter.
LogonCached | Method | Logs on to the social network site using cached credentials.

Remarks

An Outlook Social Connector (OSC) provider can choose to implement this interface if the provider supports on-demand or hybrid synchronization of friends, on-demand synchronization of activities, or logging on to the social network by using cached credentials. If the OSC provider implements ISocialSession2 and supports following persons on the social network, the OSC would call ISocialSession2::FollowPersonEx instead of ISocialSession::FollowPerson, and the provider must implement ISocialSession2::FollowPersonEx, as well.

See also

Concepts

Outlook Social Connector Provider Interfaces


ISocialSession2::FollowPersonEx

 Copy code hover
[image]

ISocialSession2::FollowPersonEx
See also Send feedback

Published: July 16, 2012

Adds the person identified by the emailAddresses and displayName parameters as a friend for the logged-on user on the social network.

C++
HRESULT _stdcall FollowPersonEx([in] SAFEARRAY(BSTR) emailAddresses, [in] BSTR displayName);

Parameters

emailAddresses

[in] An array that contains one or multiple valid SMTP addresses for a person on the social network.

displayName

[in] A string that contains the display name of the person to be added as a friend.

Remarks

If the Outlook Social Connector (OSC) provides more than on SMTP address in the array in the emailAddresses parameter, the OSC provider can assume the first element is the primary SMTP address.

If the provider has set the followPerson element as true in the capabilities XML, and none of the elements for emailAddresses match a user on the network, the provider must return the OSC_E_NOT_FOUND error. If the provider has set followPerson as false in capabilities, the provider should return the OSC_E_FAIL error.

If the FollowPersonEx method succeeds, the provider can use the string in the displayName parameter to address the person in any subsequent friend-confirmation email, rather than addressing the person by the SMTP address. On the other hand, the provider must be able to handle the OSC passing an empty string for the displayName parameter.

If the provider implements the ISocialSession2 interface and has set followPerson as true in the capabilities XML, the OSC calls FollowPersonEx instead of ISocialSession::FollowPerson. If the provider has set followPerson as true but does not implement the ISocialSession2 interface, or FollowPersonEx returns the OSC_E_NOTIMPL error, the OSC calls ISocialSession::FollowPerson.

See also

Reference

ISocialSession2 : IUnknown


ISocialSession2::GetActivitiesEx

 Copy code hover
[image]

ISocialSession2::GetActivitiesEx
See also Send feedback

Published: July 16, 2012

Gets a string that represents a collection of activities of each of the users specified by the hashedAddresses parameter.

C++
HRESULT _stdcall GetActivitiesEx([in] SAFEARRAY(BSTR) hashedAddresses, [in] DATE startTime, [out, retval] BSTR *activities);

Parameters

hashedAddresses

[in] A structure that specifies an array of hashed SMTP addresses for a set of users.

startTime

[in] The time after which activities that are created would be returned.

activities

[out] An XML string that represents the set of activities of the users specified by hashedAddresses on the social network since startTime.

Remarks

The OSC calls GetActivitiesEx if the OSC provider supports on-demand synchronization of activities. The OSC stores the information returned in activities in memory. For more information about how the OSC uses and updates this information in memory, see Synchronizing Friends and Activities.

Starting in Outlook Social Connector 2013, the OSC supports only on-demand synchronization of activities and calls only GetActivitiesEx to get activities. To support on-demand activities lookup, set cacheActivities as false, and getActivities and dynamicActivitiesLookupEx as true, and the OSC will call GetActivitiesEx.

The returned XML string must comply with the schema definition for activityFeed, as defined in the schema for OSC provider extensibility.

The hashedAddresses sring represents a set of hashed addresses for each user displayed in the People Pane. The hashed SMTP addresses are encrypted by using the hashing function specified by the hashFunction element in the provider's capabilities XML. The user does not have to be a friend of the logged-on user represented by the ISocialSession::LoggedOnUserName property.

The startTime parameter is a Date value in Coordinated Universal Time (UTC). Local time values must be converted to UTC Date values.

Activities that the GetActivitiesEx method returns must have a creation time value that is greater than startTime and less than or equal to Now. If no changes have occurred between startTime and Now, the provider must return an OSC_E_NO_CHANGES error.

See also

Reference

ISocialSession2 : IUnknown

Concepts

Synchronizing Friends and Activities


ISocialSession2::GetPeopleDetails

 Copy code hover
[image]

ISocialSession2::GetPeopleDetails
See also Send feedback

Published: July 16, 2012

Returns a string that contains a collection of person and picture details for the users specified by the personsAddresses parameter.

C++
HRESULT _stdcall GetPeopleDetails([in] BSTR personsAddresses, [out, retval] BSTR* personsCollection);

Parameters

personsAddresses

[in] An XML string that specifies the hashed SMTP addresses of a set of users.

personsCollection

[out] An XML string that contains a collection of person and picture details.

Remarks

The Outlook Social Connector (OSC) calls GetPeopleDetails if the OSC provider supports on-demand or hybrid synchronization of friends and non-friends.

The personsAddresses parameter must conform to the schema definition for hashedAddresses, as defined in the schema for OSC provider extensibility. The personsAddresses string represents a set of hashed SMTP addresses for each user displayed in the People Pane. The user does not have to be a friend of the logged-on user represented by the ISocialSession::LoggedOnUserName property. The hashed SMTP addresses are encrypted by using the hashing function specified by the hashFunction element in the provider's capabilities XML. The OSC identifies each hashedAddress in the personAddresses collection with an index element. The provider must use the index element to identify the recipient's person XML when it returns friends XML for GetPeopleDetails. If the recipient is not a registered user on the social network, the provider must not return any person XML for that recipient. The index element for each network user represented by person XML corresponds to the index element for the recipient in personsAddresses.

The OSC stores the information returned by the personsCollection parameter in memory. The personsCollection XML string must conform to the schema definition for friends, as defined in the schema for OSC provider extensibility. For more information about how the OSC uses and updates this information in memory, see Synchronizing Friends and Activities.

See also

Reference

ISocialSession2 : IUnknown

Concepts

Synchronizing Friends and Activities


ISocialSession2::LogonCached

 Copy code hover
[image]

ISocialSession2::LogonCached
See also Send feedback

Published: July 16, 2012

Logs on to the social network site by using cached credentials.

C++
HRESULT _stdcall LogonCached([in] BSTR connectIn, [in] BSTR userName, [in] BSTR password,  [out] BSTR connectOut);

Parameters

connectIn

[in] A string that can be empty or contains the logon credentials, depending on the context in which the OSC is calling LogonCached.

userName

[in] A string that contains the user name.

password

[in] A string that contains the user's password.

connectOut

[out] An opaque string that contains credentials.

Remarks

This method is called for authentication only if useLogonCached is set as true in the capabilities XML returned by ISocialProvider::GetCapabilities.

The Outlook Social Connector (OSC) calls LogonCached, and passes an empty string for connectIn and non-empty userName and password strings. The provider uses userName and password to log on to the social network, and returns an opaque connectOut parameter to the OSC if authentication succeeds. If authentication fails, the provider returns the OSC_E_LOGON_FAILURE error to the OSC.

The connectOut parameter is an opaque string to the OSC, and is passed to the connectIn parameter on subsequent attempts by the OSC to log on to the social network. The provider should place any credentials in the connectOut string that the provider wants the OSC to store across connections. The OSC does not interpret the string in connectOut, and encrypts the string for security purposes before storing it in the Windows registry.

See also

Reference

ISocialSession2 : IUnknown


Outlook Social Connector Provider XML Schema

 Copy code hover
[image]

Outlook Social Connector Provider XML Schema
See also Send feedback

Published: July 16, 2012

All XML that is returned by OSC providers in OSC provider extensibility methods must comply with the following OSC provider XML schema. The OSC schema is reproduced here in its entirety. The current schema definition file, OutlookSocialProvider1_1.xsd, is also provided in the download for the provider templates that accompany this article. For more information, see Outlook Social Connector 2013: Provider templates.

XML Copy code Copy code
<?xml version="1.0" encoding="utf-8"?>
<!--
    XML Schema for Microsoft Outlook Social Connector Provider Extensibility
    Copyright (c) 2009 Microsoft Corporation
    All Rights Reserved
-->
<xs:schema
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd"
    xmlns="http://schemas.microsoft.com/office/outlook/2010/06/socialprovider.xsd"
    elementFormDefault="qualified">

  <!-- Root element for the activity feed -->
  <xs:element name="activityFeed" type="activityFeedType" />

  <!-- Type definition for .\activityFeed  -->
  <xs:complexType name="activityFeedType">
    <xs:sequence>
      <!-- Network where the activity feed items originated (required) -->
      <xs:element name="network"    type="xs:string"  minOccurs="1" maxOccurs="1" />

      <!-- Container for activity feed items (required) -->
      <xs:element name="activities" type="activitiesType" minOccurs="1" maxOccurs="1" />

      <!-- Container for feed item display templates (required) -->
      <xs:element name="templates"  type="templatesType"  minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities -->
  <xs:complexType name="activitiesType">
    <xs:sequence>
      <xs:element name="activityDetails" type="activityDetailsType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails element -->
  <xs:complexType name="activityDetailsType">
    <xs:sequence>
      <!-- Used to denote the user id of the user generating this activity (required) -->
      <xs:element name="ownerID" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote a unique string idenfitifying this activity. Used for duplicate detection (required) -->
      <xs:element name="objectID" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote an activity feed update template, such as a blog post or profile change (required) -->
      <xs:element name="applicationID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote the template type, such as multiple profile change types (required) -->
      <xs:element name="templateID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Date on which this feed item was published (required) -->
      <xs:element name="publishDate" type="xs:dateTime" minOccurs="1" maxOccurs="1" />

      <!-- Used for denoting a status, photo or document related activity feed item (optional) -->
      <xs:element name="type" type="activityTemplateTypeRestrictionType" minOccurs="0" maxOccurs="1" />

      <!-- Variables included with the feed item (required) -->
      <xs:element name="templateVariables" type="templateVariablesType" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails\templateVariables element -->
  <xs:complexType name="templateVariablesType">
    <xs:sequence>
      <xs:element name="templateVariable" type="templateVariableType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails\templateVariables\templateVariable element -->
  <xs:complexType name="templateVariableType">
    <xs:sequence>
      <!-- All activityTemplateType nodes require a Name element to identify the node
           (required for all nodes)  -->
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the Id node value is a unique id of the person or entity
           (required for the Publisher and Entity nodes)  -->
      <xs:element name="id" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the nameHint node value is the name to be displayed in
           the formatted activity  -->
      <xs:element name="nameHint" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the emailAddress node value is the SMTP address associated
           with the person being mentioned in the feed  -->
      <xs:element name="emailAddress" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the profileUrl node value is the URI which points to the
           user's profile page   -->
      <xs:element name="profileUrl" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Link nodes to denote the text the link should display
           (optional for the Link node, if not specified the URI will be used as the display text)  -->
      <xs:element name="text" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Link and Picture nodes to specify the picture location or desired link,
           (required for the Link and Picture nodes)
           Also used by Text nodes to specify a string value for the node -->
      <xs:element name="value" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for the Picture node to denote alternate text for the picture and/or a link where
           the user is taken when they click the picture
           (both elements are optional for the Picture node) -->
      <xs:element name="altText" type="xs:string" minOccurs="0" maxOccurs="1" />
      <xs:element name="href" type="xs:anyURI" minOccurs="0" maxOccurs="1" />

      <!-- Used for the List node as a container of the simpleTemplateVariables, which contain Picture nodes
           (required for the List node)  -->
      <xs:element name="listItems" type="templateListItemsType" minOccurs="0" maxOccurs="1" />

    </xs:sequence>
    <xs:attribute name="type" type="templateTypeRestrictionType" use="required" />
  </xs:complexType>

  <xs:simpleType name="templateTypeRestrictionType">
    <xs:restriction base="xs:string">
      <!-- Denotes the publisher of the feed item -->
      <xs:enumeration value="publisherVariable" />

      <!-- Entities which are not the publisher included with the feed item -->
      <xs:enumeration value="entityVariable" />

      <!-- Links included with the feed item -->
      <xs:enumeration value="linkVariable" />

      <!-- Text included with the feed item -->
      <xs:enumeration value="textVariable" />

      <!-- Picture variables included in ListVariableItem -->
      <xs:enumeration value="pictureVariable" />

      <!-- List to hold pictures included with the feed item
           A list holds a Name node and ListItems node  -->
      <xs:enumeration value="listVariable" />
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="templateListItemsType">
    <xs:sequence>
      <!-- Lists are used to contain a series of pictures, defined as a simpleTemplateVariable
           which is enumerated as a PictureVariable -->
      <xs:element name="simpleTemplateVariable" type="simpleTemplateVariableType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="simpleTemplateVariableType">
    <xs:sequence>
      <!-- The name is used to identify this variable within the feed item template (required) -->
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used for Link nodes to denote the text the link should display
           (optional for the Link node, if not specified the URI will be used
           as the display text) -->
      <xs:element name="text" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- URI of the picture location (required) -->
      <xs:element name="value" type="xs:anyURI" minOccurs="0" maxOccurs="1" />

      <!-- Alternate text for the picture (optional) -->
      <xs:element name="altText" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- The picture can be a link which is specified here (optional) -->
      <xs:element name="href" type="xs:anyURI" minOccurs="0" maxOccurs="1" />
    </xs:sequence>
    <xs:attribute name="type" type="templateSimpleTypeRestrictionType" use="required" />
  </xs:complexType>

  <xs:simpleType name="templateSimpleTypeRestrictionType">
    <xs:restriction base="xs:string">
      <!-- Links included with the feed item -->
      <xs:enumeration value="linkVariable" />

      <!-- Text included with the feed item -->
      <xs:enumeration value="textVariable" />

      <!-- Picture variables included in ListVariableItem -->
      <xs:enumeration value="pictureVariable" />
    </xs:restriction>
  </xs:simpleType>

  <!-- Type definiton for .\activityFeed\templates -->
  <xs:complexType name="templatesType">
    <xs:sequence>
      <!-- Container for template parts -->
      <xs:element name="activityTemplateContainer" type="activityTemplateContainerType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer -->
  <xs:complexType name="activityTemplateContainerType">
    <xs:sequence>
      <!-- Used to denote an activity feed update template, such as a blog post or profile change (required) -->
      <xs:element name="applicationID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote the template type, such as multiple profile change types (required) -->
      <xs:element name="templateID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Template information for displaying activity feed item (required) -->
      <xs:element name="activityTemplate" type="activityTemplateType" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer\activityTemplate -->
  <xs:complexType name="activityTemplateType">
    <xs:sequence>
      <!-- Used for denoting a status, photo or document related activity feed item (optional) -->
      <xs:element name="type" type="activityTemplateTypeRestrictionType" minOccurs="0" maxOccurs="1" />

      <!-- Title used for displaying activity feed item (required) -->
      <xs:element name="title" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Extra information displayed with activity feed item (optional) -->
      <xs:element name="data" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Icon used for displaying activity feed item (required) -->
      <xs:element name="icon" type="xs:anyURI" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer\activityTemplate\type -->
  <!-- Only status, photo and document updates are specially recognized -->
  <xs:simpleType name="activityTemplateTypeRestrictionType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Status Update" />
      <xs:enumeration value="Photo" />
      <xs:enumeration value="Document" />
      <xs:enumeration value="Other" />
    </xs:restriction>
  </xs:simpleType>

  <!-- Type definition for Capabilities-->
  <xs:element name="capabilities">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        Schema for Capabilities
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
    <xs:sequence>
      <!-- Indicates if the network supports get friends call-->
      <xs:element name="getFriends" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network allows storing friends-->
      <!--(contacts) locally as Outlook contact items-->
      <xs:element name="cacheFriends" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports follow this person call-->
      <xs:element name="followPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports do not follow this person call-->
      <xs:element name="doNotFollowPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports get activities call-->
      <xs:element name="getActivities" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports storing activities-->
      <!-- as Outlook RSS items-->
      <xs:element name="cacheActivities" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports dynamic lookup-->
      <!-- of Activities-->
      <xs:element name="dynamicActivitiesLookup" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC displays network url in Acct config-->
      <xs:element name="displayUrl" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the OSC should use Forms Based Authentication (LogonWeb method)-->
      <xs:element name="useLogonWebAuth" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the OSC should hide "Click here to create an account" and-->
      <!-- "Forgot your password?" hyperlinks in the account setup dialog-->
      <xs:element name="hideHyperlinks" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should call the GetAutoConfiguredSession-->
      <!-- function on the ISocialSession object interface to attempt-->
      <!-- autoconfiguration of the network for the user-->
      <xs:element name="supportsAutoConfigure" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Determines the minimum time in minutes between network contact syncs, -->
      <!-- regardless of success -->
      <xs:element name="contactSyncRestartInterval" type="xs:unsignedInt" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the network supports dynamic lookup-->
      <!-- of Activities using hashed SMTP addresses-->
      <xs:element name="dynamicActivitiesLookupEx" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the network supports dynamic lookup-->
      <!-- of Contacts using hashed SMTP addresses-->
      <xs:element name="dynamicContactsLookup" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should call LogonCached on ISocialSession2-->
      <xs:element name="useLogonCached" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should hide the Remember my password check box-->
      <xs:element name="hideRememberMyPassword" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Url opens in the default browser when user clicks create account in Acct config-->
      <xs:element name="createAccountUrl" type="xs:anyURI" minOccurs="0" maxOccurs="1"/>
      <!-- Url opens in the default browser when user clicks forgot pwd in Acct config -->
      <xs:element name="forgotPasswordUrl" type="xs:anyURI" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should sync on-demand activities when people pane is minimized-->
      <xs:element name="showOnDemandActivitiesWhenMinimized" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should sync on-demand contacts when people pane is minimized -->
      <xs:element name="showOnDemandContactsWhenMinimized" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates hashing function used to hash e-mail addresses, ignored unless-->
      <!-- dynamicActivitiesLookupEx = true or dyanamicContactsLookup = true in capabilities XML-->
      <xs:element name="hashFunction" minOccurs="0" maxOccurs="1">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value="SHA1|MD5|CRC32MD5"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <!-- Indicates if the autoconfiguration settings can be changed/overridden by the user or not -->
      <xs:element name="allowChangesToAutoConfigure" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
    </xs:complexType>
  </xs:element>

  <!-- Root element for hashedAddresses list-->
  <xs:element name="hashedAddresses">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        hashedAddresses contains a collection of personAddresses elements
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="personAddresses" minOccurs="0" maxOccurs="unbounded" type="personAddressType">
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <!-- Type definition for personAddressType -->
  <xs:complexType name="personAddressType">
    <xs:annotation>
      <xs:documentation xml:lang ="en">
        personAddressType represents a collection of hashedAddress elements
      </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:annotation>
        <xs:documentation>
          <!-- The hashedAddress element contains the hash of an SMTP address
          The hash is computed based on the hashFunction element in capabilities XML
          Index attribute is an integer counter for each hashedAddress  -->
        </xs:documentation>
      </xs:annotation>
      <xs:element name="hashedAddress" minOccurs="0" maxOccurs="unbounded" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="index" type="xs:int" use ="required" />
  </xs:complexType>

  <!-- Root element for friends list-->
  <xs:element name="friends">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        Friends contains a collection of person elements
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="person" minOccurs="0" maxOccurs="unbounded" type="personType">
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <!-- Root element for friend element-->
  <xs:element name="person" type="personType">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        Top level friend element for being returned via ISocialPerson::GetDetails
      </xs:documentation>
    </xs:annotation>
  </xs:element>

  <!-- Type definition for personType -->
  <xs:complexType name="personType">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        personType represents a person contact in Outlook
      </xs:documentation>
    </xs:annotation>
      <xs:sequence>
        <!-- Network User ID for this person -->
        <xs:element name="userID" type="xs:string" />
        <!-- Person first name or given name -->
        <xs:element name="firstName" minOccurs="0" type="stringType" />
        <!-- Person last name or surname-->
        <xs:element name="lastName" minOccurs="0" type="stringType" />
        <!-- Person full name -->
        <xs:element name="fullName" minOccurs="0" type="stringType" />
        <!-- Person nickname -->
        <xs:element name="nickname" minOccurs="0" type="stringType" />
        <!-- Person fileas name used for FileAs property of Contact item-->
        <xs:element name="fileAs" minOccurs="0" type="stringType" />
        <!-- Company name for the person -->
        <xs:element name="company" minOccurs="0" type="stringType" />
        <!-- Person title -->
        <xs:element name="title" minOccurs="0" type="stringType" />
        <!-- Person's anniversary date -->
        <xs:element name="anniversary" minOccurs="0" type="xs:date" />
        <!-- Person's birthday -->
        <xs:element name="birthday" minOccurs="0" type="xs:date" />
        <!-- Unique SMTP address for the person -->
        <xs:element name="emailAddress" minOccurs="0" type="xs:string" />
        <!-- Email2 SMTP address for the person -->
        <xs:element name="emailAddress2" minOccurs="0" type="xs:string" />
        <!-- Email3 SMTP address for the person -->
        <xs:element name="emailAddress3" minOccurs="0" type="xs:string" />
        <!-- Web profile page for the person -->
        <xs:element name="webProfilePage" minOccurs="0" type="xs:string" />
        <!-- Person's home phone -->
        <xs:element name="phone" minOccurs="0" type="stringType" />
        <!-- Person's cell or mobile phone -->
        <xs:element name="cell" minOccurs="0" type="stringType" />
        <!-- Person's home phone (this element is not used in OSC v1.0) -->
        <xs:element name="homePhone" minOccurs="0" type="stringType" />
        <!-- Person's work phone -->
        <xs:element name="workPhone" minOccurs="0" type="stringType" />
        <!-- Person's address -->
        <xs:element name="address" minOccurs="0" type="stringType" />
        <!-- Person's city -->
        <xs:element name="city" minOccurs="0" type="stringType" />
        <!-- Person's state/province -->
        <xs:element name="state" minOccurs="0" type="stringType" />
        <!-- Person's country/region -->
        <xs:element name="countryOrRegion" minOccurs="0" type="stringType" />
        <!-- Person's zip code -->
        <xs:element name="zip" minOccurs="0" type="stringType" />
        <!-- Person's relationship (this element is not used in OSC v1.0) -->
        <xs:element name="relationship" minOccurs="0" type="stringType" />
        <!-- Creation time of the person's profile on the network -->
        <xs:element name="creationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Last modification time of person's profile on the network -->
        <xs:element name="lastModificationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Expiration time of the person's profile data -->
        <xs:element name="expirationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Gender for this person -->
        <xs:element name="gender" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:pattern value="male|female|unspecified"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <!-- Index must equal index attribute passed to the provider in personAddresses
             Required only when friends XML is returned to ISocialSession2::GetPeopleDetails -->
        <xs:element name ="index" minOccurs="0" type="xs:int" />
        <!-- Url for the person's picture -->
        <xs:element name ="pictureUrl" minOccurs="0" type="xs:string" />
        <!-- Indicates friend status with logged-on user -->
        <xs:element name="friendStatus" minOccurs ="0">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:pattern value="friend|notfriend|pending|pendingin|pendingout"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <!-- Person's business address -->
        <xs:element name="businessAddress" minOccurs="0" type="stringType" />
        <!-- Person's business city -->
        <xs:element name="businessCity" minOccurs="0" type="stringType" />
        <!-- Person's business state/province -->
        <xs:element name="businessState" minOccurs="0" type="stringType" />
        <!-- Person's business country/region -->
        <xs:element name="businessCountryOrRegion" minOccurs="0" type="stringType" />
        <!-- Person's business zip code -->
        <xs:element name="businessZip" minOccurs="0" type="stringType" />
        <!-- Person's other address -->
        <xs:element name="otherAddress" minOccurs="0" type="stringType" />
        <!-- Person's other city -->
        <xs:element name="otherCity" minOccurs="0" type="stringType" />
        <!-- Person's other state/province -->
        <xs:element name="otherState" minOccurs="0" type="stringType" />
        <!-- Person's other country/region -->
        <xs:element name="otherCountryOrRegion" minOccurs="0" type="stringType" />
        <!-- Person's other zip code -->
        <xs:element name="otherZip" minOccurs="0" type="stringType" />
        <!-- Person's personal website -->
        <xs:element name="website" minOccurs="0" type="stringType" />
        <!-- Person's  askmeabout -->
        <xs:element name="askmeabout" minOccurs="0" type="stringType" />
        <!-- Person's personal industries -->
        <xs:element name="industries" minOccurs="0" type="stringType" />
        <!-- Person's personal skills -->
        <xs:element name="skills" minOccurs="0" type="stringType" />
        <!-- Person's personal interests -->
        <xs:element name="interests" minOccurs="0" type="stringType" />
        <!-- Person's personal schools -->
        <xs:element name="schools" minOccurs="0" type="stringType" />
        <!-- Person's location -->
        <xs:element name="location" minOccurs="0" type="stringType" />
      </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="stringType">
    <xs:restriction base="xs:string">
      <xs:maxLength value="1024" />
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

See also

Concepts

Capabilities XML Example
Friends XML Example
Activity Feed XML Example
XML for Capabilities
XML for Friends
XML for Activities
Outlook Social Connector Provider Interfaces


Outlook Social Connector Provider Error Codes

 Copy code hover
[image]

Outlook Social Connector Provider Error Codes
Send feedback

Published: July 16, 2012

Providers should return errors to the caller by using one of the error codes shown in the following table.

Error | Error code (hexadecimal) | Description
OSC_E_AUTH_ERROR | 0x80041404 | Authentication failed on the network of the social network site.
OSC_E_COULDNOTCONNECT | 0x80041402 | No connection is available to connect to the social network site.
OSC_E_FAIL | 0x80004005 | General failure error.
OSC_E_INTERNAL_ERROR | 0x80041400 | An internal error occurred because of an invalid operation.
OSC_E_INVALIDARG (E_INVALIDARG) | 0x80070057 | An invalid argument was passed to a function.
OSC_E_NO_CHANGES | 0x80041406 | No changes have occurred since the last synchronization.
OSC_E_NOT_FOUND | 0x80041405 | A resource cannot be found.
OSC_E_NOT_IMPLEMENTED (E_NOTIMPL) | 0x80004001 | The request to the social network site is valid but has not been implemented by the social network site.
OSC_E_OUT_OF_MEMORY (E_OUTOFMEMORY) | 0x8007000E | An out-of-memory error occurred.
OSC_E_PERMISSION_DENIED | 0x80041403 | The OSC provider denied permission for the resource.
OSC_E_SERVER_VERSION_NOT_SUPPORTED | 0x80041406 | The version of the server to configure the social network account is not supported.
OSC_E_VERSION | 0x80041401 | The provider does not support this version of OSC provider extensibility.

Remarks

Success, warning, and error values are returned by using a 32-bit number that is called a result handle, or HRESULT. An HRESULT is not a handle to anything; it is merely a 32-bit value that has several fields encoded in the value. A positive result indicates success with status, a zero result indicates success without status (S_OK), and a negative result indicates failure.


Extending the Weather Bar in Outlook 2013

 Copy code hover
[image]

Extending the Weather Bar in Outlook 2013
Send feedback

Published: March 5, 2013

Learn how to plug in a third-party weather web service for the Weather Bar in Outlook 2013, to provide weather conditions data for a user-chosen location.

In this article
Weather Bar overview
Weather Bar protocol
Setting the Weather Bar to use a weather service
Dependent conditions
Weather Bar example
Conclusion
Additional resources

Weather Bar overview

The Weather Bar in Outlook displays weather conditions and forecast for a geographic location. A user can choose one or multiple locations, and conveniently see weather data in the Weather Bar in the calendar module. Figure 1 shows the Weather Bar displaying a three-day forecast for New York, NY.

Figure 1. Weather Bar in Outlook

Weather Bar showing forecast for New York.

Settings for the Weather Bar are saved with the user's profile. Depending on the type of Outlook account, the settings may roam with the user on all computers that the user logs on to with the same profile, as in the case of Exchange accounts. Alternatively, the user can customize settings on each computer, as in the case of IMAP/POP accounts.

By default, Outlook uses weather data provided by MSN Weather. The Weather Bar supports third-party weather data web services that follow a defined protocol to communicate with Outlook. As long as a third-party weather data service supports this protocol, users can choose that weather data service to provide weather data in the Weather Bar. This article describes the protocol for third-party weather services to integrate with Outlook in the Weather Bar.

Weather Bar protocol

A user can specify a different weather data service for the Weather Bar, as long as that weather data service implements a web service that supports the following protocol to communicate with Outlook:

  1. The weather data service supports a base URL to a web service. For example, a Contoso Weather web service can have a base URL of http://service.contoso.com/data.aspx.

  2. The web service allows Outlook to append the following parameters to the base URL, to request a location code:

    • outputview=search

      This parameter indicates that the request is a location search.

    • weasearchstr=city

      This parameter indicates the location, city, for which the user wants a weather forecast (for example, London).

    • culture=LCID

      This parameter indicates the culture of the version of Office installed for the user on that computer. The LCID value is defined in [RFC4646] Tags for Identifying Languages

    • src=outlook

      This parameter indicates that Outlook is the client application requesting the service.

    These parameters allow Outlook to take the location that the user is interested in and search for the associated location code as supported by the weather data service. The web service should respond to Outlook with a location code in XML that follows the Outlook Weather Location XML Schema. Figure 2 summarizes the web service request and response for a location code.

    Figure 2. Web service request and response for a location code

    Weather location request and response

  3. The web service also allows Outlook to append the following parameters, to request forecast information for a location code:

    • wealocations=code

      code in this parameter is a location code that Outlook obtains from Step 2, and that maps to the location that the user is interested in.

    • weadegreetype=degreetype

      This parameter specifies whether to use metric or imperial units of measurement for temperature. Specify c for metric, f for imperial for degreetype. This parameter is optional and does not always exist in the web service request.

    • culture=LCID

      This parameter indicates the culture of the version of Office installed for the user on that computer. The LCID value is defined in [RFC4646] Tags for Identifying Languages

    • src=outlook

      This parameter indicates that Outlook is the client application requesting the service.

    These parameters allow Outlook to take the location code returned from Step 2 and request the weather data service for the forecast. The web service should respond to Outlook with the corresponding weather data in XML that follows the Outlook Weather Information XML Schema. Figure 3 summarizes the web service request and response for weather data given a location code.

    Figure 3. Web service request and response for weather information

    Weather information request and response

Setting the Weather Bar to use a weather service

The administrator or power user can use the WeatherServiceUrl registry key to customize the Weather Bar to use a specific weather service. For example, if the base URL for a Contoso weather service is http://service.contoso.com/data.aspx, you can set the WeatherServiceUrl key to that URL.

The following table describes the WeatherServiceUrl key.

Key | HKCU\Software\Microsoft\Office\15.0\Outlook\Options\Calendar
Value name | WeatherServiceUrl
Value type | REG_SZ
Default value | EMPTY_STRING
Description | URL to a weather data service.

Dependent conditions

Outlook 2013 displays the Weather Bar by default. This section describes a few reasons why the Weather Bar might not be visible.

Weather Bar is disabled

First, verify that Show weather on the calendar is selected in the Calendar tab in the Outlook Options dialog box.

Note that an administrator can also use Group Policy to disable the Weather Bar in Outlook 2013 entirely by setting the following key in the Windows registry:

Key | HKCU\Software\Microsoft\Office\15.0\Outlook\Options\Calendar
Value name | DisableWeather
Value type | REG_DWORD
Default value | 0
Description | A value of 0 enables the Weather Bar; any other value disables the Weather Bar.

If the Weather Bar feature has been disabled by Group Policy, the Calendar tab does not include the Show weather on the calendar check box. Consult with the administrator to turn the feature back on.

Office is disconnected from the Internet

Verify that Office is enabled to connect to the Internet—go to the Privacy options tab of the Trust Center in the Backstage view, and ensure that Allow Office to connect to the Internet is selected.

If the user has chosen to not receive updates for Office, the Weather Bar is also disabled.

An administrator can also use Group Policy to disable all online content, including the Weather Bar, by setting the following key in the Windows registry:

Key | HKCU\Software\Microsoft\Office\15.0\Common\Internet
Value name | UseOnlineContent
Value type | REG_DWORD
Default value | 2
Description | A value of 2 enables the Weather Bar; any other value disables the Weather Bar.

If the Weather Bar feature has been disabled by Group Policy, the Calendar tab does not include the Show weather on the calendar check box. Consult with the administrator to turn the feature back on.

Weather Bar example

This section shows an example of a Contoso Weather service that follows the preceding protocol to communicate with Outlook. For any location that the user selects, Outlook first gets a location code for that location from Contoso Weather, then using that location code, calls the Contoso Weather service to get the weather data.

Base URL

Contoso Weather provides the following base URL for their weather data service:

http://service.contoso.com/data.aspx

Getting a location code

Outlook appends the parameters described in Step 2 above to the base URL to obtain the location code for a geographic location city:

http://service.contoso.com/data.aspx?outputview=search&weasearchstr=city

As an example, if the user has selected Tokyo in the Weather Bar, Outlook uses the following URL to obtain the location code for Tokyo from Contoso Weather:

http://weather.service.contoso.com/data.aspx?outputview=search&weasearchstr=tokyo

Contoso Weather responds with the following XML to provide the location code for Tokyo. The XML conforms to the Outlook Weather Location XML Schema. Note that it is common for weather services to return data for more than one location (for example, if the selected location is a greater metropolitan area). In this example, the response for Tokyo includes two locations, each enclosed in a weather element. The corresponding location codes are as follows:

  • wc:JAXX0085 for the weatherlocationname attribute being Tokyo, JPN

  • wc:10038604 for the weatherlocationname attribute being Shinjuku-ku, Tokyo, Japan

XML Copy code Copy code
<?xml version="1.0" ?>
<weatherdata>
  <weather weatherlocationcode="wc:JAXX0085"
    weatherlocationname="Tokyo, JPN">
  </weather>
  <weather weatherlocationcode="wc:10038604"
    weatherlocationname="Shinjuku-ku, JPN">
  </weather>
</weatherdata>

Getting weather information for a location code

After obtaining the location code for a location, Outlook appends the parameters described in Step 3 above to the base URL to obtain weather information for that location code.

http://service.contoso.com/data.aspx?wealocations=code

As an example, if Outlook has obtained the location code wc:JAXX0085 from Contoso Weather for Tokyo, Outlook uses this location code in the following URL to get the weather information.

http://service.contoso.com/data.aspx?wealocations=wc:JAXX0085

Contoso Weather responds with the following XML to provide the weather information for the location code for Tokyo. The XML conforms to the Outlook Weather Information XML Schema.

XML Copy code Copy code
<?xml version="1.0"?>
<weatherdata>
  <weather timezone="9" attribution="Data provided by Trey Research"
    degreetype="F" imagerelativeurl="http://contoso.com/images/en-us/"
    url="http://contoso.com/weather.aspx?eid=33568&q=Tokyo-JPN"
    weatherlocationname="Tokyo, JPN"
    weatherlocationcode="wc:JAXX0085">
      <current winddisplay="9 mph NNW" windspeed="9" humidity="90" feelslike="44"
        observationpoint="Tokyo" observationtime="06:00:00"
        shortday="Sat" day="Saturday" date="2012-04-14" skytext="Rain" skycode="11"
        temperature="48"/>
      <forecast shortday="Sat" day="Saturday" date="2012-04-14" precip="95" skytextday="Rain"
        skycodeday="11" high="55" low="47"/>
      <forecast shortday="Sun" day="Sunday" date="2012-04-15" precip="5" skytextday="Partly Cloudy"
        skycodeday="30" high="65" low="43"/>
      <forecast shortday="Mon" day="Monday" date="2012-04-16" precip="5" skytextday="Partly Cloudy"
        skycodeday="30" high="64" low="52"/>
      <forecast shortday="Tue" day="Tuesday" date="2012-04-17" precip="70" skytextday="Showers / Clear"
        skycodeday="39" high="66" low="53"/>
      <forecast shortday="Wed" day="Wednesday" date="2012-04-18" precip="55" skytextday="Showers / Clear"
        skycodeday="39" high="68" low="51"/>
  </weather>
</weatherdata>

Resetting Outlook to use MSN Weather

Even though Outlook uses MSN Weather by default, if a user has customized the Weather Bar to use a different weather service and subsequently wants to use MSN Weather again, the user can simply delete the WeatherServiceUrl key in the Windows Registry. Deleting that registry key resets Outlook to use MSN Weather.

Conclusion

The Weather Bar in the Outlook calendar uses MSN Weather by default to provide the weather forecast for a specified location. Users can conveniently see weather information for the locations they care about. Third-party weather data services can also integrate with the Weather Bar by supporting the Outlook Weather Location XML Schema and Outlook Weather Information XML Schema and following a simple web service protocol with Outlook.

Additional resources

  • Outlook Weather Location XML Schema

  • Outlook Weather Information XML Schema


Outlook Weather Information XML Schema

 Copy code hover
[image]

Outlook Weather Information XML Schema
Send feedback

This section contains the Outlook 2013 schema reference for the Outlook Weather Information XML Schema. This schema enables weather service providers to send weather forecast information for a specified location as a web service response to Outlook, so that Outlook can display the information in the Weather Bar.

In this section

  • Schema map (Outlook Weather Information Schema)

  • Elements (Outlook Weather Information Schema)

  • Types (Outlook Weather Information Schema)

Related sections

Extending the Weather Bar in Outlook 2013


Schema map (Outlook Weather Information Schema)

 Copy code hover
[image]

Schema map (Outlook Weather Information Schema)
Send feedback

This topic shows the schema definition for the Outlook Weather Information XML Schema.

XML Copy code Copy code
<?xml version="1.0" ?>
<xs:schema
  attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd"
xmlns="http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd"
>
  <!-- get weather info  -->
  <!-- http://weather.service.msn.com/data.aspx?src=vista&weadegreetype=C&culture=en-US&wealocations=wc:10109953 -->

  <xs:element name="weatherdata">
    <xs:annotation>
      <xs:documentation>Defines the weather element.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="weather" type="weatherType">
          <xs:annotation>
            <xs:documentation>Specifies the weather conditions of a location.</xs:documentation>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="weatherType">
    <xs:annotation>
      <xs:documentation>Specifies the weather conditions of a location.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="current" type="currentType">
        <xs:annotation>
          <xs:documentation>Specifies the current weather conditions.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="forecast" type="forecastType" minOccurs="3" maxOccurs="unbounded">
        <xs:annotation>
          <xs:documentation>Specifies the future weather conditions of at least three days ahead including today: Today, Tomorrow, Day after Tomorrow.</xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>

    <xs:attribute name="weatherlocationcode" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the code that is associated with the location used to distinguish multiple location that have the same name. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="timezone" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the GMT offset.</xs:documentation>
      </xs:annotation>
      <xs:simpleType>
        <xs:restriction base="xs:integer">
          <xs:minInclusive value="-11"/>
          <xs:maxInclusive value="12"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="attribution" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the source of the weather information.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="degreetype" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the unit for the temperature of the location for example, Celsius.</xs:documentation>
      </xs:annotation>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value='C'/>
          <xs:enumeration value='F'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="imagerelativeurl" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the URL of the image for the location.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="url" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the URL for the web page of the weather service that contains weather information for the specified location.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="weatherlocationname" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the name of the location that appears in the drop-down control.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name="currentType">
    <xs:annotation>
      <xs:documentation> Defines the parameters about the current weather conditions of a location.</xs:documentation>
    </xs:annotation>

    <xs:attribute name="winddisplay" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>A string that describes the current wind conditions. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="windspeed" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the current numerical wind speed value.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="humidity" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the current numerical humidity value.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="feelslike" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the temperature of how the current weather feels like.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="observationpoint" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies where the current weather information is observed from.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="observationtime" type="xs:time" use="required">
      <xs:annotation>
        <xs:documentation>Specifies when the current weather information is observed at.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="date" type="xs:date" use="required">
      <xs:annotation>
        <xs:documentation>Specifies today's date.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="skytext" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies one to two words describing current weather conditions.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="skycode" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies an integer code for the current weather conditions. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="temperature" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the current temperature of the location.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="shortday" type="xs:string" use="optional">
      <xs:annotation>
        <xs:documentation>Specifies a day in abbreviated form.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="day" type="xs:string" use="optional">
      <xs:annotation>
        <xs:documentation>Specifies a day for the forecast.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name="forecastType">
    <xs:annotation>
      <xs:documentation> Defines the parameters about the forecast weather conditions of a location.</xs:documentation>
    </xs:annotation>

    <xs:attribute name="shortday" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies a day in abbreviated form.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="day" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies a day for the forecast. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="date" type="xs:date" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the date for the forecast. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="precip" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the percentage possibility of precipitation. </xs:documentation>
      </xs:annotation>
    </xs:attribute>

    <xs:attribute name="skytextday" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies one to two words that describe the forecasted conditions. </xs:documentation>
      </xs:annotation>
    </xs:attribute>

    <xs:attribute name="skycodeday" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies a code for the forecasted conditions. </xs:documentation>
      </xs:annotation>
    </xs:attribute>

    <xs:attribute name="high" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the forecasted highest temperature. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="low" type="xs:integer" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the forecasted lowest temperature. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
</xs:schema>


Elements (Outlook Weather Information Schema)

 Copy code hover
[image]

Elements (Outlook Weather Information Schema)
Send feedback

This topic lists the elements in the Outlook Weather Information XML schema.

  • current element

  • forecast element

  • weather element

  • weatherdata element


current element (weatherType complexType) (Outlook Weather Information Schema)

 Copy code hover
[image]

current element (weatherType complexType) (Outlook Weather Information Schema)
Send feedback

Specifies the current weather conditions.

Element information

Element type | currentType
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd

Definition

XML Copy code Copy code
<xs:element name="current"      type="currentType">

  </xs:element>

Elements and attributes

Parent elements

Element | Type | Description
weather | weatherType | Specifies the weather conditions of a location.

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
date | xs:date | required | Specifies today's date. | A value of the type xs:date
day | xs:string | optional | Specifies a day for the forecast. | A value of the type xs:string
feelslike | xs:integer | required | Specifies the temperature of how the current weather feels like. | A value of the type xs:integer
humidity | xs:integer | required | Specifies the current numerical humidity value. | A value of the type xs:integer
observationpoint | xs:string | required | Specifies where the current weather information is observed from. | A value of the type xs:string
observationtime | xs:time | required | Specifies when the current weather information is observed at. | A value of the type xs:time
shortday | xs:string | optional | Specifies a day in abbreviated form. | A value of the type xs:string
skycode | xs:integer | required | Specifies an integer code for the current weather conditions. | A value of the type xs:integer
skytext | xs:string | required | Specifies one to two words describing current weather conditions. | A value of the type xs:string
temperature | xs:integer | required | Specifies the current temperature of the location. | A value of the type xs:integer
winddisplay | xs:string | required | A string that describes the current wind conditions. | A value of the type xs:string
windspeed | xs:integer | required | Specifies the current numerical wind speed value. | A value of the type xs:integer


forecast element (weatherType complexType) (Outlook Weather Information Schema)

 Copy code hover
[image]

forecast element (weatherType complexType) (Outlook Weather Information Schema)
Send feedback

Specifies the future weather conditions of at least three days ahead including today: Today, Tomorrow, Day after Tomorrow.

Element information

Element type | forecastType
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd

Definition

XML Copy code Copy code
<xs:element name="forecast"      type="forecastType" minOccurs="3"     maxOccurs="unbounded"    >

  </xs:element>

Elements and attributes

Parent elements

Element | Type | Description
weather | weatherType | Specifies the weather conditions of a location.

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
date | xs:date | required | Specifies the date for the forecast. | A value of the type xs:date
day | xs:string | required | Specifies a day for the forecast. | A value of the type xs:string
high | xs:integer | required | Specifies the forecasted highest temperature. | A value of the type xs:integer
low | xs:integer | required | Specifies the forecasted lowest temperature. | A value of the type xs:integer
precip | xs:integer | required | Specifies the percentage possibility of precipitation. | A value of the type xs:integer
shortday | xs:string | required | Specifies a day in abbreviated form. | A value of the type xs:string
skycodeday | xs:integer | required | Specifies a code for the forecasted conditions. | A value of the type xs:integer
skytextday | xs:string | required | Specifies one to two words that describe the forecasted conditions. | A value of the type xs:string


weather element (weatherdata element) (Outlook Weather Information Schema)

 Copy code hover
[image]

weather element (weatherdata element) (Outlook Weather Information Schema)
Send feedback

Specifies the weather conditions of a location.

Element information

Element type | weatherType
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd

Definition

XML Copy code Copy code
<xs:element name="weather"      type="weatherType">

  </xs:element>

Elements and attributes

Parent elements

Element | Type | Description
weatherdata |  | Defines the weather element.

Child elements

Element | Type | Description
current | currentType | Specifies the current weather conditions.
forecast | forecastType | Specifies the future weather conditions of at least three days ahead including today: Today, Tomorrow, Day after Tomorrow.

Attributes

Attribute | Type | Required | Description | Possible values
attribution | xs:string | required | Specifies the source of the weather information. | A value of the type xs:string
degreetype | xs:string | required | Specifies the unit for the temperature of the location for example, Celsius. | C, F
imagerelativeurl | xs:string | required | Specifies the URL of the image for the location. | A value of the type xs:string
timezone | xs:integer | required | Specifies the GMT offset. | A value between -11 and 12 inclusive
url | xs:string | required | Specifies the URL for the web page of the weather service that contains weather information for the specified location. | A value of the type xs:string
weatherlocationcode | xs:string | required | Specifies the code that is associated with the location used to distinguish multiple location that have the same name. | A value of the type xs:string
weatherlocationname | xs:string | required | Specifies the name of the location that appears in the drop-down control. | A value of the type xs:string


weatherdata element (Outlook Weather Information Schema)

 Copy code hover
[image]

weatherdata element (Outlook Weather Information Schema)
Send feedback

Defines the weather element.

Element information

Element type |
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd

Definition

XML Copy code Copy code
    <xs:element name="weatherdata"
    >
          <xs:complexType>
          <xs:sequence>
    <xs:element name="weather"
     type="weatherType">
    </xs:element>

      </xs:sequence>
      </xs:complexType>
    </xs:element>

Elements and attributes

Parent elements

None.

Child elements

Element | Type | Description
weather | weatherType | Specifies the weather conditions of a location.

Attributes

None.


Types (Outlook Weather Information Schema)

 Copy code hover
[image]

Types (Outlook Weather Information Schema)
Send feedback

This topic lists the types in the Outlook Weather Information XML schema.

  • currentType complexType

  • forecastType complexType

  • weatherType complexType


currentType complexType (Outlook Weather Information Schema)

 Copy code hover
[image]

currentType complexType (Outlook Weather Information Schema)
Send feedback

Defines the parameters about the current weather conditions of a location.

Type information

Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd
Extension base | None

Definition

XML Copy code Copy code

       <xs:complexType name="currentType">
     <xs:attribute name="winddisplay"   type="xs:string"      use="required"     />
     <xs:attribute name="windspeed"   type="xs:integer"      use="required"     />
     <xs:attribute name="humidity"   type="xs:integer"      use="required"     />
     <xs:attribute name="feelslike"   type="xs:integer"      use="required"     />
     <xs:attribute name="observationpoint"   type="xs:string"      use="required"     />
     <xs:attribute name="observationtime"   type="xs:time"      use="required"     />
     <xs:attribute name="date"   type="xs:date"      use="required"     />
     <xs:attribute name="skytext"   type="xs:string"      use="required"     />
     <xs:attribute name="skycode"   type="xs:integer"      use="required"     />
     <xs:attribute name="temperature"   type="xs:integer"      use="required"     />
     <xs:attribute name="shortday"   type="xs:string"      use="optional"     />
     <xs:attribute name="day"   type="xs:string"      use="optional"     />
       </xs:complexType>

Elements and attributes

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
date | xs:date | required | Specifies today's date. | A value of the type xs:date
day | xs:string | optional | Specifies a day for the forecast. | A value of the type xs:string
feelslike | xs:integer | required | Specifies the temperature of how the current weather feels like. | A value of the type xs:integer
humidity | xs:integer | required | Specifies the current numerical humidity value. | A value of the type xs:integer
observationpoint | xs:string | required | Specifies where the current weather information is observed from. | A value of the type xs:string
observationtime | xs:time | required | Specifies when the current weather information is observed at. | A value of the type xs:time
shortday | xs:string | optional | Specifies a day in abbreviated form. | A value of the type xs:string
skycode | xs:integer | required | Specifies an integer code for the current weather conditions. | A value of the type xs:integer
skytext | xs:string | required | Specifies one to two words describing current weather conditions. | A value of the type xs:string
temperature | xs:integer | required | Specifies the current temperature of the location. | A value of the type xs:integer
winddisplay | xs:string | required | A string that describes the current wind conditions. | A value of the type xs:string
windspeed | xs:integer | required | Specifies the current numerical wind speed value. | A value of the type xs:integer


forecastType complexType (Outlook Weather Information Schema)

 Copy code hover
[image]

forecastType complexType (Outlook Weather Information Schema)
Send feedback

Defines the parameters about the forecast weather conditions of a location.

Type information

Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd
Extension base | None

Definition

XML Copy code Copy code

       <xs:complexType name="forecastType">
     <xs:attribute name="shortday"   type="xs:string"      use="required"     />
     <xs:attribute name="day"   type="xs:string"      use="required"     />
     <xs:attribute name="date"   type="xs:date"      use="required"     />
     <xs:attribute name="precip"   type="xs:integer"      use="required"     />
     <xs:attribute name="skytextday"   type="xs:string"      use="required"     />
     <xs:attribute name="skycodeday"   type="xs:integer"      use="required"     />
     <xs:attribute name="high"   type="xs:integer"      use="required"     />
     <xs:attribute name="low"   type="xs:integer"      use="required"     />
       </xs:complexType>

Elements and attributes

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
date | xs:date | required | Specifies the date for the forecast. | A value of the type xs:date
day | xs:string | required | Specifies a day for the forecast. | A value of the type xs:string
high | xs:integer | required | Specifies the forecasted highest temperature. | A value of the type xs:integer
low | xs:integer | required | Specifies the forecasted lowest temperature. | A value of the type xs:integer
precip | xs:integer | required | Specifies the percentage possibility of precipitation. | A value of the type xs:integer
shortday | xs:string | required | Specifies a day in abbreviated form. | A value of the type xs:string
skycodeday | xs:integer | required | Specifies a code for the forecasted conditions. | A value of the type xs:integer
skytextday | xs:string | required | Specifies one to two words that describe the forecasted conditions. | A value of the type xs:string


weatherType complexType (Outlook Weather Information Schema)

 Copy code hover
[image]

weatherType complexType (Outlook Weather Information Schema)
Send feedback

Specifies the weather conditions of a location.

Type information

Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherinfo.xsd
Schema file | getweatherinfo.xsd
Extension base | None

Definition

XML Copy code Copy code

           <xs:complexType name="weatherType">
           <xs:sequence>
     <xs:element name="current"      type="currentType">

  </xs:element>
     <xs:element name="forecast"      type="forecastType" minOccurs="3"     maxOccurs="unbounded"    >

  </xs:element>
       </xs:sequence>
     <xs:attribute name="weatherlocationcode"   type="xs:string"      use="required"     />
     <xs:attribute name="timezone"   type="xs:integer"      use="required"     />
     <xs:attribute name="attribution"   type="xs:string"      use="required"     />
     <xs:attribute name="degreetype"   type="xs:string"      use="required"     />
     <xs:attribute name="imagerelativeurl"   type="xs:string"      use="required"     />
     <xs:attribute name="url"   type="xs:string"      use="required"     />
     <xs:attribute name="weatherlocationname"   type="xs:string"      use="required"     />
       </xs:complexType>

Elements and attributes

Child elements

Element | Type | Description
current | currentType | Specifies the current weather conditions.
forecast | forecastType | Specifies the future weather conditions of at least three days ahead including today: Today, Tomorrow, Day after Tomorrow.

Attributes

Attribute | Type | Required | Description | Possible values
attribution | xs:string | required | Specifies the source of the weather information. | A value of the type xs:string
degreetype | xs:string | required | Specifies the unit for the temperature of the location for example, Celsius. | C, F
imagerelativeurl | xs:string | required | Specifies the URL of the image for the location. | A value of the type xs:string
timezone | xs:integer | required | Specifies the GMT offset. | A value between -11 and 12 inclusive
url | xs:string | required | Specifies the URL for the web page of the weather service that contains weather information for the specified location. | A value of the type xs:string
weatherlocationcode | xs:string | required | Specifies the code that is associated with the location used to distinguish multiple location that have the same name. | A value of the type xs:string
weatherlocationname | xs:string | required | Specifies the name of the location that appears in the drop-down control. | A value of the type xs:string


Outlook Weather Location XML Schema

 Copy code hover
[image]

Outlook Weather Location XML Schema
Send feedback

This section contains the Outlook 2013 schema reference for the Outlook Weather Location XML Schema. This schema enables weather service providers to respond to an Outlook web service request for a location code. The location code should correspond to the location for which a user is requesting weather information in the Weather Bar.

In this section

  • Schema map (Outlook Weather Location Schema)

  • Elements (Outlook Weather Location Schema)

  • Types (Outlook Weather Location Schema)

Related sections

Extending the Weather Bar in Outlook 2013


Schema map (Outlook Weather Location Schema)

 Copy code hover
[image]

Schema map (Outlook Weather Location Schema)
Send feedback

This topic shows the schema definition for the Outlook Weather Location XML Schema.

XML Copy code Copy code
<?xml version="1.0" ?>
<xs:schema
  attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace= "http://schemas.microsoft.com/office/outlook/15/getweatherlocation.xsd"
xmlns="http://schemas.microsoft.com/office/outlook/15/getweatherlocation.xsd"
>
  <!-- get weather location  -->
  <!-- example query: http://weather.service.msn.com/data.aspx?outputview=search&weasearchstr=tsurumi -->

  <xs:element name="weatherdata">
    <xs:annotation>
      <xs:documentation>Defines the weather element.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="weather" type="weatherType" maxOccurs="unbounded">
          <xs:annotation>
            <xs:documentation>Specifies the location to report weather on.</xs:documentation>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="weatherType">
    <xs:annotation>
      <xs:documentation> Defines the parameters about the weather conditions of a location.</xs:documentation>
    </xs:annotation>

    <xs:attribute name="weatherlocationname" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies the name of the location.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="weatherlocationcode" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>Specifies a code that is associated with the location to distinguish multiple locations with the same name. </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
</xs:schema>


Elements (Outlook Weather Location Schema)

 Copy code hover
[image]

Elements (Outlook Weather Location Schema)
Send feedback

This topic lists the elements in the Outlook Weather Location XML schema.

  • weather element

  • weatherdata element


weather element (weatherdata element) (Outlook Weather Location Schema)

 Copy code hover
[image]

weather element (weatherdata element) (Outlook Weather Location Schema)
Send feedback

Specifies the location to report weather on.

Element information

Element type | weatherType
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherlocation.xsd
Schema file | getweatherlocation.xsd

Definition

XML Copy code Copy code
<xs:element name="weather"      type="weatherType" maxOccurs="unbounded"    >

  </xs:element>

Elements and attributes

Parent elements

Element | Type | Description
weatherdata |  | Defines the weather element.

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
weatherlocationcode | xs:string | required | Specifies a code that is associated with the location to distinguish multiple locations with the same name. | A value of the type xs:string
weatherlocationname | xs:string | required | Specifies the name of the location. | A value of the type xs:string


weatherdata element (Outlook Weather Location Schema)

 Copy code hover
[image]

weatherdata element (Outlook Weather Location Schema)
Send feedback

Defines the weather element.

Element information

Element type |
Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherlocation.xsd
Schema file | getweatherlocation.xsd

Definition

XML Copy code Copy code
    <xs:element name="weatherdata"
    >
          <xs:complexType>
          <xs:sequence>
    <xs:element name="weather"
     type="weatherType" maxOccurs="unbounded"
      >
    </xs:element>

      </xs:sequence>
      </xs:complexType>
    </xs:element>

Elements and attributes

Parent elements

None.

Child elements

Element | Type | Description
weather | weatherType | Specifies the location to report weather on.

Attributes

None.


Types (Outlook Weather Location Schema)

 Copy code hover
[image]

Types (Outlook Weather Location Schema)
Send feedback

This topic lists the types in Outlook Weather Location XML schema.

  • weatherType complexType


weatherType complexType (Outlook Weather Location Schema)

 Copy code hover
[image]

weatherType complexType (Outlook Weather Location Schema)
Send feedback

Defines the parameters about the weather conditions of a location.

Type information

Namespace | http://schemas.microsoft.com/office/outlook/15/getweatherlocation.xsd
Schema file | getweatherlocation.xsd
Extension base | None

Definition

XML Copy code Copy code

       <xs:complexType name="weatherType">
     <xs:attribute name="weatherlocationname"   type="xs:string"      use="required"     />
     <xs:attribute name="weatherlocationcode"   type="xs:string"      use="required"     />
       </xs:complexType>

Elements and attributes

Child elements

None.

Attributes

Attribute | Type | Required | Description | Possible values
weatherlocationcode | xs:string | required | Specifies a code that is associated with the location to distinguish multiple locations with the same name. | A value of the type xs:string
weatherlocationname | xs:string | required | Specifies the name of the location. | A value of the type xs:string


Welcome to the Outlook 2013 Auxiliary Reference

 Copy code hover
[image]

Welcome to the Outlook 2013 Auxiliary Reference
Send feedback

Published: July 23, 2013

This reference contains conceptual, reference, and code sample topics to guide you in developing solutions by using Outlook 2013 APIs that are exposed outside of the Outlook object model.

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs.

For a list of new features and changes that were added to this release, see What's new in this edition. For a general overview of this reference, see Getting started.

Additional resources

  • Outlook 2010 Auxiliary Reference Copyright Notice

  • Outlook Developer Center

  • Accessibility in Microsoft Products

  • Document Conventions

  • Microsoft Online Privacy Notice


Getting started (Outlook 2013 auxiliary reference)

 Copy code hover
[image]

Getting started (Outlook 2013 auxiliary reference)
Send feedback

The Outlook 2013 Auxiliary Reference contains conceptual content and reference documentation for four sets of APIs, code samples, and a redistributable installer that allow developers to extend and integrate with Outlook 2013. APIs in this reference are exposed by Outlook for extensibility, outside of the Outlook object model.

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs. For specific information about the Outlook object model, see the Outlook 2013 Developer Reference. For specific information on Messaging API (MAPI) supported by Outlook, see the Outlook 2013 MAPI Reference.

The conceptual discussion includes the following subjects:

  • About anti-spam settings

  • Managing message downloads for POP3 accounts

  • Locating the message download history for a POP3 account

  • Parsing the message download history for a POP3 account

  • About conflict resolution for custom item types

  • About the last update time of an Offline Address Book

  • About registering a new domain for automatic configuration

  • About meeting requests as informational updates and full updates

  • About rebasing calendars programmatically for Daylight Saving Time (There is also a redistributable installer for third-party calendar rebasing tools, which works for previous versions of Outlook as well, since Outlook 2010. To download the installer, see Outlook 2010: Auxiliary Reference Redistributable Installer and Header File for Rebasing Calendars.)

  • About persisting TZDEFINITION to a stream to commit to a binary property

The reference content includes the following:

  • The APIs Exported by Outlook include functions and data structures that were originally implemented for internal use and are now exposed for public use.

  • The Account Management API provides access to user account information and notifications of account changes.

  • The Data Degradation Layer API supports clients that access an Outlook item in a preferred character format rather than the object's native character format.

  • The Free/Busy API provides free/busy status information about specific user accounts within a specific time range.

  • Sample how-to tasks in the Outlook 2013 Auxiliary Reference include the following:

    • How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)

    • How to: Parse a stream from a binary property to read the TZDEFINITION structure

    • How to: Parse a stream from a binary property to read the TZREG structure

    • How to: Read time zone properties from an appointment

    • How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)

    • How to: Use relative time to access free/busy data

The reference for each API lists the constants, type definitions, and interfaces that a developer must implement to use the additional functionality.

Note Note

Developers must implement these APIs only as documented in this reference. Certain interface members and method parameters are named as placeholders because they are reserved for the internal use of Outlook and are subject to change without notice.


What's new in this edition (Outlook 2013 Auxiliary Reference)

 Copy code hover
[image]

What's new in this edition (Outlook 2013 Auxiliary Reference)
Send feedback

This topic describes what is new in the current edition of the Outlook 2013 Auxiliary Reference.

Account Management API

The following table lists the additions to the Account Management API in this release.

Feature area | Description | Related topics
Account management | Managing downloads of messages for POP3 accounts. | Managing message downloads for POP3 accounts Locating the message download history for a POP3 account Parsing the message download history for a POP3 account PROP_ACCT_MINI_UID PROP_INET_PASSWORD PROP_INET_PORT PROP_INET_SERVER PROP_INET_SSL PROP_INET_USE_SPA PROP_INET_USER PROP_POP_LEAVE_ON_SERVER PROP_SMTP_AUTH_METHOD PROP_SMTP_PASSWORD PROP_SMTP_PORT PROP_SMTP_SECURE_CONNECTION PROP_SMTP_SERVER PROP_SMTP_SSL PROP_SMTP_USE_AUTH PROP_SMTP_USE_SPA PROP_SMTP_USER
Account management | Gets the ACCT_BIN structure that contains the UID of the Exchange account. | PROP_MAPI_EMSMDB_UID

Outlook Exported API

The following table lists the additions to the Outlook Exported API.

Feature area | Description | Related topics
Listening to the before print event for Outlook | Use the dispidBeforePrint dispatch ID to listen to and handle this application-level event that fires before a printing operation. | Available events and their dispids (Outlook exported APIs)
Listening to the read complete event for an item | Use the dispidEventReadComplete dispatch ID to listen to and handle this item-level event that fires when Outlook has completed reading the properties of the item. | Available events and their dispids (Outlook exported APIs)


Concepts (Outlook 2013 auxiliary reference)

 Copy code hover
[image]

Concepts (Outlook 2013 auxiliary reference)
Send feedback

This section describes the four APIs in the Outlook 2013 Auxiliary Reference and provides sample tasks that use those APIs.

In This Section

  • Outlook account management

  • About the Data Degradation Layer API

  • About APIs exported by Outlook

  • Outlook configuration

  • Outlook calendars and appointments

  • Sample tasks


Outlook account management

 Copy code hover
[image]

Outlook account management
Send feedback

This section describes the Account Management API which provides access to account information and supports account-change notifications. It also includes information about protecting accounts from spam and managing message downloads for POP3 accounts.

In This Section

  • About the Account Management API

  • About anti-spam settings

  • Managing message downloads for POP3 accounts


About the Account Management API

 Copy code hover
[image]

About the Account Management API
Send feedback

The Account Management API provides access to account information and supports notifications of account changes. As clients of this API, mail providers do the following:

  1. Use IOlkAccountManager to manage access to accounts and set up notifications about account changes.

  2. Implement and use IOlkAccountNotify to send notifications about account changes.

  3. Use IOlkEnum to enumerate accounts.

  4. Use IOlkAccount to get and set properties and other information about an account. Clients obtain this interface through IOlkAccountManager::FindAccount or IOlkEnum::GetNext to access an individual account.

  5. Implement and use IOlkAccountHelper to provide the account manager helper functionality, including getting an account's profile name and the current MAPI session.

  6. Implement and use IOlkErrorUnknown to provide extra information about an error in IOlkAccountManager, IOlkAccountNotify, and IOlkAccount.

The Account Management API provides the following definitions, data types, interfaces, named properties, and properties.

Definitions:

  • Constants (Account management API)

Data types:

  • ACCT_BIN

  • ACCT_VARIANT

Interfaces:

  • IOlkAccount

  • IOlkAccountHelper

  • IOlkAccountManager

  • IOlkAccountNotify

  • IOlkEnum

  • IOlkErrorUnknown

Named properties:

  • PidLidInternetAccountName

  • PidLidInternetAccountStamp

Properties:

  • PidTagNextSendAcct

  • PidTagPrimarySendAccount

  • PROP_ACCT_DELIVERY_FOLDER

  • PROP_ACCT_DELIVERY_STORE

  • PROP_ACCT_ID

  • PROP_ACCT_IS_EXCH

  • PROP_ACCT_NAME

  • PROP_ACCT_PREFERENCES_UID

  • PROP_ACCT_SEND_STAMP

  • PROP_ACCT_SENTITEMS_EID

  • PROP_ACCT_STAMP

  • PROP_ACCT_USER_EMAIL_ADDR

  • PROP_ACCT_USER_DISPLAY_NAME

  • PROP_MAPI_EMSMDB_UID

  • PROP_MAPI_IDENTITY_ENTRYID

  • PROP_MAPI_TRANSPORT_FLAGS


About anti-spam settings

 Copy code hover
[image]

About anti-spam settings
See also Send feedback

Outlook allows users to specify settings for each account to help protect the account from spam. Such anti-spam settings are stored in a section designated for that account in the user's profile. Use the PROP_ACCT_PREFERENCES_UID property to obtain the unique ID (UID) for the section in the profile that stores the user's preferences for this account, including the anti-spam settings.

Use the following properties to obtain anti-spam settings for the account:

  • PidTagSpamJunkSenders—Specifies a semicolon-delimited list of email addresses and domains that the user has specified as blocked senders for the account.

  • PidTagSpamThreshold—Specifies the level of spam-filtering that the user has specified for the account. The following table shows the supported values.

    Supported value

    Definition

    None

    0xFFFFFFFF

    Low

    0x00000006

    Medium

    0x00000005

    High

    0x00000003

  • PidTagSpamTrustedRecipients—Specifies a semicolon-delimited list of email addresses and domains that the user has specified as trusted recipients for the account.

  • PidTagSpamTrustedSenders—Specifies a semicolon-delimited list of email addresses and domains that the user has specified as trusted senders for the account.

See also

Concepts

About the Account Management API

Other resources

Add names to the Junk E-mail Filter lists


Managing message downloads for POP3 accounts

 Copy code hover
[image]

Managing message downloads for POP3 accounts
Send feedback

This section describes how the POP3 provider of Outlook uses the Unique ID Listing (UIDL) history on a POP3 account to identify messages that the provider has downloaded or deleted from the POP3 server, to avoid downloading the same message more than once.

Introduction to POP

The Post Office Protocol (POP) specifies an application layer protocol for an email client such as Outlook to download email messages from a mail server. It allows a user to download a copy of an email message to a local device (such as a smart phone or computer), and either leave a copy on the server or delete it. The protocol supports only one mail client to be connected to the mailbox at one time. It specifies only how to retrieve but not send email messages from the mail server. When using POP, a mail client typically has to check for new email messages, connects to the mail server for only the amount of time it takes to download new messages, and does not stay connected to the server to get new mail notifications. POP supports only email messages but not other item types such as contacts and appointments unless they are encapsulated in an email. POP3 is version 3 of the protocol.

Messages for a POP account are identified by unique identifiers (UIDs). An email client that leaves mail on the server uses the UIDL command to retrieve the UIDL map that associates each message that has been delivered to the mailbox to its UID. The client also gets the UIDL history for messages that have been downloaded or deleted for the Inbox on that client. Based on the UIDL history, the client can determine which messages are new and should be downloaded.

In this section

  • Locating the message download history for a POP3 account

    This topic describes how a mail client accesses the PidTagAttachDataBinary property to get the UIDL history for messages in the client Inbox of a POP3 account.

  • Parsing the message download history for a POP3 account

    This topic describes how to parse the POP3 BLOB that represents the UIDL history for messages in the client Inbox of a POP3 account, to identify the messages that have been downloaded or deleted on that account.

Additional resources

  • Outlook account management

  • Locating the message download history for a POP3 account

  • Parsing the message download history for a POP3 account

  • PROP_POP_LEAVE_ON_SERVER

  • Constants (Account management API)

  • Properties (Account management API)


Locating the message download history for a POP3 account

 Copy code hover
[image]

Locating the message download history for a POP3 account
Send feedback

This topic describes how a mail client can access the PidTagAttachDataBinary property to get the message download history for a POP3 account.

In this article
Why get the message download history?
Find the appropriate hidden message
Find the appropriate attachment of the hidden message
Access the PidTagAttachDataBinary property of the message attachment
Next steps
Additional resources

Why get the message download history?

The Post Office Protocol (POP) provider for Outlook allows users to retrieve and download new email messages on their local device, and subsequently to leave or delete these email messages on the mail server. When the mail client checks for new messages to download, it has to be able to identify and download only the new messages for that Inbox. The mail client does this by first using the UIDL (Unique ID Listing) command, which obtains a map of each message that has ever been delivered to that Inbox to a unique identifier (UID). The client also gets the message download history for messages that have been downloaded or deleted for the Inbox on that client. Using the message UID map and download history, the client can then identify those messages that are absent in the history as new and, hence, should be downloaded.

To get the message download history for an Inbox:

  • Follow the steps in this topic to find the PidTagAttachDataBinary property, which contains the history in a binary large object (BLOB) that follows a specific format.

  • Continue with Parsing the message download history for a POP3 account, which describes how to parse this BLOB to identify messages that have been downloaded or deleted for that Inbox.

Core concepts to know for locating the message download history

The message download history for an Inbox is stored in a binary MAPI property, PidTagAttachDataBinary, on an attachment of a hidden message in the Inbox. Table 1 shows resources for concepts that help you understand how to locate the message download history.

Table 1. Core concepts
Article title | Description
MAPI Hidden Folders | MAPI allows mail clients to store information in hidden folders and hidden messages. Hidden folders are in the associated part of MAPI folders and typically contain information that is not visible to and not to be manipulated by users. Clients decide the format and contents to store in hidden messages in hidden folders.
MAPI Messages | MAPI stores messages in folders, either in the standard IPM subtree that is visible to users of a client, or outside of the subtree and invisible to users. Messages can have additional data stored in an attachment, which can be in the form of a file, another message, or an OLE object. In the case of the message download history, the history is stored in a property of a message that is attached to another hidden message.
Message Properties Overview | When a client stores information in a message, it actually stores the information in a property of the message. MAPI supports many properties—some always exist and can be set by clients, others are optional—and clients cannot expect them to be available or set to valid values. The message download history is stored in the PidTagAttachDataBinary property of an attachment to a hidden message.
MAPI Profiles | At logon time in a session, the mail client selects a profile that describes the providers and services to be used. A profile is divided into sections that contain properties. In particular, the PidTagSearchKey (PR_SEARCH_KEY) and PidTagProfileName (PR_PROFILE_NAME) properties always exist. A profile's search key is unique among all profiles, and is stored in the profile section that is identified by MUID_PROFILE_INSTANCE (which is defined in MAPIGUID.H). Use IMAPISession::OpenProfileSection to open the section, and use IMAPIProp::GetProps to get the property values.
Contents Tables | Message store providers implement contents tables for their folders. For hidden messages in the associated part of a folder, message store providers support associated contents tables, and clients can use the IMAPIContainer::GetContentsTable method to return a pointer to the associated contents table.
About Restrictions Types of Restrictions Building a Restriction Sample Restriction Code | In MAPI, clients can use restrictions to filter contents tables, to search for rows that represent messages that have a certain property set to a specific value. Restrictions are defined by using the SRestriction data structure, which can contain a union of more specialized restriction structures. The IMAPITable::FindRow method applies a restriction and retrieves the first row in a table that matches the restriction criteria.
About Registering Stores for Indexing | Use the PidTagStoreProvider (PR_MDB_PROVIDER) property to verify the type of store provider. For example, to verify whether a store is an Exchange store, the PidTagStoreProvider property should return a value represented by the constant pbExchangeProviderPrimaryUserGuid, which is defined in the public header file edkmdb.h.

Locating the appropriate hidden message and attachment

Now that we know the message download history for an Inbox is in the PidTagAttachDataBinary property of an attachment to a hidden message, the procedure to locate the appropriate attachment of the appropriate hidden message involves the following procedures.

  1. Find the appropriate hidden message

  2. Find the appropriate attachment of the hidden message

  3. Access the PidTagAttachDataBinary property of the message attachment

Find the appropriate hidden message

  1. Get the PidTagSearchKey (PR_SEARCH_KEY) property from the profile, in the profile section specified by MUID_PROFILE_INSTANCE.

  2. Open the Associated Contents for the Inbox folder by calling IMAPIContainer::GetContentsTable.

  3. Create a restriction based on the PidTagConversationKey (PR_CONVERSATION_KEY), PidTagSearchKey (PR_SEARCH_KEY), and PidTagMessageClass (PR_MESSAGE_CLASS) properties to get a table that contains all the hidden messages in the Associated Contents of the Inbox. The following is an example of a restriction extracted from Locating the POP3 UIDL History.

    C++ Copy code Copy code
    SRestriction rgRes[3];
SPropValue rgProps[3];
rgRes[0].rt = RES_AND;
rgRes[0].res.resAnd.cRes = 2;
rgRes[0].res.resAnd.lpRes = &rgRes[1];
rgRes[1].rt = RES_PROPERTY;
rgRes[1].res.resProperty.relop = RELOP_EQ;
rgRes[1].res.resProperty.ulPropTag = PR_CONVERSATION_KEY;
rgRes[1].res.resProperty.lpProp = &rgProps[0];
rgRes[2].rt = RES_PROPERTY;
rgRes[2].res.resProperty.relop = RELOP_EQ;
rgRes[2].res.resProperty.ulPropTag = PR_MESSAGE_CLASS;
rgRes[2].res.resProperty.lpProp = &rgProps[1];
rgProps[0].ulPropTag = PR_CONVERSATION_KEY;
rgProps[0].Value.bin = pVals[iSearchKey].Value.bin; // PR_SEARCH_KEY from the profile
rgProps[1].ulPropTag = PR_MESSAGE_CLASS;
rgProps[1].Value.LPSZ = (LPTSTR)"IPM.MessageManager";

  4. From the table, find the hidden message by using IMAPITable::FindRow.

  5. If step 4 fails to find a hidden message, change the restriction to use PidTagSearchKey (PR_SEARCH_KEY) instead of PidTagConversationKey, as shown below:

    C++ Copy code Copy code
    rgRes[1].res.resProperty.ulPropTag = rgProps[0].ulPropTag = PR_SEARCH_KEY;

  6. Find the hidden message using IMAPITable::FindRow.

  7. If Step 6 fails, change the restriction to use PidTagSubject (PR_SUBJECT) being equal to the following value (shown below using printf style substitution for brevity).

    C++ Copy code Copy code
    "Outlook Message Manager (%s) (KEY: %s)", PR_PROFILE_NAME, HexFromBin(PR_SEARCH_KEY)

  8. Find the hidden message by using IMAPITable::FindRow.

  9. If you are running Outlook 2010 or a later version, use the following values for PidTagProfileName (PR_PROFILE_NAME) and PidTagSearchKey (PR_SEARCH_KEY), respectively.

    C++ Copy code Copy code
    CHAR g_szGeneralKey[] = "General Key";
const SBinary g_binGeneralKey = {sizeof(g_szGeneralKey), (LPBYTE)g_szGeneralKey};

    Run through Steps 3 through 8. If this fails to find a message, fall back to the original steps 3 through 8.

  10. Open the hidden message found in Step 4, 6, or 8.

Find the appropriate attachment of the hidden message

Because the hidden message may have more than one attachment, look for the appropriate attachment in the following order.

Note Note

This procedure again uses the printf style substitution for brevity.

Find the appropriate attachment

  1. Look for an attachment whose PidTagAttachLongFilename (PR_ATTACH_LONG_FILENAME) matches the following string, where szEmailAddress is the user's SMTP address, as specified in the user's profile. .

    C++ Copy code Copy code
    "BlobPOP%s", szEmailAddress

  2. Look for an attachment whose PidTagAttachFilename (PR_ATTACH_FILENAME) matches "BlobPOP%s", szEmailAddress.

  3. Look for an attachment whose PidTagDisplayName (PR_DISPLAY_NAME) matches "BlobPOP%s", szEmailAddress.

  4. Look for an attachment whose PidTagAttachFilename (PR_ATTACH_FILENAME) matches "Blob%.8x", dwAcctUID, where dwAcctUID comes from PROP_ACCT_MINI_UID. You can use the IOlkAccount::GetProp method to access the PROP_ACCT_MINI_UID property.

Access the PidTagAttachDataBinary property of the message attachment

After locating the appropriate message attachment of the hidden message, use IMAPIProp::GetProps to read the PidTagAttachDataBinary property of the attachment.

Next steps

You have learned from this topic how to locate the message download history for the Inbox of a POP3 mail client. See Parsing the message download history for a POP3 account to learn how to parse this history to identify messages that have been downloaded or deleted for the Inbox.

Additional resources

  • Managing message downloads for POP3 accounts

  • Parsing the message download history for a POP3 account

  • Work with POP3 messages on multiple computers

  • Locating the POP3 UIDL History


Parsing the message download history for a POP3 account

 Copy code hover
[image]

Parsing the message download history for a POP3 account
Send feedback

This topic describes the structure of the POP3 BLOB that represents the message download history of a POP3 account, to identify the messages that have been downloaded or deleted on that account.

In this article
Why parse the message download history?
POP BLOB structure
Example
Additional resources

Why parse the message download history?

The Post Office Protocol (POP) provider for Outlook allows users to retrieve and download new email messages on their local device, and subsequently to leave or delete these email messages on the mail server. When the mail client checks for new messages to download, it has to be able to identify and download only the new messages for that Inbox. The mail client does this by first using the UIDL (Unique ID Listing) command to obtain a map of each message that has ever been delivered to that Inbox to a unique identifier (UID). The client also gets the message download history for messages that have been downloaded or deleted for the Inbox on that client. Using the message UID map and download history, the client can then identify those messages that are absent from the history as new and, hence, should be downloaded.

To get the messages download history for an Inbox:

  • Follow the steps in Locating the message download history for a POP3 account to find the PidTagAttachDataBinary property, which contains a binary large object (BLOB) that represents the message history for a POP3 account.

  • Read this topic, which describes the structure of the BLOB, and shows an example BLOB to identify messages that have been downloaded or deleted for the Inbox of the POP3 account.

POP BLOB structure

The POP BLOB structure, as described in Table 1, begins with two fields, Version and Count, followed by a Count number of resource tags, each of which is null-terminated.

Table 1. Structure of the BLOB that represents the message download history of a POP3 account
Field in BLOB | Size | Description
Version | 2 bytes | Must be 3 (PBLOB_VERSION_NUM).
Count | 2 bytes | The number of resource tags in this BLOB.
Resource tag | Variable | 0 or more null-terminated UTF-8 strings that encode the resource tags. The number of null-terminated strings must match Count.

Each resource tag specifies the operation that is applied to a message, some date-time metadata about the operation, and encodes the UID of the message. The format of a resource tag string is broken down as follows, and is further explained in Table 2.

Ocyyyymmddhhmmssuuu...

Table 2. Structure of a resource tag
Field in a resource tag | Size | Description
O | 1 character | The operation performed on the email message. The value must be "+", "-", or "&", which indicates a successful get, delete, or get-and-delete operation, respectively.
c | 1 character | The part of the message content involved in the operation. The value must be " ", "h", or "b", which indicates the content of none, header, or body, respectively.
yyyy | 4 characters | The four-digit year of the operation.
MM | 2 characters | The two-digit month of the operation.
dd | 2 characters | The two-digit day of the operation.
hh | 2 characters | The two-digit hour of the operation.
mm | 2 characters | The two-digit minute of the operation.
ss | 2 characters | The two-digit second of the operation.
uuu… | Variable length | The encoded UID of a message.

Example

Figure 1 shows an example of a BLOB that represents the message download history of a POP account.

Figure 1. Example BLOB structure for the message download history of a POP3 account

BLOB for messages download history of POP3 account

Based on the structure described in Table 1 and Table 2, this BLOB represents the download history of 23 email messages.

To parse the raw UID in each resource tag, be aware that the UID follows this encoding: characters in a UID are mostly alphanumeric characters, and each non-alphanumeric character is preceded by the ASCII character "$" (0x24). So the ASCII characters $2d represent the non-alphanumeric character "-". Figure 2 shows an example of first converting the raw UID in resource tag 1 to the ASCII representation, then converting any non-alphanumeric character preceded by "$" to produce the actual UID:

0BC535DB-EA63-11E1-A75C-00215AD7BB74

Figure 2. Converting the raw UID in a resource tag to the actual message UID

Converting raw UID in BLOB to actual message UID

To interpret resource tag 1 in this BLOB: the message with the UID 0BC535DB-EA63-11E1-A75C-00215AD7BB74 was successfully retrieved on September 6, 2012, at 13:11:38.

You can similarly parse the remaining 22 resource tags for that BLOB.

Additional resources

  • Managing message downloads for POP3 accounts

  • Locating the message download history for a POP3 account

  • Work with POP3 messages on multiple computers

  • Parsing the POP3 UIDL History


About the Data Degradation Layer API

 Copy code hover
[image]

About the Data Degradation Layer API
Send feedback

The Data Degradation Layer API provides the ability to hide the underlying native character format of an Outlook object, allowing a client to access the object in a preferred character format rather than in the object's native character format. It provides the constant definitions shown in Constants (Data degradation layer API), and the function HrCreateNewWrappedObject that returns an Outlook object wrapped in a specified format.


About APIs exported by Outlook

 Copy code hover
[image]

About APIs exported by Outlook
Send feedback

Outlook exports the following definitions, data structures, functions, and interfaces that were originally designed for internal use but are now exposed for public consumption.

Definitions:

  • Constants (Outlook exported APIs)

Data structures:

  • TZDEFINITION

  • TZREG

  • TZRULE

Functions:

  • HrCreateApptRebaser

  • HrProcessConvActionForSentItem

  • RebaseTaskComplete

  • RebaseTaskProgress

Interfaces:

  • IOlkApptRebaser

Events:

  • Available events and their dispids (Outlook exported APIs)

Additionally, using the dispatch identifiers, dispidFDirty and dispidShowSenderPhoto, you can achieve the following tasks:

  • How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)

  • How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)


Outlook configuration

 Copy code hover
[image]

Outlook configuration
Send feedback

This section describes how to configure Outlook to resolve item conflicts, determine the update time for an Offline Address Book, and register a domain for automatic configuration.

In This Section

  • About conflict resolution for custom item types

  • About the last update time of an Offline Address Book

  • About registering a new domain for automatic configuration


About conflict resolution for custom item types

 Copy code hover
[image]

About conflict resolution for custom item types
See also Send feedback

This topic describes how to resolve conflicts for custom item types that you create in Outlook.

Conflict Resolution for Standard Outlook Item Types

In Outlook, conflicts occur when two or more copies of the same item have been modified independently of each other. Outlook detects conflicts during synchronization. For example, you might update a meeting item online in Outlook Web App and then update the same meeting item in Outlook when you work offline. When Outlook goes online again and synchronizes the data between the client computer and the server, it detects that there are two different copies of the same meeting item.

When Outlook synchronizes items that belong to a standard Outlook item type, it takes into consideration the properties that are specific to that item type to detect possible conflicts. Outlook tries to resolve conflicts and stores the resultant copy in the appropriate folder without requesting user intervention. In cases where Outlook considers that there is a possibility that the resultant copy may not contain all essential data, Outlook stores the conflicting copies in the Conflicts folder, under the Sync Issues folder.

Note Note

Sync Issues and its subfolders are hidden until you click Folder List in the Navigation Pane.

In such cases, users can choose to go to the Conflicts folder to verify which items were in conflict and whether to use a copy in the Conflicts folder to replace the copy that Outlook decided to retain.

Conflict Resolution for Custom Item Types

Item Types and Message Classes

All items in Outlook are associated with a message class. For example, by default, a mail item is associated with the message class IPM.Note. The message class is primarily used to identify the form that should be used to display the item in Outlook. Outlook supports a list of message classes that are mapped to the types of items built in to Outlook. For more information about message classes, see Item Types and Message Classes.

Users can create custom item types, assign custom message classes to the custom item types, and have Outlook use a custom form to display the custom item types. For example, you may want Outlook to display a custom business contact form for your business contacts. To do that, you can create a custom message class IPM.Contact.Business, create a custom form for this message class, and assign business contacts with this message class.

Registering a Conflict Resolution Scheme for Custom Item Types

When you create a custom item type, other than the custom message class and custom form, you should also consider how you would like Outlook to handle conflicts between copies of an item of this item type. By default, Outlook employs a resolution scheme common to all items, does not consider properties that are specific to an item type, and presents conflicting copies for the user to make a decision. This is because custom item types may define custom fields in the custom form, and may have custom properties and custom code. If you want Outlook to consider item-specific properties and attempt to resolve the conflict with minimal user intervention, you must specify that through a setting in the Windows registry. This can be achieved in one of two ways:

  • By applying a Group Policy setting to the local computer that sets the registry key ConflictMsgCls. The following example specifies the version "14.0" for Outlook 2010:
    [HKCU]\Software\Policies\Microsoft\Office\14.0\Outlook\Options\ConflictMsgCls

  • By directly modifying the user registry key ConflictMsgCls. The following example specifies the version "14.0" for Outlook 2010:
    [HKCU]\Software\Microsoft\Office\14.0\Outlook\Options\ConflictMsgCls

Setting the conflict resolution through Group Policy takes precedence over directly modifying the user registry key. The location of the key in the registry depends on the version of Outlook. You specify the name of the custom message class as a value under this key. Specify the type of the value as DWORD, and the data of the value as one of the values shown in the following table, depending on the resolution scheme you choose.

Data | Description
0 | Common item resolution that requires a user decision, as used in Outlook 2002 and earlier versions.
1 | Common item resolution that requires minimal user intervention, as used in Outlook since Outlook 2003.
2 | Resolution specific to mail items.
3 | Resolution specific to meeting items.
4 | Resolution specific to appointment items.
5 | Resolution specific to contact items.
6 | Resolution specific to task items.
7 | Resolution specific to sticky note items.
8 | Resolution specific to journal items.

If you specify one of the item-specific resolution schemes (key data 2 through 8), Outlook will try to resolve conflicts in item-specific fields (for example, Start and End fields of an appointment item) automatically without user intervention. If Outlook considers that the resolution may result in the loss of essential data, Outlook will retain conflicting copies in the Conflicts folder, and users can choose to go to the Conflicts folder to manually re-resolve these items and override the automatic resolution.

Using the same business contacts example above, if you want to specify the contact item-specific resolution scheme for the custom message class IPM.Contact.Business, you can add it as a DWORD value under [HKCU]\Software\Microsoft\Office\15.0\Outlook\Options\ConflictMsgCls, and specify 5 as the data.

Note Note

Outlook always uses a resolution scheme that is specific to appointment items for custom message classes that are based on the appointment message class, IPM.Appointment (for example, IPM.Appointment.Personal).

See also

Concepts

Outlook Item Objects


About the last update time of an Offline Address Book

 Copy code hover
[image]

About the last update time of an Offline Address Book
See also Send feedback

An Offline Address Book (OAB) provides Outlook users in a disconnected state access to directory information from the Global Address List (GAL) and from other address books. It is a copy of an Address Book that Outlook has downloaded from an Exchange server to provide offline access.

Exchange administrators can choose which Address Books to make available for users who work offline. To create a copy of an Address Book, Exchange generates new OAB files, compresses the files, and places them on a local share. Depending on how Outlook is configured, Outlook downloads the OAB files either from the Web or from a Public Folder to a client computer for use in a disconnected state. Outlook periodically checks for and downloads OAB updates.

Outlook solutions that want to provide their users offline access to an OAB may need to find out when the OAB was last updated from the Exchange server. To find the last update time of an OAB, solutions can use the following entry in the Windows registry: HKCU\Software\Microsoft\Exchange\Exchange Provider\OAB Last Modified Time. The type of this registry entry is REG_BINARY. The data is 8 bytes in size. You can convert the data to a 64-bit FILETIME structure specifying a Universal Coordinated Time (UTC) value that Outlook last downloaded the OAB files from the Exchange server to the client computer.

See also

Other resources

Managing Offline Address Books


About registering a new domain for automatic configuration

 Copy code hover
[image]

About registering a new domain for automatic configuration
See also Send feedback

Outlook provides a way to specify a new message service domain for automatic configuration and allow the message service provider to configure the account.

When designing a message service provider, you can use the following key in the Windows registry to specify a new domain to be automatically configured by the corresponding message service provider:

HKLM\Software\Microsoft\Office\Outlook\AutoConfigDomains\<domain name>\

In the key, <domain name> is the domain for automatic configuration. This domain name supports a wildcard * at the beginning only. The following table shows the values that this key supports.

Value | Type | Description
Friendly Name | REG_SZ | The domain name that is displayed to the user during automatic configuration.
Service Name | REG_SZ | The message service registered in mapisvc.inf that supports this domain.
Install Location | REG_SZ | The URL of the location to install the message service provider, if it is not already installed.
Minimum Version | REG_DWORD | The minimum version of the .dll of the message service provider that is required. This value is optional.

When Outlook begins automatic configuration for an email account, it checks the Windows registry for the registration of the domain specified by the email address. If the domain is already specified in the Windows registry, Outlook checks whether the message service is registered in Mapisvc.inf. Outlook cannot proceed with automatic configuration of the domain unless it has been specified in the Windows registry.

If the specified message service is not currently registered in Mapisvc.inf, or the message service provider is installed but the .dll has a version earlier than the specified minimum, Outlook uses the specified friendly name and prompts the user to install the provider. If the user accepts, Outlook redirects the user to the specified installation location so that the user can install the provider. Installing the provider registers the message service in Mapisvc.inf.

If the message service is currently registered in Mapisvc.inf and the service provider .dll is an appropriate version, Outlook creates the message service by using IMsgServiceAdmin::CreateMsgService, and then configures it by using IMsgServiceAdmin::ConfigureMsgService. Outlook automatic configuration uses the following three properties to allow the provider to set up the account: PidTagAutoConfigurationUserName, PidTagAutoConfigurationUserEmail, and PidTagAutoConfigurationUserPassword.

See also

Concepts

File Format of MapiSvc.inf


Outlook calendars and appointments

 Copy code hover
[image]

Outlook calendars and appointments
Send feedback

This section provides conceptual information about Outlook calendars and appointments, including the Free/Busy API, meeting request updates, and rebasing calendars for daylight saving time.

In This Section

  • About the Free/Busy API

  • About meeting requests as informational updates and full updates

  • About rebasing calendars programmatically for Daylight Saving Time

  • About persisting TZDEFINITION to a stream to commit to a binary property


About the Free/Busy API

 Copy code hover
[image]

About the Free/Busy API
Send feedback

The Free/Busy API allows mail providers to provide free/busy status information for specified user accounts within a specified time range. The free/busy status of a block of time on a user's calendar is one of the following: out-of-office, busy, tentative, or free.

Create a Free/Busy Provider

To provide free/busy information to mail users, a mail provider creates a free/busy provider and registers it with Outlook. The free/busy provider must implement the following interfaces. Note that a number of members in these interfaces are not supported and must return the specified return values. In particular, the Free/Busy API does not support write access to free/busy information and delegate access to accounts.

  • IFreeBusySupport —This interface supports specification of interfaces that access free/busy data for specified users. It uses FBUser to identify a user.

  • IFreeBusyData —This interface gets and sets a time range for a given user and returns an interface for enumerating free/busy blocks of data within this time range. It uses relative time to get and set this time range. For more information, see How to: Use relative time to access free/busy data.

  • IEnumFBBlock —This interface supports accessing and enumerating free/busy blocks of data for a user within a time range.

    Note Note

    An enumeration contains free/busy blocks that indicate the free/busy status of periods of time on a user's calendar, within a time range (specified by IFreeBusyData::EnumBlocks). Items on a calendar, such as appointments and meeting requests, form blocks in the enumeration. Items that are adjacent to one another on the calendar and have the same free/busy status are combined to form one single block. A free period of time on a calendar also forms a block. Therefore, no two consecutive blocks in an enumeration would have the same free/busy status. These blocks do not overlap in time. When there are overlapping items on a calendar, Outlook merges these items to form non-overlapping free/busy blocks in the enumeration based on this order of precedence: out-of-office, busy, tentative.

To register the free/busy provider with Outlook, the mail provider should do the following:

  1. Register the free/busy provider with COM, providing a CLSID that allows access to the provider's implementation of IFreeBusySupport.

  2. Let Outlook know that the free/busy provider exists by setting the following key (where <xx.x> represents the version of Outlook) in the system registry:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\<xx.x>\Outlook\SchedulingInformation\FreeBusySupport

    For example, if the transport provider is SMTP, to register the provider with Microsoft Outlook 2010, set the following key to the data in the following table:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\14.0\Outlook\SchedulingInformation\FreeBusySupport

    Name

    Type

    Value

    SMTP

    REG_SZ

    {CLSID for respective implementation of IFreeBusySupport}

    In this scenario, Outlook will co-create the COM class and use it to retrieve free/busy information for any SMTP mail users.

To support an address book and transport provider that use an address entry type other than SMTP, change the Name accordingly.

Note Note

During installation, free/busy providers should check whether a registry setting for the the same address entry type already exists. If it does, the free/busy provider should overwrite the current provider for that address entry type, and restore to that provider when it uninstalls. However, if a user has installed more than one free/busy provider for the same address entry type, the user should uninstall these providers in the reverse order as installation (that is, always uninstall the latest provider). Otherwise, the registry may point to a provider that has already been uninstalled.

API Components

The Free/Busy API includes the following components:

Definitions

  • Constants (Free/busy API)

Data Types

  • FBBlock_1

  • FBStatus

  • FBUser

Interfaces

  • IEnumFBBlock

  • IFreeBusyData

  • IFreeBusySupport


About meeting requests as informational updates and full updates

 Copy code hover
[image]

About meeting requests as informational updates and full updates
Send feedback

A meeting request is an e-mail that has IPM.Schedule.Meeting.Request as the message class. By default, an attendee receiving a meeting request responds to it directly. Outlook supports setting up delegates who can respond to meeting requests on behalf of the principal recipient. Programmatically, Outlook sets the named property PidLidMeetingType of a meeting request to identify the current update status.

Recipients Without Delegates

When Outlook receives a new meeting request, Outlook sets the PidLidMeetingType property of the meeting request item to mtgRequest. Any subsequent update of that meeting is either mtgFullUpdate (a full update) or mtgInfoUpdate (an informational update) depending on the cause of the update, with Outlook setting PidLidMeetingType accordingly. A full update requires an attendee to explicitly respond to the meeting request, and an informational update does not.

Full Updates

There are two scenarios that result in a full update:

  • When an organizer changes the date, time, time zones, or recurrence of a prior meeting request, the organizer must send an update to all the attendees. This update is a full update to which an attendee must explicitly respond to notify the organizer of attendance, because Outlook ignores any previous responses.

  • If an attendee has not responded to an initial meeting request and receives a subsequent update, the initial meeting request becomes out-of-date and the update is a full update, regardless of the cause of the update.

Informational Updates

There are four scenarios in which Outlook generates an informational update. In these scenarios, responding to the informational update is optional.

  • If an organizer changes the location of a prior meeting request, the organizer must send an update to all the attendees. If an attendee already accepted the initial meeting request, the attendee receives the update as an informational update.

  • If an organizer adds an attendee to a prior meeting request, the organizer must send the meeting request to the newly added attendee, and has the option to include existing attendees on the update. The newly added attendee receives the meeting request as a new request. If the organizer chooses to send an update to existing attendees, the attendees receive the update as an informational update.

  • If an organizer removes an attendee from a prior meeting request, the organizer must send an update to the attendee who was removed from the meeting request and has an option to include existing attendees on the update. Attendees receive the update as an informational update.

  • If an organizer changes the subject or body of a prior meeting request, the organizer has the option to send an update to the attendees or just save the changes to the organizer's own copy of the meeting request. If the organizer chooses to send an update, attendees receive the update as an informational update.

Recipients Set Up with Delegates

Recipients who choose to set up delegates can have delegates respond to meeting requests that are not marked Private. By default, the principal receives only a copy of a meeting request or a copy of an update to a prior meeting request, and the delegates always receive the original meeting request or original full or informational update. In this default configuration, the principal always receives delegated meeting requests and updates; delegates of the principal receive meeting requests as new meeting requests, full updates, or informational updates, as described for recipients without delegates in the section "Recipients Without Delegates."

By default, principals can choose to respond to non-private meeting requests and updates, even though delegates are set up to do that on their behalf. However, as an alternative, administrators can set up a policy to prevent principal recipients from responding.


About rebasing calendars programmatically for Daylight Saving Time

 Copy code hover
[image]

About rebasing calendars programmatically for Daylight Saving Time
See also Send feedback

Many countries observe daylight saving time (DST) by advancing clocks so that evenings have longer daylight. This is typically done by setting the clock an hour ahead in the spring, and setting the clock an hour back in the fall. In this topic, this period between the spring and fall is referred to as the DST period. Most countries have their own regulations for when DST starts and ends. The dates of the DST period can change from year to year, and users must update their Microsoft Outlook calendar every time that the DST regulations change.

If you use a version of Windows that is Windows Vista or later, or have Windows automatic update turned on, you may not be affected by the change in DST. Otherwise, you should install DST updates for Windows. Regardless of whether the updates are installed automatically, on your behalf by an IT department, or by yourself as a home user, some existing appointments that occur during the DST period might display incorrect times after the DST updates for Windows are installed. This is true for both recurring and single-instance appointments. You must update these appointments to display them correctly in Outlook, in Outlook Web App, and in applications that are based on Collaboration Data Objects (CDO). Updating incorrectly displayed appointments on calendars because of DST is known as rebasing calendars.

Outlook provides tools for users and Exchange Server provides tools for administrators to rebase calendars. Outlook provides the Time Zone Data Update Tool for Outlook users. With this tool, users can update their own calendars. Exchange Server provides the Exchange Calendar Update Tool that helps administrators to avoid difficulties that result from deploying the Outlook tool widely to all users and to make sure that each user runs the Outlook tool correctly.

In addition to relying on users to run the Time Zone Data Update Tool or administrators to run the Exchange Calendar Update Tool, third-party MAPI client software developers can download a DLL, Tzmovelib.dll. By using this assembly, developers can use the same APIs that Outlook and Exchange Server use in their calendar rebasing tools. The following list shows the calendar rebasing APIs:

  • HrCreateApptRebaser

  • IOlkApptRebaser

  • IOlkApptRebaser::BeginEnumerateAppointments

  • IOlkApptRebaser::BeginRebaseAppointments

  • IOlkApptRebaser::EndEnumerateAppointments

  • IOlkApptRebaser::EndRebaseAppointments

  • PidLidAppointmentTimeZoneDefinitionEndDisplay

  • PidLidAppointmentTimeZoneDefinitionRecur

  • PidLidAppointmentTimeZoneDefinitionStartDisplay

  • PidLidTimeZoneStruct

  • RebaseTaskComplete

  • RebaseTaskProgress

  • TZDEFINITION

  • TZREG

  • TZRULE

To write an appointment rebasing tool by using the calendar rebasing APIs, you can use the following procedure:

  1. Use IOlkApptRebaser::BeginEnumerateAppointments and IOlkApptRebaser::EndEnumerateAppointments to find appointments that are candidates for rebasing. If necessary, present information to enable the user to decide which appointments to rebase. Alternatively, use MAPI or the Outlook Object Model to examine the time and recurrence information for an appointment by parsing the PidLidAppointmentTimeZoneDefinitionStartDisplay, PidLidAppointmentTimeZoneDefinitionEndDisplay, and PidLidAppointmentTimeZoneDefinitionRecur properties.

  2. Use HrCreateApptRebaser, IOlkApptRebaser::BeginRebaseAppointments, and IOlkApptRebaser::EndRebaseAppointments to rebase the appointment.

To obtain the Tzmovelib.dll assembly, download the OutlookTimeZoneMoveLibRedist.exe redistributable installer and the Tzmovelib.h header file at Outlook 2010: Auxiliary Reference Redistributable Installer and Header File for Rebasing Calendars. This download works for Outlook 2010 and later versions of Outlook. OutlookTimeZoneMoveLibRedist.exe installs the Tzmovelib.dll assembly file in C:\Program Files\MsExTmz. Note that third-party calendar rebasing applications can redistribute only the installer, OutlookTimeZoneMoveLibRedist.exe, and must not redistribute the assembly, Tzmovelib.dll, or any other extracted components separately from the installer.

See also

Concepts

About persisting TZDEFINITION to a stream to commit to a binary property
How to: Parse a stream from a binary property to read the TZDEFINITION structure
How to: Parse a stream from a binary property to read the TZREG structure
How to: Read time zone properties from an appointment

Other resources

Daylight Saving Time Help and Support Center
How to address daylight saving time by using the Exchange Calendar Update Tool
How to address time zone changes by using the Time Zone Data Update Tool for Microsoft Office Outlook


About persisting TZDEFINITION to a stream to commit to a binary property

 Copy code hover
[image]

About persisting TZDEFINITION to a stream to commit to a binary property
See also Send feedback

The time zone properties, PidLidAppointmentTimeZoneDefinitionEndDisplay, PidLidAppointmentTimeZoneDefinitionRecur, and PidLidAppointmentTimeZoneDefinitionStartDisplay are binary named properties, each of which contains a stream that maps to the persisted format of a TZDEFINITION structure.

This topic describes a little endian format that can be used when persisting TZDEFINITION to a stream to commit to one of three binary properties. Use the same endian format in a parser to interpret a stream value obtained from one of these properties.

Copy code Copy code
BYTE  bMajorVersion;    // breaking change
BYTE  bMinorVersion;    // extensibility
WORD  cbHeader;         // size of following data until TZREG sub structure
WORD  wFlags;

if (TZDEFINITION_FLAG_VALID_GUID)
   GUID  guid;                // guid

if (TZDEFINITION_FLAG_VALID_KEYNAME)
    WORD   cchKeyName;        // does not include null char
    WCHAR  rgchKeyName;       // not null terminated

    WORD  cRules;             // number of rules

// for each rule
   BYTE        bMajorVersion;         // breaking change
   BYTE        bMinorVersion;         // extensibility
   WORD        cbRule;                // size of following data
   WORD        wFlags;                // flags
   SYSTEMTIME  stStart;               // GMT when this rule starts

// Following are the fields of the TZREG sub structure
   long        lBias;                // offset from GMT
   long        lStandardBias;        // offset from bias during standard time
   long        lDaylightBias;        // offset from bias during daylight time
   SYSTEMTIME  stStandardDate;       // time to switch to standard time
   SYSTEMTIME  stDaylightDate;       // time to switch to daylight time

The major version number is used to make a breaking change. Clients that are unfamiliar with the major version number should treat the property as if it is not there. Clients writing the structure should specify the constant TZ_BIN_VERSION_MAJOR.

The minor version number is used for extensibility. Clients that are unfamiliar with the minor version number should read the data that they understand, and skip over the data that might be appended to each rule or to the overall stream. Clients writing the structure should specify the constant TZ_BIN_VERSION_MINOR.

If a parser does not understand the major version of the header, it should not read the rest of the structure and behave as if the data is missing. If a parser does not understand the minor version of the header, it should use cbHeader to ignore the portions that it does not understand and advance to read the portions of the stream that it understands.

The value of wFlags is always TZDEFINITION_FLAG_VALID_KEYNAME. The key name has a maximum size of MAX_PATH.

If a parser does not recognize the major version of a rule, the client should ignore the rule, and use cbRule to advance to the next rule. If a parser does not recognize the minor version of a rule, the client should only parse the parts of the rule that it understands.

When persisting a TZDEFINITION structure to a stream, a parser should not try to write any information that it does not understand.

The maximum number of rules is 1024.

Note that the TZREG structure is persisted here differently than when persisted alone, so the same code cannot be used to parse it.

See also

Concepts

Constants (Outlook exported APIs)
How to: Parse a stream from a binary property to read the TZDEFINITION structure
How to: Read time zone properties from an appointment


Sample tasks

 Copy code hover
[image]

Sample tasks
Send feedback

This section contains sample tasks that use the APIs available in the Outlook 2013 Auxiliary Reference.

In This Section

  • How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)

  • How to: Parse a stream from a binary property to read the TZDEFINITION structure

  • How to: Parse a stream from a binary property to read the TZREG structure

  • How to: Read time zone properties from an appointment

  • How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)

  • How to: Use relative time to access free/busy data


How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)

 Copy code hover
[image]

How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)
See also Send feedback

This topic shows how to use the dispidFDirty dispatch ID to invoke the corresponding property on an Outlook item, to see whether the item has been modified and has not been saved.

Given an item object, you can use the IUnknown::QueryInterface method to obtain an IDispatch interface pointer. The function in this topic, FIsItemDirty, accepts an IDispatch pointer, pdisp, as an input parameter. FIsItemDirty calls the IDispatch::Invoke method, specifying dispidFDirty as the argument for the dispIdMember parameter, and the flags DISPATCH_METHOD | DISPATCH_PROPERTYGET for wFlags, to verify whether the item has been modified. FIsItemDirty returns a Boolean value (True to indicate that the item has unsaved changes; otherwise, False).

C++ Copy code Copy code
bool FIsItemDirty(IDispatch *pdisp)
{
    DISPPARAMS dispparams;
    UINT uArgErr;
    HRESULT hr = S_OK;
    CComVariant varDirty;
    dispparams.rgvarg = 0;
    dispparams.cArgs = 0;
    dispparams.cNamedArgs = 0;
    dispparams.rgdispidNamedArgs = NULL;
    hr = pdisp->Invoke(dispidFDirty,
        IID_NULL,
        LOCALE_SYSTEM_DEFAULT,
        DISPATCH_METHOD | DISPATCH_PROPERTYGET,
        &dispparams,
        &varDirty,
        NULL,
        &uArgErr);
    return SUCCEEDED(hr) && varDirty.bVal;
}

See also

Concepts

Constants (Outlook exported APIs)


How to: Parse a stream from a binary property to read the TZDEFINITION structure

 Copy code hover
[image]

How to: Parse a stream from a binary property to read the TZDEFINITION structure
See also Send feedback

This topic shows how to read the TZDEFINITION structure from the persisted format stored in a binary property.

C++ Copy code Copy code
TZDEFINITION* BinToTZDEFINITION(ULONG cbDef, LPBYTE lpbDef)
{
    if (!lpbDef) return NULL;

    // Update this if parsing code is changed.
    // This checks the size up to the flag member.
    if (cbDef &lt; 2*sizeof(BYTE) + 2*sizeof(WORD)) return NULL;

    TZDEFINITION tzDef = {0};
    TZRULE* lpRules = NULL;
    LPBYTE lpPtr = lpbDef;
    WORD cchKeyName = NULL;
    WCHAR* szKeyName = NULL;
    WORD i = 0;

    BYTE bMajorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);
    BYTE bMinorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);

    // We only understand TZ_BIN_VERSION_MAJOR
    if (TZ_BIN_VERSION_MAJOR != bMajorVersion) return NULL;

    // We only understand if &gt;= TZ_BIN_VERSION_MINOR
    if (TZ_BIN_VERSION_MINOR &gt; bMinorVersion) return NULL;

    lpPtr += sizeof(WORD);

    tzDef.wFlags = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);

    if (TZDEFINITION_FLAG_VALID_GUID &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(GUID)) return NULL;
        tzDef.guidTZID = *((GUID*)lpPtr);
        lpPtr += sizeof(GUID);
    }

    if (TZDEFINITION_FLAG_VALID_KEYNAME &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
        cchKeyName = *((WORD*)lpPtr);
        lpPtr += sizeof(WORD);
        if (cchKeyName)
        {
            if (lpbDef + cbDef - lpPtr &lt; (BYTE)sizeof(WORD)*cchKeyName) return NULL;
            szKeyName = (WCHAR*)lpPtr;
            lpPtr += cchKeyName*sizeof(WORD);
        }
    }

    if (lpbDef+ cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
    tzDef.cRules = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);
    if (tzDef.cRules)
    {
        lpRules = new TZRULE[tzDef.cRules];
        if (!lpRules) return NULL;

        LPBYTE lpNextRule = lpPtr;
        BOOL bRuleOK = false;

See also

Concepts

About persisting TZDEFINITION to a stream to commit to a binary property
How to: Read time zone properties from an appointment


How to: Parse a stream from a binary property to read the TZREG structure

 Copy code hover
[image]

How to: Parse a stream from a binary property to read the TZREG structure
See also Send feedback

This topic shows how to read the TZREG structure from the persisted format stored in the binary property PidLidTimeZoneStruct.

C++ Copy code Copy code
TZREG* BinToTZREG(ULONG cbReg, LPBYTE lpbReg)
{
    if (!lpbReg) return NULL;

    // Update this if parsing code is changed.
    if (cbReg &lt; 3*sizeof(long) + 2*sizeof(WORD) + 2*sizeof(SYSTEMTIME)) return NULL;

    TZREG tzReg = {0};
    LPBYTE lpPtr = lpbReg;

    tzReg.lBias = *((long*)lpPtr);
    lpPtr += sizeof(long);
    tzReg.lStandardBias = *((long*)lpPtr);
    lpPtr += sizeof(long);
    tzReg.lDaylightBias = *((long*)lpPtr);
    lpPtr += sizeof(long);
    lpPtr += sizeof(WORD);// reserved

    tzReg.stStandardDate = *((SYSTEMTIME*)lpPtr);
    lpPtr += sizeof(SYSTEMTIME);
    lpPtr += sizeof(WORD);// reserved
    tzReg.stDaylightDate = *((SYSTEMTIME*)lpPtr);
    lpPtr += sizeof(SYSTEMTIME);

    TZREG* ptzReg = NULL;
    ptzReg = new TZREG;
    if (ptzReg)
    {
        *ptzReg = tzReg;
    }

    return ptzReg;
}

See also

Concepts

How to: Read time zone properties from an appointment


How to: Read time zone properties from an appointment

 Copy code hover
[image]

How to: Read time zone properties from an appointment
See also Send feedback

This topic shows a function, ReadTimeZones, that calls the two functions, BinToTZDEFINITION and BinToTZREG, to read the time zone properties, PidLidAppointmentTimeZoneDefinitionStartDisplay and PidLidTimeZoneStruct, from an appointment.

PidLidAppointmentTimeZoneDefinitionStartDisplay contains a stream that maps to the persisted format of a TZDEFINITION structure, and PidLidTimeZoneStruct contains a stream that maps to the persisted format of a TZREG structure. To obtain the exact TZDEFINITION and TZREG structures, BinToTZDEFINITION and BinToTZREG are used to parse the stream values of these properties appropriately. These two functions are defined in How to: Parse a stream from a binary property to read the TZDEFINITION structure and How to: Parse a stream from a binary property to read the TZREG structure, respectively.

C++ Copy code Copy code
void ReadTimeZones(LPMAPIPROP lpAppointment)
{
    HRESULT hRes = S_OK;
    LPSPropTagArray lpNamedPropTags = NULL;
    MAPINAMEID NamedID[2] = {0};
    LPMAPINAMEID lpNamedID[2];
    lpNamedID[0] = &NamedID[0];
    lpNamedID[1] = &NamedID[1];
    NamedID[0].lpguid = (LPGUID)&PSETID_Appointment;
    NamedID[0].ulKind = MNID_ID;
    NamedID[0].Kind.lID = dispidTimeZoneStruct;
    NamedID[1].lpguid = (LPGUID)&PSETID_Appointment;
    NamedID[1].ulKind = MNID_ID;
    NamedID[1].Kind.lID = dispidApptTZDefStartDisplay;
    hRes = lpAppointment->GetIDsFromNames(
        2,
        lpNamedID,
        NULL,
        &lpNamedPropTags);
    if (SUCCEEDED(hRes) && lpNamedPropTags)
    {
        SizedSPropTagArray(2,sptaTzProps) = {2,
            CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[0],PT_BINARY),
            CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[1],PT_BINARY),
        };
        LPSPropValue lpProps = NULL;
        ULONG cProps = 0;
        hRes = lpAppointment->GetProps(
            (LPSPropTagArray)&sptaTzProps,
            NULL,
            &cProps,
            &lpProps);
        if (SUCCEEDED(hRes) && 2 == cProps && lpProps)
        {
            if (PT_BINARY == PROP_TYPE(lpProps[0].ulPropTag))
            {
                TZREG* ptzReg = BinToTZREG(lpProps[0].Value.bin.cb,lpProps[0].Value.bin.lpb);
                // TODO: Do whatever is necessary with ptzReg.
                delete ptzReg;
            }
            if (PT_BINARY == PROP_TYPE(lpProps[1].ulPropTag))
            {
                TZDEFINITION* ptzDef = BinToTZDEFINITION(lpProps[1].Value.bin.cb,lpProps[1].Value.bin.lpb);
                // TODO: Do whatever is necessary with ptzDef.
                delete[] ptzDef;
            }
           }
        MAPIFreeBuffer(lpProps);
    }
    MAPIFreeBuffer(lpNamedPropTags);
}

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)

 Copy code hover
[image]

How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)
See also Send feedback

This topic shows how to use the dispidShowSenderPhoto dispatch ID to invoke the corresponding method on an Outlook Explorer or Inspector object, to specify whether to display a contact's picture in the explorer or inspector window, according to a Boolean argument. Specifying VARIANT_TRUE as the argument turns on the display, and VARIANT_FALSE turns off the display.

Given a pointer to an Explorer or Inspector object, you can use the IUnknown::QueryInterface method to obtain an IDispatch interface pointer. The function in this topic, SetSenderContactPhoto, accepts two input parameters:

  • inspector—An _InspectorPtr value.

  • showSenderContactPhoto—A Boolean value that specifies whether to display contacts' pictures.

SetSenderContactPhoto calls the IDispatch::Invoke method—specifying dispidShowSenderPhoto as the argument for the dispIdMember parameter, and using showSenderContactPhoto to form the argument for the pDispParams parameter—to turn on or off the display according to the value of showSenderContactPhoto.

C++ Copy code Copy code
void SetSenderContactPhoto(_InspectorPtr inspector, bool showSenderContactPhoto)
{
    CComVariant cv;
    IDispatchPtr spdisp;
    DISPPARAMS dispparams;
    EXCEPINFO excepinfo = {0};
    spdisp = inspector;
    cv = showSenderContactPhoto ? VARIANT_TRUE : VARIANT_FALSE;
    dispparams.rgvarg = &cv;
    dispparams.cArgs = 1;
    dispparams.rgdispidNamedArgs = NULL;
    dispparams.cNamedArgs = 0;
    spdisp->Invoke(dispidShowSenderPhoto,
        IID_NULL,
        0,
        DISPATCH_METHOD,
        &dispparams,
        NULL,
        &excepinfo,
        NULL);
}

This setting does not persist across Outlook sessions and does not carry from one inspector or explorer to another. The default setting is to turn on the display. This means that if a picture is present, it is displayed. However, if no picture is present, no placeholder picture is displayed.

This setting works in conjunction with the TurnOffPhotograph policy key as well as the older ShowContactPicture registry key. The TurnOffPhotograph policy key was introduced in Microsoft Outlook 2010, and ShowContactPicture registry key was introduced in Microsoft Office Outlook 2007. The following table shows how these registry keys and dispidShowSenderPhoto interact. This setting does not turn on the display if administrator policy (TurnOffPhotograph policy key) or user preference (ShowContactPicture registry key) turns off the display. For more information about the TurnOffPhotograph policy key, see How to manage the Outlook Social Connector by using Group Policy. For more information about the ShowContactPicture registry key, see Deploying additional registry values in the Office Customization Tool for Outlook 2007.

Argument for method represented by dispidShowSenderPhoto | TurnOffPhotograph policy key | ShowContactPicture registry key | Is picture displayed if present?
True | 0 or not set | 1 or not set | Yes
True | 0 or not set | 0 | No
True | 1 | 1 or not set | No
True | 1 | 0 | No
False | 0 or not set | 1 or not set | No
False | 0 or not set | 0 | No
False | 1 | 1 or not set | No
False | 1 | 0 | No

See also

Concepts

Constants (Outlook exported APIs)


How to: Use relative time to access free/busy data

 Copy code hover
[image]

How to: Use relative time to access free/busy data
See also Send feedback

The IFreeBusyData interface in the Free/Busy API uses a concept of relative time, which is the number of minutes since January 1, 1601, expressed in Universal Time (UTC), and is a value of type LONG.

The following are some commonly used relative time values:

  • ULONG ulrtmMax = 1525252319L

  • ULONG ulrtmMin = 0L

Use the preceding maximum and minimum relative time values to help verify that your relative time values are valid.

Because NTFS records file times natively in FILETIME format, it might be handy to use the following code example to convert relative time to and from FILETIME.

C++ Copy code Copy code
static const LONGLONG UnitsPerMinute = 600000000;
static const LONGLONG UnitsPerHalfMinute = 300000000;
void RTimeToFileTime(LONG rtime, FILETIME *pft)
{
    Assert(pft != NULL);
    ULARGE_INTEGER *puli = (ULARGE_INTEGER *)pft;
    puli->QuadPart = rtime * UnitsPerMinute;
}

void FileTimeToRTime(FILETIME *pft, LONG* prtime)
{
    Assert(pft != NULL);
    Assert(prtime != NULL);

    ULARGE_INTEGER uli = *(ULARGE_INTEGER *)pft;

    uli.QuadPart += UnitsPerHalfMinute;
    uli.QuadPart /= UnitsPerMinute;
    *prtime = uli.LowPart;
}

See also

Concepts

About the Free/Busy API
IFreeBusyData


Reference (Outlook 2013 auxiliary reference)

 Copy code hover
[image]

Reference (Outlook 2013 auxiliary reference)
Send feedback

This section includes reference content for the following APIs in the Outlook 2013 Auxiliary Reference.

In This Section

  • Account management API reference

  • Data degradation layer API reference

  • Free/busy API reference

  • Outlook exported APIs


Account management API reference

 Copy code hover
[image]

Account management API reference
Send feedback

This section provides reference content for the Account Management API, which provides access to account information, supports notifications of account changes, protecting accounts from spam and managing message downloads for POP3 accounts.

In This Section

  • Constants

  • Data Types

  • Interfaces

  • Named Properties

  • Properties


Constants (Account management API)

 Copy code hover
[image]

Constants (Account management API)
Send feedback

This topic contains constant definitions, class identifiers, and interface identifiers for the Account Management API.

Constants

Constant | Definition
ACCT_INIT_NOSYNCH_MAPI_ACCTS | 0x00000001
ACCT_INIT_NO_STORES_CHECK | 0x00000002
ACCTUI_NO_WARNING | 0x0100
ACCTUI_SHOW_ACCTWIZARD | 0x0400
ACCTUI_SHOW_DATA_TAB | 0x0200
E_ACCT_NOT_FOUND | 0x800C8101
E_ACCT_UI_BUSY | 0x800C8102
E_ACCT_WRONG_SORT_ORDER | 0x800C8105
E_INVALIDARG | As defined in the Windows Software Development Kit (SDK) header file winerror.h.
E_NOTIMPL | As defined in the Windows SDK header file winerror.h.
E_OLK_ALREADY_INITIALIZED | 0x800C8002
E_OLK_NOT_INITIALIZED | 0x800C8005
E_OLK_PARAM_NOT_SUPPORTED | 0x800C8003
E_OLK_PROP_READ_ONLY | 0x800C800D
E_OLK_REGISTRY | 0x800C8001
The following constants beginning with ENCRYPT_ are used by the PROP_SMTP_SECURE_CONNECTION property to specify the type of encrypted connection. |
ENCRYPT_CONN_AUTO | 3
ENCRYPT_CONN_NO_SECURITY | 0
ENCRYPT_CONN_SSL | 1
ENCRYPT_CONN_TLS | 2
MAPIACCT_SEND_ONLY | 0x00000001
NOTIFY_ACCT_CHANGED | 1
NOTIFY_ACCT_CREATED | 2
NOTIFY_ACCT_DELETED | 3
NOTIFY_ACCT_ORDER_CHANGED | 4
NOTIFY_ACCT_PREDELETED | 5
OLK_ACCOUNT_NO_FLAGS | 0
S_OK | As defined in the Windows SDK header file winerror.h.
S_FALSE | As defined in the Windows SDK header file winerror.h.
SECURE_FLAG | 0x8000
The following constants beginning with SMTP_ are used by the PROP_SMTP_AUTH_METHOD property and specify the authentication method. |
SMTP_AUTH_SAME_AS_POP | 0
SMTP_AUTH_RECEIVE_BEFORE_SEND | 2
SMTP_AUTH_USER_PASS | 1
The following 5 constants and macros are used by the PROP_POP_LEAVE_ON_SERVER property and specify options for POP accounts to leave a copy of a message on the server. |
LEAVE_ON_SERVER | 0x1
REMOVE_AFTER | 0x2
REMOVE_ON_NUKE | 0x4
GET_REMOVE_AFTER_DAYS(ul) | ((ul)>>16)
SET_REMOVE_AFTER_DAYS(days) | ((days)<<16)

Class Identifiers

Use the DEFINE_GUID macro defined in the Windows SDK header file guiddef.h to associate the GUID symbolic name with its value.

//{ed475410-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkAccountManager, 0xed475410, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475411-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkPOP3Account, 0xed475411, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475412-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkIMAP4Account, 0xed475412, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475414-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkMAPIAccount, 0xed475414, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475418-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkMail, 0xed475418, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475419-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkAddressBook, 0xed475419, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{ed475420-b0d6-11d2-8c3b-00104b2a6676}

DEFINE_GUID(CLSID_OlkStore, 0xed475420, 0xb0d6, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{4db5cbf0-3b77-4852-bc8e-bb81908861f3}

DEFINE_GUID(CLSID_OlkHotmailAccount, 0x4db5cbf0, 0x3b77, 0x4852, 0xbc, 0x8e, 0xbb, 0x81, 0x90, 0x88, 0x61, 0xf3);

//{4db5cbf2-3b77-4852-bc8e-bb81908861f3}

DEFINE_GUID(CLSID_OlkLDAPAccount, 0x4db5cbf2, 0x3b77, 0x4852, 0xbc, 0x8e, 0xbb, 0x81, 0x90, 0x88, 0x61, 0xf3);

Interface Identifiers

Use the DEFINE_GUID macro defined in the Windows SDK header file guiddef.h to associate the GUID symbolic name with its value.

//{9240A6C0-AF41-11d2-8C3B-00104B2A6676}

DEFINE_GUID(IID_IOlkErrorUnknown, 0x9240a6c0, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{9240A6C1-AF41-11d2-8C3B-00104B2A6676}

DEFINE_GUID(IID_IOlkEnum, 0x9240a6c1, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{9240a6c3-af41-11d2-8c3b-00104b2a6676}

DEFINE_GUID(IID_IOlkAccountNotify, 0x9240a6c3, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{9240a6cb-af41-11d2-8c3b-00104b2a6676}

DEFINE_GUID(IID_IOlkAccountHelper, 0x9240a6cb, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{9240a6cd-af41-11d2-8c3b-00104b2a6676}

DEFINE_GUID(IID_IOlkAccountManager, 0x9240a6cd, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);

//{9240a6d2-af41-11d2-8c3b-00104b2a6676}

DEFINE_GUID(IID_IOlkAccount, 0x9240a6d2, 0xaf41, 0x11d2, 0x8c, 0x3b, 0x0, 0x10, 0x4b, 0x2a, 0x66, 0x76);


Data types (Account management API)

 Copy code hover
[image]

Data types (Account management API)
Send feedback

This section describes the data types in the Account Management API.

Data type | Description
ACCT_BIN | A variable of this data type holds a binary value.
ACCT_VARIANT | A variable of this data type holds the value of a property, which is of a variant data type.


ACCT_BIN

 Copy code hover
[image]

ACCT_BIN
Send feedback

A variable of this data type holds a binary value.

Quick Info

Copy code Copy code
typedef struct {
    DWORDcb;
    BYTE * pb;
} ACCT_BIN;

Members

cb

Number of bytes that pb points to.

pb

Pointer to binary information.


ACCT_VARIANT

 Copy code hover
[image]

ACCT_VARIANT
Send feedback

A variable of this data type holds the value of a property, which is of a variant data type.

Quick Info

Copy code Copy code
typedef struct
    {
        DWORD dwType;
        union
            {
            DWORD dw;
            WCHAR *pwsz;
            ACCT_BIN bin;
            } Val;
    } ACCT_VARIANT;

Members

dwType

Type of variant:

  • PT_LONG

  • PT_UNICODE

  • PT_BINARY

dw

DWORD value of variant.

pwsz

String value of variant.

bin

Binary value of the variant.


Interfaces (Account management API)

 Copy code hover
[image]

Interfaces (Account management API)
Send feedback

This section describes the interfaces in the Account Management API.

Interface | Description
IOlkAccount | Supports getting and setting of properties and other information about an account.
IOlkAccountHelper | Provides helper functionality in the current MAPI session to manage accounts.
IOlkAccountManager | Manages access to accounts and sets up notifications about account changes.
IOlkAccountNotify | Provides a callback to the client for changes to an account.
IOlkEnum | Supports enumerating accounts as IUnknown objects.
IOlkErrorUnknown | Provides extra information about the last error.


IOlkAccount

 Copy code hover
[image]

IOlkAccount
See also Send feedback

Supports getting and setting of properties and other information about an account.

Quick Info

Inherits from: | IOlkErrorUnknown
Implemented by: | Outlook
Provided by: | IOlkAccountManager::FindAccount and IOlkEnum::GetNext
Called by: | Client
Interface identifier: | IID_IOlkAccount

Vtable Order

Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
GetAccountInfo | Gets the type and categories of the specified account.
GetProp | Gets the value of the specified account property. See the Properties table below.
SetProp | Sets the value of the specified account property. See the Properties table below.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
FreeMemory | Frees memory allocated by the IOlkAccount interface.
Placeholder member | Not supported or documented.
SaveChanges | Commits changes to the account object by writing to the registry store.

Properties

PROP_ACCT_DELIVERY_FOLDER | Represents the Entry ID of the default delivery folder for the account.
PROP_ACCT_DELIVERY_STORE | Represents the Entry ID of the default delivery store for the account.
PROP_ACCT_ID | Returns the account identifier in Outlook 2000 and earlier versions of Outlook.
PROP_ACCT_IS_EXCH | True if the account is a Microsoft Exchange account.
PROP_ACCT_MINI_UID | Returns the account identifier in versions of Outlook since Outlook 2002.
PROP_ACCT_NAME | Returns the account name.
PROP_ACCT_PREFERENCES_UID | Retrieves the unique identifier (UID) for the profile section that stores the account preferences.
PROP_ACCT_SEND_STAMP | Returns the account "send" stamp.
PROP_ACCT_SENTITEMS_EID | Represents the Entry ID of the default folder for sent items for the account.
PROP_ACCT_STAMP | Returns the account stamp.
PROP_ACCT_USER_DISPLAY_NAME | Returns the user display name.
PROP_ACCT_USER_EMAIL_ADDR | Specifies the email address for the account.
PROP_MAPI_EMSMDB_UID | Represents an ACCT_BIN structure that contains the UID of an Exchange account.
PROP_MAPI_IDENTITY_ENTRYID | Retrieves or sets the address book entry ID for the account.
PROP_MAPI_TRANSPORT_FLAGS | Represents transport settings that Microsoft Outlook uses to determine the necessary synchronization tasks and to disable the user interface (UI) elements that the account does not support.

Remarks

This interface is returned by IOlkAccountManager::FindAccount when searching for an account that supports IOlkAccount and IOlkEnum::GetNext when getting the next account in an enumerator.

See also

Concepts

About the Account Management API
Constants (Account management API)


IOlkAccount::FreeMemory

 Copy code hover
[image]

IOlkAccount::FreeMemory
See also Send feedback

Frees memory allocated by the IOlkAccount interface.

Quick Info

See IOlkAccount.

Copy code Copy code
HRESULT IOlkAccount::FreeMemory (
    BYTE *pv,
);

Parameters

pv

[in] A pointer to memory to be freed.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

Use this method to free memory allocated by IOlkAccount::GetProp (if the value of the specified account property is a binary or string type) and IOlkAccount::GetAccountInfo.

See also

Concepts

IOlkAccount::GetAccountInfo
IOlkAccount::GetProp


IOlkAccount::GetAccountInfo

 Copy code hover
[image]

IOlkAccount::GetAccountInfo
See also Send feedback

Gets the type and categories information for the specified account.

Quick Info

See IOlkAccount.

Copy code Copy code
HRESULT IOlkAccount::GetAccountInfo(
    CLSID *pclsidType,
    DWORD *pcCategories,
    CLSID **prgclsidCategory
);

Parameters

pclsidType

[out] The class identifier for the account type. The value must be one of the following:

  • CLSID_OlkPOP3Account

  • CLSID_OlkIMAP4Account

  • CLSID_OlkMAPIAccount

  • CLSID_OlkHotmailAccount

  • CLSID_OlkLDAPAccount

pcCategories

[out] The number of categories in prgclsidCategory.

prgclsidCategory

[out] An array of categories that this account is associated with. The array is of size *pcCategories. The value of each category in the array must be one of the following:

  • CLSID_OlkMail

  • CLSID_OlkAddressBook

  • CLSID_OlkStore

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

After this method returns, you must free prgclsidCategory by using IOlkAccount::FreeMemory.

IOlkAccount::GetAccountInfo does not support the address book category for an Exchange account. If the account is an Exchange account (pclsidType is CLSID_OlkMAPIAccount), and the account implements the address book, calling IOlkAccount::GetAccountInfo will not return CLSID_OlkAddressBook as a category in prgclsidCategory.

See also

Concepts

Constants (Account management API)
IOlkAccount::FreeMemory


IOlkAccount::GetProp

 Copy code hover
[image]

IOlkAccount::GetProp
See also Send feedback

Gets the value of the specified account property.

Quick Info

See IOlkAccount.

Copy code Copy code
HRESULT IOlkAccount::GetProp(
DWORD dwProp,
ACCT_VARIANT *pVar
);

Parameters

dwProp

[in] The property tag of the account property to get.

pVar

[out] The value of the specified property.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_ACCT_NOT_FOUND | The property is not found for the given account.
E_INVALIDARG | An invalid property tag has been specified.

Remarks

After this method returns, if the value of the account property is a binary or string type, you must free pVar by using IOlkAccount::FreeMemory.

See also

Concepts

Constants (Account management API)
IOlkAccount::FreeMemory
IOlkAccount::SetProp


IOlkAccount::SaveChanges

 Copy code hover
[image]

IOlkAccount::SaveChanges
See also Send feedback

Commits changes to the account object by writing to the registry store.

Quick Info

See IOlkAccount.

Copy code Copy code
HRESULT IOlkAccount::SaveChanges (
    DWORD dwFlags
);

Parameters

dwFlags

[in] Flags to modify behavior. OLK_ACCOUNT_NO_FLAGS is the only supported value.

Return Values

HRESULT | Description
S_OK | The method was successful.
E_ACCT_NOT_FOUND | Cannot find the specified account.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

Remarks

After changing the value of account properties by using IOlkAccount::SetProp, use IOlkAccount::SaveChanges to save such changes.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::SaveChanges


IOlkAccount::SetProp

 Copy code hover
[image]

IOlkAccount::SetProp
See also Send feedback

Sets the value of the specified account property.

Quick Info

See IOlkAccount.

Copy code Copy code
HRESULT IOlkAccount::SetProp(
    DWORD dwProp,
    ACCT_VARIANT *pVar
);

Parameters

dwProp

[in] The property tag of the account property to set.

pVar

[in] The value of the specified property.

Return Values

HRESULT | Description
S_OK | The method call was successful.
E_INVALIDARG | An invalid property tag was specified.

Remarks

Use IOlkAccount::SaveChanges to save changes to the value of account properties.

See also

Concepts

Constants (Account management API)
IOlkAccount::GetProp


IOlkAccountHelper

 Copy code hover
[image]

IOlkAccountHelper
See also Send feedback

Provides helper functionality in the current MAPI session to manage accounts.

Quick Info

Inherits from: | IUnknown
Provided by: | Client
Interface identifier: | IID_IOlkAccountHelper

Vtable Order

Placeholder1 | This member is a placeholder and is not supported.
GetIdentity | Gets the profile name of an account.
GetMapiSession | Opens a MAPI session and maintains a reference to the session for the account manager.
HandsOffSession | Releases the MAPI session object that was returned by IOlkAccountHelper::GetMapiSession.

Remarks

This interface is passed to IOlkAccountManager::Init when initializing the account manager.

See also

Concepts

About the Account Management API
Constants (Account management API)


IOlkAccountHelper::GetIdentity

 Copy code hover
[image]

IOlkAccountHelper::GetIdentity
See also Send feedback

Gets the profile name of an account.

Quick Info

See IOlkAccountHelper.

Copy code Copy code
HRESULT IOlkAccountHelper::GetIdentity (
    LPWSTR pwszIdentity,
    DWORD *pcch
);

Parameters

pwszIdentity

[in][out] The profile name.

pcch

[in] [out] Upon calling this method, contains the size (in number of characters) of pwszIdentity that has been allocated. Upon return, contains the actual length, including the 0-terminating character, of the returned profile name.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_OUTOFMEMORY | The returned profile name is longer than the size of pwszIdentity.
E_INVALIDARG | pcch is NULL.

Remarks

If pwszIdentity is too small to hold the profile name, it will not be set on return, and pcch will point to the size required for pwszIdentity.

See also

Reference

PidTagProfileName

Concepts

About the Account Management API


IOlkAccountHelper::GetMapiSession

 Copy code hover
[image]

IOlkAccountHelper::GetMapiSession
See also Send feedback

Opens a MAPI session and maintains a reference to the session for the account manager.

Quick Info

See IOlkAccountHelper.

Copy code Copy code
HRESULT IOlkAccountHelper::GetMapiSession(
    LPUNKNOWN *ppmsess
);

Parameters

ppmsess

[out] The current MAPI session.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

Because of circular reference problems, the account manager itself cannot maintain the reference for the MAPI session.

See also

Reference

IMAPISession : IUnknown

Concepts

IOlkAccountHelper::HandsOffSession


IOlkAccountHelper::HandsOffSession

 Copy code hover
[image]

IOlkAccountHelper::HandsOffSession
See also Send feedback

Releases the MAPI session object that was returned by IOlkAccountHelper::GetMapiSession.

Quick Info

See IOlkAccountHelper.

Copy code Copy code
HRESULT IOlkAccountHelper::HandsOffSession( );

Return Values

HRESULT | Description
S_OK | If your implementation of IOlkAccountHelper creates its own MAPI session that is returned in IOlkAccountHelper::GetMapiSession, you must release the session here and return S_OK.
E_NOTIMPL | If your implementation of IOlkAccountHelper did not create its own MAPI session, you must return only E_NOTIMPL. In this case, this is the only supported return value.

See also

Concepts

Constants (Account management API)
IOlkAccountHelper::GetMapiSession


IOlkAccountHelper::Placeholder1

 Copy code hover
[image]

IOlkAccountHelper::Placeholder1
See also Send feedback

This member is a placeholder and is not supported. It must always return E_NOTIMPL.

Quick Info

Copy code Copy code
HRESULT IOlkAccountHelper::Placeholder1 (
    void*
);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IOlkAccountHelper and is not supported.

Remarks

This member must always return E_NOTIMPL.

See also

Concepts

Constants (Account management API)


IOlkAccountManager

 Copy code hover
[image]

IOlkAccountManager
See also Send feedback

Manages access to accounts and sets up notifications about account changes.

Quick Info

Inherits from: | IOlkErrorUnknown
Implemented by: | Outlook
Provided by: | CLSID_OlkAccountManager
Called by: | Client
Interface identifier: | IID_IOlkAccountManager

Vtable Order

Init | Initializes the account manager for use.
DisplayAccountList | Displays either the Account Settings or Add New Account dialog box.
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
FindAccount | Finds an account by property value.
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
DeleteAccount | Deletes the specified account.
Placeholder member | Not supported or documented
SaveChanges | Saves changes to the specified account.
GetOrder | Gets the ordering of the specified category of accounts.
SetOrder | Modifies the ordering of the specified category of accounts.
EnumerateAccounts | Gets an enumerator for the accounts of the specific category and type.
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
FreeMemory | Frees memory allocated by the IOlkAccountManager interface.
Advise | Registers a client with the account manager for notifications regarding all accounts.
Unadvise | Unregisters a client with the account manager for notifications for all accounts.
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented
Placeholder member | Not supported or documented

See also

Concepts

About the Account Management API


IOlkAccountManager::Advise

 Copy code hover
[image]

IOlkAccountManager::Advise
See also Send feedback

Registers a client with the account manager for notifications regarding all accounts.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::Advise (
    IOlkAccountNotify *pNotify,
    DWORD *pdwCookie
);

Parameters

pNotify

[in] An IOlkAccountNotify interface that the account manager will use to send notifications to the client.

pdwCookie

[out] A cookie that IOlkAccountManager::Unadvise will use when removing the registration for the account.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_INVALIDARG | An invalid argument has been provided.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::Unadvise


IOlkAccountManager::DeleteAccount

 Copy code hover
[image]

IOlkAccountManager::DeleteAccount
See also Send feedback

Deletes the specified account.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::DeleteAccount (
    DWORD dwAcctID,
);

Parameters

dwAcctID

[in] The account ID of the account to be deleted.

Return Values

HRESULT | Description
S_OK | The call succeeded
E_ACCT_NOT_FOUND | The specified account cannot be found.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::FindAccount


IOlkAccountManager::DisplayAccountList

 Copy code hover
[image]

IOlkAccountManager::DisplayAccountList
Send feedback

Displays either the Account Settings or Add New Account dialog box.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::DisplayAccountList (
    HWND hwnd,
    DWORD dwFlags,
    LPCWSTR wszTitle,
    DWORD cCategories,
    const CLSID * rgclsidCategories,
    const CLSID * pclsidType
);

Parameters

hwnd

[in] The handle to the window to which the displayed dialog box is modal. May be zero.

dwFlags

[in] Flags to modify the behavior of the display.

  • ACCTUI_NO_WARNING—Do not display the warning that changes will not take effect until Outlook is restarted. Applies only if the application is running in-process with Outlook.exe.

  • ACCTUI_SHOW_DATA_TAB—Show the Account Settings dialog box with the Data tab selected. Valid only if ACCTUI_SHOW_ACCTWIZARD is not set.

  • ACCTUI_SHOW_ACCTWIZARD—Display the Add New Account dialog box.

wszTitle

[in] This parameter is not used and should be NULL.

cCategories

[in] This parameter is not used and must be NULL.

rgclsidCategories

[in] This parameter is not used and must be NULL.

pclsidType

[in] This parameter is not used and must be NULL.

Return Values

HRESULT | Description
S_OK | The call was successful.
E_ACCT_UI_BUSY | The dialog box could not be created.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.
MAPI_E_CALL_FAILED | The Add New Account dialog box returned an error.
MAPI_E_INVALID_PARAMETER | The cCategories, rgclsidCategories, or pclsidType parameter is non-NULL.
MAPI_E_USER_CANCEL | The Account Settings dialog box returned an error.

Remarks

The cCategories, rgclsidCategories, and pclsidType parameters are not used at this time and must be NULL. wszTitle is not used and should also be NULL.


IOlkAccountManager::EnumerateAccounts

 Copy code hover
[image]

IOlkAccountManager::EnumerateAccounts
See also Send feedback

Gets an enumerator for the accounts of the specific category or type.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::EnumerateAccounts (
    const CLSID *pclsidCategory,
    const CLSID *pclsidType,
    DWORD dwFlags,
    IOlkEnum **ppEnum
);

Parameters

pclsidCategory

[in] The class identifier of the category to enumerate. The value must be one of the following:

  • CLSID_OlkMail

  • CLSID_OlkAddressBook

  • CLSID_OlkStore

pclsidType

[in] The class identifier of the account type to enumerate. The value must be one of the following:

  • CLSID_OlkPOP3Account

  • CLSID_OlkIMAP4Account

  • CLSID_OlkMAPIAccount

  • CLSID_OlkHotmailAccount

  • CLSID_OlkLDAPAccount

dwFlags

[in] Flags to modify behavior. The only supported value is OLK_ACCOUNT_NO_FLAGS.

ppEnum

[out] An enumerator that supports the IOlkEnum interface.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

Remarks

Specifying NULL for category returns an enumerator of all accounts of the specified type. Similarly, specifying NULL for type returns an enumerator of all accounts of the specified category.

IOlkAccountManager::EnumerateAccounts does not support the address book category for an Exchange account. If the account is an Exchange account (pclsidType is CLSID_OlkMAPIAccount), and you are trying to enumerate accounts that implement the address book (prgclsidCategory is CLSID_OlkAddressBook), calling IOlkAccountManager::EnumerateAccounts will not return the Exchange account in the accounts enumerator ppEnum.

See also

Concepts

Constants (Account management API)
IOlkEnum


IOlkAccountManager::FindAccount

 Copy code hover
[image]

IOlkAccountManager::FindAccount
See also Send feedback

Finds an account by property value.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::FindAccount (
    DWORD dwProp,
    ACCT_VARIANT *pVar,
    IOlkAccount **ppAccount
);

Parameters

dwProp

[in] The property to search on. Must be PROP_ACCT_ID or PROP_ACCT_IS_EXCH.

pVar

[in] The value to match.

ppAccount

[out] The account found. This object supports an IOlkAccount interface.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_ACCT_NOT_FOUND | The specified account cannot be found.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.
E_OLK_PARAM_NOT_SUPPORTED | One or more parameters are invalid.

See also

Concepts

ACCT_VARIANT
Constants (Account management API)
IOlkAccountHelper


IOlkAccountManager::FreeMemory

 Copy code hover
[image]

IOlkAccountManager::FreeMemory
See also Send feedback

Frees memory allocated by the IOlkAccountManager interface.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::FreeMemory (
    BYTE *pv,
);

Parameters

pv

[in] A pointer to the memory to free.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

Use this method to release memory allocated by IOlkAccountManager::GetOrder.

See also

Concepts

IOlkAccountManager::GetOrder


IOlkAccountManager::GetOrder

 Copy code hover
[image]

IOlkAccountManager::GetOrder
See also Send feedback

Gets the ordering of the specified category of accounts.

Quick Info

See IOlkAccountManager

Copy code Copy code
HRESULT IOlkAccountManager::GetOrder (
    const CLSID *pclsidCategory,
    DWORD *pcAccts,
    DWORD *prgAccts[]
);

Parameters

pclsidCategory

[in] The category class ID for which to get the order. The value must be one of the following:

  • CLSID_OlkMail

  • CLSID_OlkAddressBook

  • CLSID_OlkStore

pcAccts

[out] The number of accounts.

prgAccts

[out] A pointer to an array of accounts.

Return Values

HRESULT | Description
S_OK | The call succeeded
E_INVALIDARG | One or more arguments are invalid.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

Remarks

Before calling this method, the caller allocates only an array pointer prgAccts but no memory for the array at which prgAccts points. After this method returns, the caller must use IOlkAccountManager::FreeMemory to release the memory allocated for prgAccts.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::SetOrder


IOlkAccountManager::Init

 Copy code hover
[image]

IOlkAccountManager::Init
See also Send feedback

Initializes the account manager for use.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::Init (
    IOlkAccountHelper *pAcctHelper,
    DWORD dwFlags
);

Parameters

pAcctHelper

[in] An IOlkAccountHelper interface that provides account helper functionality.

dwFlags

[in] Flags to modify behavior.

  • ACCT_INIT_NO_STORES_CHECK—Prevents an account (such as an IMAP account) from synchronizing with an associated store.

  • ACCT_INIT_NOSYNCH_MAPI_ACCTS—Prevents MAPI services from synchronizing with accounts.

  • OLK_ACCOUNT_NO_FLAGS —Synchronizes MAPI services with accounts.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_OLK_ALREADY_INITIALIZED | Init has already been called.
E_OLK_REGISTRY | The account manager could not access the required registry settings.

Remarks

The client must call IOlkAccountManager::Init to initialize the account manager before using the account manager to access accounts or set up notifications. Because Outlook automatically synchronizes MAPI services with accounts on startup, use ACCT_INIT_NOSYNCH_MAPI_ACCTS unless there is a specific cause to synchronize.

See also

Concepts

Constants (Account management API)


IOlkAccountManager::SaveChanges

 Copy code hover
[image]

IOlkAccountManager::SaveChanges
See also Send feedback

Saves changes to the specified account.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT IOlkAccountManager::SaveChanges (
    DWORD dwAcctID,
    DWORD dwFlags
);

Parameters

dwAcctID

[in] The account ID to save.

dwFlags

[in] Flags to modify behavior. OLK_ACCOUNT_NO_FLAGS is the only supported value.

Return Values

HRESULT | Description
S_OK | The call succeeded
E_ACCT_NOT_FOUND | The specified account cannot be found.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

Remarks

After changing the value of account properties by using IOlkAccount::SetProp, use IOlkAccountManager::SaveChanges or IOlkAccount::SaveChanges to save such changes.

See also

Concepts

Constants (Account management API)
IOlkAccount::SaveChanges


IOlkAccountManager::SetOrder

 Copy code hover
[image]

IOlkAccountManager::SetOrder
See also Send feedback

Modifies the ordering of the specified category of accounts.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT SetOrder(
    const CLSID * pclsidCategory,
    DWORD cAccts,
    DWORD rgAccts[]
);

Parameters

pclsidCategory

[in] The category class ID for which to set the order. The value must be one of the following:

  • CLSID_OlkAddressBook

  • CLSID_OlkStore

cAccts

[in] The number of accounts.

rgAccts

[in] An array of account IDs. The size of the array is cAccts.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_ACCT_WRONG_SORT_ORDER | The new sort order has a different number of accounts than the old sort order.
E_INVALIDARG | One or more arguments are invalid.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

Remarks

The caller allocates memory for the array pointer prgAccts as well as for the array at which prgAccts points.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::GetOrder


IOlkAccountManager::Unadvise

 Copy code hover
[image]

IOlkAccountManager::Unadvise
See also Send feedback

Unregisters a client with the account manager for notifications for all accounts.

Quick Info

See IOlkAccountManager.

Copy code Copy code
HRESULT Unadvise(
    DWORD dwCookie
);

Parameters

dwCookie

[in] The cookie returned by IOlkAccountManager::Advise.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_INVALIDARG | One or more arguments are invalid.
E_OLK_NOT_INITIALIZED | The account manager has not been initialized for use.

See also

Concepts

Constants (Account management API)
IOlkAccountManager::Advise


IOlkAccountNotify

 Copy code hover
[image]

IOlkAccountNotify
See also Send feedback

Provides a callback to the client for changes to an account.

Quick Info

Inherits from: | IOlkErrorUnknown
Provided by: | Client
Interface identifier: | IID_IOlkAccountNotify

Vtable Order

Notify

Notifies the client of changes to the specified account.

Remarks

This interface is passed to IOlkAccountManager::Advise when setting up notifications.

See also

Concepts

About the Account Management API
Constants (Account management API)


IOlkAccountNotify::Notify

 Copy code hover
[image]

IOlkAccountNotify::Notify
See also Send feedback

Notifies the client of changes to the specified account.

Quick Info

See IOlkAccountNotify.

Copy code Copy code
HRESULT IOlkAccount::Notify(
    DWORD dwNotify,
    DWORD dwAcctID,
    DWORD dwFlags
);

Parameters

dwNotify

[in] The type of notification. The value must be one of the following:

  • NOTIFY_ACCT_CHANGED

  • NOTIFY_ACCT_CREATED

  • NOTIFY_ACCT_DELETED

  • NOTIFY_ACCT_ORDER_CHANGED

  • NOTIFY_ACCT_PREDELETED

dwAcctID

[in] The account ID of the account that has been created, changed, deleted, or pre-deleted.

dwFlags

[in] Not used. OLK_ACCOUNT_NO_FLAGS is the only supported value.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

Constants (Account management API)
IOlkAccountManager


IOlkEnum

 Copy code hover
[image]

IOlkEnum
See also Send feedback

Supports enumerating accounts as IUnknown objects.

Quick Info

Inherits from: | IUnknown
Implemented by: | Outlook
Provided by: | IOlkAccountManager::EnumerateAccounts
Called by: | Client
Interface identifier: | IID_IOlkEnum

Vtable Order

GetCount | Gets the number of accounts in the enumerator.
Reset | Resets the enumerator to the beginning.
GetNext | Gets the next account in the enumerator.
Skip | Skips a specified number of accounts in the enumerator.

Remarks

This interface is returned by IOlkAccountManager::EnumerateAccounts when obtaining an enumerator of accounts.

See also

Concepts

About the Account Management API
Constants (Account management API)


IOlkEnum::GetCount

 Copy code hover
[image]

IOlkEnum::GetCount
See also Send feedback

Gets the number of accounts in the enumerator.

Quick Info

See IOlkEnum.

Copy code Copy code
HRESULT IOlkEnum::GetCount (
    DWORD *pulCount
);

Parameters

pulCount

[out] A pointer to the number of objects being enumerated.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

IOlkEnum::GetNext
IOlkEnum::Reset
IOlkEnum::Skip


IOlkEnum::GetNext

 Copy code hover
[image]

IOlkEnum::GetNext
See also Send feedback

Gets the next account in the enumerator.

Quick Info

See IOlkEnum.

Copy code Copy code
HRESULT IOlkEnum:: GetNext(
    LPUNKNOWN *ppunk
);

Parameters

ppunk

[in] A pointer to an IUnknown interface that the client can query to obtain an IOlkAccount interface.

Return Values

HRESULT | Description
S_OK | The call succeeded.
S_FALSE | The enumerator has reached the end.

Remarks

The interface specified by ppunk inherits from IUnknown. The client can query this interface (using IUnknown::QueryInterface) to obtain a pointer to an IOlkAccount interface, and get or set information for this account.

See also

Concepts

Constants (Account management API)
IOlkEnum::GetCount
IOlkEnum::Reset
IOlkEnum::Skip


IOlkEnum::Reset

 Copy code hover
[image]

IOlkEnum::Reset
See also Send feedback

Resets the enumerator to the beginning.

Quick Info

See IOlkEnum.

Copy code Copy code
HRESULT IOlkEnum::Reset ();

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

IOlkEnum::GetCount
IOlkEnum::GetNext
IOlkEnum::Skip


IOlkEnum::Skip

 Copy code hover
[image]

IOlkEnum::Skip
See also Send feedback

Skips a specified number of accounts in the enumerator.

Quick Info

See IOlkEnum.

Copy code Copy code
HRESULT IOlkEnum::Skip(
    DWORD cSkip
);

Parameters

cSkip

[in] The number of accounts to be skipped.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

IOlkEnum::GetCount
IOlkEnum::GetNext
IOlkEnum::Reset


IOlkErrorUnknown

 Copy code hover
[image]

IOlkErrorUnknown
See also Send feedback

Provides extra information about the last error.

Quick Info

Inherits from: | IUnknown
Provided by: | Client
Interface identifier: | IID_IOlkErrorUnknown

Vtable Order

GetLastError

Gets a message string for the specified error.

Remarks

This interface provides extra information about an error in IOlkAccountManager, IOlkAccountNotify, and IOlkAccount. It is also the base interface for IOlkAccountManager, IOlkAccountNotify, and IOlkAccount.

See also

Concepts

About the Account Management API


IOlkErrorUnknown::GetLastError

 Copy code hover
[image]

IOlkErrorUnknown::GetLastError
See also Send feedback

Gets a message string for the specified error.

Quick Info

See IOlkErrorUnknown.

Copy code Copy code
HRESULT IOlkErrorUnknown::GetLastError(
    HRESULT hr,
    LPWSTR *ppwszError
);

Parameters

hr

[in] The error code to look up.

ppwszError

[out] The error message that corresponds to hr.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_INVALIDARG | One or more arguments are invalid.

See also

Concepts

Constants (Account management API)


Named properties (Account management API)

 Copy code hover
[image]

Named properties (Account management API)
Send feedback

This section describes the named properties in the Account Management API.

Named property | Description
PidLidInternetAccountName | Returns the display name of the account that delivered the message.
PidLidInternetAccountStamp | Returns the account stamp of the account that delivered the message.


PidLidInternetAccountName

 Copy code hover
[image]

PidLidInternetAccountName
See also Send feedback

Returns the display name of the account that delivered the message.

Quick Info

Associated properties: | dispidInetAcctName
Property set: | PSETID_Common
Long ID (LID): | 0x00008580
Data type: | PT_UNICODE
Area: | General messaging

Remarks

This property should contain the same value that is returned from the Account Management API property PROP_ACCT_NAME for the account that delivered the message.

Message store providers expose this named property and PidLidInternetAccountStamp so that the following actions occur:

  • When a user clicks Reply to All in an email message, Outlook removes the email address that is associated with the account and is stamped on the message from the recipient list of the reply. This behavior occurs unless this email address is the sender of the original message.

  • By default, Outlook sends replies and forwarded messages through the account that is stamped on the original message.

Usually, the Outlook Protocol Manager delivers messages, and Outlook sets the PidLidInternetAccountName and PidLidInternetAccountStamp properties to indicate the account that delivered the message. However, if a message store is tightly coupled with a transport, the Outlook Protocol Manager does not deliver messages and Outlook cannot set these properties. In this scenario, Outlook calls the IMAPIProp::GetIDsFromNames function. If the message store provider wants to expose these named properties, it should implement IMAPIProp::GetIDsFromNames and return property tags through the output parameter lppPropTags. Outlook can then call the IMAPIProp::GetProps method by using these property tags, and the message store provider can return the account name and stamp of the desired account.

To support these named properties, store providers should expect Outlook to use IMAPIProp::GetIDsFromNames to obtain the property tag for this property. Outlook specifies the following values for the MAPINAMEID structure that corresponds to this named property, which is passed as part of the array pointed at by the input parameter lppPropNames of IMAPIProp::GetIDsFromNames.

lpGuid: | PSETID_Common
ulKind: | MNID_ID
Kind.lID: | dispidInetAcctName

See also

Reference

PidLidInternetAccountName Canonical Property

Concepts

About the Account Management API
Constants (Account management API)


PidLidInternetAccountStamp

 Copy code hover
[image]

PidLidInternetAccountStamp
See also Send feedback

Returns the account stamp of the account that delivered the message.

Quick Info

Associated properties: | dispidInetAcctStamp
Property set: | PSETID_Common
Long ID (LID): | 0x00008581
Data type: | PT_UNICODE
Area: | General messaging

Remarks

This property should contain the same value that is returned from the Account Management API property PROP_ACCT_STAMP for the account that delivered the message.

Message store providers expose this named property and PidLidInternetAccountName so that the following actions occur:

  • When a user clicks Reply to All in an email message, Outlook removes the email address that is associated with the account and is stamped on the message from the recipient list of the reply. This behavior occurs unless this email address is the sender of the original message.

  • By default, Outlook sends replies and forwarded messages through the account that is stamped on the original message.

Usually, the Outlook Protocol Manager delivers messages, and Outlook sets the PidLidInternetAccountName and PidLidInternetAccountStamp properties to indicate the account that delivered the message. However, if a message store is tightly coupled with a transport, the Outlook Protocol Manager does not deliver messages and Outlook cannot set these properties. In this scenario, Outlook calls the IMAPIProp::GetIDsFromNames function. If the message store provider wants to expose these named properties, it should implement IMAPIProp::GetIDsFromNames and return property tags through the output parameter lppPropTags. Outlook can then call the IMAPIProp::GetProps method by using these property tags, and the message store provider can return the account name and stamp of the desired account.

To support these named properties, store providers should expect Outlook to use IMAPIProp::GetIDsFromNames to obtain the property tag for this property. Outlook specifies the following values for the MAPINAMEID structure that corresponds to this named property, which is passed as part of the array pointed at by the input parameter lppPropNames of IMAPIProp::GetIDsFromNames.

lpGuid: | PSETID_Common
ulKind: | MNID_ID
Kind.lID: | dispidInetAcctStamp

See also

Reference

PidLidInternetAccountStamp Canonical Property

Concepts

About the Account Management API
Constants (Account management API)


Properties (Account management API)

 Copy code hover
[image]

Properties (Account management API)
Send feedback

This section describes the properties in the Account Management API.

Property | Description
PidTagNextSendAcct | This is the secondary account "send" stamp for the message.
PidTagPrimarySendAccount | This is the primary account "send" stamp for a message.
PROP_ACCT_DELIVERY_FOLDER | Represents the Entry ID of the default delivery folder for the account.
PROP_ACCT_DELIVERY_STORE | Represents the Entry ID of the default delivery store for the account.
PROP_ACCT_ID | Returns an identifier that uniquely identifies an account within the profile in which the account is created.
PROP_ACCT_IS_EXCH | True if the account is an Exchange account.
PROP_ACCT_MINI_UID | Returns an account identifier that is unique across Outlook profiles.
PROP_ACCT_NAME | Returns or sets the account name.
PROP_ACCT_PREFERENCES_UID | Retrieves the unique identifier (UID) for the profile section that stores the account preferences.
PROP_ACCT_SEND_STAMP | Returns the account "send" stamp.
PROP_ACCT_SENTITEMS_EID | Represents the Entry ID of the default folder for sent items for the account.
PROP_ACCT_STAMP | Returns the account stamp.
PROP_ACCT_USER_EMAIL_ADDR | Specifies the email address for the account.
PROP_ACCT_USER_DISPLAY_NAME | Returns or sets the user display name.
PROP_INET_PASSWORD | Represents the user password for a general Internet mailbox.
PROP_INET_PORT | Represents the port number for a general Internet mailbox.
PROP_INET_SERVER | Represents the server name of a general Internet mailbox.
PROP_INET_SSL | Specifies whether Secure Socket Layer (SSL) should be used for a general Internet mailbox.
PROP_INET_USE_SPA | Specifies whether Secure Password Authentication (SPA) should be used for a general Internet mailbox.
PROP_INET_USER | Represents the user name for a general Internet mailbox.
PROP_MAPI_EMSMDB_UID | Represents an ACCT_BIN structure that contains the UID of an Exchange account.
PROP_MAPI_IDENTITY_ENTRYID | Retrieves or sets the address book entry ID for the account.
PROP_MAPI_TRANSPORT_FLAGS | Represents transport settings that Outlook uses to determine the necessary synchronization tasks and to disable the user interface (UI) elements that the account does not support.
PROP_POP_LEAVE_ON_SERVER | Specifies leaving a copy of a message on the server for a POP account.
PROP_SMTP_AUTH_METHOD | Specifies the authentication method to use for the SMTP account.
PROP_SMTP_PASSWORD | Represents the password of the SMTP account.
PROP_SMTP_PORT | Represents the port number of the SMTP account.
PROP_SMTP_SECURE_CONNECTION | Specifies the type of encrypted connection to use for an SMTP account.
PROP_SMTP_SERVER | Represents the server name of the SMTP account.
PROP_SMTP_SSL | Specifies whether to use Secure Socket Layer (SSL) protocol for the SMTP account.
PROP_SMTP_USE_AUTH | Specifies whether to use authentication for the SMTP account.
PROP_SMTP_USE_SPA | Specifies whether to use Secure Password Authentication (SPA) for the SMTP account.
PROP_SMTP_USER | Represents the user name for the SMTP account.


PidTagNextSendAcct

 Copy code hover
[image]

PidTagNextSendAcct
See also Send feedback

Specifies the secondary account "send" stamp for the message.

Quick Info

Associated properties: | PR_NEXT_SEND_ACCT
Identifier: | 0x0E29
Data type: | PT_UNICODE
Area: | Outlook application

Remarks

This property applies to a MAPI message object. For a received message, the secondary account "send" stamp indicates which account a forward or a reply should be sent with, if the forward or reply cannot be sent with the primary account. For an outgoing message, the secondary account "send" stamp determines with which account to send the message, if the message cannot be sent with the primary account. Its value is the PROP_ACCT_SEND_STAMP value from the IOlkAccount interface of the account with which the message is being sent.

See also

Reference

PidTagNextSendAcct Canonical Property

Concepts

MAPI Properties
Constants (Account management API)


PidTagPrimarySendAccount

 Copy code hover
[image]

PidTagPrimarySendAccount
See also Send feedback

Specifies the primary account "send" stamp for a message.

Quick Info

Associated properties: | PR_PRIMARY_SEND_ACCOUNT
Identifier: | 0x0E28
Data type: | PT_UNICODE
Area: | Account

Remarks

This property applies to a MAPI message object. For a received message, the primary account "send" stamp indicates which account a forward or a reply should be sent with. For an outgoing message, it determines which account to send the message with. Its value is the PROP_ACCT_SEND_STAMP value from the IOlkAccount interface of the account with which the message is being sent.

See also

Reference

PidTagPrimarySendAccount Canonical Property

Concepts

Constants (Account management API)
MAPI Properties


PROP_ACCT_DELIVERY_FOLDER

 Copy code hover
[image]

PROP_ACCT_DELIVERY_FOLDER
See also Send feedback

Represents the Entry ID of the default delivery folder for the account.

Quick Info

See IOlkAccount.

Identifier: | 0x0019
Property type: | PT_BINARY
Property tag: | 0x00190102
Access: | Read/write

Remarks

Get or set this property by using IOlkAccount::GetProp or IOlkAccount::SetProp, respectively.

The default delivery folder is Inbox.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_DELIVERY_STORE

 Copy code hover
[image]

PROP_ACCT_DELIVERY_STORE
See also Send feedback

Represents the Entry ID of the default delivery store for the account.

Quick Info

See IOlkAccount.

Identifier: | 0x0018
Property type: | PT_BINARY
Property tag: | 0x00180102
Access: | Read/write

Remarks

Get or set this property by using IOlkAccount::GetProp or IOlkAccount::SetProp, respectively.

One of the side effects of setting a store as the default delivery store for an account is that when starting Outlook, Outlook creates search folders for that store if they do not already exist, and list the store in the To-Do Bar.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_ID

 Copy code hover
[image]

PROP_ACCT_ID
See also Send feedback

Returns an identifier that uniquely identifies an account within the profile in which the account is created.

Quick Info

See IOlkAccount.

Identifier: | 0x0001
Property type: | PT_LONG
Property tag: | 0x00010003
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp. If the client attempts to set this property, this property returns E_OLK_PROP_READ_ONLY.

This property is different from PROP_ACCT_MINI_UID in that its value is unique only among all the accounts within that profile in which the account was created, whereas PROP_ACCT_MINI_UID uniquely identifies the account within and outside of the profile in which the account was created. When a message with these properties roams onto a second computer with a different Outlook profile and different set of accounts, PROP_ACCT_ID can possibly conflict with an account in the profile of the second computer, and PROP_ACCT_MINI_UID can uniquely identify the original account in the original profile.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_IS_EXCH

 Copy code hover
[image]

PROP_ACCT_IS_EXCH
See also Send feedback

True if the account is an Exchange account.

Quick Info

See IOlkAccount.

Identifier: | 0x0014
Property type: | PT_LONG
Property tag: | 0x00140003
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp. If the client attempts to set this property, this property returns E_OLK_PROP_READ_ONLY.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_MINI_UID

 Copy code hover
[image]

PROP_ACCT_MINI_UID
See also Send feedback

Returns an account identifier that is unique across Outlook profiles.

Quick Info

See IOlkAccount.

Identifier: | 0x0003
Property type: | PT_LONG
Property tag: | 0x00030003
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp. If the client attempts to set this property, this property returns E_OLK_PROP_READ_ONLY.

This property is different from PROP_ACCT_ID in that its value uniquely identifies the account within and outside of the profile in which the account was created, whereas PROP_ACCT_ID is unique only among all the accounts within that one profile in which the account was created. When a message with these properties roams onto a second computer with a different Outlook profile and different set of accounts, PROP_ACCT_MINI_UID can uniquely identify the original account in the original profile. However, PROP_ACCT_ID can possibly conflict with an account in the profile of the second computer.

See also

Concepts

PROP_ACCT_ID
About the Account Management API
Constants (Account management API)


PROP_ACCT_NAME

 Copy code hover
[image]

PROP_ACCT_NAME
See also Send feedback

Returns or sets the account name.

Quick Info

See IOlkAccount.

Identifier: | 0x0002
Property type: | PT_UNICODE
Property tag: | 0x0002001F
Access: | Read/write

Remarks

Get or set this property by using IOlkAccount::GetProp or IOlkAccount::SetProp, respectively.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_PREFERENCES_UID

 Copy code hover
[image]

PROP_ACCT_PREFERENCES_UID
See also Send feedback

Retrieves the unique identifier (UID) for the profile section that stores the account preferences.

Quick Info

See IOlkAccount.

Identifier: | 0x0022
Property type: | PT_BINARY
Property tag: | 0x00220102
Access: | Read-only

Remarks

Use PROP_ACCT_PREFERENCES_UID in calls to IMAPISupport::OpenProfileSection to retrieve the profile section that contains account preferences.

See also

Concepts

About the Account Management API
About anti-spam settings


PROP_ACCT_SEND_STAMP

 Copy code hover
[image]

PROP_ACCT_SEND_STAMP
See also Send feedback

Returns the account "send" stamp.

Quick Info

See IOlkAccount.

Identifier: | 0x000E
Property type: | PT_UNICODE
Property tag: | 0x000E001F
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp. If the client attempts to set this property, this property returns E_OLK_PROP_READ_ONLY.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_SENTITEMS_EID

 Copy code hover
[image]

PROP_ACCT_SENTITEMS_EID
Send feedback

Represents the Entry ID of the default folder for sent items for the account.

Quick Info

See IOlkAccount.

Identifier: | 0x0020
Property type: | PT_BINARY
Property tag: | 0x00200102
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp.

The default folder for sent items is Sent Items.

This property is read-only for POP3 and IMAP accounts. Attempting to set this property for these types of accounts returns E_ACCT_NOT_FOUND.


PROP_ACCT_STAMP

 Copy code hover
[image]

PROP_ACCT_STAMP
See also Send feedback

Returns the account stamp.

Quick Info

See IOlkAccount.

Identifier: | 0x000D
Property type: | PT_UNICODE
Property tag: | 0x000D001F
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp. If the client attempts to set this property, this property returns E_OLK_PROP_READ_ONLY.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_USER_DISPLAY_NAME

 Copy code hover
[image]

PROP_ACCT_USER_DISPLAY_NAME
See also Send feedback

Returns or sets the user display name.

Quick Info

See IOlkAccount.

Identifier: | 0x000B
Property type: | PT_UNICODE
Property tag: | 0x000B001F
Access: | Read/write

Remarks

Get or set this property by using IOlkAccount::GetProp or IOlkAccount::SetProp, respectively.

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_ACCT_USER_EMAIL_ADDR

 Copy code hover
[image]

PROP_ACCT_USER_EMAIL_ADDR
See also Send feedback

Specifies the email address for the account.

Quick Info

See IOlkAccount.

Identifier: | 0x000C
Property type: | PT_UNICODE
Property tag: | 0x000C001F
Access: | Read/write

Remarks

PROP_ACCT_USER_EMAIL_ADDR is not expected to exist on every account. For example, an Exchange account could have PROP_MAPI_IDENTITY_ENTRYID but not PROP_ACCT_USER_EMAIL_ADDR, while for an SMTP/POP3 account, the situation is reversed.

See also

Concepts

About the Account Management API


PROP_INET_USER

 Copy code hover
[image]

PROP_INET_USER
See also Send feedback

Represents the user name for a general Internet mailbox.

Quick Info

Identifier: | 0x0101
Property type: | PT_UNICODE
Property tag: | 0x0101001F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_INET_USE_SPA

 Copy code hover
[image]

PROP_INET_USE_SPA
See also Send feedback

Specifies whether to use Secure Password Authentication (SPA) for a general Internet mailbox.

Quick Info

Identifier: | 0x0108
Property type: | PT_DWORD
Property tag: | 0x01080003
Access: | Read-only

Remarks

A zero value means do not use SPA, otherwise use SPA.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_INET_SSL

 Copy code hover
[image]

PROP_INET_SSL
See also Send feedback

Specifies whether to use Secure Socket Layer (SSL) for a general Internet mailbox.

Quick Info

Identifier: | 0x0105
Property type: | PT_DWORD
Property tag: | 0x01050003
Access: | Read-only

Remarks

A zero value means do not use SSL, otherwise use SSL.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_INET_SERVER

 Copy code hover
[image]

PROP_INET_SERVER
See also Send feedback

Represents the server name of a general Internet mailbox.

Quick Info

Identifier: | 0x0100
Property type: | PT_UNICODE
Property tag: | 0x0100001F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_INET_PORT

 Copy code hover
[image]

PROP_INET_PORT
See also Send feedback

Represents the port number for a general Internet mailbox.

Quick Info

Identifier: | 0x0104
Property type: | PT_DWORD
Property tag: | 0x01040003
Access: | Read-only

Remarks

An example is 110 for POP accounts.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_INET_PASSWORD

 Copy code hover
[image]

PROP_INET_PASSWORD
See also Send feedback

Represents the user password for a general Internet mailbox.

Quick Info

Identifier: | 0x0102
Property type: | PT_UNICODE|SECURE_FLAG
Property tag: | 0x0102801F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_MAPI_EMSMDB_UID

 Copy code hover
[image]

PROP_MAPI_EMSMDB_UID
See also Send feedback

Represents an ACCT_BIN structure that contains the UID of an Exchange account.

Quick Info

See IOlkAccount.

Identifier: | 0x2009
Property type: | PT_BINARY
Property tag: | 0x20090102
Access: | Read-only

Remarks

Get this property by using IOlkAccount::GetProp.

Use PROP_ACCT_IS_EXCH to verify if the account is an Exchange account. If it is, PROP_MAPI_EMSMDB_UID is an ACCT_BIN that contains the emsmdbUID, which is the unique ID, for the Exchange account. If the account is not an Exchange account, this property is undefined.

See also

Reference

PidTagExchangeProfileSectionId Canonical Property

Concepts

About the Account Management API
Constants (Account management API)
Using Multiple Exchange Accounts


PROP_MAPI_IDENTITY_ENTRYID

 Copy code hover
[image]

PROP_MAPI_IDENTITY_ENTRYID
See also Send feedback

Retrieves or sets the address book entry ID for the account.

Quick Info

See IOlkAccount.

Identifier: | 0x2002
Property type: | PT_BINARY
Property tag: | 0x20020102
Access: | Read/write

Remarks

PROP_MAPI_IDENTITY_ENTRYID is not expected to exist on every account. For example, an Exchange account could have PROP_MAPI_IDENTITY_ENTRYID set and not PROP_ACCT_USER_EMAIL_ADDR, while for an SMTP/POP3 account the situation is reversed. PROP_MAPI_IDENTITY_ENTRYID returns an entry ID that is similar to the value returned by lppEntryID in IMAPISession::QueryIdentity.

See also

Concepts

About the Account Management API


PROP_MAPI_TRANSPORT_FLAGS

 Copy code hover
[image]

PROP_MAPI_TRANSPORT_FLAGS
See also Send feedback

Represents transport settings that Outlook uses to determine the necessary synchronization tasks and to disable the user interface (UI) elements that the account does not support.

Quick Info

See IOlkAccount.

Identifier: | 0x2010
Property type: | PT_BINARY
Property tag: | 0x20100102
Access: | Read/write

Remarks

Get or set this property by using IOlkAccount::GetProp or IOlkAccount::SetProp, respectively.

Returns MAPIACCT_SEND_ONLY if the account can only send messages but cannot receive messages. In this case, Outlook disables UI that does not apply to this type of accounts (for example, the UI for Send/Receive).

See also

Concepts

About the Account Management API
Constants (Account management API)


PROP_POP_LEAVE_ON_SERVER

 Copy code hover
[image]

PROP_POP_LEAVE_ON_SERVER
See also Send feedback

Specifies leaving a copy of a message on the server for a POP account.

Quick Info

Identifier: | 0x1000
Property type: | PT_DWORD
Property tag: | 0x10000003
Access: | Read-only

Remarks

The following table lists the possible values. See Constants (Account management API) for more information on the constants.

Possible values | Description
LEAVE_ON_SERVER | Leaves a copy of the message on the POP server after downloading the message to a device.
REMOVE_AFTER | Removes the message from the POP server after downloading it to a device.
REMOVE_ON_NUKE | Removes the message from the POP server only after the user deletes the message from the Deleted Items folder.
GET_REMOVE_AFTER_DAYS(ul) | Gets the number of days after which the message will be removed from the POP server.
SET_REMOVE_AFTER_DAYS(days) | Sets the number of days after which the message will be removed from the POP server.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_AUTH_METHOD

 Copy code hover
[image]

PROP_SMTP_AUTH_METHOD
See also Send feedback

Specifies the authentication method to use for the SMTP account.

Quick Info

Identifier: | 0x0208
Property type: | PT_DWORD
Property tag: | 0x02080003
Access: | Read-only

Remarks

The value is a bitmask of the following constants. See Constants (Account management API) for their values.

  • SMTP_AUTH_SAME_AS_POP means using the same credentials as my incoming mail server, as provided by PROP_INET_USER and PROP_INET_PASSWORD.

  • SMTP_AUTH_USER_PASS means using the credentials as provided by PROP_SMTP_USER and PROP_SMTP_PASSWORD.

  • SMTP_AUTH_RECEIVE_BEFORE_SEND means requesting the user to log on to the incoming mail server before sending mail.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_PASSWORD

 Copy code hover
[image]

PROP_SMTP_PASSWORD
See also Send feedback

Represents the password of the SMTP account.

Quick Info

Identifier: | 0x0205
Property type: | PT_UNICODE|SECURE_FLAG
Property tag: | 0x2058001F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_PORT

 Copy code hover
[image]

PROP_SMTP_PORT
See also Send feedback

Represents the port number of the SMTP account.

Quick Info

Identifier: | 0x0201
Property type: | PT_DWORD
Property tag: | 0x02010003
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_SECURE_CONNECTION

 Copy code hover
[image]

PROP_SMTP_SECURE_CONNECTION
See also Send feedback

Specifies the type of encrypted connection to use for an SMTP account.

Quick Info

Identifier: | 0x020A
Property type: | PT_DWORD
Property tag: | 0x020A0003
Access: | Read-only

Remarks

The value can be one of the following constants. See Constants (Account management API) for their values.

Constants | Description
ENCRYPT_CONN_NO_SECURITY | Do not use any encryption.
ENCRYPT_CONN_SSL | Use Secure Socket Layer (SSL) encryption.
ENCRYPT_CONN_TLS | Use Transport Layer Security (TLS) encryption and authentication protocol.
ENCRYPT_CONN_AUTO | Automatically detect and use the encryption method supported by the mail server.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_SERVER

 Copy code hover
[image]

PROP_SMTP_SERVER
See also Send feedback

Represents the server name of the SMTP account.

Quick Info

Identifier: | 0x0200
Property type: | PT_UNICODE
Property tag: | 0x0200001F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_SSL

 Copy code hover
[image]

PROP_SMTP_SSL
See also Send feedback

Specifies whether to use Secure Socket Layer (SSL) protocol for the SMTP account.

Quick Info

Identifier: | 0x0202
Property type: | PT_DWORD
Property tag: | 0x02020003
Access: | Read-only

Remarks

A zero value means do not use SSL encryption, otherwise use SSL encryption.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_USE_AUTH

 Copy code hover
[image]

PROP_SMTP_USE_AUTH
See also Send feedback

Specifies whether to use authentication for the SMTP account.

Quick Info

Identifier: | 0x0203
Property type: | PT_DWORD
Property tag: | 0x02030003
Access: | Read-only

Remarks

A zero value means do not use authentication, otherwise use authentication.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_USE_SPA

 Copy code hover
[image]

PROP_SMTP_USE_SPA
See also Send feedback

Specifies whether to use Secure Password Authentication (SPA) for the SMTP account.

Quick Info

Identifier: | 0x0207
Property type: | PT_DWORD
Property tag: | 0x02070003
Access: | Read-only

Remarks

A zero value means do not use SPA, otherwise use SPA.

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


PROP_SMTP_USER

 Copy code hover
[image]

PROP_SMTP_USER
See also Send feedback

Represents the user name for the SMTP account.

Quick Info

Identifier: | 0x0204
Property type: | PT_UNICODE
Property tag: | 0x0204001F
Access: | Read-only

See also

Concepts

Constants (Account management API)

Other resources

Managing message downloads for POP3 accounts


Data degradation layer API reference

 Copy code hover
[image]

Data degradation layer API reference
Send feedback

This section provides reference content for the Data Degradation Layer API, which provides the ability to hide the underlying native character format of an Outlook object, allowing a client to access the object in a preferred character format rather than in the object's native character format.

In This Section

  • Constants

  • Functions


Constants (Data degradation layer API)

 Copy code hover
[image]

Constants (Data degradation layer API)
See also Send feedback

This topic contains constant definitions for the Data Degradation Layer API.

Constants

Constant | Definition
DDLWRAP_FLAG_ANSI | 0x00000001
DDLWRAP_FLAG_UNICODE | 0x00000002

See also

Concepts

About the Data Degradation Layer API


Functions (Data degradation layer API)

 Copy code hover
[image]

Functions (Data degradation layer API)
Send feedback

This section describes the functions in the Data Degradation Layer API.

Function | Description
HrCreateNewWrappedObject | Creates an object that a client can access in a preferred character format.


HrCreateNewWrappedObject

 Copy code hover
[image]

HrCreateNewWrappedObject
See also Send feedback

Creates an object that a client can access in a preferred character format.

Quick Info

Exported by: | msmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
HRESULT HrCreateNewWrappedObject(
    LPVOID        pvUnwrapped,
    ULONG         ulUnwrappedFlags,
    ULONG         ulWrappedFlags,
    const IID     *pIID,
    const ULONG   *pulReserved,
    BOOL          fCheckWrap,
    LPVOID       *ppvWrapped
);

Parameters

pvUnwrapped

[in] The initial unwrapped Outlook object. Must implement one of the following interfaces:

  • IMailUser : IMAPIProp , IMAPIFolder : IMAPIContainer, IMessage : IMAPIProp, IMsgStore : IMAPIProp, IMSLogon : IUnknown, or IOSTX.

ulUnwrappedFlags

[in] Flags that characterize the unwrapped initial object. Must be one or more of the following values:

  • DDLWRAP_FLAG_ANSI—Unwrapped object is ANSI.

  • DDLWRAP_FLAG_UNICODE—Unwrapped object is UNICODE.

ulWrappedFlags

[in] Flags for the preferred character format. Must be one or more of the following values:

  • DDLWRAP_FLAG_ANSI—Wrapped object will be exposed as ANSI.

  • DDLWRAP_FLAG_UNICODE—Wrapped object will be exposed as UNICODE.

pIID

[in] The identifier of the interface supported by the unwrapped object; set it to NULL if this is unknown.

pulReserved

[in] This parameter is not used. It must be NULL.

fCheckWrap

[in] Set this parameter to true if pvUnwrapped should be checked for its format before wrapping; set it to false if the object should be wrapped without checking.

ppvWrapped

[out] A pointer to the requested object, wrapped in the requested character format.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

Passing in a wrapped object with fCheckWrap set to true will result in an unwrapped object. Regardless of whether or not the returned object is wrapped, the client is responsible for releasing the reference on the returned object.

When using GetProcAddress to look for the address of this function in msmapi32.dll, specify HrCreateNewWrappedObject@28 as the procedure name.

See also

Concepts

About the Data Degradation Layer API
Constants (Data degradation layer API)


Free/busy API reference

 Copy code hover
[image]

Free/busy API reference
Send feedback

This section provides reference content for the Free/Busy API, which allows mail providers to provide free/busy status information for specified user accounts within a specified time range.

In This Section

  • Constants

  • Data Types

  • Interfaces


Constants (Free/busy API)

 Copy code hover
[image]

Constants (Free/busy API)
Send feedback

This topic contains constant definitions, class identifiers, and interface identifiers for the Free/Busy API.

Constants

Constant | Definition
E_NOTIMPL | As defined in the Microsoft Windows Software Development Kit (SDK) header file winerror.h.
E_OUTOFMEMORY | As defined in the Windows SDK header file winerror.h.
S_FALSE | As defined in the Windows SDK header file winerror.h.
S_OK | As defined in the Windows SDK header file winerror.h.

Interface Identifiers

For the following interface identifiers, assume the DEFINE_GUID macro defined in the Windows SDK header file guiddef.h to associate the GUID symbolic name with its value.

//{00067064-0000-0000-C000-000000000046}

DEFINE_GUID(IID_IEnumFBBlock, 0x00067064, 0x0, 0x0, 0xc0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x46);

//{00067066-0000-0000-C000-000000000046}

DEFINE_GUID(IID_IFreeBusyData, 0x00067066, 0x0, 0x0, 0xc0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x46);

//{00067067-0000-0000-C000-000000000046}

DEFINE_GUID(IID_IFreeBusySupport, 0x00067067, 0x0, 0x0, 0xc0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x46);


Data types (Free/busy API)

 Copy code hover
[image]

Data types (Free/busy API)
Send feedback

This section describes the data types in the Free/Busy API.

Data type | Description
FBBlock_1 | Defines a free/busy block of data.
FBStatus | An enumeration for the free/busy status of free/busy blocks.
FBUser | Identifies a user that may or may not have free/busy data available.


FBBlock_1

 Copy code hover
[image]

FBBlock_1
See also Send feedback

Defines a free/busy block of data. This is an item on a calendar represented by an appointment or meeting request.

Quick Info

Copy code Copy code
typedef struct  tagFBBlock_1
    {
    long m_tmStart;
    long m_tmEnd;
    FBStatus m_fbstatus;
    }FBBlock_1;

Members

m_tmStart

The start time for the block, expressed in relative time. For more information, see How to: Use relative time to access free/busy data.

m_tmEnd

The end time for the block, expressed in relative time.

m_fbStatus

The free/busy status for this block, indicating whether the user is out-of-office, busy, tentative, or free, during the time period between m_tmStart and m_tmEnd.

See also

Concepts

FBStatus
IEnumFBBlock::Next
How to: Use relative time to access free/busy data


FBStatus

 Copy code hover
[image]

FBStatus
See also Send feedback

An enumeration for the free/busy status of free/busy blocks.

Quick Info

Copy code Copy code
enum
    {
      fbFree      = 0,
      fbTentative = fbFree + 1,
      fbBusy      = fbTentative + 1,
      fbOutOfOffice = fbBusy + 1
    }

Remarks

The free/busy status of a block of time determines how it is displayed on a calendar: Free, Busy, Tentative, or Out of Office.

See also

Concepts

FBBlock_1
IEnumFBBlock::Next


FBUser

 Copy code hover
[image]

FBUser
See also Send feedback

Identifies a user who may or may not have free/busy data available.

Quick Info

Copy code Copy code
typedef struct tagFBUser
{
   ULONG m_cbEid;
   LPENTRYID m_lpEid;
   ULONG m_ulReserved;
   LPWSTR m_pwszReserved;
} FBUser;

Members

m_cbEid

The length of the entry ID of the mail user as represented by the IMailUser interface.

m_lpEid

The entry ID of the mail user as represented by the IMailUser interface.

m_ulReserved

This parameter is reserved for Outlook internal use and is not supported.

m_pwszReserved

This parameter is reserved for Outlook internal use and is not supported.

See also

Concepts

About the Free/Busy API
IFreeBusySupport


Interfaces (Free/busy API)

 Copy code hover
[image]

Interfaces (Free/busy API)
Send feedback

This section describes the interfaces in the Free/Busy API.

Interface | Description
IEnumFBBlock | Supports accessing and enumerating free/busy blocks of data for a user within a time range.
IFreeBusyData | For a given user, gets and sets a time range and returns an interface for enumerating free/busy blocks of data within this time range.
IFreeBusySupport | Supports specification of interfaces that access free/busy data for specified users.


IEnumFBBlock

 Copy code hover
[image]

IEnumFBBlock
See also Send feedback

Supports accessing and enumerating free/busy blocks of data for a user within a time range.

Quick Info

Inherits from: | IUnknown
Provided by: | Free/busy provider
Interface identifier: | IEnumFBBlock

Vtable Order

Next | Gets the next specified number of blocks of free/busy data in an enumeration.
Skip | Skips a specified number of blocks of free/busy data.
Reset | Resets the enumerator by setting the cursor to the beginning.
Clone | Creates a copy of the enumerator, using the same time restriction but setting the cursor to the beginning of the enumerator.
Restrict | Restricts the enumeration to a specified time period.

Remarks

An enumeration contains free/busy blocks of data that do not overlap in time. When there are overlapping items on a calendar, Outlook merges these items to form non-overlapping free/busy blocks in the enumeration based on this order of precedence: out-of-office, busy, tentative.

A free/busy provider obtains this interface and the enumeration for a time range for a user through IFreeBusyData.

See also

Concepts

About the Free/Busy API
Constants (Free/busy API)
IFreeBusyData


IEnumFBBlock::Clone

 Copy code hover
[image]

IEnumFBBlock::Clone
See also Send feedback

Creates a copy of the enumerator, using the same time restriction but setting the cursor to the beginning of the enumerator.

Quick Info

See IEnumFBBlock.

Copy code Copy code
HRESULT Clone(
     IEnumFBBlock **ppclone
);

Parameters

ppclone

[out] A pointer to pointer to the copy of IEnumFBBlock interface.

Return Values

HRESULT | Description
S_OK | The call succeeded.
E_OUTOFMEMORY | There is insufficient memory for making the copy.

See also

Concepts

Constants (Free/busy API)
IEnumFBBlock::Next
IEnumFBBlock::Reset
IEnumFBBlock::Restrict
IEnumFBBlock::Skip


IEnumFBBlock::Next

 Copy code hover
[image]

IEnumFBBlock::Next
See also Send feedback

Gets the next specified number of blocks of free/busy data in an enumeration.

Quick Info

See IEnumFBBlock.

Copy code Copy code
HRESULT Next(
        LONG celt,
        FBBlock_1 *pblk,
        LONG *pcfetch
);

Parameters

celt

[in] The number of free/busy data blocks in pblk to retrieve.

pblk

[in] A pointer to an array of free/busy blocks. The array is allocated a size of celt. The requested free/busy blocks are returned in this array.

pcfetch

[out] The number of free/busy blocks actually returned in pblk.

Return Values

HRESULT | Description
S_OK | The requested number of blocks has been returned.
S_FALSE | The requested number of blocks has not been returned.

See also

Concepts

Constants (Free/busy API)
FBBlock_1
IEnumFBBlock::Clone
IEnumFBBlock::Reset
IEnumFBBlock::Restrict
IEnumFBBlock::Skip


IEnumFBBlock::Reset

 Copy code hover
[image]

IEnumFBBlock::Reset
See also Send feedback

Resets the enumerator by setting the cursor to the beginning.

Quick Info

See IEnumFBBlock.

Copy code Copy code
HRESULT Reset();

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

IEnumFBBlock::Clone
IEnumFBBlock::Next
IEnumFBBlock::Restrict
IEnumFBBlock::Skip


IEnumFBBlock::Restrict

 Copy code hover
[image]

IEnumFBBlock::Restrict
See also Send feedback

Restricts the enumeration to a specified time period.

Quick Info

See IEnumFBBlock.

Copy code Copy code
HRESULT Restrict(
    FILETIME ftmStart,
    FILETIME ftmEnd
);

Parameters

ftmStart

[in] The start time to restrict the enumeration.

ftmEnd

[in] The end time to restrict the enumeration.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

This method also resets the enumeration.

See also

Concepts

IEnumFBBlock::Clone
IEnumFBBlock::Next
IEnumFBBlock::Reset
IEnumFBBlock::Skip
How to: Use relative time to access free/busy data


IEnumFBBlock::Skip

 Copy code hover
[image]

IEnumFBBlock::Skip
See also Send feedback

Skips a specified number of blocks of free/busy data.

Quick Info

See IEnumFBBlock.

Copy code Copy code
HRESULT Skip(
    LONG celt
);

Parameters

celt

[in] The number of free/busy blocks to skip.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

IEnumFBBlock::Clone
IEnumFBBlock::Next
IEnumFBBlock::Reset
IEnumFBBlock::Restrict


IFreeBusyData

 Copy code hover
[image]

IFreeBusyData
See also Send feedback

For a given user, gets and sets a time range and returns an interface for enumerating free/busy blocks of data within this time range.

Quick Info

Inherits from: | IUnknown
Provided by: | Free/busy provider
Interface identifier: | IID_IFreeBusyData

Vtable Order

Placeholder1 | This member is a placeholder and is not supported.
EnumBlocks | Gets an interface that enumerates free/busy blocks of data for a user within a specified time range.
Placeholder2 | This member is a placeholder and is not supported.
Placeholder3 | This member is a placeholder and is not supported.
Placeholder4 | This member is a placeholder and is not supported.
Placeholder5 | This member is a placeholder and is not supported.
SetFBRange | Sets the range of time for an enumeration of free/busy blocks of data for a user.
Placeholder6 | This member is a placeholder and is not supported.
GetFBPublishRange | Gets a preset time range for an enumeration of free/busy blocks of data for a user.

Remarks

Most of the members in this interface are placeholders reserved for the internal use of Outlook and are subject to change. Free/busy providers must implement them only as specified, returning only the specified return values.

See also

Concepts

About the Free/Busy API
Constants (Free/busy API)


IFreeBusyData::EnumBlocks

 Copy code hover
[image]

IFreeBusyData::EnumBlocks
See also Send feedback

Gets an interface that enumerates free/busy blocks of data for a user within a specified time range.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT EnumBlocks(
     IEnumFBBlock **ppenumfb,
     FILETIME ftmStart,
     FILETIME ftmEnd
);

Parameters

ppenumfb

[out] An interface to enumerate free/busy blocks.

ftmStart

[in] The start time for the enumeration. It is expressed in FILETIME.

ftmEnd

[in] The end time for the enumeration. It is expressed in FILETIME.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

This method is used to indicate the time range of calendar items for which to retrieve details. The values of ftmStart and ftmEnd are cached and returned in a subsequent call of IFreeBusyData::GetFBPublishRange.

A free/busy provider can also subsequently use the returned IEnumFBBlock interface to access the enumeration.

See also

Concepts

IEnumFBBlock
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange
How to: Use relative time to access free/busy data


IFreeBusyData::GetFBPublishRange

 Copy code hover
[image]

IFreeBusyData::GetFBPublishRange
See also Send feedback

Gets a preset time range for an enumeration of free/busy blocks of data for a user.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT GetFBPublishRange(
     LONG *prtmStart,
     LONG *prtmEnd
);

Parameters

prtmStart

[out] A relative time value for the start of free/busy information. This value is the number of minutes since January 1, 1601.

prtmEnd

[out] A relative time value for the end of free/busy information. This value is the number of minutes since January 1, 1601.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

A free/busy provider calls IFreeBusyData::EnumBlocks or IFreeBusyData::SetFBRange to set the time range for an enumeration. IFreeBusyData::GetFBPublishRange must return the cached values for the time range set by the most recent call for IFreeBusyData::EnumBlocks or IFreeBusyData::SetFBRange.

See also

Concepts

How to: Use relative time to access free/busy data
IFreeBusyData::EnumBlocks
IFreeBusyData::SetFBRange


IFreeBusyData::Placeholder1

 Copy code hover
[image]

IFreeBusyData::Placeholder1
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder1(
     void*
);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IFreeBusyData and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange


IFreeBusyData::Placeholder2

 Copy code hover
[image]

IFreeBusyData::Placeholder2
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder2(void *);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IFreeBusyData and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange


IFreeBusyData::Placeholder3

 Copy code hover
[image]

IFreeBusyData::Placeholder3
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder3(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IFreeBusyData and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange


IFreeBusyData::Placeholder4

 Copy code hover
[image]

IFreeBusyData::Placeholder4
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder4(
     LONG,
     LONG,
     LONG,
     BOOL,
     LONG,
     LONG,
     LONG,
     void *
);

Return Values

Always S_OK, because this is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange


IFreeBusyData::Placeholder5

 Copy code hover
[image]

IFreeBusyData::Placeholder5
Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder5(
    void *,
    LONG,
    void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IFreeBusyData and is not supported.

Remarks

This member must return E_NOTIMPL.


IFreeBusyData::Placeholder6

 Copy code hover
[image]

IFreeBusyData::Placeholder6
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT Placeholder6(
    void *,
    ULONG,
    void *,
    ULONG,
    void *,
    void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder in IFreeBusyData and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
IFreeBusyData::SetFBRange


IFreeBusyData::SetFBRange

 Copy code hover
[image]

IFreeBusyData::SetFBRange
See also Send feedback

Sets the range of time for an enumeration of free/busy blocks of data for a user.

Quick Info

See IFreeBusyData.

Copy code Copy code
HRESULT SetFBRange(
     LONG rtmStart,
     LONG rtmEnd
);

Parameters

rtmStart

[in] A relative time value for the start of free/busy information. This value is the number of minutes since January 1, 1601.

rtmEnd

[in] A relative time value for the end of free/busy information. This value is the number of minutes since January 1, 1601.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

This method is used to indicate the time range of calendar items for which to retrieve details. The values of ftmStart and ftmEnd are cached and returned in a subsequent call of IFreeBusyData::GetFBPublishRange.

See also

Concepts

IFreeBusyData::EnumBlocks
IFreeBusyData::GetFBPublishRange
How to: Use relative time to access free/busy data


IFreeBusySupport

 Copy code hover
[image]

IFreeBusySupport
See also Send feedback

Supports specification of interfaces that access free/busy data for specified users.

Quick Info

Inherits from: | IUnknown
Provided by: | Free/busy provider
Interface identifier: | IID_IFreeBusySupport

Vtable Order

Placeholder1 | This member is a placeholder and is not supported.
Placeholder2 | This member is a placeholder and is not supported.
LoadFreeBusyData | Returns, for each specified user, an interface for enumerating free/busy blocks of data within a time range.
Placeholder23 | This member is a placeholder and is not supported.
Placeholder3 | This member is a placeholder and is not supported.
Placeholder4 | This member is a placeholder and is not supported.
Placeholder5 | This member is a placeholder and is not supported.
Placeholder6 | This member is a placeholder and is not supported.
Placeholder7 | This member is a placeholder and is not supported.
Placeholder8 | This member is a placeholder and is not supported.
Placeholder9 | This member is a placeholder and is not supported.
Placeholder10 | This member is a placeholder and is not supported.
Placeholder11 | This member is a placeholder and is not supported.
Placeholder12 | This member is a placeholder and is not supported.
Placeholder13 | This member is a placeholder and is not supported.
Placeholder14 | This member is a placeholder and is not supported.
Placeholder15 | This member is a placeholder and is not supported.
Placeholder16 | This member is a placeholder and is not supported.
Placeholder17 | This member is a placeholder and is not supported.
Placeholder18 | This member is a placeholder and is not supported.
Placeholder19 | This member is a placeholder and is not supported.
Placeholder20 | This member is a placeholder and is not supported.
Placeholder21 | This member is a placeholder and is not supported.
Placeholder22 | This member is a placeholder and is not supported.

Remarks

Most of the members in this interface are placeholders reserved for the internal use of Outlook and are subject to change. Free/busy providers must implement them only as specified, returning only the specified return values.

See also

Concepts

About the Free/Busy API
FBUser


IFreeBusySupport::LoadFreeBusyData

 Copy code hover
[image]

IFreeBusySupport::LoadFreeBusyData
See also Send feedback

Returns, for each specified user, an interface for enumerating free/busy blocks of data within a time range.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT LoadFreeBusyData(
    ULONG cMax,
    FBUser *rgfbuser,
    IFreeBusyData **prgfbdata,
    HRESULT *phrStatus,
    ULONG *pcRead
);

Parameters

cMax

[in] The number of IFreeBusyData interfaces to return.

rgfbuser

[in] The array of free/busy users to retrieve data for.

prgfbdata

[in][out] The array of IFreeBusyData interfaces that correspond to the rgfbuser array of FBUser structures.

Note Note

This array of pointers is allocated by the caller and freed by the caller. The actual interfaces pointed to are released when the caller is done with them.

phrStatus

[out] The array of HRESULT results for retrieving each corresponding IFreeBusyData interface. The value may be NULL. A result is set to S_OK if corresponding prgfbdata is valid.

pcRead

[out] The actual number of users for which an IFreeBusyData interface has been found.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

Constants (Free/busy API)


IFreeBusySupport::Placeholder1

 Copy code hover
[image]

IFreeBusySupport::Placeholder1
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder1(
     void *,
     void *,
     BOOL
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder2

 Copy code hover
[image]

IFreeBusySupport::Placeholder2
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder2();

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder3

 Copy code hover
[image]

IFreeBusySupport::Placeholder3
Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder3();

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.


IFreeBusySupport::Placeholder4

 Copy code hover
[image]

IFreeBusySupport::Placeholder4
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder4(
    FBUser,
    void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
FBUser
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder5

 Copy code hover
[image]

IFreeBusySupport::Placeholder5
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder5(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder6

 Copy code hover
[image]

IFreeBusySupport::Placeholder6
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder6(
    void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder7

 Copy code hover
[image]

IFreeBusySupport::Placeholder7
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder7(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder8

 Copy code hover
[image]

IFreeBusySupport::Placeholder8
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder8(
void **,
BOOL
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder9

 Copy code hover
[image]

IFreeBusySupport::Placeholder9
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder9(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder10

 Copy code hover
[image]

IFreeBusySupport::Placeholder10
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder10();

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder11

 Copy code hover
[image]

IFreeBusySupport::Placeholder11
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
BOOL Placeholder11(
     BOOL
);

Return Values

Always false, because this member is a placeholder and is not supported.

Remarks

This member must return false.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder12

 Copy code hover
[image]

IFreeBusySupport::Placeholder12
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder12();

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder13

 Copy code hover
[image]

IFreeBusySupport::Placeholder13
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder13(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder14

 Copy code hover
[image]

IFreeBusySupport::Placeholder14
Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder14(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.


IFreeBusySupport::Placeholder15

 Copy code hover
[image]

IFreeBusySupport::Placeholder15
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder15();

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder16

 Copy code hover
[image]

IFreeBusySupport::Placeholder16
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder16(
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder17

 Copy code hover
[image]

IFreeBusySupport::Placeholder17
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder17();

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder18

 Copy code hover
[image]

IFreeBusySupport::Placeholder18
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder18();

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder19

 Copy code hover
[image]

IFreeBusySupport::Placeholder19
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder19(
     FBUser,
     void *,
     void *,
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder20

 Copy code hover
[image]

IFreeBusySupport::Placeholder20
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder20();

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder21

 Copy code hover
[image]

IFreeBusySupport::Placeholder21
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder21(
     void *,
     HWND,
     BOOL
);

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder22

 Copy code hover
[image]

IFreeBusySupport::Placeholder22
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder22();

Return Values

Always S_OK, because this member is a placeholder and is not supported.

Remarks

This member must return S_OK.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


IFreeBusySupport::Placeholder23

 Copy code hover
[image]

IFreeBusySupport::Placeholder23
See also Send feedback

This member is a placeholder and is not supported.

Quick Info

See IFreeBusySupport.

Copy code Copy code
HRESULT Placeholder23(
     ULONG,
     void *,
     void **,
     void *,
     void *
);

Return Values

Always E_NOTIMPL, because this member is a placeholder and is not supported.

Remarks

This member must return E_NOTIMPL.

See also

Concepts

Constants (Free/busy API)
IFreeBusySupport::LoadFreeBusyData


Outlook exported APIs

 Copy code hover
[image]

Outlook exported APIs
Send feedback

This section provides reference content for the APIs that Outlook exports.

In This Section

  • Constants

  • Data Types

  • Functions

  • Interfaces

  • Available events and their dispids (Outlook exported APIs)


Constants (Outlook exported APIs)

 Copy code hover
[image]

Constants (Outlook exported APIs)
See also Send feedback

This topic contains constant definitions for APIs that Outlook exports.

Definitions for Time Zone Support

Copy code Copy code
const ULONG TZ_MAX_RULES                    = 0x00000001;
const BYTE  TZ_BIN_VERSION_MAJOR            = 0x02;
const BYTE  TZ_BIN_VERSION_MINOR            = 0x01;
const WORD  TZRULE_FLAG_RECUR_CURRENT_TZREG = 0x0001;
const WORD  TZRULE_FLAG_EFFECTIVE_TZREG     = 0x0002;
const WORD  TZDEFINITION_FLAG_VALID_KEYNAME = 0x0002;

Definitions for Category Support

Constant | Definition
PCAFSIF_MSGEID_IS_SEARCH_KEY | 0x00000001

Miscellaneous Dispatch Identifiers

Outlook exposes the following dispatch identifiers (dispids) so that developers can use IDispatch::Invoke to access the corresponding property or method, or listen to the corresponding event.

Associated constant | Dispid value | Description | Applicable interface
dispidFDirty | 0xF024 | Used to invoke the corresponding property on an item to verify whether the item has been modified but has not been saved. | Item-level objects
dispidShowSenderPhoto | 0xF0D0 | Used to invoke the corresponding method on the explorer or inspector to specify whether to display a contact's picture, based on a given argument. | Explorer or inspector
dispidBeforePrint | 0xFC8E | Used to handle the event from the IDispatch::Invoke function that fires before a printing operation. | Application
dispidEventReadComplete | 0xFC8F | Used to handle the event from the IDispatch::Invoke function that fires when Outlook has completed reading the properties of the item. | Item-level objects

See also

Concepts

Outlook exported APIs
About APIs exported by Outlook
How to: Determine whether an Outlook item has been modified but not saved (Outlook 2013 Auxiliary Reference)
How to: Specify whether to display a contact's picture in Outlook (Outlook 2013 Auxiliary Reference)

Other resources

Available events and their dispids (Outlook exported APIs)


Data types (Outlook exported APIs)

 Copy code hover
[image]

Data types (Outlook exported APIs)
Send feedback

This section describes the data types that Outlook exports.

Data type | Description
TZDEFINITION | Represents an entire time zone including all historical, current, and future time zone shift rules for daylight saving time.
TZREG | Defines when daylight saving time starts, when the return to standard time occurs, and how many hours the daylight saving shift is.
TZRULE | Specifies information for a time zone rule about when daylight saving time starts, and the year in which that time zone rule first takes effect.


TZDEFINITION

 Copy code hover
[image]

TZDEFINITION
See also Send feedback

Represents an entire time zone including all historical, current, and future time zone shift rules for daylight saving time.

Quick Info

Copy code Copy code
typedef struct {
    WORD     wFlags;
    LPWSTR   pwszKeyName;
    WORD     cRules;
    TZRULE*  rgRules;
} TZDEFINITION;

Members

wFlags

Indicates that the key name that represents the time zone in the Windows registry is valid. Because each time zone should always be identified by a key name, this member should always have the value TZDEFINITION_FLAG_VALID_KEYNAME.

pwszKeyName

The name of the key for this time zone in the Windows registry. This name must not be localized. It has a maximum size of MAX_PATH, which is defined in the Windows Software Development Kit (SDK) header file windows.h.

cRules

The number of time zone rules for this definition. The maximum number of rules is TZ_MAX_RULES.

rgRules

An array of rules that describe when shifts occur.

Remarks

There must be at least one rule in rgRules. The first rule in rgRules is considered to be the rule to use until the second rule starts, regardless of the stStart on the first rule.

The rules should be sorted from oldest to newest. There is no overlap allowed between rules, so a prior rule is deemed to end when a new rule starts.

See also

Concepts

Constants (Outlook exported APIs)
About rebasing calendars programmatically for Daylight Saving Time
HrCreateApptRebaser


TZREG

 Copy code hover
[image]

TZREG
See also Send feedback

Defines when daylight saving time starts, when the return to standard time occurs, and how many hours the daylight saving shift is.

Quick Info

Copy code Copy code
typedef struct RenTimeZone {
    long        lBias;
    long        lStandardBias;
    long        lDaylightBias;
    SYSTEMTIME  stStandardDate;
    SYSTEMTIME  stDaylightDate;
} TZREG;

Members

lBias

The offset from Greenwich Mean Time (GMT).

lStandardBias

The offset from bias during standard time.

lDaylightBias

The offset from bias during daylight saving time.

stStandardDate

The time to switch to standard time.

stDaylightDate

The time to switch to daylight saving time.

Remarks

This structure is similar to TIME_ZONE_INFORMATION. This is the structure used by legacy clients to store time zone information for recurring meetings.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time
HrCreateApptRebaser
TZRULE


TZRULE

 Copy code hover
[image]

TZRULE
See also Send feedback

Specifies information for a time zone rule about when daylight saving time starts, and the year in which that time zone rule first takes effect.

Quick Info

Copy code Copy code
typedef struct {
    WORD        wFlags;
    SYSTEMTIME  stStart;
    TZREG       TZReg;
} TZRULE;

Members

wFlags

The flags set for this member identify specific details for this time zone rule. The possible flags are as follows:

  • TZRULE_FLAG_EFFECTIVE_TZREG—Identifies the rule as the one that should be used currently. Only one rule can be marked as the effective rule. All other rules are for comparison purposes only.

  • TZRULE_FLAG_RECUR_CURRENT_TZREG—On recurring meetings, identifies the rule as matching the rule in PidLidTimeZoneStruct. This can be used to detect whether PidLidTimeZoneStruct has been modified significantly by a legacy client, which would be otherwise unaware of the new, more complete property.

stStart

The time in Coordinated Universal Time (UTC) that the time zone rule started.

TZReg

The time zone information for the time zone rule.

Remarks

This structure augments TZREG by providing additional information indicating when time zone rules take effect.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time
Constants (Outlook exported APIs)
HrCreateApptRebaser
TZDEFINITION


Functions (Outlook exported APIs)

 Copy code hover
[image]

Functions (Outlook exported APIs)
Send feedback

This section describes the functions that Outlook exports.

Function | Description
HrCreateApptRebaser | Initializes an IOlkApptRebaser object for use in rebasing appointments in Outlook calendars.
HrProcessConvActionForSentItem | Performs post-send categorization on a mail item based on its PidTagConversationId.
RebaseTaskComplete | Reports completion for rebasing of appointments.
RebaseTaskProgress | Reports progress for enumeration and rebasing of appointments.


HrCreateApptRebaser

 Copy code hover
[image]

HrCreateApptRebaser
See also Send feedback

Initializes an IOlkApptRebaser object for use in rebasing appointments in Outlook calendars.

Quick Info

Header file: | tzmovelib.h
Implemented by: | tzmovelib.dll
Called by: | MAPI client applications
Pointer type: | LPHRCREATEAPPTREBASER
DLL entry point: | HrCreateApptRebaser@44
Copy code Copy code
HRESULT HrCreateApptRebaser(
    ULONG ulFlags,
    IMAPISession *pSession,
    IMsgStore *pCalendarMsgStore,
    IMAPIFolder *pCalendarFolder,
    LPCWSTR pwszUpdatePrefix,
    const FILETIME *pftInstallDateUTC,
    LONG lExpansionDepth,
    const TZDEFINITION *pTZTo,
    const TZDEFINITION *pTZMissing,
    MAPIERROR **ppError,
    IOlkApptRebaser **ppApptRebase);

Parameters

ulFlags

[in] Required. A bitmask of flags used to control how rebasing is performed. The following flags can be set and are defined in tzmovelib.h:

  • REBASE_FLAG_UPDATE_ORGANIZED_MEETINGS—Appointment items in which the user is the meeting organizer are rebased. Note that by default, this causes Outlook to send meeting updates to all attendees of any meeting being rebased. You can combine this flag with either REBASE_FLAG_FORCE_NO_EX_UPDATES or REBASE_FLAG_FORCE_NO_UPDATES to change how meeting updates are handled.

  • REBASE_FLAG_UPDATE_UNMARKED—Update appointment items that have not been marked with a time zone. If this flag is specified, the pTZMissing value is used as the time zone that an item is created in for all items that do not have time zone data.

  • REBASE_FLAG_UPDATE_ONLYRECURRING—Update only recurring appointment items.

  • REBASE_FLAG_NO_UI—Do not show any user interface (UI), including logon dialog boxes generally displayed when opening a message store.

  • REBASE_FLAG_UPDATE_MINIMIZEAPPTS—Do not rebase appointment items that occur in the past.

  • REBASE_FLAG_FORCE_REBASE—Do not check the organizer for rebasing decisions, but rebase appointment items in which the user is an attendee.

  • REBASE_FLAG_FORCE_NO_EX_UPDATES—Send updates only if the user is the organizer and recipient is not connected to an Exchange Server.

  • REBASE_FLAG_FORCE_NO_UPDATES—Never send updates.

  • REBASE_FLAG_ONLY_CREATED_PRE_PATCH—Rebase only single-instance appointment items created before the patch was applied.

  • REBASE_FLAG_REPORTING_MODE—Do not actually rebase, just report appointment items that would be rebased.

  • REBASE_FLAG_SEND_RESOURCE_UPDATES—Send meeting updates to resources.

pSession

[in] Required. A pointer to a MAPI session interface.

pCalendarMsgStore

[in] Required. A pointer to a message store containing appointment items to be rebased.

pCalendarFolder

[in] Required. A pointer to a calendar folder containing appointment items to be rebased.

pwszUpdatePrefix

[in] Optional. A pointer to a string containing the prefix to be prepended on meeting requests. May be NULL.

pftInstallDateUTC

[in] Optional. The time zone patch install date. Used only if the REBASE_FLAG_ONLY_CREATED_PRE_PATCH flag is set.

IExpansionDepth

[in] Optional. The expansion depth when expanding distribution lists to exclude recipients connected to Exchange Server. Only used if the REBASE_FLAG_FORCE_NO_EX_UPDATES flag is set.

pTZTo

[in] Required. A pointer to a TZDEFINITION structure describing the time zone to be rebased to. TZDEFINITION is defined in tzmovelib.

pTZMissing

[in] Required. A pointer to a TZDEFINITION structure describing the time zone to be assumed if time zone information is not stamped on an item. Must not be NULL, but only used if the REBASE_FLAG_UPDATE_UNMARKED flag is set.

ppError

[out] A pointer to a pointer to a MAPIERROR structure containing version, component, and context information for the error. Can be NULL if no extended error information is desired. Free with MAPIFreeBuffer.

ppApptRebase

[out] A pointer to a pointer to the returned IOlkApptRebaser interface.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

When using GetProcAddress to look for the address of this function in tzmovelib.dll, specify HrCreateApptRebaser@44 as the procedure name. Not all of the flags are valid in combination with each other.

For more information about the various options, see the section "Glossary of command-line options for the Outlook Time Zone Data Update tool" in KB 931667: How to address the daylight saving time changes in 2007 by using the Time Zone Data Update Tool for Microsoft Office Outlook.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


HrProcessConvActionForSentItem

 Copy code hover
[image]

HrProcessConvActionForSentItem
Send feedback

Performs post-send categorization on a mail item based on its PidTagConversationId.

Quick Info

Exported by: | Outlook.exe
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
HRESULT WINAPI HrProcessConvActionForSentItem(
    SBinary const *pmbinStoreEid,
    SBinary const *pmbinMsgEid,
    SBinary const *pmbinConvID,
    DWORD dwFlags)

Parameters

pmbinStoreEid

[in] The PidTagEntryId of the store, or the PidTagStoreEntryId of the mail item. Cannot be NULL or invalid.

pmbinMsgEid

[in] The PidTagEntryId of the mail item. Cannot be NULL or invalid.

pmbinConvID

[in] The PidTagConversationId of the mail item. Cannot be NULL or invalid.

dwFlags

[in] A bitmask that specifies additional information about the method call.

  • 0—No additional options are used in this method call. This is the recommended value.

  • PCAFSIF_MSGEID_IS_SEARCH_KEY—pmbinMsgEid is actually the PidTagSearchKey of the message. Using a PidTagSearchKey is resource intensive, and should be avoided if a PidTagEntryId is available.

Return Values

HRESULT | Description
S_OK | The call was successful.
E_INVALIDARG | dwFlags contains an unknown flag.

Remarks

Categories are considered personal information and should not be transmitted outside the mailbox of the user. Therefore, do not call HrProcessConvActionForSentItem on an unsent mail item. Instead, send the item, and then call HrProcessConvActionForSentItem on the archived copy. The archived copy may be stored in the Sent Items folder, or an equivalent location.

Your application must be in-process with Outlook.exe, such as from a COM add-in, to call HrProcessConvActionForSentItem. If you attempt to call HrProcessConvActionForSentItem out-of-process, HrProcessConvActionForSentItem will throw an access-violation exception.


RebaseTaskComplete

 Copy code hover
[image]

RebaseTaskComplete
See also Send feedback

Reports completion for rebasing of appointments.

Quick Info

Header file: | tzmovelib.h
Implemented by: | MAPI client applications
Called by: | Outlook rebasing object
Pointer type: | PFNREBASETASKCOMPLETE as defined in tzmovelib.h
Copy code Copy code
void STDAPICALLTYPE RebaseTaskComplete(
    ULONG ulRowIndex,
    const SRow* pRowCur,
    HRESULT hrResult,
    BOOL fModified,
    BOOL fSentUpdate,
    const MAPIERROR* pError);

Parameters

ulRowIndex

[in] The row that was processed. This index refers to the SRowSet structure passed to IOlkApptRebaser::BeginRebaseAppointments.

pRowCur

in] A pointer to an SRow structure describing the item that was processed.

hrResult

[in] An HRESULT indicating the result of the rebasing operation.

fModified

[in] Specifies whether the item was modified.

fSentUpdate

[in] Specifies whether a meeting update message was sent.

pError

[in] A pointer to a MAPIERROR structure with extended error information.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

MAPI client applications that use the IOlkApptRebaser interface implement this function to track completion of item updates.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


RebaseTaskProgress

 Copy code hover
[image]

RebaseTaskProgress
See also Send feedback

Reports progress for enumeration and rebasing of appointments.

Quick Info

Header file: | tzmovelib.h
Implemented by: | MAPI client applications
Called by: | Outlook rebasing object
Pointer type: | PFNREBASETASKPROGRESS as defined in tzmovelib.h
Copy code Copy code
void STDAPICALLTYPE RebaseTaskProgress(
    ULONG ulMin,
    ULONG ulMax,
    ULONG ulCur,
    REBASE_APPT_STATE State,
    const SRow* pRowCur);

Parameters

ulMin

[in] The low end of the range of appointments being processed. It is usually zero.

ulMax

[in] The high end of the range of appointments being processed. It is usually the number of items in the calendar folder being processed.

ulCur

[in] The current item being processed.

State

[in] A value that indicates the status of the item being processed. The enumeration REBASE_APPT_STATE is defined in tzmovelib.h. State is one of the following values:

  • REBASE_APPT_STATE_SCANNING_EXAMINING—Scanning and examining an item.

  • REBASE_APPT_STATE_SCANNING_FOUND—Scanning and found an item.

  • REBASE_APPT_STATE_BEGIN—Fixing and starting an item.

  • REBASE_APPT_STATE_REBASING—Fixing and adjusting an item.

  • REBASE_APPT_STATE_SENDING—Fixing and sending a meeting update.

  • REBASE_APPT_STATE_DONE—Fixing and done with an item.

pRowCur

[in] A pointer to an SRow structure that describes the item being scanned or fixed.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

MAPI client applications that use the IOlkApptRebaser interface implement this function to track item processing.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


Interfaces (Outlook exported APIs)

 Copy code hover
[image]

Interfaces (Outlook exported APIs)
Send feedback

This section describes the interfaces that Outlook exports.

Interface | Description
IOlkApptRebaser | Supports rebasing appointments in a calendar folder.


IOlkApptRebaser

 Copy code hover
[image]

IOlkApptRebaser
See also Send feedback

Supports rebasing appointments in a calendar folder.

Quick Info

Inherits from: | IUnknown
Header file: | tzmovelib.h
Implemented by: | tzmovelib.dll
Called by: | MAPI client applications
Exposed on: | Outlook rebasing object

Vtable Order

BeginEnumerateAppointments | Begins a task for appointment enumeration in a calendar folder to find the appointments that need rebasing.
EndEnumerateAppointments | Waits for appointment enumeration in a calendar folder to complete and returns a list of appointments that need rebasing.
BeginRebaseAppointments | Begins a task for appointment rebasing given a list of appointments, usually obtained from EndEnumerateAppointments.
EndRebaseAppointments | Waits for appointment rebasing to complete and retrieves the results.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


IOlkApptRebaser::BeginEnumerateAppointments

 Copy code hover
[image]

IOlkApptRebaser::BeginEnumerateAppointments
See also Send feedback

Begins a task for appointment enumeration in a calendar folder to find the appointments that need rebasing.

Quick Info

See IOlkApptRebaser.

Copy code Copy code
HRESULT BeginEnumerateAppointments(
    PFNREBASETASKPROGRESS pfnProgress,
    void **ppContext);

Parameters

pfnProgress

[in] Optional. A pointer to a rebase task progress function to receive progress. PFNREBASETASKPROGRESS is defined in tzmovelib.h.

ppContext

[out] Required. A pointer to a pointer to the returned context. This context will be passed to IOlkApptRebaser::EndEnumerateAppointments.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

This task runs on a new thread.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


IOlkApptRebaser::BeginRebaseAppointments

 Copy code hover
[image]

IOlkApptRebaser::BeginRebaseAppointments
See also Send feedback

Begins a task for appointment rebasing given a list of appointments, usually obtained from IOlkApptRebaser::EndEnumerateAppointments.

Quick Info

See IOlkApptRebaser.

Copy code Copy code
HRESULT BeginRebaseAppointments(
    const SRowSet *pRows,
    PFNREBASETASKPROGRESS pfnProgress,
    PFNREBASETASKCOMPLETE pfnComplete,
    void **ppContext);

Parameters

pRows

[in] Required. A pointer to an SRowSet structure that describes the appointments that need rebasing. This structure is usually obtained from a prior call to IOlkApptRebaser::EndEnumerateAppointments.

pfnProgress

[in] Optional. A pointer to a rebase task progress function to receive progress. PFNREBASETASKPROGRESS is defined in tzmovelib.h.

pfnComplete

[out] Optional. A pointer to a rebase task completion function to receive notification of rebase completion. PFNREBASETASKCOMPLETE is defined in tzmovelib.h.

ppContext

[out] Required. A pointer to a pointer to the returned context. This context will usually be passed to IOlkApptRebaser::EndRebaseAppointments.

Return Values

S_OK if the call succeeded; otherwise, an error code.

Remarks

This task runs on a new thread.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


IOlkApptRebaser::EndEnumerateAppointments

 Copy code hover
[image]

IOlkApptRebaser::EndEnumerateAppointments
See also Send feedback

Waits for appointment enumeration in a calendar folder to complete and returns a list of appointments that need rebasing.

Quick Info

See IOlkApptRebaser.

Copy code Copy code
HRESULT EndEnumerateAppointments(
    void *pContext,
    HRESULT *phResult,
    MAPIERROR **ppError,
    SRowSet **ppRows);

Parameters

pContext

[in] Required. A pointer to the context obtained from a prior call to IOlkApptRebaser::BeginEnumerateAppointments.

phResult

[out] Required. A pointer to an HRESULT to retrieve the results of the enumeration operation.

ppError

[out] Optional. A pointer to a pointer to a MAPIERROR structure to retrieve extended error information.

ppRows

[out] Required. A pointer to a pointer to an SRowSet structure that describes the appointments that need rebasing. This structure will usually be passed to IOlkApptRebaser::BeginRebaseAppointments.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


IOlkApptRebaser::EndRebaseAppointments

 Copy code hover
[image]

IOlkApptRebaser::EndRebaseAppointments
See also Send feedback

Waits for appointment rebasing to complete and retrieves the results.

Quick Info

See IOlkApptRebaser.

Copy code Copy code
HRESULT EndRebaseAppointments(
    void *pContext,
    HRESULT *phResult);

Parameters

pContext

[in] Required. A pointer to the context obtained from a call to IOlkApptRebaser::BeginRebaseAppointments.

phResult

[out] Required. A pointer to an HRESULT to retrieve the result of the rebasing operation.

Return Values

S_OK if the call succeeded; otherwise, an error code.

See also

Concepts

About rebasing calendars programmatically for Daylight Saving Time


Available events and their dispids (Outlook exported APIs)

 Copy code hover
[image]

Available events and their dispids (Outlook exported APIs)
See also Send feedback

This section describes the dispatch identifiers for the events that Outlook makes available.

Outlook exposes the following dispatch identifiers (dispids) to allow C++ add-ins to listen to and handle the corresponding events from the IDispatch::Invoke function.

Constant

Dispid for event

Description

Parameters

Remarks

dispidBeforePrint

0xFC8E

Used to handle the application-level event from the IDispatch::Invoke function that fires before a printing operation.

There are 2 unnamed parameters:

  • The first parameter is of the type VT_BOOL|VT_BREF. Return VARIANT_TRUE in this parameter to cancel the event.

  • The second parameter is not used and should be ignored.

This dispid is available since Outlook 2010.

dispidEventReadComplete

0xFC8F

Used to handle the item-level event from the IDispatch::Invoke function that fires when Outlook has completed reading the properties of the item.

There is only one parameter Cancel which is of the type VT_BOOL|VT_BREF. Return VARIANT_TRUE in this parameter to cancel the read operation.

This dispid is available since Outlook 2010.

This event corresponds to the Exchange Client Extensions (ECE) event IExchExtMessageEvents::OnReadComplete, and also to the ReadComplete event that has been added to the object model since Outlook 2013.

For an example of how to use a dispid to listen to and handle an event, see the CAppEventListener::Invoke function in the C++ Outlook solution described in Implementing Outlook 2002/XP Event Sinks in MFC C++ 2003 .NET.

See also

Concepts

Outlook exported APIs
Constants (Outlook exported APIs)
About APIs exported by Outlook

Other resources

Implementing Outlook 2002/XP Event Sinks in MFC C++ 2003 .NET


Outlook 2013 MAPI Reference

 Copy code hover
[image]

Outlook 2013 MAPI Reference
See also Send feedback

Published: July 16, 2012

Welcome to the Microsoft Outlook 2013 Messaging API (MAPI) Reference. MAPI provides the messaging architecture for Microsoft Outlook 2013. MAPI for Outlook 2013 provides a set of interfaces, functions, and other data types to facilitate the development of Outlook 2013 messaging applications. Applications and transports use MAPI to manipulate email data, to create email messages and the folders to store them in, and to support notifications of changes to existing MAPI-related data.

Note Note

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs.

In this section

Getting Started with the Outlook 2013 MAPI Reference

Provides information about the various reference and conceptual resources in the Outlook 2013 MAPI Reference.

MAPI Samples

Provides sample applications.

MAPI Concepts

Provides a guide to understanding and programming with MAPI.

MAPI Reference

Provides references to MAPI programming elements.

See also

Concepts

Outlook 2013 MAPI Reference Overview
Outlook 2013 Messaging API (MAPI) Reference Copyright Notice

Other resources

Outlook 2010: MAPI Reference (Microsoft Download Center)
Document Conventions
Accessibility in Microsoft Office 2010
Microsoft Online Privacy Notice


Getting Started with the Outlook 2013 MAPI Reference

 Copy code hover
[image]

Getting Started with the Outlook 2013 MAPI Reference
Send feedback

Published: July 16, 2012

The Microsoft Outlook 2013 Messaging API (MAPI) Reference describes how to create MAPI solutions that work with Microsoft Outlook 2013. This section describes how to find the various reference and conceptual resources in the Outlook 2013 MAPI Reference.

If you are new to developing solutions for Outlook, see Selecting an API or technology for developing solutions for Outlook 2013 to identify the APIs and technologies that are most appropriate for your needs.

In this section

Outlook 2013 MAPI Reference Overview

Provides overview information about the Outlook 2013 MAPI Reference.

What's New in This Edition

Describes the updates in the Outlook 2013 version of the MAPI Reference.

Commonly Used Header Files

Provides a list of MAPI header files that developers commonly use.

Commonly Used Properties

Describes where to find documentation for required and optional properties.

Commonly Used Objects

Describes how to find information about MAPI objects and interfaces.

API Elements Deprecated in This Edition

Describes the properties that should not be used in the current version of MAPI.

Related sections

MAPI Samples

MAPI Concepts

MAPI Reference


Outlook 2013 MAPI Reference Overview

 Copy code hover
[image]

Outlook 2013 MAPI Reference Overview
See also Send feedback

Published: July 16, 2012

This topic provides overview information about the Outlook 2013 MAPI Reference documentation.

About This Documentation

This documentation applies to the implementation of the Messaging API (MAPI) in Microsoft Outlook 2013.

Previous to Microsoft Office Outlook 2007, the MAPI Programmer's Reference was part of the Microsoft Exchange documentation.

Note Note

Because Exchange has deemphasized the use of MAPI since Microsoft Exchange Server 2007, support for the Exchange implementation is limited.

The Outlook implementation of MAPI differs from the Microsoft Exchange implementation. The Outlook implementation is optimized for running on client computers and emphasizes low latency. The Exchange implementation is intended for servers where high availability and better multithreading are important.

Use this documentation for applications running on end-user systems. For server applications, use the Exchange implementation of MAPI if appropriate, or use current Exchange APIs such as Exchange Web Services. For more information on Exchange Web Services, see the Exchange Web Services Reference.

It may be possible to write applications that work with either the Outlook or Exchange implementations of MAPI. For example, MFCMAPI works well on either platform. The implementations have many common features, but there are differences both obvious and subtle. You will have to test carefully on both platforms if you intend for your application to work in all environments. This testing will require two systems because running both implementations on the same operating system installation is not supported.

Be aware that MAPI is appropriate for low-level access to data in a MAPI store or for building a transport, message store, or address book provider. Because MAPI bypasses Outlook's business logic, you should also consider the use of the Outlook object model when you evaluate APIs for building your solution. The Outlook object model does encapsulate Outlook business logic but is not suitable for multithreaded code, sync providers, or Windows Service applications.

For information about what is new in this edition, see the following topics:

  • What's New in This Edition

  • API Elements Deprecated in This Edition

If you are new to developing MAPI applications for Outlook, see the following topics:

  • Selecting an API or technology for developing solutions for Outlook 2013

  • Commonly Used Header Files

  • Commonly Used Properties

  • Commonly Used Objects

The rest of this reference is categorized into the following three types of information:

  • MAPI Samples - Directs you to many code samples that show the use of various API elements and how to implement basic MAPI providers and create Outlook items.

  • MAPI Concepts - Explains the concepts and architecture of MAPI.

  • MAPI Reference - Provides detailed information about the functions, interfaces, structures, and properties in MAPI.

See also

Other resources

Getting Started with the Outlook 2013 MAPI Reference
MAPI Samples
MAPI Concepts


What's New in This Edition

 Copy code hover
[image]

What's New in This Edition
See also Send feedback

Published: July 16, 2012

The Microsoft Outlook 2013 MAPI Reference has been updated to include documentation for various new features.

New Content

Content has been added for the following features:

  • The topic Getting Started with the Outlook 2013 MAPI Reference has been updated to reference comprehensive information about programming models for your Outlook and MAPI functionality to help you identify the APIs and technologies that are most appropriate for your needs. Links to the referenced Technical Article have also been revised in the following topics:

    • Outlook 2013 MAPI Reference

    • Outlook 2013 MAPI Reference Overview

  • Message Store Provider Example—The Sample Wrapped PST Store Provider code has now been revised to recognize and accommodate Outlook 2013. For more information, see Previously Revised Content in this topic.

  • Autocomplete Stream—The Nickname cache topic, formerly the Nk2 File Format, had been updated to reflect changes in Outlook 2013 as well as Outlook 2010. The following topics have now been revised to provide information about the .nk2 file format developer guidelines for Microsoft Outlook 2003/Microsoft Office Outlook 2007 and binary file parsing. For more information, see Previously Revised Content in this topic.

    • MAPI Profiles

    • Nickname cache

    • Autocomplete Stream

  • Interfaces-The IAddrBook::OpenEntry topic documents a method of opening an address book entry and returning a pointer to the interface used to access it. It previously contained a flag in the ulFlags parameter, MAPI_GAL_ONLY, which could be used to open the Global Address List (GAL), only, and has been revised to include its definition.

  • Properties—The PR_CONVERSATION_KEY named property (PidTagConversationKey Canonical Property) topic has been added and relates to IPM.MessageManager messages in Outlook MAPI only. The following topics relating to it and the Transport-Neutral Encapsulation Format (TNEF) stream documentation have been revised:

    • Mapping Canonical Property Names to MAPI Names

    • Mapping MAPI Names to Canonical Property Names

    • Mapping of TNEF Attributes to MAPI Properties

    • attConversationID and attParentID

Previously Revised Content

Content was added in previous releases of the Outlook MAPI Reference for the following features:

  • Microsoft Outlook 2013 allows for non-traditional deployment scenarios such as side-by-side and Click-to-Run. These scenarios can complicate the logic used to load the proper MAPI library. MAPI developers now have the option of linking explicitly to MAPI functions, and can choose to explicitly link to the MAPI stub of the default MAPI client (for example, Msmapi32.dll of Outlook) without going through the MAPI library and the Windows MAPI stub. For more information about explicit linking as compared with implicit linking, see How to: Link to MAPI Functions. The MAPI Stub Library, posted on the CodePlex website, provides a drop-in replacement for Mapi32.lib that supports building both 32-bit and 64-bit MAPI applications.

  • Support for 64-bit Microsoft Outlook—Reference topics for applicable API elements were updated to correspond to new header files that support 64-bit Outlook. Those header files are available as a download at Outlook 2010: MAPI Header Files. A new code sample was provided in How to: Check the Version of Outlook to show how to check whether the installed version of Outlook is 64-bit Microsoft Outlook 2010 and has been revised for Outlook 2013. If your existing 32-bit MAPI application is going to be running on a 64-bit operating system with 64-bit Outlook installed, you will need to rebuild your 32-bit application as a 64-bit application. For more information about MAPI support for 64-bit Outlook, see Building MAPI Applications on 32-Bit and 64-Bit Platforms.

  • Message Store Provider Example—The Sample Wrapped PST Store Provider had previously been updated to support 64-bit architecture. The Example's Initializing a Wrapped PST Store Provider topic has now been expanded to provide information about the "Wrapped PST and Unicode Paths."

  • Autocomplete Stream—The Nickname cache topic, formerly the Nk2 File Format, has been updated to reflect changes in Outlook 2013 as well as Outlook 2010. Information such as the autocomplete list, which is the list of names that displays in the To, Cc, and Bcc edit boxes while a user is composing an email, is now saved to the Autocomplete Stream of a message on the local computer rather than saving it to a file as in Outlook 2007.

    • Interacting with the Autocomplete Stream

    • Loading the Autocomplete Stream

    • Saving the Autocomplete Stream

  • Fast shutdown support for MAPI clients—MAPI clients can now initiate a quick shutdown and have the MAPI subsystem notify loaded providers to minimize data loss from the fast shutdown. Additional interfaces were added for the client and provider to support fast shutdown. For more information about fast shutdown, see Client Shutdown in MAPI.

  • Stream structure for field definitions for an Outlook item—Documentation for a binary stream for the PidLidPropertyDefinitionStream property was added. This property specifies definitions of all custom fields and data-binding settings for built-in fields of an Outlook item.

  • Personal Store Override—The following interfaces and their respective methods were added to support overriding the Personal Folders file (PST) store providers PSTDisableGrow policy:

    IPSTOVERRIDEREQ::IUnknown

    IPSTOVERRIDE1::IUnknown

  • Using Multiple Exchange Accounts—Documentation for the MAPI Address Book API was added. This API was enhanced to support multiple Exchange accounts in Microsoft Outlook 2010 and now includes Microsoft Outlook 2013. To resolve addresses correctly with multiple Exchange accounts, use the new functions that take an account context so that calls to the address book search the correct Exchange account.

  • MAPI File Formats—MAPI configuration information has been expanded to explain how you can use paths in Registering Services and Service Providers in MapiSvc.inf.

  • Properties—The following tagged properties were added in addition to documentation for 38 other tagged properties and named properties that had previously been added:

    • PidTagAddressBookChooseDirectoryAutomatically

    • PidTagAssociatedSharingProvider

    • PidTagRoamingBinary

    • PidTagSenderSmtpAddress

    • PidTagSentRepresentingSmtpAddress

    • PidTagStoreEntryIdEmsmdbV1

  • MAPI Constants—The consolidated MAPI Constants have been expanded. In previous releases, they were distributed in a number of topics but are now collected in a single topic to make them easier to discover and use. They have also been expanded to provide more extensive coverage including the following sections:

    • Definitions for Exchange Address Book and Message Store Error Codes

    • Definitions for Exchange Server Mailbox Cached Mode Quotas

See also

Other resources

Getting Started with the Outlook 2013 MAPI Reference
CodePlex


Commonly Used Header Files

 Copy code hover
[image]

Commonly Used Header Files
See also Send feedback

Published: July 16, 2012

Each reference topic includes a table that names the MAPI header file where the API element is defined. The following table describes the MAPI header files that developers frequently use.

Header file | Description
Mapi.h | Defines structures and constants.
Mapiaux.h | Defines additional interfaces, structures, and constants used by the Messaging Applications Programming Interface.
Mapicode.h | Defines status codes for error values.
Mapidbg.h | Defines macros for debugging.
Mapidefs.h | Defines frequently used event types, property types, flags, structures, and interfaces.
Mapiform.h | Defines forms elements.
Mapiguid.h | Defines GUIDs.
Mapinis.h | Defines utilities that support internationalization.
Mapioid.h | Defines MAPI object identifiers.
Mapispi.h | Defines flags and interfaces that MAPI implements for service providers and message services.
Mapitags.h | Defines property tags.
Mapiutil.h | Defines utility interfaces and functions.
Mapival.h | Defines validation macros.
Mapiwin.h | Defines types, constants, flags, functions, and macros for developing single-source service providers.
Mapiwz.h | Defines prototypes and constants for the provider wizard.
Mapix.h | Defines flags and interfaces that MAPI implements for clients.
Mspst.h | Defines properties of the personal information store (.pst file).

For information about how to obtain MAPI header files, see How to: Install MAPI Header Files.

See also

Other resources

Getting Started with the Outlook 2013 MAPI Reference


Commonly Used Properties

 Copy code hover
[image]

Commonly Used Properties
Send feedback

Published: July 16, 2012

Lists of required and optional MAPI properties are documented in several places.

See the following interfaces for lists of properties associated with objects that support these interfaces:

  • IABContainer : IMAPIContainer

  • IAttach : IMAPIProp

  • IDistList : IMAPIContainer

  • IMailUser : IMAPIProp

  • IMAPIContainer : IMAPIProp

  • IMAPIStatus : IMAPIProp

  • IMessage : IMAPIProp

  • IMsgStore : IMAPIProp

  • IProfSect : IMAPIProp

For lists of properties required for tables, see the documentation for each type of table in MAPI Tables.

For lists of required and optional message properties for message classes defined by MAPI, see the following topics:

  • Required Properties for All Messages

  • Required Report Message Properties

  • Optional Report Message Properties

  • Recipient Properties for All Messages

  • Recipient Properties for Delivery Status Reports


Commonly Used Objects

 Copy code hover
[image]

Commonly Used Objects
Send feedback

Published: July 16, 2012

Information about objects is documented in various sections of the Microsoft Outlook 2013 MAPI Reference. Because almost all MAPI objects expose a single MAPI interface, the approach is to treat objects and the interfaces that they expose as synonymous.

You can find information about objects and interfaces in the following sections.

  • MAPI Interfaces

    Describes the interfaces in the Outlook 2013 MAPI Reference. In this section you can, for example, locate information about how to implement and use a folder under its standard interface, IMAPIFolder.

  • MAPI Object and Interface Overview

    Introduces the Component Object Model as it relates to MAPI, describes the MAPI object hierarchy and containment model, maps objects to interfaces, and describes implementation responsibilities.

  • MAPI Property Overview

    Describes how objects manage and clients work with properties.

  • MAPI Tables

    Describes in detail how to implement and use a table object, and discusses the composition and purpose of the different types of tables.

  • MAPI Forms

    Describes the various objects for the implementation and use of forms.

  • MAPI Application Development

    Provides information about the following types of objects:

    • Forms

    • Messages

    • Attachments

    • Recipients

    • Status objects

    • Profile and message service objects

  • Developing a MAPI Client Application

    Describes how to use objects to implement a MAPI client application.

  • MAPI Service Providers

    Describes how to use support and progress objects and how to implement a status object and display table.

  • Developing a MAPI Address Book Provider

    Describes how to implement the address book logon and provider objects, address book containers, messaging users, distribution lists, and related tables.

  • Developing a MAPI Transport Provider

    Describes how to implement the transport logon and provider objects, status object, Transport Neutral Encapsulation Format (TNEF) object, and folders.

  • Developing a MAPI Message Store Provider

    Describes how to implement the message store logon and provider objects, message stores, folders, messages, attachments, recipients, and related tables.

  • Developing MAPI Form Servers

    Describes how to implement form objects.


API Elements Deprecated in This Edition

 Copy code hover
[image]

API Elements Deprecated in This Edition
See also Send feedback

Published: July 16, 2012

The following API elements are deprecated in Microsoft Outlook 2013. They are no longer supported and you should not use them in new projects.

Deprecation of Message and Recipient Options

The following API elements are deprecated in this release because of obsolete message and recipient options:

  • IXPLogon::RegisterOptions—The MAPI subsystem no longer calls this method to establish any default values for message and recipient options for a transport provider.

  • OPTIONDATA—This data structure that supported properties for message and recipient options is obsolete. The MAPI subsystem no longer calls IXPLogon::RegisterOptions to obtain any message or recipient options that a transport provider supports for a particular address type.

  • OPTIONCALLBACK—This function prototype, which a transport provider used to declare a callback function and which, in turn, the MAPI subsystem used to resolve the provider's properties, is obsolete. The MAPI subsystem no longer calls IXPLogon::RegisterOptions or uses any callback function returned by the transport provider.

  • IMAPISession::MessageOptions—MAPI client and service providers should no longer call this method to display properties or let users set properties that control a particular message and address type. The method always returns MAPI_E_NOT_FOUND, which indicates that there are no message options for the particular message.

  • IMAPISession::QueryDefaultMessageOpt—MAPI client and service providers should no longer call this method to retrieve properties that control message options for a particular address type. The method no longer returns a pointer to any array of property values.

  • IAddrBook::RecipOptions—MAPI client and service providers should no longer call this method to display properties or let users set properties that control processing for a recipient of a particular address type. The method always returns MAPI_W_ERRORS_RETURNED, which indicates that there are no recipient options for the particular recipient.

  • IAddrBook::QueryDefaultRecipOpt—MAPI client and service providers should no longer call this method to retrieve properties that control recipient options for a particular address type. The method no longer returns a pointer to any array of property values.

See also

Other resources

Getting Started with the Outlook 2013 MAPI Reference


MAPI Samples

 Copy code hover
[image]

MAPI Samples
Send feedback

Published: July 16, 2012

This section contains code samples that show how to achieve certain tasks or implement certain service providers using MAPI. MFCMAPI is also used in this reference to demonstrate the use of many APIs. To run any of the samples on the Windows Vista, Windows Server 2008, Windows XP, or Windows Server 2003 operating systems, you must first set up the MAPI runtime system. For more information, see MAPI Programming Overview.

In this section

MFCMAPI as a Code Sample

Describes how to download and use MFCMAPI as a sample application for this reference.

MAPI Service Provider Samples

Shows examples of MAPI service providers.

Creating Outlook Items by Using MAPI

Shows code sample of how to create Outlook items using MAPI.

Related sections

Getting Started with the Outlook 2013 MAPI Reference

MAPI Concepts

MAPI Reference


MFCMAPI as a Code Sample

 Copy code hover
[image]

MFCMAPI as a Code Sample
See also Send feedback

Published: July 16, 2012

The MFCMAPI sample uses the Messaging API to provide access to MAPI stores through a graphical user interface. After you download this sample, you can use the source files to examine example usage cases for many of the MAPI interfaces and references. For more information, see MAPI Interfaces.

Platforms:

Microsoft Visual Studio 2008 to compile for Windows 7, Windows Vista, Windows Server 2008, Windows XP SP2, and Windows Server 2003 SP1

To download MFCMAPI

  1. On the MFCMAPI page, click the Source Code tab.

  2. Under Recent Check-Ins, click Download for the most recent build.

  3. Read the license agreement, and then click I Agree.

  4. In the File Download dialog box, click Save. In the Save As dialog box, locate the folder in which you want to save the source files, and then click Save.

  5. In the Download Complete dialog box, click Open Folder. You can also click Close to close the dialog box and locate the zipped source files in the folder that you saved them in.

  6. Right-click the MFCMAPI-<version number>.zip file, and then click Extract All. In the dialog box that appears, click Extract to extract the files to the folder that is displayed. You can also click Browse to select or create a different folder.

  7. Run Visual Studio 2008 as an administrator.

    Note Note

    If your computer is running Windows XP, you must be logged in as an administrator. If your computer is running Windows Vista, you must be logged in as an administrator and you must right-click the Visual Studio 2008 icon and then click Run as administrator.

  8. In Visual Studio 2008, click File, point to Open, and then click Project/Solution.

  9. Browse to the location where you saved the sample, select MFCMapi.vcproj, and then click Open.

  10. On the Build menu, click Build Solution.

  11. In the Save File As dialog box, click Save.

To use MFCMAPI as a code sample

In Solution Explorer, expand the MFCMapi project and examine the files in the Header Files, Resource Files, and Source Files nodes for programming scenarios.

Many method topics in the MAPI Interfaces section point to MFCMAPI source files for programming examples. For example, in IMsgStore::GetReceiveFolderTable you are instructed to look at the function CMsgStoreDlg::OnDisplayReceiveFolderTable in the MsgStoreDlg.cpp file.

See also

Other resources

MAPI Samples


MAPI Service Provider Samples

 Copy code hover
[image]

MAPI Service Provider Samples
Send feedback

Published: July 16, 2012

This section contains code samples of three MAPI service providers:

  • Downloading the Outlook MAPI Samples

    This topic describes how to download the samples.

  • Address Book Provider Sample

    This sample supports a single read-only container for display names and e-mail addresses, which are read from a flat binary file.

  • Message Store Provider Sample

    This sample uses directories as folders and OLE 2.0 document files as messages. The sample supports all required features for a default message store.

  • Transport Provider Sample

    This sample uses files and directories to transmit and receive messages.

To run any of these samples on the Windows 7, Windows Vista, Windows Server 2008, Windows XP, or Windows Server 2003 operating systems, you must first set up the MAPI runtime system. For more information, see MAPI Programming Overview.


Downloading the Outlook MAPI Samples

 Copy code hover
[image]

Downloading the Outlook MAPI Samples
See also Send feedback

Published: July 16, 2012

The Microsoft Outlook MAPI samples include an address book provider, a message store provider, and a transport provider.

To download the Sample Address Book Provider

  1. To download the Outlook MAPI samples, click the Home tab on the Outlook Messaging API (MAPI) Code Samples page.

  2. On the Home tab, click Click here to download the source for Outlook 2010 MAPI Samples.

  3. Read the licensing agreement and, if you agree, click I Agree.

  4. On the File Download dialog box, click Save. On the Save As dialog box, locate the folder in which you want to save the source files and then click Save.

  5. On the Download Complete dialog box, click Close to close the dialog box.

See also

Concepts

Address Book Provider Sample
Message Store Provider Sample
Transport Provider Sample


Address Book Provider Sample

 Copy code hover
[image]

Address Book Provider Sample
Send feedback

Published: July 16, 2012

This sample supports a single read-only container for display names and e-mail addresses, which are read from a flat binary file. The sample supports one-off templates and all configuration options except the Profile Wizard.

You can download this sample from Outlook Messaging API (MAPI) Code Samples.

Executable: | SABP32.dll
Source code directory: | SampleAddressBookProvider\SABP
Language: | C++
Platforms: | Microsoft Visual Studio 2008 to compile for Windows Vista, Windows Server 2008, Windows XP SP2, and Windows Server 2003 SP1

Supported Features

This sample supports the following features:

  • Table restrictions. The sample implements prefix-match and ambiguous-name resolution. It does not implement the full MAPI restriction language, and restrictions are supported only on the display name.

  • A details display table for messaging users.

  • One-off addresses.

  • An advanced search dialog box.

  • An IMAPIStatus : IMAPIProp interface. This interface is partially supported; its IMAPIProp methods are delegated to the IPropData interface. For more information, see the IPropData : IMAPIProp interface.

  • Interactive and programmatic configuration.

Unsupported Features

This sample does not support the following features:

  • Sorting.

  • Distribution lists.

  • Creating, deleting, and modifying entries.

  • Properties with multiple values.

  • Named properties.

  • Distinguishing between first and last names in display names.

To install the Sample Address Book Provider

  1. To download the Sample Address Book Provider, see Downloading the Outlook MAPI Samples.

  2. Locate the folder where you saved the Outlook MAPI Samples. Right-click the OutlookMAPISamples-<version number> zip folder and click Extract All.

  3. Click Browse, select the location where you want to save the sample, and click Extract.

  4. Run Visual Studio 2008.

  5. In Visual Studio 2008, click File, select Open, and then click Project/Solution.

  6. Browse to the location where you saved the sample, click SABP.vcproj, and then click Open.

  7. On the Build menu, click Build Solution.

  8. In the Save File As dialog box, click Save.

  9. In the folder where you saved the sample, right-click the install.bat file and click Run as administrator.

  10. In the User Account Control dialog box, click Continue.

    Note Note

    Install.bat copies the .dll to the default Microsoft Office installation folder, C:\Program Files\Microsoft Office\Office12\. If you have installed Office products in a different location, right-click Install.bat and click Edit. The file opens in Notepad. Replace the default installation path with the installation path used on your computer.


Message Store Provider Sample

 Copy code hover
[image]

Message Store Provider Sample
Send feedback

Published: July 16, 2012

The Sample Wrapped PST Store Provider uses a Personal Folders file (PST) provider as the back end for storing data. The wrapped PST store provider should be used together with the Replication API.

The Replication API enables you to replicate items from a back-end data repository into a Microsoft Outlook PST store. You use the Replication API to replicate the data into a dedicated PST store and keep track of the synchronization state. For more information, see About the Replication API.

Most of the functions in the Sample Wrapped PST Store Provider pass their arguments directly to the underlying PST provider. Certain functions require special implementation and are described in the following topics.

Executable: | WrpPST32.dll
Source code directory: | SampleWrappedPSTStoreProvider\WrapPST
Language: | C++
Platforms: | Microsoft Visual Studio 2008 to compile for Windows Vista, Windows Server 2008, Windows XP SP2, and Windows Server 2003 SP1

Supported Features

This sample supports Microsoft Outlook 2010 64-bit and has now been revised for Outlook 2013. See the following topics for additional information:

  • About the Replication API

  • Initializing a Wrapped PST Store Provider

  • Logging On to a Wrapped PST Store Provider

  • Using a Wrapped PST Store Provider

  • Shutting Down a Wrapped PST Store Provider

To install the Sample Wrapped PST Store Provider

  1. To download the Sample Wrapped PST Provider, see Downloading the Outlook MAPI Samples.

  2. Locate the folder where you saved the Outlook MAPI Samples. Right-click the OutlookMAPISamples-<version number> zip folder and then click Extract All.

  3. Click Browse, select the location where you want to save the sample, and then click Extract.

  4. Run Microsoft Visual Studio 2008.

  5. In Microsoft Visual Studio 2008, click File, select Open, and then click Project/Solution.

  6. Browse to the location where you saved the sample, click WrapPST.vcproj, and then click Open.

  7. On the Build menu, click Build Solution.

  8. In the Save File As dialog box, click Save.

  9. In the folder where you saved the sample, right-click the install.bat file and then click Run as administrator.

  10. In the User Account Control dialog box, click Continue.


Installing the Sample Wrapped PST Store Provider

 Copy code hover
[image]

Installing the Sample Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

This topic takes you through the steps to download and install the Sample Wrapped PST Store Provider. The Sample Wrapped PST Store Provider, WrapPST, implements a wrapped PST store provider that is intended to be used in conjunction with the Replication API. For more information about the Replication API, see About the Replication API.

Install the Sample Wrapped PST Store Provider

  1. To download the Sample Wrapped PST Store Provider, see Outlook 2007 Auxiliary Reference Code Samples and Redistributable Installer.

  2. Open the SampleWrappedPSTStoreProvider folder and click Extract All Files.

  3. Click Browse, select the location where you want to save the sample, and click OK.

  4. Click Extract. The folder you selected appears and contains the extracted files.

  5. Open Visual Studio 2005 as an administrator.

    Note Note

    If your computer is running Windows XP, you must be logged in as an Administrator. If your computer is running Windows Vista, you must be logged in as an Administrator and you must right-click the Visual Studio 2005 icon and click Run as administrator.

  6. In Visual Studio 2005, click File, select Open, and then click Project/Solution.

  7. Browse to the location where you saved the sample, click WrapPST, and then click Open.

  8. On the Build menu, click Build Solution.

  9. In the Save File As dialog box, click Save.

  10. In the folder where you saved the sample, right-click the Install.bat file and click Run as administrator.

  11. In the User Account Control dialog box, click Continue.

See also

Concepts

About the Sample Wrapped PST Store Provider
Initializing a Wrapped PST Store Provider
Logging On to a Wrapped PST Store Provider
Using a Wrapped PST Store Provider
Shutting Down a Wrapped PST Store Provider


Initializing a Wrapped PST Store Provider

 Copy code hover
[image]

Initializing a Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

To implement a wrapped Personal Folders file (PST) store provider, you must initialize the wrapped PST store provider by using the MSProviderInit function as an entry point. After the provider's DLL is initialized, the MSGSERVICEENTRY function configures the wrapped PST store provider.

In this topic, the MSProviderInit function and the MSGSERVICEENTRY function are demonstrated by using code examples from the Sample Wrapped PST Store Provider. The sample implements a wrapped PST provider that is intended to be used in conjunction with the Replication API. For more information about downloading and installing the Sample Wrapped PST Store Provider, see Installing the Sample Wrapped PST Store Provider. For more information about the Replication API, see About the Replication API.

After you have initialized a wrapped PST store provider, you must implement functions so that MAPI and the MAPI spooler can log onto the message store provider. For more information, see Logging On to a Wrapped PST Store Provider.

Initialization Routine

All wrapped PST store providers must implement the MSProviderInit function as an entry point to initialize the provider's DLL. MSProviderInit checks to see if the version number of the service provider interface, ulMAPIVer, is compatible with the current version number, CURRENT_SPI_VERSION. The function saves the MAPI memory management routines into the g_lpAllocateBuffer, g_lpAllocateMore, and g_lpFreeBuffer parameters. These memory management routines should be used throughout the wrapped PST store implementation for memory allocation and deallocation.

MSProviderInit() Example

Copy code Copy code
STDINITMETHODIMP MSProviderInit (
    HINSTANCE /*hInstance*/,
    LPMALLOC lpMalloc,
    LPALLOCATEBUFFER lpAllocateBuffer,
    LPALLOCATEMORE lpAllocateMore,
    LPFREEBUFFER lpFreeBuffer,
    ULONG ulFlags,
    ULONG ulMAPIVer,
    ULONG FAR * lpulProviderVer,
    LPMSPROVIDER FAR * lppMSProvider)
{
    Log(true,"MSProviderInit function called\n");
    if (!lppMSProvider || !lpulProviderVer) return MAPI_E_INVALID_PARAMETER;
    HRESULT hRes = S_OK;

    *lppMSProvider = NULL;
    *lpulProviderVer = CURRENT_SPI_VERSION;
    if (ulMAPIVer < CURRENT_SPI_VERSION)
    {
        Log(true,"MSProviderInit: The version of the subsystem cannot handle this"
            + "version of the provider\n");
        return MAPI_E_VERSION;
    }

    Log(true,"MSProviderInit: saving off memory management routines\n");
    g_lpAllocateBuffer = lpAllocateBuffer;
    g_lpAllocateMore = lpAllocateMore;
    g_lpFreeBuffer = lpFreeBuffer;
    HMODULE hm = LoadLibrary("C:\\Program Files\\Common Files\\System" +
        "\\MSMAPI\\1033\\MSPST32.dll" );
    if (!hm) hm = LoadLibrary("C:\\Program Files\\Microsoft Office\\Office12" +
        "\\MSPST32.dll" );
    Log(true,"LoadLibrary returned 0x%08X\n", hm);

    LPMSPROVIDERINIT pMsProviderInit = NULL;
    if (hm)
    {
        pMsProviderInit = (LPMSPROVIDERINIT)GetProcAddress(hm, "MSProviderInit");
        Log(true,"GetProcAddress returned 0x%08X\n", pMsProviderInit);
    }
    else hRes = E_OUTOFMEMORY;
    if (pMsProviderInit)
    {
        Log(true,"Calling pMsProviderInit\n");
        CMSProvider* pWrappedProvider = NULL;
        LPMSPROVIDER pSyncProviderObj = NULL;
        hRes = pMsProviderInit(
            hm,// not hInstance: first param is handle of module in which the function lives
            lpMalloc,
            lpAllocateBuffer,
            lpAllocateMore,
            lpFreeBuffer,
            ulFlags,
            ulMAPIVer,
            lpulProviderVer,
            &pSyncProviderObj
            );
        Log(true,"pMsProviderInit returned 0x%08X\n", hRes);
        if (SUCCEEDED(hRes))
        {
            pWrappedProvider = new CMSProvider (pSyncProviderObj);
            if (NULL == pWrappedProvider)
            {
                Log(true,"MSProviderInit: Failed to allocate new CMSProvider object\n");
                hRes = E_OUTOFMEMORY;
            }
            // Copy pointer to the allocated object back into the
            //return IMSProvider object pointer
            *lppMSProvider = pWrappedProvider;
        }
    }
    else hRes = E_OUTOFMEMORY;
    return hRes;
}

Wrapped PST and Unicode Paths

To retrofit the original sample prepared in Microsoft Visual Studio 2008 to use Unicode paths to the NST for use in Unicode-enabled Microsoft Outlook 2010 and Outlook 2013, the CreateStoreEntryID routine, which produces the entry identifier, should use one format for ASCII paths, and another for Unicode paths. These are represented as structures in the following example.

Copy code Copy code
typedef struct                              // short format
{
         BYTE             rgbFlags[4];     // MAPI-defined flags
         MAPIUID          uid;             // PST provider MUID
         BYTE             bReserved;       // Reserved (must be zero)
         CHAR             szPath[1];       // Full path to store (ASCII)
 } EIDMS;

// Unicode version of EIDMSW is an extension of EIDMS
// and szPath is always NULL
typedef struct                              // Long format to support Unicode path and name
{
         BYTE             rgbFlags[4];     // MAPI-defined flags
         MAPIUID          uid;             // PST provider MUID
         BYTE             bReserved;       // Reserved (must be zero)
         CHAR             szPath[1];       // ASCII path to store is always NULL
         WCHAR            wzPath[1];       // Full path to store (Unicode)
} EIDMSW;
Important note Important

The differences in these structures are two NULL bytes prior to a Unicode path. If you need to interpret the entry identifier in the "Service Entry Routine" that follows, one way to determine whether that is the case or not would be to cast as EIDMS first, then check whether the szPath[0] is NULL. If it is, cast it as EIDMSW instead.

Service Entry Routine

The MSGSERVICEENTRY function is the message service entry point where the wrapped PST store provider is configured. The function calls GetMemAllocRoutines() to get the MAPI memory management routines. The function uses the lpProviderAdmin parameter to locate the profile section for the provider and sets the properties in the profile.

ServiceEntry() Example

Copy code Copy code
HRESULT STDAPICALLTYPE ServiceEntry (
    HINSTANCE /*hInstance*/,
    LPMALLOC lpMalloc,
    LPMAPISUP lpMAPISup,
    ULONG ulUIParam,
    ULONG ulFlags,
    ULONG ulContext,
    ULONG cValues,
    LPSPropValue lpProps,
    LPPROVIDERADMIN lpProviderAdmin,
    LPMAPIERROR FAR *lppMapiError)
{
    if (!lpMAPISup || !lpProviderAdmin) return MAPI_E_INVALID_PARAMETER;
    HRESULT         hRes = S_OK;
    Log(true,"ServiceEntry function called\n");
    Log(true,"About to call NSTServiceEntry\n");

    if (MSG_SERVICE_INSTALL         == ulContext ||
        MSG_SERVICE_DELETE            == ulContext ||
        MSG_SERVICE_UNINSTALL        == ulContext ||
        MSG_SERVICE_PROVIDER_CREATE == ulContext ||
        MSG_SERVICE_PROVIDER_DELETE == ulContext)
    {
        // These contexts are not supported
        return MAPI_E_NO_SUPPORT;
    }

    // Get memory routines
    hRes = lpMAPISup->
        GetMemAllocRoutines(&g_lpAllocateBuffer,&g_lpAllocateMore,&g_lpFreeBuffer);
    HMODULE hm = LoadLibrary("C:\\Program Files\\Common Files\\System" +
        "\\MSMAPI\\1033\\MSPST32.dll" );
    if (!hm) hm = LoadLibrary("C:\\Program Files\\Microsoft Office\\Office12" +
        "\\MSPST32.dll" );
    Log(true, "Got module 0x%08X\n", hm);
    if (!hm) return E_OUTOFMEMORY;
    LPMSGSERVICEENTRY pNSTServiceEntry =
        (LPMSGSERVICEENTRY)GetProcAddress(hm, "NSTServiceEntry");
    Log(true, "Got procaddress  0x%08X\n", pNSTServiceEntry);
    if (!pNSTServiceEntry) return E_OUTOFMEMORY;

    // Get profile section
    LPPROFSECT lpProfSect = NULL;
    hRes = lpProviderAdmin->
        OpenProfileSection((LPMAPIUID) NULL, NULL, MAPI_MODIFY, &lpProfSect);
    // Set passed in props into the profile
    if (lpProps && cValues)
    {
        hRes = lpProfSect->SetProps(cValues,lpProps,NULL);
    }
    // Make sure there is a store path set
    if (SUCCEEDED(hRes)) hRes = SetOfflineStoreProps(lpProfSect,ulUIParam);
    ULONG            ulProfProps = 0;
    LPSPropValue    lpProfProps = NULL;

    // Evaluate props
    hRes = lpProfSect->GetProps((LPSPropTagArray)&sptClientProps,
                                fMapiUnicode,
                                &ulProfProps,
                                &lpProfProps);
    if (SUCCEEDED(hRes))
    {
        CSupport * pMySup = NULL;
        pMySup = new CSupport(lpMAPISup, lpProfSect);
        if (!pMySup)
        {
            Log(true,"MSProviderInit: Failed to allocate new CSupport object\n");
            hRes = E_OUTOFMEMORY;
        }
        if (SUCCEEDED(hRes))
        {
            hRes = pNSTServiceEntry(
                hm,
                lpMalloc,
                pMySup,
                ulUIParam,
                ulFlags,
                ulContext,
                ulProfProps,
                lpProfProps,
                NULL,//pAdminProvObj, //Don't pass this when creating an NST
                lppMapiError);
            if (SUCCEEDED(hRes))
            {
                // Finish setting up the profile
                hRes = InitStoreProps(
                    lpMAPISup,
                    lpProfSect,
                    lpProviderAdmin);
                hRes = lpProfSect->SaveChanges(KEEP_OPEN_READWRITE);
            }
        }
    }
    Log(true, "Ran pNSTServiceEntry 0x%08X\n", hRes);
    MyFreeBuffer(lpProfProps);
    if (lpProfSect) lpProfSect->Release();

    return hRes;
}

See also

Concepts

About the Sample Wrapped PST Store Provider
Installing the Sample Wrapped PST Store Provider
Logging On to a Wrapped PST Store Provider
Using a Wrapped PST Store Provider
Shutting Down a Wrapped PST Store Provider


Logging On to a Wrapped PST Store Provider

 Copy code hover
[image]

Logging On to a Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

Before you can log on MAPI to a wrapped PST store provider, you must initialize and configure the wrapped Personal Folders file (PST) store provider. For more information, see Initializing a Wrapped PST Store Provider.

After you have initialized and configured a wrapped PST store provider, you must implement two logon routines. The IMSProvider::Logon function logs on MAPI to the wrapped PST store provider. The IMSProvider::SpoolerLogon function logs on the MAPI spooler to the wrapped PST store provider.

In this topic, the IMSProvider::Logon function and the IMSProvider::SpoolerLogon function are demonstrated by using code examples from the Sample Wrapped PST Store Provider. The sample implements a wrapped PST provider that is intended to be used in conjunction with the Replication API. For more information about downloading and installing the Sample Wrapped PST Store Provider, see Installing the Sample Wrapped PST Store Provider. For more information about the Replication API, see About the Replication API.

After MAPI and the MAPI spooler are logged on to the wrapped PST store provider, it is ready to be used. For more information, see Using a Wrapped PST Store Provider.

MAPI Logon Routine

After the wrapped PST store provider is initialized, you must implement the IMSProvider::Logon function to log on MAPI to the wrapped PST store. This function validates user credentials and gets the configuration properties for the provider. You must also implement the SetOLFIInOST function to set the Offline File Info (OLFI). OLFI is a queue of long-term ID structures that is used by the wrapped PST store provider to assign an Entry ID for a new message or folder in offline mode. Finally, the IMSProvider::Logon function returns a message store object that the MAPI spooler and client applications can log on to in the ppMDB parameter.

CMSProvider::Logon() Example

Copy code Copy code
STDMETHODIMP CMSProvider::Logon(
    LPMAPISUP pSupObj,
    ULONG ulUIParam,
    LPTSTR pszProfileName,
    ULONG cbEntryID,
    LPENTRYID pEntryID,
    ULONG ulFlags,
    LPCIID pInterface,
    ULONG * pcbSpoolSecurity,
    LPBYTE * ppbSpoolSecurity,
    LPMAPIERROR * ppMAPIError,
    LPMSLOGON * ppMSLogon,
    LPMDB * ppMDB)
{
    HRESULT hRes = S_OK;
    LPMDB lpPSTMDB = NULL;
    CMsgStore* pWrappedMDB = NULL;

    Log(true,"CMSProvider::Logon Pst logon Called\n");

    LPPROFSECT lpProfSect = NULL;
    CSupport * pMySup = NULL;
    hRes = GetGlobalProfileObject(pSupObj,&lpProfSect);
    pMySup = new CSupport(pSupObj, lpProfSect);
    if (!pMySup)
    {
        Log(true,"CMSProvider::Logon: Failed to allocate new CSupport object\n");
        hRes = E_OUTOFMEMORY;
    }
    if (SUCCEEDED(hRes))
    {
        ulFlags = (ulFlags & ~MDB_OST_LOGON_ANSI) | MDB_OST_LOGON_UNICODE;
        hRes = m_pPSTMS->Logon(
            pMySup,
            ulUIParam,
            pszProfileName,
            cbEntryID,
            pEntryID,
            ulFlags,
            pInterface,
            pcbSpoolSecurity,
            ppbSpoolSecurity,
            ppMAPIError,
            ppMSLogon,
            &lpPSTMDB);
    }
    Log(true,"CMSProvider::Logon returned 0x%08X\n", hRes);

    // Set up the MDB to allow synchronization
    if (SUCCEEDED(hRes))
    {
        hRes = SetOLFIInOST(lpPSTMDB);
        Log(true,"SetOLFIInOST returned 0x%08X\n", hRes);
    }
    // Wrap the outgoing MDB
    pWrappedMDB = new CMsgStore (lpPSTMDB);
    if (NULL == pWrappedMDB)
    {
        Log(true,"CMSProvider::Logon: Failed to allocate new CMsgStore object\n");
        hRes = E_OUTOFMEMORY;
    }
    // Copy pointer to the allocated object back into the return LPMDB object pointer
    *ppMDB = pWrappedMDB;
    if (lpProfSect) lpProfSect->Release();

    return hRes;
}

MAPI Spooler Logon Routine

Similar to IMSProvider::Logon, you must implement the IMSProvider::SpoolerLogon function to log the MAPI spooler on to the wrapped PST store. A message store object that the MAPI spooler and client applications can log on to is returned in the ppMDB parameter.

CMSProvider::SpoolerLogon() Example

Copy code Copy code
STDMETHODIMP CMSProvider::SpoolerLogon (
    LPMAPISUP pSupObj,
    ULONG ulUIParam,
    LPTSTR pszProfileName,
    ULONG cbEntryID,
    LPENTRYID pEntryID,
    ULONG ulFlags,
    LPCIID pInterface,
    ULONG cbSpoolSecurity,
    LPBYTE pbSpoolSecurity,
    LPMAPIERROR * ppMAPIError,
    LPMSLOGON * ppMSLogon,
    LPMDB * ppMDB)
{
    HRESULT hRes = S_OK;

    Log(true,"CMSProvider::SpoolerLogon\n");
    LPPROFSECT lpProfSect = NULL;
    CSupport * pMySup = NULL;
    hRes = GetGlobalProfileObject(pSupObj,&lpProfSect);
    pMySup = new CSupport(pSupObj, lpProfSect);
    if (!pMySup)
    {
        Log(true,"CMSProvider::SpoolerLogon: " +
            "Failed to allocate new CSupport object\n");
        hRes = E_OUTOFMEMORY;
    }
    if (SUCCEEDED(hRes))
    {
        hRes = m_pPSTMS->SpoolerLogon(
            pMySup,//pSupObj,
            ulUIParam,
            pszProfileName,
            cbEntryID,
            pEntryID,
            ulFlags,
            pInterface,
            cbSpoolSecurity,
            pbSpoolSecurity,
            ppMAPIError,
            ppMSLogon,
            ppMDB);
    }
    Log(true,"CMSProvider::SpoolerLogon returned 0x%08X\n", hRes);

    return hRes;
}

See also

Concepts

About the Sample Wrapped PST Store Provider
Installing the Sample Wrapped PST Store Provider
Initializing a Wrapped PST Store Provider
Using a Wrapped PST Store Provider
Shutting Down a Wrapped PST Store Provider


Using a Wrapped PST Store Provider

 Copy code hover
[image]

Using a Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

Before you can use a wrapped Personal Folders file (PST) store provider, you must initialize and configure the wrapped PST store provider. After the wrapped PST store provider is configured, you must implement functions so that MAPI and the MAPI spooler can log on to the message store provider. For more information about initializing and logging on to a wrapped PST store provider, see Initializing a Wrapped PST Store Provider and Logging On to a Wrapped PST Store Provider.

The IMAPISupport::IUnknown interface provides implementations for tasks that are commonly performed by message store providers. This interface must be wrapped for the Sample Wrapped PST Store Provider to work. The IMAPISupport::OpenProfileSection function requires special implementation. All other functions can pass their parameters to the underlying wrapped object.

In this topic, the IMAPISupport::OpenProfileSection function is demonstrated by using a code example from the Sample Wrapped PST Store Provider. The sample implements a wrapped PST provider that is intended to be used in conjunction with the Replication API. For more information about downloading and installing the Sample Wrapped PST Store Provider, see Installing the Sample Wrapped PST Store Provider. For more information about the Replication API, see About the Replication API.

When you finish using a wrapped PST store provider, you must properly shut down the wrapped PST store provider. For more information, see Shutting Down a Wrapped PST Store Provider.

Open Profile Section Routine

The IMAPISupport::OpenProfileSection function opens a section of the current profile. The function requires special handling in the wrapped PST store provider implementation. When the pgNSTGlobalProfileSectionGuid is requested, the function returns the profile section that is cached.

CSupport::OpenProfileSection() Example

Copy code Copy code
STDMETHODIMP CSupport::OpenProfileSection(
    LPMAPIUID lpUid,
    ULONG ulFlags,
    LPPROFSECT * lppProfileObj)
{
    Log(true,"CSupport::OpenProfileSection\n");
    if (lpUid &&
        IsEqualMAPIUID(lpUid, (void *)&pbNSTGlobalProfileSectionGuid) &&
        m_lpProfSect)
    {
        // Allow the opening of the Global Section
        if (m_lpProfSect)
        {
            *lppProfileObj = m_lpProfSect;
            (*lppProfileObj)->AddRef();
            return S_OK;
        }
    }
    return m_pMAPISup->OpenProfileSection(lpUid, ulFlags, lppProfileObj);
}

See also

Concepts

About the Sample Wrapped PST Store Provider
Installing the Sample Wrapped PST Store Provider
Initializing a Wrapped PST Store Provider
Logging On to a Wrapped PST Store Provider
Shutting Down a Wrapped PST Store Provider


Shutting Down a Wrapped PST Store Provider

 Copy code hover
[image]

Shutting Down a Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

After you finish using a wrapped Personal Folders file (PST) store provider, you must properly shut down the wrapped PST store provider. For more information about using the wrapped PST store provider, see Using a Wrapped PST Store Provider.

To shut down a wrapped PST store provider, you must call the IMSProvider::Shutdown function. This functions closes down the wrapped PST store provider in an orderly fashion.

In this topic, the IMSProvider::Shutdown function is demonstrated by using a code example from the Sample Wrapped PST Store Provider. The sample implements a wrapped PST provider that is intended to be used in conjunction with the Replication API. For more information about downloading and installing the Sample Wrapped PST Store Provider, see Installing the Sample Wrapped PST Store Provider. For more information about the Replication API, see About the Replication API.

Shut Down Routine

The MAPI spooler calls the IMSProvider::Shutdown function just before it releases the wrapped PST store provider so that the wrapped PST store provider can shut down properly. The function terminates all session objects associated with the wrapped PST store provider.

CMSProvider::ShutDown() Example

Copy code Copy code
STDMETHODIMP CMSProvider::Shutdown(ULONG * pulFlags)
{
    HRESULT hRes = S_OK;
    Log(true,"CMSProvider::Shutdown\n");
    hRes =m_pPSTMS->Shutdown(pulFlags);
    Log(true,"CMSProvider::Shutdown returned: 0x%08X\n", hRes);
    return hRes ;
}

See also

Concepts

About the Sample Wrapped PST Store Provider
Installing the Sample Wrapped PST Store Provider
Initializing a Wrapped PST Store Provider
Logging On to a Wrapped PST Store Provider
Using a Wrapped PST Store Provider


Transport Provider Sample

 Copy code hover
[image]

Transport Provider Sample
Send feedback

Published: July 16, 2012

This sample uses files and directories to transmit and receive messages. It implements and registers a very simple preprocessor that appends a line of text to each outbound message. The sample illustrates how to split message content between Transport Neutral Encapsulation Format (TNEF) and text. It also supports all configuration options (property sheets, wizards, and programmatic configuration) and message options. It does not support the remote transport interfaces.

You can download this sample from Outlook Messaging API (MAPI) Code Samples.

Executable: | mrxp32.dll
Source code directory: | SampleTransportProvider\MRXP
Language: | C++
Platforms: | Visual Studio 2008 to compile for Windows Vista, Windows Server 2008, Windows XP SP2, and Windows Server 2003 SP1

Supported Features

This sample supports the following features:

  • Basic features such as sending, receiving, and polling for new messages.

  • Interactive and programmatic configuration.

  • The IMAPIStatus interface, except for property setting. For more information, see the IMAPIStatus : IMAPIProp interface.

  • Thread safety.

  • Event logging to a text file. The file is automatically limited to a specified size. All transport sessions use the same file.

Unsupported Features

This sample does not support asynchronous detection of incoming messages.

To install the Sample Transport Provider

  1. To download the Sample Transport Provider, see Downloading the Outlook MAPI Samples.

  2. Locate the folder where you saved the Outlook MAPI samples. Right-click the OutlookMAPISamples-<version number> zip folder and click Extract All.

  3. Click Browse, select the location where you want to save the sample, and click Extract.

  4. Run Visual Studio 2008.

  5. In Visual Studio 2008, click File, select Open, and then click Project/Solution.

  6. Browse to the location where you saved the sample, click mrxp32.vcproj, and then click Open.

  7. On the Build menu, click Configuration Manager.

  8. In the Configuration Manager dialog box, go to the mrxp32 row, and in the Configuration column select Release, and then click Close.

  9. On the Build menu, click Build Solution.

  10. In the Save File As dialog box, click Save.

  11. In the folder where you saved the sample, right-click the installation batch file and click Run as administrator.

  12. In the User Account Control dialog box, click Continue.

    Note Note

    install.bat copies the .dll to the default Microsoft Office installation folder, C:\Program Files\Microsoft Office\Office12\. If you have installed Office products in a different location, right-click install.bat and click Edit. The file opens in Notepad. Replace the default installation path with the installation path used on your computer.

To set up the Transport Provider in Outlook

  1. On the Tools menu of Outlook, click Account Settings.

  2. In the Account Settings dialog box, on the E-mail tab, click New.

  3. Under Choose E-mail Service click Other, select MRXP Sample Transport, and then click Next.

  4. In the MRXP Transport Configuration dialog box type a User Display Name.

  5. Under Path to Inbox (UNC Share) enter a folder path. This can also be a path to a local folder.

    Important note Important

    This path must exist.

  6. Click OK.

  7. In the Add E-mail Account dialog box click OK. Click Finish and then click Close.

  8. To start using the MRXP account, exit and restart Outlook.

To use the Transport Provider Sample to send a message in Outlook

  1. On the File menu, click New, and then click Mail Message.

  2. In the To box type the name of the recipient using the format [MRXP:<ADDRESS>]. The address is the UNC share or local folder path to the recipient's inbox.

    Note Note

    If there are colons or backslashes in the address, you must insert a backslash before each colon or backslash. For example, to send mail to [MRXP:C:\Mail\myDir] you must type [MRXP:C\:\\Mail\\myDir].

    Important note Important

    The recipient address must exist.

  3. Click Account and then click MRXP Sample Transport.

  4. Type your message and click Send. The message is sent using the MRXP transport provider.

To use the Transport Provider Sample to receive a message in Outlook

  1. On the File menu, click New, and then click Mail Message.

  2. Type your message.

  3. Click the Microsoft Office Button, click Save As, and then click Save As to save the file to the inbox folder you specified during setup.

  4. In the Save As dialog box, browse to the UNC share or local folder that you set as your inbox.

  5. In the Save as type drop down, click Outlook Message Format.

  6. Type a name for the file and click Save.

  7. The file is saved to the shared folder. The MRXP transport provider delivers the message to your Inbox in Outlook.


Creating Outlook Items by Using MAPI

 Copy code hover
[image]

Creating Outlook Items by Using MAPI
Send feedback

Published: July 16, 2012

The topics in this section demonstrate how to create Outlook items using MAPI.

  • How to: Install the Samples Used in This Section

    This topic shows how to install and view the samples discussed in this section.

  • How to: Create a Simple Mail Item

    This topic shows how to create a simple mail item that requests a read receipt.

  • How to: Create a Simple Recurrent Task Item

    This topic shows how to create a simple task item that occurs every week.

  • How to: Create a Complex Recurrent Appointment Item

    This topic shows how to create a weekly-recurrent appointment item, that also takes into consideration issues related to time zones.

  • How to: Read and Parse a Recurrence Pattern

    This topic shows how to read and parse a recurrence pattern for an appointment item.


How to: Install the Samples Used in This Section

 Copy code hover
[image]

How to: Install the Samples Used in This Section
See also Send feedback

Published: July 16, 2012

To install the MFCMAPI application and CreateOutlookItemsAddin project to view and run the sample code referenced by the topics in the Creating Outlook Items by Using MAPI section, follow these steps.

Installation Instructions

To download and install the examples used in the "Using MAPI to Create Outlook Items" section, follow these steps.

To download and install the MFCMAPI application and open CreateOutlookItemsAddin project

  1. Download the current version of the MFCMAPI executable to a folder on your system.

  2. Extract the MFCMapi.exe file in MFCMapi.exe.version.zip to an empty folder on your hard drive.

  3. Download the current version of the CreateOutlookItemsAddin project.

  4. Extract all the files in the CreateOutlookItemsAddin.zip file to the folder where you extracted the MFCMapi.exe file in Step 2.

  5. Copy MFCMapi.exe from the folder used in Step 2 to the build directory for the CreateOutlookItemsAddin project (\CreateOutlookItemsAddin\Debug).

  6. Open the CreateOutlookItemsAddin project (\CreateOutlookItemsAddin\CreateOutlookItemsAddin.vcproj) in Visual Studio to examine the source code. Refer to the topics from the Creating Outlook Items by Using MAPI section to determine which source files to open.

Running MFCMAPI and the CreateOutlookItemsAddin Project

The following steps assume that you have downloaded and installed the current version of the MFCMAPI executable and the CreateOutlookItemsAddin project as described in the preceding procedure. These steps will guide you to the Addins menu items that enable you to create Outlook items using the MFCMAPI application and the CreateOutlookItemsAddin project.

Note Note

The folder you select in step 8, and the command you select in step 9, depends on the item type discussed in one of the topics from the Creating Outlook Items by Using MAPI section.

To run the MFCMAPI application and Addins menu commands

  1. Start Mfcmapi.exe in the CreateOutlookItemsAddin\Debug folder that is created when you follow the installation instructions.

  2. Click OK to dismiss the MFCMAPI splash screen.

  3. On the Session menu, click Logon and Display Store Table.

  4. In the Choose Profile dialog box, select the correct profile, and then click OK.

  5. Double-click Mailbox - [User Name] in the store table list view.

  6. In the folder tree view, expand the root node. The name displayed for the root node varies depending on the type of profile selected. Typically this node is displayed as Root - Mailbox.

  7. In the folder tree view, expand the node that contains the information store. The name displayed for this node varies depending on the type of profile selected. Typically this node is displayed as IPM_SUBTREE or Top of Information Store.

  8. Double-click the folder for the item type to create. For example, to create an appointment, click the Appointments folder.

  9. On the Addins menu, click the appropriate command for the item to create.

Downloading and Viewing Code from the MFCMAPI Application

Some topics refer to source code from the MFCMAPI application itself. The following steps describe how to download the MFCMAPI source code and view it in Visual Studio.

To download and view the MFCMAPI application source code

  1. Download the source code for the current version of the MFCMAPI application to a folder on your system.

  2. Extract the files in MFCMAPI-changeset.zip to an empty folder on your hard drive.

  3. Open the MFCMapi project (\foldername\ MFCMapi.vcproj) in Visual Studio to examine the source code.

See also

Concepts

How to: Create a Simple Mail Item
How to: Create a Simple Recurrent Task Item
How to: Create a Complex Recurrent Appointment Item
How to: Read and Parse a Recurrence Pattern


How to: Create a Simple Mail Item

 Copy code hover
[image]

How to: Create a Simple Mail Item
See also Send feedback

Published: July 16, 2012

MAPI can be used to create and send a message that requests a read receipt. When a read receipt is requested, the messaging system generates and returns a read report to the sender when the recipient opens the message.

For information about how to download, view, and run the code from the MFCMAPI application and CreateOutlookItemsAddin project referenced in this topic, see How to: Install the Samples Used in This Section.

To create and send a message requesting a read receipt

  1. Create an outgoing message. For information about how to create an outgoing message, see Handling an Outgoing Message.

  2. Add the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property and set it to true.

  3. Add the PR_CONVERSATION_INDEX (PidTagConversationIndex) property.

  4. Add the PR_REPORT_TAG (PidTagReportTag) property.

  5. Send the message by calling the IMessage::SubmitMessage method.

The AddMail function in the Mails.cpp source file of the CreateOutlookItemsAddin project demonstrates these steps. The AddMail function takes parameters from the Add Mail dialog box that is displayed when you click the Add Mail command on the Addins menu in the MFCMAPI sample application. The DisplayAddMailDialog function in Mails.cpp displays the dialog box and passes the values from the dialog box to the AddMail function. The DisplayAddMailDialog function does not relate directly to creating a mail item using MAPI, so it is not listed here. The AddMail function is listed below.

Note that the lpFolder parameter passed to the AddMail method is a pointer to an IMAPIFolder interface that represents the folder where the new message will be created. Given the lpFolder parameter that represents an IMAPIFolder interface, the code calls the IMAPIFolder::CreateMessage method. The CreateMessage method returns a success code and a pointer to a pointer to an IMessage : IMAPIProp interface. Most of the AddMail function code handles the work of setting properties in preparation for calling the IMAPIProp::SetProps method. If the call to the SetProps method succeeds, a call to the IMAPIProp::SaveChanges method commits the changes to the store and creates a new mail item. Then, if requested, the IMessage::SubmitMessage method is called to send the message.

The AddMail function uses two helper functions to build values for the PR_CONVERSATION_INDEX and PR_REPORT_TAG properties: the BuildConversationIndex and AddReportTag functions. The BuildConversationIndex function, located in CreateOutlookItemsAddin.cpp, does the same work that the built-in MAPI ScCreateConversationIndex function does when a parent conversation index is not passed to it. The format of the conversation index buffer that these functions generate is documented in PidTagConversationIndex Canonical Property. The AddReportTag function, located in Mails.cpp, in turn calls the BuildReportTag function to build a structure for the PR_REPORT_TAG property. For information about the structure that the BuildReportTag function builds, see PidTagReportTag Canonical Property.

The following is the complete listing of the AddMail function.

C++ Copy code Copy code
HRESULT AddMail(LPMAPISESSION lpMAPISession,
            LPMAPIFOLDER lpFolder,
            LPWSTR szSubject, // PR_SUBJECT_W, PR_CONVERSATION_TOPIC
            LPWSTR szBody, // PR_BODY_W
            LPWSTR szRecipientName, // Recipient table
            BOOL bHighImportance, // PR_IMPORTANCE
            BOOL bReadReceipt, // PR_READ_RECEIPT_REQUESTED
            BOOL bSubmit,
            BOOL bDeleteAfterSubmit)
{
   if (!lpFolder) return MAPI_E_INVALID_PARAMETER;
   HRESULT hRes = S_OK;
   LPMESSAGE lpMessage = 0;

   // Create a message and set its properties
   hRes = lpFolder->CreateMessage(0,
      0,
      &lpMessage);
   if (SUCCEEDED(hRes))
   {
      // Because the properties to be set are known in advance,
      // most of the structures involved can be statically declared
      // to minimize expensive MAPIAllocateBuffer calls.
      SPropValue spvProps[NUM_PROPS] = {0};
      spvProps[p_PR_MESSAGE_CLASS_W].ulPropTag          = PR_MESSAGE_CLASS_W;
      spvProps[p_PR_ICON_INDEX].ulPropTag                 = PR_ICON_INDEX;
      spvProps[p_PR_SUBJECT_W].ulPropTag                = PR_SUBJECT_W;
      spvProps[p_PR_CONVERSATION_TOPIC_W].ulPropTag     = PR_CONVERSATION_TOPIC_W;
      spvProps[p_PR_BODY_W].ulPropTag                   = PR_BODY_W;
      spvProps[p_PR_IMPORTANCE].ulPropTag               = PR_IMPORTANCE;
      spvProps[p_PR_READ_RECEIPT_REQUESTED].ulPropTag   = PR_READ_RECEIPT_REQUESTED;
      spvProps[p_PR_MESSAGE_FLAGS].ulPropTag             = PR_MESSAGE_FLAGS;
      spvProps[p_PR_MSG_EDITOR_FORMAT].ulPropTag         = PR_MSG_EDITOR_FORMAT;
      spvProps[p_PR_MESSAGE_LOCALE_ID].ulPropTag         = PR_MESSAGE_LOCALE_ID;
      spvProps[p_PR_INETMAIL_OVERRIDE_FORMAT].ulPropTag = PR_INETMAIL_OVERRIDE_FORMAT;
      spvProps[p_PR_DELETE_AFTER_SUBMIT].ulPropTag      = PR_DELETE_AFTER_SUBMIT;
      spvProps[p_PR_INTERNET_CPID].ulPropTag            = PR_INTERNET_CPID;
      spvProps[p_PR_CONVERSATION_INDEX].ulPropTag         = PR_CONVERSATION_INDEX;
      spvProps[p_PR_MESSAGE_CLASS_W].Value.lpszW = L"IPM.Note";
      spvProps[p_PR_ICON_INDEX].Value.l = 0x103; // Unsent Mail
      spvProps[p_PR_SUBJECT_W].Value.lpszW = szSubject;
      spvProps[p_PR_CONVERSATION_TOPIC_W].Value.lpszW = szSubject;
      spvProps[p_PR_BODY_W].Value.lpszW = szBody;
      spvProps[p_PR_IMPORTANCE].Value.l = bHighImportance?IMPORTANCE_HIGH:IMPORTANCE_NORMAL;
      spvProps[p_PR_READ_RECEIPT_REQUESTED].Value.b = bReadReceipt?true:false;
      spvProps[p_PR_MESSAGE_FLAGS].Value.l = MSGFLAG_UNSENT;
      spvProps[p_PR_MSG_EDITOR_FORMAT].Value.l = EDITOR_FORMAT_PLAINTEXT;
      spvProps[p_PR_MESSAGE_LOCALE_ID].Value.l = 1033; // (en-us)
      spvProps[p_PR_INETMAIL_OVERRIDE_FORMAT].Value.l = NULL; // Mail system chooses default encoding scheme
      spvProps[p_PR_DELETE_AFTER_SUBMIT].Value.b = bDeleteAfterSubmit?true:false;
      spvProps[p_PR_INTERNET_CPID].Value.l = cpidASCII;

      hRes = BuildConversationIndex(
         &spvProps[p_PR_CONVERSATION_INDEX].Value.bin.cb,
         &spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb);

      if (SUCCEEDED(hRes))
      {
         hRes = lpMessage->SetProps(NUM_PROPS, spvProps, NULL);
         if (SUCCEEDED(hRes))
         {
            hRes = AddRecipient(lpMAPISession,
               lpMessage,
               MAPI_TO,
               szRecipientName);
            AddInLog(true,L"CallMenu: AddRecipient - returned hRes = 0x%08X\n",hRes);
            if (SUCCEEDED(hRes))
            {
               if (bReadReceipt)
               {
                  hRes = AddReportTag(lpMessage);
               }

               if (SUCCEEDED(hRes))
               {
                  hRes = lpMessage->SaveChanges(KEEP_OPEN_READWRITE);
                  if (SUCCEEDED(hRes) && bSubmit)
                  {
                     hRes = lpMessage->SubmitMessage(NULL);
                  }
               }
            }
         }
      }
      if (spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb)
         delete[] spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb;
   }
   if (lpMessage) lpMessage->Release();
   return hRes;
}

See also

Other resources

Using MAPI to Create Outlook 2007 Items


How to: Create a Simple Recurrent Task Item

 Copy code hover
[image]

How to: Create a Simple Recurrent Task Item
See also Send feedback

Published: July 16, 2012

MAPI can be used to create to create task items. This topic describes how to create a simple recurrent task item.

For information about how to download, view, and run the code from the MFCMAPI application and CreateOutlookItemsAddin project referenced in this topic, see How to: Install the Samples Used in This Section.

To create a task item

  1. Open a message store. For information on how to open a message store, see Opening a Message Store.

  2. Open the Tasks folder in the message store. For more information, see PR_IPM_TASK_ENTRYID (PidTagIpmTaskEntryId).

  3. Call the IMAPIFolder::CreateMessage method on the Tasks folder to create the new task item.

  4. Set the dispidTaskRecur (PidLidTaskRecurrence) property and other task-related properties required to create a recurrent task.

  5. Save the new task item.

The AddTask function in the Tasks.cpp source file of the CreateOutlookItemsAddin project demonstrates these steps. The AddTask function takes parameters from the Add Task dialog box that is displayed when you click Add Task on the Addins menu in the MFCMAPI sample application. The DisplayAddTaskDialog function in Tasks.cpp displays the dialog box and passes values from the dialog box to the AddTask function. The DisplayAddTaskDialog function does not relate directly to creating a task item using MAPI, so it is not listed here.

Important note Important

The code in the MFCMAPI application does not ensure that the Tasks folder has been selected when you click the Add Task command on the Addins menu. Creating task items in a folder other than the Tasks folder can cause undefined behavior. Make sure that you have selected the Tasks folder before using the Add Task command in the MFCMAPI application.

The AddTask function is listed below. Note that the lpFolder parameter passed to the AddTask function is a pointer to an IMAPIFolder interface that represents the folder where the new task is created. Given the lpFolder that represents an IMAPIFolder interface, the code calls the IMAPIFolder::CreateMessage method. The CreateMessage method returns a success code and a pointer to a pointer to an IMessage interface. Most of the AddTask function code handles the work of specifying properties in preparation for calling the IMAPIProp::SetProps method. If the call to the SetProps method succeeds, the IMAPIProp::SaveChanges method is called to commit the changes to the store and create a new task item.

The AddTask function sets a number of named properties. For information about named properties and how they are created, see Using MAPI to Create Outlook 2007 Items. Because the named properties used for task items occupy multiple property sets, care must be taken when building parameters to pass to the IMAPIProp::GetIDsFromNames method.

The AddTask function uses the BuildWeeklyTaskRecurrencePattern helper function to build a structure representing a task recurrence for setting the dispidTaskRecur property. For information on the task recurrence structure the BuildWeeklyTaskRecurrencePattern function builds, see PidLidTaskRecurrence Canonical Property and PidLidRecurrencePattern Canonical Property. Note that while a large variety of recurrence patterns are possible, the BuildWeeklyTaskRecurrencePattern function only builds a weekly recurrence pattern. It is also hard coded for a number of assumptions, such as the calendar type (Gregorian), the first day of the week (Sunday), and the number of modified or deleted instances (none). A more general purpose recurrence pattern creation function would need to accept these sorts of variables as parameters.

The following is the complete listing of the AddTask function.

C++ Copy code Copy code
HRESULT AddTask(LPMAPIFOLDER lpFolder,
            SYSTEMTIME* lpstStart, // PidLidCommonEnd, PidLidTaskDueDate, PidLidTaskRecurrence
            SYSTEMTIME* lpstEnd, // PidLidTaskRecurrence
            SYSTEMTIME* lpstFirstDOW, // PidLidTaskRecurrence
            DWORD dwPeriod, // PidLidTaskRecurrence
            DWORD dwOccurrenceCount, // PidLidTaskRecurrence
            DWORD dwPatternTypeSpecific, // PidLidTaskRecurrence
            LPWSTR szSubject, // PR_SUBJECT_W
            LPWSTR szBody) // PR_BODY_W
{
   if (!lpFolder) return MAPI_E_INVALID_PARAMETER;

   HRESULT hRes = S_OK;
   LPMESSAGE lpMessage = 0;
   // create a message and set its properties
   hRes = lpFolder->CreateMessage(0,
      0,
      &lpMessage);
   if (SUCCEEDED(hRes))
   {
      MAPINAMEID  rgnmid[ulTaskProps];
      LPMAPINAMEID rgpnmid[ulTaskProps];
      LPSPropTagArray lpNamedPropTags = NULL;

      ULONG i = 0;
      for (i = 0 ; i < ulTaskProps ; i++)
      {
         if (i < ulFirstTaskProp)
            rgnmid[i].lpguid = (LPGUID)&PSETID_Common;
         else
            rgnmid[i].lpguid = (LPGUID)&PSETID_Task;
         rgnmid[i].ulKind = MNID_ID;
         rgnmid[i].Kind.lID = aulTaskProps[i];
         rgpnmid[i] = &rgnmid[i];
      }

      hRes = lpFolder->GetIDsFromNames(
         ulTaskProps,
         (LPMAPINAMEID*) &rgpnmid,
         NULL,
         &lpNamedPropTags);
      if (SUCCEEDED(hRes) && lpNamedPropTags)
      {
      // Because the properties to be set are known in advance,
      // most of the structures involved can be statically declared
      // to minimize expensive MAPIAllocateBuffer calls.
         SPropValue spvProps[NUM_PROPS] = {0};
         spvProps[p_PidLidTaskMode].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskMode],PT_LONG);
         spvProps[p_PidLidCommonEnd].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCommonEnd],PT_SYSTIME);
         spvProps[p_PidLidTaskStatus].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskStatus],PT_LONG);
         spvProps[p_PidLidPercentComplete].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidPercentComplete],PT_DOUBLE);
         spvProps[p_PidLidTaskState].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskState],PT_LONG);
         spvProps[p_PidLidTaskRecurrence].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskRecurrence],PT_BINARY);
         spvProps[p_PidLidTaskDeadOccurrence].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskDeadOccurrence],PT_BOOLEAN);
         spvProps[p_PidLidTaskOwner].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskOwner],PT_UNICODE);
         spvProps[p_PidLidTaskFRecurring].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskFRecurring],PT_BOOLEAN);
         spvProps[p_PidLidTaskOwnership].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskOwnership],PT_LONG);
         spvProps[p_PidLidTaskAcceptanceState].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskAcceptanceState],PT_LONG);
         spvProps[p_PidLidTaskFFixOffline].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskFFixOffline],PT_BOOLEAN);
         spvProps[p_PidLidTaskDueDate].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskDueDate],PT_SYSTIME);
         spvProps[p_PidLidTaskComplete].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTaskComplete],PT_SYSTIME);

         spvProps[p_PR_MESSAGE_CLASS_W].ulPropTag   = PR_MESSAGE_CLASS_W;
         spvProps[p_PR_ICON_INDEX].ulPropTag        = PR_ICON_INDEX;
         spvProps[p_PR_SUBJECT_W].ulPropTag         = PR_SUBJECT_W;
         spvProps[p_PR_MESSAGE_FLAGS].ulPropTag     = PR_MESSAGE_FLAGS;
         spvProps[p_PR_BODY_W].ulPropTag            = PR_BODY_W;

         spvProps[p_PidLidTaskMode].Value.l = tdmtNothing;
         SYSTEMTIME stStartUTC = {0};
         TzSpecificLocalTimeToSystemTime(NULL,lpstStart,&stStartUTC);
         SystemTimeToFileTime(&stStartUTC,&spvProps[p_PidLidCommonEnd].Value.ft);

         spvProps[p_PidLidTaskStatus].Value.l = tsvNotStarted;
         spvProps[p_PidLidPercentComplete].Value.dbl = 0.0;
         spvProps[p_PidLidTaskState].Value.l = tdsOWNNEW;
         spvProps[p_PidLidTaskDeadOccurrence].Value.b = false;
         spvProps[p_PidLidTaskOwner].Value.lpszW = L"Unknown";
         spvProps[p_PidLidTaskFRecurring].Value.b = true;
         spvProps[p_PidLidTaskOwnership].Value.l = tovNew;
         spvProps[p_PidLidTaskAcceptanceState].Value.l = tdvNone;
         spvProps[p_PidLidTaskFFixOffline].Value.b = true;
         SystemTimeToFileTime(lpstStart,&spvProps[p_PidLidTaskDueDate].Value.ft);
         spvProps[p_PidLidTaskComplete].Value.b = false;

         spvProps[p_PR_MESSAGE_CLASS_W].Value.lpszW = L"IPM.Task";
         spvProps[p_PR_ICON_INDEX].Value.l = 0x501; // Unassigned Recurring Task
         spvProps[p_PR_SUBJECT_W].Value.lpszW = szSubject;
         spvProps[p_PR_MESSAGE_FLAGS].Value.l = MSGFLAG_READ;
         spvProps[p_PR_BODY_W].Value.lpszW = szBody;

         hRes = BuildWeeklyTaskRecurrencePattern(
            lpstStart,
            lpstEnd,
            lpstFirstDOW,
            dwPeriod,
            dwOccurrenceCount,
            dwPatternTypeSpecific,
            &spvProps[p_PidLidTaskRecurrence].Value.bin.cb,
            &spvProps[p_PidLidTaskRecurrence].Value.bin.lpb);
         if (SUCCEEDED(hRes))
         {
            hRes = lpMessage->SetProps(NUM_PROPS, spvProps, NULL);
            if (SUCCEEDED(hRes))
            {
               hRes = lpMessage->SaveChanges(FORCE_SAVE);
            }
         }
         if (spvProps[p_PidLidTaskRecurrence].Value.bin.lpb)
            delete[] spvProps[p_PidLidTaskRecurrence].Value.bin.lpb;
      }
      MAPIFreeBuffer(lpNamedPropTags);
   }
   if (lpMessage) lpMessage->Release();
   return hRes;
}

See also

Other resources

Using MAPI to Create Outlook 2007 Items


How to: Create a Complex Recurrent Appointment Item

 Copy code hover
[image]

How to: Create a Complex Recurrent Appointment Item
See also Send feedback

Published: July 16, 2012

MAPI can be used to create recurring appointment items.

For information about how to download, view, and run the code from the MFCMAPI application and CreateOutlookItemsAddin project referenced in this topic, see How to: Install the Samples Used in This Section.

To create an appointment item

  1. Open a message store. For information on how to open a message store, see Opening a Message Store.

  2. Open a Calendar folder in the message store. See PR_IPM_APPOINTMENT_ENTRYID (PidTagIpmAppointmentEntryId).

  3. Call the IMAPIFolder::CreateMessage method on the Calendar folder to create the new appointment item.

  4. Set the dispidApptRecur (PidLidAppointmentRecur) property and other properties required to create a recurrent appointment.

  5. Save the new appointment item.

The AddAppointment function in the Appointments.cpp source file of the CreateOutlookItemsAddin project demonstrates these steps. The AddAppointment function takes parameters from the Add Appointment dialog box that is displayed when you click Add Appointment on the Addins menu in the MFCMAPI sample application. The DisplayAddAppointmentDialog function in Appointments.cpp displays the dialog box and passes values from the dialog box to the AddAppointment function. The DisplayAddAppointmentDialog function does not relate directly to creating an appointment item using MAPI, so it is not listed here.

Important note Important

The code in the MFCMAPI application does not ensure that the Calendar folder has been selected when you click the Add Appointment command on the Addins menu. Creating an appointment item in a folder other than the Calendar folder can cause undefined behavior. Make sure that you have selected the Calendar folder before using the Add Appointment command in the MFCMAPI application.

The AddAppointment method is listed below. Note that the lpFolder parameter passed to the AddAppointment method is a pointer to an IMAPIFolder interface that represents the folder where the recurrent appointment is created. Given the lpFolder parameter that represents an IMAPIFolder interface, the code calls the IMAPIFolder::CreateMessage method. The CreateMessage method returns a success code and a pointer to a pointer to an IMessage interface. Most of the AddAppointment function code handles the work of specifying properties in preparation for calling the IMAPIProp::SetProps method. If the call to the SetProps method succeeds, the IMAPIProp::SaveChanges method is called to commit the changes to the store and create a new calendar item.

The AddAppointment function sets a number of named properties. For information about named properties and how they are created, see Using MAPI to Create Outlook 2007 Items. Because the named properties used for appointment items occupy multiple property sets, care must be taken when building parameters to pass to the IMAPIProp::GetIDsFromNames method.

The AddAppointment function uses several helper functions to build a structure for various appointment-related properties. The BuildTimeZoneStruct and BuildTimeZoneDefinition helper functions are used to build a structure that specifies the time-zone-related properties. The time-zone-related properties are dispidTimeZoneStruct (PidLidTimeZoneStruct), dispidTimeZoneDesc (PidLidTimeZoneDescription), dispidApptTZDefRecur (PidLidAppointmentTimeZoneDefinitionRecur), dispidApptTZDefStartDisplay (PidLidAppointmentTimeZoneDefinitionStartDisplay), and dispidApptTZDefEndDisplay (PidLidAppointmentTimeZoneDefinitionEndDisplay), and they are discussed in the corresponding sections of [MS-OXOCAL]. The BuildGlobalObjectID function is used to build a structure that specifies the LID_GLOBAL_OBJID (PidLidGlobalObjectId) and dispidCleanGlobalObjId (PidLidCleanGlobalObjectId) properties, which are discussed in the corresponding sections of [MS-OXOCAL]. The structure that specifies the dispidApptRecur property is built using the BuildWeeklyAppointmentRecurrencePattern function. For information about the structure built by the BuildWeeklyAppointmentRecurrencePattern function, see PidLidAppointmentRecur Canonical Property. Note that while a large variety of appointment recurrence patterns are possible, the BuildWeeklyAppointmentRecurrencePattern function only builds a weekly appointment recurrence pattern. It also uses several hard-coded values, such as the calendar type (Gregorian), the first day of the week (Sunday), and number of modified or deleted instances (none). A more general purpose appointment recurrence pattern creation function would need to accept these sorts of variables as parameters.

The following is the complete listing of the AddAppointment function.

C++ Copy code Copy code
HRESULT AddAppointment(LPMAPIFOLDER lpFolder,
               SYSTEMTIME* lpstStartDateLocal, // PidLidAppointmentRecur
               SYSTEMTIME* lpstEndDateLocal, // PidLidAppointmentRecur
               SYSTEMTIME* lpstStartFirstUST, // PidLidAppointmentStartWhole, PidLidCommonStart, PR_START_DATE
               SYSTEMTIME* lpstEndFirstUST, // PidLidAppointmentEndWhole, PidLidCommonEnd, PR_END_DATE
               SYSTEMTIME* lpszClipStartUST, // PidLidClipStart
               SYSTEMTIME* lpstClipEndUST, // PidLidClipEnd
               SYSTEMTIME* lpstFirstDOW, // PidLidAppointmentRecur
               DWORD dwStartOffsetLocal, // PidLidAppointmentRecur
               DWORD dwEndOffsetLocal, // PidLidAppointmentRecur
               DWORD dwPeriod, // PidLidAppointmentRecur
               DWORD dwOccurrenceCount, // PidLidAppointmentRecur
               DWORD dwPatternTypeSpecific, // PidLidAppointmentRecur
               ULONG ulDuration, // PidLidAppointmentDuration
               LPWSTR szSubject, // PR_SUBJECT_W
               LPWSTR szLocation, // PidLidLocation
               LPWSTR szPattern) // PidLidRecurrencePattern
{
   if (!lpFolder) return MAPI_E_INVALID_PARAMETER;
   HRESULT hRes = S_OK;
   LPMESSAGE lpMessage = 0;
   // create a message and set its properties
   hRes = lpFolder->CreateMessage(0,
      0,
      &lpMessage);
   if (SUCCEEDED(hRes))
   {
      MAPINAMEID  rgnmid[ulAppointmentProps];
      LPMAPINAMEID rgpnmid[ulAppointmentProps];
      LPSPropTagArray lpNamedPropTags = NULL;

      ULONG i = 0;
      for (i = 0 ; i < ulAppointmentProps ; i++)
      {
         if (i < ulFirstMeetingProp)
            rgnmid[i].lpguid = (LPGUID)&PSETID_Appointment;
         else if (i < ulFirstCommonProp)
            rgnmid[i].lpguid = (LPGUID)&PSETID_Meeting;
         else
            rgnmid[i].lpguid = (LPGUID)&PSETID_Common;
         rgnmid[i].ulKind = MNID_ID;
         rgnmid[i].Kind.lID = aulAppointmentProps[i];
         rgpnmid[i] = &rgnmid[i];
      }

      hRes = lpFolder->GetIDsFromNames(
         ulAppointmentProps,
         (LPMAPINAMEID*) &rgpnmid,
         NULL,
         &lpNamedPropTags);
      if (SUCCEEDED(hRes) && lpNamedPropTags)
      {
      // Because the properties to be set are known in advance,
      // most of the structures involved can be statically declared
      // to minimize expensive MAPIAllocateBuffer calls.
         SPropValue spvProps[NUM_PROPS] = {0};
         spvProps[p_PidLidAppointmentSequence].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentSequence],PT_LONG);
         spvProps[p_PidLidBusyStatus].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidBusyStatus],PT_LONG);
         spvProps[p_PidLidLocation].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidLocation],PT_UNICODE);
         spvProps[p_PidLidAppointmentStartWhole].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentStartWhole],PT_SYSTIME);
         spvProps[p_PidLidAppointmentEndWhole].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentEndWhole],PT_SYSTIME);
         spvProps[p_PidLidAppointmentDuration].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentDuration],PT_LONG);
         spvProps[p_PidLidAppointmentColor].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentColor],PT_LONG);
         spvProps[p_PidLidResponseStatus].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidResponseStatus],PT_LONG);
         spvProps[p_PidLidRecurring].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurring],PT_BOOLEAN);
         spvProps[p_PidLidClipStart].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidClipStart],PT_SYSTIME);
         spvProps[p_PidLidClipEnd].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidClipEnd],PT_SYSTIME);
         spvProps[p_PidLidTimeZoneStruct].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTimeZoneStruct],PT_BINARY);
         spvProps[p_PidLidTimeZoneDescription].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTimeZoneDescription],PT_UNICODE);
         spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].ulPropTag
           = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionRecur],
           PT_BINARY);
         spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionStartDisplay],
            PT_BINARY);
         spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionEndDisplay],
            PT_BINARY);
         spvProps[p_PidLidAppointmentRecur].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentRecur],PT_BINARY);
         spvProps[p_PidLidRecurrenceType].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurrenceType],PT_LONG);
         spvProps[p_PidLidRecurrencePattern].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurrencePattern],PT_UNICODE);
         spvProps[p_PidLidIsRecurring].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidIsRecurring],PT_BOOLEAN);
         spvProps[p_PidLidGlobalObjectId].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidGlobalObjectId],PT_BINARY);
         spvProps[p_PidLidCleanGlobalObjectId].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCleanGlobalObjectId],PT_BINARY);
         spvProps[p_PidLidCommonStart].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCommonStart],PT_SYSTIME);
         spvProps[p_PidLidCommonEnd].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCommonEnd],PT_SYSTIME);
         spvProps[p_PidLidSideEffects].ulPropTag
            = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidSideEffects],PT_LONG);

         spvProps[p_PR_SUBJECT_W].ulPropTag          = PR_SUBJECT_W;
         spvProps[p_PR_START_DATE].ulPropTag         = PR_START_DATE;
         spvProps[p_PR_END_DATE].ulPropTag           = PR_END_DATE;
         spvProps[p_PR_MESSAGE_CLASS_W].ulPropTag    = PR_MESSAGE_CLASS_W;
         spvProps[p_PR_ICON_INDEX].ulPropTag         = PR_ICON_INDEX;
         spvProps[p_PR_CONVERSATION_INDEX].ulPropTag   = PR_CONVERSATION_INDEX;
         spvProps[p_PR_MESSAGE_FLAGS].ulPropTag      = PR_MESSAGE_FLAGS;

         spvProps[p_PidLidAppointmentSequence].Value.l = 0;
         spvProps[p_PidLidBusyStatus].Value.l = olBusy;
         spvProps[p_PidLidLocation].Value.lpszW = szLocation;
         SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PidLidAppointmentStartWhole].Value.ft);
         SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PidLidAppointmentEndWhole].Value.ft);
         spvProps[p_PidLidAppointmentDuration].Value.l = ulDuration;
         spvProps[p_PidLidAppointmentColor].Value.l = 0; // No color
         spvProps[p_PidLidResponseStatus].Value.l = respNone;
         spvProps[p_PidLidRecurring].Value.b = true;
         SystemTimeToFileTime(lpszClipStartUST,&spvProps[p_PidLidClipStart].Value.ft);
         SystemTimeToFileTime(lpstClipEndUST,&spvProps[p_PidLidClipEnd].Value.ft);

         SYSTEMTIME stStandard = {0};
         stStandard.wMonth = 0xB;
         stStandard.wDay = 0x1;
         stStandard.wHour = 0x2;
         SYSTEMTIME stDaylight = {0};
         stDaylight.wMonth = 0x3;
         stDaylight.wDay = 0x2;
         stDaylight.wHour = 0x2;
         hRes = BuildTimeZoneStruct(
            300,
            0,
            (DWORD)-60,
            &stStandard,
            &stDaylight,
            &spvProps[p_PidLidTimeZoneStruct].Value.bin.cb,
            &spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb);
         spvProps[p_PidLidTimeZoneDescription].Value.lpszW = L"(GMT-05:00) Eastern Time (US & Canada)";
         SYSTEMTIME stRule1Standard = {0};
         stRule1Standard.wMonth = 0xA;
         stRule1Standard.wDay = 0x5;
         stRule1Standard.wHour = 0x2;
         SYSTEMTIME stRule1Daylight = {0};
         stRule1Daylight.wMonth = 0x4;
         stRule1Daylight.wDay = 0x1;
         stRule1Daylight.wHour = 0x2;
         if (SUCCEEDED(hRes)) hRes = BuildTimeZoneDefinition(
            L"Eastern Standard Time",
            0, // TZRule Flags
            2006, // wYear
            300, // lbias
            0, // lStandardBias,
            (DWORD)-60, // lDaylightBias,
            &stRule1Standard, // stStandardDate
            &stRule1Daylight, // stDaylightDate
            TZRULE_FLAG_EFFECTIVE_TZREG, // TZRule Flags
            2007, // wYear
            300, // lbias
            0, // lStandardBias,
            (DWORD)-60, // lDaylightBias,
            &stStandard, // stStandardDate
            &stDaylight, // stDaylightDate
            &spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb,
            &spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb);
         spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].Value.bin.cb
            = spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb;
         spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].Value.bin.lpb
            = spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
         spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].Value.bin.cb
            = spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb;
         spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].Value.bin.lpb
            = spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
         if (SUCCEEDED(hRes)) hRes = BuildWeeklyAppointmentRecurrencePattern(
            lpstStartDateLocal,
            lpstEndDateLocal,
            lpstFirstDOW,
            dwStartOffsetLocal,
            dwEndOffsetLocal,
            dwPeriod,
            dwOccurrenceCount,
            dwPatternTypeSpecific,
            &spvProps[p_PidLidAppointmentRecur].Value.bin.cb,
            &spvProps[p_PidLidAppointmentRecur].Value.bin.lpb);
         spvProps[p_PidLidRecurrenceType].Value.l = rectypeWeekly;
         spvProps[p_PidLidRecurrencePattern].Value.lpszW = szPattern;
         spvProps[p_PidLidIsRecurring].Value.b = true;
         if (SUCCEEDED(hRes)) hRes = BuildGlobalObjectId(
            &spvProps[p_PidLidGlobalObjectId].Value.bin.cb,
            &spvProps[p_PidLidGlobalObjectId].Value.bin.lpb);
         spvProps[p_PidLidCleanGlobalObjectId].Value.bin.cb  = spvProps[p_PidLidGlobalObjectId].Value.bin.cb;
         spvProps[p_PidLidCleanGlobalObjectId].Value.bin.lpb = spvProps[p_PidLidGlobalObjectId].Value.bin.lpb;
         SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PidLidCommonStart].Value.ft);
         SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PidLidCommonEnd].Value.ft);
         spvProps[p_PidLidSideEffects].Value.l
            = seOpenToDelete | seOpenToCopy | seOpenToMove | seCoerceToInbox | seOpenForCtxMenu;

         spvProps[p_PR_SUBJECT_W].Value.lpszW = szSubject;
         SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PR_START_DATE].Value.ft);
         SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PR_END_DATE].Value.ft);
         spvProps[p_PR_MESSAGE_CLASS_W].Value.lpszW = L"IPM.Appointment";
         spvProps[p_PR_ICON_INDEX].Value.l = 0x00000401; // Recurring Appointment
         if (SUCCEEDED(hRes)) hRes = BuildConversationIndex(
            &spvProps[p_PR_CONVERSATION_INDEX].Value.bin.cb,
            &spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb);
         spvProps[p_PR_MESSAGE_FLAGS].Value.l = MSGFLAG_READ;

         if (SUCCEEDED(hRes)) hRes = lpMessage->SetProps(NUM_PROPS, spvProps, NULL);
         if (SUCCEEDED(hRes))
         {
            hRes = lpMessage->SaveChanges(FORCE_SAVE);
         }
         if (spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb)
            delete[] spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb;
         if (spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb)
            delete[] spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
         // Do not delete p_PidLidAppointmentTimeZoneDefinitionStartDisplay,
         // it was borrowed from p_PidLidAppointmentTimeZoneDefinitionStartDisplay
         // Do not delete p_PidLidAppointmentTimeZoneDefinitionEndDisplay,
         // it was borrowed from p_PidLidAppointmentTimeZoneDefinitionStartDisplay
         if (spvProps[p_PidLidAppointmentRecur].Value.bin.lpb)
            delete[] spvProps[p_PidLidAppointmentRecur].Value.bin.lpb;
         if (spvProps[p_PidLidGlobalObjectId].Value.bin.lpb)
            delete[] spvProps[p_PidLidGlobalObjectId].Value.bin.lpb;
         // Do not delete p_PidLidCleanGlobalObjectId, it was borrowed from p_PidLidGlobalObjectId
         if (spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb)
            delete[] spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb;
      }
      MAPIFreeBuffer(lpNamedPropTags);
   }
   if (lpMessage) lpMessage->Release();
   return hRes;
}

See also

Other resources

Using MAPI to Create Outlook 2007 Items


How to: Read and Parse a Recurrence Pattern

 Copy code hover
[image]

How to: Read and Parse a Recurrence Pattern
See also Send feedback

Published: July 16, 2012

MAPI can be used to read and parse a recurrence pattern for an appointment.

For information about how to download, view, and run the code from the MFCMAPI application project referenced in this topic, see How to: Install the Samples Used in This Section.

To parse a recurrence blob

  1. Open an appointment item. For information about opening a message, see Opening a Message.

  2. Retrieve the named property dispidApptRecur (PidLidAppointmentRecur Canonical Property). For information about retrieving named properties, see MAPI Named Properties.

  3. Follow the guidance in [MS-OXOCAL] to read the appointment recurrence pattern structure.

The MFCMAPI reference application demonstrates the last step with the BinToAppointmentRecurrencePatternStruct function in the InterpretProp2.cpp source file of the MFCMapi project. The BinToAppointmentRecurrencePatternStruct function takes a pointer to a buffer in memory as a parameter. The MFCMAPI application obtains this buffer by first mapping the dispidApptRecur named property to a property tag, then by requesting the property's value using the IMAPIProp::GetProps method. If the property is too large to retrieve using the GetProps method, MFCMAPI opens a stream interface to retrieve the property using the IMAPIProp::OpenProperty method. The MFCMAPI application then reads the data out of the stream to build the buffer.

For information about the format of the buffer, see the PidLidAppointmentRecur Canonical Property. The bulk of the data in the buffer consists of fields of a fixed number of bytes, which must be read one after another. Some fields are present only if other fields contain certain values, and the size of some fields may depend on the value of other fields. Parsing the buffer to read the various fields involves a lot of bookkeeping. MFCMAPI uses an internal helper class named CBinaryParser to encapsulate this bookkeeping. For example, the CBinaryParser::GetDWORD function checks whether enough bytes remain in the buffer to read a DWORD, and then reads the value and updates the pointers.

After the buffer has been parsed into a structure, the MFCMAPI application uses the AppointmentRecurrencePatternStructToString function to convert the structure to a string to display to the user. This is not the same string Outlook would display, but is instead a raw view of the data upon which Outlook builds its logic.

It is possible to encounter a buffer which contains either corrupted data or more data than is needed to encode a recurrence pattern. To help identify those scenarios, the MFCMAPI application keeps track of how much data has been successfully parsed and how much remains in the buffer. If data remains in the buffer after parsing has completed, MFCMAPI includes this "junk data" in the structure so it can be examined.

The following is the complete listing of the BinToAppointmentRecurrencePatternStruct function.

C++ Copy code Copy code
AppointmentRecurrencePatternStruct* BinToAppointmentRecurrencePatternStruct(ULONG cbBin, LPBYTE lpBin)
{
   if (!lpBin) return NULL;

   AppointmentRecurrencePatternStruct arpPattern = {0};
   CBinaryParser Parser(cbBin,lpBin);

   size_t cbBinRead = 0;
   arpPattern.RecurrencePattern = BinToRecurrencePatternStruct(cbBin,lpBin,&cbBinRead);
   Parser.Advance(cbBinRead);
   Parser.GetDWORD(&arpPattern.ReaderVersion2);
   Parser.GetDWORD(&arpPattern.WriterVersion2);
   Parser.GetDWORD(&arpPattern.StartTimeOffset);
   Parser.GetDWORD(&arpPattern.EndTimeOffset);
   Parser.GetWORD(&arpPattern.ExceptionCount);

   if (arpPattern.ExceptionCount &&
      arpPattern.ExceptionCount == arpPattern.RecurrencePattern->ModifiedInstanceCount &&
      arpPattern.ExceptionCount < _MaxExceptions)
   {
      arpPattern.ExceptionInfo = new ExceptionInfoStruct[arpPattern.ExceptionCount];
      if (arpPattern.ExceptionInfo)
      {
         memset(arpPattern.ExceptionInfo,0,sizeof(ExceptionInfoStruct) * arpPattern.ExceptionCount);
         WORD i = 0;
         for (i = 0 ; i < arpPattern.ExceptionCount ; i++)
         {
            Parser.GetDWORD(&arpPattern.ExceptionInfo[i].StartDateTime);
            Parser.GetDWORD(&arpPattern.ExceptionInfo[i].EndDateTime);
            Parser.GetDWORD(&arpPattern.ExceptionInfo[i].OriginalStartDate);
            Parser.GetWORD(&arpPattern.ExceptionInfo[i].OverrideFlags);
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_SUBJECT)
            {
               Parser.GetWORD(&arpPattern.ExceptionInfo[i].SubjectLength);
               Parser.GetWORD(&arpPattern.ExceptionInfo[i].SubjectLength2);
               if (arpPattern.ExceptionInfo[i].SubjectLength2 && arpPattern.ExceptionInfo[i].SubjectLength2 + 1
                  == arpPattern.ExceptionInfo[i].SubjectLength)
               {
                  Parser.GetStringA(arpPattern.ExceptionInfo[i].SubjectLength2,&arpPattern.ExceptionInfo[i].Subject);
               }
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_MEETINGTYPE)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].MeetingType);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_REMINDERDELTA)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].ReminderDelta);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_REMINDER)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].ReminderSet);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_LOCATION)
            {
               Parser.GetWORD(&arpPattern.ExceptionInfo[i].LocationLength);
               Parser.GetWORD(&arpPattern.ExceptionInfo[i].LocationLength2);
               if (arpPattern.ExceptionInfo[i].LocationLength2 && arpPattern.ExceptionInfo[i].LocationLength2
                  + 1 == arpPattern.ExceptionInfo[i].LocationLength)
               {
                  Parser.GetStringA(arpPattern.ExceptionInfo[i].LocationLength2,&arpPattern.ExceptionInfo[i].Location);
               }
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_BUSYSTATUS)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].BusyStatus);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_ATTACHMENT)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].Attachment);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_SUBTYPE)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].SubType);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_APPTCOLOR)
            {
               Parser.GetDWORD(&arpPattern.ExceptionInfo[i].AppointmentColor);
            }
         }
      }
   }
   Parser.GetDWORD(&arpPattern.ReservedBlock1Size);
   if (arpPattern.ReservedBlock1Size && arpPattern.ReservedBlock1Size < _MaxReservedBlock)
   {
      Parser.GetBYTES(arpPattern.ReservedBlock1Size,&arpPattern.ReservedBlock1);
   }
   if (arpPattern.ExceptionCount &&
      arpPattern.ExceptionCount == arpPattern.RecurrencePattern->ModifiedInstanceCount &&
      arpPattern.ExceptionCount < _MaxExceptions &&
      arpPattern.ExceptionInfo)
   {
      arpPattern.ExtendedException = new ExtendedExceptionStruct[arpPattern.ExceptionCount];
      if (arpPattern.ExtendedException)
      {
         memset(arpPattern.ExtendedException,0,sizeof(ExtendedExceptionStruct) * arpPattern.ExceptionCount);
         WORD i = 0;
         for (i = 0 ; i < arpPattern.ExceptionCount ; i++)
         {
            if (arpPattern.WriterVersion2 >= 0x0003009)
            {
               Parser.GetDWORD(&arpPattern.ExtendedException[i].ChangeHighlight.ChangeHighlightSize);
               Parser.GetDWORD(&arpPattern.ExtendedException[i].ChangeHighlight.ChangeHighlightValue);
               if (arpPattern.ExtendedException[i].ChangeHighlight.ChangeHighlightSize > sizeof(DWORD))
               {
                  Parser.GetBYTES(arpPattern.ExtendedException[i].ChangeHighlight.ChangeHighlightSize
                     - sizeof(DWORD),&arpPattern.ExtendedException[i].ChangeHighlight.Reserved);
               }
            }
            Parser.GetDWORD(&arpPattern.ExtendedException[i].ReservedBlockEE1Size);
            if (arpPattern.ExtendedException[i].ReservedBlockEE1Size &&
                arpPattern.ExtendedException[i].ReservedBlockEE1Size < _MaxReservedBlock)
            {
               Parser.GetBYTES(arpPattern.ExtendedException[i].ReservedBlockEE1Size,&arpPattern.ExtendedException[i].ReservedBlockEE1);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_SUBJECT ||
               arpPattern.ExceptionInfo[i].OverrideFlags & ARO_LOCATION)
            {
               Parser.GetDWORD(&arpPattern.ExtendedException[i].StartDateTime);
               Parser.GetDWORD(&arpPattern.ExtendedException[i].EndDateTime);
               Parser.GetDWORD(&arpPattern.ExtendedException[i].OriginalStartDate);
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_SUBJECT)
            {
               Parser.GetWORD(&arpPattern.ExtendedException[i].WideCharSubjectLength);
               if (arpPattern.ExtendedException[i].WideCharSubjectLength)
               {
                  Parser.GetStringW(arpPattern.ExtendedException[i].WideCharSubjectLength,&arpPattern.ExtendedException[i].WideCharSubject);
               }
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_LOCATION)
            {
               Parser.GetWORD(&arpPattern.ExtendedException[i].WideCharLocationLength);
               if (arpPattern.ExtendedException[i].WideCharLocationLength)
               {
                  Parser.GetStringW(arpPattern.ExtendedException[i].WideCharLocationLength,&arpPattern.ExtendedException[i].WideCharLocation);
               }
            }
            if (arpPattern.ExceptionInfo[i].OverrideFlags & ARO_SUBJECT ||
               arpPattern.ExceptionInfo[i].OverrideFlags & ARO_LOCATION)
            {
               Parser.GetDWORD(&arpPattern.ExtendedException[i].ReservedBlockEE2Size);
               if (arpPattern.ExtendedException[i].ReservedBlockEE2Size && arpPattern.ExtendedException[i].ReservedBlockEE2Size < _MaxReservedBlock)
               {
                  Parser.GetBYTES(arpPattern.ExtendedException[i].ReservedBlockEE2Size,&arpPattern.ExtendedException[i].ReservedBlockEE2);
               }
            }
         }
      }
   }
   Parser.GetDWORD(&arpPattern.ReservedBlock2Size);
   if (arpPattern.ReservedBlock2Size && arpPattern.ReservedBlock2Size < _MaxReservedBlock)
   {
      Parser.GetBYTES(arpPattern.ReservedBlock2Size,&arpPattern.ReservedBlock2);
   }

   // Junk data remains.
   if (Parser.RemainingBytes() > 0)
   {
      arpPattern.JunkDataSize = Parser.RemainingBytes();
      Parser.GetBYTES(arpPattern.JunkDataSize,&arpPattern.JunkData);
   }

   AppointmentRecurrencePatternStruct* parpPattern = new AppointmentRecurrencePatternStruct;
   if (parpPattern)
   {
      *parpPattern = arpPattern;
   }

   return parpPattern;
}

See also

Other resources

Using MAPI to Create Outlook 2007 Items


MAPI Concepts

 Copy code hover
[image]

MAPI Concepts
Send feedback

Published: July 16, 2012

This section provides a guide to understanding and programming with MAPI.

In this section

MAPI Features and Architecture

Contains information about general MAPI design and concepts.

MAPI Application Development

Provides information about developing client applications and service providers by using MAPI.

MAPI Programming Elements

Contains conceptual overviews of the programming elements in the MAPI Reference.

MAPI Service Providers

Provides basic information about MAPI service providers.

Related sections

Getting Started with the Outlook 2013 MAPI Reference

MAPI Samples

MAPI Reference


MAPI Features and Architecture

 Copy code hover
[image]

MAPI Features and Architecture
See also Send feedback

Published: July 16, 2012

Messaging API (MAPI) is composed of a set of common application programming interfaces and a dynamic-link library (DLL) component. The interfaces are used to create and access diverse messaging applications and messaging systems, offering a uniform environment for development and use, and providing true independence for both. The DLL contains the MAPI subsystem, which manages the interaction between front-end messaging applications and back-end messaging systems and provides a common user interface for frequent tasks. The MAPI subsystem acts as a central clearinghouse to unify the various messaging systems and shield clients from their differences.

See also

Other resources

MAPI Concepts


MAPI Feature Overview

 Copy code hover
[image]

MAPI Feature Overview
See also Send feedback

Published: July 16, 2012

MAPI has several key features that enable it to provide a consistent way for developers to work with and use different messaging systems in a seamless fashion. These features include a comprehensive and open programming interface, and support for industry standards.

Because MAPI is an open programming interface, it provides services in a generic way, enabling users to add any necessary customization now and in the future. The MAPI programming interface fulfills the requirements of client applications with diverse messaging needs, such as a word processing application that requires only the ability to send documents, or a workgroup application that requires the ability to share and store different types of data. In fact, any application that needs to either exchange or store information in a particular format can benefit from the MAPI programming interface. Any service provider can use the interface to expose the unique features of its messaging system, selecting those features that provide the most benefit to application users.

MAPI provides separation between the programming interface used by the front-end messaging client applications and the programming interface used by the back-end service providers. Separating the client interface from the service provider enables a single application to use multiple messaging systems and multiple applications to use a single service provider. Every component works with a common Microsoft Windows-based user interface. This is a great benefit to users. Users can select from a variety of systems, depending on their needs at any one time, and can work consistently with each selected system, thereby providing true independence from specific messaging systems.

For example, a single messaging client application can receive messages from a fax, voice mail, and an RSS feed. Messages from all of these systems can be placed in a single location, or universal Inbox, on arrival. Having a single application handle all of these systems lessens the cost of development, user training, and system administration.

Separating the client interface from the provider interface removes any programming dependencies placed on the application by the messaging system and vice versa. Developers of client applications and service providers write code to a standard set of MAPI features, rather than a diverse set of application-specific or messaging system-specific features. Developers focus only on their component, whether it is a client or service provider, and MAPI handles the rest, reducing development time and costs.

The MAPI programming interface provides a comprehensive set of features. MAPI is aimed at the powerful new market of workgroup applications — applications that communicate with such different messaging systems as fax, DEC All-In-1, voice mail, and public communications services such as AT&T Easylink Services, CompuServe, and MCI MAIL. The MAPI interface enables service providers to be made available for all of these systems.

MAPI-compliant objects are similar in form to Component Object Model (COM) objects. COM objects implement a set of methods that belong to one or more interfaces, or collections of related functions that define how objects behave and operate in COM. Users access COM objects only through pointers to these interfaces.

MAPI provides cross-platform support through such industry standards as SMTP and X.400. You can run MAPI applications on Windows 7, Windows Vista, Windows Server 2008, Windows Server 2003, and Windows XP.

See also

Concepts

MAPI Features and Architecture


MAPI Architecture Overview

 Copy code hover
[image]

MAPI Architecture Overview
See also Send feedback

Published: July 16, 2012

MAPI defines a modular architecture, as shown in the following illustration.

Outlook 2010 architecture

The MAPI application is known as a client application because it is a client of the MAPI subsystem. Messaging-based applications employ messaging as a central part of their processing and offer extensive messaging features, such as the exchange of information of various types in various formats and the ability to save and organize the information locally. E-mail, scheduling, and work flow applications are examples of messaging-based applications.

The MAPI subsystem is made up of a common user interface and the programming interfaces. The common user interface is a set of dialog boxes that gives client applications a consistent look and users a consistent way to work.

MAPI has programming interfaces that are used by the MAPI subsystem, by client software developers, and by service provider developers. The MAPI programming interface is the main object-based programming interface. The MAPI programming interface is similar to the OLE Component Object Model and is used by the MAPI subsystem and messaging-based client applications written in C or C++.

As a client software developer, you make MAPI calls directly through the MAPI programming interface. You can implement messaging with a single MAPI client interface or a combination of interfaces. A single application can make calls to methods or functions belonging to any of the interfaces.

See also

Concepts

MAPI Features and Architecture


MAPI Client Application Overview

 Copy code hover
[image]

MAPI Client Application Overview
See also Send feedback

Published: July 16, 2012

A MAPI client application is any application that uses the MAPI programming interface. Client applications implement messaging tasks as either their primary or secondary focus. Messaging client applications, such as applications that send and receive e-mail, implement messaging as their primary focus. For non-messaging client applications, such as inventory or configuration applications, messaging is a secondary feature.

Messaging activities can include, for example, a word processing application that has a Send command on its File menu to enable documents to be sent, Microsoft Office Outlook e-mail, work flow automation programs, and bulletin board services.

Client applications can either include the user to create an interactive environment or operate without a user in an automated environment. Although MAPI supplies a set of common dialog boxes with its standard user interface, client applications are not required to present a user interface. In fact, all processing can be handled in the application, if you want. An example of an automated client application would be an inventory management application that is programmed to route items of a particular type to standard recipients on a regular basis.

See also

Concepts

MAPI Features and Architecture


MAPI Spooler Overview

 Copy code hover
[image]

MAPI Spooler Overview
See also Send feedback

Published: July 16, 2012

MAPI spooler is a function of the Microsoft Office Outlook process that is responsible for sending messages to and receiving messages from a messaging system. MAPI spooler plays a vital role in message receipt and delivery. When a messaging system is unavailable, MAPI spooler stores the messages and automatically forwards them at a later time. This ability to hold on to or send data when necessary is known as store and forward, a critical feature in environments where remote connections are common and network traffic is high. MAPI spooler runs as a background thread within Outlook.

MAPI spooler has additional responsibilities related to message distribution. These extra duties include the following:

  • Keeping track of the recipient types that are handled by specific transport providers.

  • Informing a client application when a new message has been delivered.

  • Invoking message preprocessing and postprocessing.

  • Generating reports that indicate that message delivery has occurred.

  • Maintaining status on processed recipients.

The following illustration shows at a high level how a message flows from a client to the messaging system.

Outgoing message flow

Outgoing message flow

The user of a client application sends a message to one or more recipients. The message store provider initiates the sending process, formatting the message with additional information needed for transmission.

MAPI spooler receives the message to process if any of the following conditions occur:

  • The message store provider is not tightly coupled with a transport provider.

  • The message requires preprocessing.

  • The message store and transport provider are tightly coupled, but they cannot handle all the recipients to whom the message is addressed.

If MAPI spooler receives the message, it performs any required preprocessing and delivers the message to the appropriate transport provider. The transport provider gives the message to its messaging system, which sends it to its intended recipient.

With incoming messages, the flow is reversed. The transport provider receives a message from its messaging system and notifies MAPI spooler. Spooler performs any necessary postprocessing and informs the message store provider that a new message has arrived. This notification causes the client to refresh its message display, enabling the user to read the new message.

See also

Concepts

MAPI Features and Architecture


MAPI Service Provider Overview

 Copy code hover
[image]

MAPI Service Provider Overview
See also Send feedback

Published: July 16, 2012

Between the MAPI subsystem and the messaging systems are the various service providers. Service providers are like drivers that connect MAPI client applications to an underlying messaging system. There are three types of providers: message store providers, address book or directory providers, and message transport providers. MAPI supports each type of service independently, enabling a vendor to offer one or more custom service providers. For example, a vendor might want to create an address book provider that uses a corporate telephone book directory of employees or to create a message store provider that uses an existing database.

Service providers are typically written for specific messaging systems by software developers who have specialized knowledge or experience with a particular system. For example, the Microsoft Outlook 2013 and Microsoft Outlook 2010 Mobile Services use an address book provider to expose a mobile address book in Outlook.

MAPI presents client applications with a unified view of address book and transport provider information. This integrated approach prevents the client application from having to map data to the appropriate provider. It also prevents the user from having to negotiate among multiple address book and transport provider addressing schemes. Message store provider information, however, is not unified, and clients that use multiple message store providers are responsible for handling them individually.

The service providers work with MAPI to create and send messages in the following way: messages are created by using a form that is appropriate for the specific type, or class, of message. Many messages are made with the standard note form that comes with the MAPI subsystem, either by the user of a client application or programmatically without user interaction. The completed message is addressed to one or more recipients — a user or group of users designated to receive the message. A recipient might or might not have an entry in a directory that one of the installed address book providers owns. Recipients that are not associated with an installed address book provider are called custom recipients or one-off addresses. A one-off address can be temporary, lasting only until the message is submitted.

When the client application sends the message, the message store provider checks that each recipient has a unique and valid address and that the message has all of the information necessary for transmission. If there is a question about a recipient (for example, when there are multiple recipients with the same name), an address book provider takes care of resolving the ambiguity. The message is then placed in the outbound queue.

See also

Concepts

MAPI Features and Architecture


MAPI Address Book Provider Overview

 Copy code hover
[image]

MAPI Address Book Provider Overview
See also Send feedback

Published: July 16, 2012

Address book providers handle access to directory information. Directory information consists of data for two types of message recipients: individual messaging users and groups of messaging users who are commonly addressed together in distribution lists. Depending on the type of recipient and the address book provider, there is a wide range of information that can be made available. For example, all address book providers store a recipient's name, address, and address type.

Each address book provider organizes this data by using one or more containers. The number and structure of the containers depends on the address book provider's implementation. For example, one address book provider might use a single container to hold all of the information, another might use one top-level container that holds subcontainers, and a third might use several top-level containers, each holding subcontainers. An address book container hierarchy can be quite deep; there is no limit to the number of subcontainers that can be used.

The following illustration shows a typical MAPI address book organization.

Address book organization

Address book organization

MAPI integrates all the information supplied by the installed address book providers into a single address book, presenting a unified view to the client application. The integrated list shows the top-level containers displayed by each of the installed address book providers. Most address book providers expose only a few containers (typically one to three) at the top level for inclusion in the top level of the MAPI integrated address book. For example, an address book provider might make available "All Users" and "Local Users" as two containers at the top level.

The users of client applications can view the contents of address book containers and, in some cases, modify the contents. Address book containers can be created with different access levels, depending on the address book provider.

See also

Concepts

MAPI Features and Architecture


MAPI Message Store Provider Overview

 Copy code hover
[image]

MAPI Message Store Provider Overview
See also Send feedback

Published: July 16, 2012

Message store providers handle the storage and retrieval of messages and other information for the users of client applications. The message information is organized by using a hierarchical system known as a message store. The message store is implemented in multiple levels, with containers called folders holding messages of different types. There is no limit to the number of levels in a message store; folders can contain many subfolders.

The following illustration shows the hierarchical message store architecture.

Message store architecture

Message store architecture

The figure shows two folders, one with a subfolder. Client application users can access a summary view of the messages contained in each folder or view them individually with a form. Whether the client displays a standard form that MAPI supplies or a custom form that a form developer supplies depends on the type, or class, of the message. The first folder contains note messages and uses the MAPI standard note form. The second folder contains inventory request messages and uses a custom inventory form. The information on both forms represents the properties of the message.

You can use message store data in a variety of ways. In addition to using data for traditional electronic mail, you can use folders as a forum for public discussion, as a repository for reference documents, or as a container for voice mail, calendar, contacts, or tasks, for example. A single message store can hold many types of information. Multiple clients can install the same message store. This makes the sharing of data easy and fast.

Message store folders enable you to sort and filter messages and to customize the message display in a user interface. Links to filtered messages are held in special folders called search-results folders. The user of a client application enters filtering criteria, which MAPI refers to as a restriction, and the criteria is applied to the messages stored in one or more folders. For example, a user might want to view only those messages that deal with a particular subject and have arrival dates that are more recent than last week. References to the messages that match the criteria are listed in the search folder, and the real messages remain in their regular folders.

Messages are the units of data that are transferred from one user or application to another user or application. Every message contains some message text, with simple or complex formatting, and message envelope information that is used for transmission. Some messages include one or more attachments, or additional data related to and transported with a message in the form of a file, another message, or an OLE object.

Depending on the message store provider, a user can save a new message currently being written in addition to messages that have been sent or received. Messages can be copied or moved from one folder to another with each copy becoming a separate message that can be copied, deleted, or modified individually. Another feature that some message store providers enable is the ability to change a message after it has been received and to store it back in its folder. A user might take advantage of this feature for rotating a fax message that arrived upside down. The user can store the correct view in the folder for later viewing.

See also

Concepts

MAPI Features and Architecture


MAPI Transport Provider Overview

 Copy code hover
[image]

MAPI Transport Provider Overview
Send feedback

Published: July 16, 2012

Transport providers handle message transmission and reception and implement security, if necessary. They also take care of any necessary preprocessing and postprocessing tasks. There is typically one transport provider for every active messaging system.

Client applications communicate with the transport provider through a message store provider.

Transport providers register with MAPI to handle one or more particular types of recipient entries. When a message is ready to be sent, MAPI must determine which transport provider should handle the transmission. Depending on the type of recipient, MAPI can even call upon more than one transport provider. If an unavailable transport provider is the only one that can handle the recipient, the message transmission will be postponed until a connection with that provider can be reestablished.

Some messaging systems are secure systems; all potential users are required to enter a set of valid credentials before access is permitted. MAPI prevents unauthorized access to such secure messaging systems by having the transport provider validate credentials at logon time.


MAPI Message Service Overview

 Copy code hover
[image]

MAPI Message Service Overview
See also Send feedback

Published: July 16, 2012

A message service defines a group of related service providers, typically service providers that work with the same messaging system. Whereas service providers perform the work of communicating between messaging systems and the MAPI subsystem, message services perform the work of interfacing between the user and service providers that work with a common messaging system.

Message services exist to make the installation and configuration of service providers easier for users. Users never directly install or configure a service provider; the message service completely handles the installation and configuration of each of the service providers that belong to the service. Because of this feature, users do not need to be familiar with specific service provider configuration requirements.

The following figure shows the relationship between a messaging-based client application and two message services.

Message service installation and configuration

Message service installation and configuration

The user invokes the installation code of each message service to add the service and its service providers to a profile. In one of the message services shown in the figure, there are three service providers; in the other message service, there are two service providers. At some later time after installation is complete, typically at logon time, the service providers in each message service are configured. The configuration code in each message service handles the configuration of the providers in the service.

When a message service is installed, its installation program copies necessary files from the installation source to the user's local disk and updates a configuration file, Mapisvc.inf. The Mapisvc.inf file contains configuration settings for all of the message services and service providers that can be installed on the computer. It is organized in hierarchical sections, with links between each section at each level. The section at the top level contains information that is relevant for the MAPI subsystem, such as a list of all available message services, and for the online Help installation. The next level has sections for each message service, with information such as the DLL file name of the message service and the name of its configuration entry point function. The third level has sections with configuration data for each service provider in the message service.

To handle configuration, a message service implements an entry point function that complies with a prototype defined by MAPI, and a tabbed dialog box known as a property sheet. MAPI calls the entry point function to service client requests that relate to profile management and the management of service providers in the message service. Property sheets are used for viewing and changing message service and service provider configuration properties.

See also

Concepts

MAPI Features and Architecture


MAPI Profile Overview

 Copy code hover
[image]

MAPI Profile Overview
See also Send feedback

Published: July 16, 2012

A profile is a collection of information about the message services and service providers that a user of a client application wants to be available during a particular MAPI session. Every user has at least one profile; many users keep several. For example, a user might have one profile to work with a server-based message store service and another profile to work with a message store service on the local computer. A user might want to access one set of messaging systems by using the appropriate transport services for part of the day and another set for the rest of the day. Profiles provide a flexible way to select combinations of messaging system services.

Profiles can have names up to 64 alphanumeric characters in length. The names can include accent characters, the underscore, and embedded spaces, and cannot include leading or trailing spaces.

Profiles are organized hierarchically and divided into sections, with one section for each message service and one section for each service provider in a service. The related sections are linked, making it easier to navigate through the information. Each section contains a series of entries that MAPI or a client application uses for configuration.

The entries included in a profile vary from message service to message service. Some of the common entries include the following:

  • The name of each message service or service provider.

  • The name of the DLLs that contain service providers and message services.

  • The name of each message service's entry point function.

  • A list of the service providers that make up each message service.

Profiles can be created at installation time, when MAPI or a message service is loaded onto a computer, or at any later time. MAPI provides the Profile Wizard for profile administration.

The Profile Wizard is an application that creates new profiles with a minimum amount of work. The wizard uses default values for settings wherever possible, saving users time and effort. Users enter values only when absolutely necessary. For more information, see Creating a Profile by Using the Profile Wizard. You can also use the Office Customization Tool to create a new profile. For more information, see Office Customization Tool.

See also

Concepts

MAPI Features and Architecture


MAPI Forms Overview

 Copy code hover
[image]

MAPI Forms Overview
See also Send feedback

Published: July 16, 2012

A MAPI form is a viewer for a message. Every message has a message class that dictates the particular form that is used as its viewer. MAPI defines several message classes and has implemented the forms for viewing messages of these classes. Client software developers can create new message classes and custom forms for viewing messages created by using the new classes.

Every custom form implements a set of standard menu commands, such as Open, Create, Delete, and Reply, and a set of commands that are specific to the particular form. Some of the form commands are integrated with the user interface of the client application when the form is active; other form commands completely replace the client commands.

The following illustration shows the relationship between the MAPI components involved in using forms.

MAPI form architecture

MAPI form architecture

In the diagram, notice that the form manager plays a role that is similar to other MAPI service providers, although it is not a service provider itself. The form manager is a replaceable DLL that implements some of the MAPI interfaces. Although developers can implement their own form manager, most environments will use the form manager provided by Microsoft due to the form manager's complexity.

The following list describes the components in the diagram and their relationship to other components:

  • Messaging client: An application that can use form objects. The messaging client uses the MAPI form interfaces to communicate with the form manager to load messages into form objects.

  • MAPI form interfaces: A defined standard for communication between MAPI components that are related to forms.

  • Form manager: The DLL that messaging clients use to handle installation of forms in form libraries, loading of form servers, and initial communication between messaging clients and form servers.

  • Form libraries: Permanent storage for the executable files associated with form servers.

  • Form servers: Executable files that implement a form. Form servers create form objects and user interfaces to deal with specific messages. This executable is also an OLE server and adheres to the usual OLE conventions.

  • Form objects: Run-time objects created by form servers that correspond to specific messages. Form objects run in the same process context as their form server.

For more information about MAPI form components, see MAPI Forms.

See also

Concepts

MAPI Features and Architecture


About the Offline State API

 Copy code hover
[image]

About the Offline State API
Send feedback

Published: July 16, 2012

The Offline State API supports callbacks indicating changes in a user's connection state in Microsoft Outlook 2013 and Microsoft Outlook 2010—for example, from being online in Outlook 2013 or Outlook 2010 to being offline. The API uses a global offline object in Outlook 2013 or Outlook 2010 to track such changes for a given user account profile. Notification is the only supported form of callback. As clients of this API, mail providers who want to be notified of such connection state changes do the following:

  1. Implement IMAPIOfflineNotify.

  2. Open an existing offline object for a specific profile using HrOpenOfflineObj.

  3. Determine if the object has the capability of providing online or offline notifications using IMAPIOffline::GetCapabilities.

  4. Register the object for online or offline notifications using IMAPIOfflineMgr::Advise. Mail providers can now receive notifications that Outlook 2013 or Outlook 2010 send using IMAPIOfflineNotify.

  5. On shutdown, remove registration for online and offline notifications using IMAPIOfflineMgr::Unadvise.

Note Note

In general, Outlook 2013 and Outlook 2010 can notify a client of online/offline changes as well as other changes, but the Offline State API supports only notifications for online/offline changes. The client should ignore all other notifications. For more information, see IMAPIOfflineNotify::Notify and MAPIOFFLINE_NOTIFY.

For an example of a client that uses the Offline State API, see About the Sample Offline State Add-in. The Sample Offline State Add-in is a COM add-in that uses the Offline State API to monitor and change the connection state.

This API provides the following:

Definitions:

  • MAPI Constants

Data types:

  • MAPIOFFLINE_ADVISEINFO

  • MAPIOFFLINE_CALLBACK_TYPE

  • MAPIOFFLINE_NOTIFY

Functions:

  • HrOpenOfflineObj

Interfaces:

  • IMAPIOffline

  • IMAPIOfflineMgr

  • IMAPIOfflineNotify


About the Sample Offline State Add-in

 Copy code hover
[image]

About the Sample Offline State Add-in
See also Send feedback

Published: July 16, 2012

The Offline State API supports callbacks indicating changes in a user's connection state in Outlook—for example, from being online in Outlook to being offline. The Sample Offline State Add-in is a COM add-in written in C++ that demonstrates how to receive notifications of connection state changes and how to modify the current state using the Offline State API. For more information about the Offline State API, see About the Offline State API.

In This Section

  • Installing the Sample Offline State Add-in

  • Explains how to download and install the Sample Offline State Add-in.

  • Setting Up an Offline State Add-in

  • Describes how to implement connection, initialization, and setup functions in order to use an offline state add-in.

  • Monitoring Connection State Changes Using an Offline State Add-in

  • Describes how to use the HrOpenOfflineObj function to obtain an offline object to monitor and change the connection state.

  • Disconnecting an Offline State Add-in

  • Describes how to properly terminate and clean up an offline state add-in when the add-in is disconnected.

See also

Concepts

About the Offline State API


Installing the Sample Offline State Add-in

 Copy code hover
[image]

Installing the Sample Offline State Add-in
See also Send feedback

Published: July 16, 2012

This topic takes you through the steps to download and install the Sample Offline State Add-in. The Sample Offline State Add-in is a COM add-in that adds an Offline State menu to Outlook and utilizes the Offline State API. Through the Offline State menu you can enable or disable state monitoring, check the current state, and change the current state. For more information about how the Offline State Add-in is implemented, see Setting Up an Offline State Add-in.

Install the Sample Offline State Add-in

  1. Download the Sample Offline State Add-in here: Outlook 2007 Auxiliary Reference Code Samples and Redistributable Installer.

  2. Run Visual Studio 2005 as an administrator.

    Note Note

    If your computer is running Windows XP, you must be logged in as an Administrator. If your computer is running Windows Vista, you must be logged in as an Administrator. Right-click the Visual Studio 2005 icon and click Run as administrator.

  3. In Visual Studio 2005, click File, select Open, and then click Project/Solution.

  4. Browse to the location where you saved the sample, click ConnectionStateAddin, and then click Open.

  5. On the Build menu, click Build Solution.

  6. In the Save File As dialog box, click Save.

  7. Click the Start menu, click All Programs, click Accessories, right-click Command Prompt, and then click Run as administrator.

    Note Note

    If you are running Windows XP, you must be logged in as an Administrator.

  8. In the User Account Control dialog box, click Continue.

  9. In the Command Prompt window, change directories to the Debug folder where you saved the sample. For example, if you saved the sample on your C:\ drive, you would type cd "C:\ConnectionStateAddin\Debug" and then press ENTER.

  10. Type regsvr32 OfflineStateAddin.dll and press ENTER.

    Note Note

    To uninstall the Sample Offline State Add-in, type regsvr32 -u OfflineStateAddin.dll

  11. In the RegSrv32 dialog box, click OK.

  12. Restart Outlook to see the Offline State menu.

See also

Concepts

About the Offline State API
Installing the Sample Offline State Add-in
About the Sample Offline State Add-in
Setting Up an Offline State Add-in
Monitoring Connection State Changes Using an Offline State Add-in
Disconnecting an Offline State Add-in


Setting Up an Offline State Add-in

 Copy code hover
[image]

Setting Up an Offline State Add-in
See also Send feedback

Published: July 16, 2012

To implement an offline state add-in, you must implement connection, initialization, and other setup functions. In this topic, these connection, initialization, and setup functions are demonstrated by using code examples from the Sample Offline State Add-in. The Sample Offline State Add-in is a COM add-in that adds an Offline State menu to Outlook and uses the Offline State API. Through the Offline State menu, you can enable or disable state monitoring, check the current state, and change the current state. For more information about downloading and installing the Sample Offline State Add-in, see Installing the Sample Offline State Add-in. For more information about the Offline State API, see About the Offline State API.

After you set up an offline state add-in, you must implement functions to monitor and modify connection state changes. For more information, see Monitoring Connection State Changes Using an Offline State Add-in.

On Connection Routine

The IDTExtensibility2.OnConnection Method is called every time an add-in is loaded. It is the entry point for the add-in, so the code you put in the OnConnection function will be called when the add-in starts. In the following example, the OnConnection function calls the HrInitAddin function.

CMyAddin::OnConnection() Example

Copy code Copy code
STDMETHODIMP CMyAddin::OnConnection(
    IDispatch * Application,
    ext_ConnectMode ConnectMode,
    IDispatch * /*AddInInst*/,
    SAFEARRAY * * /*custom*/)
{
    Log(true,"OnConnection\n");
    HRESULT hRes = S_OK;
    m_spApp = Application;
    m_ConnectMode = ConnectMode;
    if (ConnectMode == ext_cm_AfterStartup)
        hRes = HrInitAddin();
    return hRes;
}

Initialize Add-in Routine

The HrInitAddin function calls the LoadLibraries, HrCacheProfileName, and HrAddMenuItems functions to finish setting up the offline state add-in.

CMyAddin::HrInitAddin() Example

Copy code Copy code
HRESULT CMyAddin::HrInitAddin()
{
    HRESULT hRes = S_OK;
    LoadLibraries();
    hRes = HrCacheProfileName();
    Log(true,_T("HrCacheProfileName returned 0x%08X\n"),hRes);
    hRes = HrAddMenuItems();
    Log(true,_T("HrAddMenuItems returned 0x%08X\n"),hRes);
    return hRes;
}

Load Libraries Routine

The LoadLibraries function loads the dynamic-link library (DLL) files that the add-in requires.

LoadLibraries() Example

Copy code Copy code
void LoadLibraries()
{
    Log(true,_T("LoadLibraries - loading exports from DLLs\n"));
    HRESULT hRes = S_OK;
    UINT uiRet = 0;
    LONG lRet = 0;
    BOOL bRet = true;
    CHAR szSystemDir[MAX_PATH+1] = {0};

    // Get the system directory path
    // (mapistub.dll and mapi32.dll reside here)
    uiRet = GetSystemDirectoryA(szSystemDir, MAX_PATH);
    if (uiRet > 0)
    {
        CHAR szDLLPath[MAX_PATH+1] = {0};
        hRes = StringCchPrintfA(szDLLPath, MAX_PATH+1, "%s\\%s",
            szSystemDir, "mapistub.dll");
        if (SUCCEEDED(hRes))
        {
            LPFGETCOMPONENTPATH pfnFGetComponentPath = NULL;
            // Load mapistub.dll
            hModMAPIStub = LoadLibraryA(szDLLPath);
            if (hModMAPIStub)
            {
                // Get the address of FGetComponentPath from the mapistub
                pfnFGetComponentPath = (LPFGETCOMPONENTPATH)GetProcAddress(
                    hModMAPIStub, "FGetComponentPath");
            }
            // If there is no address for FGetComponentPath yet
            // try getting it from mapi32.dll
            if (!pfnFGetComponentPath)
            {
                hRes = StringCchPrintfA(szDLLPath, MAX_PATH+1, "%s\\%s",
                    szSystemDir, "mapi32.dll");
                if (SUCCEEDED(hRes))
                {
                    // Load mapi32.dll
                    hModMAPI = LoadLibraryA(szDLLPath);
                    if (hModMAPI)
                    {
                        // Get the address of FGetComponentPath from mapi32
                        pfnFGetComponentPath = (LPFGETCOMPONENTPATH)GetProcAddress(
                            hModMAPI, "FGetComponentPath");
                    }
                }
            }
            if (pfnFGetComponentPath)
            {
                LPSTR szAppLCID = NULL;
                LPSTR szOfficeLCID = NULL;
                HKEY hMicrosoftOutlook = NULL;
                lRet = RegOpenKeyEx(
                    HKEY_LOCAL_MACHINE,
                    _T("Software\\Clients\\Mail\\Microsoft Outlook"),
                    NULL,
                    KEY_READ,
                    &hMicrosoftOutlook);
                if (ERROR_SUCCESS == lRet && hMicrosoftOutlook)
                {
                    HrGetRegMultiSZValueA(hMicrosoftOutlook, "MSIApplicationLCID", (LPVOID*) &szAppLCID);
                    HrGetRegMultiSZValueA(hMicrosoftOutlook, "MSIOfficeLCID", (LPVOID*) &szOfficeLCID);
                }
                if (szAppLCID)
                {
                    bRet = pfnFGetComponentPath(
                        "{FF1D0740-D227-11D1-A4B0-006008AF820E}", szAppLCID, szDLLPath, MAX_PATH, true);
                }
                if ((!bRet || szDLLPath[0] == _T('\0')) && szOfficeLCID)
                {
                    bRet = pfnFGetComponentPath(
                        "{FF1D0740-D227-11D1-A4B0-006008AF820E}", szOfficeLCID, szDLLPath, MAX_PATH, true);
                }
                if (!bRet || szDLLPath[0] == _T('\0'))
                {
                    bRet = pfnFGetComponentPath(
                        "{FF1D0740-D227-11D1-A4B0-006008AF820E}", NULL, szDLLPath, MAX_PATH, true);
                }
                delete[] szOfficeLCID;
                delete[] szAppLCID;
                if (hMicrosoftOutlook) RegCloseKey(hMicrosoftOutlook);
            }
            hModMSMAPI = LoadLibrary(szDLLPath);
            if (hModMSMAPI)
            {
                pfnHrOpenOfflineObj = (HROPENOFFLINEOBJ*) GetProcAddress(
                    hModMSMAPI,
                    "HrOpenOfflineObj@20");
                pfnMAPIFreeBuffer = (LPMAPIFREEBUFFER) GetProcAddress(
                    hModMSMAPI,
                    "MAPIFreeBuffer");
            }
        }
    }
}

Cache Profile Name Routine

The HrCacheProfileName function calls the IMAPISupport::OpenProfileSection function to open a profile section for the current session, and then sets the profile for the button handlers.

CMyAddin::HrCacheProfileName() Example

Copy code Copy code
HRESULT CMyAddin::HrCacheProfileName()
{
    HRESULT hRes = S_OK;
    _NameSpacePtr spSession = m_spApp->GetNamespace("MAPI");
    IUnknown* lpMAPIObject = NULL;
    LPMAPISESSION lpMAPISession = NULL;
    // use the raw accessor
    hRes = spSession->get_MAPIOBJECT(&lpMAPIObject);
    if (SUCCEEDED(hRes) && lpMAPIObject)
    {
        hRes = lpMAPIObject->QueryInterface(IID_IMAPISession,(LPVOID*)&lpMAPISession);
    }
    if (SUCCEEDED(hRes) && lpMAPISession)
    {
        LPPROFSECT lpPSGlobal = NULL;
        hRes = lpMAPISession->OpenProfileSection((LPMAPIUID)pbGlobalProfileSectionGuid, NULL, 0, &lpPSGlobal);

        if (SUCCEEDED(hRes) && lpPSGlobal)
        {
            LPSPropValue lpProfileName = NULL;
            // Asking for PR_PROFILE_NAME_W here - this might not work with earlier versions of Outlook
            SPropTagArray staga = {1,PR_PROFILE_NAME_W};
            ULONG cVal = 0;
            hRes = lpPSGlobal->GetProps(&staga,0,&cVal,&lpProfileName);
            if (SUCCEEDED(hRes) && 1 == cVal && lpProfileName && PR_PROFILE_NAME_W == lpProfileName->ulPropTag)
            {
                m_InitButtonHandler.SetProfile(lpProfileName->Value.lpszW);
                m_GetStateButtonHandler.SetProfile(lpProfileName->Value.lpszW);
                m_SetStateButtonHandler.SetProfile(lpProfileName->Value.lpszW);
            }
            if (pfnMAPIFreeBuffer) pfnMAPIFreeBuffer(lpProfileName);
        }
        if (lpPSGlobal) lpPSGlobal->Release();
    }
    if (lpMAPISession) lpMAPISession->Release();
    return hRes;
}

Add Menu Items Routine

The HrAddMenuItems function defines the menu options that appear under the Offline State menu that is created when the add-in is loaded in Outlook, and then calls DispEventAdvise for each menu item.

CMyAddin::HrAddMenuItems() Example

Copy code Copy code
HRESULT CMyAddin::HrAddMenuItems()
{
    Log(true,"HrAddMenuItems\n");
    HRESULT    hRes = S_OK;
    if (!m_fMenuItemsAdded)
    {
        try
        {
            _ExplorerPtr spExplorer = m_spApp->ActiveExplorer();
            _CommandBarsPtr spCmdBars = spExplorer->__CommandBars;
            CommandBarPtr spMainBar = spCmdBars->ActiveMenuBar;
            CommandBarControlsPtr spMainCtrls = spMainBar->Controls;

            try { m_spMyMenu = spMainCtrls->GetItem("Offline State"); } catch (_com_error) {}
            if (m_spMyMenu == NULL)
            {
                m_spMyMenu = spMainCtrls->Add((long)msoControlPopup,vtMissing,vtMissing,vtMissing, true);
                m_spMyMenu->Caption = "Offline State";
            }

            CommandBarControlsPtr spMyMenuCtrls = m_spMyMenu->Controls;
            try { m_spInitButton = spMyMenuCtrls->GetItem("&Init Monitor"); } catch (_com_error) {}
            if (m_spInitButton == NULL)
            {
                m_spInitButton = spMyMenuCtrls->Add((long)msoControlButton, vtMissing, vtMissing, vtMissing, true);
                m_spInitButton->Caption = "&Init Monitor";
                m_spInitButton->FaceId = MY_INIT_BUTTON;
            }
            try { m_spDeinitButton = spMyMenuCtrls->GetItem("&Deinit Monitor"); } catch (_com_error) {}
            if (m_spDeinitButton == NULL)
            {
                m_spDeinitButton = spMyMenuCtrls->Add((long)msoControlButton, vtMissing, vtMissing, vtMissing, true);
                m_spDeinitButton->Caption = "&Deinit Monitor";
                m_spDeinitButton->FaceId = MY_DEINIT_BUTTON;
            }
            try { m_spGetStateButton = spMyMenuCtrls->GetItem("&GetCurrentState"); } catch (_com_error) {}
            if (m_spGetStateButton == NULL)
            {
                m_spGetStateButton = spMyMenuCtrls->Add((long)msoControlButton, vtMissing, vtMissing, vtMissing, true);
                m_spGetStateButton->Caption = "&GetCurrentState";
                m_spGetStateButton->FaceId = MY_GETSTATE_BUTTON;
            }
            try { m_spSetStateButton = spMyMenuCtrls->GetItem("&SetCurrentState"); } catch (_com_error) {}
            if (m_spSetStateButton == NULL)
            {
                m_spSetStateButton = spMyMenuCtrls->Add((long)msoControlButton, vtMissing, vtMissing, vtMissing, true);
                m_spSetStateButton->Caption = "&SetCurrentState";
                m_spSetStateButton->FaceId = MY_SETSTATE_BUTTON;
            }
            // Set up advise
            _com_util::CheckError(m_InitButtonHandler.DispEventAdvise(m_spInitButton));
            _com_util::CheckError(m_DeinitButtonHandler.DispEventAdvise(m_spDeinitButton));
            _com_util::CheckError(m_GetStateButtonHandler.DispEventAdvise(m_spGetStateButton));
            _com_util::CheckError(m_SetStateButtonHandler.DispEventAdvise(m_spSetStateButton));
        }
        catch (_com_error)
        {
            hRes = E_FAIL;
        }
        if (SUCCEEDED(hRes))
        {
            m_fMenuItemsAdded = true;
        }
    }
    return hRes;
}

See also

Concepts

About the Offline State API
Installing the Sample Offline State Add-in
About the Sample Offline State Add-in
Monitoring Connection State Changes Using an Offline State Add-in
Disconnecting an Offline State Add-in


Monitoring Connection State Changes Using an Offline State Add-in

 Copy code hover
[image]

Monitoring Connection State Changes Using an Offline State Add-in
See also Send feedback

Published: July 16, 2012

Before you can use an offline state add-in to monitor connection state changes, you must implement functions to set up and initialize the add-in. For more information, see Setting Up an Offline State Add-in.

After you set up the offline state add-in, you must use the HrOpenOfflineObj function to obtain an offline object. Using this offline object, you can initialize your state monitor, and then get and set the current state.

In this topic, these state monitoring functions are demonstrated by using code examples from the Sample Offline State Add-in. The Sample Offline State Add-in is a COM add-in that adds an Offline State menu to Outlook and utilizes the Offline State API. Through the Offline State menu, you can enable or disable state monitoring, check the current state, and change the current state. For more information about downloading and installing the Sample Offline State Add-in, see Installing the Sample Offline State Add-in. For more information about the Offline State API, see About the Offline State API.

When the offline state add-in is disconnected, you must implement functions to properly terminate and clean up the add-in. For more information, see Disconnecting an Offline State Add-in.

Open Offline Object Routine

For the client to be notified when a connection state change occurs, you must call the HrOpenOfflineObj function. This function opens an offline object that supports IMAPIOfflineMgr. The HrOpenOfflineObj function is defined in the ConnectionState.h header file.

Note Note

The HrOpenOfflineObj function is declared in the ImportProcs.h header file as follows: extern HROPENOFFLINEOBJ* pfnHrOpenOfflineObj;.

HrOpenOfflineObj Example

Copy code Copy code
typedef HRESULT (STDMETHODCALLTYPE HROPENOFFLINEOBJ)(
    ULONG ulFlags,
    LPCWSTR pwszProfileName,
    const GUID* pGUID,
    const GUID* pInstance,
    IMAPIOfflineMgr** ppOffline
);

Initialize Monitor Routine

The InitMonitor function calls the HrOpenOfflineObj function. The InitMonitor function calls CMyOfflineNotify so that Outlook can send callback notifications to the client, and registers the callback through the MAPIOFFLINE_ADVISEINFO variable AdviseInfo.

InitMonitor() Example

Copy code Copy code
void InitMonitor(LPCWSTR szProfile)
{
    if (!szProfile) return;
    Log(true,_T("Initializing Outlook Offline State Monitor\n"));
    HRESULT hRes = S_OK;

    if (g_lpOfflineMgr)
    {
        Log(true,_T("Already initialized\n"));
        return;
    }

    if (pfnHrOpenOfflineObj)
    {
        if (g_lpOfflineMgr) DeInitMonitor();
        Log(true,_T("Calling HrOpenOfflineObj for \"%ws\"\n"),szProfile);
        hRes = pfnHrOpenOfflineObj(
            NULL,
            szProfile,
            &GUID_GlobalState,
            NULL,
            &g_lpOfflineMgr);
        if (FAILED(hRes))
        {
            Log(true,_T("HrOpenOfflineObj failed: 0x%08X\n"),hRes);
        }
        if (g_lpOfflineMgr)
        {
            IMAPIOffline* lpOffline = NULL;
            hRes = g_lpOfflineMgr->QueryInterface(IID_IMAPIOffline,(LPVOID*)&lpOffline);

            if (lpOffline)
            {
                ULONG ulCap = NULL;
                hRes = lpOffline->GetCapabilities(&ulCap);

                if (ulCap & MAPIOFFLINE_CAPABILITY_OFFLINE) Log(true,_T("MAPIOFFLINE_CAPABILITY_OFFLINE supported\n"));
                if (ulCap & MAPIOFFLINE_CAPABILITY_ONLINE) Log(true,_T("MAPIOFFLINE_CAPABILITY_ONLINE supported\n"));

                if (ulCap & (MAPIOFFLINE_CAPABILITY_OFFLINE | MAPIOFFLINE_CAPABILITY_ONLINE))
                {
                    CMyOfflineNotify* lpImplNotify = new CMyOfflineNotify();

                    if (lpImplNotify)
                    {
                        MAPIOFFLINE_ADVISEINFO AdviseInfo = {0};
                        AdviseInfo.ulSize = sizeof(MAPIOFFLINE_ADVISEINFO);
                        AdviseInfo.ulClientToken = 0;// something you want to get handed back when you get the notification
                        AdviseInfo.CallbackType = MAPIOFFLINE_CALLBACK_TYPE_NOTIFY;
                        AdviseInfo.pCallback = lpImplNotify;
                        AdviseInfo.ulAdviseTypes = MAPIOFFLINE_ADVISE_TYPE_STATECHANGE;
                        AdviseInfo.ulStateMask = MAPIOFFLINE_STATE_ALL;

                        hRes = g_lpOfflineMgr->Advise(MAPIOFFLINE_ADVISE_DEFAULT, &AdviseInfo, &g_ulAdviseToken);
                        Log(true,"ulAdviseToken = 0x%08X\n",g_ulAdviseToken);
                    }
                }
                lpOffline->Release();
            }
        }
    }
}

Get Current State Routine

The GetCurrentState function calls the HrOpenOfflineObj function, and then uses the offline object to get the current connection state. The current state is returned in the ulCurState variable, which is used in the CButtonEventHandler::Click function to display the current state to the user.

GetCurrentState() Example

Copy code Copy code
ULONG (LPCWSTR szProfile)
{
    if (!szProfile) return 0;
    Log(true,_T("Getting Current Offline State\n"));
    HRESULT hRes = S_OK;
    ULONG ulCurState = NULL;

    if (pfnHrOpenOfflineObj)
    {
        if (g_lpOfflineMgr) DeInitMonitor();
        Log(true,_T("Calling HrOpenOfflineObj for \"%ws\"\n"),szProfile);
        hRes = pfnHrOpenOfflineObj(
            NULL,
            szProfile,
            &GUID_GlobalState,
            NULL,
            &g_lpOfflineMgr);
        if (FAILED(hRes))
        {
            Log(true,_T("HrOpenOfflineObj failed: 0x%08X\n"),hRes);
        }
        if (g_lpOfflineMgr)
        {
            IMAPIOffline* lpOffline = NULL;
            hRes = g_lpOfflineMgr->QueryInterface(IID_IMAPIOffline,(LPVOID*)&lpOffline);

            if (lpOffline)
            {
                hRes = lpOffline->GetCurrentState(&ulCurState);
                Log(true,_T("GetCurrentState returned 0x%08X\n"),hRes);

                switch(ulCurState)
                {
                case MAPIOFFLINE_STATE_ONLINE:
                    Log(true,_T("Current state is MAPIOFFLINE_STATE_ONLINE\n"));
                    break;
                case MAPIOFFLINE_STATE_OFFLINE:
                    Log(true,_T("Current state is MAPIOFFLINE_STATE_OFFLINE\n"));
                    break;
                default:
                    Log(true,_T("Current state is 0x%0X\n"),ulCurState);
                }
                lpOffline->Release();
            }
        }
    }
    return ulCurState;
}

Set Current State Routine

The SetCurrentState function calls the HrOpenOfflineObj function, and then uses the offline object to set the current connection state. The CButtonEventHandler::Click function calls the SetCurrentState function and the new state is passed in through the ulState variable.

SetCurrentState() Example

Copy code Copy code
HRESULT SetCurrentState(LPCWSTR szProfile, ULONG ulFlags, ULONG ulState)
{
    if (!szProfile) return 0;
    Log(true,_T("Setting Current Offline State\n"));
    HRESULT hRes = S_OK;

    if (pfnHrOpenOfflineObj)
    {
        if (g_lpOfflineMgr) DeInitMonitor();
        Log(true,_T("Calling HrOpenOfflineObj for \"%ws\"\n"),szProfile);
        hRes = pfnHrOpenOfflineObj(
            NULL,
            szProfile,
            &GUID_GlobalState,
            NULL,
            &g_lpOfflineMgr);
        if (FAILED(hRes))
        {
            Log(true,_T("HrOpenOfflineObj failed: 0x%08X\n"),hRes);
        }
        if (g_lpOfflineMgr)
        {
            IMAPIOffline* lpOffline = NULL;
            hRes = g_lpOfflineMgr->QueryInterface(IID_IMAPIOffline,(LPVOID*)&lpOffline);

            if (lpOffline)
            {
                switch(ulFlags)
                {
                case MAPIOFFLINE_FLAG_BLOCK:
                    Log(true,_T("Flag used: MAPIOFFLINE_FLAG_BLOCK\n"));
                    break;
                case MAPIOFFLINE_FLAG_DEFAULT:
                    Log(true,_T("Flag used: MAPIOFFLINE_FLAG_DEFAULT\n"));
                    break;
                default:
                    Log(true,_T("Flag used: 0x%0X\n"),ulFlags);
                }
                switch(ulState)
                {
                case MAPIOFFLINE_STATE_ONLINE:
                    Log(true,_T("New state will be MAPIOFFLINE_STATE_ONLINE\n"));
                    break;
                case MAPIOFFLINE_STATE_OFFLINE:
                    Log(true,_T("New state will be MAPIOFFLINE_STATE_OFFLINE\n"));
                    break;
                default:
                    Log(true,_T("New state will be 0x%0X\n"),ulState);
                }
                hRes = lpOffline->SetCurrentState(ulFlags, MAPIOFFLINE_STATE_OFFLINE_MASK,ulState,NULL);
                Log(true,_T("SetCurrentState returned 0x%08X\n"),hRes);

                lpOffline->Release();
            }
        }
    }
    return hRes;
}

Notification Routine

The IMAPIOfflineNotify::Notify function is used by Outlook to send notifications to a client when there are changes in the connection state.

CMyOfflineNotify::Notify() Example

Copy code Copy code
void CMyOfflineNotify::Notify(const MAPIOFFLINE_NOTIFY *pNotifyInfo)
{
    Log(true,_T("CMyOfflineNotify::Notify\n"));
    if    (pNotifyInfo == NULL)
    {
        Log(true,_T("pNotifyInfo is NULL\n"));
    }
    else
    {
        Log(true,_T("pNotifyInfo->ulSize == 0x%0X\n"),pNotifyInfo->ulSize);
        switch(pNotifyInfo->NotifyType)
        {
            case    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE:
                Log(true,_T("pNotifyInfo->NotifyType == MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE\n"));
                break;
            case    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_START:
                Log(true,_T("pNotifyInfo->NotifyType == MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_START\n"));
                break;
            case    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_DONE:
                Log(true,_T("pNotifyInfo->NotifyType == MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_DONE\n"));
                break;
            default:
                Log(true,_T("pNotifyInfo->NotifyType == 0x%08X\n"),pNotifyInfo->NotifyType);
        }
        Log(true,_T("pNotifyInfo->ulClientToken == 0x%0X\n"),pNotifyInfo->ulClientToken);
        switch(pNotifyInfo->Info.StateChange.ulMask)
        {
            case    MAPIOFFLINE_STATE_OFFLINE_MASK:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulMask == MAPIOFFLINE_STATE_OFFLINE_MASK\n"));
                break;
            default:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulMask == 0x%0X\n"),pNotifyInfo->Info.StateChange.ulMask);
        }
        switch(pNotifyInfo->Info.StateChange.ulStateOld)
        {
            case    MAPIOFFLINE_STATE_ONLINE:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateOld == MAPIOFFLINE_STATE_ONLINE\n"));
                break;
            case    MAPIOFFLINE_STATE_OFFLINE:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateOld == MAPIOFFLINE_STATE_OFFLINE\n"));
                break;
            default:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateOld == 0x%0X\n"),pNotifyInfo->Info.StateChange.ulStateOld);
        }
        switch(pNotifyInfo->Info.StateChange.ulStateNew)
        {
            case    MAPIOFFLINE_STATE_ONLINE:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateNew == MAPIOFFLINE_STATE_ONLINE\n"));
                break;
            case    MAPIOFFLINE_STATE_OFFLINE:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateNew == MAPIOFFLINE_STATE_OFFLINE\n"));
                break;
            default:
                Log(true,_T("pNotifyInfo->Info.StateChange.ulStateNew == 0x%0X\n"),pNotifyInfo->Info.StateChange.ulStateNew);
        }
    }
    return;
}

See also

Concepts

About the Offline State API
Installing the Sample Offline State Add-in
About the Sample Offline State Add-in
Setting Up an Offline State Add-in
Disconnecting an Offline State Add-in


Disconnecting an Offline State Add-in

 Copy code hover
[image]

Disconnecting an Offline State Add-in
See also Send feedback

Published: July 16, 2012

When the offline state add-in is disconnected, you must implement functions to properly terminate and clean up the add-in. For more information on setting up and using the offline state add-in to monitor connection state changes, see Setting Up an Offline State Add-in and Monitoring Connection State Changes Using an Offline State Add-in.

In this topic, these disconnection, terminate, and clean-up functions are demonstrated by using code examples from the Sample Offline State Add-in. The Sample Offline State Add-in is a COM add-in that adds an Offline State menu to Outlook and uses the Offline State API. Through the Offline State menu, you can enable or disable state monitoring, check the current state, and change the current state. For more information about downloading and installing the Sample Offline State Add-in, see Installing the Sample Offline State Add-in. For more information about the Offline State API, see About the Offline State API.

On Disconnection Routine

The IDTExtensibility2.OnDisconnection method is called when the Offline State Add-in is unloaded. You should implement clean up code in this function. In the following example, the IDTExtensibility2.OnDisconnection function calls the HrTermAddin function.

CMyAddin::OnDisconnection() Example

Copy code Copy code
STDMETHODIMP CMyAddin::OnDisconnection(ext_DisconnectMode /*RemoveMode*/, SAFEARRAY * * /*custom*/)
{
    Log(true,"OnDisconnection\n");
    HRESULT hRes = S_OK;
    hRes = HrTermAddin();
     return hRes;
}

Terminate Add-in Function

The HrTermAddin function calls the inDeInitMonitor, HrRemoveMenuItems, and UnloadLibraries functions to finish cleaning up the Offline State Add-in.

CMyAddin::HrTermAddin()

Copy code Copy code
HRESULT CMyAddin::HrTermAddin()
{
    HRESULT hRes = S_OK;
    DeInitMonitor();
    hRes =  HrRemoveMenuItems();
    UnloadLibraries();
    return hRes;
}

Deinitialize Monitor Routine

The inDeInitMonitor function calls the IMAPIOfflineMgr::Unadvise function to cancel the callbacks for the offline object.

DeInitMonitor() Example

Copy code Copy code
void DeInitMonitor()
{
Log(true,_T("Deinitializing Outlook Offline State Monitor\n"));
HRESULT hRes = S_OK;
if (g_lpOfflineMgr)
{
hRes = g_lpOfflineMgr->Unadvise(MAPIOFFLINE_UNADVISE_DEFAULT, g_ulAdviseToken);
g_lpOfflineMgr->Release();
g_lpOfflineMgr = NULL;
g_ulAdviseToken = NULL;
}
}

Remove Menu Items Routine

The HrRemoveMenuItems function calls DispEventUnadvise for each menu item under the Offline State menu, and then deletes the Offline State menu.

CMyAddin::HrRemoveMenuItems() Example

Copy code Copy code
HRESULT CMyAddin::HrRemoveMenuItems()
{
    Log(true,"HrRemoveMenuItems\n");
    HRESULT hRes = S_OK;
    if (m_fMenuItemsAdded)
    {
        try
        {
            if (m_spInitButton)
            {
                m_InitButtonHandler.DispEventUnadvise(m_spInitButton);
            }
            if (m_spDeinitButton)
            {
                m_DeinitButtonHandler.DispEventUnadvise(m_spDeinitButton);
            }
            if (m_spGetStateButton)
            {
                m_GetStateButtonHandler.DispEventUnadvise(m_spGetStateButton);
            }
            if (m_spSetStateButton)
            {
                m_SetStateButtonHandler.DispEventUnadvise(m_spSetStateButton);
            }

            m_spMyMenu->Delete();
        }
        catch(_com_error)
        {
            hRes = E_FAIL;
        }
        if (SUCCEEDED(hRes))
        {
            m_fMenuItemsAdded = false;
        }
    }
    return hRes;
}

Unload Libraries Routine

When the add-in is unloaded from Outlook, the UnloadLibraries function unloads the dynamic-link libraries (DLLs) that the add-in required.

UnloadLibraries() Example

Copy code Copy code
void UnloadLibraries()
{
    Log(true,_T("UnloadLibraries - freeing modules\n"));
    pfnHrOpenOfflineObj = NULL;
    pfnMAPIFreeBuffer = NULL;
    if (hModMSMAPI) FreeLibrary(hModMSMAPI);
    hModMSMAPI = NULL;
    if (hModMAPI) FreeLibrary(hModMAPI);
    hModMAPI = NULL;
    if (hModMAPIStub) FreeLibrary(hModMAPIStub);
    hModMAPIStub = NULL;
}

See also

Concepts

About the Offline State API
Installing the Sample Offline State Add-in
About the Sample Offline State Add-in
Setting Up an Offline State Add-in
Monitoring Connection State Changes Using an Offline State Add-in


About the MAPI Crash Recovery API

 Copy code hover
[image]

About the MAPI Crash Recovery API
See also Send feedback

Published: July 16, 2012

The MAPI Crash Recovery API checks the state of the Personal Folders file (PST) or Offline Folders file (OST) shared memory to verify that the data is in a consistent state. If it is in a consistent state, the MAPICrashRecovery function moves the data from the open PSTs or OSTs to disk and locks the PSTs or OSTs and does not allow any read or write access to the data. This ensures that the data remains in a consistent state until the process is terminated. By ensuring that the PSTs or OSTs are in a consistent state before the process is terminated, you can prevent Microsoft Outlook 2013 and Microsoft Outlook 2010 from displaying the following error message and avoid performance problems.

A data file did not close properly the last time it was used and is being checked for problems. Performance might be affected while the check is in progress.

This API provides the following:

Constants:

  • MAPI Constants

Functions:

  • MAPICrashRecovery

See also

Concepts

How to: Use the MAPI Crash Recovery API


About Setting the Resolution Order for Address Lists in Outlook

 Copy code hover
[image]

About Setting the Resolution Order for Address Lists in Outlook
Send feedback

Published: July 16, 2012

For each profile, Microsoft Office Outlook supports multiple address lists and users can manually specify the order of address lists by which recipients in e-mail messages and attendees in meeting requests are resolved. For example, you can set the resolution order so that names are resolved first against your Outlook Address Book, and then against the Global Address List. On a computer, a user can open the Address Book, click Tools and then Options to specify this resolution order. However, in a corporate environment, it is more efficient for IT administrators to programmatically set the order of address lists by which names are resolved. Such code can be used as part of a startup automation script that an administrator deploys inside the corporation.

MAPI supports the SetSearchPath method in the IAddrBook interface, which allows you to set a new search path in the profile that is used for name resolution. To use the IAddrBook::SetSearchPath method, you must specify the desired resolution order by using an array that holds containers of the relevant address books in the order they should be resolved. Each entry in that array should also contain the entry ID of the corresponding address book.

The following are code examples of how to specify a custom search path for address lists.

  • How to: Programmatically Set the Resolution Order for Address Lists

  • KB 292590: How To Change Address Book Sort Order with SetSearchPath


About the Replication API

 Copy code hover
[image]

About the Replication API
Send feedback

Published: July 16, 2012

The Replication API provides the functionality for a MAPI message store provider to synchronize Microsoft Outlook 2013 or Microsoft Outlook 2010 items between a server and a private .pst-based local store that is created for that provider.

Note Note

A MAPI message store provider must implement the Replication API according to the instructions in About the Replication State Machine. The provider must use the API only on a personal store created for itself, and not on personal stores created for other providers, because personal stores created for other providers may have already set up their own replication mechanisms with the respective server. For example, an offline folder file (.ost) maintains its own replication relationship with a Microsoft Exchange server.

To use the Replication API, a MAPI message store provider must first open and wrap a .pst-based local store by calling NSTServiceEntry. The provider can then use the major interfaces of the API, IOSTX and IPSTX, to carry out replication. IPSTX is provided by querying on IMsgStore : IMAPIProp, and IOSTX is provided by IPSTX::GetSyncObject.

The IOSTX Interface

The IOSTX interface is the primary interface that performs synchronization in the Replication API. IOSTX moves the local store through a series of states, retrieving information in each state about changes in the local store, as well as informing the local store of changes on the server. The Replication API also specifies many data structures that support the synchronization.

A store provider, as a client to this API, uses the Replication API to wrap the local store and move through these states, pushing changes on the local store (such as changes to the folder hierarchy or the addition of new items) to the server, and also retrieving information about changes on the server and providing that information to the IOSTX interface. The IOSTX interface adopts Incremental Change Synchronization (ICS) provided by Microsoft Exchange Server. For more information about ICS, see ICS Evaluation Criteria. Through IOSTX, the client uses ICS to monitor and synchronize incremental changes to the hierarchy or content on a local store.

The IPSTX Interface

IPSTX and five other IPSTXn interfaces that inherit from IPSTX provide helper functionality that can be used when performing replication through the IOSTX interface. For example, IPSTX::EmulateSpooler allows you to make the local store emulate the Outlook Protocol Manager to spool outgoing messages to a server.

For more information about state transitions during replication, see About the Replication State Machine.

The Replication API

The Replication API provides the following defintions, data types, and interfaces. For a sample implementation of a store provider for wrapped Personal Folders files (PST), see About the Sample Wrapped PST Store Provider.

Definitions:

  • Constants for the Replication API

Functions:

  • NSTServiceEntry

Data types:

  • DNHIER

  • DNTBL

  • DNTBLE

  • FEID

  • HDRSYNC

  • LTID

  • MEID

  • OLFI

  • SKEY

  • SYNC

  • SYNCCONT

  • SYNCSTATE

  • UPDEL

  • UPDELE

  • UPFLD

  • UPHIER

  • UPMOV

  • UPMSG

  • UPREAD

  • UPREADE

  • UPTBL

  • UPTBLE

Interfaces:

  • IOSTX

  • IPSTX

  • IPSTX2

  • IPSTX3

  • IPSTX4

  • IPSTX5

  • IPSTX6


About the Sample Wrapped PST Store Provider

 Copy code hover
[image]

About the Sample Wrapped PST Store Provider
See also Send feedback

Published: July 16, 2012

Overview of Message Store Providers

Message store providers handle the storage and retrieval of messages and other information for the users of client applications. The message information is organized by using a hierarchical system known as a message store. The message store is implemented in multiple levels, with containers called folders that hold messages of different types. There is no limit to the number of levels in a message store; folders can contain many subfolders.

Message store data can be used in a variety of ways. In addition to the typical e-mail usage, folders can be used as a forum for public discussion, as a repository for reference documents, or as a container for bulletin board information. A single message store can hold many types of information, some modifiable and some not. Multiple clients can install the same message store, making it easy and fast to share data.

Message store folders allow you to sort and filter messages and to customize the view in a user interface (UI) display. Links to filtered messages are held in special folders called search-results folders. The user of a client application enters filtering criteria, which MAPI refers to as a restriction, and the criteria is applied to the messages stored in one or more folders. For example, a user might want to view only those messages dealing with a particular subject with arrival dates that are more recent than last week. References to the messages that match the criteria are listed in the search-results folder and the real messages remain in their regular folders.

Messages are the units of data transferred from one user or application to another user or application. Every message contains some message text and message envelope information that is used for transmission. Some messages include one or more attachments, or additional data related to and transported with a message in the form of a file, another message, or an OLE object.

The Sample Wrapped PST Store Provider

The Replication API allows you to replicate items from a back-end data repository into an Outlook PST store. You use the Replication API to replicate the data into a dedicated PST store and keep track of the synchronization state. This approach does not require you to introduce a custom MAPI store provider, which is complex to write and maintain. However, the PST store provider does need to be wrapped to work with the Replication API.

The Sample Wrapped PST Store Provider uses the Personal Folders file (PST) provider as the back end for storing data. The wrapped PST store provider should be used in conjunction with the Replication API. For more information, see About the Replication API. Most of the functions in the Sample Wrapped PST Store Provider pass their arguments directly to the underlying PST provider. Certain functions require special implementation and are described in the following topics.

In This Section

  • Installing the Sample Wrapped PST Store Provider

  • Explains how to download and install the Sample Wrapped PST Store Provider.

  • Initializing a Wrapped PST Store Provider

  • The first step in implementing a wrapped PST store provider is to initialize and configure the wrapped PST store provider.

  • Logging On to a Wrapped PST Store Provider

  • After a wrapped PST store provider is initialized, you must implement functions so that MAPI and the MAPI spooler can log on to the wrapped PST store provider.

  • Using a Wrapped PST Store Provider

  • To use a wrapped PST store provider you must wrap the IMAPISupport::IUnknown interface to implement common wrapped PST store provider tasks.

  • Shutting Down a Wrapped PST Store Provider

  • After you finish using a wrapped PST store provider, you must properly shut down the wrapped PST store provider.

See also

Concepts

About the Replication API
Developing a MAPI Message Store Provider


About the Replication State Machine

 Copy code hover
[image]

About the Replication State Machine
See also Send feedback

Published: July 16, 2012

This topic contains an overview of the state machine for Microsoft Outlook 2013 and Microsoft Outlook 2010 data replication.

Note Note

The Replication API must be fully implemented according to the instructions in this topic in order to be useful or supported. The Replication API is available exclusively to replicate Outlook 2013 or Outlook 2010 changes to and from a server.

IOSTX and the State Machine

A client calls IOSTX::SyncBeg, IOSTX::SyncEnd, IOSTX::SyncHdrBeg, and IOSTX::SyncHdrEnd in a sequence to synchronize Outlook 2013 or Outlook 2010 folders and items between a local store and a server. The actual sequence of calls depends on the data that needs to be replicated (for example, a hierarchy of Outlook 2013 or Outlook 2010 folders, an Outlook 2013 or Outlook 2010 folder, mail items, calendar items, and so on) and the direction of synchronization (whether uploading from the local store to the server, or downloading from the server to the local store). Here is a typical sequence of calls:

  1. The client calls IOSTX::SyncBeg to begin replication, specifying a state identifier and a pointer to an address of a corresponding data structure.

  2. Outlook 2013 or Outlook 2010 allocates the data structure and initializes the data structure with the necessary information for the client.

  3. The client performs the replication, updating the data structure to convey to the local store any necessary information about the replication.

  4. After performing the replication, the client calls IOSTX::SetSyncResult and IOSTX::SyncEnd to notify the local store of the completion of the specific replication.

Note Note

The client always calls IOSTX::SyncEnd to end a replication that the client has begun for a certain state. Depending on the overall data that the client needs to synchronize, the client may call the pair of calls IOSTX::SyncBeg and IOSTX::SyncEnd more than once.

State Table

Note Note

The following table lists all the valid states in the replication state machine, along with the corresponding state identifiers and data structures. In the Data Replicated column, the term "items" includes mail, calendar, contact, note, journal, and task items. When replicating changes from the local store to the server, use state identifiers specifying "UPLOAD" and data structures with the "UP" prefix (for example, LR_SYNC_UPLOAD_HIERARCHY and UPHIER). When replicating changes from the server to the local store, use state identifiers specifying "DOWNLOAD" and data structures with the "DN" prefix (for example, LR_SYNC_DOWNLOAD_HIERARCHY and DNHIER).

State | Data Replicated | State Identifier | Data Structure
Idle state | None | LR_SYNC_IDLE | None
Synchronize state | Folders or items | LR_SYNC | SYNC
Upload hierarchy state | Folders | LR_SYNC_UPLOAD_HIERARCHY | UPHIER
Upload folder state | Folder | LR_SYNC_UPLOAD_FOLDER | UPFLD
Synchronize contents state | Items | LR_SYNC_CONTENTS | SYNCCONT
Upload table state | Items | LR_SYNC_UPLOAD_TABLE | UPTBL
Upload message state | Item | LR_SYNC_UPLOAD_MESSAGE | UPMSG
Upload read status state | Items | LR_SYNC_UPLOAD_MESSAGE_READ | UPREAD
Upload delete status state | Items | LR_SYNC_UPLOAD_MESSAGE_DEL | UPDEL
Download hierarchy state | Folders | LR_SYNC_DOWNLOAD_HIERARCHY | DNHIER
Download table state | Items | LR_SYNC_DOWNLOAD_TABLE | DNTBL
Download message header state | Message header | LR_SYNC_DOWNLOAD_HEADER | HDRSYNC

State Transition Diagram

The following diagram shows the state transitions that occur when uploading or performing a full synchronization (downloading followed by uploading) of folders or contents of folders (mail, calendar, contact, note, task, or journal items).

@@@@@NEED TO INSERT ART HERE THAT IS MISSING@@@@@@

Example: Uploading a Folder Hierarchy

When uploading a hierarchy of folders, the following sequence of steps takes place:

Step | Action | State | Related Data Structure
1. | The client initiates the hierarchy upload with IOSTX::SyncBeg. | LR_SYNC_UPLOAD_HIERARCHY | UPHIER
2. | Outlook 2013 or Outlook 2010 populates UPHIER with information for the client. This includes initializing the [out] parameters: iEnt is set to 0, and cEnt to the number of folders in the hierarchy that needs uploading. | LR_SYNC_UPLOAD_HIERARCHY | UPHIER
3. | The client does the actual hierarchy upload. As an example, if cEnt is 10, for each of the 10 folders, the client calls IOSTX::SyncBeg, specifying the appropriate state identifier and data structure for uploading a folder. | LR_SYNC_UPLOAD_FOLDER | UPFLD
4. | Outlook 2013 or Outlook 2010 populates UPFLD by initializing its [out] parameters, including the reason for the folder upload, the pointer to the folder object, and the entry ID for the folder. | LR_SYNC_UPLOAD_FOLDER | UPFLD
5. | The client uploads the specified folder. | LR_SYNC_UPLOAD_FOLDER | UPFLD
6. | The client notifies the local store of the completion of the folder upload: Upon success, the client sets the [in] parameter ulFlags in UPFLD with UPF_OK, and then calls IOSTX::SetSyncResult (S_OK) and IOSTX::SyncEnd. Upon failure, the client would not set ulFlags with the UPF_OK flag. It calls IOSTX::SetSyncResult, passing in the HRESULT value, and IOSTX::SyncEnd. | LR_SYNC_UPLOAD_FOLDER | UPFLD
7. | If UPF_OK is set, Outlook 2013 or Outlook 2010 will clear the internal request for uploading the folder. Then regardless of the state of ulFlags, it will clean up any internal bookkeeping information. While there are still folders in the hierarchy to upload (iEnt is still less than cEnt), the client and Outlook 2013 or Outlook 2010 repeat steps 3 through 7. | LR_SYNC_UPLOAD_FOLDER | UPFLD
8. | The client notifies the local store of the completion of the hierarchy upload: Upon success, the client sets the [in] flag in UPHIER with UPH_OK, and then calls IOSTX::SetSyncResult (S_OK) and IOSTX::SyncEnd. Upon failure, the client would not set the UPH_OK flag. It calls IOSTX::SetSyncResult, passing in the HRESULT value, and IOSTX::SyncEnd. | LR_SYNC_UPLOAD_HIERARCHY | UPHIER
9. | If UPH_OK is set, Outlook 2013 or Outlook 2010 will clear the internal request for uploading the hierarchy. Then regardless of the state of ulFlags, it will clean up any internal bookkeeping information. | LR_SYNC_UPLOAD_HIERARCHY | UPHIER

See also

Concepts

About the Replication API
MAPI Constants
SYNCSTATE


Download Hierarchy State

 Copy code hover
[image]

Download Hierarchy State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the download hierarchy state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_DOWNLOAD_HIERARCHY
Related Data Structure: | DNHIER
From this state: | Synchronize state
To this state: | Synchronize state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates downloading a tree hierarchy of folders from a server to the local store.

Outlook initializes the associated DNHIER data structure with a pointer to the hierarchy. The client downloads the hierarchy, and inserts new folders or modifications to folders in the local store. The download process adopts Microsoft Exchange Incremental Change Synchronization (ICS). For more information on ICS, see ICS Evaluation Criteria.

When this state ends, the local store returns to the synchronize state.

See also

Concepts

About the Replication API
About the Replication State Machine
SYNCSTATE


Download Message Header State

 Copy code hover
[image]

Download Message Header State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the download message header state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_DOWNLOAD_HEADER
Related Data Structure: | HDRSYNC
From this state: | Idle state
To this state: | Idle state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

During this state, the client updates the header of a message on a local store. The local store enters this state upon IOSTX::SyncHdrBeg and exits when IOSTX::SyncHdrEnd is called. During this state, Outlook initializes members of the associated HDRSYNC data structure with information about the header of a message. The client first downloads the full message item from the server and then updates the header of the message item locally.

When syncrhonization ends, the client sets the download results. The local store returns to the idle state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Download Table State

 Copy code hover
[image]

Download Table State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the download table state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_DOWNLOAD_TABLE
Related Data Structure: | DNTBL
From this state: | Synchronize contents state
To this state: | Synchronize contents state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates downloading a folder. During this state, Outlook initializes the associated DNTBL data structure with information about the folder. The client downloads the folder contents, and updates the folder on the local store with new contents, modifications, or deletions from the server. The download process adopts Microsoft Exchange Incremental Change Synchronization (ICS). For more information on ICS, see ICS Evaluation Criteria.

When this state ends, the local store returns to the synchronize contents state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Idle State

 Copy code hover
[image]

Idle State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the idle state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_IDLE
Related Data Structure: | None
From this state: | Not applicable
To this state: | Synchronize state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

Nothing happens in this state. A local store is in this state before replication is initiated and after replication is complete.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Synchronize Contents State

 Copy code hover
[image]

Synchronize Contents State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the synchronize contents state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_CONTENTS
Related Data Structure: | SYNCCONT
From this state: | Synchronize state
To this state: | Download table state, upload table state, or synchronize state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates one of the two replication processes: uploading the contents of specified folders on a local store, or a full synchronization. In a full synchronization, for each of the specified folders, contents are uploaded first and then downloaded. Depending on the ulFlags set in the corresponding SYNC structure in the preceding synchronize state, Outlook initializes [out] members in the SYNCCONT structure to provide information about the contents.

Through the same SYNCCONT structure, the client obtains the count of the folders that have content to be uploaded or downloaded. The client will loop through each of these folders by moving the local store to the upload table state to upload a folder, or moving the local store to the download table state to download the folder.

In addition, the client obtains entry IDs for the folders requiring replication.

When this state ends, Outlook cleans up its internal information. The local store returns to the synchronize state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Synchronize State

 Copy code hover
[image]

Synchronize State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the synchronize state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC
Related Data Structure: | SYNC
From this state: | Idle state
To this state: | Download hierarchy state, synchronize contents state, upload hierarchy state, or idle state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates synchronization. A local store can transition to an upload or a download state from here. For example, a local store can move to the upload hierarchy state to upload a folder hierarchy to the server, or it can perform a full synchronization by first uploading the hierarchy and then downloading the hierarchy from the server.

During this state, Outlook initializes the associated SYNC data structure with the path to the local store, so that Outlook sees modifications during other states.

The client sets the [in] members of SYNC, which tells Outlook how to handle other states. For example, the client can set ulFlags to UPS_UPLOAD_ONLY and UPS_THESE_FOLDERS and pel to a list of entry identifiers of the folders to tell Outlook that only these folders will be uploaded. When this state ends, the local store reverts to the idle state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Delete Status State

 Copy code hover
[image]

Upload Delete Status State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload delete status state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_MESSAGE_DEL
Related Data Structure: | UPDEL
From this state: | Upload table state
To this state: | Upload table state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates updating on a server those Outlook items (mail, calendar, contact, task, note, or journal) that have been deleted in a folder on a local store specified in a preceding upload table state. During this state, Outlook initializes members in the associated UPDEL data structure with information for the items that have been deleted or moved from the folder.

The client then deletes the specified items in the folder on the server. To distinguish items that have been moved as opposed to having been deleted, the client must check the pupmov members identified in the UPDEL structure.

When this state ends, Outlook clears the internal information indicating that the item has been deleted; consequently, Outlook will no longer have a record of the item. The local store returns to the upload table state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Folder State

 Copy code hover
[image]

Upload Folder State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload folder state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_FOLDER
Related Data Structure: | UPFLD
From this state: | Upload hierarchy state
To this state: | Upload hierarchy state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates uploading a folder in a hierarchy that has been specified in a preceding upload hierarchy state. During this state, Outlook provides the folder object (if it has not been deleted) and the flags indicating the state of the folder (new, moved, modified, or deleted) as part of the corresponding UPFLD data structure. The client then uploads this information to the server.

If the upload is successful, the client sets ulFlags in UPFLD to UPF_OK. Outlook then clears its internal information about the request to upload the folder.

When the folder upload ends, the local store returns to the upload hierarchy state. Based on the UPHIER structure corresponding to the preceding upload hierarchy state, Outlook determines whether to proceed with uploading the next folder and to prepare for the next upload folder state.

Note Note

If the client needs to upload only one folder, the client can initiate the replication through the synchronize state without entering the upload hierarchy state. The client sets certain members of SYNC — ulFlags to UPS_UPLOAD_ONLY and UPS_ONE_FOLDER and feid to the folder's ID — to tell Outlook that only one folder will be uploaded.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Hierarchy State

 Copy code hover
[image]

Upload Hierarchy State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload hierarchy state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_HIERARCHY
Related Data Structure: | UPHIER
From this state: | Synchronize state
To this state: | Upload folder state, or synchronize state
Note Note

The replication state machine is a deterministic state machine. A client departing one state to another must eventually return to the former from the latter.

Description

This state initiates uploading a folder tree hierarchy that has been specified in a preceding synchronize state. Outlook determines the number of folders that have been created or modified in that hierarchy and initializes cEnt in UPHIER. Outlook also keeps a count of the number of uploaded folders with another member iEnt. To upload each of the cEnt folders, the client moves the local store into the upload folder state, returning to the upload hierarchy state when the folder upload finishes.

When the upload hierarchy state ends, the local store returns to the synchronize state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Message State

 Copy code hover
[image]

Upload Message State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload message state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_MESSAGE
Related Data Structure: | UPMSG
From this state: | Upload table state
To this state: | Upload table state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates uploading an Outlook item (mail, calendar, contact, task, note, or journal) that is new or has been moved to the current folder, or that has been modified. Outlook initializes the correpsonding UPMSG data structure with the appropriate information for the item as being added, moved, or modified.

If the item has been added or moved, the client then appropriately adds or updates the item on the server.

If the item has been modified, Outlook further specifies in the UPMSG data structure whether the modifications are in a message header (in which case the item is the message header), in the item properties, or in the item itself that requires conflict resolution. The client then updates the item on the server.

When the item upload ends, Outlook notes that the message has been uploaded, so that it will not be processed in a subsequent upload. The local store returns to the upload table state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Read Status State

 Copy code hover
[image]

Upload Read Status State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload read status state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_MESSAGE_READ
Related Data Structure: | UPREAD
From this state: | Upload table state
To this state: | Upload table state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates uploading the read status of items in a folder specified in a preceding upload table state. During this state, Outlook initializes the associated UPREAD data structure with information for those items in the folder whose read status has changed. The client then updates the read status of these items on the server as being read or unread.

When this state ends, Outlook clears the internal information about the item's read status, preventing the item's read status from being uploaded again. The local store returns to the upload table state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


Upload Table State

 Copy code hover
[image]

Upload Table State
See also Send feedback

Published: July 16, 2012

This topic describes what happens during the upload table state of the replication state machine.

Quick Info

State Identifier: | LR_SYNC_UPLOAD_TABLE
Related Data Structure: | UPTBL
From this state: | Synchronize contents state
To this state: | Upload message state, upload delete status state, upload read status state, or synchronize contents state
Note Note

The replication state machine is a deterministic state machine. A client departing from one state to another must eventually return to the former from the latter.

Description

This state initiates uploading the contents of a folder that has been specified in a preceding synchronize contents state. The folder can be a mail, calendar, contacts, tasks, notes, or journal folder. During this state, Outlook creates a list of items that have been added, modified, moved, deleted, or marked as read, and prepares the appropriate internal information for the corresponding upload message state, upload delete status state, or upload read status state.

When this state ends, Outlook marks the folder as having its contents synchronized, so that the contents will not be uploaded again until another modification is made. The local store returns to the synchronize contents state.

See also

Concepts

About the Replication API
MAPI Constants
About the Replication State Machine
SYNCSTATE


About the Store API

 Copy code hover
[image]

About the Store API
Send feedback

Published: July 16, 2012

The Store API provides miscellaneous store functionality to store providers. It provides the following defintions, data types, properties, and interfaces.

Definitions:

  • Constants for the Store API

Data types:

  • INDEX_SEARCH_PUSHER_PROCESS

  • MSCAP_SELECTOR

Named Properties:

  • ArchiveSourceSupportMask

  • CrawlSourceSupportMask

  • Display Server Folder Sizes

  • Hide Meeting Update Option

  • Make Store Type Private

  • NoFolderScan

Note Note

Store providers that do not require any of the functionality offered by these named properties can simply ignore them and not implement support in the IMAPIProp interface. Because these properties are provided starting in Microsoft Outlook 2003 Service Pack 1, adding them to a store in an earlier version of Microsoft Outlook has no effect. They are ignored if they do not exist or if their value is false.

Properties:

  • PR_ADDITIONAL_REN_ENTRYIDS

  • PR_PROVIDER_ITEMID

  • PR_PROVIDER_PARENT_ITEMID

  • PR_SEARCH_OWNER_ID

Interfaces:

  • IFolderSupport

  • IMSCapabilities

  • IProxyStoreObject

Registering Stores for Indexing

The MAPI Protocol Handler checks the Windows registry for stores that it should index for search purposes. Store providers that want to be indexed must be registered in the Windows registry. For more information about registering store providers for indexing in Outlook 2013 or Outlook 2010, see About Registering Stores for Indexing.

Indexing Stores

MAPI store providers can choose to allow the MAPI Protocol Handler to crawl and index messages in the store, or send notifications to the indexer only when there are messages to be indexed. For more information about notifications-based indexing, see About Notification-Based Store Indexing.


About Registering Stores for Indexing

 Copy code hover
[image]

About Registering Stores for Indexing
See also Send feedback

Published: July 16, 2012

This topic is specific to Instant Search in Microsoft Office Outlook 2007.

Instant Search lets you quickly find items in Outlook. It uses components of Windows Desktop Search.

The MAPI Protocol Handler checks the Windows registry for stores that it should index for search purposes. Store providers that want to be indexed must be registered in the Windows registry.

By default, Windows Desktop Search adds the following four types of store providers to the Windows registry to allow indexing:

  • Store for Personal Folders files (.PST).

  • Microsoft Exchange store, including any Offline Folder files (.ost).

  • Store for public folders.

  • Store for Microsoft Office Outlook Connector for MSN.

Third-party store providers that want to be indexed must register themselves in the Windows registry.

Note Note

Administrators and users can use a Group Policy setting to prevent Windows Desktop Search from indexing Outlook items. For more information, see Extending Windows Desktop Search.

Registry Keys

On a computer, all store providers that want to be indexed must be registered under only one of the following three registry keys in the Windows registry. The MAPI Protocol Handler looks under each of these keys in the following order:

  1. [HKLM]\Software\Policies\Microsoft\Windows\Windows Search\

  2. [HKLM]\Software\Microsoft\Windows\Windows Search\Preferences\

  3. [HKCU]\Software\Microsoft\Windows\Windows Search\Preferences\

Each value under the key corresponds to a store provider that would be indexed. The name of the value is the Globally Unique Identifier (GUID) of the store provider, which is of the type DWORD and has the hexadecimal value 0x00000001.

GUIDs for Store Providers

The MAPI property PR_MDB_PROVIDER specifies the GUID of a MAPI store. The GUIDs for the store providers that Outlook indexes are described in the following table.

Type of Store Provider | GUID | Notes
Personal Folders files (.PST) | {4154494E-BFF9-01B8-00AA-0037D96E0000} | GUID is documented in the public header file mspst.h as MSPST_UID_PROVIDER
Exchange | {C0A19454-7F29-1B10-A587-08002B2A2517} | GUID is documented in the public header file edkmdb.h as pbExchangeProviderPrimaryUserGuid
Public folders | {70fab278-f7af-cd11-9bc8-00aa002fc45a} | GUID is documented in the public header file edkmdb.h as pbExchangeProviderPublicGuid
Outlook Connector for MSN | {c34f5c97-eb05-bb4b-b199-2a7570ec7cf9} | None

See also

Concepts

About the Store API


About Notification-Based Store Indexing

 Copy code hover
[image]

About Notification-Based Store Indexing
See also Send feedback

Published: July 16, 2012

A MAPI store provider can specify whether the MAPI Protocol Handler crawls and indexes messages in the store, or whether the store sends notifications to the indexer when there are messages to be indexed. The latter is known as notification-based indexing, and a store that supports notification-based indexing is a known as a pusher store.

A store provider that supports notification-based indexing sets the STORE_PUSHER_OK flag in the PR_STORE_SUPPORT_MASK property. The MAPI Protocol Handler or a client can get the PR_STORE_SUPPORT_MASK property to determine the characteristics of the store.

Whenever there is an attachment, folder, or a message to be indexed, the store provider generates a MAPI Uniform Resource Locator (URL) identifying the object to be indexed and sends it to the indexer. This MAPI URL is encoded in Unicode and must uniquely identify the object to the MAPI Protocol Handler. For more information about MAPI URLs, see About MAPI URLs for Notification-Based Indexing.

Because an indexer cannot always index everything before a shutdown occurs in a pusher store, the pusher store must persist what needs to be pushed. When a store provider sends a notification about an object that needs to be indexed, it specifies the notification type fnevIndexing in the ulEventType member of the NOTIFICATION structure. The info member of the NOTIFICATION structure contains an EXTENDED_NOTIFICATION structure. The store provider identifies the process in the PR_SEARCH_OWNER_ID property. It also identifies the process in the INDEX_SEARCH_PUSHER_PROCESS structure, and passes this information as part of the pbEventParameters member of the EXTENDED_NOTIFICATION structure. If the process is shut down or crashes, the MAPI Protocol Handler will be able to immediately detect that and stop indexing the pusher store.

See also

Concepts

About the Store API
MAPI Constants


About MAPI URLs for Notification-Based Indexing

 Copy code hover
[image]

About MAPI URLs for Notification-Based Indexing
See also Send feedback

Published: July 16, 2012

When a store provider notifies an indexer that an object is ready for indexing, it generates a MAPI URL that uniquely identifies the object to the MAPI Protocol Handler. MAPI URLs are encoded in Unicode, and have the following format:

Copy code Copy code
Mapi://SID/StoreDisplayName ($HashNumber)/StoreType/FolderNameA/…/FolderNameN/[EntryIDEncoded[/at=AttachIDEncoded:FileName]]

The following sections describe the various parts of a typical URL.

SID

  • The current user's security identifier.

StoreDisplayName

  • A string that specifies the display name of the user on that store.

HashNumber

  • A DWORD in hexadecimal representation that is calculated based on the store entry ID or the store mapping signature. This value is stored in the registry and will be used later to identify the store in the MAPI Protocol Handler. This number must be calculated in a way that minimizes collisions with other stores. For the algorithm that Microsoft Outlook uses to calculate the hash number, see Algorithm to Calculate the Store Hash Number.

StoreType

  • A number that identifies the type of the store that contains the object to be indexed. The possible values are as follows:

    • 0 - Default store.

    • 1 - Delegate store, used for delegate items cached locally.

    • 2 - Public folders, used for public folder favorites.

Note Note

If the store is being crawled instead of pushed, the value that is used is the character X.

FolderNameA/…/FolderNameN

  • The path from the root of the IPM_SUBTREE to the folder or message. For example, a message in the Family folder under Inbox has Inbox/Family for this parameter.

EntryIDEncoded

  • MAPI entry ID for the item encoded as a Unicode string. See the following section "Special Characters" for information about how certain special characters are encoded. For more information about the algorithm to encode the entry ID, see Algorithm to Encode Entry IDs and Attachment IDs.

    Note Note

    When viewed as text, this encoded entry ID appears as random Hangul characters or boxes in compliance with the algorithm, depending on available fonts.

AttachIDEncoded

  • Attachment ID encoded as a Unicode string. See the following section "Special Characters" for information about how certain special characters are encoded. For more information about the algorithm to encode the entry ID, see Algorithm to Encode Entry IDs and Attachment IDs.

    Note Note

    When viewed as text, this encoded entry ID appears as random Hangul characters or boxes in compliance with the algorithm, depending on available fonts.

FileName

  • Name of the attachment file, as it appears in the message.

Examples of MAPI URLs

The following are some examples of MAPI URLs.

  • MAPI URL for a folder:

    mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox - Some User ($be19928f)/2/Office

  • MAPI URL for a message:

    mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox - Some User ($484efb89)/0/Calendar/곯가가가걍걝걌곌겷걢곒갑겛개가검걟곔걙곾걤곂갠가

  • MAPI URL for an attachment:

    mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox - Some User ($484efb89)/0/Inbox/곯가가가걍걝걌곌겷걢곒갑겛개가검걟곔걙곾간곷갦가/at=겅걋각가:somefile.txt

Special Characters

Certain characters are encoded if they appear in the message or attachment. The following shows which characters are encoded in a MAPI URL:

  • % -> %25

  • / -> %2F

  • \ -> %5C

  • * -> %2A

  • ? -> %3F

Blob Associated With Each MAPI URL

When pushing a MAPI URL for an object to be indexed, a store provider also creates a binary large object (BLOB) that contains certain information for the MAPI Protocol Handler. The store provider associates this BLOB with each MAPI URL and sends it when pushing the MAPI URL to the indexer. The format of the BLOB is as follows:

Copy code Copy code
DWORD  dwVersion
DWORD  dwFlags
ULONG  cbProfileName
WCHAR  wszProfileName
ULONG  cbProviderItemID
WCHAR  wszProviderItemID

The store provider must write these values to the BLOB in the order shown. The following describes each field of the BLOB:

dwVersion

  • This is the version of the data being sent. Currently this value is 1.

dwFlags

  • Reserved for future use. Currently this value should be 0.

cbProfileName

  • The size of the profile name, in bytes. This information is useful for the MAPI Protocol Handler to know which profile to use when indexing the item.

wszProfileName

  • Null-terminated Unicode string that contains the profile name.

cbProviderItemID

  • Size of the provider item ID, in bytes. The store provider should send only the provider item ID for folders, to prevent opening additional folders to get this information.

wszProviderItemID

  • Null-terminated Unicode string with the provider item ID that uniquely identifies the item in the store.

See also

Concepts

About Notification-Based Store Indexing
MAPI Constants


Algorithm to Calculate the Store Hash Number

 Copy code hover
[image]

Algorithm to Calculate the Store Hash Number
See also Send feedback

Published: July 16, 2012

As part of a MAPI Uniform Resource Locator (URL), a store provider sends a store hash number to the MAPI Protocol Handler to identify an object that is ready for indexing. The MAPI Protocol Handler uses this store hash number to identify a store. In general, a store provider calculates the store hash number based on the store mapping signature, if the store has the PR_MAPPING_SIGNATURE property defined in the global profile section. Otherwise, the store provider uses the store entry ID. The algorithm to calculate the store hash number must minimize ambiguities identifying stores.

This topic describes an algorithm that Microsoft Office Outlook uses to calculate a store hash number based on the store mapping signature or entry ID and the store file name.

The binary blob to be encoded is the PR_ENTRYID of the store in most cases, but for cached Exchange stores, both public and private, the binary blob should be the PR_MAPPING_SIGNATURE, found in the profile.

After computing the hash for a public folder store's binary blob, but before hashing-in the OST path, the constant 0x2E505542, which represents the string ".PUB", is hashed in to assure it is unique, that is, distinct from the private store's hash.

The support code culls the relevant bits from the profile, which can be used to determine whether a store is public or private, if it's cached, and the path to the OST. To incorporate this code in a project, call the function ComputeStoreHash, which takes as its input the session pointer as well as PR_ENTRYID, PR_SERVICE_UID, and PR_MDB_PROVIDER from the message store table. The rest of the information it needs it gets from the profile. For output, this function returns the hash as computed from PR_MAPPING_SIGNATURE if the store is a cached Exchange store, or the hash as computed from PR_ENTRYID.

Note Note

The HrEmsmdbUIDFromStore support function is a Multiple Exchange Accounts-aware replacement for using pbGlobalProfileSectionGuid to open the profile section for an Exchange mailbox.

Copy code Copy code
#define PR_PROFILE_OFFLINE_STORE_PATH_A PROP_TAG(PT_STRING8, 0x6610)
#define PR_PROFILE_OFFLINE_STORE_PATH_W PROP_TAG(PT_UNICODE, 0x6610)
#define CONFIG_OST_CACHE_PRIVATE  ((ULONG)0x00000180)
#define CONFIG_OST_CACHE_PUBLIC   ((ULONG)0x00000400)
HRESULT HrEmsmdbUIDFromStore(IMAPISession* pmsess,
                             MAPIUID* puidService,
                             MAPIUID* pEmsmdbUID)
{
  if (!puidService) return MAPI_E_INVALID_PARAMETER;
  HRESULT hRes = S_OK;
  SRestriction mres = {0};
  SPropValue mval = {0};
  SRowSet* pRows = NULL;
  SRow* pRow = NULL;
  LPSERVICEADMIN spSvcAdmin = NULL;
  LPMAPITABLE spmtab = NULL;
  enum { eEntryID = 0, eSectionUid, eMax };
  static const SizedSPropTagArray(eMax, tagaCols) =
  {
    eMax,
    {
      PR_ENTRYID,
      PR_EMSMDB_SECTION_UID,
    }
  };
  hRes = pmsess->AdminServices(0, (LPSERVICEADMIN*)&spSvcAdmin);
  if (SUCCEEDED(hRes) && spSvcAdmin)
  {
    hRes = spSvcAdmin->GetMsgServiceTable(0, &spmtab);
    if (spmtab)
    {
      hRes = spmtab->SetColumns((LPSPropTagArray)&tagaCols, TBL_BATCH);
      mres.rt = RES_PROPERTY;
      mres.res.resProperty.relop = RELOP_EQ;
      mres.res.resProperty.ulPropTag = PR_SERVICE_UID;
      mres.res.resProperty.lpProp = &mval;
      mval.ulPropTag = PR_SERVICE_UID;
      mval.Value.bin.cb = sizeof(*puidService);
      mval.Value.bin.lpb = (LPBYTE)puidService;
      (void) spmtab->Restrict(&mres, 0);
      (void) spmtab->QueryRows(10, 0, &pRows);
      if (SUCCEEDED(hRes) && pRows && pRows->cRows)
      {
        pRow = &pRows->aRow[0];
        if (pEmsmdbUID && pRow)
        {
          if (PR_EMSMDB_SECTION_UID == pRow->lpProps[eSectionUid].ulPropTag &&
            pRow->lpProps[eSectionUid].Value.bin.cb == sizeof(*pEmsmdbUID))
          {
            memcpy(pEmsmdbUID, pRow->lpProps[eSectionUid].Value.bin.lpb, sizeof(*pEmsmdbUID));
          }
        }
      }
      FreeProws(pRows);
    }
    if (spmtab) spmtab->Release();
  }
  if (spSvcAdmin) spSvcAdmin->Release();
  return hRes;
} // HrEmsmdbUIDFromStore
bool FExchangePrivateStore(LPMAPIUID lpmapiuid)
{
  if (!lpmapiuid) return false;
  return IsEqualMAPIUID(lpmapiuid, (LPMAPIUID)pbExchangeProviderPrimaryUserGuid);
} // FExchangePrivateStore
bool FExchangePublicStore(LPMAPIUID lpmapiuid)
{
  if (!lpmapiuid) return false;
  return IsEqualMAPIUID(lpmapiuid, (LPMAPIUID)pbExchangeProviderPublicGuid);
} // FExchangePublicStore
DWORD ComputeHash(ULONG cbStoreEID, LPBYTE pbStoreEID, LPCSTR pszFileName, LPCWSTR pwzFileName, BOOL bPublicStore)
{
  DWORD  dwHash = 0;
  ULONG  cdw    = 0;
  DWORD* pdw    = NULL;
  ULONG  cb     = 0;
  BYTE*  pb     = NULL;
  ULONG  i      = 0;
  if (!cbStoreEID || !pbStoreEID) return dwHash;
  // Shouldn't see both of these at the same time.
  if (pszFileName && pwzFileName) return dwHash;
  // Get the Store Entry ID
  // pbStoreEID is a pointer to the Entry ID.
  // cbStoreEID is the size in bytes of the Entry ID.
  pdw = (DWORD*)pbStoreEID;
  cdw = cbStoreEID / sizeof(DWORD);
  for (i = 0; i < cdw; i++)
  {
    dwHash = (dwHash << 5) + dwHash + *pdw++;
  }
  pb = (BYTE *)pdw;
  cb = cbStoreEID % sizeof(DWORD);
  for (i = 0; i < cb; i++)
  {
    dwHash = (dwHash << 5) + dwHash + *pb++;
  }
  if (bPublicStore)
  {
    // Augment to assure it is unique, else could be same as private store.
    dwHash = (dwHash << 5) + dwHash + 0x2E505542; // this is '.PUB'
  }
  // To also include the store file name in the hash calculation,
  // pszFileName and pwzFileName are NULL terminated strings with the path and filename of the store.
  if (pwzFileName)
  {
    while (*pwzFileName)
    {
      dwHash = (dwHash << 5) + dwHash + *pwzFileName++;
    }
  }
  else if (pszFileName)
  {
    while (*pszFileName)
    {
      dwHash = (dwHash << 5) + dwHash + *pszFileName++;
    }
  }
  // dwHash now contains the hash to be used. It should be written in hex when building a URL.
  return dwHash;
} // ComputeHash
void ComputeStoreHash(LPMAPISESSION lpMAPISession, LPSBinary lpEntryID, LPSBinary lpServiceUID, LPSBinary lpProviderUID, DWORD* lpdwSigHash, DWORD* lpdwEIDHash)
{
  HRESULT hRes = S_OK;
  MAPIUID emsmdbUID = {0};
  LPPROFSECT lpProfSect = NULL;
  BOOL fPublicExchangeStore  = FExchangePublicStore((LPMAPIUID)lpProviderUID->lpb);
  BOOL fPrivateExchangeStore = FExchangePrivateStore((LPMAPIUID)lpProviderUID->lpb);
  BOOL fCached = false;
  LPSPropValue lpConfigProp = NULL;
  LPSPropValue lpPathPropA = NULL;
  LPSPropValue lpPathPropW = NULL;
  LPSPropValue lpMappingSig = NULL;
  LPSTR szPath = NULL; // Do not free.
  LPWSTR wzPath = NULL; // Do not free.
  // Get profile section.
  if (lpServiceUID)
  {
    hRes = HrEmsmdbUIDFromStore(lpMAPISession,
      (LPMAPIUID) lpServiceUID->lpb,
      &emsmdbUID);
    if (SUCCEEDED(hRes))
    {
      hRes = lpMAPISession->OpenProfileSection(&emsmdbUID, NULL, 0, &lpProfSect);
    }
  }
  if (!lpServiceUID || FAILED(hRes))
  {
    // For Outlook 2003/2007, HrEmsmdbUIDFromStore may not succeed,
    // so use pbGlobalProfileSectionGuid instead.
    hRes = lpMAPISession->OpenProfileSection((LPMAPIUID)pbGlobalProfileSectionGuid, NULL, 0, &lpProfSect);
  }
  if (lpProfSect)
  {
    hRes = HrGetOneProp(lpProfSect, PR_PROFILE_CONFIG_FLAGS, &lpConfigProp);
    if (SUCCEEDED(hRes) && PROP_TYPE(lpConfigProp->ulPropTag) != PT_ERROR)
    {
      if (fPrivateExchangeStore)
      {
        fCached = ((lpConfigProp->Value.l & CONFIG_OST_CACHE_PRIVATE) != 0);
      }
      if (fPublicExchangeStore)
      {
        fCached = ((lpConfigProp->Value.l & CONFIG_OST_CACHE_PUBLIC) == CONFIG_OST_CACHE_PUBLIC);
      }
    }
    if (fCached)
    {
      hRes = HrGetOneProp(lpProfSect, PR_PROFILE_OFFLINE_STORE_PATH_W, &lpPathPropW);
      if (FAILED(hRes))
      {
        hRes = HrGetOneProp(lpProfSect, PR_PROFILE_OFFLINE_STORE_PATH_A, &lpPathPropA);
      }
      if (SUCCEEDED(hRes))
      {
        if (lpPathPropW && lpPathPropW->Value.lpszW)
        {
          wzPath = lpPathPropW->Value.lpszW;
        }
        else if (lpPathPropA && lpPathPropA->Value.lpszA)
        {
          szPath = lpPathPropA->Value.lpszA;
        }
      }
      // If this is an Exchange store with an OST path, it's an OST, so get the mapping signature.
      if ((fPrivateExchangeStore || fPublicExchangeStore) && (wzPath || szPath))
      {
        hRes = HrGetOneProp(lpProfSect, PR_MAPPING_SIGNATURE, &lpMappingSig);
      }
    }
  }
  DWORD dwSigHash = NULL;
  if (lpMappingSig && PT_BINARY == PROP_TYPE(lpMappingSig->ulPropTag))
  {
    dwSigHash = ComputeHash(lpMappingSig->Value.bin.cb, lpMappingSig->Value.bin.lpb, NULL, NULL, fPublicExchangeStore);
  }
  DWORD dwEIDHash = ComputeHash(lpEntryID->cb, lpEntryID->lpb, szPath, wzPath, fPublicExchangeStore);
  if (lpdwSigHash) *lpdwSigHash = dwSigHash;
  if (lpdwEIDHash) *lpdwEIDHash = dwEIDHash;
  MAPIFreeBuffer(lpMappingSig);
  MAPIFreeBuffer(lpPathPropA);
  MAPIFreeBuffer(lpPathPropW);
  MAPIFreeBuffer(lpConfigProp);
  if (lpProfSect) lpProfSect->Release();
} // ComputeStoreHash
Tip Tip

The HrEmsmdbUIDFromStore function works without actually opening the store, so it is a good general purpose approach. However, if you have a pointer to the store object already, you can also retrieve the profile section GUID directly from the message store by reading the PR_EMSMDB_SECTION_UID property.

See also

Concepts

About Notification-Based Store Indexing
About MAPI URLs for Notification-Based Indexing


Algorithm to Encode Entry IDs and Attachment IDs

 Copy code hover
[image]

Algorithm to Encode Entry IDs and Attachment IDs
See also Send feedback

Published: July 16, 2012

A store provider can send as part of a MAPI Uniform Resource Locator (URL) an entry ID and an attachment ID to the MAPI Protocol Handler to identify an object that is ready for indexing. The store provider encodes the entry ID and attachment ID as Unicode strings. This topic shows an algorithm that generates a compact representation of the entry ID or attachment ID.

Copy code Copy code
const WORD kwBaseOffset = 0xAC00;  // Hangul char range (AC00-D7AF)
LPWSTR EncodeID(ULONG cbEID, LPENTRYID rgbID)
{
    ULONG   i = 0;
    LPWSTR  pwzDst = NULL;
    LPBYTE  pbSrc = NULL;
    LPWSTR  pwzIDEncoded = NULL;

    // rgbID is the item Entry ID or the attachment ID
    // cbID is the size in bytes of rgbID

    // Allocate memory for pwzIDEncoded
    pwzIDEncoded = new WCHAR[cbEID];
    if (!pwzIDEncoded) return NULL;

    for (i = 0, pbSrc = (LPBYTE)rgbID, pwzDst = pwzIDEncoded;
        i < cbEID;
        i++, pbSrc++, pwzDst++)
    {
        *pwzDst = (WCHAR) (*pbSrc + kwBaseOffset);
    }

    // Ensure NULL terminated
    *pwzDst = L'\0';

    // pwzIDEncoded now contains the entry ID encoded.
    return pwzIDEncoded;
}

See also

Concepts

About Notification-Based Store Indexing
About MAPI URLs for Notification-Based Indexing


About the MAPI-MIME Conversion API

 Copy code hover
[image]

About the MAPI-MIME Conversion API
Send feedback

Published: July 16, 2012

The MAPI-MIME Conversion API allows mail providers to convert between MIME objects and MAPI messages. It provides constant definitions, class identifiers, and interface identifiers as shown in MAPI Constants. Mail providers must cocreate an instance of IConverterSession by calling the CoCreateInstance function.


About the Attachment Security API

 Copy code hover
[image]

About the Attachment Security API
Send feedback

Published: July 16, 2012

The Attachment Security API allows Outlook solutions to discover whether an attachment is considered unsafe by Outlook and is blocked for viewing and indexing. It provides the following definitions and interface.

Definitions

  • MAPI Constants

Interface

  • IAttachmentSecurity


About MAPI Additions

 Copy code hover
[image]

About MAPI Additions
See also Send feedback

Published: July 16, 2012

MAPI additions are APIs that belong to Messaging Application Programming Interface (MAPI), such as data types, functions, and properties, that were previously not exposed and documented as part of the MAPI Programmer's Reference. They include the following definitions and properties.

Constant Definitions

Additional MAPI Constants

Data Types

  • EXCHANGE_STORE_VERSION_NUM

  • FollowUpStatus

  • Gender

  • OlFlagIcon

Functions

  • FixMAPI

Properties

The following properties are generally exposed by message objects.

  • PR_BODY_W

  • PR_CONFLICT_ITEMS

  • PR_DISPLAY_BCC_W

  • PR_DISPLAY_CC_W

  • PR_DISPLAY_TO_W

  • PR_FLAG_STATUS

  • PR_FOLLOWUP_ICON

  • PR_INETMAIL_OVERRIDE_FORMAT

  • PR_MESSAGE_CLASS_W

  • PR_MSG_EDITOR_FORMAT

  • PR_NORMALIZED_SUBJECT_W

  • PR_SENDER_ADDRTYPE_W

  • PR_SENDER_EMAIL_ADDRESS_W

  • PR_SENDER_NAME_W

  • PR_SENT_REPRESENTING_ADDRTYPE_W

  • PR_SENT_REPRESENTING_EMAIL_ADDRESS_W

  • PR_SENT_REPRESENTING_NAME_W

  • PR_SUBJECT_PREFIX_W

  • PR_SUBJECT_W

The following properties are exposed by address book contents table objects.

  • PR_DISPLAY_TYPE_EX

The following properties are exposed by address book container objects.

  • PR_EMS_AB_SERVER

  • PR_EMS_AB_SERVER_A

  • PR_EMS_AB_SERVER_W

The following properties are exposed by folder objects.

  • PR_AGING_GRANULARITY

  • PR_AGING_PERIOD

The following properties are exposed by messaging user objects.

  • PR_ASSISTANT_TELEPHONE_NUMBER_W

  • PR_ASSISTANT_W

  • PR_ATTACHMENT_CONTACTPHOTO

  • PR_BIRTHDAY

  • PR_BUSINESS_FAX_NUMBER_W

  • PR_BUSINESS_HOME_PAGE_W

  • PR_CALLBACK_TELEPHONE_NUMBER_W

  • PR_CAR_TELEPHONE_NUMBER_W

  • PR_CELLULAR_TELEPHONE_NUMBER_W

  • PR_CHILDRENS_NAMES_W

  • PR_DEPARTMENT_NAME_W

  • PR_DISPLAY_NAME_PREFIX_W

  • PR_GENDER

  • PR_GENERATION_W

  • PR_GIVEN_NAME_W

  • PR_HOBBIES_W

  • PR_HOME_ADDRESS_CITY_W

  • PR_HOME_ADDRESS_COUNTRY_W

  • PR_HOME_ADDRESS_POST_OFFICE_BOX_W

  • PR_HOME_ADDRESS_POSTAL_CODE_W

  • PR_HOME_ADDRESS_STATE_OR_PROVINCE_W

  • PR_HOME_ADDRESS_STREET_W

  • PR_HOME_FAX_NUMBER_W

  • PR_HOME_TELEPHONE_NUMBER_W

  • PR_KEYWORD_W

  • PR_MANAGER_NAME_W

  • PR_MIDDLE_NAME_W

  • PR_NICKNAME_W

  • PR_OFFICE_LOCATION_W

  • PR_OFFICE_TELEPHONE_NUMBER_W

  • PR_OTHER_ADDRESS_CITY_W

  • PR_OTHER_ADDRESS_COUNTRY_W

  • PR_OTHER_ADDRESS_POST_OFFICE_BOX_W

  • PR_OTHER_ADDRESS_POSTAL_CODE_W

  • PR_OTHER_ADDRESS_STATE_OR_PROVINCE_W

  • PR_OTHER_ADDRESS_STREET_W

  • PR_PAGER_TELEPHONE_NUMBER_W

  • PR_PERSONAL_HOME_PAGE_W

  • PR_PRIMARY_TELEPHONE_NUMBER_W

  • PR_PROFESSION_W

  • PR_SPOUSE_NAME_W

  • PR_SURNAME_W

  • PR_TITLE_W

  • PR_TTYTDD_PHONE_NUMBER_W

  • PR_WEDDING_ANNIVERSARY

The following properties are exposed by profile section objects.

  • PR_PROFILE_SERVER_FULL_VERSION

  • PR_PROFILE_SERVER_VERSION

  • PR_PROVIDER_DISPLAY_NAME_W

  • PR_PROVIDER_ICON_W

  • PR_ROH_FLAGS

  • PR_ROH_PROXY_AUTH_SCHEME

  • PR_ROH_PROXY_PRINCIPAL_NAME

  • PR_ROH_PROXY_SERVER

The following properties are exposed by store objects.

  • PR_IPM_APPOINTMENT_ENTRYID

  • PR_IPM_CONTACT_ENTRYID

  • PR_IPM_DRAFTS_ENTRYID

  • PR_IPM_JOURNAL_ENTRYID

  • PR_IPM_NOTE_ENTRYID

  • PR_IPM_TASK_ENTRYID

The following properties are exposed by store objects and are used in searching specific elements of an e-mail on the store.

  • PR_SEARCH_ATTACHMENTS_W

  • PR_SEARCH_RECIP_EMAIL_BCC_W

  • PR_SEARCH_RECIP_EMAIL_CC_W

  • PR_SEARCH_RECIP_EMAIL_TO_W

See also

Concepts

How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Detect the Version of Exchange Server in an Outlook Profile
How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode


About Named Properties Used by Outlook

 Copy code hover
[image]

About Named Properties Used by Outlook
See also Send feedback

Published: July 16, 2012

MAPI provides a facility for assigning names to certain properties, for mapping these names to unique identifiers, and for making this name-to-identifier mapping persistent across sessions. Named properties are identified by a name and a globally unique identifier (GUID) for a property set. The name can be a number or a string. For Microsoft Outlook 2013 or Microsoft Outlook 2010, the property set is often a namespace defined by Outlook 2013 or Outlook 2010, such as PSETID_Appointment.

Named properties are manipulated by using the IMAPIProp::GetIDsFromNames function and the IMAPIProp::GetNamesFromIDs function. The name and the property set GUID are passed to the IMAPIProp::GetIDsFromNames function to obtain a property identifier that is valid for the current MAPI session. Because this property identifier can vary from computer to computer, the only consistent way to access a named property is to know its name and property set GUID. The range for identifiers is always in the 0x8000 and 0xFFFE range.

Any object that implements the IMAPIProp : IUnknown interface can support named properties. Specifically, a MAPI service provider or a MAPI client must implement IMAPIProp::GetProps to get values of named properties. Setting named properties used by Outlook 2013 or Outlook 2010 is not supported because of the risk of corrupting data that is shared with other MAPI providers or clients.

Outlook 2013 and Outlook 2010 use MAPI named properties to implement many of their features, for example, attachment security and meeting counter-proposals. Above this underlying data, Outlook 2013 and Outlook 2010 expose some of these properties as item properties in their Outlook 2013 and Outlook 2010 object models. For example, the Email1Address property of the ContactItem object in the object model corresponds to the named PidLidEmail1EmailAddress Canonical Property in the PSETID_Address namespace. But in general, due to concerns for compatibility and data integrity, many of the MAPI properties that are used by Outlook 2013 and Outlook 2010 are not exposed in the object model.

This reference describes a number of named properties that are listed below.

Named properties in the PSETID_Address namespace are the following:

  • PidLidEmail1AddressType Canonical Property

  • PidLidEmail1EmailAddress Canonical Property

  • PidLidEmail1OriginalEntryId Canonical Property

  • PidLidEmail2AddressType Canonical Property

  • PidLidEmail2DisplayName Canonical Property

  • PidLidEmail2EmailAddress Canonical Property

  • PidLidEmail2OriginalDisplayName Canonical Property

  • PidLidEmail2OriginalEntryId Canonical Property

  • PidLidEmail3AddressType Canonical Property

  • PidLidEmail3DisplayName Canonical Property

  • PidLidEmail3EmailAddress Canonical Property

  • PidLidEmail3OriginalDisplayName Canonical Property

  • PidLidEmail3OriginalEntryId Canonical Property

  • PidLidEmail1DisplayName Canonical Property

  • PidLidEmail1OriginalDisplayName Canonical Property

  • PidLidFileUnder Canonical Property

  • PidLidInstantMessagingAddress Canonical Property

  • PidLidWorkAddressCity Canonical Property

  • PidLidWorkAddressCountry Canonical Property

  • PidLidWorkAddressPostalCode Canonical Property

  • PidLidWorkAddressPostOfficeBox Canonical Property

  • PidLidWorkAddressState Canonical Property

  • PidLidWorkAddressStreet Canonical Property

  • PidLidYomiCompanyName Canonical Property

  • PidLidYomiFirstName Canonical Property

  • PidLidYomiLastName Canonical Property

Named properties in the PSETID_Appointment namespace are the following:

  • PidLidAllAttendeesString Canonical Property

  • PidLidAppointmentCounterProposal Canonical Property

  • PidLidAppointmentDuration Canonical Property

  • PidLidAppointmentEndWhole Canonical Property

  • PidLidAppointmentStartWhole Canonical Property

  • PidLidBusyStatus Canonical Property

  • PidLidCcAttendeesString Canonical Property

  • PidLidLocation Canonical Property

  • PidLidRecurring Canonical Property

  • PidLidToAttendeesString Canonical Property

Named properties in the PSETID_Common namespace are the following:

  • PidLidCommonEnd Canonical Property

  • PidLidCommonStart Canonical Property

  • PidLidCompanies Canonical Property

  • PidLidContacts Canonical Property

  • PidLidCustomFlag Canonical Property

  • PidLidFormPropStream Canonical Property

  • PidLidFormStorage Canonical Property

  • PidLidHeaderItem Canonical Property

  • PidLidPageDirStream Canonical Property

  • PidLidPropertyDefinitionStream Canonical Property

  • PidLidReminderSet Canonical Property

  • PidLidReminderTime Canonical Property

  • PidLidFlagRequest Canonical Property

  • PidLidScriptStream Canonical Property

  • PidLidSmartNoAttach Canonical Property

  • PidLidToDoTitle Canonical Property

  • PidLidUseTnef Canonical Property

Named properties in the PSETID_Meeting namespace are the following:

  • PidLidMeetingType Canonical Property

Named properties in the PSETID_Task namespace are the following:

  • PidLidTaskActualEffort Canonical Property

  • PidLidTaskDueDate Canonical Property

  • PidLidTaskEstimatedEffort Canonical Property

  • PidLidTaskFRecurring Canonical Property

  • PidLidTaskStartDate Canonical Property

  • PidLidTaskStatus Canonical Property

Named properties in the PS_INTERNET_HEADERS namespace are the following:

  • PidTagInternetReturnPath Canonical Property

Named properties in the PSETID_Log namespace are the following:

  • PidLidLogDuration Canonical Property

  • PidLidLogEnd Canonical Property

  • PidLidLogStart Canonical Property

  • PidLidLogType Canonical Property

Named properties in the PS_PUBLIC_STRINGS namespace are the following:

  • PidNameKeywords Canonical Property

  • PidNameExchangeJunkEmailMoveStamp Canonical Property

See also

Concepts

MAPI Constants
How to: Determine if Outlook Downloaded Only the Header of a Message
How to: Get the Email Address of a Contact Item
How to: Remove Custom Form Definition Saved With a Message


MAPI Application Development

 Copy code hover
[image]

MAPI Application Development
Send feedback

Published: July 16, 2012

The topics in this section apply to developers of client applications and service providers. These topics are arranged in order of importance. That is, topics that are critical to all programmers appear first and topics that are either of minimal importance or do not apply to all programmers appear last.


MAPI Programming Overview

 Copy code hover
[image]

MAPI Programming Overview
Send feedback

Published: July 16, 2012

This Microsoft Outlook Messaging API (MAPI) Reference is written for C and C++ developers with a variety of needs and experience with messaging. For those developers who want to use MAPI to augment their applications that have messaging features, no specific prerequisite knowledge is required. You need a background in messaging and the Component Object Model (COM) to use MAPI to create full-scale workgroup applications or drivers for specialized messaging system services.

Before starting development work, you should consider the following information about how to use MAPI, the logon process, and how profiles and message services are created and configured.

The Messaging Application Program Interface (MAPI) is an extensive set of functions that developers can use to create mail-enabled applications. The full function library is known as MAPI. MAPI enables complete control over the messaging system on the client computer, creation and management of messages, management of the client mailbox, service providers, and so on.

Note Note

Extended MAPI is the same as MAPI, and is simply referred to as MAPI in the MAPI documentation.

Simple MAPI

Simple MAPI provides a set of functions that enables you to add a basic level of messaging functionality to Microsoft Windows-based applications.

Important note Important

The Simple MAPI function MAPISendMail is supported by Microsoft Outlook 2013 and Microsoft Outlook 2010. Other Simple MAPI functions have been deprecated in Windows.


Installing the MAPI Subsystem

 Copy code hover
[image]

Installing the MAPI Subsystem
See also Send feedback

Published: July 16, 2012

Supported versions of Windows install the MAPI stub library, Mapi32.dll, in the <drive>\Windows\System32 folder.

The supported versions of Windows are as follows:

  • Windows 7.

  • Windows Vista.

  • Windows Server 2008.

  • Windows Server 2003.

  • Windows XP.

To correctly install the MAPI subsystem, install an application that contains a MAPI-based subsystem, such as Microsoft Outlook.

You can find information about a computer's MAPI subsystem installation in the system registry. All values in the registry entries are character strings.

Message service installation programs are responsible for creating the installation information in the following system registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Messaging Subsystem

Message services must add entries to the system registry.

The following table summarizes how clients retrieve version information for the MAPI subsystem on their computer.

To check | Registry
Availability of MAPI | Look for MAPIX=1.
Available version of MAPI | Look for a MAPIXVER string of the form "x.x.x".

See also

Concepts

MAPI Programming Overview


How to: Install MAPI Header Files

 Copy code hover
[image]

How to: Install MAPI Header Files
See also Send feedback

Published: July 16, 2012

This topic describes how to obtain and install MAPI header files and library files.

MAPI Header Files

MAPI header files are available as a download at Outlook 2010: MAPI Header Files. By default, MAPI header files are installed in the following folder: C:\Program Files\Microsoft SDKs\Office\14.0\Include.

For a list of MAPI header files, see Commonly Used Header Files.

See also

Concepts

MAPI Programming Overview
How to: Link to MAPI Functions
Commonly Used Header Files


How to: Link to MAPI Functions

 Copy code hover
[image]

How to: Link to MAPI Functions
See also Send feedback

Published: July 16, 2012

There are three methods of linking: implicit linking, explicit linking, and a new hybrid model using the MAPI Stub Library.

Implicit Linking

Historically, calling MAPI functions in a messaging application always involved linking to the Mapi32.lib library. This included routing MAPI calls to the Windows MAPI stub library, Mapi32.dll, which then forwarded the calls to the default MAPI client implementation at run time. This call process is known as implicit linking. The left side of the following figure shows an example of implicit linking used in a MAPI function call process. The process is initiated by a MAPI application and involves the MAPI library (Mapi32.lib) and the Windows MAPI stub (Mapi32.dll) and is completed by the Outlook MAPI client implementation of the MAPI stub (Msmapi32.dll).

Comparison of implicit and explicit linking.

Comparison of implicit and explicit linking

Explicit Linking

Because the default MAPI client supports on-demand installation using the Windows Installer (MSI), you can develop messaging applications directly on the Outlook MAPI stub instead of using the MAPI library and Windows MAPI stub. The right side of the previous figure shows an example of a MAPI function call process, starting with a MAPI application looking for the path and DLL name for the Outlook MAPI stub (step 2 in the following section), and making function calls into the Outlook MAPI stub (step 3 in the following section). The following procedure shows how to call MAPI functions by using explicit linking.

Note Note

This information about explicit linking may be superfluous to your needs with the introduction of the MAPIStubLibrary.lib discussed in the following section. Like the implicit model, the new library manages everything and implements the explicit linking logic that loads Outlook's MAPI directly.

For more information about explicit linking, see Linking Explicitly.

To call MAPI API elements without the MAPI library and the Windows MAPI stub

  1. In your program file, create a global list of function pointers for each MAPI API element that you are using.

    The following example shows this step.

    C++ Copy code Copy code
    //Global MAPI function pointers
LPMAPIINITIALIZE pfnMAPIInitialize = NULL;
LPMAPIUNINITIALIZE pfnMAPIUninitialize = NULL;

  2. Create a function that initializes MAPI functions to link to the MAPI DLL of the default MAPI client (for example, Msmapi32.dll of Microsoft Outlook). In this function, do the following:

    1. Load mapi32.dll from the appropriate system directory.

      x64 or x86 natively

      %windir%\system32\mapi32.dll

      x86 on WoW mode

      %windir%\syswow64\mapi32.dll

    2. Call the FGetComponentPath function to get the path and DLL name that implements the MAPI subsystem. For more information, see How to: Choose a Specific Version of MAPI to Load.

    3. Load the DLL by calling the LoadLibrary function.

    4. Initialize the MAPI function pointer array by calling the GetProcAddress function.

    The following example shows the previous steps:

    C++ Copy code Copy code
    void InitializeMapiFunctions()
{
    // Get the DLL path and name of the actual MAPI implementation.
    FGetComponentPath(g_szMapiComponentGUID, NULL, szMAPIDLL, MAX_PATH);

    // Load the DLL.
    hMod = LoadLibrary(szMAPIDLL);

    // Initialize MAPI functions.
    pfnMAPIInitialize = GetProcAddress(hMod, "MAPIInitialize");
    pfnMAPIUninitialize = GetProcAddress(hMod, "MAPIUninitialize");
}

  3. Finally, call the function that you created in step 2 in your messaging application before you make calls to MAPI API elements.

    Caution note Caution

    You must uninitialize the MAPI subsystem before closing your application.

    The following example shows this step:

    C++ Copy code Copy code
    int main()
{
    HRESULT hr;

    InitializeMapiFunctions();

    // Initialize the MAPI subsystem.
    hr = (*pfnMAPIInitialize)(NULL);
    if (hr!= S_OK)
    {
        // Handle the error case.
    }
    // Here is where you make calls to other MAPI interfaces.

    // Uninitialize the MAPI subsystem.
    (*pfnMAPIUninitialize)();
return (0);
}

MAPIStubLibrary.lib

The advent of Microsoft Outlook 2010 and 64-bit MAPI, now extending to the Microsoft Outlook 2013, requires more than the traditional 32-bit API for full implementation. A new project, the MAPI Stub Library, posted on the CodePlex website provides a drop-in replacement for Mapi32.lib that supports building both 32-bit and 64-bit MAPI applications. MAPIStubLibrary.lib eliminates the need to explicitly link to MAPI, and having built it, you can remove Mapi32.lib from your linker settings, replacing it with MAPIStubLibrary.lib; no further modifications to your code should be needed. It also eliminates the need to write LoadLibrary, GetProcAddress, and FreeLibrary code to handle newer exports included in this library file but not in Mapi32.lib, which would be needed if you used explicit linking.

Some of the new functions linked from this library that are not available in Mapi32.lib include the following:

  • GetDefCachedMode

  • HrGetGALFromEmsmdbUID

  • HrOpenOfflineObj

  • MAPICrashRecovery

  • OpenStreamOnFileW

  • WrapCompressedRTFStreamEx

An alternate method of incorporating the MAPI Stub Library is to copy the source files, MapiStubLibrary.cpp and StubUtils.cpp, directly into your project and remove any linkage to Mapi32.lib and any code that explicitly links to MAPI.

To access the MAPI Stub Library files and for information about how to build and integrate it into your project, as well as questions about this library such as when and why to use it, see the MAPI Stub Library on the CodePlex site.

See also

Concepts

MAPI Programming Overview
Installing the MAPI Subsystem
How to: Install MAPI Header Files
How to: Choose a Specific Version of MAPI to Load

Other resources

Determining Which Linking Method to Use
Linking an Executable to a DLL
Setting Up the MSI Keys for Your MAPI DLL


How to: Choose a Specific Version of MAPI to Load

 Copy code hover
[image]

How to: Choose a Specific Version of MAPI to Load
See also Send feedback

Published: July 16, 2012

When linking explicitly to an implementation of MAPI, you must carefully select which implementation to load.

There are two methods to link explicitly to an implementation of MAPI.

  1. You can load the MAPI stub library, and specify in the registry a custom DLL to load and dispatch MAPI calls to.

  2. You can implement the MAPI client lookup algorithm to look up the version of MAPI used by the default mail client and load it.

Because you can change the Mapi32.dll Stub Registry Settings to direct your application to use any implementation of MAPI, we recommend that you direct your application to use an implementation of MAPI that you have tested with. The following describes both methods of linking explicitly.

Reading from the Registry

To Read MAPI Implementation Information from the Registry

  1. The registry keys that indicate a custom DLL for a mail client are located under the HKLM\Software\Clients\Mail key of the mail client.

    The following table describes these keys:

    Key

    Description

    MSIComponentID

    A Windows Installer PublishComponent category ID (GUID) that identifies the DLL that exports simple MAPI or MAPI calls. If set, this key takes precedence over the DLLPath or DLLPathEx key.

    MSIApplicationLCID

    Locale identifier (LCID) for your application. The first string value identifies a sub-key from HKLM\Software and subsequent string values identify registry values underneath this key that contain locale information.

    MSIOfficeLCID

    LCIDs for Microsoft Office. The first string value identifies a sub-key from HKLM\Software and subsequent string values identify registry values underneath this key.

    Obtain the information from these keys.

  2. Pass the values that you obtained from the previous step to the FGetComponentPath function. FGetComponentPath is a function that is exported by the MAPI stub library Mapistub.dll. It returns the path of the custom version of MAPI.

To Load the Implementation of MAPI Marked as Default

  1. Read the HKLM\Software\Clients\Mail::(default) registry value.

  2. Look up the information for the indicated client as described earlier.

Note Note

Note that the default mail client might not implement Extended MAPI.

Example

To load MAPI as implemented by Outlook, look up the registry keys under HKLM\Software\Clients\Mail\Microsoft Outlook and pass them to FGetComponentPath. FGetComponentPath will return the path for Outlook's implementation of MAPI.

If the keys MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID are not set, check the DLLPathEx registry value. If the keys are set, FGetComponentPath gives the path of the client's implementation of MAPI.

Implementing the MAPI Client Lookup Algorithm

The following table lists the four functions from MFCMAPI that are used to look up the path for a custom implementation of MAPI:

Function | Description
GetMAPIPath | Gets the MAPI library path.
GetMailKey | Gets the MAPI mail registry key.
GetMapiMsiIds | Gets the Windows Installer identifier.
GetComponentPath | Gets the component path using FGetComponentPath.

Because MFCMAPI loads the default implementation of MAPI by default, if you want to use a different implementation of MAPI, you must explicitly direct it to do so. This is performed by using the Session\Load MAPI routine.

The following steps describe how these functions work:

  1. MFCMAPI calls GetMAPIPath, passing NULL for the client parameter, to load the default MAPI implementation.

  2. GetMAPIPath calls GetMapiMsiIds to read the values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID.

  3. GetMapiMsiIds calls GetMailKey to open the registry key for the default mail client.

  4. GetMapiMsiIds uses the registry handle returned by GetMailKey to look up values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID.

  5. The values for MSIComponentID, MSIApplicationLCID, and MSIOfficeLCID, are returned to GetMAPIPath. GetMAPIPath then passes them to GetComponentPath.

  6. GetComponentPath loads the MAPI stub library, Mapi32.dll, from the system directory.

  7. GetComponentPath then retrieves the address of the FGetComponentPath function from Mapi32.dll, assuming that Mapi32.dll exports FGetComponentPath.

  8. If getting the address of FGetComponentPath from Mapi32.dll fails, GetComponentPath retrieves the address from Mapistub.dll.

  9. GetComponentPath then calls FGetComponentPath, obtaining the path of the default version of MAPI.

  10. GetMAPIPath then returns this path to the caller, which then loads MAPI and explicitly links to it as described in How to: Link to MAPI Functions.

Notes

  • To support localized copies of MAPI for English and non-English locales, GetMAPIPath reads the values for the MSIApplicationLCID and MSIOfficeLCID subkeys. GetMAPIPath then calls FGetComponentPath, first specifying MSIApplicationLCID as szQualifier, and again specifying MSIOfficeLCID as szQualifier.

    For more information about registry keys for mail clients that support non-English languages, see Setting Up the MSI Keys for Your MAPI DLL.

  • If MFCMAPI does not receive a path for MAPI using GetMAPIPath, it loads the MAPI stub library from the system directory.

  • The MSMapiApps registry value discussed in Explicitly Mapping MAPI Calls to MAPI DLLs only applies when the MAPI Stub library is used. Applications that load a specific implementation of MAPI or load the default implementation do not have to set the MSMapiApps registry key.

See also

Reference

FGetComponentPath

Concepts

MAPI Programming Overview
How to: Link to MAPI Functions

Other resources

Mapi32.dll Stub Registry Settings
Setting Up the MSI Keys for Your MAPI DLL
Explicitly Mapping MAPI Calls to MAPI DLLs


How to: Check the Version of Outlook

 Copy code hover
[image]

How to: Check the Version of Outlook
See also Send feedback

Published: July 16, 2012

This topic provides a code sample that checks version information of installed versions of Microsoft Outlook if the installed version is Microsoft Outlook 2013, Microsoft Outlook 2010, Microsoft Office Outlook 2007, or Microsoft Outlook 2003. Checking the version of Outlook is sometimes necessary to ensure that a MAPI application calls API elements that are supported by the currently running version of Outlook.

The following code sample, PrintOutlookVersionString, obtains full version strings by using the MsiProvideQualifiedComponent and MsiGetFileVersion functions, as declared in the Msi.h file in the Microsoft Windows Software Development Kit (SDK). PrintOutlookVersionString also returns a pointer to a Boolean variable that indicates whether a 64-bit version of Outlook is installed. For information about the expected values for the different parts of a version string for some released versions of Outlook, see How to determine Outlook version information.

C++ Copy code Copy code
void PrintOutlookVersionString()
{
TCHAR pszOutlookQualifiedComponents[][MAX_PATH] = {
TEXT("{E83B4360-C208-4325-9504-0D23003A74A5}"), // Outlook 2013
TEXT("{1E77DE88-BCAB-4C37-B9E5-073AF52DFD7A}"), // Outlook 2010
TEXT("{24AAE126-0911-478F-A019-07B875EB9996}"), // Outlook 2007
TEXT("{BC174BAD-2F53-4855-A1D5-0D575C19B1EA}")  // Outlook 2003
};
int nOutlookQualifiedComponents = _countof(pszOutlookQualifiedComponents);
int i = 0;
UINT ret = 0;

for (i = 0; i < nOutlookQualifiedComponents; i++)
{
DWORD dwValueBuf = 0;
LPTSTR pszTempPath = NULL;
LPTSTR pszTempVer = NULL;
bool b64 = false;

ret = pfnMsiProvideQualifiedComponent(
pszOutlookQualifiedComponents[i],
TEXT("outlook.x64.exe"),
(DWORD) INSTALLMODE_DEFAULT,
NULL,
&dwValueBuf);
if (ERROR_SUCCESS == ret)
{
b64 = true;
}
else
{
ret = pfnMsiProvideQualifiedComponent(
pszOutlookQualifiedComponents[i],
TEXT("outlook.exe"),
(DWORD) INSTALLMODE_DEFAULT,
NULL,
&dwValueBuf);
if (ERROR_SUCCESS == ret)
{
b64 = false;
}
}

if (ret == ERROR_SUCCESS)
{
dwValueBuf += 1;
pszTempPath = (LPTSTR) malloc(dwValueBuf * sizeof(TCHAR));
if (pszTempPath != NULL)
{
if (ERROR_SUCCESS == pfnMsiProvideQualifiedComponent(
pszOutlookQualifiedComponents[i],
TEXT("outlook.exe"),
(DWORD) INSTALLMODE_EXISTING,
pszTempPath,
&dwValueBuf))
{
pszTempVer = (LPTSTR) malloc(MAX_PATH * sizeof(TCHAR));
dwValueBuf = MAX_PATH;
if (ERROR_SUCCESS == pfnMsiGetFileVersion(pszTempPath,
pszTempVer,
&dwValueBuf,
NULL,
NULL))
{
printf("Path: %s\nVersion: %s\n64 bit: %s\n", pszTempPath, pszTempVer, b64?_T("true"):_T("false"));
}
}
}
free(pszTempVer);
free(pszTempPath);
}
}
}HRESULT GetOutlookVersionString(LPTSTR* ppszVer, BOOL* pf64Bit)
{
    HRESULT hr = E_FAIL;
    LPTSTR pszTempPath = NULL;
    LPTSTR pszTempVer = NULL;
    TCHAR pszOutlookQualifiedComponents[][MAX_PATH] = {
        TEXT("{E83B4360-C208-4325-9504-0D23003A74A5}"), // Outlook 2013
        TEXT("{1E77DE88-BCAB-4C37-B9E5-073AF52DFD7A}"), // Outlook 2010
        TEXT("{24AAE126-0911-478F-A019-07B875EB9996}"), // Outlook 2007
        TEXT("{BC174BAD-2F53-4855-A1D5-0D575C19B1EA}")  // Outlook 2003
    };
    int nOutlookQualifiedComponents = _countof(pszOutlookQualifiedComponents);
    int i = 0;
    DWORD dwValueBuf = 0;
    UINT ret = 0;

    *pf64Bit = FALSE;

    for (i = 0; i < nOutlookQualifiedComponents; i++)
    {
        ret = MsiProvideQualifiedComponent(
            pszOutlookQualifiedComponents[i],
            TEXT("outlook.x64.exe"),
            (DWORD) INSTALLMODE_DEFAULT,
            NULL,
            &dwValueBuf);
        if (ERROR_SUCCESS == ret) break;
    }

    if (ret != ERROR_SUCCESS)
    {
        for (i = 0; i < nOutlookQualifiedComponents; i++)
        {
            ret = MsiProvideQualifiedComponent(
                pszOutlookQualifiedComponents[i],
                TEXT("outlook.exe"),
                (DWORD) INSTALLMODE_DEFAULT,
                NULL,
                &dwValueBuf);
            if (ERROR_SUCCESS == ret) break;
        }
    }
    else
    {
        *pf64Bit = TRUE;
    }

    if (ret == ERROR_SUCCESS)
    {
        dwValueBuf += 1;
        pszTempPath = (LPTSTR) malloc(dwValueBuf * sizeof(TCHAR));
        if (pszTempPath != NULL)
        {
            if ((ret = MsiProvideQualifiedComponent(
                pszOutlookQualifiedComponents[i],
                TEXT("outlook.exe"),
                (DWORD) INSTALLMODE_EXISTING,
                pszTempPath,
                &dwValueBuf)) != ERROR_SUCCESS)
            {
                goto Error;
            }

            pszTempVer = (LPTSTR) malloc(MAX_PATH * sizeof(TCHAR));
            dwValueBuf = MAX_PATH;
            if ((ret = MsiGetFileVersion(pszTempPath,
                pszTempVer,
                &dwValueBuf,
                NULL,
                NULL))!= ERROR_SUCCESS)
            {
                goto Error;
            }
            *ppszVer = pszTempVer;
            pszTempVer = NULL;
            hr = S_OK;
        }
    }

Error:
    free(pszTempVer);
    free(pszTempPath);
    return hr;
}

See also

Concepts

MAPI Programming Overview


Testing and Debugging

 Copy code hover
[image]

Testing and Debugging
See also Send feedback

Published: July 16, 2012

Testing strategies differ depending on whether you are developing a client or service provider. Because a client application requires one or more service providers to operate, clients should be tested in an environment with different sets of service providers.

Service providers, however, should be tested in isolation before being integrated with other providers. MAPI provides tools that are meant to test the features of a service provider of a particular type. The MFCMAPI sample application shows how to test the features of an address book provider and works with a message store provider.

See also

Concepts

MAPI Programming Overview
MFCMAPI as a Code Sample


MAPI Sessions

 Copy code hover
[image]

MAPI Sessions
See also Send feedback

Published: July 16, 2012

Before the client application can call an underlying messaging system, it must establish a session, or connection, with the MAPI subsystem.

Sessions are initiated when a user logs on, a process that accesses a valid profile and validates the messaging system and the message service credentials. Then, the process ensures that all of the profile's message services are correctly configured. The client interface you use determines the logon call. MAPI clients call the MAPILogonEx function.

Message service configuration is one of the most important parts of the logon process. The profile is the initial source for configuration information. If information for a particular message service is missing, the logon process tries to prompt the user to supply it. This is not always successful for two reasons: First, prompting the user requires the display of a dialog box. It is possible for clients to disallow the display of a user interface by passing a flag into the logon call. Second, the user could cancel the dialog box before the needed information can be added.

When a logon process fails one time, the user is informed of the failure and given the chance to retry or correct the error condition. Once again, a user interface will be displayed, if the client allows it, and the user will be prompted to enter whatever data is missing. If this second try is unsuccessful, MAPI disables all service providers in the message service for the duration of the session. In effect, the whole message service is disabled. This means that none of the service providers in the message service can work. This is done because if one provider fails logon, the other providers usually also fail. The logon process can fail due to an invalid path for a necessary resource, an incompatible version of MAPI, an unavailable messaging server, or data corruption.

Clients can specify one of two types of sessions to be established in the logon call: an individual session or a shared session. Individual sessions are private connections; there is a one-to-one relationship between a client application and the session it is using. As a consequence, client applications that share a session also share a profile. Shared sessions are established once but can be used by other client applications that need to use them. The profile and credentials are specified only with the initial logon.

Clients can log on multiple times as the same user or as multiple users. MAPI does not prevent this. Some service providers, however, might not be as flexible, returning the error value MAPI_E_SESSION_LIMIT on subsequent logon attempts. Service providers with underlying hardware limitations can be required to enforce a session limit.

The function calls for establishing a session have a collection of flags and parameters that control how the session is created. The client specifies an optional profile name and a window handle that acts as the parent window for any dialog boxes that are displayed. The flags include MAPI_NEW_SESSION, which requests that a new, individual session (rather than a shared session) be established, and the MAPI_LOGON_UI user interface flag. The user interface flag is set to request a logon dialog box.

The following illustration shows how these various parameters and flags establish a MAPI session.

MAPI session flowchart

MAPI session flowchart

For information about handling sessions from within a client application, see MAPI Session Handling

See also

Reference

MAPILogonEx
IMAPISession : IUnknown

Concepts

MAPI Session Handling
MAPI Programming Overview


Message Services and Profiles

 Copy code hover
[image]

Message Services and Profiles
See also Send feedback

Published: July 16, 2012

Some users require the services of several messaging systems, each with one or more service providers. Because it is cumbersome to install and configure each of these service providers individually, and because a messaging server usually requires a group of related providers to expose all its functionality, MAPI includes the concept of a message service. Message services help users install and configure their service providers.

To create a message service, a developer writes a message-service entry point program to handle the configuration of each provider in the service and a setup program to do the following:

  • Install each provider in the service.

  • Create registry and initialization file entries.

  • Create entries in the MAPI configuration file, Mapisvc.inf.

The Mapisvc.inf file contains information that relates to the configuration of all message services and service providers installed on the computer. It is organized in hierarchical sections, with each level linked to the next. At the top are three sections that contain the following:

  • A list of message service Help files.

  • A list of the most important, or default, message services.

  • A list of all the services on the computer.

The next level contains sections for each message service, and the last level contains sections for each service provider in a service. MAPI requires that developers of service providers and message services add certain entries to Mapisvc.inf; developers can add other entries at their own discretion. Most of the information in Mapisvc.inf ends up in one or more profiles, a collection of configuration information for a user's preferred set of message services. Because a computer can have multiple users and a single user can have multiple sets of preferences, many profiles can exist on a computer. Each profile describes a different set of message services. Having multiple profiles enables a user to work, for example, at home with one set of message services and at the office with a different set.

Profiles are created at message service installation or logon time by a client application that provides configuration support. MAPI provides two such client applications: a Control Panel item and the Profile Wizard. The Control Panel item is a full-service configuration application with which users can create, delete, edit, and copy profiles, as well as make modifications to the entries in a profile. The Profile Wizard is a simple application designed to make adding a message service to a profile as easy as possible. The Profile Wizard consists of a series of dialog boxes, called property pages, that prompt the user through the process of installing and configuring a service. The user is prompted only for values for the most critical settings; all other settings inherit default values. Once the profile has been created, users are not allowed to make changes.

Whereas the Control Panel item is always invoked through the Control Panel, there are a variety of scenarios that can cause the Profile Wizard to be called. Client applications can call the Profile Wizard to create a default profile at logon time when one has not yet been created. Rather than reimplementing code to add a profile, the Control Panel item or another client application can rely on the functionality already in the Profile Wizard. A message service, in its entry point function, can call the Profile Wizard when the service needs to be added to the default profile. Message services that use the Profile Wizard must write an extra entry point function and a standard Windows dialog box procedure. The Profile Wizard calls the entry point function to retrieve the service's configuration dialog box while the dialog box procedure handles the messages that are generated when this dialog box is in use.

Profiles are organized in a similar way to the Mapisvc.inf file. Profiles have linked hierarchical sections; service providers own sections in the lowest level, message services own sections in the middle level, and MAPI owns sections in the highest level. Each section is identified with a unique identifier known as a MAPIUID. The MAPI sections contain information internal to MAPI, such as the identifiers of all of the message service profile sections and links to each of the other sections. Each message service section stores links to its provider sections, and each provider section stores a link to its service section.

The following illustration shows the contents of two typical profiles. Sam has two profiles on his computer, one for home use and one for office use. The home profile contains three message services. Message Service X is a single provider service for address book management. Message Services Y and Z have three providers — an address book provider, a message store provider, and a transport provider. Sam's Work Profile contains two different message services, each of which has an address book provider, a message store provider, and a transport provider.

Profile example

The following illustration shows a profile that includes two message services. The code for installing and configuring the service providers that belong to the message service resides in the same DLL as the code for the providers. This code reads information from the profile at logon time to configure the service providers, and it prompts the user, if possible and necessary, for missing information. Requests from a client to view or change configuration settings for any of the providers are also handled by this common code.

Installing and configuring service providers

Installing and configuring service providers

See also

Reference

MAPIUID

Concepts

MAPI Programming Overview


Operating Environment Issues

 Copy code hover
[image]

Operating Environment Issues
See also Send feedback

Published: July 16, 2012

The issues of operating system and operating environment are important when MAPI developers choose a development environment and an environment for Windows SDK installation.

MAPI developers must be aware that these choices affect the operating system that their component will run on and the range of components that they will be able to target.

See also

Concepts

MAPI Programming Overview


Building MAPI Applications on 32-Bit and 64-Bit Platforms

 Copy code hover
[image]

Building MAPI Applications on 32-Bit and 64-Bit Platforms
See also Send feedback

Published: July 16, 2012

This topic describes the actions that MAPI developers should take to change and rebuild 32-bit MAPI applications to run on a 64-bit platform, and 64-bit applications to run on a 32-bit platform. In this topic, a 64-bit platform is a computer installed with 64-bit Microsoft Outlook and 64-bit Windows, and a 32-bit platform is a computer installed with a 32-bit Outlook and 32-bit or 64-bit Windows.

Operating System and Office Support for 64-Bit Outlook

Note Note

The term bitness refers to the distinction between 32-bit and 64-bit processor architectures and the associated compatibility of applications. In this topic, bitness is used to qualify the version of Windows, Microsoft Office, Outlook, or a MAPI application built to suit a 32-bit or 64-bit processor architecture of a computer, and possibly other applications that run on that computer.

Starting in Microsoft Office 2010, Outlook is available as a 32-bit and a 64-bit application. On the same computer, the bitness of Outlook depends on the bitness of the Windows operating system (x86 or x64), and of Microsoft Office, if Office is already installed on that computer. The following are some of the factors that determine the feasibility of installing a 32-bit or a 64-bit version of Outlook:

  • 32-bit Office (and 32-bit Outlook) can be installed on a 32-bit or 64-bit version of the Windows operating system. 64-bit Office (and 64-bit Outlook) can be installed only on a 64-bit operating system.

  • The default installation of Office on a 64-bit version of the Windows operating system is 32-bit Office.

  • The bitness of an installed version of Outlook is always the same as the bitness of Office, if Office is installed on the same computer. In other words, a 32-bit version of Outlook cannot be installed on the same computer that already has 64-bit versions of other Office applications installed, such as 64-bit Microsoft Word or 64-bit Microsoft Excel. Similarly, a 64-bit version of Outlook cannot be installed on the same computer that already has 32-bit versions of other Office applications installed.

Preparing MAPI Applications for 32-Bit and 64-Bit Platforms

MAPI applications include standalone applications such as Microsoft Communicator and MFCMAPI, and service providers such as address book, store, and transport providers. For MAPI method and function calls to work in a MAPI application (with the exception of one Simple MAPI function, MAPISendMail), the bitness of the MAPI application must be the same as the bitness of the MAPI subsystem on the computer that the application is targeted to run on. The bitness of the MAPI subsystem, in turn, is determined by and always the same as the bitness of the installed version of Outlook. The following table summarizes the necessary actions to prepare MAPI applications to run on targeted computers configured with Office and Windows of various bitness.

Bitness of MAPI application | Bitness of Outlook on targeted computer | Bitness of Windows on targeted computer | Necessary action to enable application to run on targeted computer
32-bit | 32-bit | 32-bit or 64-bit | No specific action is necessary.
32-bit | 64-bit | 64-bit | Rebuild the application as a 64-bit application. Otherwise, all MAPI method and function calls (except for MAPISendMail) will fail.
64-bit | 64-bit | 64-bit | No specific action is necessary.
64-bit | 32-bit | 32-bit or 64-bit | Rebuild the application as a 32-bit application. Otherwise, all MAPI method and function calls (except for MAPISendMail) will fail.

The following sections further explain each scenario. For scenarios that require rebuilding the MAPI application, see How to: Link to MAPI Functions for additional information regarding linking to and calling MAPI functions.

32-Bit MAPI Application and 32-Bit Outlook

MAPI applications compiled for a 32-bit MAPI subsystem that is available in 32-bit versions of Outlook, including those versions prior to Microsoft Outlook 2013, continue to be supported on computers installed with 32-bit Outlook and a 32-bit or 64-bit Windows operating system. There is no specific action necessary for the application developers.

32-bit MAPI Application and 64-Bit Outlook

32-bit MAPI applications are not supported to run on a computer installed with 64-bit Outlook and 64-bit Windows. The application developer must update and rebuild the application as a 64-bit application for the 64-bit platform. This is because a 32-bit application cannot load a 64-bit Msmapi32.dll file. There are a small number of API changes that application developers must incorporate to build their code successfully for a 64-bit environment. MAPI header files have been updated with these changes to support the 64-bit platform. You can download these header files at Outlook 2010: MAPI Header Files. Developers can use this same set of MAPI header files to build both 32-bit and 64-bit MAPI applications.

64-bit MAPI Application and 64-Bit Outlook

64-bit MAPI applications are supported on computers installed with 64-bit Outlook and 64-bit Windows. There is no specific action necessary for the application developers.

64-Bit MAPI Application and 32-Bit Outlook

64-bit MAPI applications are not supported to run on a computer installed with 32-bit Outlook and 32-bit or 64-bit Windows. The application developer must update and rebuild the application as a 32-bit application to work with 32-bit Outlook. Use the updated MAPI header files, which you can download at Outlook 2010: MAPI Header Files. Developers can use this same set of MAPI header files to build both 32-bit and 64-bit MAPI applications.

Exception: MAPISendMail

In general, a 32-bit MAPI application must not run on a 64-bit platform (64-bit Outlook on 64-bit Windows) without first being rebuilt as a 64-bit application, and a 64-bit MAPI application must not run on a computer installed with 32-bit Outlook and 32-bit or 64-bit Windows without first being rebuilt as a 32-bit application. Figure 1 shows an alert dialog box that would be displayed if either of these scenarios occurs.

Figure 1. Error message for most cross-bitness MAPI calls.

Error message for most cross-bitness MAPI calls

However, one function call among all Simple MAPI and MAPI elements, MAPISendMail, would succeed in a Windows-32-bit-on-Windows-64-bit (WOW64) or Windows-64-bit-on-Windows-32-bit (WOW32) scenario and would not result in the above alert. This WOW64 scenario only applies to Windows 7. Figure 2 shows a WOW64 scenario in which a 32-bit MAPI application calls MAPISendMail on a computer installed with 64-bit Windows 7. In this scenario, the MAPI library makes a COM call to launch a 64-bit Fixmapi application. The Fixmapi application implicitly links to the MAPI library, which routes the function call to the Windows MAPI stub, which in turn forwards the call to the Outlook MAPI stub, enabling the MAPISendMail function call to succeed.

Figure 2. Processing MAPISendMail in a WOW64 scenario.

Processing MAPISendMail in a WOW64 scenario

See also

Concepts

How to: Link to MAPI Functions


Calling MAPI from Windows Services

 Copy code hover
[image]

Calling MAPI from Windows Services
See also Send feedback

Published: July 16, 2012

To enable MAPI client applications that are written as Windows services to operate with MAPI-compliant service providers, MAPI imposes several limitations and requirements.

MAPI clients have the following limitations:

  • They cannot allow a user interface.

  • They can send messages only through a tightly coupled message store and transport provider. In addition, MAPI clients can send and receive messages by using only the Exchange Server or another server-based transport provider. Because of identity and security issues between client applications and the MAPI spooler, most transport providers are not supported in a service.

All MAPI client applications, whether they are implemented as Windows services, must call the MAPIInitialize function to initialize the MAPI libraries. A call to the OleInitialize function is also necessary to use the OLE libraries. Both MAPIInitialize and OleInitialize make calls to the CoInitialize function to initialize the Component Object Model (COM) libraries. Clients that are services must set a special flag, MAPI_NT_SERVICE, in the ulFlags member of the MAPIINIT_0 structure that is passed to MAPIInitialize and in the ulFlags parameter that is passed to the MAPILogonEx function to inform MAPI of their special implementation.

MAPI clients that are written as Windows services and written with the MAPI client interface have an additional requirement. They must set the MAPI_NO_MAIL flag in the call to MAPILogonEx. Other types of clients do not have to set a flag for logon because it is automatically set by MAPI.

To handle messages in an initialization thread, a MAPI client that is implemented as a service does the following:

  1. Calls the MsgWaitForMultipleObjects function when the main thread blocks.

  2. Calls the GetMessage, TranslateMessage, and DispatchMessage sequence of Windows functions to handle the message when MsgWaitForMultipleObjects returns the sum of the value of the nCount parameter and the value of WAIT_OBJECT_0, which indicates that a message is in the queue.

See also

Reference

MAPIInitialize
MAPIINIT_0
MAPILogonEx

Concepts

Operating Environment Issues


How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode

 Copy code hover
[image]

How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode
See also Send feedback

Published: July 16, 2012

This topic contains a code sample in C++ that shows how to use the MAPI_NO_CACHE flag to open a folder or a message on a message store on the remote server when Microsoft Office Outlook is in Cached Exchange Mode.

Cached Exchange Mode permits Outlook to use a local copy of a user's mailbox while Outlook maintains an online connection to a remote copy of the user's mailbox on the remote Exchange server. When Outlook is running in Cached Exchange Mode, by default, any MAPI solutions that log on to the same session are also connected to the cached message store. Any data that is accessed and any changes that are made are made against the local copy of the mailbox.

A client or service provider can override the connection to the local message store and open a message or a folder on the remote store by setting the bit for MAPI_NO_CACHE in the ulFlags parameter when calling IMsgStore::OpenEntry.

The following code sample shows how to call IMsgStore::OpenEntry with the MAPI_NO_CACHE flag set in the ulFlags parameter to open the root folder on the remote message store.

Copy code Copy code
HRESULT HrOpenRootFolder (
    LPMDB lpMDB,
    LPMESSAGE* lpRootFolder)
{
    ULONG ulObjType = NULL;

    HRESULT hRes = lpMDB-&gt;OpenEntry(
        0,// size of entry ID
        NULL,                                   // Pointer to entry ID
        NULL,                                   // Use default interface (IMAPIFolder)
        MAPI_BEST_ACCESS | MAPI_NO_CACHE,       // Flags
        &amp;ulObjType,
// Output parameter indicates the type of object returned
        (LPUNKNOWN *) lpRootFolder));           // Pointer to put the opened folder in
    return hRes;

}

If you opened the message store with the MDB_ONLINE flag on the remote server, you do not have to use the MAPI_NO_CACHE flag.

See also

Concepts

About MAPI Additions
How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode


How to: Detect the Version of Exchange Server in an Outlook Profile

 Copy code hover
[image]

How to: Detect the Version of Exchange Server in an Outlook Profile
Send feedback

Published: July 16, 2012

This topic includes a code sample in C++ that shows how to use the PR_PROFILE_SERVER_VERSION property and PR_PROFILE_SERVER_FULL_VERSION property to obtain version information of the Microsoft Exchange Server that the active account is connected to.

The GetProfileServiceVersion function in the code sample accepts a profile as an input parameter. Depending on whether the PR_PROFILE_SERVER_VERSION property and the PR_PROFILE_SERVER_FULL_VERSION property exist in the given profile, the function gets each property and returns the appropriate version information as output parameters.

GetProfileServiceVersion first calls the MAPIAdminProfiles function to create a profile administration object. It then uses the profile administration object to call IProfAdmin::AdminServices to obtain a message service administration object. Using the message service administration object, it calls IMsgServiceAdmin::OpenProfileSection to obtain a section of the current profile, and then calls HrGetOneProp to verify if each of the two properties exists in that section of the profile, and if so, sets the version information in the appropriate output parameters.

Copy code Copy code
TZDEFINITION* BinToTZDEFINITION(ULONG cbDef, LPBYTE lpbDef)
{
    if (!lpbDef) return NULL;

    // Update this if parsing code is changed.
    // This checks the size up to the flag member.
    if (cbDef &lt; 2*sizeof(BYTE) + 2*sizeof(WORD)) return NULL;

    TZDEFINITION tzDef = {0};
    TZRULE* lpRules = NULL;
    LPBYTE lpPtr = lpbDef;
    WORD cchKeyName = NULL;
    WCHAR* szKeyName = NULL;
    WORD i = 0;

    BYTE bMajorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);
    BYTE bMinorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);

    // We only understand TZ_BIN_VERSION_MAJOR
    if (TZ_BIN_VERSION_MAJOR != bMajorVersion) return NULL;

    // We only understand if &gt;= TZ_BIN_VERSION_MINOR
    if (TZ_BIN_VERSION_MINOR &gt; bMinorVersion) return NULL;

    lpPtr += sizeof(WORD);

    tzDef.wFlags = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);

    if (TZDEFINITION_FLAG_VALID_GUID &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(GUID)) return NULL;
        tzDef.guidTZID = *((GUID*)lpPtr);
        lpPtr += sizeof(GUID);
    }

    if (TZDEFINITION_FLAG_VALID_KEYNAME &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
        cchKeyName = *((WORD*)lpPtr);
        lpPtr += sizeof(WORD);
        if (cchKeyName)
        {
            if (lpbDef + cbDef - lpPtr &lt; (BYTE)sizeof(WORD)*cchKeyName) return NULL;
            szKeyName = (WCHAR*)lpPtr;
            lpPtr += cchKeyName*sizeof(WORD);
        }
    }

    if (lpbDef+ cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
    tzDef.cRules = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);
    if (tzDef.cRules)
    {
        lpRules = new TZRULE[tzDef.cRules];
        if (!lpRules) return NULL;

        LPBYTE lpNextRule = lpPtr;
        BOOL bRuleOK = false;


How to: Determine if Outlook Downloaded Only the Header of a Message

 Copy code hover
[image]

How to: Determine if Outlook Downloaded Only the Header of a Message
Send feedback

Published: July 16, 2012

This topic shows a code sample in Visual C++ that uses the named PidLidHeaderItem Canonical Property to determine whether Microsoft Outlook 2013 has downloaded only the header of a message or the header and the body of a message.

Copy code Copy code
BOOL bIsHeader(LPMESSAGE lpMessage)
{
    HRESULT         hRes = S_OK;
    BOOL            bRet = false;
    ULONG    ulVal = 0;
    LPSPropValue    lpPropVal = NULL;
    LPSPropTagArray lpNamedPropTag = NULL;
    MAPINAMEID      NamedID = {0};
    LPMAPINAMEID    lpNamedID = NULL;

    NamedID.lpguid = (LPGUID) &PSETID_Common;
    NamedID.ulKind = MNID_ID;
    NamedID.Kind.lID = dispidHeaderItem;
    lpNamedID = &NamedID;
    hRes = lpMessage->GetIDsFromNames(1, &lpNamedID, NULL, &lpNamedPropTag);

    if (lpNamedPropTag && 1 == lpNamedPropTag->cValues)
    {
lpNamedPropTag->aulPropTag[0] = CHANGE_PROP_TYPE(lpNamedPropTag->aulPropTag[0], PT_LONG);

//Get the value of the property.
hRes = lpMessage->GetProps(lpNamedPropTag, 0, &ulVal, &lpPropVal);
if (lpPropVal && 1 == ulVal && PT_LONG == PROP_TYPE(lpPropVal->ulPropTag) && lpPropVal->Value.ul)
{
    bRet = true;
}
    }

    MAPIFreeBuffer(lpPropVal);
    MAPIFreeBuffer(lpNamedPropTag);
    return bRet;
}


How to: Get the Email Address of a Contact Item

 Copy code hover
[image]

How to: Get the Email Address of a Contact Item
Send feedback

Published: July 16, 2012

This topic shows how to obtain the value of a named property that represents the email address of an Microsoft Outlook 2010 or Microsoft Outlook 2013 Contact item.

You can associate up to three email addresses with a Contact item in Outlook 2010 and Outlook 2013. Each email address corresponds to a property of the Outlook 2010 or Outlook 2013ContactItem object in the Outlook 2010 and Outlook 2013 object models. Internal to Outlook 2010 and Outlook 2013, the email address also corresponds to a MAPI named property. For example, the first email address of a contact corresponds to the Email1Address property of the ContactItem in the Outlook 2010 and Outlook 2013 object models, and the Outlook 2010 and Outlook 2013 internal named PidLidEmail1EmailAddress Canonical Property.

To obtain the value of an email address of a contact item, you can use the PropertyAccessor object of the Outlook 2010 or Outlook 2013 object model, or first use IMAPIProp::GetIDsFromNames to obtain the property tag of the named property, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the appropriate values for the MAPINAMEID structure pointed at by the input parameter lppPropNames. The following code sample shows how to obtain the first email address of a specified contact, lpContact, using GetIDsFromNames and GetProps.

Copy code Copy code
HRESULT HrGetEmail1(LPMESSAGE lpContact)
{
    HRESULT hRes = S_OK;
    LPSPropTagArray lpNamedPropTags = NULL;
    MAPINAMEID NamedID = {0};
    LPMAPINAMEID lpNamedID = &NamedID;
    NamedID.lpguid = (LPGUID)&PSETID_Address;
    NamedID.ulKind = MNID_ID;
    NamedID.Kind.lID = dispidEmailEmailAddress;

    hRes = lpContact->GetIDsFromNames(
           1,
           &lpNamedID,
           NULL,
           &lpNamedPropTags);

    if (SUCCEEDED(hRes) && lpNamedPropTags)
    {
        SPropTagArray sPropTagArray;

        sPropTagArray.cValues = 1;
        sPropTagArray.aulPropTag[0] = CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[0],PT_STRING8);
        LPSPropValue lpProps = NULL;
        ULONG cProps = 0;

        hRes = lpContact->GetProps(
               &sPropTagArray,
               NULL,
               &cProps,
               &lpProps);
        if (SUCCEEDED(hRes) &&
            1 == cProps &&
            lpProps &&
            PT_STRING8 == PROP_TYPE(lpProps[0].ulPropTag) &&
            lpProps[0].Value.lpszA)
        {
            printf("Email address 1 = \"%s\"\n",lpProps[0].Value.lpszA);
        }
        MAPIFreeBuffer(lpProps);
        MAPIFreeBuffer(lpNamedPropTags);
     }
     return hRes;
}


How to: Get the Path of a Specific Version of MAPI for the Default Mail Client

 Copy code hover
[image]

How to: Get the Path of a Specific Version of MAPI for the Default Mail Client
Send feedback

Published: July 16, 2012

This topic includes a code sample in C++ that shows how to obtain the path of a specific version of MAPI that is used by the default mail client on a computer. MAPI mail clients have an option to specify in the registry a custom DLL that the MAPI stub library should load and dispatch MAPI calls to. The registry key to set for this custom DLL for a default mail client is MSIComponentID, under the HKLM\Software\Clients\Mail key of the default mail client. The FGetComponentPath function, exported by the MAPI stub library, mapistub.dll, can return the path to the custom version of MAPI specified by the MSIComponentID registry key.

This code sample includes two functions: HrGetRegMultiSZValueA and GetMAPISVCPath. The GetMAPISVCPath function uses FGetComponentPath to obtain the path to the custom version of MAPI. It assumes that the default mail client is Microsoft Office Outlook 2007, and passes to FGetComponentPath the value, {FF1D0740-D227-11D1-A4B0-006008AF820E}, that Outlook 2007 sets as the component ID of MAPI for the MSIComponentID registry key.

Note Note

In practice, you should not assume the value, {FF1D0740-D227-11D1-A4B0-006008AF820E}, is always the component ID of MAPI and directly pass it to FGetComponentPath. To reliably find out which version of MAPI Outlook uses on a computer, you must read from the registry the value of MSIComponentID and pass it to FGetComponentPath.

The following steps describe how GetMAPISVCPath does this.

  1. Loads the MAPI stub library, mapistub.dll, from the system directory.

  2. Assumes that mapistub.dll exports the FGetComponentPath function, it tries to get the address of this function from mapistub.dll.

  3. If getting the address from mapistub.dll fails, it tries to get the address from mapi32.dll.

  4. If getting the address of FGetComponentPath succeeds, it opens the registry and uses the HrGetRegMultiSZValueA function to read the registry values under HKLM\Software\Clients\Mail\Microsoft Outlook.

  5. Calls FGetComponentPath, specifying the value, {FF1D0740-D227-11D1-A4B0-006008AF820E}, to obtain the path to the version of MAPI that Outlook 2007 uses.

Note that to support localized copies of MAPI for English and non-English locales, the code sample reads the values for the MSIApplicationLCID and MSIOfficeLCID subkeys and calls FGetComponentPath, first specifying MSIApplicationLCID as szQualifier, and then again specifying MSIOfficeLCID as szQualifier. For more information about registry keys for mail clients that support non-English languages, see Setting Up the MSI Keys for Your MAPI DLL.

Copy code Copy code
// HrGetRegMultiSZValueA
// Get a REG_MULTI_SZ registry value - allocating memory using new to hold it.
void HrGetRegMultiSZValueA(
    IN HKEY hKey, // the key.
    IN LPCSTR lpszValue, // value name in key.
    OUT LPVOID* lppData) // where to put the data.
{
    *lppData = NULL;
    DWORD dwKeyType = NULL;
    DWORD cb = NULL;
    LONG lRet = 0;

    // Get its size
    lRet = RegQueryValueExA(
        hKey,
        lpszValue,
        NULL,
        &amp;dwKeyType,
        NULL,
        &amp;cb);

    if (ERROR_SUCCESS == lRet &amp;&amp; cb &amp;&amp; REG_MULTI_SZ == dwKeyType)
    {
        *lppData = new BYTE[cb];

        if (*lppData)
        {
            // Get the current value
            lRet = RegQueryValueExA(
                hKey,
                lpszValue,
                NULL,
                &amp;dwKeyType,
                (unsigned char*)*lppData,
                &amp;cb);

            if (ERROR_SUCCESS != lRet)
            {
                delete[] *lppData;
                *lppData = NULL;
            }
        }
    }
}

typedef BOOL (STDAPICALLTYPE FGETCOMPONENTPATH) (
    LPSTR szComponent,
    LPSTR szQualifier,
    LPSTR szDllPath,
    DWORD cchBufferSize,
    BOOL fInstall);
typedef FGETCOMPONENTPATH FAR * LPFGETCOMPONENTPATH;

///////////////////////////////////////////////////////////////////////////////
// Function name   : GetMAPISVCPath
// Description       : This will get the correct path to the MAPISVC.INF file.
// Return type      : void
// Argument         : LPSTR szMAPIDir - Buffer to hold the path to the MAPISVC file.
//                    ULONG cchMAPIDir - size of the buffer
void GetMAPISVCPath(LPSTR szMAPIDir, ULONG cchMAPIDir)
{
    HRESULT hRes = S_OK;
    UINT uiRet = 0;
    LONG lRet = 0;
    BOOL bRet = true;

    szMAPIDir[0] = &apos;\0&apos;; // Terminate string at position 0, safer if fail below

    CHAR szSystemDir[MAX_PATH+1] = {0};

    // Get the system directory path
    // (mapistub.dll and mapi32.dll reside here)
    uiRet = GetSystemDirectoryA(szSystemDir, MAX_PATH);
    if (uiRet &gt; 0)
    {
        CHAR szDLLPath[MAX_PATH+1] = {0};

        hRes = StringCchPrintfA(szDLLPath, MAX_PATH+1, &quot;%s\\%s&quot;,
            szSystemDir, &quot;mapistub.dll&quot;);
        if (SUCCEEDED(hRes))
        {
            LPFGETCOMPONENTPATH pfnFGetComponentPath = NULL;

            HMODULE hmodStub = 0;
            HMODULE hmodMapi32 = 0;

            // Load mapistub.dll
            hmodStub = LoadLibraryA(szDLLPath);
            if (hmodStub)
            {
                // Get the address of FGetComponentPath from the mapistub
                pfnFGetComponentPath = (LPFGETCOMPONENTPATH)GetProcAddress(
                    hmodStub, &quot;FGetComponentPath&quot;);
            }

            // If failed to get the address of FGetComponentPath,
            // try mapi32.dll
            if (!pfnFGetComponentPath)
            {
                hRes = StringCchPrintfA(szDLLPath, MAX_PATH+1, &quot;%s\\%s&quot;,
                    szSystemDir, &quot;mapi32.dll&quot;);
                if (SUCCEEDED(hRes))
                {
                    // Load mapi32.dll
                    hmodMapi32 = LoadLibraryA(szDLLPath);
                    if (hmodMapi32)
                    {
                        // Get the address of FGetComponentPath from mapi32
                        pfnFGetComponentPath = (LPFGETCOMPONENTPATH)GetProcAddress(
                            hmodMapi32, &quot;FGetComponentPath&quot;);
                    }
                 }
            }
            if (pfnFGetComponentPath)
            {
                LPSTR szAppLCID = NULL;
                LPSTR szOfficeLCID = NULL;
                HKEY hMicrosoftOutlook = NULL;

                lRet = RegOpenKeyEx(
                    HKEY_LOCAL_MACHINE,
                    _T(&quot;Software\\Clients\\Mail\\Microsoft Outlook&quot;),
                    NULL,
                    KEY_READ,
                    &amp;hMicrosoftOutlook);

                if (ERROR_SUCCESS == lRet &amp;&amp; hMicrosoftOutlook)
                {
                    HrGetRegMultiSZValueA(hMicrosoftOutlook, &quot;MSIApplicationLCID&quot;, (LPVOID*) &amp;szAppLCID);
                    HrGetRegMultiSZValueA(hMicrosoftOutlook, &quot;MSIOfficeLCID&quot;, (LPVOID*) &amp;szOfficeLCID);
                }

                // Only passing a fixed value as the component ID for MAPI in this example
                // In practice, must read from the registry the value of MSIComponentID
                if (szAppLCID)
                {
                    bRet = pfnFGetComponentPath(
                        &quot;{FF1D0740-D227-11D1-A4B0-006008AF820E}&quot;, szAppLCID, szMAPIDir, cchMAPIDir, true);
                }
                if ((!bRet || szMAPIDir[0] == _T(&apos;\0&apos;)) &amp;&amp; szOfficeLCID)
                {
                    bRet = pfnFGetComponentPath(
                    &quot;{FF1D0740-D227-11D1-A4B0-006008AF820E}&quot;, szOfficeLCID, szMAPIDir, cchMAPIDir, true);
                }
                if (!bRet || szMAPIDir[0] == _T(&apos;\0&apos;))
                {
                    bRet = pfnFGetComponentPath(
                        &quot;{FF1D0740-D227-11D1-A4B0-006008AF820E}&quot;, NULL, szMAPIDir, cchMAPIDir, true);
                }

                // Got the path to msmapi32.dll - need to strip it
                if (bRet &amp;&amp; szMAPIDir[0] != _T(&apos;\0&apos;))
                {
                    LPSTR lpszSlash = NULL;
                    LPSTR lpszCur = szMAPIDir;

                    for (lpszSlash = lpszCur; *lpszCur; lpszCur = lpszCur++)
                    {
                        if (*lpszCur == _T(&apos;\\&apos;)) lpszSlash = lpszCur;
                    }
                   *lpszSlash = _T(&apos;\0&apos;);
                }

                delete[] szOfficeLCID;
                delete[] szAppLCID;
                if (hMicrosoftOutlook) RegCloseKey(hMicrosoftOutlook);
            }

            // If FGetComponentPath returns FALSE or if
            // it returned nothing, or if failed to find an
            // address of FGetComponentPath, then
            // just default to the system directory
            if (!bRet || szMAPIDir[0] == &apos;\0&apos;)
            {
                hRes = StringCchPrintfA(
                    szMAPIDir, cchMAPIDir,&quot;%s&quot;, szSystemDir);
            }

            if (szMAPIDir[0] != _T(&apos;\0&apos;))
            {
                hRes = StringCchPrintfA(
                    szMAPIDir, cchMAPIDir, &quot;%s\\%s&quot;, szMAPIDir, &quot;MAPISVC.INF&quot;);
            }

            if (hmodMapi32) FreeLibrary(hmodMapi32);
            if (hmodStub) FreeLibrary(hmodStub);
        }
    }
}


How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode

 Copy code hover
[image]

How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode
See also Send feedback

Published: July 16, 2012

This topic contains a code sample in C++ that shows how to use IID_IMessageRaw in IMsgStore::OpenEntry to obtain an IMessage interface that manages a message in an offline folders file (OST) without forcing a download of the whole message when the client is in Cached Exchange Mode.

When a client is in Cached Exchange Mode, messages in the OST can be in one of two states:

  • The whole message that contains the header and the body is downloaded.

  • The message with only its header is downloaded.

When you request an IMessage interface for a message in an OST and the client is in Cached Exchange Mode, use IID_IMessageRaw. If you use IID_IMessage to request an IMessage interface, and if the message has only its header downloaded in the OST, you invoke a synchronization that attempts to download the whole message.

If you use IID_IMessageRaw or IID_IMessage to request an IMessage interface, the interfaces that are returned are identical in use. The IMessage interface that was requested by using IID_IMessageRaw returns an email message as it exists in the OST, and synchronization is not forced.

The following example shows how to call the OpenEntry method, passing IID_IMessageRaw instead of IID_IMessage.

Copy code Copy code
HRESULT HrOpenRawMessage (
    LPMDB lpMSB,
    ULONG cbEntryID,
    LPENTRYID lpEntryID,
    ULONG ulFlags,
    LPMESSAGE* lpMessage)
{
    ULONG ulObjType = NULL;

    HRESULT hRes = lpMDB->OpenEntry(
        cbEntryID,
        lpEntryID,
        IID_IMessageRaw,
        ulFlags,
        &ulObjType,
        (LPUNKNOWN*) lpMessage));

   return hRes;
}

If the OpenEntry method returns the MAPI_E_INTERFACE_NOT_SUPPORTED error code, it indicates that the message store does not support accessing the message in raw mode. In this situation, try the OpenEntry method again by passing IID_IMessage.

Important note Important

IID_IMessageRaw might not be defined in the downloadable header file that you currently have. In this case, you can add it to your code by using the following definition. Use the DEFINE_OLEGUID macro defined in the Microsoft Windows Software Development Kit (SDK) header file guiddef.h to associate the GUID symbolic name with its value.

#if !defined(INITGUID) || defined(USES_IID_IMessageRaw)

DEFINE_OLEGUID(IID_IMessageRaw,0x0002038A, 0, 0);

#endif

See also

Concepts

About MAPI Additions
How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode


How to: Obtain a Contact Message Given a Contacts Address Book Entry

 Copy code hover
[image]

How to: Obtain a Contact Message Given a Contacts Address Book Entry
See also Send feedback

Published: July 16, 2012

This topic contains an example in C++, HrOpenContact, that shows how to use the CONTAB_ENTRYID structure that identifies an entry in a Contacts Address Book to obtain the associated MAPI Contact message.

HrOpenContact has the following parameters:

  • lpSession is an input parameter representing the current session. LPMAPISESSION is defined in the MAPI header file mapix.h as a pointer to IMAPISession : IUnknown.

  • cbEntryID is an input parameter representing the size of the entry identifier associated with lpEntryID.

  • lpEntryID is an input parameter representing a pointer to the entry identifier of an entry in a Contact Address Book.

  • ulFlags is an input parameter representing a bitmask containing object access flags to the MAPI Contact message.

  • lpContactMessage is an output parameter representing a pointer to the MAPI Contact message.

To open the underlying MAPI Contact message, HrOpenContact first casts lpEntryID to a pointer to CONTAB_ENTRYID. It then calls IMAPISession::OpenEntry to obtain the MAPI Contact message, passing as parameters the cbeid and abeid fields of the entry in the Contacts Address Book that identify respectively the size of the entry identifier and the entry identifier of the MAPI Contact message.

Copy code Copy code
TZDEFINITION* BinToTZDEFINITION(ULONG cbDef, LPBYTE lpbDef)
{
    if (!lpbDef) return NULL;

    // Update this if parsing code is changed.
    // This checks the size up to the flag member.
    if (cbDef &lt; 2*sizeof(BYTE) + 2*sizeof(WORD)) return NULL;

    TZDEFINITION tzDef = {0};
    TZRULE* lpRules = NULL;
    LPBYTE lpPtr = lpbDef;
    WORD cchKeyName = NULL;
    WCHAR* szKeyName = NULL;
    WORD i = 0;

    BYTE bMajorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);
    BYTE bMinorVersion = *((BYTE*)lpPtr);
    lpPtr += sizeof(BYTE);

    // We only understand TZ_BIN_VERSION_MAJOR
    if (TZ_BIN_VERSION_MAJOR != bMajorVersion) return NULL;

    // We only understand if &gt;= TZ_BIN_VERSION_MINOR
    if (TZ_BIN_VERSION_MINOR &gt; bMinorVersion) return NULL;

    lpPtr += sizeof(WORD);

    tzDef.wFlags = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);

    if (TZDEFINITION_FLAG_VALID_GUID &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(GUID)) return NULL;
        tzDef.guidTZID = *((GUID*)lpPtr);
        lpPtr += sizeof(GUID);
    }

    if (TZDEFINITION_FLAG_VALID_KEYNAME &amp; tzDef.wFlags)
    {
        if (lpbDef + cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
        cchKeyName = *((WORD*)lpPtr);
        lpPtr += sizeof(WORD);
        if (cchKeyName)
        {
            if (lpbDef + cbDef - lpPtr &lt; (BYTE)sizeof(WORD)*cchKeyName) return NULL;
            szKeyName = (WCHAR*)lpPtr;
            lpPtr += cchKeyName*sizeof(WORD);
        }
    }

    if (lpbDef+ cbDef - lpPtr &lt; sizeof(WORD)) return NULL;
    tzDef.cRules = *((WORD*)lpPtr);
    lpPtr += sizeof(WORD);
    if (tzDef.cRules)
    {
        lpRules = new TZRULE[tzDef.cRules];
        if (!lpRules) return NULL;

        LPBYTE lpNextRule = lpPtr;
        BOOL bRuleOK = false;

See also

Reference

IMAPISession::OpenEntry


How to: Access a Message on an IMAP Store Without Downloading the Entire Message

 Copy code hover
[image]

How to: Access a Message on an IMAP Store Without Downloading the Entire Message
Send feedback

Published: July 16, 2012

This topic shows a code sample in C++ that queries a message store for the IProxyStoreObject interface, and uses the returned pointer and the IProxyStoreObject::UnwrapNoRef function to obtain a pointer to an IMAP store object that has been unwrapped. Using this unwrapped store allows access to a message in its current state without invoking a download of the entire message.

Because UnwrapNoRef does not increment the reference count for this new pointer to the unwrapped store object, after successfully calling UnwrapNoRef, you must call IUnknown::AddRef to maintain the reference count.

Copy code Copy code
HRESULT HrUnWrapMDB(LPMDB lpMDBIn, LPMDB* lppMDBOut)
{
    HRESULT hRes = S_OK;
    IProxyStoreObject* lpProxyObj = NULL;
    LPMDB lpUnwrappedMDB = NULL;
    hRes = lpMDBIn->QueryInterface(IID_IProxyStoreObject,(void**)&lpProxyObj);
    if (SUCCEEDED(hRes) && lpProxyObj)
    {
        hRes = lpProxyObj->UnwrapNoRef((LPVOID*)&lpUnwrappedMDB);
        if (SUCCEEDED(hRes) && lpUnwrappedMDB)
        {
            // UnwrapNoRef doesn't addref, so do it here
            lpUnwrappedMDB->AddRef();
            (*lppMDBOut) = lpUnwrappedMDB;
        }
    }
    if (lpProxyObj) lpProxyObj->Release();
    return hRes;
}


How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode

 Copy code hover
[image]

How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode
See also Send feedback

Published: July 16, 2012

This topic contains a code sample in C++ that shows how to use the MDB_ONLINE flag to open a message store on the remote server when Microsoft Outlook 2010 or Microsoft Outlook 2013 is in Cached Exchange Mode.

Cached Exchange Mode permits Outlook 2010 and Outlook 2013 to use a local copy of a user's mailbox while Outlook 2010 or Outlook 2013 maintains an online connection to a remote copy of the user's mailbox on the remote Exchange server. When Outlook 2010 or Outlook 2013 is running in Cached Exchange Mode, by default, any MAPI solutions that log on to the same session are also connected to the cached message store. Any data that is accessed and any changes that are made are made against the local copy of the mailbox.

A client or service provider can override the connection to the local message store and open the store on the remote server by setting the bit for MDB_ONLINE in the ulFlags parameter when calling IMAPISession::OpenMsgStore. After the store has been successfully opened on the remote server for that session, you can use IMAPISession::OpenEntry to open items or folders on the remote store.

You cannot open an Exchange store in cached mode and in non-cached mode at the same time in the same MAPI session. If you have already opened the cached message store, you must either close the store before you open it with this flag, or open a new MAPI session where you can open the Exchange store on the remote server by using this flag.

The following code sample shows how to call IMAPISession::OpenMsgStore with the MDB_ONLINE flag set in the ulFlags parameter to open the default store on the remote server.

Copy code Copy code
HRESULT HrRemoteMessageStore(
    LPMAPISESSION lpMAPISession,
    LPMDB* lppMDB)
{
    HRESULT hRes = S_OK;
    LPMAPITABLE pStoresTbl = NULL;
    SRestriction sres = {0};
    SPropValue spv = {0};
    LPSRowSet pRow = NULL;
    LPMDB lpTempMDB = NULL;
    enum {EID,NUM_COLS};
    static SizedSPropTagArray(NUM_COLS,sptCols) = {NUM_COLS,
        PR_ENTRYID,
    };

    //Obtain the table of all the message stores that are available
    hRes = lpMAPISession-&gt;GetMsgStoresTable(0, &amp;pStoresTbl);

    if (SUCCEEDED(hRes) &amp;&amp; pStoresTbl)
    {
        //Set up restrictions for the default store
        sres.rt = RES_PROPERTY;                                  //Comparing a property
        sres.res.resProperty.relop = RELOP_EQ;                   //Testing equality
        sres.res.resProperty.ulPropTag = PR_DEFAULT_STORE;       //Tag to compare
        sres.res.resProperty.lpProp = &amp;spv;                      //Prop tag and value to compare against

        spv.ulPropTag = PR_DEFAULT_STORE;                        //Tag type
        spv.Value.b   = TRUE;                                    //Tag value

        //Convert the table to an array that can be stepped through
        //Only one message store should have PR_DEFAULT_STORE set to true, so that only one will be returned
        hRes = HrQueryAllRows(
            pStoresTbl,                                          //Table to query
            (LPSPropTagArray) &amp;sptCols,                          //Which columns to obtain
            &amp;sres,                                               //Restriction to use
            NULL,                                                //No sort order
            0,                                                   //Max number of rows (0 means no limit)
            &amp;pRow);                                              //Array to return

        if (SUCCEEDED(hRes) &amp;&amp; pRow &amp;&amp; pRow-&gt;cRows)
        {
            //Open the first returned (default) message store
            hRes = lpMAPISession-&gt;OpenMsgStore(
                NULL,                                                //Window handle for dialogs
                pRow-&gt;aRow[0].lpProps[EID].Value.bin.cb,             //size and...
                (LPENTRYID)pRow-&gt;aRow[0].lpProps[EID].Value.bin.lpb, //value of entry to open
                NULL,                                                //Use default interface (IMsgStore) to open store
                MAPI_BEST_ACCESS | MDB_ONLINE,                       //Flags
                &amp;lpTempMDB);                                         //Pointer to put the store in
            if (SUCCEEDED(hRes) &amp;&amp; lppMDB) lppMDB* = lpTempMDB;
        }
    }
    FreeProws(pRow);
    if (pStoresTbl) pStoresTbl-&gt;Release();

    return hRes;
}

See also

Concepts

About MAPI Additions
MAPI Constants
How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode


How to: Programmatically Set the Resolution Order for Address Lists

 Copy code hover
[image]

How to: Programmatically Set the Resolution Order for Address Lists
See also Send feedback

Published: July 16, 2012

This topic contains a code sample in C++ that programmatically sets the order of address lists by which recipients in e-mail messages and attendees in meeting requests are resolved.

In MAPI, each profile can support multiple address lists and each address list resides in its own container. MAPI supports the SetSearchPath method in the interface that allows you to set a new search path in the profile that is used for name resolution. To use the IAddrBook::SetSearchPath method, you have to define the desired resolution order in a SRowSet array that holds the containers of the relevant address books in the desired order, and then specify the array as the lpSearchPath parameter. The first property for each entry in the SRowSet array must be the PR_ENTRYID property of the corresponding address book.

The code sample sets the resolution order in the following steps:

  1. Initializes numANR to the number of containers to match, and specifies the names and resolution order of the desired address lists in an ANROrder array.

  2. Initializes MAPI by using the MAPIInitialize function.

  3. Logs on to MAPI and allows the user to choose a profile.

  4. Gets a pointer to the address book from the current session.

  5. Opens the Address Book.

  6. Opens the container for the root Address Book.

  7. Opens the hierarchy table of the root address book container.

  8. Gets the list of address book containers in the hierarchy.

  9. Looks for the entry IDs of the desired address lists by comparing the names of the desired address lists in ANROrder to the existing names in the address book hierarchy.

  10. Sets the appropriate entry IDs to the SRowSet array, pNewRows.

  11. Calls and passes pNewRows as the lpSearchPath parameter to IAddrBook::SetSearchPath to set the search path.

  12. Cleans up internal buffers and pointers.

  13. Logs off from MAPI.

  14. Uninitalizes MAPI.

This code sample uses address lists that are available in the default installation of Microsoft Office Outlook: All Contacts, All Groups, and Contacts. You must run the sample after Outlook is started and is running on an initialized profile. The sample works well with names that are in one language (for example, all names are in English). It is not designed to work in multi-lingual deployments, for example the Contacts folder localized for a user running a non-English Outlook build.

Copy code Copy code
#include "stdafx.h"
#include <mapix.h>
#include <mapiguid.h>
#include <mapiutil.h>
#include <mapidefs.h>
#include <stdio.h>
#include <conio.h>

//Number of address lists to resolve against
const int numANR = 3;
WCHAR *ANROrder[numANR] = {_T("All Contacts"), _T("All Groups"), _T("Contacts")};
UINT  numContainersFound [numANR] = {0};

// Temporary structure to allocate buffer in MAPI. This will be used as a parent buffer to free space later.
LPVOID tempLink;

// Forward declaration of helper function to copy binary data
STDMETHODIMP CopySBinary(
    LPSBinary psbDest,
    const LPSBinary psbSrc,
    LPVOID pParent);

void main()
{
    // MAPI address book and session variables
    HRESULT       hRes = S_OK;            // Result code returned from MAPI calls.
    LPMAPISESSION lpSession = NULL;   // Pointer to MAPI session.
    LPADRBOOK     lpAddrBook = NULL;  // Pointer to Address Book.

    // Counters
    ULONG         i = 0;                  // Index counter
    ULONG         j = 0;                  // Index counter

    // Used for querying hierarchy
    ULONG                                   ulObjType = 0L;      // Object type returned by MAPI
    LPMAPICONTAINER     pIABRoot = NULL;     // Root address book container
    LPMAPITABLE              pHTable = NULL;      // Holds hierarchy table
    LPSRowSet        pRows = NULL;        // Pointer to row set. Stores AB Address Lists

    // Used for setting search path
    LPSRowSet     pNewRows = NULL;        // Pointer to new row set
    SizedSRowSet  (numANR, NewRows);      // New row set
    SPropValue    sProps[numANR] = {0};   // Property tag structure

    // Structures contaning MAPI Column Sets required for querying tables
    enum {
        abPR_ENTRYID,
        abPR_DISPLAY_NAME_W,
        abNUM_COLS};

    static SizedSPropTagArray(abNUM_COLS,abCols) = {
        abNUM_COLS,
        PR_ENTRYID,
        PR_DISPLAY_NAME_W,
    };

    // Initialize MAPI
    if (FAILED ( hRes = MAPIInitialize(NULL))) goto Exit;

    // Log on to MAPI and allow user to choose profile

    // Note: This uses the current MAPI session if there is one
    if (FAILED ( hRes = MAPILogonEx(NULL, NULL, NULL, MAPI_LOGON_UI, &lpSession))) goto Exit;

    // Open the Address Book
    if (FAILED (hRes = lpSession->OpenAddressBook(NULL, NULL, NULL, &lpAddrBook))) goto Cleanup;

    // Open the Address Book Root container
    if (FAILED (hRes = lpAddrBook -> OpenEntry (
        0L,
        NULL,
        NULL,
        0L,
        &ulObjType,
        (LPUNKNOWN *) &pIABRoot )))
    goto Cleanup;

    // Intentionally allocate 0 bytes. This is used for buffer management.
    MAPIAllocateBuffer(0L, &tempLink);

    // Make sure there is a Container object
    // Query hierarchy for containers
    if ( MAPI_ABCONT == ulObjType ) {
        // - Call IMAPIContainer::GetHierarchyTable to open the Hierarchy
        //   table of the root address book container
        if ( FAILED ( hRes = pIABRoot -> GetHierarchyTable ( CONVENIENT_DEPTH | MAPI_UNICODE,
            &pHTable ) ) )
        goto Cleanup;

        // Get the list of address book containers first
        if ( FAILED ( hRes = HrQueryAllRows (
            pHTable,
            (LPSPropTagArray) &abCols,
            NULL,
            NULL,
            0L,
            &pRows ) ) )
        goto Cleanup;

        // Initialize the structures to set the search order
        ZeroMemory(&NewRows, numANR * sizeof(SRow));
        pNewRows = (LPSRowSet)&NewRows;

        // Set the number of rows you are going to set
        pNewRows->cRows = numANR;

        // Set the pointers to the structures
        for (i=0; i<numANR; i++)
            pNewRows->aRow[i].lpProps = &sProps[i];

        // Compare the list to the ones that of interest
        for (i=0; i<pRows->cRows; i++) {
            if (pRows->aRow[i].lpProps[abPR_DISPLAY_NAME_W].ulPropTag == PR_DISPLAY_NAME_W) {
                LPWSTR containerName =  pRows->aRow[i].lpProps[abPR_DISPLAY_NAME_W].Value.lpszW;
                for (j=0; j<numANR; j++)
                    if (!wcscmp (containerName, ANROrder[j])) {
                        // First check if a container with this name has been found already
                        if (numContainersFound[j] == 0) {
                            numContainersFound[j]++;
                            pNewRows->aRow[j].cValues = 1;

                            // The property being passing is PR_ENTRY_ID
                            pNewRows->aRow[j].lpProps[0].ulPropTag = PR_ENTRYID;

                            // Copy the binary data over
                            if (FAILED (hRes = CopySBinary(
                                &pNewRows->aRow[j].lpProps[0].Value.bin,
                                &pRows->aRow[i].lpProps[abPR_ENTRYID].Value.bin,
                                tempLink))) {
                                    printf ("Fatal Error:Failed to copy entry IDs\n");
                                    goto Cleanup;
                            }
                         }
                         // More than 1 container matched the same name
                         else {
                             printf ("Fatal Error: Duplicate container found, container name = %s\n", containerName);
                             goto Cleanup;
                         }
                    }
            }
        }

        // Only set the search path if all the rows have been found
        // Check the array for any entries that were blank
        for (i=0; i< numANR; i++)
            if (numContainersFound [i] == 0) {
                printf ("Fatal Error: all containers were not found\n");
                goto Cleanup;
            }

        // Everything is safe to set the search path now
        if (FAILED (hRes = lpAddrBook->SetSearchPath(0, pNewRows))) {
            printf ("Fatal Error: failed to set the search path\n");
            goto Cleanup;
        }
    }

    Cleanup:
        MAPIFreeBuffer(tempLink);
        UlRelease(pHTable);
        FreeProws(pRows);
        UlRelease (pIABRoot);
        UlRelease(lpAddrBook);

        // Log off from MAPI
        hRes = lpSession->Logoff(NULL, NULL, 0);
        UlRelease(lpSession);

    Exit:
        // Uninitialize MAPI
        MAPIUninitialize();
}

/////////////////////////////////////////////////////////////
//    CopySBinary()
//
//    Parameters
//
//    Purpose
//      Allocates a new SBinary and copies psbSrc into it
//

STDMETHODIMP CopySBinary(
    LPSBinary psbDest,
    const LPSBinary psbSrc,
    LPVOID pParent)
{
    HRESULT     hRes = S_OK;
    psbDest->cb = psbSrc->cb;

    if (psbSrc->cb) {
        if (pParent)
            hRes = MAPIAllocateMore(
                 psbSrc->cb,
                 pParent,
                 (LPVOID*) &psbDest->lpb);
        else
            hRes = MAPIAllocateBuffer(
                 psbSrc->cb,
                 (LPVOID*) &psbDest->lpb);

    if (!FAILED(hRes))
        CopyMemory(psbDest->lpb,psbSrc->lpb,psbSrc->cb);
    }

   return hRes;
}

See also

Concepts

About Setting the Resolution Order for Address Lists in Outlook


How to: Remove Custom Form Definition Saved With a Message

 Copy code hover
[image]

How to: Remove Custom Form Definition Saved With a Message
See also Send feedback

Published: July 16, 2012

This topic shows a code sample in C++ that converts a message that has been saved with a custom form definition to a regular message without the form definition.

In Microsoft Outlook 2010 or Microsoft Outlook 2013, you can share forms containing custom form pages by either publishing them to a forms library or saving the corresponding form definition with a message. A custom form saved with a message is commonly referred as a "one-off form", since the form is shared only for viewing that specific message as a one-off instance. You typically do this when the form is not published in a forms library but you want the recipient to use the custom form when opening the item. You can specify a form is a one-off in the Forms Designer, by selecting the Send form definition with item check box on the Properties page of the form.

Forms containing form pages can be customized with code in Visual Basic Scripting Edition (VBScript). Messages that are saved with form definitions are generally bigger in size. For security and storage reasons, Outlook 2010 and Outlook 2013 ignore form definitions saved with any item.

To convert a message that is saved with a custom form definition to one without, you must remove four named properties:

  • PidLidFormStorage Canonical Property

  • PidLidPageDirStream Canonical Property

  • PidLidFormPropStream Canonical Property

  • PidLidScriptStream Canonical Property

In addition, you should also remove the PidLidPropertyDefinitionStream Canonical Property that contains the definitions of custom properties saved with that message. A side effect of removing this property is that the Outlook 2010 or Outlook 2013 object models and the Outlook 2010 or Outlook 2013 user interface will no longer be able to access user properties that have been set on the message. You are still able to access these properties and their values through MAPI. Note that if you do not remove this property and the message is saved with another form definition, the PidLidPropertyDefinitionStream Canonical Property is partially overwritten with new data and data integrity is not guaranteed.

If you remove the PidLidPropertyDefinitionStream Canonical Property, then you should also remove the INSP_PROPDEFINITION flag from the PidLidCustomFlag Canonical Property.

The following function, RemoveOneOff, accepts as input parameters a pointer to a message and an indicator whether to remove the PidLidPropertyDefinitionStream Canonical Property. Using the message pointer, it calls IMAPIProp::GetIDsFromNames to obtain the appropriate property identifiers, and then calls IMAPIProp::DeleteProps to remove the named properties. It also calls IMAPIProp::GetProps to get the PidLidCustomFlag Canonical Property and clears the INSP_ONEOFFFLAGS flag and INSP_PROPDEFINITION flag as appropriate from that property, so that Outlook 2010 and Outlook 2013 will not look for those named properties that have been removed.

Copy code Copy code
ULONG aulOneOffIDs[] = {dispidFormStorage,
    dispidPageDirStream,
    dispidFormPropStream,
    dispidScriptStream,
    dispidPropDefStream, // dispidPropDefStream must remain next to last in list
    dispidCustomFlag};   // dispidCustomFlag must remain last in list

#define ulNumOneOffIDs (sizeof(aulOneOffIDs)/sizeof(aulOneOffIDs[0]))

HRESULT RemoveOneOff(LPMESSAGE lpMessage, BOOL bRemovePropDef)
{
    if (!lpMessage) return MAPI_E_INVALID_PARAMETER;

    HRESULT hRes = S_OK;
    MAPINAMEID  rgnmid[ulNumOneOffIDs];
    LPMAPINAMEID rgpnmid[ulNumOneOffIDs];
    LPSPropTagArray lpTags = NULL;

    ULONG i = 0;
    for (i = 0 ; i < ulNumOneOffIDs ; i++)
    {
        rgnmid[i].lpguid = (LPGUID)&PSETID_Common;
        rgnmid[i].ulKind = MNID_ID;
        rgnmid[i].Kind.lID = aulOneOffIDs[i];
        rgpnmid[i] = &rgnmid[i];
    }

    hRes = lpMessage->GetIDsFromNames(
        ulNumOneOffIDs,
        rgpnmid,
        0,
        &lpTags);
    if (lpTags)
    {
        // The last prop is the flag value
        // to be updated, don't count it
        lpTags->cValues = ulNumOneOffIDs-1;

        // If the prop def stream is not to be removed, don't count it
        if (!bRemovePropDef)
        {
          lpTags->cValues = lpTags->cValues-1;
        }

        hRes = lpMessage->DeleteProps(
            lpTags,
            0);
        if (SUCCEEDED(hRes))
        {
            SPropTagArray pTag = {0};
            ULONG cProp = 0;
            LPSPropValue lpCustomFlag = NULL;

            // Grab dispidCustomFlag, the last tag in the array
            pTag.cValues = 1;
            pTag.aulPropTag[0] = CHANGE_PROP_TYPE(
                lpTags->aulPropTag[ulNumOneOffIDs-1],
                PT_LONG);

            hRes = lpMessage->GetProps(
                &pTag,
                fMapiUnicode,
                &cProp,
                &lpCustomFlag);
            if (SUCCEEDED(hRes) &&
                1 == cProp && lpCustomFlag &&
                PT_LONG == PROP_TYPE(lpCustomFlag->ulPropTag))
            {
                // Clear the INSP_ONEOFFFLAGS bits so Outlook
                // doesn't look for the props that have been deleted
                lpCustomFlag->Value.l =
                    lpCustomFlag->Value.l & ~(INSP_ONEOFFFLAGS);
                if (bRemovePropDef)
                {
                    lpCustomFlag->Value.l =
                        lpCustomFlag->Value.l & ~(INSP_PROPDEFINITION);
                }
                hRes = lpMessage->SetProps(
                    1,
                    lpCustomFlag,
                    NULL);
             }

             hRes = lpMessage->SaveChanges(KEEP_OPEN_READWRITE);
         }
    }
    MAPIFreeBuffer(lpTags);

    return hRes;
}

See also

Concepts

MAPI Constants


How to: Retrieve the Body of a Message in Compressed RTF and Convert It to Its Native Format

 Copy code hover
[image]

How to: Retrieve the Body of a Message in Compressed RTF and Convert It to Its Native Format
Send feedback

Published: July 16, 2012

This code example in Microsoft C++ shows you how to use the exported Microsoft Outlook 2010 or Microsoft Outlook 2013 function WrapCompressedRTFStreamEx to access the body of a message that is encapsulated in compressed RTF, and to obtain the body in its native format.

Copy code Copy code
//These are definitions for the WrapCompressedRTFStreamEx function.
typedef HRESULT (STDMETHODCALLTYPE WRAPCOMPRESSEDRTFSTREAMEX) (
    LPSTREAM lpCompressedRTFStream, CONST RTF_WCSINFO * pWCSInfo, LPSTREAM * lppUncompressedRTFStream, RTF_WCSRETINFO * pRetInfo);
typedef WRAPCOMPRESSEDRTFSTREAMEX *LPWRAPCOMPRESSEDRTFSTREAMEX;

HRESULT TestWrapCompressedRTFStreamEx(LPMESSAGE lpMsg)
{
    HRESULT         hRes = S_OK;
    LPSTREAM        lpCompressed = NULL;
    LPSTREAM        lpUncompressed = NULL;
    char            szBody[1024] = {0};
    ULONG           ulRead = 0;
    RTF_WCSINFO     wcsinfo = {0};
    RTF_WCSRETINFO  retinfo = {0};
    LPSPropValue    lpPropCPID = NULL;

    retinfo.size = sizeof(RTF_WCSRETINFO);

    wcsinfo.size = sizeof(RTF_WCSINFO);
    wcsinfo.ulFlags = MAPI_NATIVE_BODY;
    wcsinfo.ulOutCodePage = 0;

    // Retrieve the value of the Internet code page.
    // Pass this value to the WrapCompressedRTFStreamEx function.
    // If the property is not found, the default is 0.
    if(SUCCEEDED(hRes = HrGetOneProp(lpMsg, PR_INTERNET_CPID, &lpPropCPID)))
    {
        wcsinfo.ulInCodePage = lpPropCPID->Value.l;
    }

    // Open the compressed RTF stream.
    if(SUCCEEDED(hRes = lpMsg->OpenProperty(PR_RTF_COMPRESSED,
                                         &IID_IStream,
                                         STGM_READ | STGM_DIRECT,
                                         0,
                                         (LPUNKNOWN*)&lpCompressed)))
    {

        // Notice that the WrapCompressedRTFStreamEx function has been loaded
        // by using the GetProcAddress function into pfnWrapEx.

        // Call the WrapCompressedRTFStreamEx function.
        if(SUCCEEDED(hRes = pfnWrapEx(lpCompressed,
                                   &wcsinfo,
                                   &lpUncompressed,
                                   &retinfo)))
        {

            printf("Body's native type is: ");

            // Check what the native body type is.
            switch(retinfo.ulStreamFlags)
            {
            case MAPI_NATIVE_BODY_TYPE_RTF:
                printf("MAPI_NATIVE_BODY_TYPE_RTF\n");
                break;
            case MAPI_NATIVE_BODY_TYPE_HTML:
                printf("MAPI_NATIVE_BODY_TYPE_HTML\n");
                break;
            case MAPI_NATIVE_BODY_TYPE_PLAINTEXT:
                printf("MAPI_NATIVE_BODY_TYPE_PLAINTEXT\n");
                break;
            default:
                printf("UNKNOWN\n");
            }

            // Read the first 1,000 characters out of the stream.
            if(SUCCEEDED(hRes = lpUncompressed->Read(szBody, 1024, &ulRead)))
            {
                printf("First %d characters of the native body stream:\n%s\n", ulRead, szBody);
            }
        }
    }

    MAPIFreeBuffer(lpPropCPID);
    if(lpUncompressed)lpUncompressed->Release();
    if(lpCompressed)lpCompressed->Release();

    return hRes;
}


How to: Use the MAPI Crash Recovery API

 Copy code hover
[image]

How to: Use the MAPI Crash Recovery API
See also Send feedback

Published: July 16, 2012

This topic contains a code sample in C++ that shows how to call the MAPICrashRecovery function from the UnhandledExceptionFilter function. The MAPICrashRecovery function checks the state of the Personal Folders file (PST) or Offline Folders file (OST) shared memory. If the memory is in a consistent state, the MAPICrashRecovery function moves the data to disk and prevents further read or write access until the process is terminated. By ensuring that the PSTs or OSTs are in a consistent state before the process is terminated, you can prevent Microsoft Outlook 2010 or Microsoft Outlook 2013 from displaying the following error message and avoid performance problems.

A data file did not close properly the last time it was used and is being checked for problems. Performance might be affected while the check is in progress.

Copy code Copy code
LONG WINAPI UnhandledExceptionFilter(__in EXCEPTION_POINTERS* pep)
{
    // Let the OS terminate the process upon return.
    LONG retval = EXCEPTION_EXECUTE_HANDLER;

    switch (pep->ExceptionRecord->ExceptionCode)
    {
        case EXCEPTION_BREAKPOINT:
        case EXCEPTION_SINGLE_STEP:
            // Ignore debugging exceptions.
            retval = EXCEPTION_CONTINUE_SEARCH;
            break;

        default:
            // The process is going to be terminated, so disconnect the MAPI database.
            MAPICrashRecovery(MAPICRASH_RECOVER);
            // Optionally, you can display a crash reporting dialog box here.
            // If the user chooses to debug,
            // call MAPICrashRecovery(MAPICRASH_CONTINUE).
            break;
    }

    return retval;
}

See also

Concepts

About the MAPI Crash Recovery API
MAPICrashRecovery


How to: Verify an Attachment is Blocked

 Copy code hover
[image]

How to: Verify an Attachment is Blocked
Send feedback

Published: July 16, 2012

This code sample in C++ shows how to use the IAttachmentSecurity : IUnknown interface to find out whether an attachment is blocked by Microsoft Outlook 2010 or Microsoft Outlook 2013 for viewing and indexing.

IAttachmentSecurity : IUnknown is derived from the IUnknown interface. You can obtain the IAttachmentSecurity : IUnknown interface by calling IUnknown::QueryInterface on the MAPI session object, requesting IID_IAttachmentSecurity. IAttachmentSecurity::IsAttachmentBlocked returns true in pfBlocked if the attachment is considered unsafe by Outlook 2010 or Outlook 2013 and is blocked for viewing and indexing in Outlook 2010 or Outlook 2013.

Copy code Copy code
HRESULT IsAttachmentBlocked(LPMAPISESSION lpMAPISession, LPCWSTR pwszFileName, BOOL* pfBlocked)
{
    if (!lpMAPISession || !pwszFileName || !pfBlocked) return MAPI_E_INVALID_PARAMETER;

    HRESULT hRes = S_OK;
    IAttachmentSecurity* lpAttachSec = NULL;
    BOOL bBlocked = false;

    hRes = lpMAPISession-&gt;QueryInterface(IID_IAttachmentSecurity,(void**)&amp;lpAttachSec);
    if (SUCCEEDED(hRes) &amp;&amp; lpAttachSec)
    {
        hRes = lpAttachSec-&gt;IsAttachmentBlocked(pwszFileName,&amp;bBlocked);
    }
    if (lpAttachSec) lpAttachSec-&gt;Release();

    *pfBlocked = bBlocked;
    return hRes;
}


MAPI Tables

 Copy code hover
[image]

MAPI Tables
See also Send feedback

Published: July 16, 2012

A MAPI table is a MAPI object that is used to view a collection of properties belonging to other MAPI objects of a particular type. MAPI tables are structured in a row and column format with each row representing an object and each column representing a property of the object. One of the properties usually included in each row is the PR_ENTRYID (PidTagEntryId) property, an identifier that can be used to open and modify the object.

Because rows contain property values, retrieving a row from a table is similar to getting a set of properties directly from the object that the row represents. Both operations result in the retrieval of a property value array. The main difference is in the handling of long string and binary properties. For inclusion in a table, some table implementers truncate these properties to 255 bytes. When retrieved directly from the object, the full value is always available.

Tables are implemented by address book and message store providers and by MAPI, depending on the type of table and the objects within it. A message store provider implements folders and a contents table for each folder that includes information about the messages in the folder. An address book provider implements address book containers and a hierarchy table that shows their organization. MAPI implements several different tables, some for use by client applications, some for use by service providers, and some for use by both. The status table is unique in that MAPI ultimately supplies the table, but the rows are comprised of contributions from all types of service providers in addition to MAPI.

The following illustration shows one of the frequent uses of a table in MAPI: to display the contents of a folder. On the right is a display of two messages as might appear in a typical messaging client application. The display contains four pieces of information about each message: the sender, the recipient, the subject, and the message text. Each piece of information corresponds to a property of the message.

On the left is a view of the contents table that includes these two messages. Whereas the contents table may have ten rows because the folder has ten messages, with each row containing many more than three columns, this particular view is limited to only two rows and three columns.

The following table shows the properties that make up the column set for the table view.

Property | Description
PR_SENDER_NAME (PidTagSenderName) | Sender name
PR_ORIGINAL_DELIVERY_TIME (PidTagOriginalDeliveryTime) | Date and time when the message was sent
PR_SUBJECT (PidTagSubject) | Message subject line

Notice that the set of properties displayed in the message are not the same as the set of columns displayed in the table. The implementer of the table, in this case a message store provider, supplies a default set of columns in a default order. The client can modify this column set, requesting additional columns or rejecting default ones, and ask that they be ordered in a specific way. The client can also order the rows, sorting them according to the value of one or more columns.

Using a table to display folder contents

Using a table to display folder contents

There are two interfaces for working with tables:

  • IMAPITable : IUnknown gives clients and service providers a read-only view of the underlying data of the table, allowing them to view and change only the presentation. Multiple users can access the same data concurrently with IMAPITable. IMAPITable is implemented by MAPI and by service providers.

  • ITableData : IUnknown gives clients and service providers read/write access to the underlying data of the table, allowing them to make permanent changes. IMAPITable is implemented by MAPI and used primarily by service providers who access it by calling the CreateTable function. The ITableData implementation holds all the data for the table and any associated restrictions in memory, making it unsuitable for use with very large tables. Compound restrictions and complex operations such as categorization are unsupported.

See also

Other resources

MAPI Concepts


Types of Tables

 Copy code hover
[image]

Types of Tables
See also Send feedback

Published: July 16, 2012

There are many different types of tables, each type differentiated by the information that it presents. Tables enable client applications and service providers to readily access and manipulate the important properties of many types of objects.

Some tables, such as contents tables, provide an alternative way of accessing properties. For example, a client can retrieve the subject of a message — its PR_SUBJECT (PidTagSubject) property — either directly from the message by calling its IMAPIProp::GetProps method or through the message's contents table. Other tables provide the only way to access object properties. For example, a client cannot access an attachment's PR_ATTACH_METHOD (PidTagAttachMethod) property by calling IMAPIProp::GetProps; it must always retrieve the attachment table of the message to which it is attached. PR_ATTACH_METHOD is a required column in all attachment tables.

A table view can be static or dynamic. With a static table view, changes to the underlying data do not cause the view to be updated. Once the view has been instantiated, it does not change. Users of static tables can be informed of changes to data through table notifications. A dynamic table view is updated when changes are made to the data. There are two types of dynamic tables: one that updates the columns of each row, but the rows remain static and one that updates both the columns and rows. This latter type of table always reflects the underlying data exactly.

Tables have a default column set, the minimum set of columns that a client or service provider can expect to see when retrieving rows from a table that has not yet been affected by an IMAPITable::SetColumns call. Clients and service providers can add columns to or remove columns from this default set by calling the SetColumns method. Changes can be made either statically or dynamically, following a client request. Not all tables support dynamic column set modification.

The MAPI tables and their implementers and users are:

Table | Implementers
Attachment | Implemented by message store providers. Used by clients and transport providers.
Contents | Implemented by message store and address book providers. Used by clients.
Display | Implemented by MAPI and service providers. Used by MAPI and service providers.
Hierarchy | Implemented by message store and address book providers. Used by clients.
Message service | Implemented by MAPI. Used by clients.
Message store | Implemented by MAPI. Used by clients.
One-off | Implemented by address book providers. Used by MAPI.
Outgoing queue | Implemented by message store providers. Used by MAPI spooler.
Profile | Implemented by MAPI. Used by clients.
Provider | Implemented by MAPI. Used by clients.
Receive folder | Implemented by message store providers. Used by clients.
Recipient | Implemented by message store providers. Used by clients and transport providers.
Status | Implemented by MAPI and service providers. Used by clients.

See also

Concepts

MAPI Tables


Attachment Tables

 Copy code hover
[image]

Attachment Tables
See also Send feedback

Published: July 16, 2012

An attachment table contains information about all of the attachment objects that are associated with a submitted message or a message under composition.

Only attachments that have been saved through a call to the message's IMAPIProp::SaveChanges method are included in the table. Attachment tables are implemented by message store providers and used by client applications and transport providers.

An attachment table can be accessed by calling:

  • IMessage::GetAttachmentTable.

    - Or -

  • IMAPIProp::OpenProperty, requesting the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property.

Attachment tables are dynamic.

Message store providers are not required to support sorting on their attachment tables. If sorting is not supported, the table must be presented in order by rendering position — the PR_RENDERING_POSITION (PidTagRenderingPosition) property.

Message store providers are also not required to support restrictions on their attachment tables. Providers that do not support restrictions return MAPI_E_NO_SUPPORT from their implementations of IMAPITable::Restrict and IMAPITable::FindRow.

Attachment tables can be small; there are only four columns in the required column set:

  • PR_ATTACH_NUM (PidTagAttachNumber)

  • PR_INSTANCE_KEY (PidTagInstanceKey)

  • PR_RECORD_KEY (PidTagRecordKey)

  • PR_RENDERING_POSITION

PR_ATTACH_NUM is nontransmittable and contains a value for uniquely identifying an attachment within a message. This property is often used as an index into the rows of the table. PR_ATTACH_NUM has a short lifespan; it is only valid while the message containing the attachment is open. Its value is guaranteed to remain constant as long as the attachment table is open.

PR_INSTANCE_KEY is required in nearly every table. It is used to uniquely identify a particular row.

PR_RECORD_KEY is commonly used to uniquely identify an object for comparison purposes. Unlike PR_ATTACH_NUM, PR_RECORD_KEY has the same scope as a long-term entry identifier; it remains available and valid even after the message is closed and reopened. For more information about the use of record keys in MAPI, see MAPI Record and Search Keys.

PR_RENDERING_POSITION indicates how an attachment should be displayed in a rich text message. It can be set to an offset in characters, with the first character of the message content as stored in the PR_BODY (PidTagBody) property being offset 0, or to -1 (0xFFFFFFFF), indicating that the attachment should not be rendered within the message text at all. Not setting PR_RENDERING_POSITION is also an option.

When an attachment table is sorted by rendering position, the message store provider treats it as a signed value (PT_LONG). Therefore, attachments with rendering positions of -1 are sorted before attachments with rendering positions that reflect valid offsets.

For more information about rendering an attachment in a plain text message, see Rendering an Attachment in Plain Text.

For information about rendering an attachment in formatted text such as Rich Text Format (RTF), see Rendering an Attachment in RTF Text.

Some of the properties message store providers commonly include in an attachment table because they are easy to compute or retrieve are:

PR_ATTACH_ENCODING (PidTagAttachEncoding) | PR_ATTACH_EXTENSION (PidTagAttachExtension)
PR_ATTACH_FILENAME (PidTagAttachFilename) | PR_ATTACH_LONG_FILENAME (PidTagAttachLongFilename)
PR_ATTACH_PATHNAME (PidTagAttachPathname) | PR_ATTACH_LONG_PATHNAME (PidTagAttachLongPathname)
PR_ATTACH_METHOD (PidTagAttachMethod) | PR_ATTACH_TAG (PidTagAttachTag)
PR_CREATION_TIME (PidTagCreationTime) | PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName)
PR_DISPLAY_NAME (PidTagDisplayName) | PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime)

See also

Concepts

MAPI Tables


Contents Tables

 Copy code hover
[image]

Contents Tables
See also Send feedback

Published: July 16, 2012

A contents table contains information about objects in a MAPI container. Address book providers implement contents tables for each of their containers, and message store and remote transport providers implement contents tables for their folders. The contents table of an address book container lists information about its messaging user and distribution list objects, while the contents table of a folder lists information about its messages. Contents tables are used primarily by client applications.

There are two types of folder contents tables:

  • Standard contents tables contain standard messages — messages that can be transmitted and made visible to a user.

  • Associated contents tables contain hidden, non-transmittable information created by a client for a specific purpose, such as to store an alternate representation of a standard message. Associated information is created by passing the MAPI_ASSOCIATED flag to the IMAPIFolder::CreateMessage call.

The contents tables of most address book containers and many folders do not support categorized sorting.

A contents table can be accessed by calling:

  • IMAPIContainer::GetContentsTable.

    - Or -

  • IMAPIProp::OpenProperty with PR_CONTAINER_CONTENTS (PidTagContainerContents) or PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) (folders only) specified as the property tag and IID_IMAPITable as the interface identifier.

Message store and address book providers must support both techniques for retrieving table properties. It is unacceptable for providers to support only one way for accessing these tables because clients expect to have the choice.

GetContentsTable accepts as input several flags that specify preferences. When set, the MAPI_ASSOCIATED flag retrieves an associated contents table. Because some folders do not support associated contents, and there is no way for clients to determine this ahead of time, GetContentsTable sometimes returns the error MAPI_E_NO_SUPPORT when an associated contents table is requested.

The MAPI_DEFERRED_ERRORS flag indicates to the implementer of the table that any errors encountered during the call do not need to be reported until some later time.

The call to IMAPIProp::OpenProperty involves accessing a contents table by opening its corresponding property, PR_CONTAINER_CONTENTS for address book contents tables and standard folder contents tables, and PR_FOLDER_ASSOCIATED_CONTENTS for associated contents tables. Although neither or these properties can be retrieved through a folder or container's IMAPIProp::GetProps method, they are included in the property tag array that is returned by the IMAPIProp::GetPropList method.

PR_CONTAINER_CONTENTS can also be used to include or exclude a contents table from a copy operation. If a client specifies PR_CONTAINER_CONTENTS in the lpExcludeProps parameter for IMAPIProp::CopyTo in a copy operation, the new folder or container will not support the contents table of the original folder or container.

Address book container and folder contents tables have a lengthy list of required columns — columns that clients can expect to be available after they retrieve the table from GetContentsTable or OpenProperty. Providers can add to this required set if necessary and clients, through the SetColumns method, can also request modifications.

The required columns for each of the types of contents tables are:

Required column | Type of contents table
PR_ADDRTYPE (PidTagAddressType) | Address book container tables
PR_DISPLAY_NAME (PidTagDisplayName) | Address book container tables
PR_DISPLAY_CC (PidTagDisplayCc) | Message store folder tables
PR_DISPLAY_TO (PidTagDisplayTo) | All folder contents tables
PR_DISPLAY_TYPE (PidTagDisplayType) | Address book container tables
PR_ENTRYID (PidTagEntryId) | All contents tables
PR_HASATTACH (PidTagHasAttachments) | All folder contents tables
PR_INSTANCE_KEY (PidTagInstanceKey) | All contents tables
PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime) | Message store folder tables
PR_MAPPING_SIGNATURE (PidTagMappingSignature) | Message store folder tables
PR_MESSAGE_CLASS (PidTagMessageClass) | All folder contents tables
PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime) | Remote transport folder tables
PR_MESSAGE_FLAGS (PidTagMessageFlags) | All folder contents tables
PR_MESSAGE_SIZE (PidTagMessageSize) | All folder contents tables
PR_MSG_STATUS (PidTagMessageStatus) | All folder contents tables
PR_OBJECT_TYPE (PidTagObjectType) | All contents tables
PR_PARENT_ENTRYID (PidTagParentEntryId) | Message store folder tables
PR_RECORD_KEY (PidTagRecordKey) | Address book container and message store folder tables
PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) | Remote transport folder tables
PR_STORE_ENTRYID (PidTagStoreEntryId) | Message store folder tables
PR_STORE_RECORD_KEY (PidTagStoreRecordKey) | Message store folder tables

The entry identifier available with each row can either be a short- or long-term entry identifier, depending on the table implementation. Short-term entry identifiers are typically used in situations where performance is an issue. Either type of entry identifier can be used to access the corresponding object.

Contents tables also have a set of columns that are optional but commonly included by service providers in their implementations. These optional columns are:

Optional column | Type of contents table
PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) | Message store folder tables
PR_CONTENT_COUNT (PidTagContentCount) | Standard folder contents tables
PR_CONTENT_UNREAD (PidTagContentUnreadCount) | Standard folder contents tables
PR_CONVERSATION_INDEX (PidTagConversationIndex) | Message store folder tables
PR_EMAIL_ADDRESS (PidTagEmailAddress) | Address book container tables
PR_IMPORTANCE (PidTagImportance) | All folder contents tables
PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) | All folder contents tables
PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) | All folder contents tables
PR_PRIORITY (PidTagPriority) | All folder contents tables
PR_SEARCH_KEY (PidTagSearchKey) | Address book container tables
PR_SEND_RICH_INFO (PidTagSendRichInfo) | Address book container tables
PR_SENDER_NAME (PidTagSenderName) | All folder contents tables
PR_SENSITIVITY (PidTagSensitivity) | All folder contents tables
PR_SUBJECT (PidTagSubject) | All folder contents tables
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName) | Address book container tables

Message store providers must also include PR_PARENT_DISPLAY (PidTagParentDisplay) for search-result folders contents tables only.

Named properties may be added to the column set of a folder contents table only if all messages in the folder have the same mapping signature, that is, the same mapping of property names to property identifiers. Folder contents tables should support adding message class specific properties to the column set, if they support the creation of arbitrary messages in the folder.

Clients can save the default sort order for a folder contents table by calling its IMAPIFolder::SaveContentsSort method. If the RECURSIVE_SORT flag is specified on the call, the sort order can be made to apply to all of the subfolders within the folder.

See also

Concepts

MAPI Tables


Display Tables

 Copy code hover
[image]

Display Tables
See also Send feedback

Published: July 16, 2012

A display table describes how to show a specific type of dialog box — one having one or more tabbed property pages dedicated to displaying and possibly editing one or more properties. Associated with every display table is an IMAPIProp : IUnknown interface implementation. The IMAPIProp implementation maintains the property data that is presented in the dialog box.

The rows in a display table represent the controls, or user interface objects, that are displayed in the dialog box. MAPI defines many types of controls, some with static values and some with dynamic values that a user can change. Most controls can be associated with properties maintained with the IMAPIProp implementation. When a user changes the value of a modifiable control, the corresponding property is updated.

Service providers implement display tables and the IMAPIProp interface. Creating a display table is similar to writing a program with a scripting language. Service providers can create a display table by:

  • Calling the BuildDisplayTable function.

    - Or -

  • Including custom code that populates the display table directly using a table data object — an object that supports the ITableData : IUnknown interface.

The BuildDisplayTable function combines information from display table structures with visual elements from a dialog box resource to build display table rows. The function returns a pointer to an IMAPITable : IUnknown interface implementation, and, if requested, a pointer to an ITableData interface implementation.

Using BuildDisplayTable to create a display table is straightforward and makes maintenance easier when visual elements of the display change. However, service providers that prefer not to use BuildDisplayTable can create a display table with custom code that uses the methods of ITableData. For example, service providers that have an existing template structure for their property pages might want to create custom code rather than use BuildDisplayTable.

There are a variety of ways service providers can implement the property interface for their display table. These include:

  • Supplying a standard IMAPIProp : IUnknown implementation.

  • Supplying a wrapped IMAPIProp implementation that includes special processing before making the standard calls.

  • Supplying an IPropData : IMAPIProp implementation.

The type of implementation depends on the characteristics of the data to be displayed and the responsible service provider. For example, if there is an implicit relationship between the data in two edit controls and one of the controls changes, the IMAPIProp implementation must change the value of the other control appropriately.

Display tables have the following properties in their required column set:

PR_XPOS (PidTagXCoordinate) | PR_YPOS (PidTagYCoordinate)
PR_DELTAX (PidTagDeltaX) | PR_DELTAY (PidTagDeltaY)
PR_CONTROL_TYPE (PidTagControlType) | PR_CONTROL_FLAGS (PidTagControlFlags)
PR_CONTROL_STRUCTURE (PidTagControlStructure) | PR_CONTROL_ID (PidTagControlId)

PR_XPOS and PR_YPOS specify the X and Y coordinates of the upper left corner of the control. The horizontal units are 1/4 of the dialog base width unit; the vertical units are 1/8 of the dialog base height unit. Windows computes the current dialog base units from the height and width of the current system font. The coordinates are relative to the origin of the property page area. The size of property pages is limited to approximately 200 by 180 dialog units.

PR_DELTAX and PR_DELTAY are the width and height of the control. These are ULONG values. The width units are 1/4 of the dialog base width unit; the height units are 1/8 of the dialog base height unit. The coordinates are relative to the origin of the control.

The other four properties describe various characteristics of the control. PR_CONTROL_TYPE indicates the type of control. MAPI defines twelve types of controls, each with a different set of attributes. These attributes are described in the flags property, PR_CONTROL_FLAGS. Examples of attributes include whether or not a control is editable or required.

The control structure, PR_CONTROL_STRUCTURE, contains information relevant to the particular type of control. Each type of control is described with a different structure. For example, edit controls are described with the DTBLEDIT structure. DTBLEDIT structures contain members that list the number of and specific types of characters that can be placed on the control and a property tag that identifies the property whose value is to be displayed in the control. PR_CONTROL_STRUCTURE is stored as a binary property.

The control identifier, PR_CONTROL_ID, uniquely identifies the control in the dialog box described by the display table. PR_CONTROL_ID is set from the values placed in the lpbNotif and cbNotif members of the DTCTL structure that is used by BuildDisplayTable to create the display table. Because MAPI sometimes combines display tables, the identifier in PR_CONTROL_ID should always be unique. Typically, providers assign a GUID structure to PR_CONTROL_ID to ensure its uniqueness. The PR_CONTROL_ID property is included in the TABLE_NOTIFICATION structure when a display table notification is generated.

For more information about display tables, see Display Table Implementation and About Display Table Notifications.

See also

Concepts

MAPI Tables


Hierarchy Tables

 Copy code hover
[image]

Hierarchy Tables
See also Send feedback

Published: July 16, 2012

A hierarchy table contains information about the folders in a message store or the containers in an address book container. Each row of a hierarchy table contains a set of columns with information about one folder or address book container. Hierarchy tables are primarily used by clients and implemented by message store providers to show a tree of folders and subfolders and implemented by address book providers to show a tree of containers in the address book. Containers that cannot hold subcontainers, as indicated by the absence of the AB_SUBCONTAINERS flag in their PR_CONTAINER_FLAGS (PidTagContainerFlags) property, do not implement a hierarchy table.

A hierarchy table can be accessed by calling:

  • IMAPIContainer::GetHierarchyTable.

    - Or -

  • IMAPIProp::OpenProperty passing PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) as the property tag and IID_IMAPITable as the interface identifier.

Containers and folders must support both techniques for retrieving table properties. It is unacceptable for service providers to support only one way to access these tables because clients expect to have the choice.

Important note Important

Store providers are not guaranteed to honor the sort order set specified for hierarchy tables.

The call to IMAPIProp::OpenProperty involves accessing the hierarchy table by opening its corresponding property, PR_CONTAINER_HIERARCHY. Although PR_CONTAINER_HIERARCHY cannot be retrieved through a folder or container's IMAPIProp::GetProps method, it is included in the property tag array that is returned by the IMAPIProp::GetPropList method.

PR_CONTAINER_HIERARCHY can also be used to include or exclude a hierarchy table from a copy operation. If a client specifies PR_CONTAINER_HIERARCHY in the lpExcludeProps parameter for IMAPIProp::CopyTo in a copy operation, the new folder or container will not support the hierarchy table of the original folder or container.

The following properties make up the required column set in a hierarchy table:

PR_COMMENT (PidTagComment) | PR_DEPTH (PidTagDepth)
PR_DISPLAY_NAME (PidTagDisplayName) | PR_DISPLAY_TYPE (PidTagDisplayType)
PR_ENTRYID (PidTagEntryId) | PR_INSTANCE_KEY (PidTagInstanceKey)
PR_OBJECT_TYPE (PidTagObjectType) | PR_STATUS (PidTagStatus)

PR_DISPLAY_NAME contains the name for the container or folder that should appear in the display of the hierarchy.

PR_ENTRYID is the entry identifier associated with this container or folder. It is expected to be a long-term entry identifier. Clients and MAPI can pass this entry identifier to OpenEntry to open the container or folder and view its contents by calling IMAPIContainer::GetContentsTable.

PR_DEPTH is a numeric value that indicates the level of indentation for this container or folder with zero being the top level. The deeper in the hierarchy a container or folder resides, the higher the value for its PR_DEPTH property. Clients use the PR_DEPTH property to display a hierarchy table appropriately so that users can clearly see parent and child relationships. Container or folder depth is always relative to the container or folder implementing the hierarchy table.

PR_OBJECT_TYPE is always set to MAPI_ABCONT for address book hierarchy tables and MAPI_FOLDER for folder hierarchy tables.

PR_DISPLAY_TYPE is a numeric value that relates to how a container or folder is displayed in the hierarchy table. It is mainly used for display purposes, to differentiate visually between types of containers or folders. Many message store and address book providers use icons for the different display types. It is up to the provider to supply these icons; MAPI does not supply defaults.

MAPI defines many values for PR_DISPLAY_TYPE, some that are valid for folders and others that are used with the hierarchy tables of address book containers. Typically, a folder's PR_DISPLAY_TYPE is set to DT_FOLDER to indicate a default folder icon, DT_FOLDER_LINK to indicate an icon that represents a link to another folder, or DT_FOLDER_SPECIAL to indicate an icon that is application-specific. DT_FOLDER_LINK is used with search-results folders.

In addition to these required columns, address book hierarchy tables must include the PR_CONTAINER_FLAGS property. PR_CONTAINER_FLAGS indicates various attributes about a container in the hierarchy and is used to distinguish one container from another.

An optional property for address book hierarchy tables is the PR_AB_PROVIDER_ID (PidTagAbProviderId) property.

Message-store hierarchy tables include these properties in their required column set:

  • PR_FOLDER_TYPE (PidTagFolderType)

  • PR_SUBFOLDERS (PidTagSubfolders)

  • PR_CONTENT_COUNT (PidTagContentCount)

  • PR_CONTENT_UNREAD (PidTagContentUnreadCount)

Address book providers must support the following IMAPITable methods in their hierarchy table implementations because they are required by the MAPI integrated address book:

IMAPITable::QueryColumns | IMAPITable::QueryPosition
IMAPITable::SeekRow | IMAPITable::SeekRowApprox
IMAPITable::FindRow | IMAPITable::Restrict
IMAPITable::CreateBookmark | IMAPITable::FreeBookmark
IMAPITable::QueryRows |

See also

Concepts

MAPI Tables


Message Service Tables

 Copy code hover
[image]

Message Service Tables
See also Send feedback

Published: July 16, 2012

The message service table contains information about the message services in the current profile. There is one message service table for every MAPI session, implemented by MAPI and used by special purpose client applications that provide configuration support.

The message service table is a static table.

Clients access the message service table by calling the IMsgServiceAdmin::GetMsgServiceTable method.

The following properties make up the required column set in the message service table:

PR_DISPLAY_NAME (PidTagDisplayName) | PR_INSTANCE_KEY (PidTagInstanceKey)
PR_RESOURCE_FLAGS (PidTagResourceFlags) | PR_SERVICE_DLL_NAME (PidTagServiceDllName)
PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) | PR_SERVICE_NAME (PidTagServiceName)
PR_SERVICE_SUPPORT_FILES (PidTagServiceSupportFiles) | PR_SERVICE_UID (PidTagServiceUid)

PR_DISPLAY_NAME is the displayable name for the message service and the default sort key column.

PR_INSTANCE_KEY serves as the index column for the table, uniquely identifying a row.

PR_RESOURCE_FLAGS describes the message service's capabilities.

PR_SERVICE_DLL_NAME is the name of the DLL that contains the message service implementation.

PR_SERVICE_ENTRY_NAME is the name of the message service's entry point function that conforms to the MSGSERVICEENTRY prototype.

PR_SERVICE_NAME is a required entry in the [Services] section in MAPISVC.INF. The value for this property will never be changed or localized. PR_SERVICE_NAME can be used to programmatically identify the message service.

PR_SERVICE_SUPPORT_FILES is a list of files that must be installed with the message service.

PR_SERVICE_UID is a unique identifier for the message service.

See also

Concepts

MAPI Tables


Message Store Tables

 Copy code hover
[image]

Message Store Tables
See also Send feedback

Published: July 16, 2012

The message store table contains information about message store providers in the current profile. There is one message store table for every MAPI session, implemented by MAPI and used by clients. Clients can use this table, for example, to locate all instances of a particular provider or to locate a specific message store.

The message store table is dynamic. If the user of a client application edits the profile, changing the default message store, for example, the values of the PR_DEFAULT_STORE properties for the affected message stores are immediately updated.

Clients access the message store table by calling the IMAPISession::GetMsgStoresTable method.

The following properties make up the required column set in the message store table:

PR_DEFAULT_STORE (PidTagDefaultStore) | PR_DISPLAY_NAME (PidTagDisplayName)
PR_ENTRYID (PidTagEntryId) | PR_INSTANCE_KEY (PidTagInstanceKey)
PR_MDB_PROVIDER (PidTagStoreProvider) | PR_OBJECT_TYPE (PidTagObjectType)
PR_PROVIDER_DISPLAY (PidTagProviderDisplay) | PR_RECORD_KEY (PidTagRecordKey)
PR_RESOURCE_FLAGS (PidTagResourceFlags) | PR_RESOURCE_TYPE (PidTagResourceType)

See also

Concepts

MAPI Tables


One-Off Tables

 Copy code hover
[image]

One-Off Tables
See also Send feedback

Published: July 16, 2012

A one-off table contains information about the templates that an address book provider supports for creating new recipients. One-off tables are implemented by address book providers, individual address book containers, and by MAPI, and can be persistent or temporary.

Note Note

Do not confuse the templates in one-off tables with template identifiers; while their purposes are similar, their code constructs are nothing alike. Templates are used to create recipients of a particular type while template identifiers are used to bind the data of one recipient that belong to a host provider with code to support another recipient that belong to a foreign provider.

Clients create new recipients:

  • To add to the recipient list of an outgoing message.

  • To add to one of the containers in the address book.

In both scenarios, an address book provider is asked to return a one-off table. Address book providers can implement either a single one-off table to be used in both situations or a unique one-off table for each situation.

When the recipient will be included with an outgoing message, MAPI calls the address book provider's IABLogon::GetOneOffTable method to retrieve its one-off table. The one-off table includes templates which enable a user to enter information resulting in the creation of a recipient with a valid address. MAPI registers for notifications on this table, keeping it open so that changes can be reflected to the user. MAPI releases the table only when its subsystem or address book status object's IMAPIStatus::ValidateState method is called.

When the recipient will be added to a container, MAPI makes a different call, invoking the container's IMAPIProp::OpenProperty method to retrieve its PR_CREATE_TEMPLATES (PidTagCreateTemplates) property. The set of templates included in this one-off table represents the types of recipients that can be added to the container. For example, mail servers often expose one container for every gateway that is installed so that each container only holds addresses specific to the corresponding gateway.

MAPI provides a one-off table that includes its own templates as well as templates from each of the address book providers in the session. MAPI provides a generic template that can be used to create a new recipient for any address type, assuming that the user knows its format. Address book providers use this one-off table by calling IMAPISupport::GetOneOffTable. Each of the templates included in the MAPI one-off table results in the creation of recipients with valid recipient addresses.

Address book providers typically supply one template for every address type they support. However, support for templates is not required. Address book providers that do not allow the creation of new addresses can return MAPI_E_NO_SUPPORT when MAPI calls to request a one-off table. Address book providers that do allow new address creation but do not supply any templates can call IMAPISupport::GetOneOffTable to use the templates listed in the MAPI one-off table.

The following properties make up the required column set in one-off tables:

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_DEPTH (PidTagDepth)

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_DISPLAY_TYPE (PidTagDisplayType)

  • PR_ENTRYID (PidTagEntryId)

  • PR_INSTANCE_KEY (PidTagInstanceKey)

  • PR_SELECTABLE (PidTagSelectable)

PR_ADDRTYPE indicates the type of address that can be associated with the new recipient created with the template.

PR_DISPLAY_NAME and PR_DISPLAY_TYPE associate data with the new recipient. PR_DISPLAY_NAME contains a character string that identifies the new recipient and PR_DISPLAY_TYPE contains a constant that identifies the type of icon to be displayed with the row. Templates for messaging users have their PR_DISPLAY_TYPE column set to DT_MAILUSER; templates for distribution lists have their PR_DISPLAY_TYPE column set to DT_DISTLIST.

PR_ENTRYID is the entry identifier of the template to be used to create a new recipient. This entry identifier can be passed to future IAddrBook::NewEntry, IAddrBook::OpenEntry, and IABContainer::CreateEntry calls. Containers set the PR_ENTRYID column of their row for the default messaging user template to PR_DEF_CREATE_MAILUSER (PidTagDefCreateMailuser) and the PR_ENTRYID column of their row for the default distribution list template to PR_DEF_CREATE_DL (PidTagDefCreateDl).

PR_DEPTH is used to support the hierarchical display of the entries in a one-off table by indicating the level of indentation for the template. Although one-off tables can be displayed either as a flat list or a hierarchical display, the latter is preferable and address book providers should support it by setting the PR_DEPTH column for each row appropriately. PR_DEPTH is zero-based; rows with a value of 0 in their PR_DEPTH column are not indented. The higher the value of PR_DEPTH, the more the row is indented. For example, rows with PR_DEPTH set to 1 are indented one tab while rows with PR_DEPTH set to 3 are indented three tabs.

PR_SELECTABLE is used to indicate whether a row in the table represents a template that can be selected and used to create a new recipient. Although most rows in a one-off table do represent templates, providers can include non-template rows. For example, a provider might want to organize the one-off table by template type, including a category row that appears in the display but is not used for recipient creation.

See also

Concepts

MAPI Tables


Outgoing Queue Tables

 Copy code hover
[image]

Outgoing Queue Tables
See also Send feedback

Published: July 16, 2012

An outgoing queue table contains information about all the outgoing messages for a message store. Message store providers implement outgoing queue tables for the MAPI spooler to use. Stores that do not support the sending or receiving of messages need not implement this table.

To access an outgoing queue table, the MAPI spooler calls the IMsgStore::GetOutgoingQueue method.

There is a requirement that messages be preprocessed and submitted to the transport provider in the same order as they were sent by the client application. The MAPI spooler is designed to accept messages from the message store in ascending order of submission time. Because of this requirement, there can be some delay before some messages appear in the outgoing queue table.

Message stores should either allow sorting on the outgoing queue table so that the MAPI spooler can sort the messages by submission time, or the default sort order should be by ascending submission time.

The outgoing queue table must send notifications when the contents of the queue changes.

The following properties make up the required column set in outgoing queue tables:

PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) | PR_DISPLAY_BCC (PidTagDisplayBcc)
PR_DISPLAY_CC (PidTagDisplayCc) | PR_DISPLAY_TO (PidTagDisplayTo)
PR_ENTRYID (PidTagEntryId) | PR_MESSAGE_FLAGS (PidTagMessageFlags)
PR_MESSAGE_SIZE (PidTagMessageSize) | PR_PRIORITY (PidTagPriority)
PR_SENDER_NAME (PidTagSenderName) | PR_SUBJECT (PidTagSubject)
PR_SUBMIT_FLAGS (PidTagSubmitFlags) |

For more information about how the outgoing queue table is used, see Sending Messages by Using Message Store Providers.

See also

Concepts

MAPI Tables


Profile Tables

 Copy code hover
[image]

Profile Tables
See also Send feedback

Published: July 16, 2012

The profile table lists information about all profiles associated with a particular client application. There is one profile table for every session, implemented by MAPI for use by clients.

Clients access the profile table by calling the IProfAdmin::GetProfileTable method.

The profile table is a static table. Profiles that have been marked for deletion are not included in the profile table.

As with most table implementations, if GetProfileTable is called and there are no profiles available to the client, the table is created with zero rows.

The following properties make up the required column set in profile tables:

PR_DEFAULT_PROFILE (PidTagDefaultProfile)

PR_DISPLAY_NAME (PidTagDisplayName)

See also

Concepts

MAPI Tables


Provider Tables

 Copy code hover
[image]

Provider Tables
See also Send feedback

Published: July 16, 2012

A provider table contains information about service providers. There are two different provider tables, both implemented by MAPI and used by clients. The first table, accessed by calling the IMsgServiceAdmin::GetProviderTable method, holds information about all of the providers for the current profile. The second table, accessed through IProviderAdmin::GetProviderTable, creates a table that stores information about all of the service providers for a message service.

These two tables have another difference. The provider table available through IMsgServiceAdmin::GetProviderTable contains only rows that represent service providers while the table available through IProviderAdmin::GetProviderTable may include rows that represent additional information associated with a service provider. This extra information is added to the profile with the "Sections" keyword of MAPISVC.INF. When a provider has extra profile sections, it stores the MAPIUID values for these sections in the PR_SERVICE_EXTRA_UIDS (PidTagServiceExtraUids) property. PR_SERVICE_EXTRA_UIDS is saved in the message service profile section.

The following properties make up the required column set in both types of provider tables:

PR_INSTANCE_KEY (PidTagInstanceKey) | PR_DISPLAY_NAME (PidTagDisplayName)
PR_PROVIDER_DISPLAY (PidTagProviderDisplay) | PR_PROVIDER_DLL_NAME (PidTagProviderDllName)
PR_PROVIDER_ORDINAL (PidTagProviderOrdinal) | PR_PROVIDER_UID (PidTagProviderUid)
PR_RESOURCE_FLAGS (PidTagResourceFlags) | PR_RESOURCE_TYPE (PidTagResourceType)
PR_SERVICE_NAME (PidTagServiceName) | PR_SERVICE_UID (PidTagServiceUid)

The provider table can be used to display the current transport order or to change it. To display the current order, build a restriction to retrieve only those rows with the PR_RESOURCE_TYPE property set to MAPI_TRANSPORT_PROVIDER. Then use PR_PROVIDER_ORDINAL as a sort key to sort the table and retrieve all the rows with either the IMAPITable::QueryRows method or the HrQueryAllRows function.

To change the transport order, apply the same restriction and retrieve the rows. Then create an array of values from the PR_PROVIDER_UID property that represents the unique identifiers for the transport providers. When the identifiers are in the desired order, pass them to the IMsgServiceAdmin::MsgServiceTransportOrder method.

After a provider table has been made available, it will not reflect subsequent changes, such as the addition or deletion of a provider.

See also

Concepts

MAPI Tables


Receive Folder Tables

 Copy code hover
[image]

Receive Folder Tables
See also Send feedback

Published: July 16, 2012

A receive folder table contains information for all the folders designated as receive folders for a message store. A receive folder is a folder where incoming messages of a particular message class are placed. Message store providers implement receive folder tables and client applications use them by making a call to the IMsgStore::GetReceiveFolderTable method.

The following properties make up the required column set in receive folder tables:

PR_ENTRYID (PidTagEntryId)

PR_MESSAGE_CLASS (PidTagMessageClass)

PR_RECORD_KEY (PidTagRecordKey)

See also

Concepts

MAPI Tables


Recipient Tables

 Copy code hover
[image]

Recipient Tables
See also Send feedback

Published: July 16, 2012

The recipient table contains information about all the recipients for a message. Message store providers implement recipient tables and client applications use them. Clients access a recipient table by making a call to the IMessage::GetRecipientTable method, or if the message store provider supports it, to the IMAPIProp::OpenProperty method. Clients access recipient tables with OpenProperty by specifying PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) for the property tag and IID_IMAPITable for the interface identifier. Changes to a recipient table can be made by calling the IMessage::ModifyRecipients method.

Recipient tables have a different column set depending on whether the message has been submitted. The following properties make up the required column set in recipient tables:

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_RECIPIENT_TYPE (PidTagRecipientType)

  • PR_ROWID (PidTagRowid)

The optional properties are:

  • PR_DISPLAY_TYPE (PidTagDisplayType)

  • PR_ENTRYID (PidTagEntryId)

  • PR_SPOOLER_STATUS (PidTagSpoolerStatus)

  • PR_OBJECT_TYPE (PidTagObjectType)

Submitted messages should include these additional properties in their required column set:

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_RESPONSIBILITY (PidTagResponsibility)

Depending on a provider's implementation, additional columns, such as PR_SENDER_NAME (PidTagSenderName) and ENTRYID, might be in the table.

Any message store provider that supports message transmission — as indicated by the STORE_SUBMIT_OK bit being set in the provider's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property — should offer support for a particular set of restrictions in a recipient table implementation. The AND, OR, exist, and property restrictions are among the types of restrictions that should be available to recipient table users. Only the equal and not equal operators need to be supported on the property restriction. These restrictions must work with the following properties:

  • PR_ADDRTYPE

  • PR_EMAIL_ADDRESS (PidTagEmailAddress)

  • PR_RECIPIENT_TYPE

  • PR_RESPONSIBILITY

  • PR_SPOOLER_STATUS

See also

Concepts

MAPI Tables


Status Tables

 Copy code hover
[image]

Status Tables
See also Send feedback

Published: July 16, 2012

The status table contains information relating to the state of the current session. There is one status table for every MAPI session that includes information provided by MAPI and by service providers. MAPI provides data for three rows: a row for the MAPI subsystem, a row for the MAPI spooler, and a row for the integrated address book. Because transport providers are required to supply status information to the status table, there is one row for every active transport provider. Address book and message store providers can choose whether to support the status table.

Because each row is provided by a different resource, the set of columns can vary from row to row. There is a set of columns that every status object is required to supply and a set of columns that MAPI supplies. A service provider can add to these sets to expose provider-specific properties. For example, message store providers might add PR_STORE_RECORD_KEY (PidTagStoreRecordKey) to supply clients with the identifier of their message store. Clients must have advance knowledge of the existence of this extra information to be able to use it.

The following table lists the properties that must be in every status table row. The implementer of the status object provides some of the properties; others are computed by MAPI.

Properties provided by status object | Properties provided by MAPI
PR_DISPLAY_NAME (PidTagDisplayName) | PR_PROVIDER_DLL_NAME (PidTagProviderDllName)
PR_STATUS_CODE (PidTagStatusCode) | PR_RESOURCE_FLAGS (PidTagResourceFlags)
PR_RESOURCE_METHODS (PidTagResourceMethods) | PR_RESOURCE_TYPE (PidTagResourceType)

If the status object provides an identity, it should set PR_IDENTITY_DISPLAY (PidTagIdentityDisplay), PR_IDENTITY_ENTRYID (PidTagIdentityEntryId), and PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey), and include these properties in the table.

Four properties are computed by MAPI for each status table row:

PR_ENTRYID (PidTagEntryId) | PR_INSTANCE_KEY (PidTagInstanceKey)
PR_OBJECT_TYPE (PidTagObjectType) | PR_ROWID (PidTagRowid)

MAPI assigns an entry identifier to the status row to enable clients to open the corresponding status object. A row identifier is also assigned to identify the row in the table as is an instance key to identify the data in the status object. The PR_OBJECT_TYPE property is set to MAPI_STATUS.

To access the status table, clients call the IMAPISession::GetStatusTable method. This call should not be made immediately upon startup. This is because GetStatusTable has to wait for the MAPI spooler to initialize the transport providers, an operation that is postponed until after the client has finished its logon. GetStatusTable is a relatively fast call after the MAPI spooler has completed its startup processing.

Status table information can be used in a variety of ways, such as to access a status object, to determine whether a client is running in a connected or offline mode, and to monitor a provider's state. For example, clients can open a specific service provider's status object by passing the value of the PR_ENTRYID property to the IMAPISession::OpenEntry method. The status object supports the IMAPIStatus interface, an interface that contains methods to change a service provider password, flush the message queue, display a configuration property sheet, or confirm status with a provider directly. Status table information can also be used to build a dialog box to inform clients of progress during a lengthy operation.

Service providers who do support the status table use the IMAPISupport::ModifyStatusRow method to create and update their row. Whenever a change occurs to their row, all advise sink objects registered to receive status table notifications must be notified. Service providers can call the IMAPISupport::Notify method if they are using the MAPI notification utility or call each advise sink's IMAPIAdviseSink::OnNotify method directly.

See also

Concepts

MAPI Tables


Tips for Working with Tables

 Copy code hover
[image]

Tips for Working with Tables
See also Send feedback

Published: July 16, 2012

Working with a MAPI table is a little like working with a relational database table. A user can limit the number of rows and columns in the view and specify their order. Rows can be retrieved one at a time or in groups. A cursor that keeps track of the current position can be moved to a specific place in the table.

To work with tables, clients use the read-only interface, IMAPITable : IUnknown, whereas service providers, depending on whether they own the data that the table is based on, can use either IMAPITable or ITableData : IUnknown. The operations defined in these interfaces can be categorized as operations that all users of tables either do or can invoke and operations that are not as widely used because they are more advanced. Some of the advanced operations are more complex to implement; others are no more complex, but are of interest to a small minority of MAPI components.

The more common operations are:

  • Column operations, which affect single columns. These include specifying the properties to be included in the column set and the order in which they should be included.

  • Row operations, which affect single rows. These include data retrieval and the maintenance operations: adding, deleting, and modifying a single row or rows.

  • Global operations, which affect the entire table. These include event notification, searching and sorting.

See also

Concepts

MAPI Tables


Retrieving Data from Table Rows

 Copy code hover
[image]

Retrieving Data from Table Rows
See also Send feedback

Published: July 16, 2012

Retrieving rows from a table involves:

  • Obtaining the property values for all the columns.

  • Modifying the current position.

One of the required columns in most tables is an entry identifier — the PR_ENTRYID (PidTagEntryId) property — that can be used to open the object that represents the row. This entry identifier is usually a short-term entry identifier, one that does not persist past the lifetime of the table. However, it can be a long-term identifier if the service provider implementing the table only supports one type of entry identifier.

Clients and service providers can make one of the following calls to retrieve rows:

IMAPITable::QueryRows | Retrieves a specified number of rows starting with the current row in either a forward or backward direction.
HrQueryAllRows | Retrieves all of the rows in a table.
ITableData::HrQueryRow | Retrieves a row in a table according to the value of its index column. PR_INSTANCE_KEY (PidTagInstanceKey) is usually the index column for a table.

When an optional property is included as one of the columns in a table, some of the rows might have valid values for the column while others might not. Whether a valid value exists for a column depends on whether the object providing the information for the row sets the property. Depending on the implementation of the object, a non-existent property can be represented in the table as PR_NULL (PidTagNull) or an arbitrary value. Users of tables must be careful to differentiate between properties that are nonexistent and have meaningless values and properties that do exist and have valid values.

See also

Concepts

MAPI Tables


Table Positioning

 Copy code hover
[image]

Table Positioning
Send feedback

Published: July 16, 2012

The current position within a table is always indicated by a cursor. There is one cursor for each view of a table; its value is set by the table's implementer. When a client or service provider using the table makes a call to change the position of the table, the value of the cursor is reset. A table's position can be changed with:

  • A bookmark.

  • A fractional value.

  • A filter.


Setting a Table Position with a Bookmark

 Copy code hover
[image]

Setting a Table Position with a Bookmark
See also Send feedback

Published: July 16, 2012

A bookmark is a resource that indicates a particular location in a table. Setting a bookmark makes it possible to return to a position at a later time, a feature that can significantly improve the performance of table operations. MAPI defines three standard bookmarks:

BOOKMARK_CURRENT | Points to the current row in a table.
BOOKMARK_BEGINNING | Points to the first row in a table.
BOOKMARK_END | Points to the last row in a table.

Table implementers are required to support these standard bookmarks and can also support others. However, because bookmarks are resources and resources are limited, bookmark users should free them as soon as possible.

To set a bookmark at the current table position

  • Call IMAPITable::CreateBookmark. Occasionally there will be insufficient memory available to allocate the new bookmark, causing CreateBookmark to return the MAPI_E_UNABLE_TO_COMPLETE error value.

To free a bookmark

  • Call IMAPITable::FreeBookmark.

To move the cursor to a bookmarked position

  • Call IMAPITable::SeekRow. SeekRow establishes a new value for the BOOKMARK_CURRENT position. SeekRow can be used, for example, to position a table ten rows from the current position or to start over at the beginning. Clients or service providers can seek to the current, beginning, or end of a table, or any other position that is associated with a predefined bookmark. They can move in either a forward or backward direction and limit the operation to a specified number of rows. As a rule, callers should seek through no more than 50 rows with SeekRow; IMAPITable::SeekRowApprox should be used with larger numbers of rows.

See also

Concepts

MAPI Tables


Setting Table Position with a Fractional Value

 Copy code hover
[image]

Setting Table Position with a Fractional Value
See also Send feedback

Published: July 16, 2012

Table users can move to a position that represents an approximate percentage of rows in relation to the total. Rather than moving to an exact row, this method of positioning divides the table into portions based on fractions. Table users can move, for example, to a table's half-way point or to the row that is 7/8 of the way through the table.

To move the cursor an approximate number of rows

  • Call IMAPITable::SeekRowApprox. SeekRowApprox moves to the row that represents a particular percentage of rows in relation to the beginning of the table. This percentage is specified in the ulNumerator and ulDenominator parameters. SeekRowApprox is used frequently to implement scroll bars.

To determine a table's approximate position

  • Call IMAPITable::QueryPosition. QueryPosition can be used to inform the user of the current position. It sets a fractional value based on the number of rows in the table and the number of the current row. Expect that this value represents an approximation. Table implementers are encouraged not to calculate the exact position because accurate implementations can be expensive to invoke, especially on categorized tables.

See also

Concepts

MAPI Tables


Setting a Table Position with a Filter

 Copy code hover
[image]

Setting a Table Position with a Filter
See also Send feedback

Published: July 16, 2012

Table users can move the cursor to a row that matches a set of filter criteria. Filters can be based on a variety of guidelines such as column property values, bitmasks, or subobjects. Filters are specified in MAPI using an SRestriction structure.

To position a table to the first row that matches the criteria established in a restriction

  • Call the IMAPITable::FindRow method. Starting with the row represented by a particular bookmark, FindRow searches in either a forward or backward direction to locate a row that matches the criteria specified in the restriction. FindRow can be useful for implementing a scroll bar that is based on character strings, instead of fractional values. For example, a client can call MAPI's implementation of FindRow when searching through the integrated address book to enable a user, by entering one or more characters, to locate the first name that begins with the specified characters.

See also

Concepts

MAPI Tables


Tables and Memory Usage

 Copy code hover
[image]

Tables and Memory Usage
See also Send feedback

Published: July 16, 2012

An important issue connected with retrieving data from a table is memory usage. Lack of available memory can cause IMAPITable::QueryRows and HrQueryAllRows to fail, returning less than the desired number of rows. Deciding which method or function to use to retrieve table data depends on whether the table can be expected to fit in memory, and if it cannot, if failure is acceptable.

Because it is not always easy to determine the amount of data that will fit into memory at one time, MAPI provides some basic guidelines for a client application or service provider to follow. Remember that there are always exceptions, based on the particular table implementation and how the underlying data is stored.

The following guidelines can be used to evaluate table memory usage:

  • Clients that can tolerate occasional working set memory usage in the megabyte range and can assume they will have no problems reading an entire table into memory.

  • Restrictions have an affect on a table's usage of memory. A severely restricted table with an extensive number of rows, such as a contents table, can be expected to fit into memory while an unrestricted large table usually cannot.

  • Several of the tables owned by MAPI such as the status, profile, message service, provider, and message store tables, will usually fit in memory. These are generally small tables. However, there are exceptions. For example, a server-based profile provider might generate a larger profile table that will not be able to fit.

To retrieve all of the rows from a table that will fit into memory with no problems, call HrQueryAllRows, setting the maximum number of rows to zero.

To retrieve all of the rows from a table that might or might not fit into memory, generating an error, call HrQueryAllRows specifying a maximum number of rows. The maximum number of rows should be set to a number greater than the minimum number of rows that are needed. If a client must access at least 50 rows from a 300 row table, the maximum number of rows should be set to at least 51.

To retrieve all of the rows from a table that is not expected to fit into memory, call IMAPITable::QueryRows in a loop with a relatively small row count, as the following code sample illustrates:

C++ Copy code Copy code
HRESULT     hr;
LPSRowSet   pRows = NULL;
LONG        irow;
LONG            cAsk = 50;                  // adjust this value
while ((hr = pTable->QueryRows(cAsk, 0, &pRows)) == hrSuccess
        && pRows->cRows != 0)
{
    for (irow = 0; irow < prows->cRows; ++irow)
    {
        // process the row...
    }
    FreeProws(pRows);
    pRows = NULL;
}
if (hr)
{
    // handle the error...
}

When this loop completes and all the rows in the table have been processed and cRows is zero, the position of the cursor will usually be at the bottom of the table.

See also

Concepts

MAPI Tables


Working with Large Columns

 Copy code hover
[image]

Working with Large Columns
See also Send feedback

Published: July 16, 2012

Columns with string or binary property data can be large, possibly many thousands of bytes long. Because including one or more columns with hundreds of bytes in a view is often impractical, MAPI enables table implementers to truncate the value, most often to 255 bytes and less often to 510 bytes. Whenever possible, table implementers should include the full value of a property in a table column. The recommended alternative is to include only the first 255 bytes.

Clients cannot know in advance whether a table they are using truncates large columns. They should assume that a column represents a truncated property if the length of the column is either 255 or 510 bytes. If necessary, clients can directly retrieve the full value of a truncated column from the object by calling the object's IMAPIProp::GetProps method.

Clients building restrictions with large properties should be aware that it is up to the table implementer as to how these restrictions operate. Some table implementers allow restrictions that are built with a truncated column to be based on the truncated size while others base it on the entire value.

See also

Concepts

MAPI Tables


Working with Multivalued Columns

 Copy code hover
[image]

Working with Multivalued Columns
See also Send feedback

Published: July 16, 2012

A multivalued column contains the data of a multivalued property, which is a property that has an array of values of the base type instead of a single value. Because none of the tables include multivalued properties in their default column sets, multivalued properties are included in a table only if the user of the table requests it.

Multivalued columns can be displayed in tables:

  • In a single row, with all of the property values appearing in the single column instance. This is the default.

    - Or -

  • In a series of rows, with one row for each of the property values. Each unique value appears in the column in its own row with there being as many rows as there are values in the multivalued property. Each row has a unique value for the PR_INSTANCE_KEY (PidTagInstanceKey) property, but the same values for the other columns. If a row contains more than one column with multiple values, for example, two columns with M and N values respectively, then M*N instances of the row appear in the table.

A table user requests the nondefault type of display by calling the IMAPITable::SetColumns method with the MVI_FLAG flag set in the property type of the multivalued column. The MVI_FLAG flag is a constant defined as the result of combining the MV_FLAG and MV_INSTANCE flags with a logical OR operation. In addition to being used in SetColumns, MVI_FLAG can also be passed to IMAPITable::SortTable in the lpSortCriteria parameter and IMAPITable::Restrict in the ulPropTag member of the lpRestriction parameter. When passed the MVI_FLAG, SortTable performs similarly to SetColumns, adding one row for each value in the multivalued column and sorting on the single values in the instances. One row is added for each value.

Restrict, however, does not expand the multivalued column into additional computed rows. A multivalued column with the MVI_FLAG set instructs the service provider to use that column in restricting the table. If there is a property value in the restriction, it must be a single value property tag identical to the one that would be returned by IMAPITable::QueryRows for the column.

Table implementers are only required to support the default type of display and can return the MAPI_E_TOO_COMPLEX value when a caller requests the other alternative. The ability to support both types of display is most important for message store providers implementing folder contents tables.

See also

Concepts

MAPI Tables


Working with Unicode Columns

 Copy code hover
[image]

Working with Unicode Columns
See also Send feedback

Published: July 16, 2012

Character strings in tables can be represented using standard 8-bit characters, which are property type PT_STRING8, or 16-bit Unicode characters, which are property type PT_UNICODE. Table implementers are free to choose whether or not their tables support Unicode strings. Because Unicode adds value for both clients and service providers by extending the feature set, supporting Unicode wherever possible is recommended.

Many table methods accept a flag that dictates whether or not string property values are expected to be Unicode. On input, specifying the MAPI_UNICODE flag indicates to the table implementer that all string property values passed in with the call are Unicode strings and have property types of PT_UNICODE. On output, this flag indicates that all returned string property values should be Unicode strings, if possible. Whether the flag has a meaning for input or output depends on the method. Table implementers that do not support Unicode and are passed the MAPI_UNICODE flag return the MAPI_E_BAD_CHAR_WIDTH value.

See also

Concepts

MAPI Tables


Determining a Table's End

 Copy code hover
[image]

Determining a Table's End
See also Send feedback

Published: July 16, 2012

A common error is to assume that the end of the table has been reached when:

  • IMAPITable::QueryRows has been called in a loop, with the end of the loop determined by the row count returned by IMAPITable::GetRowCount. The count that GetRowCount returns does not always represent the exact number of rows in the table; it is an approximate count.

  • QueryRows has been called with a fixed number of rows and fewer rows are returned. It is not until QueryRows returns a row set with a row count equal to zero that there are no more rows to retrieve.

Important note Important

The only time that a caller can assume that the cursor is positioned at the end of the table for a positive row count or at the beginning of the table for a negative row count is when the value S_OK and zero rows are returned. The value MAPI_E_NOT_FOUND is never returned.

See also

Concepts

MAPI Tables


Sorting and Categorization

 Copy code hover
[image]

Sorting and Categorization
See also Send feedback

Published: July 16, 2012

Sorting a table places rows in an order that makes sense for its viewer. For example, one viewer might prefer to see the contents table of a folder sorted by message subject so that all the threads of a conversation are together while another viewer might want the messages sorted by the name of the sender. A newly instantiated table is not necessarily sorted in any particular order.

There are two types of sorting:

  • Standard sorting

  • Categorized sorting

With standard sorting, all of the rows are displayed in a flat list using one or more columns as a sort key. With categorized sorting, the rows are displayed hierarchically with one or more columns as the sort key. Within each category, there is a special heading row that contains the following columns.

  • The column or columns that make up the sort key

  • PR_CONTENT_COUNT (PidTagContentCount)

  • PR_CONTENT_UNREAD (PidTagContentUnreadCount)

  • PR_INSTANCE_KEY (PidTagInstanceKey)

  • PR_DEPTH (PidTagDepth)

  • PR_ROW_TYPE (PidTagRowType)

Indented under the heading row are all the rows from the table that contain columns with values that match the sort key. These rows are called the leaf rows. Leaf rows contain all the columns in the column set minus the sort key columns.

The contents tables of folders often support categorized sorting in addition to standard sorting. The contents tables of address book containers typically support only standard sorting.

A category can have two states: collapsed and expanded. When a category is in the collapsed state, only the heading row is returned from IMAPITable::QueryRows. When a category is in the expanded state, all of the rows related to the category are returned. This includes the heading row and the leaf rows.

Each category in a table view can be expanded or collapsed independently. That is, not all categories must be in the same state at the same time; some categories can be collapsed while others are expanded.

The user of a categorized table decides how it is displayed. One common option is to use a control provided in the Windows SDK called the treeview control. Treeview controls are list boxes that support information in a tree-like structure. Heading rows for categories in the expanded state are marked with a minus sign while heading rows for categories in the collapsed state are marked with a plus sign. Expanded categories are displayed with the leaf rows indented under the heading rows.

To collapse and expand a category, a client application or service provider uses the following IMAPITable : IUnknown methods:

  • IMAPITable::GetCollapseState

  • IMAPITable::SetCollapseState

  • IMAPITable::ExpandRow

  • IMAPITable::CollapseRow

For more information about sorting the threads of a conversation see the following topics:

  • SSortOrder

  • PidTagSubject Canonical Property

  • PidTagSubjectPrefix Canonical Property

  • PidTagNormalizedSubject Canonical Property

  • PidTagConversationTopic Canonical Property

  • PidTagConversationIndex Canonical Property

  • ScCreateConversationIndex

  • Sorting Tables After Setting Columns and Restrictions

See also

Concepts

MAPI Tables


About Restrictions

 Copy code hover
[image]

About Restrictions
See also Send feedback

Published: July 16, 2012

A restriction is a way to limit the number of rows in a view to only those rows with values for columns that match specific criteria. There are many different opportunities for using restrictions with tables. Client applications can use restrictions, for example, to filter a contents table for messages sent by a particular person, to search for rows that either do not support a property or have set a property to a specific value, or to look for duplicate recipients within a message.

The IMAPITable::Restrict and IMAPITable::FindRow methods are used to set restrictions on a table. Restrict applies the restriction to the table without retrieving any rows. To retrieve only those rows that meet the restriction, a subsequent call to IMAPITable::QueryRows or a similar method is required. FindRow applies the restriction and retrieves the first row in the table that matches the criteria. FindRow applies a temporary restriction, which is in existence only for the duration of the call, whereas Restrict applies a more permanent restriction.

Some clients can build a restriction using columns that are not in the current column set. Supporting such a restriction is optional and table implementers that do support it add value, particularly for contents tables. Table implementers that do not support it can return the MAPI_E_TOO_COMPLEX value from a Restrict call or the MAPI_E_NOT_FOUND value from a FindRow call.

Clients should be aware that, even if the provider does support restrictions on columns not in the current column set, they will get better performance overall by specifying the columns they intend to use in their restrictions with IMAPITable::SetColumns.

See also

Concepts

MAPI Tables


Types of Restrictions

 Copy code hover
[image]

Types of Restrictions
See also Send feedback

Published: July 16, 2012

There are many types of restrictions, some that focus on specific columns. All table implementations are expected to support restrictions on the columns in the current column set. However, to add value, table implementers can also support restrictions based on object properties that are not currently in the table view.

Some restrictions can be combined using a restriction that performs a logical AND, OR, or NOT operation. For example, most property restrictions must be joined with exist restrictions using AND restrictions. There are a few exceptions, such as when the property used in the property restriction is the PR_ANR (PidTagAnr) property or when it is a required column in a table. A client building restrictions to limit its view should use exist restrictions with its property restrictions because MAPI does not specify how service providers should evaluate property restrictions when a property does not exist. It is reasonable and recommended that service providers fail the restriction, but there are no requirements.

A restriction is defined using the SRestriction data structure which contains a union of more specialized restriction structures and an indicator of the type of structure included in the union.

Each of the specialized restriction structures in the union represents a different type of restriction. The types of restrictions and their associated data structures are:

Type of restriction | Associated data structure | Description
Compare property | SComparePropsRestriction | Compares two properties of the same type.
AND | SAndRestriction | Performs a logical AND operation on two or more restrictions.
OR | SOrRestriction | Performs a logical OR operation on two or more restrictions.
NOT | SNotRestriction | Performs a logical NOT operation on two or more restrictions.
Content | SContentRestriction | Locates specified data.
Property | SPropertyRestriction | Specifies a particular property value as criteria for matching. Can be used, for example, to search for a particular type of attachment.
Bitmask | SBitMaskRestriction | Applies a bitmask to a PT_LONG property, typically to determine whether particular flags are set.
Size | SSizeRestriction | Tests the size of a property using standard relational operators.
Exist | SExistRestriction | Tests whether an object has a value for a property.
Subobject | SSubRestriction | Used for searching through subobjects, or objects that cannot be accessed with an entry identifier, such as recipients and attachments. Can be used, for example, to look for messages for a particular recipient.
Comment | SCommentRestriction | Associates an object with a set of named properties.

Some restrictions use regular expressions, and MAPI supports a limited form of regular expression notation in the style that is used many text applications.

The comment restriction is used by clients that save restrictions on disk to keep application-specific information with the restriction. For example, a client saving the name of a named property used in a property restriction can do so with a comment restriction. Saving the name is not possible in a property restriction; the SPropertyRestriction data structure holds only the property tag. Comment restrictions are ignored by IMAPITable::Restrict in that they have no effect on the rows returned by IMAPITable::QueryRows after a Restrict call has been made.

See also

Concepts

MAPI Tables


Address Book Restrictions

 Copy code hover
[image]

Address Book Restrictions
See also Send feedback

Published: July 16, 2012

Address book providers are required to support three types of restrictions on the contents tables of their containers:

  • Ambiguous name property restrictions

  • Instance key property restrictions

  • Prefixed display name content restrictions

Ambiguous name restrictions are property restrictions using the PR_ANR (PidTagAnr) property to match recipient names with entries in address book containers. The PR_ANR property restriction is a "best guess" type of search whereby address book providers can choose the matching property that works best for their container. For example, one address book provider might implement the PR_ANR restriction by matching recipient names against the PR_ACCOUNT (PidTagAccount) property of each container entry whereas another provider might use PR_DISPLAY_NAME (PidTagDisplayName).

MAPI recommends that implementations of the PR_ANR restriction strike a balance between adequate performance and user satisfaction. User satisfaction can be compromised when an address book provider implements the restriction in such a way that too few or too many matches are found. Some address book providers support what is known as a distinguished, or common, name that is not displayable in a dialog box but can match an ambiguous name restriction.

A typical implementation might be to parse the recipient's display name into words, matching any entry that contains all of the words. Attention to details such as sensitivity to word position, whether nonconsecutive words are matched, and the choice of separator characters can vary. For example, if the name to be resolved is "Bill L," a typical PR_ANR restriction would select the following entries as matching:

  • Billy Larson

  • Bill Lee

  • Bill Logan Jr.

  • Sam Bill Lee

Instance key restrictions, or PR_INSTANCE_KEY (PidTagInstanceKey) property restrictions, are used in the implementation of list boxes that are used in client applications for viewing MAPI tables. Some list box implementations allow users to make multiple selections, scroll up or down, and return to the first item selected. To implement this behavior, clients call IMAPITable::FindRow, passing a property restriction on the PR_INSTANCE_KEY property to the method. Address book providers are required to support this restriction.

Another feature of list boxes used for table viewing is the ability to position the cursor based on a set of prefix characters. As the user starts typing prefix characters, the client moves the cursor to the first item that begins with these characters. Clients implement this feature with a content restriction based on the PR_DISPLAY_NAME property and the FL_PREFIX fuzzy level.

See also

Concepts

MAPI Tables


Building a Restriction

 Copy code hover
[image]

Building a Restriction
See also Send feedback

Published: July 16, 2012

To build a restriction, a client application creates a hierarchy of one or more restriction structures of various types and passes a pointer to the hierarchy to the IMAPITable::Restrict or IMAPITable::FindRow method. The illustration that follows and the code sample in Sample Restriction Code demonstrate how a typical restriction is implemented with linked restriction structures of different types. In this example, a user of a client application is trying to find all messages that contain the word "volleyball" in the subject line and were sent to Sue from Sam. First, a generic SRestriction structure is allocated. This structure becomes the basis for other calls to the MAPIAllocateMore function to create linked SRestriction and SPropValue structures that can be freed with a single call to MAPIFreeBuffer. Because the criteria to apply to the set of messages is in three parts, the top level restriction structure is an AND restriction. The SAndRestriction structure's cRes member is set to 3 to indicate the three restrictions to evaluate and its lpRes member is set to a three member array of SRestriction structures.

To search for messages that are sent to a particular recipient, it is necessary to search the recipient table for each message rather than the message itself. A subobject restriction is used to perform the recipient table search. Therefore, the first member of the array points to an SSubRestriction structure with its ulSubObject member set to PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients). Then, to specify what to look for in the recipient table, a content restriction is used.

The second and third members of the array are more straightforward. They both point to content restriction structures, one to search for messages that have a PR_SENDER_NAME (PidTagSenderName) property set to "Sam" and another that has a PR_SUBJECT (PidTagSubject) property set to "volleyball."

Restriction implementation

See also

Concepts

MAPI Tables


Sample Restriction Code

 Copy code hover
[image]

Sample Restriction Code
See also Send feedback

Published: July 16, 2012

The following sample code shows how to create a restriction that filters out all messages that do not contain the word "volleyball" in the subject line and were not sent to Sue from Sam. A tree of SRestriction structures is required, with the top node being an AND restriction implemented with an SAndRestriction structure. The three restrictions that are joined by the AND operation are a subobject restriction that searches for messages sent to Sue, a content restriction that searches for messages from Sam, and another AND restriction that searches for messages that have a subject containing "volleyball." Because PR_SUBJECT (PidTagSubject) is not a required property, an Exist restriction must be included.

This code uses dynamic allocation and initialization; it is possible to allocate and initialize statically as well. In the interest of brevity, the error checking that must occur following the allocation calls is not included in the sample.

C++ Copy code Copy code
HRESULT BuildRestriction (LPSTR pszSent, LPSTR pszFrom,
                                LPSTR pszSubjectText);
{
    LPSRestriction pRest, pAndRes, pObjRes, pSubjAndRes;
    LPSPropValue pRecip, pSender, pSubject;
    HRESULT hResult;
    ULONG ulResCount = 3, ulSubjCount = 2
    // Allocate and build  restriction to join criteria
    hResult = MAPIAllocateMore (sizeof(SRestriction)*ulResCount, pRest,
            (LPVOID *)&pAndRes);
    pRest->rt = RES_AND;
    pRest->res.resAnd.cRes = ulResCount;
    pRest->res.resAnd.lpRes = pAndRes;
    // Allocate and build subobject restriction to search recipient list
    hResult = MAPIAllocateMore (sizeof(SRestriction), pRest,
            (LPVOID *)&pObjRes);
    pAndRes[0].rt = RES_SUBRESTRICTION;
    pAndRes[0].res.resSub.ulSubObject = PR_MESSAGE_RECIPIENTS;
    pAndRes[0].res.resSub.lpRes = pObjRes;
    // Allocate and build content restriction to look for recipient
    hResult = MAPIAllocateMore (sizeof(SPropValue), pRest,
            (LPVOID *)&pRecip);
    pObjRes->rt = RES_CONTENT;
    pObjRes->res.resContent.ulFuzzyLevel =
            FL_FULLSTRING | FL_IGNORECASE;
    pObjRes->res.resContent.ulPropTag = pRecip->ulPropTag =
            PR_DISPLAY_NAME;
    pObjRes->res.resContent.lpProp = pRecip;
    pRecip->Value.LPSZ = pszSent;              // pszSent set to Sue
    // Allocate and build content restriction to look for sender
    hResult = MAPIAllocateMore (sizeof(SPropValue), pRest,
            (LPVOID *)&pSend);
    pAndRes[1].rt = RES_CONTENT;
    pAndRes[1].res.resContent.ulFuzzyLevel =
            FL_FULLSTRING | FL_IGNORECASE;
    pAndRes[1].res.resContent.ulPropTag = pSend->ulPropTag =
            PR_SENDER_NAME;
    pAndRes[1].res.resContent.lpProp = pSend;
    pSend->Value.LPSZ = pszName;                    // pszName set to Sam
    // Allocate and build  restriction to look for subject
    hResult = MAPIAllocateMore (sizeof(SRestriction)*ulSubjCount, pRest,
            (LPVOID *)&pSubjAndRes);
    pRest->rt = RES_AND;
    pRest->res.resAnd.cRes = ulResCount;
    pRest->res.resAnd.lpRes = pAndRes;
    // Create an  restriction to search for subject
    hResult = MAPIAllocateMore (sizeof(SPropValue), pRest,
            (LPVOID *)&pSubjAndRes);
    pAndRes[2].rt = RES_AND;
    pAndRes[2].res.resAnd.cRes = ulSubjCount;
    pAndRes[2].res.resAnd.lpRes = pSubjAndRes;
    // Exist restriction to check that PR_SUBJECT exists
    hResult = MAPIAllocateMore (sizeof(SPropValue), pRest,
            (LPVOID *)&pSubj);
    pSubjAndRes[0].rt = RES_EXIST;
    pSubjAndRes[0].res.resExist.ulReserved1 = 0;
    pSubjAndRes[0].res.resExist.ulReserved2 = 0;
    pSubjAndRes[0].res.resExist.ulPropTag = PR_SUBJECT;
    // Content restriction to check for "volleyball" in subject
    hResult = MAPIAllocateMore (sizeof(SPropValue), pRest,
            (LPVOID *)&pSubj);
    pSubjAndRes[1].res.resContent.ulFuzzyLevel =
            FL_SUBSTRING | FL_IGNORECASE;
    pSubjAndRes[1].res.resContent.ulPropTag = pSubj->ulPropTag =
            PR_SUBJECT;
    pSubjAndRes[1].res.resContent.lpProp = pSubj;
    pSubj->Value.LPSZ = pszSubjectText;
    return hResult;
}

See also

Concepts

MAPI Tables


About Table Notifications

 Copy code hover
[image]

About Table Notifications
See also Send feedback

Published: July 16, 2012

Clients often rely on table notifications to learn of changes to objects instead of registering to receive notifications directly from the objects. Typical changes that cause notifications to be sent include the addition, deletion, or modification of a row and any critical error. When notifications arrive, clients can determine whether to make another call to reload the table.

Because table notifications are asynchronous, there are a few issues that can make handling notifications less than straightforward:

  • The data passed in the TABLE_NOTIFICATION structure might not represent the table's most current state. For example, a client might make a change to a message and then decide to delete it. The message store provider implementing the contents table that included the message sends two notifications: a TABLE_ROW_MODIFIED event followed by a TABLE_ROW_DELETED event. Depending on how the message store provider times notifications, the client might receive the TABLE_ROW_MODIFIED notification after the deletion of the row.

  • The column set included with a notification might be different from the table's current column set. MAPI requires that the notification column set match the column set that was in effect at the time that the notification was generated. Because it is possible for a client to call IMAPITable::SetColumns to alter the column set at any time — including after a notification — the two column sets may not be synchronized.

  • Table notifications are only sent for rows that are part of the view. That is, if a row is excluded from the view due to a restriction or because the table is in a collapsed state, no notification will be sent if that row changes. Also, no notifications are sent to inform a client about a change in category state.

Clients should be aware that not all tables support the TABLE_SORT_DONE notification and should be prepared to handle this condition by:

  1. Forcing the sort to be synchronous.

  2. Reloading the rows of the table when IMAPITable::SortTable returns.

See also

Concepts

MAPI Tables


About Display Table Notifications

 Copy code hover
[image]

About Display Table Notifications
See also Send feedback

Published: July 16, 2012

Notifications on a display table are sent by the service provider responsible for creating the display table to MAPI. MAPI registers for these notifications by calling a display table's IMAPITable::Advise method and specifying the table modified event.

As with all table notifications, display table notifications include a TABLE_NOTIFICATION structure. Only the ulTableEvent and the propIndex members of this structure are significant; the other members are ignored. The ulTableEvent member is set to TABLE_ROW_MODIFIED and the propIndex member is set to the value of the PR_CONTROL_ID (PidTagControlId) column in the corresponding row. MAPI responds to the notification by calling the IMAPIProp::GetProps method for the property displayed in the control and by displaying the new value.

Display table notifications can be used by a service provider to coordinate changes to related controls on the dialog box. For example, if the property interface implementation needs to refresh one or more fields on the dialog box — perhaps in response to another control that has set the DT_SET_IMMEDIATE flag in its PR_CONTROL_FLAGS (PidTagControlFlags) property — it can generate a display table notification. A display table notification can alert the property interface implementation that the value of one or more controls needs to be reread due to a change being made or an external event occurring.

A service provider can issue display table notifications by:

  • Calling ITableData::HrNotify, if the display table was built with a table data object.

    - Or -

  • Using its own code, if the display table was built with the provider's IMAPITable implementation.

MAPI responds to display table notifications when necessary by rereading a control's value from the property interface implementation. The following table describes the details surrounding how MAPI handles notifications for specific types of controls.

Control | MAPI action
Button | Calls IMAPIProp::OpenPropertyto retrieve the control object by way of the property represented by the ulPRControl member of the DTBLBUTTON structure if the call had failed previously. Calls the control object's IMAPIControl::GetState to determine whether the button should be enabled and enables or disables the button accordingly.
Check box | Rereads the value for the ulPRPropertyName member.
Combo box | Reopens the table associated with the ulPRTableName member of the DTBLCOMBOBOX structure. Rereads all of the rows including the value for the ulPRPropertyNamemember.
Drop-down list box | Reopens the table associated with the ulPRTableName member of the DTBLDDLBX structure and rereads all of the rows. Calls IMAPIProp::GetProps to retrieve the values for the properties stored in the ulPRDisplayProperty and the ulPRSetProperty members.
Edit | Rereads the property and redisplays.
Group box | Ignores the notification.
Label | Ignores the notification.
Multiple selection list box | If one of the columns is an entry identifier, refreshes the list box. The corresponding object is not closed or reloaded.
Single selection list box | Reads the set property, trying to identify it.
Multivalued list box | Rereads the property and repopulates the list box.
Tabbed page | There are no notifications for this control; everything is static.
Radio button | Rereads the property that is associated with the button and is stored in the ulPropTag member of the DTBLRADIOBUTTON structure and makes the appropriate selection with the controls.

See also

Concepts

MAPI Tables


About Asynchronous Table Operations

 Copy code hover
[image]

About Asynchronous Table Operations
See also Send feedback

Published: July 16, 2012

The IMAPITable interface includes three methods that operate asynchronously and three methods for controlling an asynchronous operation. The following table lists these methods:

Asynchronous operation | Asynchronous control method
IMAPITable::SetColumns | IMAPITable::GetStatus
IMAPITable::Restrict | IMAPITable::Abort
IMAPITable::SortTable | IMAPITable::WaitForCompletion

To retrieve status information about a table's type and current operation

  • Call IMAPITable::GetStatus. With GetStatus, a table user can determine whether the table is static or dynamic, if an operation is in progress or has completed, and if an error has occurred from a completed operation. For example, if a client needs to cancel a sort operation because it is taking too much time, the client can first call GetStatus to determine whether, in fact, a sort operation is presently processing. Then the client can call IMAPITable::Abort to stop it.

To suspend activity until an asynchronous task has completed

  • Call IMAPITable::WaitForCompletion. Calling WaitForCompletion allows the task to complete without interruption.

See also

Concepts

MAPI Tables


Tips for Better Table Performance

 Copy code hover
[image]

Tips for Better Table Performance
See also Send feedback

Published: July 16, 2012

Because many of the table operations can be time-consuming and there is no way to indicate progress, it is helpful to use the following techniques for improving performance:

  • Make IMAPITable calls in the correct order

    Clients and service providers can work with tables in a variety of ways. They can open the table and retrieve the data for all of the rows using the default column set and sort order. Alternatively, they can modify this default view of the table by changing the column set, changing the sort order, or establishing a restriction to narrow the table's scope. Table users that intend to perform one or more of these operations before retrieving any data should perform them in the following order:

    1. Define a column set with IMAPITable::SetColumns.

    2. Establish a restriction with IMAPITable::Restrict.

    3. Define a sort order with IMAPITable::SortTable.

    Performing these tasks in this order limits the number of rows and columns that will be sorted, thereby improving performance.

  • Delay an operation using the TBL_BATCH flag if possible

    Setting the TBL_BATCH flag on a method allows the table implementer to collect several calls before acting on any one of them. Instead of make potentially many calls to a remote server; a table implementer can make one, performing all the operations at one time. The results of the operations are not evaluated until they are needed. For example, when a client calls IMAPITable::Restrict to specify a restriction with the TBL_BATCH flag set, the restriction do not have to go into effect until the client calls IMAPITable::QueryRows to retrieve the data. This allows the table implementer to combine the work of two calls into one. Table users that take advantage of the TBL_BATCH flag should be aware that error handling under these conditions can be more complex. Because handling the errors from a delayed operation is similar to handling the errors when the MAPI_DEFERRED_ERRORS flag is set, see Deferring MAPI Errors for more information.

  • Keep a cache of commonly used properties

    Service providers implementing tables can lessen the time it takes to create a view by caching copies of commonly used object properties. Keeping a copy of these properties in memory saves having to retrieve them from the object each time the view must be rebuilt.

See also

Concepts

MAPI Tables


MAPI Forms

 Copy code hover
[image]

MAPI Forms
Send feedback

Published: July 16, 2012

After reading this overview of the MAPI form architecture, you will have an understanding of what MAPI forms are and how they interact with other components of the MAPI subsystem. The purpose of this section is to give you the conceptual knowledge you need to implement your own MAPI form servers.

Before reading this section, you should familiarize yourself with the material in the MAPI Forms Overview topic.

Note Note

Because the MAPI form architecture is based on the Component Object Model (COM), developing form server applications requires knowledge of COM programming. For more information about COM, see the COM and ActiveX Object Services section in the Windows SDK.


MAPI Form Servers

 Copy code hover
[image]

MAPI Form Servers
See also Send feedback

Published: July 16, 2012

From the user's perspective, a form is usually a property sheet for a message or a data-entry form that enables users to enter structured information. However, it can be any user interface that is associated with a message class. From a programmer's point of view, a form consists of:

  • A type of MAPI message with its own message class and OLE identifier.

  • The executable file that implements the form server.

  • A collection of MAPI properties — custom or otherwise — that the form server uses. Some or all of these may be available to messaging clients for use.

  • The configuration file that describes the form and is used by the form manager.

Because forms are IMessage objects, they exhibit properties and behavior that is consistent with MAPI message objects. However, because forms can have custom properties, controls, and a display rendering that is application-specific, the MAPI interfaces that forms use are generic enough to permit any sort of interface that is needed. The actual definition of a form is stored in a form library, which is discussed later in this section.

Note Note

More accurately, all messages are instances of MAPI forms. However, it is usually easier to think of custom forms as special cases of messages, since forms for composing and reading typical e-mail messages are the most commonly used forms. The fact that all messages are really just forms gives custom forms the same status as any other message in the MAPI system.

Every form has a set of properties, some of which are visible in the form's user interface. Usually, properties are matched to fields in the form's user interface. For example, a purchase order form might have the fields Item, Description, Price, Tax, and Subtotal. These fields are simply visual renderings of form properties of the same names. Clients ascertain which properties are supported by a particular message class through the IMAPIFormInfo::CalcFormPropSet method, which is implemented by the MAPI form manager.

Like basic messages, MAPI forms can contain all the standard message properties such as the sender, the intended recipient, and when the message was sent. Forms can also contain any number of custom properties that are specific to the form. For example a "Bug Report" form might contain custom properties for Bug Type, Bug Severity, and Product Version.

To create a form you must implement a form server. The form server is the executable file that is loaded when a messaging client needs to display a message that is the type supported by the form server. The form server in turn creates form objects as necessary to display specific messages and handle user interactions with those messages.

Every form server has a configuration file associated with it. This file contains information that describes the form server for the benefit of the form manager. The form manager uses this information when installing the form server into a form library.

For details on creating the parts of a form, see Developing MAPI Form Servers.

Form servers adhere to the Component Object Model (COM). Form servers run as standalone executables, not as in-proc servers. For more information, see the COM and ActiveX Object Services section in the Windows SDK.

A unique class identifier (CLSID) identifies each form server. There is always a one-to-one mapping between a class identifier and its message class. This does not mean, however, that a form server can only work with messages of one message class. If no form server is available to service a message of a particular class, the form manager being used should attempt to find a form server for a message class higher in the message class hierarchy; the default form manager supplied with the Windows SDK does this. Such a form server will probably be able to render only a subset of the message's properties (the ones supported by the superclass), but it will be better than nothing. What happens when no matching form server is found at all is an implementation detail specific to the form manager being used; the default form manager does not open messages when this happens.

For more information, see MAPI Message Classes.

See also

Concepts

MAPI Forms


Form Verbs

 Copy code hover
[image]

Form Verbs
See also Send feedback

Published: July 16, 2012

A form's user interface typically offers menu items or controls that enable users to take some kind of action with the form. It is the form server's job to handle these user actions. This interface is implemented using standard Win32 APIs; writing one is just like writing other interfaces for regular Win32 programs.

Often, user actions are associated with verbs. A verb is the name for an action that is specific to a certain message class. For example, Reply is a verb that is implemented by many form servers, each of which may have a different interpretation of that verb. Verbs are sometimes referred to as commands.

Note Note

Not all menu items and controls on a form correspond to a verb. For example, a Cancel button does not correspond to a Cancel verb within the form server. Usually, verbs are associated with actions that are specific to a particular message class or a set of message classes. Although different message classes can support different sets of verbs, all support at least the Open verb, which displays the form's user interface and loads it with the message's property values.

Verbs may take no parameters. Forms that export commands with variable parameters must use the Automation mechanisms.

Clients can determine which verbs are supported by a particular message class through the IMAPIFormInfo::CalcVerbSet method, which is implemented by the MAPI form manager. The form manager gets this information from the form's configuration file. The verb set returned by this method is used by the client to show the user which commands can be executed on a message. For example, a client might enable users to click the right mouse button over a message to display verbs applicable to that message.

See also

Concepts

MAPI Forms


MAPI Form Objects

 Copy code hover
[image]

MAPI Form Objects
See also Send feedback

Published: July 16, 2012

Form objects are created dynamically by form servers in order to display specific messages and allow users to interact with them. A form object is, therefore, an instantiation of the class derived from IMAPIForm that is implemented by the form server. When a client application opens a message, the form server for that message class creates a form object to handle the message. The form object then creates its interface and displays the properties of the message in it. The form object and its interface persists until the user closes it. The form object handles any changes to the values of the message's properties.

Additionally, the MAPI form interfaces define a mechanism by which one form object can load and display a series of messages. This is an efficiency mechanism, as it avoids needless destruction and creation of message objects and their interfaces. When requested by the messaging client to load a different message, the form object should save any changes to the current message's properties.

For information on a client application's perspective of form objects, see MAPI Custom Form Objects.

See also

Concepts

MAPI Forms


MAPI Form Manager

 Copy code hover
[image]

MAPI Form Manager
See also Send feedback

Published: July 16, 2012

A form manager is an object that implements the IMAPIFormMgr interface. Most organizations will use the form manager supplied with MAPI, referred to as the default form manager. However, an organization can replace the default form manager with a custom form manager if desired. The form manager takes care of locating forms within form libraries, loading forms in response to user requests, and installing forms into a user's local form library, folder form library, or personal form library.

For a user to interact with a message, an instance of the form server for the message's message class must be created and activated to display the message and carry out the requested operation on the message. As described in the topic MAPI Form Libraries, a form's implementation can exist in several different locations (form libraries) and there is no guarantee that a form or its server will be locally available or in a running state when a user wants to interact with it. The form manager takes care of the details of locating and activating the form.

Clients use services provided by the form manager to find and activate forms. The IMAPIFormMgr interface is implemented by the form manager and is called by clients to access its services. The form manager is an essential component because it hides almost all the details of finding and activating forms from messaging clients.

When loading form servers, the default form manager loads the form from the first form library in which an implementation for the form's message class is found. The default form manager searches the form libraries in the following order:

  1. The user's local form library. This form library is searched first because it provides the fastest access to a form's implementation if the implementation is installed in the local form library.

  2. The folder form library of the message's container — the folder in which the message being loaded is stored.

  3. The user's personal form library.

A custom form manager can search the available form libraries in any order, or can implement other form libraries such as an organization-wide form library. For more details on form libraries, see MAPI Form Libraries.

See also

Concepts

MAPI Forms


Capabilities Not Supported by Form Managers

 Copy code hover
[image]

Capabilities Not Supported by Form Managers
See also Send feedback

Published: July 16, 2012

The following features are not supported by the default form manager for performance reasons but can be supported by custom form managers.

  • A hierarchy that enables forms to be grouped or categorized throughout a form library. A form library is a flat-file database of forms.

  • Access control for categories of forms, corresponding to message classes or superclasses.

  • Support for multiple language versions of the same form in a single form library.

These are implementation issues. There is nothing to prevent a custom form manager from implementing these features.

The MAPI form architecture does not support multiple form managers running concurrently. Although MAPI supports multiple concurrent message store providers, transport providers, and address book providers, only a single form manager is supported.

Because only one form manager may be running at once, if you implement a custom form manager you will have to re-implement any functionality from the default form manager that you need. Because your custom form manager will entirely replace the default form manager, capabilities of the default form manager will be unavailable unless they are duplicated in your custom form manager.

See also

Concepts

MAPI Forms


Disk Instances and Cache Tables

 Copy code hover
[image]

Disk Instances and Cache Tables
See also Send feedback

Published: July 16, 2012

To activate a form, its executable files must be available on the user's computer. If they are not available, they must be copied from the form library to the local disk. To do this, the default form manager creates a subdirectory in the user's Windows directory to contain the form's executable files (.EXEs,.HLPs). This directory is referred to as the disk instance of the form.

The default form manager maintains a table of all disk instances so that if a disk instance already exists it can be used without having to copy files from the form library to the user's disk. The table of disk instances is managed as a least-frequently-used cache. If a new disk instance is needed, it is copied to the user's computer, replacing the least-frequently-used disk instance. The disk instance cache table is then updated to reflect the latest configuration. The size of the disk cache is a user-configurable option, enabling users to balance speed with available disk capacity.

In addition to the disk instance cache, the default form manager maintains a running instance table that lists all running instances of form servers on the user's computer. This uses MAPI's ability to keep idle form instances running in an invisible state until a form of that form server's message class is activated. In other words, form servers can be cached in RAM to minimize the number of times a form's executable must be located within a form library and loaded into memory from disk or over the network. Like the disk instance cache, the running instance cache behaves in a least-frequently-used fashion so that a running form instance can be purged from the cache to make room for another form instance. This cache is searched for a running instance of a form server before the form libraries are searched for the form server.

Note Note

The default form manager displays a progress indicator when installing a form on a user's workstation, enabling the user to cancel the operation. This is especially useful if the user's connection to the form server's executable file is over a low bandwidth network.

See also

Concepts

MAPI Forms


MAPI Form Libraries

 Copy code hover
[image]

MAPI Form Libraries
See also Send feedback

Published: July 16, 2012

To help organize form servers and make them easily available to client applications, the MAPI form architecture includes form libraries, which support the installation, administration, replication, and use of form servers.

Form libraries are repositories of form servers and configuration information about them that the form manager uses when loading form servers.

Note Note

Early in the history of MAPI, form libraries were called "registries." Because of this, the term "registry" has persisted in some form-related MAPI interfaces, properties, configuration file entries, and so forth. If your application's interface requires use of one of these terms, you should use the term "library" exclusively.

See also

Concepts

MAPI Forms


Form Storage

 Copy code hover
[image]

Form Storage
See also Send feedback

Published: July 16, 2012

Although it is not necessary to know all the details of how forms are physically stored, it is useful to understand a few of the main concepts. Therefore, before describing the three types of form libraries supported by the default form manager, this topic gives an overview of how forms are stored.

Form definitions can be physically stored within folders in one or more MAPI message stores. Every MAPI folder can be thought of as having two areas for storing message objects: the standard part and the associated part. The standard part of the folder includes the messages and folders that users manipulate.

The associated part includes hidden message objects that are associated with the folder, including form definitions, views, rule templates, reply templates, and so on. This alternate part is called the folder-associated contents table, and the set of messages in the associated contents table is referred to as the folder-associated information. The hidden messages are an integral part of the folder and are copied along with the standard folder contents when the folder is copied. Although physically stored as messages, information in a folder's associated contents table behaves more like properties than like viewable messages. Any folder object that supports an associated contents table is capable of storing custom forms. The IMAPIContainer::GetContentsTable method can return either the standard contents or the associated contents of the folder, depending on the value of the method's ulflags parameter.

A form library consists of form definitions stored in a folder's associated contents table. The form definition includes the form's properties, the actions the form supports, and even the form server executable file, which is stored as one or more message attachments.

Additionally, forms can be stored in any file or location that the form manager being used supports. The default form manager stores form servers in MAPI folders, but a custom form manager could implement its own storage for form servers.

A form can have multiple user interfaces that are bound to its message class. For example, a form can have separate Compose and Read user interfaces. The form takes care of invoking the proper user interface for different user requests, depending on which of the form's verbs is being called. For example, if your form server has separate composing and reading user interfaces, the Compose user interface can be opened automatically when the user creates a new message of the form's message class and the Read user interface can be opened automatically when the user opens an existing message of the form's message class.

Most of the information stored within a form definition is available by invoking the IMAPIFormInfo::IMAPIProp method on an IMAPIFormInfo object. The IMAPIFormInfo interface simplifies access to form information by calling all the MAPI folder and message methods needed to retrieve the information. An IMAPIFormInfo object can be obtained by calling the IMAPIFormContainer::ResolveMessageClass method.

The three types of form libraries are described in the topics Local Form Libraries, Folder Form Libraries and Personal Form Libraries.

See also

Concepts

MAPI Forms


Local Form Libraries

 Copy code hover
[image]

Local Form Libraries
See also Send feedback

Published: July 16, 2012

Local form libraries are stored directly on a user's machine, usually in a file called FRMCACHE.DAT.

Client applications can access forms in the local form library without accessing any network resources. Local form libraries are an exception to the rule that forms are stored in associated contents tables, since the local form library is simply a file on disk that is not part of any MAPI folder hierarchy.

See also

Concepts

MAPI Forms


Folder Form Libraries

 Copy code hover
[image]

Folder Form Libraries
See also Send feedback

Published: July 16, 2012

In some cases, you might want to associate one or more forms with a specific folder. For example, employees in your organization could all have a Progress Report folder in their personal message store for creating and storing progress reports. Because the progress report is specific to each user's Progress Report folder, it might not be appropriate to store the progress report form in the system wide form library. However, a copy of the progress report form can be kept in the associated-contents table of each user's Progress Report folder. This restricts the user from using progress report forms outside of the designated folder.

Conceptually, there is one folder form library for every folder in a message store, even if no form servers are installed in it. Folder form libraries are implemented like other form libraries — they are stored as associated-contents tables in the alternate part of the folder. Because folder form libraries are contained in the folder, they are copied along with their parent folder in copy operations.

See also

Concepts

MAPI Forms


Personal Form Libraries

 Copy code hover
[image]

Personal Form Libraries
See also Send feedback

Published: July 16, 2012

As its name suggests, personal form libraries contain forms of interest to a particular user. A user's personal form library is the form library associated with the default message store identified in the user's profile; each profile installed on a workstation can use a separate default store, and therefore, a separate personal form library. A personal form library can contain copies of forms that are also contained in other form libraries in addition to other forms.

A personal form library is implemented in the associated-contents table of the root folder in a user's default message store — whether that resides on a server or locally on the user's workstation is immaterial. If the user's default message store is stored on the user's workstation, personal form libraries offer enhanced performance by enabling applications to access forms locally instead of over the network. It also makes forms available to users working offline, which can occur when users want to take their forms with them on portable computers and are without access to a network.

The properties and underlying implementation of personal form library entries include a "Container ID" property that identifies a master container that the local entry must be synchronized with. This can be the identifier of an arbitrary folder that contains forms. This is useful if you are using a custom form manager that supports some sort of organization-wide form library; the form manager would take care of synchronizing the forms stored in the personal form library and the organization-wide form library. This would probably happen when the form manager was loaded, but could theoretically happen at any time.

See also

Concepts

MAPI Forms


Forms and MAPI Client Applications

 Copy code hover
[image]

Forms and MAPI Client Applications
See also Send feedback

Published: July 16, 2012

Because all MAPI messages are instances of forms, client applications display and interact with form objects just as they do with other message objects.

Client applications that use the MAPI form interfaces can provide additional interaction with form objects. Client applications can use any special verbs defined by a form to provide users with the full range of interactions intended by the form's designer. Clients can also use any custom properties that the form server exposes to help users sort, preview, or otherwise manage forms in the client's interface.

For more information, see Handling MAPI Forms.

See also

Concepts

MAPI Forms


MAPI Form Interfaces

 Copy code hover
[image]

MAPI Form Interfaces
See also Send feedback

Published: July 16, 2012

MAPI defines the following interfaces relating to forms.

Interface name | Description
IMAPIForm | Manipulates form objects and handles form object commands.
IMAPIFormAdviseSink | Determines if the form object can handle the next message and changes the next or previous state of the form object.
IMAPIFormContainer | Supports installation, deinstallation, and resolution of form servers against a specific form container.
IMAPIFormFactory | Supports the use of configurable run-time form servers.
IMAPIFormInfo | Enables client applications to work with properties that are specific to a message class.
IMAPIFormMgr | Enables client applications to get information about form servers, activates form servers, and installs form servers in the messaging system.
IMAPIMessageSite | Used to manipulate messages associated with form objects.
IMAPIViewAdviseSink | Notifies client applications that an event has occurred in the form object.
IMAPIViewContext | Used to respond to Next, Previous, and Delete commands in the form object.
IPersistMessage | Used to save, initialize, and load form objects to and from message storage.

For more information about the methods of the MAPI form interfaces, see the documentation for these interfaces. You do not have to implement all of the MAPI form interfaces in order to create a custom form. A form itself requires only that you implement the IPersistMessage, IMAPIForm, and IMAPIFormAdviseSink interfaces. Additionally, it is also a good idea to implement IMAPIFormFactory and IMAPIFormInfo. IMAPIFormFactory is useful for OLE compliance, and IMAPIFormInfo enables well-written client applications to make better use of your forms.

Note Note

Strictly speaking, IMAPIFormAdviseSink is an optional interface. However, it is strongly recommended that you implement it in your form servers. This interface is critical to efficient interaction between messaging clients and form servers, especially when several messages of your form server's message class are being dealt with.

See also

Concepts

MAPI Forms


Developing a MAPI Client Application

 Copy code hover
[image]

Developing a MAPI Client Application
Send feedback

Published: July 16, 2012

MAPI client applications are written with the object oriented MAPI client interface. MAPI clients interact with one or more messaging systems through the MAPI subsystem and MAPI-compliant service providers. This interaction can occur in many different ways; there is an enormous variety in client applications. Most clients are messaging clients, either integrating messaging into their established feature set or performing messaging as their primary feature. Other features that MAPI clients might provide include profile administration or address book and message store management.

All messaging clients initialize the MAPI libraries and start a session with the MAPI subsystem. For more information, see Accessing Objects by Using the Session. After a session has been established, a client can:

  • Handle outgoing messages, including replies, forwarded messages, and retransmissions.

  • Handle incoming messages.

  • Handle the message store by opening folders and messages, creating, modifying, copying, and sending messages, tracking conversations, and searching one or more folders.

  • Handle the address book by creating and modifying recipients, locating entries, and traversing the container hierarchy.

  • Handle a transport provider by performing reconfiguration, setting options and transport order, and sending messages on demand.

  • Handle event notification.

  • Handle forms.

  • Handle profiles and message services.

Use the topics in this section to help you implement these basic tasks and the specific features that will make your MAPI client unique.


Types of Client Applications

 Copy code hover
[image]

Types of Client Applications
Send feedback

Published: July 16, 2012

There are primarily two types of messaging clients: those that handle interpersonal messages (IPM) and those that handle interprocess communication (IPC) messages. Within those types, messaging client applications can be categorized as follows:

  • Person-to-person

  • Person-to-machine

  • Machine-to-person

  • Machine-to-machine

  • Mix of persons and machines

Person-to-person applications involve a person initiating the exchange of messages and another person responding. This category of applications includes traditional e-mail applications as well as more structured exchanges such as document routing or expense approval.

Person-to-machine applications involve a person initiating the exchange of messages and a machine responding. This category includes applications that use e-mail to, for example, submit a database query or subscribe to a mailing list.

Machine-to-person applications involve a machine initiating the exchange of messages and a person responding. This category includes applications that distribute documents such as news feeds and opinion surveys.

Machine-to-machine applications involve a machine initiating the exchange of messages and a machine responding. This category includes applications such as link heartbeat monitoring and directory and database replication.

The final category, a mix of persons and machines, involves a more complex scenario. This category includes applications that do not necessarily transmit messages between senders and recipients. Instead they might post them directly into a public folder or to a web-site forum supported by a message store. The messages can then be consumed on demand by other readers, an administrator, or a software agent.

If you are writing a person-to-person application, machine-to-person application, or an application that posts messages to public forums, design your application to send and receive IPM messages. If you are writing a person-to-machine or machine-to-machine application, it can be designed to send and receive IPC messages. Any application that requires the interaction of a human user must support IPM messages. Applications that involve both people and machines in a variety of scenarios often must support both IPM and IPC messages. The only real difference between the two classes is that IPM messages in a message store are visible to users of messaging clients, while IPC messages usually are not visible to the client application users.

Rather than limiting your messages to the capabilities provided by the MAPI superclasses, IPM and IPC, you can customize and enhance these classes by creating new IPM or IPC subclasses. Creating message subclasses involves inventing new message classes that inherit from the superclasses. For example, if your person-to-person application specializes in customer relationship management, you can subclass the IPM superclass by defining an IPM.Contact.Customer class and create properties that describe a customer. In addition to supporting these custom properties, your IPM.Contact.Customer messages will inherit the properties supported by all IPM messages.


Linking to the MAPI DLLs

 Copy code hover
[image]

Linking to the MAPI DLLs
Send feedback

Published: July 16, 2012

MAPI clients can link to the MAPI DLLs implicitly, or explicitly by using the Windows functions LoadLibrary and GetProcAddress. For information on explicitly linking MAPI DLLs, see How to: Link to MAPI Functions.

MAPI provides type definition statements in the MAPIX.H header file for each of the following functions:

MAPILogonEx

MAPIUninitialize

MAPIInitialize

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

MAPIAdminProfiles

Use these type definitions to correctly call the corresponding entry points if you link explicitly to the MAPI DLLs.

Service providers can contain non-MAPI functionality — features that are completely unrelated to MAPI — in their DLL. If you need to use these features, call LoadLibrary before using the DLL and FreeLibrary to remove the DLL from memory after its use. Because MAPI is unaware of non-MAPI uses of a service provider DLL, there is no guarantee that the DLL will be available when needed. MAPI releases a service provider DLL when there are no longer any clients with active sessions that require its services.


MAPI Session Handling

 Copy code hover
[image]

MAPI Session Handling
Send feedback

Published: July 16, 2012

Before you can communicate with service providers and an underlying messaging system, you must establish a session. A MAPI session is a link from a client to other MAPI components. As the result of successfully starting a session, MAPI returns to clients a pointer to a session object — an object that implements the IMAPISession interface. For more information, see IMAPISession : IUnknown. You can use the methods of the IMAPISession interface to access the objects of address book and message store providers, access several tables, display forms, set transport provider properties, and perform profile and message service administration.

In This Section

Starting a MAPI Session

Describes how to start a MAPI session and includes links to topics with more detailed information.

Ending a MAPI Session

Describes how to end a MAPI session.

Accessing Objects by Using the Session

Describes how to use a session pointer to access session objects.

Retrieving Primary and Provider Identity

Describes the properties used to retrieve primary and provider identity.

Status Table and Status Objects

Describes how to access information from the status table.


Starting a MAPI Session

 Copy code hover
[image]

Starting a MAPI Session
Send feedback

Published: July 16, 2012

Although there is a significant amount of work performed during session start up, the required tasks are minimal. Much of this work is done in the MAPI processing of the MAPIInitialize and MAPILogonEx calls. Both of these functions accept flags as input parameters for controlling aspects of the session such as notification handling and the user interface. It is important to understand the consequences of setting each of these flags when calling MAPIInitialize to initialize the MAPI libraries and MAPILogonEx to log on to the MAPI subsystem.

To start a MAPI session

  1. Call MAPIInitialize to initialize the standard set of MAPI libraries.

  2. If you need to use the OLE libraries, call the OLE function OleInitialize.

  3. If you need to use the MAPI utility library, call ScInitMapiUtil.

  4. Call MAPILogonEx with a valid profile to log on to the MAPI subsystem. MAPILogonEx verifies the configuration of each of the service providers in the message services included in the profile, prompting the user for additional information if necessary and possible. When MAPILogonEx completes, the configured service providers are ready for service.

In This Section

Initializing MAPI

Describes how to initialize MAPI for a session.

Initializing OLE for MAPI

Describes the calls to make to initialize OLE for use with MAPI.

Initializing the MAPI Utilities

Describes how to initialize MAPI utilities.

Logging on to MAPI

Describes how client applications log on to the MAPI sub system.


Initializing MAPI

 Copy code hover
[image]

Initializing MAPI
Send feedback

Published: July 16, 2012

All client applications that use the MAPI libraries must call the MAPIInitialize function. For more information, see MAPIInitialize. MAPIInitialize initializes global data for the session and prepares the MAPI libraries to accept calls. There are a few flags that are important to set in some situations:

  • MAPI_NT_SERVICE

    Set the MAPI_NT_SERVICE flag if your client is implemented as a Windows service. If your client is a Windows service and you do not set this flag, MAPI will not recognize it as a service.

  • MAPI_MULTITHREAD_NOTIFICATIONS

    The MAPI_MULTITHREAD_NOTIFICATIONS flag relates to how MAPI manages notifications. MAPI creates a hidden window that receives window messages when changes occur to an object generating notifications. The window messages are processed at some point, causing the notifications to be sent and the appropriate IMAPIAdviseSink::OnNotify methods to be called.

  • MAPI_NO_COINIT

    Set the MAPI_NO_COINT flag so that MAPIInitialize does not try to initialize COM with a call to CoInitialize. If a MAPIINIT_0 structure is passed into MAPIInitialize with ulFlags set to MAPI_NO_COINIT, MAPI will assume that COM has already been initialized and bypass the call to CoInitialize.

If MAPI_MULTITHREAD_NOTIFICATIONS flag is not passed, MAPI creates the notification window on the thread that was used for your first MAPIInitialize call. MAPI creates the notification window on a separate thread if MAPI_MULTITHREAD_NOTIFICATIONS is passed — a thread dedicated to handling notifications. MAPI expects the thread that is used to create the hidden notification window to:

  • Have a message loop.

  • Remain unblocked throughout the life of the session.

  • Have a longer lifetime than any other thread created by your client.

You can choose which thread is used by setting a flag in the first MAPIInitialize call. The danger in allowing one of your threads to handle the notifications is that if the thread disappears, the notification window is destroyed and notifications can no longer be sent to any of your other threads. Also, special processing might be needed to control the dispatching of the notification messages that are posted to the hidden window's message queue.

If you use a separate window to handle notifications, be assured that notifications will appear at the appropriate time on an appropriate thread. You will not need any special code to check for and process the Windows messages that are posted to the notification window.

MAPI recommends that the following types of client applications use a separate thread to create the hidden window for notification support:

  • All multithreaded clients.

  • Single-threaded Windows services and Win32 console applications.

  • Single-threaded clients that do not need to use their main thread for notification.

To use the separate thread approach, call MAPIInitialize on every thread, setting the MAPI_MULTITHREAD_NOTIFICATIONS flag.

Note Note

Only a client's first call to MAPIInitialize causes a hidden window to be created to support notifications. Subsequent calls only cause a reference count to be incremented.


Initializing OLE for MAPI

 Copy code hover
[image]

Initializing OLE for MAPI
Send feedback

Published: July 16, 2012

If you also use OLE, call the OLE function OleInitialize to initialize the OLE libraries. OleInitialize initializes global data for the session and prepares the OLE libraries to accept calls. For information about calling OleInitialize, see the Windows SDK.


Initializing the MAPI Utilities

 Copy code hover
[image]

Initializing the MAPI Utilities
Send feedback

Published: July 16, 2012

If the only part of MAPI that you need to use are the utilities — the interfaces and functions declared in MAPI's MAPIUTIL.H header file such as IPropData and ITableData — you do not need to call MAPIInitialize for initialization. For more information, see IPropData : IMAPIProp, ITableData : IUnknown, and MAPIInitialize. Instead, call the ScInitMapiUtil function. For more information, see ScInitMapiUtil. ScInitMapiUtil enables client applications to use utility functions and methods that require MAPI allocators, but that do not ask for them explicitly.

At shutdown time, make a call to DeinitMapiUtil to free resources connected to the utilities. Do not call MAPIUninitialize. For more information, see DeinitMapiUtil and MAPIUninitialize.

Be aware that the ITableData interface does not support table notifications for clients that have called ScInitMapiUtil rather than MAPIInitialize.


Logging on to MAPI

 Copy code hover
[image]

Logging on to MAPI
Send feedback

Published: July 16, 2012

Client applications log on to the MAPI subsystem by calling the MAPILogonEx function. For more information, see MAPILogonEx. MAPILogonEx validates the profile selection and the configuration of each service provider in the profile. Once configured, MAPI starts the address book providers before starting the message store providers. Transport providers are started when their services are first required.

To choose a profile

  • Pass in a character string that represents the name of the profile in the lpszProfileName parameter to MAPILogonEx

    - Or -

  • Allow the user to specify the profile by passing NULL in the lpszProfileName parameter and setting the MAPI_LOGON_UI flag.

    - Or -

  • Select the default profile by passing NULL in the lpszProfileName parameter and setting the MAPI_USE_DEFAULT flag.

If you require a specific profile other than the default profile, you must save its name in your own configuration database or use a specific naming convention. MAPI does not expose any profile attributes other than the name and default flag in the profile table, and the default profile flag is reserved for messaging client and related IPM applications.

Clients that supply partial profile or provider configuration information to MAPILogonEx must prompt the user for the additional data by allowing a dialog box to be displayed. If information is missing and MAPILogonEx cannot prompt the user to supply it, the logon fails. Clients that do not need user input can suppress the dialog box display.

The flags that MAPILogonEx uses to enable a user interface are mutually exclusive; only one can be set. Leaving these flags unset suppresses the display of a user interface, causing MAPILogonEx to fail if necessary information is missing. That is, if you disable the user interface and pass NULL for the lpszProfileName parameter and do not set the MAPI_USE_DEFAULT flag, MAPILogonEx will fail because it cannot retrieve a profile name.

The session that MAPILogonEx establishes can be an individual messaging session, a shared messaging session, or a nonmessaging session. Individual messaging sessions are private connections between your client and the MAPI subsystem and can be established by setting the MAPI_NEW_SESSION flag in the call to MAPILogonEx.

Shared messaging sessions are connections that multiple messaging clients can use. Shared sessions are typically established for clients use the same profile. To establish a new session as a shared session, set the MAPI_ALLOW_OTHERS flag.

To use an existing shared session

  • Do not set the MAPI_NEW_SESSION flag.

  • Do not set the MAPI_ALLOW_OTHERS flag.

  • Pass NULL for the lpszProfileName parameter.

  • Pass NULL for the lpszPassword parameter.

Nonmessaging sessions allow clients to access the MAPI subsystem, but do not allow messages to be sent or received. Configuration or administration applications are examples of clients that might need to establish nonmessaging sessions. To request a nonmessaging session, set the MAPI_NO_MAIL flag. Setting this flag logs your client on without informing the MAPI spooler. Clients that log on to MAPI with this flag cannot expect to ever receive read status reports.

The MAPI_NO_MAIL flag should only be set:

  • If your client will not send or receive messages during the session.

  • If your client has complete control over the contents of the profile and messages are sent and received using tightly coupled message store and transport providers, such as the Microsoft Exchange providers.

A messaging client can share a session with a nonmessaging client. The characteristics of one member of a shared session are not affected by the characteristics of other members. That is, if you log on with the MAPI_NO_MAIL and MAPI_ALLOW_OTHERS flags set, a messaging client logging on to your session has no affect on the operation of your client and vice versa. The messaging client will still be able to send and receive messages and your client will not.

MAPILogonEx defines a few other flags that you can set:

  • MAPI_FORCE_DOWNLOAD indicates that incoming messages should be downloaded before MAPILogonEx returns. Not setting this flag causes messages to be downloaded in the background at a later time.

  • MAPI_SERVICE_UI_ALWAYS requests that every message service in the profile display a configuration dialog box.

  • MAPI_NT_SERVICE indicates that your client is implemented as a Windows service. This flag must be set if your client is a service.

With every successful logon, MAPILogonEx returns a pointer to a MAPI session. You can use this pointer to call the methods of the IMAPISession interface. For more information, see IMAPISession : IUnknown. Session pointers, regardless of the type of session, are unique to the clients that receive them and are not valid across tasks.


Ending a MAPI Session

 Copy code hover
[image]

Ending a MAPI Session
Send feedback

Published: July 16, 2012

Clients can end their sessions in response to a user's request, either immediately or after all outbound messages have been processed, and when a critical error occurs. Some clients need to stay logged on so that pending outbound messages can reach the transport provider and the destination messaging system. If such a client sends a message and immediately logs off, the message may remain in the outgoing queue until a user logs back on and stays logged on long enough for the message to be transmitted.

When you need to terminate your session with the MAPI subsystem

  1. Cancel the registrations for all notifications by calling the Unadvise method of every registered object.

  2. Release all open objects by calling their IUnknown::Release methods. The types of open objects can include advise sinks, the status table, the Outbox folder, one or more message stores, and the address book.

  3. Call MAPIFreeBuffer to free the memory for any cached entry identifiers, such as PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId).

  4. Call IMAPISession::Logoff, setting the MAPI_LOGOFF_UI flag if you allow a user interface and the MAPI_LOGOFF_SHARED flag if you own the current shared session. Logoff notifies all other clients that are using the current shared session that they should log off by sending an error notification.

  5. Release the session pointer by calling the session's IUnknown::Release method.

  6. If you called OleInitialize during session startup to initialize the OLE libraries, uninitialize them now by calling OleUninitialize. Only clients that have called OleInitialize must call OleUninitialize.

  7. Uninitialize the MAPI libraries by calling MAPIUninitialize. If you called OleInitialize at some point, make sure that a call to OleUninitialize occurs before this call to MAPIUninitialize. The timing is crucial. If the call to OleUninitialize follows the call to MAPIUninitialize, your client might terminate ungracefully.

  8. If you called ScInitMapiUtil during session startup to initialize the MAPI utility library, uninitialize it now by calling DeinitMapiUtil. Only clients that have called ScInitMapiUtil must call DeinitMapiUtil.

Note Note

All open objects must be released before the call to IMAPISession::Logoff. Objects that remain open after Logoff is called become invalid; they cannot accept any calls and might never be freed. If a call is made to one of these objects, expect the call to fail.

MAPI has no mechanism for deleting DLLs during the session shutdown process. A service provider's DLL can only be deleted when a configuration client such as the Control Panel calls its message service entry point function with the MSG_SERVICE_INSTALL event.


Accessing Objects by Using the Session

 Copy code hover
[image]

Accessing Objects by Using the Session
Send feedback

Published: July 16, 2012

The session pointer that you receive from your call to MAPILogonEx can be used to access a wide variety of objects. The following table lists the methods that are used to access various objects:

Object | Session method
Profile section | IMAPISession::OpenProfileSection
Message store | IMAPISession::OpenMsgStore
Address book | IMAPISession::OpenAddressBook
Message service administration object | IMAPISession::AdminServices
Folder, message, address book container, distribution list, or messaging user | IMAPISession::OpenEntry

With the OpenEntry method and a valid entry identifier, you can open any address book or message store provider object. There are other OpenEntry methods in MAPI, in addition to the IMAPISession method. OpenEntry is implemented in the following objects:

Object | Method
Address book provider's logon object | IABLogon::OpenEntry
Address book | IAddrBook::OpenEntry
Address book container | IMAPIContainer::OpenEntry
Session | IMAPISession::OpenEntry
Message store | IMsgStore::OpenEntry
Message store provider's logon object | IMSLogon::OpenEntry
Folder | IMAPIContainer::OpenEntry
Support object | IMAPISupport::OpenEntry

Some OpenEntry methods require an entry identifier of the object to be opened, as does IMAPISession::OpenEntry; other methods allow NULL to be specified. A NULL entry identifier is interpreted differently depending on the object. For example, when you call IAddrBook::OpenEntry with a NULL entry identifier, MAPI opens the root container of the address book. The message store's OpenEntry method behaves similarly; it opens the root folder of the message store. IMAPIContainer::OpenEntry, implemented by both folders and address book containers, might return MAPI_E_INVALID_PARAMETER or the root container, depending on the implementer.

In addition to disallowing a NULL value for the entry identifier, the session's OpenEntry method differs from other OpenEntry methods because its job is not to open objects. Instead, it examines the entry identifier and forwards the call to another OpenEntry method implemented by the appropriate service provider. For example, if you call IMAPISession::OpenEntry with the entry identifier of a message, MAPI calls the IMSLogon::OpenEntry method of the message store responsible for the message.

In addition to using the session to open objects, clients use it to compare them. The IMAPISession::CompareEntryIDs method compares objects by comparing their entry identifiers. If the MAPIUID structures contained within the entry identifiers belong to the same service provider, MAPI forwards the call to that provider. CompareEntryIDs returns an error value when the two entry identifiers do not match. Although this method can compare entry identifiers that belong to any type of object, CompareEntryIDs works best for higher level objects such as message stores and address book containers. To compare lower level objects, compare directly the objects' search keys (PR_SEARCH_KEY (PidTagSearchKey)) or record keys (PR_RECORD_KEY (PidTagRecordKey)).

Like OpenEntry, CompareEntryIDs is implemented by multiple objects. Choose which OpenEntry and CompareEntryID method to use according to the amount of information that you have about the object or objects to be opened or compared. Use the following guidelines when deciding which interface method to call:

  • If you have no information about the target objects, call IMAPISession::OpenEntry or IMAPISession::CompareEntryIDs. This approach enables access to any object, but is the slowest of the three.

  • If you know that the target objects are address book entries rather than, for example, folders, call the IAddrBook::OpenEntry or IAddrBook::CompareEntryIDs method. IAddrBook::OpenEntry opens the root container of the address book when NULL is specified as the target object. This approach enables access to any address book object and is faster than using IMAPISession, but slower than using IMAPIContainer.

  • If the entry identifier being used is a short-term entry identifier or if you know that the target objects belong to a particular address book container or folder, call the IMAPIContainer::OpenEntry method. This approach yields the fastest performance, but enables access only to objects in a specific container or folder.


Retrieving Primary and Provider Identity

 Copy code hover
[image]

Retrieving Primary and Provider Identity
Send feedback

Published: July 16, 2012

Service providers, typically address book providers, have the option of supplying an identity that can be used to represent the session in a variety of situations. Three properties describe a provider's identity:

  • PR_IDENTITY_ENTRYID (PidTagIdentityEntryId)

  • PR_IDENTITY_DISPLAY (PidTagIdentityDisplay)

  • PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey)

These properties are set to the entry identifier, display name, and search key of the corresponding identity object, which is typically a messaging user. Providers that supply an identity also set the STATUS_PRIMARY_IDENTITY flag in their PR_RESOURCE_FLAGS (PidTagResourceFlags) property.

Depending on your needs, you might use a particular provider's identity or the primary identity for the session. You can use a provider's identity also for display purposes or to retrieve properties, such as PR_RESOURCE_PATH (PidTagResourcePath). PR_RESOURCE_PATH, if set, contains the path to files used or created by the provider. Retrieve the PR_RESOURCE_PATH property for the provider supplying the primary identity when you want to locate files that pertain to the user of the session.

To retrieve the identity of a specific provider

  1. Call IMAPISession::GetStatusTable to access the status table.

  2. Build a restriction using an SPropertyRestriction structure to match the PR_PROVIDER_DLL_NAME (PidTagProviderDllName) column with the name of the specified provider.

  3. Call IMAPITable::FindRow to locate the provider's row. The provider's identity will be stored in the PR_IDENTITY_ENTRYID column, if it exists.

To retrieve the primary identity for a session

  • Call IMAPISession::QueryIdentity. QueryIdentity bases session identity on the existence of the STATUS_PRIMARY_IDENTITY value in the PR_RESOURCE_FLAGS column for one of the rows in the status table. If none of the status rows have this value set, QueryIdentity assigns identity to the first service provider that sets the three PR_IDENTITY properties. If no service provider supplies an identity, QueryIdentity returns MAPI_W_NO_SERVICE. When this happens, you should create a character string to represent a generic user that can serve as the primary identity.

To explicitly set the primary identity for a session

  • Call IMsgServiceAdmin::SetPrimaryIdentity. Pass the MAPIUID for the target service provider.


Status Table and Status Objects

 Copy code hover
[image]

Status Table and Status Objects
See also Send feedback

Published: July 16, 2012

MAPI provides a table with information about the status of the MAPI subsystem, MAPI spooler, address book, or a particular service provider. You can access this table by calling IMAPISession::GetStatusTable.

Each row in the status table represents a status object implemented by MAPI or a service provider. You can use a status object to display a provider's configuration property sheet, to change a provider password, to upload or download messages, and to communicate with a particular transport provider.

There are two ways to access a status object:

  • Through the status table

  • Through a logon object's OpenStatusEntry method

Because logon objects are unavailable to clients, you must use the status table to access status objects. The status table approach is indirect, requiring a few calls before the status object is opened and a pointer to its IMAPIStatus implementation returned.

To use the status table to open a status object

  1. Call IMAPIStatus::GetStatusTable to retrieve an IMAPITable pointer.

  2. Call the status table's IMAPITable::SetColumns method to limit the column set to PR_ENTRYID (PidTagEntryId), PR_RESOURCE_TYPE (PidTagResourceType), and PR_DISPLAY_NAME (PidTagDisplayName).

  3. Limit the table view to a particular status object. For MAPI implementations, a client can define a property restriction using PR_RESOURCE_TYPE. For service provider implementations, a client can restrict on PR_PROVIDER_DISPLAY (PidTagProviderDisplay), the name of the provider, or on PR_PROVIDER_DLL_NAME (PidTagProviderDllName), the name of the provider DLL file.

  4. Call IMAPITable::Restrict to set the restriction.

  5. Call HrQueryAllRows, passing in the SPropertyRestriction structure, to retrieve the row that represents the status of the provider.

  6. Call IMAPISession::OpenEntry, specifying the entry identifier from the status table row, to open the status object and retrieve an IMAPIStatus pointer.

To display a property sheet, call the status object's IMAPIStatus::SettingsDialog method for the target provider. SettingsDialog displays a property sheet for viewing and in some cases, changing the configuration properties of a provider.

To communicate with a transport provider, call its status object's IMAPIStatus::ValidateState method. ValidateState can reconfigure a transport provider, prevent the provider from displaying a user interface, and control a session that involves downloading message headers from a remote server, depending on the flags that you pass in. For example, to cancel the downloading of remote headers, pass the ABORT_XP_HEADER_OPERATION flag to ValidateState. To connect or disconnect from the remote server, pass FORCE_XP_CONNECT or FORCE_XP_DISCONNECT. To reconfigure the provider, pass CONFIG_CHANGED.

Clients that implement sending or receiving of messages on demand call either a transport provider's or the MAPI spooler's IMAPIStatus::FlushQueues method. You can pass three flags into the method: FLUSH_UPLOAD, FLUSH_DOWNLOAD, and FLUSH_FORCE. FLUSH_UPLOAD instructs the provider or the MAPI spooler to send any messages waiting in the output queue while FLUSH_DOWNLOAD instructs the provider or the MAPI spooler to receive any incoming messages. FLUSH_FORCE can be set with either of the other flags to cause the status object to perform the flush regardless of the timing.

Do not expect to be able to call SettingsDialog or ChangePassword on any of the MAPI subsystem, MAPI spooler, or address book status objects. Both the subsystem and address book status objects only support ValidateState; the MAPI spooler status object supports FlushQueues in addition to ValidateState.

See also

Concepts

Status Tables
MAPI Status Objects


Handling an Outgoing Message

 Copy code hover
[image]

Handling an Outgoing Message
Send feedback

Published: July 16, 2012

An outgoing message is a message that can be sent to one or more recipients across one or more messaging systems or be posted to a folder in a message store.

To create and send an outgoing message

  1. Open the default message store. For more information, see Opening a Message Store and Opening the Default Message Store.

  2. Open the Outbox folder. For more information, see Opening a Message Store Folder.

  3. Call the Outbox folder's IMAPIFolder::CreateMessage method to create the new message. For more information, see IMAPIFolder::CreateMessage,

  4. Create a recipient list with one or more resolved recipients. For more information, see Creating a Recipient List.

  5. Optionally, add a subject. For more information, see Creating a Message Subject.

  6. Add the message text. For more information, see Creating Message Text.

  7. If the message text is formatted, add rendering information. For more information, see Adding Rendering Information to Formatted Text.

  8. Optionally, add one or more attachments. For more information, see Creating a Message Attachment.

  9. Set other message properties as desired and then save and send the message by calling IMessage::SubmitMessage. For more information, see IMessage::SubmitMessage.

  10. Delete the sent message if the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property is set to TRUE or move it to the folder identified by the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property. For more information, see Processing a Sent Message.

If you want to intermittantly save the message before sending it, call the message's IMAPIProp::SaveChanges method. For more information, see, Saving a Message or Sending a Message.

In This Section

Creating a Recipient List

Describes how to create a recipient list.

Creating a Message Subject

Describes how to create an optional subject for a message.

Creating Message Text

Describes how to create message text.

Adding Rendering Information to Formatted Text

Describes where in formatted text an attachment is to be rendered.

Creating a Message Attachment

Describes how to create attachments.

Saving a Message

Describes how clients save messages.

Sending a Message

Describes how to send a message.

Processing a Sent Message

Describes how to sent messages can be processed.


Creating a Recipient List

 Copy code hover
[image]

Creating a Recipient List
Send feedback

Published: July 16, 2012

A recipient list is an ADRLIST structure that contains an array of property value structures for each message recipient — destination for the message. A recipient can represent a human user, a machine, or a folder. All messages to be sent require at least one recipient that has been through the name resolution process — a process for ensuring that the PR_ENTRYID (PidTagEntryId) property is included in the recipient's property value array.

The properties of a recipient are a combination of address book properties and message properties. Recipient properties can apply either to all messages for a particular recipient or only to the current message. Both message store and transport providers can set recipient properties.

Each recipient must have a core set of properties in its property value array by the time the message is ready to be sent. The required set of recipient properties include:

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_EMAIL_ADDRESS (PidTagEmailAddress)

  • PR_ENTRYID

  • PR_OBJECT_TYPE (PidTagObjectType)

  • PR_SEARCH_KEY (PidTagSearchKey)

These properties are used to access the recipient, send messages to it, and to compare it to others. Not all of these properties need to be available right away. You can add a recipient initially without knowing its entry identifier, relying on the name resolution process to assign this property. At some point before you send a message, call IAddrBook::ResolveName to make sure that all of the recipients in your recipient list are resolved. For more information, see Resolving a Recipient Name.

Recipient lists can be created from messaging users or distribution list entries in an address book container or from one-offs. One-offs are recipients that are created either as temporary entries to be used only for addressing a single message or as entries to be added to a personal address book. The format for a one-off entry identifier and address is defined by MAPI. For more information about these formats, see One-Off Addresses and One-Off Entry Identifiers.

You can enable users to build their recipient lists:

  • Only with entries from the address book.

  • Only with one-off entries.

  • With a combination of address book recipients and one-offs.

To create a recipient list using the common address dialog box

  1. Allocate an ADRPARM structure and a pointer to an ADRLIST structure.

  2. Zero the memory in the ADRPARM structure and set the ADRLIST pointer to NULL.

  3. Call IAddrBook::Address to display the address dialog box and populate the ADRPARM structure.

  4. Call IMessage::ModifyRecipients, passing the ADRLIST pointer. This structure will contain the properties of each of the recipients selected by the user.

To create a recipient list programmatically

  1. Allocate an ADRLIST structure that contains one ADRENTRY structure for each of the recipients to be included in the list. Make each ADRENTRY structure large enough to hold each of the required properties and PR_RECIPIENT_TYPE (PidTagRecipientType).

  2. For each recipient, set the property value array for its aEntries member in the ADRLIST structure.

  3. Call IMessage::ModifyRecipients with the MODRECIP_ADD flag set.


Creating a Message Subject

 Copy code hover
[image]

Creating a Message Subject
Send feedback

Published: July 16, 2012

The subject of a message, PR_SUBJECT (PidTagSubject), is an optional property, used to summarize the intent of a message. If you choose to set it, make it a character string 128 bytes or less. The 128 byte limit is not a limit imposed by MAPI; it is a limit imposed by some message store providers. To ensure interoperability with providers that do impose it, limit subjects to 128 bytes.

Be aware that some message store providers do not allow PR_SUBJECT to be written to a stream with the IStream interface.

Do not set PR_SUBJECT_PREFIX (PidTagSubjectPrefix); this property is set only on replies and forwarded messages.


Creating Message Text

 Copy code hover
[image]

Creating Message Text
Send feedback

Published: July 16, 2012

Although some messages are made up of nothing more than a recipient list and a subject line, the content of most messages, specifically IPM.Note messages, includes text. Message text can be plain or formatted and is stored in three properties: PR_BODY (PidTagBody), PR_HTML (PidTagHtml), and PR_RTF_COMPRESSED (PidTagRtfCompressed). If your client is plain text-based, set PR_BODY. If you support formatted text in the Rich Text Format (RTF), set either PR_RTF_COMPRESSED only or both PR_RTF_COMPRESSED and PR_BODY, depending on the message store provider that you are using. When an RTF-aware client is using an RTF-aware message store, it sets PR_RTF_COMPRESSED only. When an RTF-aware client is using a non-RTF-aware message store, it sets both properties. If your client supports HTML, set the PR_HTML property.

To determine whether or not your message store supports Rich Text Format

  1. Call the message store's IMAPIProp::GetProps method to retrieve the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property.

  2. Check for the STORE_RTF_OK bit. If STORE_RTF_OK is set, the message store provider supports RTF text. If it is not set, the message store provider supports plain text only.

To determine whether or not your message store supports HTML

  1. Call the message store's IMAPIProp::GetProps method to retrieve the PR_STORE_SUPPORT_MASK property.

  2. Check for the STORE_HTML_OK bit. If STORE_HTML_OK is set, the message store provider supports HTML text.

To set PR_RTF_COMPRESSED

  1. Call the message's IMAPIProp::OpenProperty method to open the PR_RTF_COMPRESSED property, specifying IID_IStream as the interface identifier and setting the MAPI_CREATE flag.

  2. Call the WrapCompressedRTFStream function, passing the STORE_UNCOMPRESSED_RTF flag if the STORE_UNCOMPRESSED_RTF bit is set in the message store's PR_STORE_SUPPORT_MASK property.

  3. Release the original stream by calling its IUnknown::Release method.

  4. Call either IStream::Write or IStream::CopyTo to write the message text to the stream returned from WrapCompressedRTFStream.

  5. Call the Commit and Release methods on the stream returned from the OpenProperty method.

At this point, if the message store provider supports RTF, you have done all that is required. You can depend on the message store provider to handle synchronizing the message content and formatting and to create the PR_BODY property if necessary. RTF-aware message stores call RTFSync to handle the synchronization. If the RTF_SYNC_BODY_CHANGED flag is set to TRUE, the provider will recompute the PR_BODY property.

If your message store provider does not support RTF, you must also add non-RTF message content by setting the PR_BODY property.

To set PR_HTML

  1. Call the IMAPIProp::OpenProperty method to open the PR_HTML property with the IStream interface.

  2. Call IStream::Write to write the message text data to the stream returned from OpenProperty.

  3. Call IStream::Commit and IUnknown::Release on the stream to commit the changes and free its memory.

To set PR_BODY

  1. Call the IMAPIProp::OpenProperty method to open the PR_BODY property with the IStream interface.

  2. Call IStream::Write to write the message text data to the stream returned from OpenProperty.

  3. Call the RTFSync function to synchronize the text with the formatting. Because this is a new message, set both the RTF_SYNC_RTF_CHANGED and RTF_SYNC_BODY_CHANGED flags to indicate that both the RTF and plain text version of the message text has changed. RTFSync will set several related properties that the message store provider requires, such as PR_RTF_IN_SYNC (PidTagRtfInSync), and write them to the message.

  4. Call IStream::Commit and IUnknown::Release on the stream to commit the changes and free its memory.


Adding Rendering Information to Formatted Text

 Copy code hover
[image]

Adding Rendering Information to Formatted Text
Send feedback

Published: July 16, 2012

To indicate the location in formatted text where an attachment is rendered, you must insert a sequence of placeholder characters in the message's PR_RTF_COMPRESSED (PidTagRtfCompressed) property. The placeholder sequence is made up of the following characters: \objattph.

To add rendering information to formatted message text

  • When writing the stream of text to the message's PR_RTF_COMPRESSED property, insert the placeholder sequence and a space character at the position where the attachment should be rendered.

  • Set the PR_RENDERING_POSITION (PidTagRenderingPosition) property of each attachment to a numeric value. The lowest value should be assigned to the PR_RENDERING_POSITION property of the first attachment to appear in the formatted text; the highest value to the last attachment.


Creating a Message Attachment

 Copy code hover
[image]

Creating a Message Attachment
See also Send feedback

Published: July 16, 2012

A message attachment is some additional data, such as a file, another message, or an OLE object, that you can send or save along with a message. Each attachment has a collection of properties that identifies it and describes its type and how it is rendered. Like recipients, message attachments can only be accessed through the message to which they belong. Therefore, for an attachment to be usable, its message must be open.

To create a message attachment

  1. Call the message's IMessage::CreateAttach method and pass NULL as the interface identifier. CreateAttach returns a number that uniquely identifies the new attachment within the message. The attachment number is stored in the PR_ATTACH_NUM (PidTagAttachNumber) property and is valid only as long as the message containing the attachment is open.

  2. Call IMAPIProp::SetProps to set PR_ATTACH_METHOD (PidTagAttachMethod) to indicate how to access the attachment. PR_ATTACH_METHOD is required. Set it to:

    • ATTACH_BY_VALUE if the attachment is binary data.

    • ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, or ATTACH_BY_REF_ONLY if the attachment is a file.

    • ATTACH_EMBEDDED_MSG if the attachment is a message.

    • ATTACH_OLE if the attachment is an OLE object.

  3. Set the appropriate attachment data property:

    • PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) for binary data and OLE 1 objects.

    • PR_ATTACH_PATHNAME (PidTagAttachPathname) for files.

    • PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) for messages and OLE 2 objects.

  4. Set PR_ATTACH_RENDERING (PidTagAttachRendering) to hold the graphic representation of the attachment for file or binary attachments. Do not set it for OLE objects, which store the rendering information internally, or for attached messages.

  5. Set PR_RENDERING_POSITION (PidTagRenderingPosition) to indicate where the attachment should be displayed. PR_RENDERING_POSITION applies only to clients that set the PR_BODY property. If you only support PR_RTF_COMPRESSED, place the following placeholder information in the compressed stream:

    Copy code Copy code
    \objattph

    To set PR_RENDERING_POSITION, assign either a number that represents an ordinal offset in characters, with the first character of PR_BODY being 0, if you need to know where in the message the attachment is rendered, or 0xFFFFFFFF, if you do not render attachments within PR_BODY.

  6. Set PR_ATTACH_FILENAME (PidTagAttachFilename) to indicate the short name of the file for a file attachment and PR_ATTACH_LONG_FILENAME (PidTagAttachLongFilename) to indicate the name of the file as supported on a platform that handles the long filename format. Both properties are optional. However, if you set PR_ATTACH_LONG_FILENAME, also set PR_ATTACH_FILENAME.

  7. Set PR_DISPLAY_NAME (PidTagDisplayName) to indicate the name for the attachment that can appear in a dialog box. PR_DISPLAY_NAME is optional.

To set PR_ATTACH_DATA_BIN

  1. Call IMAPIProp::OpenProperty to open the property with the IStream interface.

  2. If a file contains the data and it is open or if you need explicit control over buffer size, call IStream::Write in a loop to place the data in the stream.

  3. Another option is to call OpenStreamOnFile to create a stream to access the data file and then call this stream's IStream::CopyTo method to copy the data to the stream returned by OpenProperty.

  4. Call the new stream's IStream::Commit method.

To set PR_ATTACH_DATA_OBJ

  1. Call IMAPIProp::OpenProperty to open the property with the IStreamDocfile interface to create a stream that works with structured storage. IStreamDocfile is implemented by message store providers to give clients a higher-performance way to store and retrieve structured storage. The IStreamDocfile interface is the same as IStream, but the content of the stream is guaranteed to be formatted as structured storage. If this call succeeds, create the stream with the same steps outlined for setting PR_ATTACH_DATA_BIN.

  2. If OpenProperty fails:

    1. Call OpenProperty again asking for IStorage.

    2. Call StgOpenStorage to open the OLE object and return a storage object.

    3. Call the returned storage object's IStorage::CopyTo method to copy to the storage object returned from OpenProperty.

    4. Call the new storage object's IStorage::Commit method.

To set PR_ATTACH_PATHNAME

  1. Allocate an SPropValue structure, setting the ulPropTag member to PR_ATTACH_PATHNAME and the Value.LPSZ member to the character string that represents the filename.

  2. Call the attachment's IMAPIProp::SetProps method.

Note Note

If your platform supports long filenames, set both PR_ATTACH_PATHNAME and PR_ATTACH_LONG_PATHNAME. It might be necessary to make an operating system call to retrieve the short filename.

See also

Concepts

MAPI Attachments


Saving a Message

 Copy code hover
[image]

Saving a Message
Send feedback

Published: July 16, 2012

Before a message is saved, clients typically call the message's IMAPIProp::SetProps method to set a few properties in addition to the message text properties, attachment properties, PR_SUBJECT (PidTagSubject), and properties associated with the recipient list.

Set the PR_MESSAGE_CLASS (PidTagMessageClass) property to a character string such as IPM.Note that describes the class of the outgoing message. Although clients should set PR_MESSAGE_CLASS on all outgoing messages, a default value is supplied by the message store provider if you do not set it. The default message class for outgoing messages is IPM.

Set the MSGFLAG_UNSENT flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property. If desired, also set the MSGFLAG_READ and MSGFLAG_UNMODIFIED flags. Setting the MSGFLAG_UNMODIFIED allows a message under composition to simulate a delivered message. MSGFLAG_UNMODIFIED can only be set by clients before a message has been saved for the first time.

When you are ready to make a permanent copy of an unsent message, call IMAPIProp::SaveChanges on the message and all of its attachments. If you intend to send the message right away, you do not need to call SaveChanges. The call to SubmitMessage internally saves the message as part of its processing.

When calling SaveChanges, it is a good idea to specify the KEEP_OPEN_READWRITE flag, which allows the message to be modified at a later time. Other settable flags include FORCE_SAVE, which indicates that the message or attachment should be closed after changes are committed, KEEP_OPEN_READONLY, which indicates that no further changes will be made, and the flag to allow the message store provider to batch client requests, MAPI_DEFERRED_ERRORS.

It is essential that you call SaveChanges for every attachment in the message before you call SaveChanges for the message. If you fail to save an attachment, the attachment will not be included with the message when it is sent and it will not appear in the message's attachment table. If you fail to save the message after saving all of the attachments, both the message and the attachments will be lost.

When SaveChanges is called, the message store provider updates the following properties:

  • PR_DISPLAY_TO (PidTagDisplayTo) lists all primary recipients.

  • PR_DISPLAY_TO lists all carbon copy recipients.

  • PR_DISPLAY_BCC (PidTagDisplayBcc) lists all blind carbon copy recipients.

  • PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime)

  • PR_MESSAGE_FLAGS sets MSGFLAG_HASATTACH if one or more attachments have been saved and clears MSGFLAG_UNMODIFIED to show the message has changed.

  • PR_MESSAGE_SIZE (PidTagMessageSize) contains the most current size of the message.

  • PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) provides access to the attachment table.

  • PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) provides access to the recipient table.

Some message properties are typically supplied by clients or service providers when a message is created. If a client neglects to set them, it is up to the message store provider to update them at the time SaveChanges is called. For example, if a message's PR_ENTRYID (PidTagEntryId) and PR_RECORD_KEY (PidTagRecordKey) properties were set when the message was created, they need not be modified at save time. However, message store providers that neglect to set them at message creation must set them the first time that SaveChanges is called.

If SaveChanges returns MAPI_E_CORRUPT_DATA, assume that the data being saved is now lost. Message store providers that use a client-server model for their implementation might return this value when a network connection is lost or the server is not running. Before returning an error to the user, try to write and save the data a second time by making a call to SetProps followed by another call to SaveChanges. If the data is cached locally, this should not be a problem. However, if there is no local cache or the second SaveChanges call fails, display an error to alert the user to the problem.


Sending a Message

 Copy code hover
[image]

Sending a Message
Send feedback

Published: July 16, 2012

When you are ready to send a message, call its IMessage::SubmitMessage method. SubmitMessage places the message in the outgoing queue and sets the MSGFLAG_SUBMIT flag in the message's PR_MESSAGE_FLAGS (PidTagMessageFlags) property.

The message store provider, if tightly coupled to a transport provider, gives the message directly to the transport which delivers it to the messaging system. If not tightly coupled, the message store provider informs the MAPI spooler that the outgoing queue has changed and the MAPI spooler transfers the message to an appropriate transport provider.

If you allow users to cancel a send operation, call IMsgStore::AbortSubmit to implement this feature. AbortSubmit removes the message from the outgoing queue. Users can be allowed to stop a send from happening until the message is given to the underlying messaging system.

If SubmitMessage returns MAPI_E_CORRUPT_DATA, assume that the data being sent is now lost. Before attempting to send a second time, re-write the message by calling IMAPIProp::SetProps and IMAPIProp::SaveChanges. Display an error to the user if these IMAPIProp calls fail or if SubmitMessage fails a second time.

After a successful call to SubmitMessage, free any memory that was allocated for the recipient list and release the message and its attachments. Once a message has been sent, MAPI does not permit any further operations on the pointers for these objects. The one exception is calling IUnknown::Release. No other calls are allowed because many message store providers invalidate entry identifiers for messages that have been sent.


Processing a Sent Message

 Copy code hover
[image]

Processing a Sent Message
Send feedback

Published: July 16, 2012

Outgoing messages, after they have been sent, can be left in the Outbox folder, moved to a folder designated to hold sent messages, or deleted. The type of processing depends on whether or not you have set the message store properties:

  • PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit)

  • PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId)

PR_DELETE_AFTER_SUBMIT is a Boolean property, set to TRUE if messages should be deleted after they are sent, and FALSE otherwise. PR_SENTMAIL_ENTRYID is the entry identifier of a folder. When this property is set, you should move sent messages to the folder represented by this entry identifier. The saved messages typically have the identity of the last message store or transport provider to send them.

Either one or the other, or neither of these properties should be set, but not both. However, if you set PR_SENTMAIL_ENTRYID, it must contain a valid entry identifier.

The following table describes how these properties affect what you do with sent messages.

If neither property is set: | Leave the message in the folder from which it was sent (typically the Outbox).
If PR_SENTMAIL_ENTRYID is set: | Move the message to the indicated folder.
If PR_DELETE_AFTER_SUBMIT is set: | Delete the message.


Posting a Message

 Copy code hover
[image]

Posting a Message
Send feedback

Published: July 16, 2012

Posting a message is similar to sending a message. The main difference is the destination. Rather than being directed to one or more recipients across one or more messaging systems, a posted message remains in a folder in the current message store.

To post a message

  1. Open the destination folder by calling IMsgStore::OpenEntry. If the destination folder is the Inbox, locate the entry identifier to pass to OpenEntry by calling IMsgStore::GetReceiveFolder.

  2. Call IMAPIFolder::CreateMessage to create the message.

  3. Call the message's IMAPIProp::SetProps method to set:

    • The MSGFLAG_READ flag in the PidTagMessageFlags (PR_MESSAGE_FLAGS) property.

    • The PR_SENDER properties.

    • The PR_SENT_REPRESENTING properties.

    • The PR_RECEIPT_TIME (PidTagReceiptTime) property.

    • The PR_RTF_COMPRESSED (PidTagRtfCompressed) or PR_BODY (PidTagBody) property.

    • The PR_SUBJECT (PidTagSubject) property.

    • The PR_MESSAGE_CLASS (PidTagMessageClass) property.

    • Any properties required by the message class.

  4. Call the message's IMAPIProp::SaveChanges method to save the message.

  5. If necessary, create an attachment, set its properties, and save it. For more information about adding attachments to messages, see Creating a Message Attachment.

  6. Call IMessage::SaveChanges to save the message. At this point it will appear in the contents table of the destination folder.

Notice that you do not create a recipient list. Instead, you set several properties that are normally set by a transport provider for a sent message.

If you want to save a message intermittently before having it appear in the contents table of the visible folder, create it instead in a hidden folder such as the root folder of the IPM subtree and then move it to the target folder.


Resending an Undelivered Message

 Copy code hover
[image]

Resending an Undelivered Message
Send feedback

Published: July 16, 2012

A transport provider sends a non-delivery report (NDR) when it cannot successfully deliver a message that you have submitted. It is up to the client whether or not users can attempt to resend these undelivered messages. If you support resending messages, you can either use a form provided by MAPI or implement your own. The MAPI form displays the names of the failed recipients and the reason for the delivery failure, if possible, and includes a button that, when selected, allows a user to resend the message.

When a resent message is received, it should look exactly like the original message. The recipient should be unable to differentiate between a message that was delivered on its first attempt at transmission or a subsequent attempt. Replies on this message should work exactly as if the message had been sent successfully the first time.

To resend an undelivered message

  1. Call IMAPIFolder::CreateMessage to create a new message.

  2. Copy all of the properties from the original message, excluding the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property, and the PR_SENDER and PR_SENT_REPRESENTING properties. Make the following property modifications:

    • Set PR_MESSAGE_CLASS (PidTagMessageClass) to the report's PR_ORIG_MESSAGE_CLASS (PidTagOriginalMessageClass) property.

    • Set the MSGFLAG_RESEND flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property.

    • Set PR_ORIGINAL_ENTRYID (PidTagOriginalEntryId) to the original message's PR_ENTRYID (PidTagEntryId) property.

    • For each recipient, set MAPI_SUBMITTED in the PR_RECIPIENT_TYPE (PidTagRecipientType) property.

    • Duplicate each failed recipient. Change the PR_RECIPIENT_TYPE property for the duplicated recipient to MAPI_P1. Therefore, for each failed recipient there are now two entries in the recipient table: one with PR_RECIPIENT_TYPE set to its original value and the other with PR_RECIPIENT_TYPE set to MAPI_P1.

  3. Call ScCreateConversationIndex to set up conversation tracking if desired.

  4. Call the new message's IMessage::ModifyRecipients method to update the recipient list.

  5. Call IMessage::SubmitMessage to save and send the new message.


Sending a Reply

 Copy code hover
[image]

Sending a Reply
Send feedback

Published: July 16, 2012

Client applications typically support two types of replies: one that is sent only to the sender of the original message and one that is sent to all other recipients included in the recipient list of the original message in addition to the sender. This second type of reply is commonly referred to as a reply all message.

To send a reply of either type, you implement some of the same tasks that you would when you send an original message. For example, you open the default message store and the outgoing message folder, typically the Outbox, and call the outgoing folder's IMAPIFolder::CreateMessage method to create the reply. Also, you open the folder that holds the original message, typically the Inbox. For information about opening different folders, see Opening a Message Store Folder.

The main difference between creating a reply and creating an original message is that with a reply, most of the properties are either based on or copied directly from properties of the original message. Attachments — a message's PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property — are specifically excluded. The recipient list for a reply all message is created from the original message's list with the recipient represented by the PR_RECEIVED_BY_SEARCH_KEY (PidTagReceivedBySearchKey) property and all blind carbon copy recipients removed. The PR_RECEIVED_BY_SEARCH_KEY property represents the current user.

To send a reply

  1. Open the default message store. For more information, see Opening the Default Message Store.

  2. Open the Outbox folder. For more information, see Opening a Message Store Folder.

  3. Call the Outbox's IMAPIFolder::CreateMessage method to create the reply.

  4. Call the original message's IMAPIProp::CopyTo method to copy the following properties to the reply message:

    • PR_BODY (PidTagBody) or PR_RTF_COMPRESSED (PidTagRtfCompressed), depending on whether or not you support Rich Text Format.

    • PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients), if the reply will go to the entire recipient list.

    • PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject).

  5. Do not include the following properties in your call to IMAPIProp::CopyTo:

PR_CLIENT_SUBMIT_TIME | PR_MESSAGE_DELIVERY_TIME
PR_MESSAGE_DOWNLOAD_TIME | PR_MESSAGE_FLAGS
PR_ORIGINATOR_DELIVERY_ REPORT_REQUESTED | PR_RCVD_REPRESENTING properties
PR_READ_RECEIPT_ENTRYID | PR_READ_RECEIPT_REQUESTED
PR_RECEIVED_BY properties | PR_REPLY_RECIPIENT properties
PR_REPORT_ENTRYID | PR_SENDER properties
PR_SENT_REPRESENTING properties | PR_SENTMAIL_ENTRYID
PR_SUBJECT_PREFIX |

  1. Add separator text to whichever message body property you support — PR_BODY, PR_HTML, or PR_RTF_COMPRESSED.

  2. Call ScCreateConversationIndex, passing in the value of the original message's PR_CONVERSATION_INDEX (PidTagConversationIndex) property.

  3. Set a prefix for the reply. If you are using the standard "RE:", concatenate these characters onto the beginning of PR_NORMALIZED_SUBJECT and set PR_SUBJECT (PidTagSubject) to this new string. Do not set PR_SUBJECT_PREFIX (PidTagSubjectPrefix). If you are using a nonstandard prefix, such as a string longer than three characters, store it in PR_SUBJECT_PREFIX.

  4. Set the PR_SENT_REPRESENTING properties to the corresponding values in the PR_RCVD_REPRESENTING properties.

  5. Set each of the entries in PR_REPLY_RECIPIENT_ENTRIES (PidTagReplyRecipientEntries) and PR_REPLY_RECIPIENT_NAMES (PidTagReplyRecipientNames) to the entry identifier and display name of a primary recipient — a recipient whose type is MAPI_TO. Keep these properties synchronized. That is, PR_REPLY_RECIPIENT_ENTRIES and PR_REPLY_RECIPIENT_NAMES must contain the same number of entries, and an entry at a particular position in one of the properties must correspond to an entry at the same position in the other property.

  6. If the reply is being sent only to the sender of the original message, create a single entry recipient list with the recipient represented by the original message's PR_SENT_REPRESENTING property. For more information about creating a recipient list, see Creating a Recipient List.

  7. If the reply is a reply all, create a recipient list as follows:

    1. Call the original message's IMessage::GetRecipientTable method to access its recipient table.

    2. Call HrQueryAllRows to retrieve all of the rows in the table. Determine if each row represents a primary or carbon copy recipient and should remain in the list or if it represents a blind carbon copy recipient or the user and should be removed from the list.

    3. Differentiate between recipient types by looking at the PR_RECIPIENT_TYPE (PidTagRecipientType) column. This column will be set to MAPI_TO for primary recipients, MAPI_CC for carbon copy recipients, and MAPI_BCC for blind carbon copy recipients.

    4. Compare the PR_SEARCH_KEY (PidTagSearchKey) column with the PR_RECEIVED_BY_SEARCH_KEY property of the original message to determine if the row represents the user.

    5. Remove unwanted rows from the recipient list by calling MAPIFreeBuffer to free the memory associated with the corresponding entries in the recipient table's SRowSet structure. Set all of the values in the property value array to zero, all of the cValues members to zero, and all of the lpProps members in each SRow structure in the SRowSet to NULL.

    6. Add the sender to the recipient list, as represented by the original message's PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) and PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId) properties. Check that the sender is not duplicated in the list.

    7. Call the reply message's IMessage::ModifyRecipients method, setting the ulFlags parameter to zero, to create a new recipient list for the reply or forwarded message based on the list from the original message.

  8. Call the reply's IMAPIProp::SaveChanges method to save the message or IMessage::SubmitMessage to save and send it.

Note Note

Before calling IMessage::ModifyRecipients to store changes in the recipient list, you can allow users to make modifications through the message form. Users can add to the list or remove particular members. Allowing users to make changes to a recipient list is an optional client feature.


Forwarding a Message

 Copy code hover
[image]

Forwarding a Message
See also Send feedback

Published: July 16, 2012

Forwarding a message involves many of the same tasks as sending an original message. First, you must open the default message store and the folder that is designated to hold outgoing messages, typically the Outbox, and call this folder's IMAPIFolder::CreateMessage method to create the message to be forwarded. You must also open the folder that holds the original message, typically the Inbox. For information about opening different folders, see Opening a Message Store Folder.

The main difference between creating a message to be forwarded and creating the original is that with a forwarded message, most of the properties are either based on or copied directly from properties of the original message.

To forward a message

  1. Open the default message store. For more information, see Opening the Default Message Store.

  2. Open the Outbox folder. For more information, see Opening a Message Store Folder.

  3. Call the Outbox's IMAPIFolder::CreateMessage method to create a new forwarded message.

  4. Call the original message's IMAPIProp::CopyTo method to copy the following properties to the forwarded message:

    • PR_BODY (PidTagBody), PR_HTML (PidTagHtml), or PR_RTF_COMPRESSED (PidTagRtfCompressed), depending on whether or not you support Rich Text Format, plain text, or HTML.

    • PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject)

  5. Copy the message attachments from the original message either by calling the original message's IMAPIProp::CopyTo method to copy the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property or by invoking the following three step procedure for each attachment to be copied:

    1. Call the new forwarded message's IMessage::CreateAttach method to create a new attachment.

    2. Call the original message's IMessage::OpenAttach method to open the attachment to be copied.

    3. Call the original message's IMAPIProp::CopyTo method to copy all of the attachment properties from the old attachment to the new one.

  6. Do not include the following properties in your call to IMAPIProp::CopyTo:

PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) | PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)
PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime) | PR_MESSAGE_FLAGS (PidTagMessageFlags)
PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) | PR_RCVD_REPRESENTING properties
PR_READ_RECEIPT_ENTRYID (PidTagReadReceiptEntryId) | PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested)
PR_RECEIVED_BY properties | PR_REPLY_RECIPIENT properties
PR_REPORT_ENTRYID (PidTagReportEntryId) | PR_SENDER properties
PR_SENT_REPRESENTING properties | PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId)
PR_SUBJECT_PREFIX (PidTagSubjectPrefix) |

  1. Format the message text by adding indentation and a header paragraph that includes the original sender, date of transmission, subject, and recipient list. Do not include Internet-style prefix characters with the content.

  2. Call ScCreateConversationIndex, passing in the value of the original message's PR_CONVERSATION_INDEX (PidTagConversationIndex) property.

  3. Set a prefix for the forwarded message. If you are using the standard "FW:", concatenate these characters onto the beginning of PR_NORMALIZED_SUBJECT and set PR_SUBJECT (PidTagSubject) to this new string. Do not set PR_SUBJECT_PREFIX (PidTagSubjectPrefix). If you are using a nonstandard prefix, such as a string longer than three characters, store it in PR_SUBJECT_PREFIX.

  4. Set the PR_SENT_REPRESENTING properties to the corresponding values in the PR_RCVD_REPRESENTING properties.

  5. Create a recipient list. For more information, see Creating a Recipient List.

  6. Call the forwarded message's IMAPIProp::SaveChanges method to save it or IMessage::SubmitMessage to save and send it.

See also

Reference

PidTagMessageAttachments Canonical Property


Handling an Incoming Message

 Copy code hover
[image]

Handling an Incoming Message
Send feedback

Published: July 16, 2012

An incoming message is a message that has been sent across one or more messaging systems. It may have been sent only to you or to many other recipients. Incoming messages are placed in a receive folder designated to hold messages of a particular class. You can set up a different receive folder for each message class that you handle or use one folder for all of the classes.

If you have registered for new mail notifications with the message store, you will be notified whenever a message is placed in a receive folder. If you have not registered for new mail notifications, you must open the appropriate receive folder periodically to manually check for the arrival of new messages.

Clients register for new mail notifications by setting the parameters to IMsgStore::Advise as follows:

  • Set cbEntryID to 0.

  • Set lpEntryID to NULL.

  • Set ulEventMask to fnevNewMail.

The lpNotifications parameter in the call to your IMAPIAdviseSink::OnNotify method points to a NEWMAIL_NOTIFICATION structure that contains information about the incoming message, such as its message class, its entry identifier, the entry identifier of its parent folder, and the contents of its PR_MESSAGE_FLAGS property. For more information about registering for and handling notifications, see IMAPIAdviseSink::OnNotify, NEWMAIL_NOTIFICATION, PR_MESSAGE_FLAGS (PidTagMessageFlags), and Handling Notifications.

Before displaying an incoming message to a user, determine if its message class is a class that your client supports. If not, ignore the message. If the class is one that you support, you can open and display the message with a form that is appropriate for the message class of the message. The choice of forms is based on message class. Messages that belong to the IPM class use a default form implemented by MAPI. Messages that belong to custom classes defined by clients can use either client-defined specialized forms or the MAPI default form.

To open and display an incoming message

  1. Call IMsgStore::GetReceiveFolder to retrieve the entry identifier of the receive folder for the message class of the message and pass this entry identifier to IMsgStore::OpenEntry to open the folder. For more information, see IMsgStore::GetReceiveFolder, IMsgStore::OpenEntry, and Opening a Message Store Folder.

  2. Call the receive folder's IMAPIContainer::GetContentsTable method to retrieve its contents table. For more information, see IMAPIContainer::GetContentsTable. Call the table's IMAPITable::QueryRows method to retrieve all the rows in the table. For more information see IMAPITable::QueryRows and Contents Tables. For more information about displaying a contents table, see Displaying a Folder Contents Table.

  3. If your client is interactive, allow the user to select a message from the table and determine the form to be used to display that message. Clients can use the default form provided by MAPI or a custom form. For more information, see Handling MAPI Forms.

  4. Call IMsgStore::OpenEntry to open the message. For more information, see Opening a Message.

  5. Process the message text. For more information, see Opening Message Text.

  6. Render each of the message attachments. For more information, see Rendering an Attachment in Plain Text or Rendering an Attachment in RTF Text.

  7. Open an attachment if desired. For more information see Opening an Attachment.

In This Section

Opening Message Text

Describes how to open the message text.

Rendering an Attachment in Plain Text

Describes how to render an attachment in plain text.

Rendering an Attachment in RTF Text

Describes how to render an attachment in formatted text.

Opening an Attachment

Describes how to open an attachment.


Opening Message Text

 Copy code hover
[image]

Opening Message Text
Send feedback

Published: July 16, 2012

The text of a message is stored either in its PR_BODY property or PR_RTF_COMPRESSED property. For more information, see PR_BODY (PidTagBody), PR_HTML (PidTagHtml), and PR_RTF_COMPRESSED (PidTagRtfCompressed). If you support the Rich Text Format (RTF), open PR_RTF_COMPRESSED. If you do not support RTF, open PR_BODY. Because the text of a message can be large regardless of whether or not it is formatted, use IMAPIProp::OpenProperty to open these properties. For more information, see IMAPIProp::OpenProperty.

To display formatted message text

  1. If you are using a non-RTF aware message store, as indicated by the absence of the STORE_RTF_OK flag in the store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property:

    1. Call the message's IMAPIProp::GetProps method to retrieve the PR_RTF_IN_SYNC property. For more information, see IMAPIProp::GetProps and PR_RTF_IN_SYNC (PidTagRtfInSync).

    2. Call RTFSync to synchronize the message's PR_BODY property with the PR_RTF_COMPRESSED property. For more information, see RTFSync, PR_BODY, and PR_RTF_COMPRESSED. Pass the RTF_SYNC_BODY_CHANGED flag if the call to retrieve PR_RTF_IN_SYNC failed because the property does not exist or it is set to FALSE.

    3. If RTFSync returned TRUE — indicating that changes were made — call the message's IMAPIProp::SaveChanges method to permanently store them. For more information, see IMAPIProp::SaveChanges.

  2. Regardless of whether or not you are using an RTF-aware message store:

    1. Call IMAPIProp::OpenProperty to open the PR_RTF_COMPRESSED property. For more information, see IMAPIProp::OpenProperty and PR_RTF_COMPRESSED.

    2. If PR_RTF_COMPRESSED is not available, call OpenProperty to open the PR_BODY property.

    3. Call the WrapCompressedRTFStream function to create an uncompressed version of the compressed RTF data, if available. For more information, see WrapCompressedRTFStream.

    4. Copy the formatted text from the stream to the appropriate place in the message form.

To display plain message text

  1. Call the message's IMAPIProp::GetProps method to retrieve the PR_BODY property. For more information, see IMAPIProp::GetProps.

  2. If GetProps returns either PT_ERROR for the property type in the property value structure or MAPI_E_NOT_ENOUGH_MEMORY, call the message's IMAPIProp::OpenProperty method. Pass PR_BODY as the property tag and IID_IStream as the interface identifier. For more information, see IMAPIProp::OpenProperty.

  3. Copy the plain text from the stream to the appropriate place in the message form.


Rendering an Attachment in Plain Text

 Copy code hover
[image]

Rendering an Attachment in Plain Text
Send feedback

Published: July 16, 2012

To render an attachment in a message with plain text, retrieve the attachment's PR_RENDERING_POSITION (PidTagRenderingPosition) property and apply it to the data in the PR_ATTACH_RENDERING (PidTagAttachRendering) property. There are two ways to retrieve PR_RENDERING_POSITION:

  • Open the attachment by calling the message's IMessage::OpenAttach method and then ask for the PR_RENDERING_POSITION property by calling the attachment's IMAPIProp::GetProps method. For more information, see IMessage::OpenAttach and IMAPIProp::GetProps.

  • Call the message's IMessage::GetAttachmentTable method to access its attachment table and retrieve the column that holds the PR_RENDERING_POSITION property. This way is always preferable. For more information, see IMessage::GetAttachmentTable.

Keep in mind that many RTF-aware message stores do not calculate PR_RENDERING_POSITION until a client requests the PR_BODY (PidTagBody) property of a message. Until that time, PR_RENDERING_POSITION usually represents an approximate value. Message store providers are allowed to supply clients with an approximate value to enhance performance.

The rendering for a file or binary attachment is stored in its PR_ATTACH_RENDERING property. You have the choice of retrieving PR_ATTACH_RENDERING in the same ways as you retrieved PR_RENDERING_POSITION: directly from the attachment or from the attachment table. For PR_ATTACH_RENDERING, the first strategy, although more time-consuming, is safer. Because some message store providers truncate their table columns to 255 bytes, or in a few cases 510 bytes, it is difficult to be sure that the PR_ATTACH_RENDERING column contains the complete rendering. When retrieving the property directly from the attachment, it will always be complete.

Neither OLE nor message attachments set PR_ATTACH_RENDERING. Instead, rendering information for OLE 1 attachments is stored in the message text stream. For OLE 2 attachments, it is stored in a special child stream of the storage object. Rendering information for message attachments is available through the form manager.

To retrieve the rendering for a message attachment

  1. Use the message class of the message to access the form manager.

  2. Access the form manager's PR_MINI_ICON property. For more information, see PR_MINI_ICON (PidTagMiniIcon).


Rendering an Attachment in RTF Text

 Copy code hover
[image]

Rendering an Attachment in RTF Text
Send feedback

Published: July 16, 2012

Rich Text Format (RTF)-aware clients can retrieve rendering position information from RTF message text by looking for the following escape sequence in the message's PR_RTF_COMPRESSED (PidTagRtfCompressed) property:

\objattph

To locate rendering information in formatted text

  1. Call IMessage::GetAttachmentTable to access the message's attachment table. For more information, see IMessage::GetAttachmentTable.

  2. Build a property restriction that limits the table to rows that have PR_RENDERING_POSITION not equal to -1. For more information, see PR_RENDERING_POSITION (PidTagRenderingPosition).

  3. Call IMAPITable::Restrict to enforce the restriction. For more information, see IMAPITable::Restrict.

  4. Call IMAPITable::SortTable to sort the attachments. For more information, see IMAPITable::SortTable.

  5. Call IMAPITable::QueryRows to retrieve the appropriate rows. For more information, see IMAPITable::QueryRows.

  6. Call the message's IMAPIProp::OpenProperty method to retrieve PR_RTF_COMPRESSED with the IStream interface. For more information, see IMAPIProp::OpenProperty and PR_RTF_COMPRESSED.

  7. Scan the stream, looking for the rendering placeholder, \objattph. The character following this placeholder is the place for the next attachment in the sorted table.


Opening an Attachment

 Copy code hover
[image]

Opening an Attachment
Send feedback

Published: July 16, 2012

Opening an attachment involves displaying its data. For example, when a file attachment is opened, the contents of the file are displayed. Whereas messages and folders are opened using their entry identifiers, attachments are opened using their attachment numbers — PR_ATTACH_NUM properties. For more information, see PR_ATTACH_NUM (PidTagAttachNumber). Attachment numbers are available through a message's attachment table.

To open all attachments in a message

  1. Call the message's IMessage::GetAttachmentTable method to access its attachment table.

  2. Call HrQueryAllRows to retrieve all the rows in the table.

  3. For each row:

    1. Open the attachment by passing the attachment number represented in the PR_ATTACH_NUM column in a call to the message's IMessage::OpenAttach method. For more information, see IMessage::OpenAttach. OpenAttach returns a pointer to an IAttach implementation that provides access to attachment properties.

    2. Call the attachment's IMAPIProp::GetProps method to retrieve its PR_ATTACH_METHOD property. For more information, see IMAPIProp::GetProps and PR_ATTACH_METHOD (PidTagAttachMethod).

    3. If PR_ATTACH_METHOD is set to ATTACH_BY_REF_ONLY, call IMAPIProp::GetProps to retrieve the PR_ATTACH_PATHNAME property. For more information, see PR_ATTACH_PATHNAME (PidTagAttachPathname).

    4. If PR_ATTACH_METHOD is set to ATTACH_BY_VALUE, call IMAPIProp::OpenProperty to open the PR_ATTACH_DATA_BIN property with the IStream interface. See the sample code following this procedure. For more information, see IMAPIProp::OpenProperty and PR_ATTACH_DATA_BIN (PidTagAttachDataBinary).

    5. If PR_ATTACH_METHOD is set to ATTACH_OLE and the attachment is an OLE 2 object:

      1. Call IMAPIProp::OpenProperty to open the PR_ATTACH_DATA_OBJ property with the IStreamDocfile interface. Attempt to use this interface because it is an implementation of IStream guaranteed to work with structured storage with the least amount of overhead. For more information, see PR_ATTACH_DATA_OBJ (PidTagAttachDataObject).

      2. If the OpenProperty call fails, call it again to retrieve the PR_ATTACH_DATA_BIN property with the IStreamDocfile interface.

      3. If this second OpenProperty call fails, try again to call OpenProperty to retrieve PR_ATTACH_DATA_OBJ. However, rather than specifying IStreamDocfile, specify the IStorage interface.

  4. If PR_ATTACH_METHOD is set to ATTACH_EMBEDDED_MSG, it is not unusual for the value of PR_ATTACH_DATA_OBJ to contain an error. This is because you and the table implementer have no way to agree on the type of object to return. To retrieve a pointer to the attached message, open the attachment using IMessage::OpenAttach. Then access the attachment data by calling its IMAPIProp::OpenProperty method. For more information, see IMessage::OpenAttach and IMAPIProp::OpenProperty.

You can request that an attachment is opened in read/write or read-only mode. Read-only is the default mode, and many message store providers open all attachments in this mode regardless of what clients request. Pass the MAPI_BEST_ACCESS flag to request that the message store provider grant the highest level of access it can and then retrieve the open attachment's PR_ACCESS_LEVEL property to determine the level of access that was actually granted. For more information, see PR_ACCESS_LEVEL (PidTagAccessLevel).

The following example shows how to open the data in an attachment's PR_ATTACH_DATA_BIN property. It allocates pointers to two streams: one for the file and one for the attachment. The OpenStreamOnFile function opens the file stream in read-only mode. The call to the attachment's IMAPIProp::OpenProperty method opens the attachment stream in read/write mode. For more information, see PR_ATTACH_DATA_BIN, OpenStreamOnFile, and IMAPIProp::OpenProperty. The code then copies from the file stream to the attachment stream and releases both streams.

C++ Copy code Copy code
LPSTREAM pStreamFile, pStreamAtt;
HRESULT hr;
hr = OpenStreamOnFile (MAPIAllocateBuffer, MAPIFreeBuffer,
                       STGM_READ, "myfile.doc", NULL, &pStreamFile);
if (HR_SUCCEEDED(hr))
{
    // Open the destination stream in the attachment object
    hr = pAttach->OpenProperty (PR_ATTACH_DATA_BIN,
                                &IID_IStream,
                                0,
                                MAPI_MODIFY | MAPI_CREATE,
                                (LPUNKNOWN *)&pStreamAtt);
    if (HR_SUCCEEDED(hr))
    {
        STATSTG StatInfo;
        pStreamFile->Stat (&StatInfo, STATFLAG_NONAME);
        hResult = pStreamFile->CopyTo (pStreamAtt, StatInfo.cbSize,
                                       NULL, NULL);
        pStreamAtt->Release();
    }
    pStreamFile->Release();
}


Handling a Message Store

 Copy code hover
[image]

Handling a Message Store
Send feedback

Published: July 16, 2012

Handling a message store is an important part of any client's set of tasks. These tasks include opening, copying, moving, adding, and deleting folders and messages, displaying various tables, setting properties, and controlling access levels.

Opening a Message Store

Describes how to open one or more message stores during a session.

Opening the Default Message Store

Describes how to open the default message store.

Validating and Initializing a Message Store

Describes how to initialize and validate a message store.

Searching a Message Store

Describes how to look through one or more folders looking for messages that match search criteria.

Selecting a Receive Folder

Describes the steps for creating a receive folder.

Opening a Message Store Folder

Describes how to open a folder.

Displaying a Folder Contents Table

Describes how to display the folder contents table that contains summary information about all of its messages.

Traversing the Inbox Folder

Describes how to cycle through all the messages in the Inbox.

Copying or Moving a Message or a Folder

Describes how to copy or move one or more messages.

Opening a Message

Describes how to open a message.

Finding the Icon for a Message

Describes how to find an icon that is associated with a message.

Opening a View Descriptor

Describes how to open a view descriptor.

Deleting a Message

Describes how to delete a message.

Saving a Message in the Inbox

Describes how to store a message in the Inbox.

Finding Sent or Saved Messages

Describes how to locate all outgoing messages that have been saved or sent.

Tracking Conversations

Describes how to track conversations.


Opening a Message Store

 Copy code hover
[image]

Opening a Message Store
See also Send feedback

Published: July 16, 2012

Depending on the profile, a client will need to open one or more message stores during a typical session. Opening a message store means gaining access to a pointer to its IMsgStore : IMAPIProp implementation. The IMsgStore interface provides methods for notification, making folder assignments, and accessing folders and messages.

Clients open message stores at logon and when a profile is being modified. If your client allows users to add message stores to the profile during an active session, you can either open them immediately or ignore them until the next session. By registering for notifications on the message store table, you will be alerted to the availability of a new message store.

To open a message store, you must have its entry identifier available. Most clients access the entry identifiers for the message stores they wish to open through the message store table. However, some message stores document the format of their entry identifiers, thereby enabling clients to bypass the message store table and construct the necessary entry identifier. They can pass this entry identifier directly to IMAPISession::OpenMsgStore and MAPI automatically creates a profile section for the provider without associating it with any message service.

To retrieve an entry identifier from the message store table

  1. Call IMAPISession::GetMsgStoresTable to open the message store table.

  2. Call IMAPITable::SetColumns to limit the table to a small column set that includes the following columns:

    PR_PROVIDER_DISPLAY or PR_DISPLAY_NAME

    PR_ENTRYID properties

    PR_MDB_PROVIDER

    PR_RESOURCE_FLAGS

  3. Build a restriction to filter out the row that represents the message store to be opened. For more information about looking for the default message store, see Opening the Default Message Store. To look for a message store by name, apply any of the following property restrictions:

    • Match PR_PROVIDER_DISPLAY (PidTagProviderDisplay) with the general name for this type of message store. For example, PR_PROVIDER_DISPLAY might be set to "Personal Folders".

    • Match PR_MDB_PROVIDER (PidTagStoreProvider) with the specific MAPIUID for this type of message store.

    • Match PR_DISPLAY_NAME (PidTagDisplayName) with the name for this particular message store. For example, PR_DISPLAY_NAME might be set to "My Messages for Fiscal Year 2010."

  4. Call HrQueryAllRows to retrieve the appropriate row from the message store table. The entry identifier for the row will be included in the property value array for the aRow member of the row set pointed to by the pprows parameter.

  5. Call FreeProws to free the row set pointed to by pprows.

  6. Release the message store table by calling its IUnknown::Release method.

If you have created a custom entry identifier for the message store to be opened, call the WrapStoreEntryID function to convert it to a standard entry identifier.

After you have a message store's entry identifier, call one of the following methods to open it:

  • IMAPISession::OpenMsgStore

  • IMAPISession::OpenEntry

Call OpenMsgStore if you need to specify a variety of special options for the message store. OpenMsgStore allows you to suppress the display of dialog boxes, identify the message store as temporary or as a nonmessaging store, set access levels, and to defer errors. OpenEntry allows you only to set access levels and defer errors.

Setting the MDB_NO_MAIL flag indicates to MAPI that the message store will not be used for sending or receiving messages. MAPI does not inform the MAPI spooler about the existence of this message store. The MDB_TEMPORARY flag designates a message store as temporary, implying that it cannot be used to store permanent information. Temporary message stores do not appear in the message store table.

See also

Reference

IMAPITable::SetColumns


Opening the Default Message Store

 Copy code hover
[image]

Opening the Default Message Store
See also Send feedback

Published: July 16, 2012

In any particular session, one message store acts as the default message store. A default message store has the following characteristics:

  • The PR_DEFAULT_STORE (PidTagDefaultStore) property is set to TRUE.

  • The STATUS_DEFAULT_STORE flag is set in the PR_RESOURCE_FLAGS (PidTagResourceFlags) property.

  • MAPI automatically creates the IPM subtree and the root folders for search-results, common views and personal views when the message store is opened. For more information about these folders, see IPM Subtree and MAPI Special Folders.

To retrieve the entry identifier for the default message store, you must call IMAPISession::GetMsgStoresTable to open the message store table and apply an appropriate restriction in a call to HrQueryAllRows. HrQueryAllRows will return a row set with the one row that represents the default message store. The restriction that you pass to HrQueryAllRows can take on one of the following forms:

  1. An AND restriction that uses an SAndRestriction structure to combine:

    • An exists restriction that uses an SExistRestriction structure to test for the existence of the PR_DEFAULT_STORE property.

    • A property restriction that uses an SPropertyRestriction structure to check for the TRUE value in the PR_DEFAULT_STORE property.

  2. A bitmask restriction that uses an SBitMaskRestriction structure for applying STATUS_DEFAULT_STORE as a mask against the PR_RESOURCE_FLAGS property.

See also

Reference

SExistRestriction
SAndRestriction


Validating and Initializing a Message Store

 Copy code hover
[image]

Validating and Initializing a Message Store
Send feedback

Published: July 16, 2012

When you open a message store through the IMAPISession::OpenMsgStore method without setting the MDB_NO_MAIL flag, MAPI creates several folders and assigns them default names and roles. MAPI is responsible for creating these folders to avoid the incompatibilities that would inevitably occur if either clients or message store providers were responsible for the creation.

Sometimes it is necessary to verify that the appropriate folders have been created and that they are valid. The HrValidateIPMSubtree function is available for this purpose. If you are validating the default message store, pass the MAPI_FULL_IPM_TREE flag. A more extensive group of folders is created for the default message store. When HrValidateIPMSubtree receives the MAPI_FULL_IPM_TREE flag, it checks for the following folders:

  • Root folder for the IPM subtree

  • Deleted Items folder in the IPM root folder

  • Inbox folder in the IPM root folder

  • Outbox folder in the IPM root folder

  • Sent Items folder in the IPM root folder

  • Folder views in the message store's root folder

  • Common views in the message store's root folder

  • Search folder in the message store's root folder

If the message store is not the default, you can either set or not set the MAPI_FULL_IPM_TREE flag. When this flag is not set, HrValidateIPMSubtree checks for only the root folder for the subtree, the Deleted Items folder, and the root folder for message store search results.

To initialize a message store, store the following properties in memory so that they are readily available:

  • PR_VALID_FOLDER_MASK (PidTagValidFolderMask)

  • PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask)

These properties are bitmasks that describe features of the message store. PR_VALID_FOLDER_MASK has one bit set for every special folder that exists in the message store and has an assigned entry identifier that is valid. For more information about accessing these folders and their entry identifiers, see Opening a Message Store Folder.

PR_STORE_SUPPORT_MASK has one bit set for every feature supported in the message store. For example, if a message store supports notification and formatted text, its PR_STORE_SUPPORT_MASK will have the STORE_NOTIFY_OK and STORE_RTF_OK bits set.

Other properties that should be stored locally include the entry identifiers for the folders that the PR_VALID_FOLDER_MASK property describes as valid. Each of these special folders, except for the Inbox folder, has an entry identifier property associated with it. For example, the entry identifier for the Outbox folder is its PR_IPM_OUTBOX_ENTRYID (PidTagIpmOutboxEntryId) property. Because these folders are the folders that will be opened frequently, it is a good idea to have their entry identifiers readily available.


Searching a Message Store

 Copy code hover
[image]

Searching a Message Store
Send feedback

Published: July 16, 2012

Client applications can search through one or more folders looking for messages that match search criteria. The most straightforward search technique involves applying a restriction to define criteria and placing the results into a search-results folder, created explicitly for this search or for a prior search. Not all message stores support this technique. To determine whether or not the message store you are using supports using search-results folders, call its IMAPIProp::GetProps method to retrieve the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property. If the STORE_SEARCH_OK flag is set, searching is supported. If it is not set, you'll need an alternate approach such as manually inspecting the target folders.

To search one or more folders in a message store

  1. If you have a search-results folder from a previous search, skip to step 2. Otherwise, to create a search-results folder:

    1. Retrieve the entry identifier for the search-results root folder by calling the message store's IMAPIProp::GetProps method and requesting PR_FINDER_ENTRYID (PidTagFinderEntryId).

    2. Call IMsgStore::OpenEntry to open the folder represented by PR_FINDER_ENTRYID.

    3. Call the folder's IMAPIFolder::CreateFolder method to create a search-results folder with the FOLDER_SEARCH flag set.

  2. Build a restriction to hold your search criteria.

  3. Create an array of entry identifiers that represent the folders to search. This step is unnecessary if the search-results folder has been used before and you want to search the same folders.

  4. Call the search-results folder's IMAPIContainer::SetSearchCriteria method, pointing lpContainerList to the entry identifier array and lpRestriction to the restriction.

  5. If you have registered for search complete notifications with the message store, wait for the notification to arrive.

  6. View the results of the search by calling the search-results folder's IMAPIContainer::GetContentsTable method to access its contents table.

  7. Call the contents table's IMAPITable::QueryRows method to retrieve the messages that satisfy the search criteria.


Selecting a Receive Folder

 Copy code hover
[image]

Selecting a Receive Folder
Send feedback

Published: July 16, 2012

A receive folder is where incoming messages of a particular class are placed. For IPM and related report messages, MAPI assigns the Inbox as the default receive folder. For IPC and related report messages, MAPI assigns the root folder of the message store as the default receive folder. You can change these assignments or make additional assignments for other message classes. Making explicit receive folder assignments for your client's supported message classes is optional.

When an incoming message class does not have an assigned receive folder, the message store provider automatically uses the receive folder for the class that matches the longest possible prefix of the incoming class. For example, if your client receives a message of class IPM.Note.MyDocument and the only receive folder that has been established is the Inbox for IPM messages, this message will be placed in the Inbox because IPM.Note.MyDocument derives from the base class IPM.

When you are assigning a receive folder for IPC messages, never use a folder from the IPM subtree. These folders should be reserved for IPM messages only. Use instead a folder that is contained within the message store's root folder.

To create a receive folder for an IPM message class

  1. Call the message store's IMAPIProp::GetProps method to retrieve the PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId) property.

  2. Call IMsgStore::OpenEntry with PR_IPM_SUBTREE_ENTRYID as the entry identifier to open the root folder of the IPM subtree in the message store.

  3. Call IMAPIFolder::CreateFolder to create the receive folder.

  4. Call IMsgStore::SetReceiveFolder to map the new folder to your IPM message class.

To create a receive folder for an IPC message class

  1. Call IMsgStore::OpenEntry with a null entry identifier to open the root folder of the message store.

  2. Call IMAPIFolder::CreateFolder to create the receive folder.

  3. Call IMsgStore::SetReceiveFolder to map the new folder to your IPC message class.

Assign the receive folder that you use for messages for related report messages. For example, if your client receives IPM.Note messages, set up one receive folder for future IPM.Note messages and the same receive folder for future Report.IPM.Note messages.


Opening a Message Store Folder

 Copy code hover
[image]

Opening a Message Store Folder
See also Send feedback

Published: July 16, 2012

Before any folder can be opened, its entry identifier must be available. For most folders, this means retrieving their PR_ENTRYID properties. For special folders, such as some of the IPM subtree folders and other root folders, MAPI defines special entry identifier properties that are accessible by calling the message store's IMAPIProp::GetProps method. These entry identifiers are always long-term and are named as follows:

Folder | Entry identifier property
Outbox folder | PR_IPM_OUTBOX_ENTRYID (PidTagIpmOutboxEntryId) (IPM message class only)
Deleted Items folder | PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId)
Sent Items folder | PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId)
IPM root folder | PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId)
Search-results root folder | PR_FINDER_ENTRYID (PidTagFinderEntryId)
Common views root folder | PR_COMMON_VIEWS_ENTRYID (PidTagCommonViewsEntryId)
Personal views root folder | PR_VIEWS_ENTRYID (PidTagViewsEntryId)
Contacts root folder | PR_IPM_CONTACT_ENTRYID (PidTagIpmContactEntryId)
Drafts root folder | PR_IPM_DRAFTS_ENTRYID (PidTagIpmDraftsEntryId)
Journal root folder | PR_IPM_JOURNAL_ENTRYID (PidTagIpmJournalEntryId)
Calendar root folder | PR_IPM_APPOINTMENT_ENTRYID (PidTagIpmAppointmentEntryId)
Notes root folder | PR_IPM_NOTE_ENTRYID (PidTagIpmNoteEntryId)
Tasks root folder | PR_IPM_TASK_ENTRYID (PidTagIpmTaskEntryId)

Before you try to retrieve one of these special entry identifiers, retrieve the PR_VALID_FOLDER_MASK (PidTagValidFolderMask) property of the message store. PR_VALID_FOLDER_MASK is a bitmask that identifies which of the special entry identifiers exist. There is one bit for each of the special folders. If the bit is set, it indicates that the corresponding folder is supported and has a valid entry identifier. For example, if the Deleted Items folder exists and has a valid entry identifier, the FOLDER_IPM_WASTEBASKET_VALID bit will be set in PR_VALID_FOLDER_MASK.

To open the folder where all incoming messages of a particular class are placed

  1. Call IMsgStore::GetReceiveFolder to retrieve its entry identifier, setting the lpszMessageClass parameter to point to a character string identifying the message class. For example, if you want to open the Inbox for your IPM subtree, point lpszMessageClass to IPM. If you want to open the receive folder for IPC messages, set it to point to IPC. If there is no registered receive folder for the message class, GetReceiveFolder chooses the receive folder whose associated message class matches the longest possible prefix of the message class passed in. For more information, see MAPI Receive Folders. Note that the PR_IPM_OUTBOX_ENTRYID property is used to open the Outbox folder only for IPM messages. If you are opening the Outbox for IPC messages, use instead the entry identifier for its receive folder. Both incoming and outgoing IPC messages are placed in the receive folder.

  2. Call one of four OpenEntry methods to open the folder and return an interface pointer that you can use to access it. You can call any one of the following methods to open a folder:

    • IMAPISession::OpenEntry

    • IMSLogon::OpenEntry

    • IMsgStore::OpenEntry

    • IMAPIContainer::OpenEntry

    The specific method that you choose depends on the folder to be opened and the objects that are available at the time. Because the IMAPISession method can open any folder for any message store in the current profile, call this OpenEntry when you do not know anything about the folder to be opened. If you know which message store owns the folder and you have a pointer to the message store, call IMsgStore::OpenEntry. For example, use the IMsgStore method to open a receive folder. If you have a pointer to the message store provider's logon object, call IMSLogon::OpenEntry. Because these calls go directly to the message store provider rather than through MAPI, processing is faster. If the folder you are opening is a subfolder of a folder that you already have open, call the open folder's IMAPIContainer::OpenEntry method. The IMAPIContainer method only opens subfolders of a currently opened folder and is the only method guaranteed to work with short-term entry identifiers.

  3. If you want to be able to make changes to the folder to be opened, specify an access level by setting either the MAPI_BEST_ACCESS or MAPI_MODIFY flag in the OpenEntry call. These flags are suggestions to the message store provider to grant the highest level of access, for MAPI_BEST_ACCESS, or read/write access, for MAPI_MODIFY, when opening the folder. Because these flags are only suggestions, the folder may or may not be opened with the access level you expect. By retrieving the PR_ACCESS (PidTagAccess) property, you can determine the range of operations that can be performed on the open folder. However, because many message store providers calculate the value for this property on demand rather than supporting it as a folder property or as a column in their hierarchy table, retrieving it can be time-consuming. An alternate strategy is to attempt whatever operation you need to perform and return an error if necessary.

See also

Reference

PidTagEntryId Canonical Property
IMAPIProp::GetProps


Displaying a Folder Contents Table

 Copy code hover
[image]

Displaying a Folder Contents Table
Send feedback

Published: July 16, 2012

The contents table of a folder contains summary information about all of its messages. Summary information about new incoming messages appears in the contents table of the receive folder for the message class. To make this information available to users, retrieve the table and display the columns and rows as appropriate.

To display a folder contents table

  1. Call IMsgStore::OpenEntry, passing the entry identifier of the folder containing the table.

  2. Call the folder's IMAPIContainer::GetContentsTable method to open its contents table.

  3. Limit your view of the contents table if desired by calling the table's IMAPITable::SetColumns method to specify particular columns.

  4. Limit your view of the contents table if desired by calling the table's IMAPITable::Restrict method to filter particular rows. If, for example, you want to show only messages with a specific message class that have yet to be read:

    1. Create a property restriction in an SPropertyRestriction structure that matches the PR_MESSAGE_CLASS (PidTagMessageClass) property with the desired message class.

    2. Create a bitmask restriction in an SBitMaskRestriction structure that uses PR_MESSAGE_FLAGS (PidTagMessageFlags) as the property tag and the MSGFLAG_UNREAD value as the mask.

    3. Create a restriction in an SAndRestriction structure that joins the property and bitmask restrictions.

  5. Sort the contents table if desired by calling the table's IMAPITable::SortTable method.

  6. Call IMAPITable::QueryRows to retrieve all of the rows from the contents table for processing.


Traversing the Inbox Folder

 Copy code hover
[image]

Traversing the Inbox Folder
Send feedback

Published: July 16, 2012

To cycle through all of the messages in the Inbox

  1. Call IMsgStore::GetReceiveFolder to retrieve the entry identifier of the Inbox.

  2. Call IMAPIFolder::OpenEntry to open the Inbox.

  3. Call the Inbox's IMAPIContainer::GetContentsTable method to retrieve the contents table.

  4. Call the contents table's IMAPITable::SetColumns method to limit the column set to PR_ENTRYID (PidTagEntryId) and any other columns you require.

  5. Call IMAPITable::QueryRows to retrieve a group of rows.

  6. Until there are no longer any rows in the contents table:

    1. Call IMsgStore::OpenEntry to open the message represented by the entry identifier from each row.

    2. Assign the lppUnk parameter to a local IMessage interface pointer.

    3. Work with the properties of the message.

    4. Release the pointer pointed to by the lppUnk parameter.

    5. Call IMAPITable::QueryRows to retrieve the next group of rows.

  7. Release the contents table.


Copying or Moving a Message or a Folder

 Copy code hover
[image]

Copying or Moving a Message or a Folder
Send feedback

Published: July 16, 2012

A client can use one of four methods to copy or move a message or a folder:

  • IMAPIFolder::CopyFolder

  • IMAPIFolder::CopyMessages

  • IMAPIProp::CopyTo

  • IMAPIProp::CopyProps

By setting the appropriate flags and parameters, CopyTo and CopyProps can be made to work just like CopyFolder or CopyMessages. Consider the following issues when deciding which method to call:

  • Are you copying or moving a folder or a message?

  • How much do you know about the folder or message to be moved or copied?

  • How many of the folder or message's properties will be moved or copied?

You can use the IMAPIProp methods to copy or move either a folder or a message. IMAPIFolder::CopyMessages works with messages only; IMAPIFolder::CopyFolder works with folders only.

Whereas using the IMAPIFolder methods does not require any knowledge of the properties supported by the folder or message to be copied or moved, you must have some knowledge to use the IMAPIProp methods. With IMAPIProp::CopyProps, you must be able to explicitly specify which of the folder or message properties that you want to copy or move. With IMAPIProp::CopyTo, unless you want to copy or move all of the properties, you must explicitly specify which ones should be excluded. For more information about these methods, see Copying MAPI Properties.

The number of properties to be copied or moved can affect your decision as to which method to use. If you are copying or moving multiple messages, call IMAPIFolder::CopyMessages. An alternate choice is to call IMAPIProp::CopyProps to copy only the folder's PR_CONTAINER_CONTENTS (PidTagContainerContents) property. The following procedure shows how to use CopyMessages.

To copy or move one or more messages

  1. Locate valid entry identifiers for the source and destination folders.

  2. Open these folders in read/write mode by calling either IMAPISession::OpenEntry or IMsgStore::OpenEntry and setting the MAPI_MODIFY flag.

  3. Check that the interface pointer returned from OpenEntry is an IMAPIFolder interface pointer. If not, cast it to the LPMAPIFOLDER type.

  4. Create an array of entry identifiers representing the one or more messages to be copied or moved.

  5. Call IMAPIFolder::CopyMessages with the following flags set:

    • MESSAGE_MOVE, if you want to perform a move operation.

    • MESSAGE_DIALOG and pass a window handle in the ulUIParam parameter, if you want the folder to show a progress indicator.

  6. Release the IMAPIFolder pointers for the source and destination folders.

If you want to copy the complete contents of a folder to another folder, call the source folder's IMAPIFolder::CopyFolder or IMAPIProp::CopyTo method.

To copy a few of a folder's properties, call its IMAPIProp::CopyProps method. To copy most of a folder's properties, call IMAPIProp::CopyTo.

For example, if you want to copy a folder's PR_DISPLAY_NAME (PidTagDisplayName) and PR_COMMENT (PidTagComment) properties, you have the following options:

  • Call IMAPIFolder::CopyFolder to copy all of the folder properties and then delete the unwanted ones from the new folder.

  • Call CopyTo and exclude all of the folder's properties except for PR_DISPLAY_NAME and PR_COMMENT.

  • Call CopyProps, passing PR_DISPLAY_NAME and PR_COMMENT in the include array.

In this case, CopyProps is the best choice because it is meant to be used to copy a small set of properties and is the easiest call to implement.

To copy or move only folder properties, without including messages, call the folder's IMAPIProp::CopyTo method and exclude the following properties:

  • PR_CONTAINER_CONTENTS (PidTagContainerContents)

  • PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents)

The copy methods can return S_OK, indicating total success, MAPI_W_PARTIAL_COMPLETION, indicating partial success, or an error. If MAPI_W_PARTIAL_COMPLETION is returned, use the HR_FAILED macro to access a more specific error. For more information, see Using Macros for Error Handling.

If you copy messages from one message store to another and Unicode is not supported by both, be aware that information can be lost due to code page conversion. Usually you cannot know if the message stores support one or both formats, making it impossible to determine whether to copy text properties as ASCII strings or as Unicode strings. If you support Unicode, try to perform a Unicode copy; if it fails with the error value MAPI_E_BAD_CHARWIDTH, resort to ASCII.


Opening a Message

 Copy code hover
[image]

Opening a Message
Send feedback

Published: July 16, 2012

To open a message

  1. Retrieve the message's entry identifier from one of the following sources:

    • The row that represents the message in the contents table of its parent folder. For more information about working with a folder contents table, see Contents Tables.

    • The lpEntryID member of the NEWMAIL_NOTIFICATION structure that is sent with a new mail notification. For more information about receiving and handling notifications, see Handling Notifications.

    • A call to the message's IMAPIProp::GetProps method requesting the PR_ENTRYID (PidTagEntryId) property.

  2. Call one of the following OpenEntry methods to open the message, setting lpEntryID to the message's entry identifier:

    • IMAPIContainer::OpenEntry

    • IMsgStore::OpenEntry

    • IMAPISession::OpenEntry

    The fastest method is usable only for incoming messages and involves calling the receive folder's IMAPIFolder::OpenEntry method. The next fastest method, calling the message store's IMsgStore::OpenEntry method, is usable for all messages as is the slowest method, calling IMAPISession::OpenEntry.

Note Note

Folders and their contents tables can be closed at any time without adversely affecting any of the messages that were opened from within them.

To open a message that has been saved on disk

  1. Call StgOpenStorage to retrieve an IStorage interface pointer, passing the name of the message file for the pwcsName parameter.

    C++ Copy code Copy code
    LPSTORAGE pStorage = NULL;
HRESULT hr = StgOpenStorage (L"MESSAGE.MSG", NULL,
                             STGM_TRANSACTED |
                             STGM_READWRITE |
                             STGM_SHARE_EXCLUSIVE,
                             NULL, 0, &pStorage);

  2. Call OpenIMsgOnIStg to retrieve an IMessage interface pointer to access the message.

    C++ Copy code Copy code
    LPMESSAGE pMessage = NULL;
LPMALLOC pMalloc = MAPIGetDefaultMalloc();
hr = OpenIMsgOnIStg (NULL, MAPIAllocateBuffer, MAPIAllocateMore,
                     MAPIFreeBuffer, pMalloc, NULL, pStorage,
                     NULL, 0, 0, &pMessage);


Finding the Icon for a Message

 Copy code hover
[image]

Finding the Icon for a Message
Send feedback

Published: July 16, 2012

To find the icon associated with a message

  1. Call the message's IMAPIProp::GetProps method to retrieve its PR_MESSAGE_CLASS (PidTagMessageClass) property.

  2. Call MAPIOpenFormMgr to retrieve an IMAPIFormMgr interface pointer. Pass your IMAPISession pointer in the pSession parameter.

  3. Call IMAPIFormMgr::ResolveMessageClass to retrieve an IMAPIFormInfo interface pointer.

  4. Use the IMAPIFormInfo pointer to call IMAPIProp::GetProps and retrieve the PR_ICON (PidTagIcon) and/or PR_MINI_ICON (PidTagMiniIcon) properties.


Opening a View Descriptor

 Copy code hover
[image]

Opening a View Descriptor
Send feedback

Published: July 16, 2012

Many folders can be opened with a normal view, a default view, or any number of personalized views. A view describes how to display the contents of a folder. The normal view is used when there is no alternative view and when you are opening the folder for the first time. When an alternative view does exist, you must use it to open the folder.

A view is described in a message known as a view descriptor. View descriptors are typically created as associated messages and can appear in either the common or personal view folders or in any IPM folder.

To open a view descriptor

  1. Call IMAPIContainer::GetContentsTable to retrieve the associated contents table for the folder.

  2. Create a restriction that locates only messages with the message class reserved for view descriptors and call IMAPITable::Restrict to limit the table and IMAPITable::QueryRows to retrieve the appropriate rows.

    - Or -

    Call the folder's IMAPIProp::GetProps method to retrieve its PR_DEFAULT_VIEW_ENTRYID (PidTagDefaultViewEntryId) property. PR_DEFAULT_VIEW_ENTRYID contains the entry identifier for the message containing the default view descriptor for a folder. This call will succeed if the folder supports the use of the MAPI_ASSOCIATED flag on calls to IMAPIFolder::CreateMessage and IMAPIContainer::GetContentsTable.

  3. Call IMsgStore::OpenEntry with the entry identifier of the view descriptor to open it.


Deleting a Message

 Copy code hover
[image]

Deleting a Message
Send feedback

Published: July 16, 2012

A client can delete a message when it is open and the user is reading it, or when it is closed and the user is viewing the contents table. To protect a user from inadvertently removing a message, MAPI defines message deletion as a two step process:

  1. Mark a message for deletion by moving it to the folder that has been designated as the Deleted Items folder — the folder whose entry identifier is stored in the PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId) property.

  2. Remove the message by calling the IMAPIFolder::DeleteMessages method.

When a user chooses to delete a message in a folder other than the Deleted Items folder, mark it for deletion. Only when a user selects messages from within the Deleted Items folder should the messages be physically removed from the workstation. You can prompt the user to verify that the user really intended to perform the deletion.

To delete a message

  1. Confirm with the user that the impending deletion is intentional.

  2. Determine the parent of the folder to be deleted. If it is the Deleted Items folder or a subfolder within the Deleted Items folder, call IMAPIFolder::DeleteMessages to remove the message.

  3. If the folder is not contained within the Deleted Items folder, call IMAPIFolder::CopyMessages with the MESSAGE_MOVE flag set to relocate the message to the Deleted Items folder.


Saving a Message in the Inbox

 Copy code hover
[image]

Saving a Message in the Inbox
Send feedback

Published: July 16, 2012

To store a message in the Inbox without any recipients

  1. Call IMsgStore::GetReceiveFolder to retrieve the entry identifier of the Inbox.

  2. Call IMsgStore::OpenEntry to open the Inbox and retrieve a pointer to it.

  3. Call the Inbox's IMAPIFolder::CreateMessage method to create the message.

  4. Call the message's IMAPIProp::SetProps method to add the PR_BODY (PidTagBody), PR_HTML (PidTagHtml), or PR_RTF_COMPRESSED (PidTagRtfCompressed) and PR_SUBJECT (PidTagSubject) properties.

  5. Create each attachment, set its properties, and save it. For detailed information about adding attachments to messages, see Creating a Message Attachment.

  6. Call IMessage::SaveChanges to save the message. At this point it will appear in the contents table of the Inbox.

If you want to save a message intermittantly before having it appear in the contents table of the Inbox, create it instead in a hidden folder such as the root folder of the IPM subtree and then move it to the Inbox.


Finding Sent or Saved Messages

 Copy code hover
[image]

Finding Sent or Saved Messages
Send feedback

Published: July 16, 2012

To locate all the outgoing messages that you have saved or sent

  1. Call IMsgStore::CompareEntryIDs to compare the folder that contains your sent messages with the folder that contains your incoming messages.

  2. Set the lpEntryID1 parameter to point to PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId) and the lpEntryID2 parameter to point to PR_PARENT_ENTRYID (PidTagParentEntryId).

Be aware that if you either delete messages after they are sent or have moved any of the sent messages to another folder, this strategy will not work.

If in examining an incoming message you notice that the properties that are typically set by a transport provider are missing, you can assume that the message was never handled by a transport provider. These properties include:

  • PR_RECEIVED_BY properties

  • PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime)

  • PR_TRANSPORT_MESSAGE_HEADERS (PidTagTransportMessageHeaders)

  • PR_MESSAGE_TO_ME (PidTagMessageToMe)

  • PR_MESSAGE_CC_ME (PidTagMessageCcMe)

  • PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe)


Tracking Conversations

 Copy code hover
[image]

Tracking Conversations
Send feedback

Published: July 16, 2012

Conversation tracking is collecting responses to a message. Clients should set two properties that aid in tracking conversations:

  • PR_CONVERSATION_TOPIC (PidTagConversationTopic)

    PR_CONVERSATION_TOPIC is the normalized subject of the message, the subject without the prefix strings. Set this property to the value of the message's PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) property.

  • PR_CONVERSATION_INDEX (PidTagConversationIndex)

    PR_CONVERSATION_INDEX indicates the position of the message within a particular conversation. It is a client's reponsibility to set PR_CONVERSATION_INDEX for each outgoing message, whether it is a new message, a forwarded message, or a reply. Clients can set this property manually or call ScCreateConversationIndex, a utility function provided by MAPI.

ScCreateConversationIndex generates the value of a conversation index for any outgoing message. ScCreateConversationIndex implements the index as a header block that is 22 bytes in length, followed by zero or more child blocks each 5 bytes in length.

The header block is composed of 22 bytes, divided into three parts:

  • One reserved byte. Its value is 1.

  • Five bytes for the current system time converted to the FILETIME structure format.

  • Sixteen bytes holding a GUID, or globally unique identifier.

Each child block is composed of 5 bytes, divided as follows:

  • One bit containing a code representing the difference between the current time and the time stored in the header block. This bit will be 0 if the difference is less than .02 second and greater than two years and 1 if the difference is less than one second and greater than 56 years.

  • Thirty one bits containing the difference between the current time and the time in the header block expressed in FILETIME units.This part of the child block is produced using one of two strategies, depending on the value of the first bit. If this bit is zero, ScCreateConversationIndex discards the high 15 bits and the low 18 bits. If this bit is one, the function discards the high 10 bits and the low 23 bits.

  • Four bits containing a random number generated by calling the Win32 function GetTickCount.

  • Four bits containing a sequence count that is taken from part of the random number.

If you choose to set the conversation indexes of messages manually, consider the following suggestions:

  1. Keep differences in the respondents' time zones transparent; use UTC times rather than local time.

  2. Indent each conversation group by the same amount.

  3. Sort responses to the same message date.

  4. Separate threads started at different times that happen to share the same topic.

  5. To implement a categorized sort so that messages are grouped by topic, sort by PR_CONVERSATION_TOPIC first and then by PR_CONVERSATION_INDEX. To present the results of the sort, set the PR_DEPTH (PidTagDepth) property to 0 for messages with a conversation index that is 22 bytes in length. Then, for every 5-byte increment in the length, increment the value of the PR_DEPTH property by one.

The PR_ORIGINAL group of properties can also be used for conversation tracking. Set these properties to link reply or forwarded messages to the original message. All of the PR_ORIGINAL properties are optional. If you do not explicitly set, for example, PR_ORIGINAL_AUTHOR_ENTRYID (PidTagOriginalAuthorEntryId), the message store provider can use the default value, or the value of the PR_SENDER_ENTRYID (PidTagSenderEntryId) property. Likewise, if you do not set PR_ORIGINAL_AUTHOR_NAME or PR_ORIGINAL_SUBMIT_TIME (PidTagOriginalSubmitTime), these properties can default to the values of the PR_SENDER_NAME (PidTagSenderName) and PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) properties, respectively.


Handling the Address Book

 Copy code hover
[image]

Handling the Address Book
Send feedback

Published: July 16, 2012

Handling the MAPI address book can include extracting entries to be used as message recipients, modifying recipient properties, adding messaging users or distribution lists, creating one-offs, and displaying one or more of the common address dialog boxes to allow users to browse address information and make changes.

In This Section

Opening the Address Book

Describes how to use MAPI to open an address book.

Displaying the Common Address Dialog Box

Describes how to display different address book containers.

Opening an Address Book Container

Describes how to open different address book containers.

Setting Address Book Options

Describes how to set the properties that describe options for using the address book.

Creating a Recipient

Describes how to create recipients when addressing messages and adding entries to modifiable address book containers.

Creating a Distribution List

Describes how to create a distribution list into a modifiable container.

Copying a Recipient

Describes how to copy recipients from one container into another or the same container.

Deleting a Recipient

Describes how to remove one or more address book entries from a modifiable container.

Preparing a Recipient

Describes how to prepares recipients by converting their short-term entry identifiers to long-term entry identifiers and possibly adding, changing, or reordering properties.

Accessing the Members of a Distribution List

Describes how to access the members of a distribution list.

Retrieving Recipient Properties

Describes how to access one or more properties of a recipient address book entry.

Searching the Address Book

Describes the two levels of MAPI search functionality.

Using an Advanced Search Dialog Box

Describes how to run an advanced search functionality in an address book container.

Resolving a Recipient Name

Describes how to resolve a name in an address book.

Expanding Distribution Lists

Describes how to prompt MAPI to expand a distribution list.


Opening the Address Book

 Copy code hover
[image]

Opening the Address Book
Send feedback

Published: July 16, 2012

Call IMAPISession::OpenAddressBook to open the integrated address book and retrieve a pointer to the MAPI IAddrBook : IMAPIProp interface. The methods of the IAddrBook interface can be used to access entries in all of the containers of each of the address book providers in the profile.

OpenAddressBook might return a warning, MAPI_W_ERRORS_RETURNED, to indicate that there were problems with one or more of the address book providers. Interactive clients should call IMAPISession::GetLastError to retrieve additional error information and display the returned information the first time they call OpenAddressBook and it returns a warning.

Noninteractive clients should ignore the warning and proceed as if the method succeeded. The returned IAddrBook interface is valid regardless of whether all, some, or none of the address book providers in the profile are running. Therefore, both interactive and noninteractive clients must always remember to release the IAddrBook pointer when the session ends.


Displaying the Common Address Dialog Box

 Copy code hover
[image]

Displaying the Common Address Dialog Box
Send feedback

Published: July 16, 2012

The MAPI common address dialog box can be used for a variety of addressing tasks such as constructing a recipient list. To display this dialog box, call IAddrBook::Address. Depending on which of the many parameters you set and how you set them, you can limit your display to entries of a particular type from a particular container.

To limit the address dialog box to displaying personal address book (PAB) entries only

  1. Call IAddrBook::GetPAB to retrieve the entry identifier of the PAB.

  2. Create a property restriction that uses RELOP_EQ for the relop member of the SPropertyRestriction structure and either PR_ENTRYID (PidTagEntryId) or PR_AB_PROVIDER_ID (PidTagAbProviderId) as the ulPropTag member. If you use PR_ENTRYID, pass the entry identifier retrieved from GetPAB. If you use PR_AB_PROVIDER_ID, pass the value included in the MSPAB.H header file. PR_AB_PROVIDER_ID is the unique identifier for the PAB designed by MAPI.

  3. Call IAddrBook::Address with the lpHierRestriction parameter pointing to the property restriction.


Opening an Address Book Container

 Copy code hover
[image]

Opening an Address Book Container
Send feedback

Published: July 16, 2012

After opening the MAPI integrated address book, open one or more address book containers to access the recipients within them.

To open the top-level container of the address book, call IAddrBook::OpenEntry with a NULL entry identifier.

Address book containers can be implemented with read-only or read/write access. Read-only containers are used only for browsing. Read/write containers can be modified, allowing clients to create new entries and delete and modify existing entries. All personal address book (PAB) containers are implemented as read/write containers.

To open any lower level container, call OpenEntry and specify the entry identifier of the container to be opened.

To open the container designated as the PAB

  1. Call IAddrBook::GetPAB to retrieve the PAB's entry identifier.

  2. Pass this entry identifier to IAddrBook::OpenEntry.

To open a container that is not the PAB

  1. Call IAddrBook::OpenEntry with a NULL entry identifier to open the address book's root container.

  2. Call the root container's IMAPIContainer::GetHierarchyTable method to retrieve its hierarchy table — a list of all of the top-level containers in the address book.

  3. If the container to be opened is of a specific type:

    • Create an SPropertyRestriction structure with PR_DISPLAY_TYPE (PidTagDisplayType) for the property tag, the container's type for the property value, and RELOP_EQ for the relation. PR_DISPLAY_TYPE can be set to many values, among them:

      • DT_GLOBAL to limit the hierarchy table to containers that belong in the global address list.

      • DT_LOCAL to limit the table to containers belonging to a local address book.

      • DT_MODIFIABLE to limit the table to containers that can be modified.

    • Create an SPropTagArray structure that includes PR_ENTRYID, PR_DISPLAY_TYPE, and any other columns of interest.

    • Call HrQueryAllRows, passing your property restriction and property tag array. HrQueryAllRows will return zero or more rows, one row for every container that belongs to the specified type. Be prepared to handle the return of any number of rows.

    • Call IAddrBook::OpenEntry with the entry identifier from the PR_ENTRYID column of the row that represents the container of interest.

  4. If the container to be opened belongs to a specific address book provider:

    • Create an SPropertyRestriction structure with PR_AB_PROVIDERS (PidTagAbProviders) for the property tag, a provider-specific value for the property value, and RELOP_EQ for the relation. Typically the provider-specific value is a globally unique identifier or GUID. You will find this value published in one of the address book provider's header files.

    • Create an SPropTagArray structure that includes PR_ENTRYID (PidTagEntryId), PR_AB_PROVIDERS, and any other columns of interest.

    • Call HrQueryAllRows, passing your property restriction and property tag array. HrQueryAllRows will return zero rows if the specified address book provider is not in the profile. It can return one or more rows for the provider's top-level containers, depending on how the provider is organized.

    • Call IAddrBook::OpenEntry with the entry identifier from the PR_ENTRYID column of the row that represents the container of interest. If the container that you are interested in is not a top-level container, find the top-level container and traverse the hierarchy.


Setting Address Book Options

 Copy code hover
[image]

Setting Address Book Options
See also Send feedback

Published: July 16, 2012

You can set three properties that describe options for using the address book:

  • PR_AB_SEARCH_PATH (PidTagAbSearchPath)

    The PR_AB_SEARCH_PATH property is used by IAddrBook::ResolveName to determine the containers to be involved in name resolution and the order that they should be involved. For each container in PR_AB_SEARCH_PATH, IAddrBook::ResolveName calls its IABContainer::ResolveNames method. Containers at the beginning of PR_AB_SEARCH_PATH are searched before containers at the end of PR_AB_SEARCH_PATH.

    The search order in PR_AB_SEARCH_PATH is specified using an SRowSet structure, the same structure that is used to represent rows in a table. You can view the current search path by calling the IAddrBook::GetSearchPath method and change it by calling the IAddrBook::SetSearchPath method.

  • PR_AB_DEFAULT_DIR (PidTagAbDefaultDir)

    The PR_AB_DEFAULT_DIR property is the entry identifier of the address book container to be displayed initially when the address book is displayed. The default directory setting remains in effect until you change it by calling the IAddrBook::SetDefaultDir method. You can view the default directory by calling the IAddrBook::GetDefaultDir method.

  • PR_AB_DEFAULT_PAB (PidTagAbDefaultPab)

These three properties are special because you cannot work with them using the standard IMAPIProp methods. Instead, you must use IAddrBook methods. Because none of these properties can be changed with IMAPIProp::SetProps, there is no need to call IMAPIProp::SaveChanges to make changes permanent. Modifications made through the IAddrBook methods take effect immediately.

See also

Reference

IAddrBook : IMAPIProp


Creating a Recipient

 Copy code hover
[image]

Creating a Recipient
Send feedback

Published: July 16, 2012

Clients create recipients when they are addressing messages and when they are adding entries to modifiable address book containers. MAPI provides three methods for creating recipients:

  • IAddrBook::CreateOneOff

  • IAddrBook::NewEntry

  • IABContainer::CreateEntry

Call IAddrBook::CreateOneOff when you are creating recipients to be used to address messages. CreateOneOff creates a specially formatted one-off entry identifier to be associated with an address of a particular address type. For more information about one-offs and one-off entry identifiers, see One-Off Addresses and One-Off Entry Identifiers.

Call IAddrBook::NewEntry when you are creating recipients to be used either to address messages or to add to a container. NewEntry has three pairs of parameters that contain entry identifiers. These parameters are described as follows:

Parameter pair | Description
cbEidContainer and lpEidContainer | Entry identifier for the container into which the new entry should be placed.
cbEidNewEntryTpl and lpEidNewEntryTpl | Entry identifier for the template to be used to create the new entry.
lpcbEidNewEntry and lppEidNewEntry | Entry identifier for the new entry.

To create a recipient for an outgoing message, set cbEidContainer to zero and lpEidContainer to NULL. NewEntry creates a recipient with an entry identifier that conforms to the one-off format, the same type of recipient that is produced by a call to IAddrBook::CreateOneOff.

To create a recipient to be inserted into a particular container, set lpEidContainer to the container's entry identifier and cbEidContainer to the number of bytes in the container's entry identifier.

To use a template to create a recipient, set lpEidNewEntryTpl to the entry identifier of the template to be used and cbEidNewEntryTpl to the count of bytes in this entry identifier. Most modifiable address book containers support one or more templates for creating entries of a particular type. One-off templates are typically, but not always, dialog boxes. Entering information into the template produces a recipient with an address that is correctly formatted for the type.

Obtain the template entry identifier from either:

  • The PR_ENTRYID (PidTagEntryId) column in the container's one-off table, accessed by calling the container's IMAPIProp::OpenProperty method and specifying PR_CREATE_TEMPLATES (PidTagCreateTemplates) as the property tag and IID_IMAPITable as the interface identifier.

  • An address book provider's PR_DEF_CREATE_MAILUSER (PidTagDefCreateMailuser) and PR_DEF_CREATE_DL (PidTagDefCreateDl) properties which hold the entry identifiers for the provider's messaging user object and distribution list templates.

Note Note

Do not confuse a new entry template's entry identifier with a different type of entry identifier called a template identifier. A template identifier is used only by providers to maintain entries copied from other providers; it is never used by clients and it is not used to create new entries.

To enable the user to determine the type of entry to be created, pass zero for cbEidNewEntryTpl and NULL for lpEidNewEntryTpl. When this occurs, NewEntry displays a common dialog box built from MAPI's one-off table — a hierarchical list of all of the templates supported by each address book provider in the profile.

When an address type has been determined, either through the setting of the lpEidNewEntryTpl parameter or a selection by the user from the one-off table display, NewEntry displays the corresponding template using its display table. All new entry templates support the PR_DETAILS_TABLE (PidTagDetailsTable) property.

To have NewEntry return the entry identifier of the created entry, pass a valid address for the lpcbEidNewEntry and lppEidNewEntry parameters. MAPI places the new entry identifier at the address pointed to by lppEidNewEntry and the byte count of the new entry identifier at the address pointed to by lpcbEidNewEntry.

Call IABContainer::CreateEntry to create a recipient and save it into a particular address book container. You can use this method only with modifiable containers — containers that have the AB_MODIFIABLE flag set in their PR_CONTAINER_FLAGS (PidTagContainerFlags) property. Address book providers with nonmodifiable containers do not support this method. Specify the entry identifier of the template for creating an entry of the desired type in the lpEntryID parameter.

In the ulCreateFlags parameter, specify the type of duplicate entry checking required and whether or not new entries should replace existing ones. If CreateEntry fails to create a new object because of the duplicate entry checking imposed by the provider, do not expect to see an error or warning returned. Under these conditions, providers return a success code.

If you are working directly with a container and you know exactly the types of addresses that the container can create, you can call IABContainer::CreateEntry and pass the entry identifier for the appropriate template. The address book provider sets some initial default properties; you can call SetProps to set others. The user is never involved.


Creating a Distribution List

 Copy code hover
[image]

Creating a Distribution List
Send feedback

Published: July 16, 2012

Clients can create a distribution list directly into a modifiable container such as the personal address book (PAB).

To create a distribution list in the PAB

  1. Create a sized property tag array with one property tag, PR_DEF_CREATE_DL (PidTagDefCreateDl), as follows:

    C++ Copy code Copy code
    SizedPropTagArray(1, tagaDefaultDL) =
{
    1,
    {
        PR_DEF_CREATE_DL
    }
};

  2. Call IAddrBook::GetPAB to retrieve the entry identifier of the PAB. If there is an error or GetPAB returns zero or NULL, do not continue.

    C++ Copy code Copy code
    LPENTRYID peidPAB = NULL;
ULONG cbeidPAB = 0;
lpIAddrBook->GetPAB(&cbeidPAB, &peidPAB);

  3. Call IAddrBook::OpenEntry to open the PAB. The ulObjType output parameter should be set to MAPI_ABCONT.

    C++ Copy code Copy code
    ULONG ulObjType = 0;
LPABCONT lpPABCont = NULL;
lpIAddrBook->OpenEntry(cbeidPAB, peidPAB,
                NULL,
                MAPI_MODIFY,
                &ulObjType,
                &lpPABCont);

  4. Call the PAB's IMAPIProp::GetProps method to retrieve the PR_DEF_CREATE_DL property, the template that it uses to create a distribution list.

    C++ Copy code Copy code
    lpPABCont->GetProps(0,
            tagaDefaultDL,
            &lpspvDefDLTpl);

  5. If GetProps fails:

    1. Call the PAB's IMAPIProp::OpenProperty method to open the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property with the IMAPITable interface.

    2. Create a property restriction to search for the row with the PR_ADDRTYPE (PidTagAddressType) column equal to "MAPIPDL."

    3. Call IMAPITable::FindRow to locate this row.

  6. Save the entry identifier returned by either GetProps or FindRow.

    C++ Copy code Copy code
    peidDefDLTpl = lpspvDefDLTpl->Value.bin.pb;
cbeidDefDLTpl = lpspvDefDLTpl->Value.bin.cb;

  7. Call the PAB's IABContainer::CreateEntry method to create a new entry using the template represented by the saved entry identifier. Do not assume that the object returned will be a distribution list rather than a messaging user when this call is remoted. Notice that the CREATE_CHECK_DUP flag is passed in the ulFlags parameter to prevent the entry from being added twice.

    C++ Copy code Copy code
    lpPABCont->CreateEntry(cbeidDefDLTpl,
                peidDefDLTPL,
                CREATE_CHECK_DUP_STRICT,
                &lpNewPABEntry);

  8. Call the new entry's IUnknown::QueryInterface method, passing IID_IDistList as the interface identifier, to determine if the entry is a distribution list and supports the IDistList : IMAPIContainer interface. Because CreateEntry returns an IMAPIProp pointer rather than the more specific IMailUser or IDistList pointer, check that a distribution list object was created. If QueryInterface succeeds, you can be sure that you have created a distribution list rather than a messaging user.

  9. Call the distribution list's IMAPIProp::SetProps method to set its display name and other properties.

  10. Call the distribution list's IABContainer::CreateEntry method to add one or more messaging users.

  11. Call the distribution list's IMAPIProp::SaveChanges method when you're ready to save it. To retrieve the entry identifier of the saved distribution list, set the KEEP_OPEN_READWRITE flag and then call IMAPIProp::GetProps requesting the PR_ENTRYID (PidTagEntryId) property.

  12. Release the new distribution list and the PAB by calling their IUnknown::Release methods.

  13. Call MAPIFreeBuffer to release the memory for the entry identifier of the PAB and the sized property tag array.


Copying a Recipient

 Copy code hover
[image]

Copying a Recipient
Send feedback

Published: July 16, 2012

To copy one or more recipients from one container into another or the same container, first check that the target container is modifiable. Containers that are modifiable set the AB_MODIFIABLE flag in their PR_CONTAINER_FLAGS (PidTagContainerFlags) property.

To copy one or more entries into a modifiable container, call the destination container's IABContainer::CopyEntries method. Because copying address book entries can be time-consuming, CopyEntries accepts four input parameters: an array of entry identifiers for the entries to be copied, a window handle, a progress indicator, and a bitmask of flags.

The window handle and progress indicator are used by the address book provider to show the status of the operation to the user. If you want to display progress, pass a window handle for the parent window of the progress indicator in the ulUIParam parameter and do not set the AB_NO_DIALOG flag in the ulFlags parameter. If you have your own implementation of a progress indicator, pass a pointer to the implementation in the lpProgress parameter. If not, pass NULL. The address book provider will use the MAPI progress indicator implementation.

The bitmask of flags indicates whether or not you want to display a progress indicator and how duplicate entry checking should be handled. Set the AB_NO_DIALOG flag to suppress a progress indicator. Set the CREATE_CHECK_DUP_LOOSE flag to instruct the address book provider to loosely check for duplicates or the CREATE_CHECK_DUP_STRICT flag for stricter duplicate checking. Set the CREATE_REPLACE flag to have copied entries replace existing entries when the provider determines there are duplicates.

When copying into a personal address book (PAB) container, the provider copies some or all of the properties for each entry. Because MAPI does not establish requirements for providers implementing container copy operations, you cannot make assumptions about the number and type of properties that are copied with an address book entry.


Deleting a Recipient

 Copy code hover
[image]

Deleting a Recipient
Send feedback

Published: July 16, 2012

To remove one or more address book entries from a modifiable container

  • Call the IABContainer::DeleteEntries method, passing an array of entry identifiers that represent the address book entries to be deleted. DeleteEntries can return a warning, MAPI_W_PARTIAL_COMPLETION, to indicate that it couldn't delete one or more of the entries. Test for this return value with the HR_FAILED macro and call the container's IMAPIProp::GetLastError method if more information about the problem is needed.

When you hold a pointer to a deleted entry's ADRENTRY structure in your cache, you will still be able to retrieve properties using its entry identifier. This is because the entry is only marked for deletion. MAPI maintains a level of access to these marked entries by design.


Preparing a Recipient

 Copy code hover
[image]

Preparing a Recipient
Send feedback

Published: July 16, 2012

A client application prepares recipients by converting their short-term entry identifiers to long-term entry identifiers and possibly adding, changing, or reordering properties. You can prepare recipients that are part of a recipient list for a message or recipients that are unrelated to a message. Typically, clients call IAddrBook::PrepareRecips directly to translate short-term entry identifiers into long-term entry identifiers for recipients that are included in the common address dialog box. For recipients that are associated with an outgoing message, recipient preparation is handled by the name resolution process.

To prepare a list of recipients, call IAddrBook::PrepareRecips. PrepareRecips accepts an ADRLIST structure and a list of property tags. The ADRLIST structure contains the recipients to be prepared while the property tag list represents properties that each recipient should support. PrepareRecips attempts to place the properties that are included in the property tag list at the beginning of the ADRLIST structure. If any of the properties in the list are missing from the ADRLIST structure, MAPI calls the address book provider to supply them. If you only need to check for long-term entry identifiers, pass NULL for the lpSPropTagArray parameter.

For example, suppose you are working with five recipients. All five recipients appear in the ADRLIST structure with the following properties in the following order:

  1. PR_ENTRYID (PidTagEntryId)

  2. PR_DISPLAY_NAME (PidTagDisplayName)

  3. PR_SEARCH_KEY (PidTagSearchKey)

  4. PR_EMAIL_ADDRESS (PidTagEmailAddress)

  5. PR_ADDRTYPE (PidTagAddressType)

Three other properties are included in the ADRLIST structure for the first two recipients.

  1. PR_ACCOUNT (PidTagAccount)

  2. PR_GIVEN_NAME (PidTagGivenName)

  3. PR_SURNAME (PidTagSurname)

Because all of the recipients need to have as their first three properties PR_ADDRTYPE, PR_ENTRYID, and PR_HOME_TELEPHONE_NUMBER (PidTagHomeTelephoneNumber), create a property tag array with these properties and pass it and the ADRLIST structure to PrepareRecips. PrepareRecips calls each recipient's IMAPIProp::GetProps method to retrieve PR_HOME_TELEPHONE_NUMBER because it is not currently part of the ADRLIST structure. When PrepareRecips returns, the recipient list represents a merged list of recipients with the properties included in the ADRLIST structure appearing first for each recipient.

The recipient list for recipients 1 and 2 includes properties in the following order:

  1. PR_ADDRTYPE

  2. PR_ENTRYID

  3. PR_HOME_TELEPHONE_NUMBER

  4. PR_DISPLAY_NAME

  5. PR_SEARCH_KEY

  6. PR_EMAIL_ADDRESS

  7. PR_ADDRTYPE

  8. PR_ACCOUNT

  9. PR_GIVEN_NAME

  10. PR_SURNAME

The recipient list for recipients 3, 4, and 5 includes properties in the following order:

  1. PR_ADDRTYPE

  2. PR_ENTRYID

  3. PR_HOME_TELEPHONE_NUMBER

  4. PR_DISPLAY_NAME

  5. PR_SEARCH_KEY

  6. PR_EMAIL_ADDRESS

  7. PR_ADDRTYPE

As an alternative to calling IAddrBook::PrepareRecips to work with properties, call each recipient's IMAPIProp::GetProps method and, if necessary, its IMAPIProp::SetProps method. When only one recipient is involved, either technique is satisfactory. However, when multiple recipients are involved, calling PrepareRecips rather than the IMAPIProp methods saves time and, if you are operating remotely, many remote procedure calls. PrepareRecips processes all recipients in a single call whereas GetProps and SetProps make one call for each recipient.


Accessing the Members of a Distribution List

 Copy code hover
[image]

Accessing the Members of a Distribution List
Send feedback

Published: July 16, 2012

To get the members of a distribution list

  1. Create a sized property tag array with the properties of the members you would like to retrieve, such as PR_ENTRYID (PidTagEntryId), PR_DISPLAY_NAME (PidTagDisplayName), and PR_DISPLAY_TYPE (PidTagDisplayType).

  2. Call IAddrBook::OpenEntry to open the distribution list.

  3. Call the distribution list's IABContainer::GetContentsTable method to access its contents table.

  4. Call HrQueryAllRows to retrieve all of the table's rows representing the members of the distribution list.


Retrieving Recipient Properties

 Copy code hover
[image]

Retrieving Recipient Properties
Send feedback

Published: July 16, 2012

To access one or more properties of an address book entry

  1. For each address book entry of interest, call IAddrBook::OpenEntry, passing the entry identifier of the target messaging user or distribution list.

  2. Then do one of the following:

    • Call the messaging user or distribution list's IMAPIProp::GetProps method for each address book entry of interest, with a list of the one or more properties to retrieve.

    • Call IAddrBook::PrepareRecips, passing an ADRLIST structure that holds all of the properties for all of the desired address book entries. Because one call to PrepareRecips can return information for multiple address book entries, it is the preferable strategy when you are interested in more than one recipient.


Searching the Address Book

 Copy code hover
[image]

Searching the Address Book
Send feedback

Published: July 16, 2012

MAPI enables address book providers to implement two levels of search functionality:

  • A basic level that matches a specified name with the PR_DISPLAY_NAME (PidTagDisplayName) property of address book entries. This level allows users, for example, to view distribution lists with names beginning with Northwest or locate individual messaging users whose last name is Brown.

  • An advanced level that matches on properties other than PR_DISPLAY_NAME. This level allows users, for example, to further narrow their searches and find messaging users named Brown with a particular address type.

Because address book providers can support searching for each of their containers at the basic level, at both levels, or choose not to support it at all, do not expect searching to be implemented as a standard feature. To determine if a particular container supports searches, attempt to establish search criteria in a call to its IMAPIContainer::SetSearchCriteria method. If SetSearchCriteria returns MAPI_E_NO_SUPPORT, the container does not support searches.

In a container that supports searches, retrieve established criteria by calling IMAPIContainer::GetSearchCriteria. You can also request that the user be prompted for search criteria before a container's contents table is displayed. To choose this option, set the AB_FIND_ON_OPEN flag of the container's PR_CONTAINER_FLAGS (PidTagContainerFlags) property. After the user enters the criteria, it is stored as a restriction and passed to the SetSearchCriteria method. Setting AB_FIND_ON_OPEN is particularly useful if you are using an online service or any address book provider that has a slow link to its data.

To perform a basic search in an address book container

  1. Call the container's IMAPIContainer::GetContentsTable method to open its contents table.

  2. Choose a search technique that meets your needs. The choices include:

    • IMAPITable::FindRow to locate a specific row in the table.

    • IMAPITable::SortTable to order rows in the table.

    • IMAPITable::Restrict to limit the table view.

    • Property restriction using the PR_ANR (PidTagAnr) property for resolving ambiguous names. Call IMAPITable::Restrict to impose this restriction.

    • IABContainer::ResolveNames to resolve ambiguous names.

  3. Call IMAPITable::QueryRows to retrieve any rows that meet your applied search criteria. QueryRows can return zero or more matching rows.

The FindRow, SortTable, and Restrict methods are table methods that are available for any table that can be created, either by a client or a service provider. The PR_ANR property restriction and IABContainer::ResolveNames method are specific to address book providers and are used for resolving ambiguous names. Ambiguous names are entries in a recipient list that do not have a PR_ENTRYID property associated with them.

The PR_ANR restriction invokes an algorithm that separates a character string into words and matches those words with information in the address book using prefix-matching. The information used for the matching depends on the address book provider. All address book providers are required to support the PR_ANR restriction for their address book containers. For more information, see Implementing Name Resolution.

IABContainer::ResolveNames performs PR_ANR restriction processing on multiple names without requiring the container's contents table to be open. Calling ResolveNames once to resolve multiple names can be much faster than invoking a PR_ANR restriction multiple times. However, address book providers are not required to support ResolveNames.


Using an Advanced Search Dialog Box

 Copy code hover
[image]

Using an Advanced Search Dialog Box
Send feedback

Published: July 16, 2012

Some address book containers support an advanced searching capability that allows clients to search on properties other than PR_DISPLAY_NAME (PidTagDisplayName). Address book containers that support advanced searches have a container object property called PR_SEARCH (PidTagSearch). This container object provides access to a display table that describes the search dialog box — a dialog box used to enter and edit the advanced search criteria.

To perform an advanced search on an address book container

  1. Call the container's IMAPIProp::OpenProperty method, specifying PR_SEARCH for the property tag and IID_IMAPIContainer for the interface identifier.

  2. Call the search object 's IMAPIProp::OpenProperty method, specifying PR_DETAILS_TABLE (PidTagDetailsTable) for the property tag and IID_IMAPITable for the interface identifier.

  3. Call the search object's IMAPIProp::SetProps method to establish values for the properties to be used in the advanced search.

  4. Call the search object's IMAPIProp::SaveChanges method to save the advanced search criteria.

This sequence of calls results in a restriction being available when a client calls the search object's GetSearchCriteria method.


Resolving a Recipient Name

 Copy code hover
[image]

Resolving a Recipient Name
Send feedback

Published: July 16, 2012

When a message is addressed, a recipient list is built with properties relating to each recipient. By the time the message is sent, one of those properties must be the recipient's long-term entry identifier. To ensure that each recipient includes the PR_ENTRYID (PidTagEntryId) property, pass the ADRLIST structure describing your recipient list in the contents of the lpAdrList parameter in a call to IAddrBook::ResolveName.

ResolveName begins processing by ignoring the entries in the ADRLIST structure that have already been resolved, as indicated by the presence of an entry identifier in the corresponding ADRENTRY structure's SPropValue array. Next, ResolveName automatically assigns one-off entry identifiers to two types of recipients:

  • Recipients with an address formatted as an Internet address

  • Recipients with an address formatted as follows:

    displayname[address type:e-mail address]

For all remaining entries, ResolveName searches the address book for an exact match on the display name. ResolveName uses the PR_AB_SEARCH_PATH (PidTagAbSearchPath) property to determine the set of containers to search and the search order. MAPI calls the IABContainer::ResolveNames method of every container to attempt to resolve all of the names. Because some containers do not support ResolveNames, if the container returns MAPI_E_NO_SUPPORT, MAPI applies a PR_ANR (PidTagAnr) property restriction against its contents table. All address book containers are required to support name resolution with this restriction. Once all the names are resolved, no further container calls are made. If all the containers have been called, but ambiguous or unresolved names remain, MAPI displays a dialog box if possible to prompt the user to resolve the remaining names.

The PR_ANR restriction matches the value of the PR_ANR property against the display name in the ADRLIST structure. Limiting the view of a container's contents table with the PR_ANR property restriction causes the address book provider to perform a "best guess" type of search, matching against the property that makes sense for the provider. For example, one address book provider might always match names in the recipient list against PR_DISPLAY_NAME (PidTagDisplayName) while another might allow an administrator to select the property.

To set a PR_ANR property restriction on an address book container's contents table

  1. Create an SRestriction structure as shown in the following code:

    C++ Copy code Copy code
    SRestriction SRestrict;
SRestrict.rt = RES_PROPERTY;
SRestrict.res.resProperty.relop = RELOP_EQ;
SRestrict.res.resProperty.ulPropTag = PR_ANR;
SRestrict.res.resProperty.lpProp->ulPropTag = PR_ANR;
SRestrict.res.resProperty.lpProp->Value.LPSZ = lpszName;

  2. Call the contents table's IMAPITable::Restrict method, passing the SRestriction structure as the lpRestriction parameter.


Expanding Distribution Lists

 Copy code hover
[image]

Expanding Distribution Lists
Send feedback

Published: July 16, 2012

To prompt MAPI to expand a distribution list

  • Set its PR_ADDRTYPE (PidTagAddressType) property to MAPIPDL.

    MAPI expands addresses with this type before sending the message to the transport provider.


Handling a Transport Provider

 Copy code hover
[image]

Handling a Transport Provider
Send feedback

Published: July 16, 2012

Clients communicate with transport providers through status objects supplied by transport providers and the MAPI spooler. Clients access status objects by calling IMAPISession::GetStatusTable to retrieve the status table. Status objects implement the IMAPIStatus : IMAPIProp interface, which has methods for configuring providers, flushing incoming and outgoing message queues, setting passwords, and state validation. For more information about status objects, see Status Table and Status Objects.

In This Section

Sending or Receiving a Message on Demand

Describes how to send or receive a message on demand.

Setting Transport Order

Describes how to set transport order.

Reconfiguring a Transport Provider

Describes how to reconfigure a transport provider and what properties are available to set.


Sending or Receiving a Message on Demand

 Copy code hover
[image]

Sending or Receiving a Message on Demand
Send feedback

Published: July 16, 2012

Clients typically rely on the MAPI subsystem — the MAPI spooler and the service providers — to handle the timing of message transmission and reception. However, you can alter this timing by using the status object of either the MAPI spooler or a transport provider.

The IMAPIStatus::FlushQueues method removes all messages from one or more transport provider's incoming or outgoing queues. The following procedures describe two techniques for sending or receiving messages on demand. The first procedure uses the MAPI spooler's status object to flush the queues of every transport provider in the profile; the second procedure flushes the queue of a single transport provider.

To flush all incoming or outgoing queues in a single operation

  1. Call IMAPISession::GetStatusTable to access the status table.

  2. Call the status table's IMAPITable::SetColumns method to limit the column set to PR_ENTRYID (PidTagEntryId) and PR_RESOURCE_TYPE (PidTagResourceType).

  3. Build a property restriction using an SPropertyRestriction structure to match PR_RESOURCE_TYPE with MAPI_SPOOLER.

  4. Call HrQueryAllRows, passing in the SPropertyRestriction structure, to retrieve the row that represents the status of the MAPI spooler.

  5. Pass the PR_ENTRYID column to IMAPISession::OpenEntry to open the MAPI spooler's status object.

  6. Call the MAPI spooler's IMAPIStatus::FlushQueues method, passing the FLUSH_NO_UI flag to suppress the user interface and either the FLUSH_DOWNLOAD or FLUSH_UPLOAD flag to flush the outgoing or incoming queues.

  7. Release the status object and the status table, as well as the SRowSet structure that is allocated for the table.

To flush incoming or outgoing queues individually by transport provider

  1. Call IMAPISession::GetStatusTable to access the status table.

  2. Call the status table's IMAPITable::SetColumns method to limit the column set to PR_ENTRYID and PR_RESOURCE_TYPE.

  3. Build a property restriction using an SPropertyRestriction structure to match PR_RESOURCE_TYPE with MAPI_TRANSPORT_PROVIDER.

  4. Call HrQueryAllRows, passing in the SPropertyRestriction structure, to retrieve the rows that are supplied by transport providers.

  5. For each row returned from HrQueryAllRows:

    1. Pass the PR_ENTRYID column to IMAPISession::OpenEntry to open the transport provider's status object.

    2. Check that the transport status object supports the FlushQueues method by checking that its PR_RESOURCE_METHODS (PidTagResourceMethods) property has the STATUS_FLUSH_QUEUES flag set.

    3. If supported, call IMAPIStatus::FlushQueues. If unsupported, call the MAPI spooler's IMAPIStatus::FlushQueues method, passing the entry identifier of the transport in the lpTargetTransport parameter. See the preceding procedure for instructions on accessing the MAPI spooler's status object. Set the FLUSH_DOWNLOAD flag to flush the outgoing queues or the FLUSH_UPLOAD flag to flush the incoming queues.

    4. Release the status object and the status table, as well as the SRowSet structure that is allocated for the table.

The MAPI spooler honors the FLUSH_NO_UI flag as do most LAN transport providers. However, not all transport providers honor this flag, particularly those that use a modem explicitly and the Remote Access Service (RAS). RAS was not designed to allow clients to suppress the user interface. It is possible for a client to be configured so that it can connect without requiring the interaction of a user, but it is difficult and requires intimate knowledge of the client's message services.


Setting Transport Order

 Copy code hover
[image]

Setting Transport Order
Send feedback

Published: July 16, 2012

The MAPI spooler assigns responsibility for outgoing messages based on the address types and identifiers that transport providers declare they can handle. Transport providers publish a list of supported address types and identifiers — stored in MAPIUID structures — when MAPI calls their IXPLogon::AddressTypes method, directly after logon. A recipient's address type is stored in its PR_ADDRTYPE (PidTagAddressType) property.

Registering for an address type indicates to MAPI that the transport provider can deliver to recipients with their PR_ADDRTYPE property set to the registered address type. Similarly, registering for a MAPIUID indicates that the transport provider can deliver to recipients that are represented by entry identifiers with the registered MAPIUID.

Most transport providers register for one or more address types; few register by MAPIUID. Transport providers that are tightly coupled with an address book provider and understand its entry identifier format can register to handle messages by MAPIUID, thereby improving performance. These tightly coupled transport providers can extract the recipient's e-mail address and other necessary information from the entry identifier without having to open it with an IMAPISupport::OpenEntry call.

MAPI maintains an order for transport providers, used when multiple transport providers have registered for the same address type or MAPIUID. You can override this order by calling IMsgServiceAdmin::MsgServiceTransportOrder and passing an ordered list of the MAPIUIDs of all of the active transport providers pointed to by the lpUIDList parameter.:

To retrieve a list of all of the address types that can be handled by one of the active transport providers, call IMAPISession::EnumAdrTypes. EnumAdrTypes returns an array of strings that describes address types supported by the transport providers that are active in the current session.


Reconfiguring a Transport Provider

 Copy code hover
[image]

Reconfiguring a Transport Provider
Send feedback

Published: July 16, 2012

You can use a transport provider's status object to change some of the properties of the provider. The range of properties that can be changed depends on the properties that are included with the provider's property sheet and how those properties are defined.

To reconfigure an active transport provider

  1. Call IMAPISession::GetStatusTable to access the status table.

  2. Locate the row for the transport provider to be reconfigured by creating a property restriction that matches PR_DISPLAY_NAME (PidTagDisplayName) with the name of the target provider.

  3. Call IMAPITable::FindRow to retrieve the appropriate row.

  4. Check that the STATUS_SETTINGS_DIALOG and STATUS_VALIDATE_STATE flags are set in the target transport provider's PR_RESOURCE_METHODS (PidTagResourceMethods) property. If STATUS_SETTINGS_DIALOG is not set, the transport provider does not display a configuration property sheet. If STATUS_VALIDATE_STATE is not set, you cannot perform dynamic reconfiguration.

  5. If STATUS_SETTINGS_DIALOG is set, call IMAPIStatus::SettingsDialog to display the transport provider's property sheet and allow the user to make changes.

  6. After the user has finished with the reconfiguration, call IMAPIStatus::ValidateState if STATUS_VALIDATE_STATE is set, passing CONFIG_CHANGED.


Handling Notifications

 Copy code hover
[image]

Handling Notifications
Send feedback

Published: July 16, 2012

Notifications enable one object to inform another object that it has undergone a change. The type of change is referred to as an event. MAPI defines several events for which notifications are generated.

Clients typically register for one or more events with one or more objects. These objects are referred to as advise sources. Objects that can act as advise sources include the session object, under MAPI's control, or an object created by a service provider, such as a message. The informed object, referred to as the advise sink, contains either an implementation of the IMAPIAdviseSink : IUnknown interface or the IMAPIViewAdviseSink : IUnknown interface and is within a client application.

Advise source objects implement an Advise method, which is called by clients to register for notifications, and an Unadvise method, which is called to cancel a registration. One of the parameters to Advise is a pointer to an implementation of IMAPIAdviseSink or IMAPIViewAdviseSink. The advise source caches this pointer so that it can call IMAPIAdviseSink::OnNotify or one of the methods in IMAPIViewAdviseSink when a change occurs.

Because receiving notifications enables users to view the most up-to-date information, it is recommended that all clients register for and handle notifications. However, it is optional.

In This Section

Registering for a Notification

Describes how to register a client for notifications as a part of its initialization process.

Canceling a Notification

Describes how to cancel a subscription to a notification.

Handling Message Store Notification

Describes how to register for message store notifications.

Handing Address Book Notification

Describes how to register for and handle address book notifications.

Handling Table Notification

Describes how to register for notifications from the hierarchy table.

Implementing an Advise Sink Object

Describes how to implement an advise sink object.

Timing a Notification

Describes the timing of client notification by service providers.

Ensuring a Thread-Safe Notification

Describes how to ensure thread-safe notification with MAPI.

Forcing a Notification

Describes how to force a notification in MAPI.


Registering for a Notification

 Copy code hover
[image]

Registering for a Notification
Send feedback

Published: July 16, 2012

A client can register for address book or message store notifications as part of its initialization process.

MAPI supports notification on the address book regardless of whether any of the address book providers support it. Support for notification on message stores depends on the particular message store provider. To determine whether a particular message store provider supports notifications, check its PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property. If the message store supports notifications, the STORE_NOTIFY_OK bit will be set.

Register for notifications by calling an advise source object's Advise method. Many objects implement Advise and clients can register with those objects in a variety of ways.

To register for a notification

  1. Create a MAPI advise sink object and increment its reference count.

  2. If appropriate, call HrThisThreadAdviseSink to create an advise sink object that wraps your original advise sink, then release the original advice sink..

  3. Call one of the following Advise methods to complete the registration:

    • Call IMAPISession::Advise to register for session notifications or for notifications on an address book or message store object.

    • Call IAddrBook::Advise to register for address book notifications or for notifications on a messaging user, container, or distribution list.

    • Call IABLogon::Advise to register directly with an address book provider for notifications on a messaging user, container, or distribution list.

    • Call IMsgStore::Advise to register for message store notifications or for notifications on a folder or message.

    • Call IMSLogon::Advise to register directly with a message store provider for notifications on a folder or message.

    • Call IMAPITable::Advise to register for table notifications.

  4. Cache the connection number returned from Advise.

  5. If using a wrapped advise sink, release it. Once the wrapped advise sink is registered, you no longer need it.

Calling IMAPISession::Advise enables you to register for critical error notifications on the overall session or for various notifications on individual objects. Sessions send critical error notifications to clients logged on to shared sessions when another client using the shared session calls the IMAPISession::Logoff method. To register for session notifications, pass NULL for the entry identifier parameter. To register for notifications on an individual object, pass the object's entry identifier. The IMAPISession method forwards the call to the appropriate service provider, as determined by the MAPIUID portion of the entry identifier. Calling IMAPISession::Advise to register for object notifications is simpler than calling a service provider's Advise method.

Registering with the address book is similar to registering with the session. To register for critical error notification from the address book, pass NULL for the entry identifier. To register for notifications on a particular address book object, specify the appropriate entry identifier and event or events of interest. Be aware that many address book providers do not support notifications on individual objects. Rather, they support table notifications on their contents and hierarchy tables.

It is good practice to release the advise sink that you implement or create with HrAllocAdviseSink immediately after a successful return from an Advise call. This is because it is possible for service providers to release your advise sink after the Advise call, but before an Unadvise call is made. Once you have given the advise source a pointer to your advise sink and the reference count has been incremented on this advise sink, it is wise to release it unless you have a long term use for it.

Note Note

All connection numbers that represent valid advisory registrations will not be released until the Unadvise call is made.


Canceling a Notification

 Copy code hover
[image]

Canceling a Notification
Send feedback

Published: July 16, 2012

To cancel a notification, clients call an advise source's Unadvise method. Calling Unadvise is important because it causes the service provider to release its reference to your advise sink. As long as a service provider maintains a reference to an advise sink, the advise sink can continue to receive IMAPIAdviseSink::OnNotify calls. In fact, because of the asynchronous nature of event notification, clients can be notified even after a successful Unadvise call. Clients must be able to handle the receipt of notifications at any time.

Because service provider implementations differ, clients that fail to call Unadvise to cancel a notification cannot assume anything about when a provider will release its reference to their advise sink. Some service providers release their references to advise sinks when they release their advise sources. Some service providers do not. As long as a service provider maintains a reference to an advise sink, that advise sink can continue to receive notifications.


Handling Message Store Notification

 Copy code hover
[image]

Handling Message Store Notification
Send feedback

Published: July 16, 2012

To register for message store notifications, call either the IMAPISession::Advise or IMsgStore::Advise method and specify a message store, folder, or message entry identifier in the contents of the lpEntryID parameter. Message store providers support both object and table notifications. Whether you register with particular message store objects, with the folder hierarchy and contents tables that describe these objects, or with both objects and tables depends on the notifications you expect to see, the calls you make to perform operations, and how the message store provider supports notification.

Because MAPI allows flexibility in how providers support notifications, be aware that you will not always receive the same type of notification in response to a particular event from all message store providers. Some message store providers do not support notifications at all. To determine if the message store you are using supports notification, look for the STORE_NOTIFY_OK bit in its PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property.

At one end of the spectrum of message store providers that support notification are the providers that generate "rich" notifications; these providers send descriptive notifications for all registered advise sources. At the other end are the message store providers that support limited notifications; these providers send general notifications for a restricted number of advise sources.

For example, if you copy a message to a folder with which you have registered to receive both object copied and object moved notifications, you may or may not receive the object copied notification. Whether or not you receive it depends on:

  • The method that you called to perform the copy. This could be IMAPIFolder::CopyMessages, IMAPIProp::CopyTo, or IMAPIProp::CopyProps.

  • How the message store provider implements the copy method.

  • Whether or not the message store provider supports object copied notifications on folders.

Because there are no strict guidelines that describe how to implement event notification for message store providers, clients cannot expect consistent behavior. MAPI does make recommendations as to how message store providers implement event notification and the following table outlines these recommendations. Read the table as follows: after you perform the operation in the first column, expect to receive a notification of the type listed in the second column if you have registered for that type with the object listed in the third column. For example, after you have created a folder, you will receive an fnevObjectCreated notification only if you have registered for fnevObjectCreated notifications with the message store.

Operation | Event type | Advise source
Create a folder | fnevObjectCreated | Message store
Delete a folder | fnevObjectDeleted | Message store Deleted folder
Move a folder from one folder to another | fnevObjectMoved | Message store Moved folder
Copy a folder from one folder to another | fnevObjectCopied | Message store and copied folder (no fnevObjectCreated notification sent for the new copy of the folder)
Change in a computed folder property (PR_SUBFOLDERS (PidTagSubfolders), PR_CONTENT_UNREAD (PidTagContentUnreadCount), PR_CONTENT_COUNT (PidTagContentCount) | fnevObjectModified | Message store Changed folder (No notification to parent folder)
Create a message | fnevObjectCreated | Message store
Delete a message, causing a change in the parent folder's PR_CONTENT_COUNT property | fnevObjectDeleted | Message store Deleted message
Move a message from one folder to another | fnevObjectMoved | Message store Moved message
Copy a message from one folder to another | fnevObjectCopied | Message store Copied message (No fnevObjectCreated notification for new copy of the message)
Save a message, causing a change in the parent folder's PR_CONTENT_COUNT property | fnevObjectCreated | Message store on first save only
Save a message | fnevObjectModified | Message store on saves after the first save Changed message (No notification to parent folder)
Complete a search operation | fnevSearchComplete | Message store Search folder
New message | fnevNewMail | Message store
Note Note

When you receive an object modified notification, remember that the property tag array portion of the OBJECT_NOTIFICATION structure pointed to by the lpNotifications parameter in the OnNotify call may or may not be NULL. Message store providers are not required to insert property information in this array and most do not. Make sure your OnNotify method can handle the case where the lpPropTagArray pointer is NULL.

For most, if not all object notifications, update the view of the affected folder or folders.


Handing Address Book Notification

 Copy code hover
[image]

Handing Address Book Notification
Send feedback

Published: July 16, 2012

Address book notifications allow a client to learn of events that occur to any address book entry or to a particular entry. You can register for these notifications either through the MAPI address book by calling IAddrBook::Advise or through an address book container's hierarchy or contents table by calling IMAPITable::Advise.

Specify the entry identifier of an address book container, distribution list, or messaging user if you are registering for notifications on a particular entry and NULL if registering for notifications on the entire address book. The entry identifier must represent a messaging user or distribution list in an address book container. IAddrBook::Advise examines this entry identifier to determine which address book provider is responsible for the corresponding object and forwards the call to the appropriate address book provider's IABLogon::Advise method.

Clients can register for the following types of events on address book entries:

  • Critical error

  • Any of the object events (created, modified, deleted, moved, or copied)

  • Table modified

Typically, registration occurs only on address book container contents and hierarchy tables. It is rare that clients register with the lower level messaging user and distribution list objects. This is because:

  • Many address book providers do not support notifications on their messaging users and distribution lists.

  • Table notifications are sufficient for tracking changes and reporting them to users.


Handling Table Notification

 Copy code hover
[image]

Handling Table Notification
Send feedback

Published: July 16, 2012

As an alternative to registering directly with an advise source object, such as a folder or a messaging user, a client can register for notifications on a contents or hierarchy table. Tracking changes to address book entries, folders, and messages through a contents or hierarchy table can be simpler and more straightforward than through individual objects. For example, you can call IMAPITable::Advise on a folder's hierarchy table to discover when changes occur to one of its subfolders. If you support the viewing of remote messages, register with the status table to observe activity by transport providers and the MAPI spooler.

However, it is not always preferable to use table notifications instead of object notifications. Monitoring changes in the number of messages in a folder is an example of when your client might need to register for object notifications on a folder rather than on a table implemented by the folder.


Implementing an Advise Sink Object

 Copy code hover
[image]

Implementing an Advise Sink Object
Send feedback

Published: July 16, 2012

A client can either implement its own advise sink objects or use a utility function, HrAllocAdviseSink. HrAllocAdviseSink creates an advise sink object with an implementation of OnNotify that invokes a callback function.

There are advantages and disadvantages to using HrAllocAdviseSink. It can save work, but it provides no control over reference counting the advise sink object that it creates. Therefore, clients that need to carefully control their advise sink's release or that have interdependencies between their advise sink and another client object should construct their own IMAPIAdviseSink implementation and avoid using HrAllocAdviseSink altogether.

A client implementing its own advise sink should make it an independent object not related to or dependent upon any other objects so as to eliminate potential complications in reference counting and object release. However, if you must implement your advise sink as part of another object or include a back pointer to another object as a data member, it is recommended that two separate reference counts be maintained: one for the object referenced by the advise sink and one for the advise sink.

When the reference count of the referenced object falls to zero, all of its methods can fail and its vtable can be destroyed, but the memory for the advise sink must remain intact until after its reference count also falls to zero. This means that the advise sink's Release method must decrement its reference count and finish destroying the object when that count reaches zero. If two separate reference counts are not maintained, it would be easy to inadvertently destroy the advise sink as part of the encompassing object's Release process.

Clients using HrAllocAdviseSink to implement an advise sink must be equally careful not to include their callback function as a method in another advise sink object. For C++ clients, it is tempting to do this and pass the this pointer as a parameter. This is a dangerous strategy because clients typically free an object when its reference count reaches zero. Freeing the memory for the advise sink object would render the this pointer invalid.

Depending on the type of event and the advise source, your OnNotify method can handle events in various ways. The following table offers suggestions in how to handle some of the standard events.

Type of event | Handling in OnNotify
Object moved | If the moved object's original parent is related to the new parent, update the view beginning with the folder or address book container highest in the hierarchy. If the two parent containers are unrelated, update both of their views.
New message | Change the user interface to inform the user of the arrival of one or more new messages. Place the receive folder in the current view.
Error | For all objects except the session, log the error if necessary and return. For the session object, log off if possible.
Search complete | No processing necessary.
Note Note

Notification handlers should be reentrant.


Timing a Notification

 Copy code hover
[image]

Timing a Notification
Send feedback

Published: July 16, 2012

Because event notification is an asynchronous process, you can be notified at any time, not necessarily immediately after the event has occurred.

The timing of calls to your IMAPIAdviseSink::OnNotify method varies depending on the service provider implementing the advise source. Service providers can notify your client either:

  • Simultaneously with the event.

  • Directly after the event.

  • At some later point following the event, possibly after an Unadvise call.

Most service providers call OnNotify after the MAPI method responsible for the event has returned to its caller. For example, notifications on messages are sent either when changes to the message are saved, after the IMAPIProp::SaveChanges call, or when the message is released, after the IUnknown::Release call. Until the notification is sent, no changes are visible in the message store.

You can receive notifications from an advise source after you have called Unadvise to cancel a registration. Be sure to release your advise sink only after its reference count has fallen to zero, not following a successful Unadvise call. Do not assume that because you have called Unadvise that the advise sink is no longer necessary.


Ensuring a Thread-Safe Notification

 Copy code hover
[image]

Ensuring a Thread-Safe Notification
Send feedback

Published: July 16, 2012

If your client runs on a multithreaded platform, you may need assurance that calls to your IMAPIAdviseSink::OnNotify methods occur on a particular thread. Because calls to OnNotify can typically occur on any thread, it is possible to receive notifications on unexpected and unwanted threads, leading to errors that are difficult to debug.

To guarantee that calls to OnNotify for a particular notification are made on the same thread that was used for the Advise call, call HrThisThreadAdviseSink before calling Advise. HrThisThreadAdviseSink creates a new advise sink object from your advise sink object. Pass this new object in the call to Advise. All clients with advise sink objects that might not work outside the context of a particular thread should always register advise sink objects created with HrThisThreadAdviseSink.


Forcing a Notification

 Copy code hover
[image]

Forcing a Notification
Send feedback

Published: July 16, 2012

When service providers use the IMAPISupport : IUnknown methods for notification, MAPI delivers notifications using a hidden window and its corresponding window procedure. For each process to receive a notification, MAPI posts a special message to the hidden window. This message is named with the constant szMAPINotificationMsg which is defined in MAPIDEFS.H.

You receive these notifications when the hidden window's window procedure processes the szMAPINotificationMsg message. To guarantee that notifications are delivered, it is necessary to wait for and dispatch this szMAPINotificationMsg message. Implementing the logic to achieve this can be done fairly simply, but MAPI provides an entry point into the MAPI DLL called HrDispatchNotifications to make processing even simpler. Call HrDispatchNotifications as follows to receive notifications in your client:

C++ Copy code Copy code
HRESULT hr = HrDispatchNotifications(0);


Handling MAPI Forms

 Copy code hover
[image]

Handling MAPI Forms
See also Send feedback

Published: July 16, 2012

A MAPI form is a viewer for a message of a particular class. Clients that allow their users to work with messages belonging to a variety of message classes must be written to handle a variety of MAPI forms. To handle multiple forms, clients implement a component known as a form viewer which contains the following three objects:

  • A message site object, which supports the IMAPIMessageSite : IUnknown interface.

  • A view advise sink, which supports the IMAPIViewAdviseSink : IUnknown interface.

  • A view context object, which supports the IMAPIViewContext : IUnknown interface.

Each of these objects is used by a component called the form server which implements each form, handling its storage and the notifications generated by clients handling the view. One other component, the form library provider, implements a form manager. The form manager administers the form libraries, which store form server executable files. This administration includes loading the appropriate form server and handling the initial communication between the server and the client.

The following diagram shows the relationship between a client and the other parts of the MAPI form architecture.

MAPI form architecture

MAPI form architecture

If your client plans to handle MAPI forms, you will use the form manager's IMAPIFormMgr : IUnknown interface to perform five basic tasks:

  • Launch the appropriate MAPI form server when a message is opened or composed.

  • Display form servers' icons in the contents tables of folders.

  • Send and receive form notifications. For more information, see Sending and Receiving Form Notifications.

  • Allow users to install or remove form servers from form libraries. For more information, see Maintaining a Form Library.

  • Allow users to associate form servers with particular folders.

To access the form manager, call the MAPIOpenFormMgr function once during initialization.

In This Section

Implementing a Form Viewer

Describes how to implement a form viewer by using a view advise sink, a message site, and a view context.

Implementing Standard Form Verbs

Describes how to implement the verbs for user menu or button clicks on MAPI forms.

Sending and Receiving Form Notifications

Describes how to send and receive form notifications.

Maintaining a Form Library

Describes how to maintain a library that holds all the important information about a form.

Loading a Message Into a Form

Describes how to load a message into a form.

Composing a New Message by Using a Form

Describes how to compose a message using a form.

Displaying Form Icons

Describes the steps for displaying an icon with a form.

See also

Concepts

MAPI Forms
Developing MAPI Form Servers


Implementing a Form Viewer

 Copy code hover
[image]

Implementing a Form Viewer
Send feedback

Published: July 16, 2012

A form viewer includes three objects: a message site, a view advise sink, and a view context. Each of these objects allows you to interact with a form server and its forms.

A message site is an object that implements the IMAPIMessageSite : IUnknown interface and assists form servers with tasks such as moving, saving, or deleting messages, creating new messages, or launching new form servers. Message sites are used by forms to get information about your client's status with respect to various service providers. For example, a form can use your message site to get a pointer to your current message store, a message, or a folder.

There are two types of methods in the IMAPIMessageSite interface:

  • Methods that provide information to form objects.

  • Methods that manipulate messages.

The methods that provide information to form objects are straightforward to implement. In all cases except IMAPIMessageSite::GetSiteStatus, you should already have available the information required by each method.

The methods that manipulate messages should act as if they had been triggered through your regular user interface. For example, if a form object calls your IMAPIMessageSite::NewMessage method, behave as if the user had chosen to compose a new custom message with your regular user interface. Commands which typically generate this behavior are Compose, Open, Reply, Reply to All Recipients, and Forward .

A view context is an object that implements the IMAPIViewContext : IUnknown interface and provides form servers with a context for the current message, allowing servers to easily switch to the next or previous message in the folder. A form uses a view context for sharing information. With a view context object, a form can:

  • Register with your client for notifications.

  • Activate the next or previous message in the folder.

  • Get printing information.

  • Get your client's status.

  • Get a stream that can be used to save the text version of a message.

Similar to the methods in the IMAPIMessageSite : IUnknown interface, the methods in IMAPIViewContext correlate with user actions and client features that relate to the view context. For example, a view context is involved with activating the next or previous message, sorting the contents of the folder, and filtering the contents of the folder.

It is not important what mechanism you provide for users to activate these features, it is only important that the semantics of those features map well to the methods in the IMAPIViewContext interface.

A view advise sink is an object that implements the IMAPIViewAdviseSink : IUnknown interface and handles notifications from form servers that affect your viewer and help forms and form viewers to work together. For more information, see Sending and Receiving Form Notifications.


Implementing Standard Form Verbs

 Copy code hover
[image]

Implementing Standard Form Verbs
Send feedback

Published: July 16, 2012

MAPI defines a set of standard verbs, or actions taken when a user makes a menu selection or clicks a button, that all form viewers should support. Each verb has a constant associated with it for identification, defined in the EXCHFORM.H header file. The following table lists the standard form verbs and their associated constants:

Verb | Value
Open | EXCHIVERB_OPEN
Reply | EXCHIVERB_REPLYTOSENDER
Reply to All | EXCHIVERB_REPLYTOALL
Forward | EXCHIVERB_FORWARD
Print | EXCHIVERB_PRINT
Save As | EXCHIVERB_SAVEAS
Reply to Folder | EXCHIVERB_REPLYTOFOLDER

When a user chooses a verb, pass its constant in a call to the form's IMAPIForm::DoVerb method to perform its corresponding action.

In addition to accessing verbs through your form viewer, users can sometimes access verbs directly from the form. For example, some form objects allow the user to invoke the Print verb by right-clicking on the form and choosing Print from a context-sensitive menu.


Sending and Receiving Form Notifications

 Copy code hover
[image]

Sending and Receiving Form Notifications
Send feedback

Published: July 16, 2012

Form notifications are used in MAPI to facilitate communication both from the form to your viewer as well as from your viewer to the form.

Forms send notifications to your viewer when one of the following events occur:

  • The form is closed.

  • A new message is loaded in the form.

  • A save operation is completed.

  • A message is sent.

Each of these event types correspond to a particular method in IMAPIViewAdviseSink : IUnknown, one of the interfaces that your form viewer must implement. When an event occurs, the form calls the corresponding IMAPIViewAdviseSink method in your viewer's advise sink. For example, when a new message arrives that your viewer should include in its display, the form calls your IMAPIViewAdviseSink::OnNewMessage method.

Implement your view advise sink in a way that makes sense for your viewer; there is no standard implementation. For example, in OnNewMessage you can update the view of the current folder's contents table to include the newly arrived message. In IMAPIViewAdviseSink::OnSubmitted, the method that is called when you receive a submitted message event, you can copy the submitted message to a Sent Items folder.

Forms receive notification from your viewer when a change occurs that affects the form and when you are loading a new message. To notify a form, call one of the methods of IMAPIFormAdviseSink: IMAPIFormAdviseSink::OnChange or IMAPIFormAdviseSink::OnActivateNext. Call OnChange to communicate status. For example, if the form is displaying the last item in a folder when a new message arrives, call OnChange with the VCSTATUS_NEXT flag set to tell the form that there is now a next item.

Call OnActivateNext to alert the form to the arrival of a new message that it may or may not be able to display. Pass the message class of the message to OnActivateNext.

Notifications by a form object to the client application are handled by the client application's IMAPIViewAdviseSink interface. For more information, see IMAPIViewAdviseSink : IUnknown.


Maintaining a Form Library

 Copy code hover
[image]

Maintaining a Form Library
Send feedback

Published: July 16, 2012

A form library holds all of the important information about a form: its properties, its verbs, and its server's executable files. Some clients allow their users to maintain, install, or remove form servers. If you want to offer this feature to your users, you must have access to:

  • The form server's configuration file, a file with the .CFG extension.

  • The form library's container object, an object that implements the IMAPIFormContainer : IUnknown interface.

To access the configuration file or a pathname to it, use whatever means are convenient. Usually, clients present the user with a dialog box for installing and removing form servers that can also be used to prompt the user for the location of the configuration file.

To access the form library's container, call the form manager's IMAPIFormMgr::OpenFormContainer method. Pass in an enumeration value to specify which form library to open, and if necessary, a pointer to the object that the form manager should use to open the form library. For example, if you are opening a Folder Form Libraries, pass an IMAPIFolder : IMAPIContainer pointer.

After OpenFormContainer returns the IMAPIFormContainer pointer, call either IMAPIFormContainer::InstallForm or IMAPIFormContainer::RemoveForm, depending on the maintenance to be performed. InstallForm adds a form server to the library; RemoveForm deletes a form server from the library.


Loading a Message Into a Form

 Copy code hover
[image]

Loading a Message Into a Form
Send feedback

Published: July 16, 2012

To load an existing message into a form using a form server, use one of the following strategies.

  • Call IMAPISession::PrepareForm to create a token and then IMAPISession::ShowForm to display the form.

  • Call IMAPIFormMgr::LoadForm.

Using the PrepareForm and ShowForm strategy is comparatively easy, but it results in forms that are modal with respect to your client. This is because the call to ShowForm does not return until the form has exited. If you need to handle forms asynchronously, do not use this strategy.

Using the LoadForm strategy is more difficult because the method requires several parameters. These parameters instruct the form manager to launch the proper form server in the proper context and display the proper message. If the form server is already running, the form manager loads the message into the form server without launching a new instance of the form server.

To specify which form server to launch, pass the message class handled by the target server in the contents of the lpszMessageClass parameter. The appropriate message class can be determined by retrieving the PR_MESSAGE_CLASS (PidTagMessageClass) property of the message to be loaded. Sometimes there is no form server for the specified message class, only a form server that handles messages belonging to the message's superclass. If you prefer that the message be loaded only by a form server specifically meant to handle messages of that class, set the MAPIFORM_EXACTMATCH flag in the LoadForm call. For more information, see MAPI Message Classes.

LoadForm also requires a pointer to your viewer's message site and view context and the value for the target message's PR_MSG_STATUS (PidTagMessageStatus) and PR_MESSAGE_FLAGS (PidTagMessageFlags) properties.


Composing a New Message by Using a Form

 Copy code hover
[image]

Composing a New Message by Using a Form
Send feedback

Published: July 16, 2012

To use a form to compose a new message, first create a new custom message object.

To compose a new message using a form

  1. Call the form manager's IMAPIFormMgr::ResolveMessageClass method to retrieve a pointer to a form information object — an object that implements the IMAPIFormInfo : IMAPIProp interface.

  2. Pass the pointer to the form information object in a call to IMAPIFormMgr::CreateForm. CreateForm loads the appropriate form server. In addition, pass an interface identifier to CreateForm to specify the interface to be used to access the new message. Typically, you request IPersistMessage : IUnknown by passing IID_IPersistMessage to CreateForm.

  3. Save the new message by calling its IPersistMessage::Save method. The form server should set values for the message's required properties when it creates the message.

  4. Load the message by using one of two strategies: IMAPIFormMgr::LoadForm or IMAPISession::PrepareForm followed by IMAPISession::ShowForm. For more information about these strategies, see Loading a Message Into a Form.

Note Note

There are opportunities for performance gains when loading a new custom message into a form server because you will already have had an opportunity to get some information about the message — such as its message class — during the processing required for the ResolveMessageClass and CreateForm calls. Because of this, you will be able to simplify the processing required before calling LoadForm over that described in the topic Loading a Message Into a Form.


Displaying Form Icons

 Copy code hover
[image]

Displaying Form Icons
Send feedback

Published: July 16, 2012

When displaying a list of messages in a folder, it is helpful to your users if you distinguish messages with custom message classes from the standard IPM.Note messages. Custom message classes correspond to form servers, and form servers provide icons to represent themselves. You can display these icons in the list of messages to alert users to each message's message class before the user opens the messages. Typically, the icon in the form's PR_MINI_ICON (PidTagMiniIcon) property is the one that should be displayed in the list of messages. Forms also have a PR_ICON (PidTagIcon) property that can be displayed when the form is minimized in a property sheet.

To get an icon for a message class without activating the form server for that message class

  1. Call the IMAPIFormMgr::OpenFormContainer method to get a pointer to an IMAPIFormContainer : IUnknown interface.

  2. Call the IMAPIFormContainer::ResolveMessageClass method to get a pointer to an IMAPIFormInfo : IMAPIProp interface.

  3. Call the IMAPIFormInfo::MakeIconFromBinary method to get an icon handle.

The icon can then be displayed using standard Win32 APIs.

Important note Important

Once you have the icon for a message class, make every effort to cache that icon. Not caching icons severely affects the performance of client applications. When caching icons, be careful of the relationships between message classes and their subclasses. For example, if the IPM.Note.Meeting.Cancel message class happens to resolve back to IPM.Note, do not assume that all subclasses of IPM.Note should use the icon for IPM.Note.


Administering Profiles and Message Services

 Copy code hover
[image]

Administering Profiles and Message Services
Send feedback

Published: July 16, 2012

Profile and message service administration can involve creating new profiles, deleting old profiles, and modifying the contents of existing profiles by changing the message services and service providers contained within them. Not all clients support profile and message service administration as standard features. Some clients have nothing more to do with profiles than allow their users to select one at logon time.

If you support profile or message service administration, chances are you will use the following interfaces that are implemented by MAPI:

  • IMsgServiceAdmin : IUnknown to administer a message service in a profile, accessible through either IMAPISession::AdminServices or IProfAdmin::AdminServices. Messaging clients typically call IMAPISession while configuration clients, or clients that do not send or receive messages, call IProfAdmin. Whenever possible, call the IProfAdmin method because it does not cause the message service to be started. For more information about using the IMsgServiceAdmin interface, see the following topics: Configuring a Message Service, Copying a Message Service, and Deleting a Message Service.

  • IProfAdmin : IUnknown to administer a profile, accessible through the MAPIAdminProfiles function. For more information about using the IProfAdmin interface, see the following topics: Creating a Profile by Using Custom Code, Copying a Profile, Deleting a Profile, Finding a Profile Name, and Setting a Default Profile.

  • IProfSect : IMAPIProp to maintain the properties in a profile section, accessible through the IMAPISession::OpenProfileSection or IProviderAdmin::OpenProfileSection method. For more information about profile sections, see MAPI Profiles.

  • IProviderAdmin : IUnknown to administer the service providers in a message service, accessible through IMsgServiceAdmin::AdminProviders. For more information about using the IProviderAdmin interface, see Adding or Deleting Providers in a Message Service.

Be careful in your support of profile and message service administration. There are no safeguards to protect against adversely modifying a profile that is in use. MAPI can prevent you from deleting a profile in use, but cannot prevent you from deleting every message service in it. If you delete every message service in a profile, all of the service providers in these services will stop thereby causing unpredictable results to occur.

In This Section

Creating a Profile

Describes how to create a profile.

Copying a Profile

Describes how to copy a profile.

Deleting a Profile

Describes how to delete a profile.

Setting a Default Profile

Describes how to set a default profile.

Finding a Profile Name

Describes how to find a name of a profile.

Adding a Message Service

Describes how to add a message service.

Configuring a Message Service

Describes how to configure a message service.

Copying a Message Service

Describes how to copy a message service to a profile.

Deleting a Message Service

Describes how to delete a message service.

Adding or Deleting Providers in a Message Service

Describes how to add or delete providers in a message service.


Creating a Profile

 Copy code hover
[image]

Creating a Profile
Send feedback

Published: July 16, 2012

A client can create a profile in one of two ways, by using the Profile Wizard, or by writing custom code.

In This Section

Creating a Profile by Using the Profile Wizard

Describes how to invoke the Profile Wizard, an application that creates a profile by enabling the user to choose message services and service providers interactively.

Creating a Profile by Using Custom Code

Describes how to write C or C++ code, often the best choice for noninteractive client applications which require a specific set of message services.


Creating a Profile by Using the Profile Wizard

 Copy code hover
[image]

Creating a Profile by Using the Profile Wizard
Send feedback

Published: July 16, 2012

The Profile Wizard is a MAPI feature that enables a user to create a profile in the easiest possible way. The Profile Wizard displays a series of dialog boxes which prompt the user to select message services and enter values for a few of the most essential configuration properties. For most of the other required properties, the Profile Wizard uses default values provided. To invoke the Profile Wizard, call LaunchWizard, a function based on the LAUNCHWIZARDENTRY prototype.

The user can add only those message services and service providers to the new profile that support the Profile Wizard. Because each message service might require more properties to be set than the Profile Wizard can handle, be aware that if you use this approach, it is possible for one or more of the selected services or providers to be incompletely configured.


Creating a Profile by Using Custom Code

 Copy code hover
[image]

Creating a Profile by Using Custom Code
Send feedback

Published: July 16, 2012

If you choose to write code to create a profile, make sure that you understand how to order profile entries and the type and amount of information that is needed for each entry. The implications of ordering entries in a profile is explained in MAPI Profiles.

To create a profile with C or C++ code

  1. Read the header file for each message service. Understand what properties you will need to configure and what values you will use.

  2. Call the MAPIAdminProfiles function to retrieve an IProfAdmin interface pointer.

  3. Call IProfAdmin::CreateProfile to create your profile. If you want to create a profile with the message services listed in the [Default Services] section of the MAPISVC.INF file, set the MAPI_DEFAULT_SERVICE flag. If you want to enable the user to enter configuration information, set the MAPI_DIALOG flag. Make sure that you set this flag if not all of the necessary information is available through the MAPISVC.INF file. CreateProfile calls the entry point function for each message service to be added to the profile with MSG_SERVICE_CREATE set as the ulContext parameter.

  4. Call IProfAdmin::AdminServices to obtain a message service administration object.

  5. Use the message service administration object to add message services to the profile. For each message service that you want to add:

    1. Call the IMsgServiceAdmin::CreateMsgService method to create the new message service.

    2. Call IMsgServiceAdmin::ConfigureMsgService, passing the MAPIUID structure of the service you just created and a property value array with its configuration properties.

  6. To retrieve the identifier of a newly added service, which is its PR_SERVICE_UID (PidTagServiceUid) property, call IMsgServiceAdmin::GetMsgServiceTable to access the message service table and search for the row that represents the message service. The last row in the table will represent the most recently added message service.

To make a new profile temporary, call the IProfAdmin::DeleteProfile method immediately after you log on. DeleteProfile will mark the new profile as deleted while making it usable for the duration of the session. Because it will not be included in the session's profile table, other clients will be unable to use it.


Copying a Profile

 Copy code hover
[image]

Copying a Profile
Send feedback

Published: July 16, 2012

One way to create a profile is to copy from an existing profile and alter the necessary message services and service providers. Copying a profile involves using a profile administration object, provided by MAPI through the MAPIAdminProfiles function.

To copy a profile

  1. Call MAPIAdminProfiles to retrieve an IProfAdmin interface pointer.

  2. Call IProfAdmin::GetProfileTable to access the profile table.

  3. Build a property restriction with an SPropertyRestriction structure to match PR_DISPLAY_NAME (PidTagDisplayName) with the name of the profile to be copied.

  4. Call IMAPITable::FindRow to locate the appropriate row in the profile table.

  5. Call IProfAdmin::CopyProfile, passing the value of the PR_DISPLAY_NAME column as the lpszOldProfileName parameter.


Deleting a Profile

 Copy code hover
[image]

Deleting a Profile
Send feedback

Published: July 16, 2012

To delete a profile

  • Call IProfAdmin::DeleteProfile.

DeleteProfile marks the profile for deletion if it is currently being used, waiting until it is no longer active to remove it. The profile does not actually disappear until every client with an active session has disconnected.

DeleteProfile calls the entry point function of every message service in the profile with the ulContext parameter set to MSG_SERVICE_DELETE. The calls to the entry point functions occur before the services are physically removed from the profile.


Setting a Default Profile

 Copy code hover
[image]

Setting a Default Profile
Send feedback

Published: July 16, 2012

The default profile is the profile that is used if you do not explicitly specify one in the call to MAPILogonEx, setting instead the MAPI_USE_DEFAULT flag.

To establish a default profile

  1. Call the MAPIAdminProfiles function to retrieve an IProfAdmin interface pointer.

  2. Call IProfAdmin::SetDefaultProfile. SetDefaultProfile sets the PR_DEFAULT_PROFILE (PidTagDefaultProfile) property for the new default profile and removes the setting for the previous default profile.


Finding a Profile Name

 Copy code hover
[image]

Finding a Profile Name
Send feedback

Published: July 16, 2012

Clients sometimes need to find the name of the profile currently being used for the session, the name of the default profile, or the name of an alternate profile installed on the computer.

There are a few ways to retrieve the name of a profile during the course of a session. If you need to find the name of a profile that is not necessarily the one being used for the session, use the first procedure. If you need to find the name of the default profile, use the second procedure. If you need to find the name of the current profile for the session, use the last procedure.

To find the name of any profile

  1. Call MAPIAdminProfiles to retrieve an IProfAdmin interface pointer.

  2. Call IProfAdmin::GetProfileTable to access the profile table.

  3. Call the profile table's IMAPITable::QueryRows method to retrieve all of the rows in the table and examine each one to determine if it represents your target profile.

To find the name of the default profile

  1. Call MAPIAdminProfiles.

  2. Call IProfAdmin::GetProfileTable to access the profile table.

  3. Build a property restriction with an SPropertyRestriction structure to match PR_DEFAULT_PROFILE (PidTagDefaultProfile) with the value TRUE.

  4. Call IMAPITable::FindRow to locate the row in the profile table that represents the default profile. The PR_DISPLAY_NAME (PidTagDisplayName) column contains the name of the default profile.

To find the name of the current profile

To find the name of the current profile, complete one of the following steps:

  • Assuming that you have the MAPIUID structure representing one of the current profile's sections, pass it in the lpUID parameter to IMAPISession::OpenProfileSection. Retrieve the profile section's PR_PROFILE_NAME (PidTagProfileName) property using its IMAPIProp::GetProps method.

  • Call IMAPISession::GetStatusTable to access the status table and find the row that has its PR_RESOURCE_TYPE (PidTagResourceType) column set to MAPI_SUBSYSTEM. The PR_DISPLAY_NAME column for this row is the profile name. Do not use the status table during start up because it blocks an application until the MAPI spooler has finished initializing all of the transport providers. This can degrade your performance.


Adding a Message Service

 Copy code hover
[image]

Adding a Message Service
Send feedback

Published: July 16, 2012

To add a new message service to a profile and access the new message service

Call IMsgServiceAdmin2::CreateMsgServiceEx. CreateMsgServiceEx performs the following tasks:

  1. Copies all of the relevant information for the message service that is in the MAPISVC.INF file, creating a profile section for every provider section.

  2. Calls the message service's entry point function, MSGSERVICEENTRY, with the ulContext parameter set to MSG_SERVICE_CREATE.

  3. Sets and retrieves the message service's PR_SERVICE_UID (PidTagServiceUid) property.

To access any newly added message service

  1. Call IMsgServiceAdmin::GetMsgServiceTable to retrieve the message service table.

  2. Call the message service table's IMAPITable::Advise method to register for table notifications.

  3. When MAPI sends a TABLE_ROW_ADDED notification, locate the entry identifier of the newly added message service in the SRow structure included in the TABLE_NOTIFICATION structure.


Configuring a Message Service

 Copy code hover
[image]

Configuring a Message Service
Send feedback

Published: July 16, 2012

To configure all the service providers in a message service

  • Call IMsgServiceAdmin::ConfigureMsgService. If all of the data necessary for configuration is available programmatically, you can choose whether or not to display a user interface. However, if some of the information for one or more providers is not available, make sure that you set the SERVICE_UI_ALLOWED or SERVICE_UI_ALWAYS flag. Suppressing a user interface when required configuration data is unavailable results in an unconfigured message service.

To configure a single service provider in a message service

  1. Call IMAPISession::GetStatusTable to access the service provider's status object.

  2. Call IMAPIStatus::SettingsDialog to display the service provider's property sheet.

For more information about using status objects, see Status Table and Status Objects.


Copying a Message Service

 Copy code hover
[image]

Copying a Message Service
Send feedback

Published: July 16, 2012

To copy a message service to a profile

  • Call IMsgServiceAdmin::CopyMsgService.

When a message service is copied, the new instance of the service is configured in exactly the same way as the original. Sometimes CopyMsgService returns the error MAPI_E_ACCESS_DENIED. The most common cause of this error return is a message service that does not allow itself to be duplicated.


Deleting a Message Service

 Copy code hover
[image]

Deleting a Message Service
Send feedback

Published: July 16, 2012

To delete a message service from a profile

  1. Call IMAPISession::GetMsgServiceTable to access the message service table.

  2. Locate the row for the message service and pass its PR_SERVICE_UID (PidTagServiceUid) column in the lpuid parameter to IMsgServiceAdmin::DeleteMsgService.

DeleteMsgService calls the message service's entry point function with the ulContext parameter set to MSG_SERVICE_DELETE. Message services perform any clean up tasks at this time before they are removed from the profile.


Adding or Deleting Providers in a Message Service

 Copy code hover
[image]

Adding or Deleting Providers in a Message Service
Send feedback

Published: July 16, 2012

To add or delete service providers in a message service, use the IProviderAdmin : IUnknown interface. You can retrieve an IProviderAdmin pointer by calling IMsgServiceAdmin::AdminProviders. The provider table, accessable through IProviderAdmin::GetProviderTable, lists information about the service providers currently installed in the message service. Clients and service providers can use the provider table to access the name of the provider DLL file, for example, or the MAPIUID, display name, and type of the provider as well as information about the message service. For more information, see Provider Tables.

To add or delete a service provider in a message service

  1. Call the AdminServices method to access a message service administration object.

  2. Call IMsgServiceAdmin::GetMsgServiceTable to access the message service table.

  3. Build a property restriction using an SPropertyRestriction structure that matches PR_DISPLAY_NAME (PidTagDisplayName) or PR_SERVICE_NAME (PidTagServiceName) with the name of the message service to be modified.

  4. Call the message service table's IMAPITable::FindRow method to locate the row in the table that represents the targeted message service.

  5. Call IMsgServiceAdmin::AdminProviders to retrieve an IProviderAdmin pointer. Pass the PR_SERVICE_UID (PidTagServiceUid) column from the message service table row as the lpUID parameter.

  6. Call IProviderAdmin::GetProviderTable to access the provider table.

  7. Build a property restriction using an SPropertyRestriction structure that matches PR_DISPLAY_NAME (PidTagDisplayName) or PR_PROVIDER_DISPLAY (PidTagProviderDisplay) with the name of the service provider to be added or deleted.

  8. Call the provider table's IMAPITable::FindRow method to locate the row in the table that represents the targeted service provider.

  9. Call IProviderAdmin::CreateProvider to add the provider or IProviderAdmin::DeleteProvider to remove it from the message service. For CreateProvider, pass the provider's PR_DISPLAY_NAME property as the lpszProvider parameter. For either method, pass the provider's PR_SERVICE_UID property as the lpUID parameter. After the service provider has been added or deleted, the change will not be apparent until a new session is created.

Another technique for adding a service provider, specifically a message store provider, to a profile involves constructing an entry identifier for the provider. Because constructing an entry identifier requires knowledge of its format, this technique can only be used if the service provider has made its entry identifier format public.

With the newly constructed entry identifier, a client can call IMAPISession::OpenMsgStore. MAPI automatically creates a profile section in the profile for the service provider, but does not add it to a message service.

Some message services do not allow this type of dynamic modification; whether or not it is supported is up to the message service. Another feature that may or may not be supported is the ability to directly access a message service's private profile sections. If the message service you are using permits such access, it will publish the GUID that represents the private section in MAPISVC.INF. You can pass this GUID in a call to IProviderAdmin::OpenProfileSection to access the profile section.


Advanced Client Topics

 Copy code hover
[image]

Advanced Client Topics
Send feedback

Published: July 16, 2012

This section includes subtopics on how to implement some of the more uncommon or difficult features in a client application.

In This Section

Writing an Automated Client

Describes how to write an automated client that suppresses the user interface.

Writing a Remote Viewer

Describes how to write a client application that provides controlled access to messages stored on another computer.

Writing a Hierarchy Viewer

Describes how to write a hierarchy viewer, a user interface component that is used for displaying folder and address book container hierarchy tables.

Using the MAPI Utilities

Describes how to use MAPI utilities that are made up of table data and property data objects and a variety of functions to support miscellaneous features

Implementing a Progress Indicator

Describes how to implement a progress indicator.

Centralizing the Receipt of NDRs

Describes how to centralize the receipt of non-delivery reports.


Writing an Automated Client

 Copy code hover
[image]

Writing an Automated Client
Send feedback

Published: July 16, 2012

An automated client application is an application that runs unattended, displaying no user interface.

By default, many MAPI interface methods show a user interface. All of these methods have flags that allow a client to either allow or suppress this display. Although MAPI expects service providers to honor these flags, there are some providers that do not always meet these expectations. A legitimate reason for not honoring the flags is the reliance of the service provider on another service that does not allow user interface suppression. If you are developing an automated client, pay careful attention to the service providers you are using and how they are configured. Do not assume that all of your calls to suppress a user interface will be successful.

Automated clients must have the necessary information available for proper configuration of each of the message services in the profile. There are two ways to supply configuration information at logon time:

  • The service provider can retrieve information from the profile.

  • The service provider can prompt the user for information.

Since the second option is unavailable to automated clients, these clients must use the first option. Clients must configure their profiles carefully to ensure that this option always works.

Automated clients always set the MAPI_NO_MAIL flag in the MAPILogonEx function call to begin a MAPI session.


Writing a Remote Viewer

 Copy code hover
[image]

Writing a Remote Viewer
Send feedback

Published: July 16, 2012

A remote viewer is a window in a client application that provides controlled access to messages stored on another computer. This controlled access might operate on a slow communications link. Rather than retrieve a complete selection of available messages every time a user opens a folder, the remote viewer first displays only the headers. The user then selects from the headers which of the messages to display in full. Remote viewer clients can allow their users to delete messages before they are ever downloaded.

To retrieve the headers of messages stored remotely

  1. Call IMAPISession::GetStatusTable to access the status table.

  2. Call IMAPITable::Restrict to limit the status table to only those rows that have their PR_RESOURCE_TYPE (PidTagResourceType) column set to MAPI_TRANSPORT_PROVIDER.

  3. Call IMAPITable::SetColumns to include the following columns in the status table: PR_ENTRYID (PidTagEntryId), PR_RESOURCE_METHODS (PidTagResourceMethods), PR_RESOURCE_TYPE, PR_PROVIDER_DISPLAY (PidTagProviderDisplay), and PR_STATUS_CODE (PidTagStatusCode).

  4. Call HrQueryAllRows to retrieve all the rows in the status table.

  5. Pass the entry identifier for each row in the table in a call to IMAPISession::OpenEntry. Because this interface is marshaled from the MAPI spooler's process context to the client's process context — unlike interfaces typically obtained from address book or message store providers — issues concerning multithreading are of more importance.

  6. Call the status object's IUnknown::QueryInterface method, passing IID_IMAPIFolder as the interface identifier, to retrieve the remote folder. The remote folder is not a complete folder implementation; it supports only a subset of folder methods and properties. One of the required methods, IMAPIProp::GetProps, supports the retrieval of the following properties:

    PR_ACCESS (PidTagAccess)

    PR_ACCESS_LEVEL (PidTagAccessLevel)

    PR_CONTENT_COUNT (PidTagContentCount)

    PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)

    PR_FOLDER_TYPE (PidTagFolderType)

    PR_OBJECT_TYPE (PidTagObjectType)

    PR_SUBFOLDERS (PidTagSubfolders)

    PR_CREATION_TIME (PidTagCreationTime)

    PR_DISPLAY_NAME (PidTagDisplayName)

    PR_DISPLAY_TYPE (PidTagDisplayType)

    Remote folders must also support the IMAPIProp::GetPropList, IMAPIContainer::GetContentsTable, and IMAPIFolder::SetMessageStatus methods. Remote folder contents tables typically support the following columns:

    PR_DISPLAY_TO (PidTagDisplayTo)

    PR_ENTRYID

    PR_HASATTACH (PidTagHasAttachments)

    PR_IMPORTANCE (PidTagImportance)

    PR_INSTANCE_KEY (PidTagInstanceKey)

    PR_MESSAGE_CLASS (PidTagMessageClass)

    PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)

    PR_MESSAGE_FLAGS (PidTagMessageFlags)

    PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime)

    PR_MESSAGE_SIZE (PidTagMessageSize)

    PR_MSG_STATUS (PidTagMessageStatus)

    PR_OBJECT_TYPE

    PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject)

    PR_PRIORITY (PidTagPriority)

    PR_SENDER_NAME (PidTagSenderName)

    PR_SENSITIVITY (PidTagSensitivity)

    PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName)

    PR_SUBJECT (PidTagSubject)

  7. Call the transport provider's IMAPIStatus::ValidateState method the first time that one of the transfer options is picked. Either the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE process flag should be set as well as the SHOW_XP_SSESSION_UI flag to allow the user interface to be shown.

    Note Note

    To mark a particular message header for downloading or deletion, a client calls IMAPIFolder::SetMessageStatus and sets either the MSGSTATUS_REMOTE_DOWNLOAD or MSGSTATUS_REMOTE_DELETE flag.


Writing a Hierarchy Viewer

 Copy code hover
[image]

Writing a Hierarchy Viewer
Send feedback

Published: July 16, 2012

A hierarchy viewer is a user interface component that is used for displaying folder and address book container hierarchy tables. Hierarchy viewers can display members of the hierarchy at different levels, expanding and contracting each level on demand.

The container property, PR_DEPTH (PidTagDepth), controls the level at which a hierarchy member is displayed. Entries that represent top-level address book containers or folders have their PR_DEPTH property set to zero. The value of this property is incremented sequentially for entries in sequential levels. That is, when a user selects a top-level container to expand, display all containers with PR_DEPTH set to 1. When a user expands one of these subcontainers, display the containers with PR_DEPTH set to 2, and so on.

Hierarchy viewers support a different range of depths. You can limit your viewer to only one or two levels or you can support multiple levels, if displaying an expansive hierarchy is a priority.

The address book provides a hierarchy viewer for the top-level containers in the address book.

To access the address book hierarchy table

  1. Call IAddrBook::OpenEntry, passing a null entry identifier, to open the address book's root container.

  2. Call the root container's IMAPIContainer::GetHierarchyTable method to access the hierarchy table of the MAPI address book.

To access the default message store's hierarchy table

  1. Call IMAPISession::GetMsgStoresTable to access the message store table.

  2. Build a restriction using the SPropertyRestriction structure to limit the table to only those rows that have a PR_DEFAULT_STORE (PidTagDefaultStore) property set to TRUE.

  3. Call IMAPITable::FindRow, passing it the SPropertyRestriction, to locate the row representing the default message store.

  4. Call IMAPISession::OpenEntry, passing in the PR_ENTRYID (PidTagEntryId) property from the default message store's row in the message store table.

  5. Call the message store's IMAPIProp::GetProps method to retrieve the PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId) property.

  6. Call the message store's IMsgStore::OpenEntry method, passing the PR_IPM_SUBTREE_ENTRYID property, to open the root folder of the message store's IPM subtree.

  7. Call the IPM root folder's IMAPIContainer::GetHierarchyTable method to access its hierarchy table.


Using the MAPI Utilities

 Copy code hover
[image]

Using the MAPI Utilities
Send feedback

Published: July 16, 2012

The MAPI utilities are made up of table data and property data objects and a variety of functions to support miscellaneous features. It is possible for a client to need only these utilities and not have to log on to the MAPI subsystem to establish a connection with service providers. If your client fits into this category, call the API function ScInitMapiUtil rather than the MAPIInitialize function at initialization time.

ScInitMapiUtil enables clients to use utility functions that require MAPI allocators, but that do not ask for the allocators explicitly. When it is time to shut down, call DeinitMapiUtil to free resources rather than MAPIUninitialize. Clients that never call MAPIInitialize should not call MAPIUninitialize.

If you have called ScInitMapiUtil rather than MAPIInitialize and are using tables through the ITableData methods rather than through the IMAPITable methods, be aware that table notifications will not work. Notifications require the use of the MAPI libraries and IMAPITable : IUnknown.


Implementing a Progress Indicator

 Copy code hover
[image]

Implementing a Progress Indicator
Send feedback

Published: July 16, 2012

Many of the operations initiated by clients take a significant amount of time. One of the input parameters to these potentially lengthy operations is a pointer to a progress object — an object that implements the IMAPIProgress : IUnknown interface. Progress objects control the appearance and display of progress indicators and are implemented by clients and by MAPI. You can choose whether or not to implement a progress object. The MAPI implementation is available for service providers to use if you elect not to supply an implementation.

Progress objects work with the following pieces of data:

  • A global minimum value which, when your IMAPIProgress::Progress method is called, should be less than or equal to the value of the ulValue parameter. At the beginning of the operation, ulValue will be equal to this minimum value.

  • A global maximum value which, when your IMAPIProgress::Progress method is called, should be greater than or equal to the ulValue parameter. At the end of the operation, ulValue will be equal to this maximum value.

  • A flags value which indicates whether the progress corresponds to a top or lower level item.

  • A value that indicates the current level of progress for the operation.

  • The number of the currently processed items relative to the total.

  • The total number of items to be processed during the operation.

The minimum and maximum values represent the beginning and end of the operation in numeric form. Use 1 for the initial minimum value and 1000 for the initial maximum value, passing these values to service providers in the IMAPIProgress::GetMin and IMAPIProgress::GetMax methods. Service providers reset these values when they call IMAPIProgress::SetLimits.

The flags value is used by service providers to determine how they should set the other values. Initialize the flags value to MAPI_TOP_LEVEL and return this value in your implementation of GetFlags until the service provider resets it by calling SetLimits.

In your implementation of the SetLimits method, save local copies of each of the parameters: lpulMin, lpulMax, and lpulFlags. These values should be readily available when a service provider calls your GetMin, GetMax, or GetFlags methods.

To update the display of the progress indicator, service providers call your IMAPIProgress::Progress method. There are three parameters to this method: a value, a count, and a total. Use the first parameter, ulValue, to display the progress indicator. The ulValue parameter is the progress indicator and will be equal to global ulMin only at the very beginning of the operation and equal to global ulMax only at the completion of the operation.

Use the second and third parameters, ulCount and ulTotal, if available, to display an optional message such as "5 items completed out of 10." If the second and third parameters are set to 0, you can choose whether or not to visually change the progress indicator. Some service providers set these parameters to zeroes to indicate that they are processing a subobject whose progress is monitored relative to a parent object. In this situation, it makes sense to change the display only when the parent object reports progress. Some service providers pass zeroes for these parameters every time.


Centralizing the Receipt of NDRs

 Copy code hover
[image]

Centralizing the Receipt of NDRs
Send feedback

Published: July 16, 2012

To have nondelivery reports (NDRs) arrive at a central location when multiple instances of your client are running simultaneously

  1. Set PR_REPORT_ENTRYID (PidTagReportEntryId), PR_REPORT_NAME (PidTagReportName), and PR_REPORT_SEARCH_KEY (PidTagReportSearchKey) to the appropriate values for the account that is to receive the reports. Create the entry identifier by calling IAddrBook::CreateOneOff if necessary.

  2. Understand that there are messaging systems that will ignore the account you've requested for reports and send them to the originator. Reduce the impact that this will have on administrators that will need to move reports around by:

    • Giving your original message a distinct message class, such as IPM.Note.MSNNews. Look for incoming messages with class Report.IPM.Note.MSNNews.NDR and forward them to the account you intended reports to come to. At the same time, send e-mail to the messaging system that ignored your nondelivery report account to communicate that it should honor the PR_REPORT_ENTRYID property.

    • Most messaging systems which do not honor PR_REPORT_ENTRYID will not honor the MAPI message class conventions either. Therefore, you'll receive something that looks like a note. This is a little harder to deal with because the input is so variable. Look at the subject and forward it if you find either something from a list of words that mean "undeliverable" or something from your original subject. Be prepared to tune these lists over time.


Improving Client Performance

 Copy code hover
[image]

Improving Client Performance
Send feedback

Published: July 16, 2012

The topics in this section contain tips that help you create a client application with the best possible performance.


Avoiding Certain Methods at Startup

 Copy code hover
[image]

Avoiding Certain Methods at Startup
Send feedback

Published: July 16, 2012

To improve performance at startup time, avoid making the following calls:

  • IMAPISession::EnumAdrTypes

  • IMAPISession::GetStatusTable

  • IMAPISession::Logoff

  • IMAPISession::QueryIdentity

  • IMAPIStatus::ValidateState

  • IUnknown::Release

The call to IMAPIStatus::ValidateState affects performance only when made on either the MAPI spooler or the MAPI subsystem. The reason that these methods slow startup processing is because they cannot complete until the MAPI spooler has finished its startup tasks.

You should also avoid searching the message store at startup time. Make your IMAPIContainer::SetSearchCriteria call when startup processing has finished.


Getting and Setting Multiple Properties

 Copy code hover
[image]

Getting and Setting Multiple Properties
Send feedback

Published: July 16, 2012

By getting and setting as many properties as possible with the least number of calls, remote activity is curtailed and the overhead involved with each property is reduced. Although service providers try to collect properties before making a remote procedure call for retrieval or modification, you can optimize this effort by requesting multiple properties to begin with.

For example, if you work with routing lists that describe future recipients with named properties belonging to particular property sets, process all of the recipients with two calls. Use one call to IMAPIProp::GetIDsFromNames to retrieve the identifiers for all of the recipient properties and the other call to IMAPIProp::GetProps to retrieve all of the values. The alternative, making a call to GetIDsFromNames followed by a call to GetProps for each recipient, is much less efficient.


Using a Table to Work with Properties

 Copy code hover
[image]

Using a Table to Work with Properties
Send feedback

Published: July 16, 2012

Many properties are available both from the objects that support them and as columns on tables. Whenever possible, retrieve these properties through the table.

Call IMAPITable::SetColumns to include all of the properties that your client needs and IMAPITable::QueryRows to retrieve all of the rows of the table.

These two calls are usually sufficient for retrieving enough information to display to a user, and are frequently sufficient for any necessary internal processing, making a call to OpenEntry to open the object unnecessary.

There are only two exceptions:

  • If the property is over 255 bytes. The IMAPITable interface might not return the entire property value, instead truncating it at 255 bytes. Think about this tradeoff, though. If you are displaying this data to the user, 255 bytes may be enough for a textual field such as a comment.

  • If you need a specific property from a single row in a table. In this case it is unnecessary to create a table with properties that will never be used. Most of the time you will need the same properties for all rows.


Getting and Setting Properties with GetProps and SetProps

 Copy code hover
[image]

Getting and Setting Properties with GetProps and SetProps
Send feedback

Published: July 16, 2012

Whenever possible, try to retrieve or modify a property with the IMAPIProp::GetProps and IMAPIProp::SetProps methods. Unless the property you are working with is very large, these methods should be adequate. The other alternative is to read from or write to a stream with the IStream interface. Streams can handle very large properties successfully, but they are a greater drain on resources because they require the COM libraries. Use the IStream interface only after your call to IMAPIProp::GetProps or IMAPIProp::SetProps fails.


Saving Frequently Used Properties

 Copy code hover
[image]

Saving Frequently Used Properties
Send feedback

Published: July 16, 2012

Improve performance by storing data that takes time and resources to retrieve and is accessed frequently. Using extra memory can sometimes be a better option that repeated retrievals. Use caution and care when creating a cache for storing this data. Keep in mind that a poorly designed cache can negatively impact performance.

For example, most interpersonal message (IPM) clients need to display and open the IPM subtree of folders many times during a typical session. You can improve performance by storing the entry identifiers for each of these folders.


Deferring Processing

 Copy code hover
[image]

Deferring Processing
Send feedback

Published: July 16, 2012

Pass the MAPI_DEFERRED_ERRORS flag to method calls as much as possible. Many of the MAPI method calls have been optimized to accept this flag, causing the provider to either postpone the requested task until multiple tasks can be performed at once or you can wait no longer for the results.

For example, if you pass MAPI_DEFERRED_ERRORS to IMsgStore::OpenEntry to open a folder, the opening of the folder and a possible remote call can be postponed until you make another call such as a call to the folder's GetHierarchyTable or GetProps methods. Both GetHierarchyTable and GetProps require the return of data from the service provider, a task that must be performed immediately.

Another way to defer processing is simply not to make a call. By being aware of the user and when the user can perceive a drain on resources or processing time, you can determine when it makes sense to make calls. There is an opportunity to improve performance by making calls either at a time when the user will not notice or by not making them at all.

For example, consider the situation when you are receiving more than one notification per second from a message store that is moving a great number of messages. A progress indicator is displayed to indicate the percentage of the operation's completion. Users typically will not perceive this operation to be slow until a few seconds have passed. Therefore, if you are updating the progress indicator, do not make any changes until at least four seconds after the initiation of the move operation. This will save time in the common cases when the operation is fast and inform users in a timely manner when the operation is slow.


Writing Uncompressed Formatted Text

 Copy code hover
[image]

Writing Uncompressed Formatted Text
Send feedback

Published: July 16, 2012

When preparing to send a message with formatted text, either set the message's PR_RTF_COMPRESSED (PidTagRtfCompressed) property to compressed or uncompressed text. Writing compressed text in the PR_RTF_COMPRESSED property is a very CPU intensive operation and can dramatically affect performance.

To improve the performance of sending formatted messages, either:

  • Upgrade the CPU, a solution that is not always plausible.

    - Or -

  • Write uncompressed text in the PR_RTF_COMPRESSED property.

The procedure for setting PR_RTF_COMPRESSED with uncompressed text is the same as for setting it with compressed text, with one exception. When calling WrapCompressedRTFStream, set the STORE_UNCOMPRESSED_RTF flag in the ulFlags parameter. Setting uncompressed text has the disadvantage in that it increases the size of messages.


Avoiding Using IStream::SetSize to Extend a Stream

 Copy code hover
[image]

Avoiding Using IStream::SetSize to Extend a Stream
Send feedback

Published: July 16, 2012

When writing to streams, it is sometimes necessary to enlarge them because their initial size is no longer sufficient. Use the OLE method IStream::Write to accomplish this rather than IStream::SetSize. IStream::Write automatically extends the stream, making IStream::SetSize unnecessary. Calling IStream::Write without IStream::SetSize can be up to three times faster than making the SetSize call prior to Write.


Sorting Tables After Setting Columns and Restrictions

 Copy code hover
[image]

Sorting Tables After Setting Columns and Restrictions
Send feedback

Published: July 16, 2012

When you need to limit the view of a sorted table, always make the following IMAPITable calls in the following order:

  1. IMAPITable::SetColumns to define the column set.

  2. IMAPITable::Restrict to impose the restriction.

  3. IMAPITable::SortTable to perform the sort.

If the sorted table is categorized, make a call to IMAPITable::SetCollapseState, if necessary, after the SortTable call. This ordering of calls is important because most service providers sort a table as the last task to achieve the best performance. If, for example, a message store provider must categorize a folder contents table before a restriction can be imposed, this categorization will be removed during the processing of the restriction. A second categorization will be necessary.


Calling QueryRows for Small Tables

 Copy code hover
[image]

Calling QueryRows for Small Tables
Send feedback

Published: July 16, 2012

When retrieving rows from a small table, call IMAPITable::QueryRows instead of first building a restriction. Creating a restriction impacts performance because the provider must first create a table, find the matching rows in the original table, and then copy the rows to the new table. If the total number of rows in the table is less than 100, it is probably more effective to read all of the rows and then call IMAPITable::FindRow to find the appropriate row. This is a particularly good strategy if this information is needed only occasionally.

The proper time to use a restriction is when the restricted or filtered information will be used over a longer period of time or used frequently. For instance, if you always need a view with unread messages, then a restriction is the proper call to use.


Opening OLE Attachments with IStreamDocfile

 Copy code hover
[image]

Opening OLE Attachments with IStreamDocfile
Send feedback

Published: July 16, 2012

When opening an OLE object attachment, use the IStreamDocfile interface rather than IStream or IStorage.IStreamDocfile provides direct access to the object using structured storage, eliminating the need to perform a copy operation and reducing overhead. IStreamDocfile is a specific implementation of IStream with the content of the stream guaranteed to be formatted as structured storage. IStreamDocfile is implemented by message store providers.


Naming Folders by Using Character Strings

 Copy code hover
[image]

Naming Folders by Using Character Strings
Send feedback

Published: July 16, 2012

If you access one or more folders frequently during a session, consider assigning names to the folders with the IMsgStore::SetReceiveFolder method. Although IMsgStore::SetReceiveFolder is used primarily to establish special folders to receive incoming messages for particular message classes, it can also be used to associate any folder with a name. The name can be the same as the message class or it can be any character string, customized for your client's use. Associating a name with a folder decreases the time it takes to find and open the folder.


Developing MAPI Form Servers

 Copy code hover
[image]

Developing MAPI Form Servers
See also Send feedback

Published: July 16, 2012

This section describes the process of creating form server executable and form configuration files for creating custom MAPI forms. Before reading this section, you should familiarize yourself with the information in MAPI Forms.

Developing a form server includes the following steps:

  1. Deciding what information the form will contain and choosing a set of properties to hold that information. For more information, see Choosing a Form's Property Set.

  2. Designing a user interface with which users can interact with the form's properties.

  3. Choosing a message class and generating a unique class identifier (CLSID). For an overview of message classes, see MAPI Message Classes. For more information about message classes and forms, see Choosing a Message Class.

  4. Implementing the required MAPI form interfaces, as well as any optional interfaces that your particular form server needs. For more information, see Writing Form Server Code.

  5. Writing user interface code to handle the user's interaction with the form object and the properties the form uses.

  6. Creating a form configuration file for the form. For more information, see File Format of Form Configuration Files.

  7. Installing the form on users' computers. For more information, see Installing a Form into a Library.

You will most likely perform steps 1 through 5 simultaneously rather than completing them in sequence. The process of developing a form server, like many programming projects, is not one in which there is a particularly well-defined sequence. For example, creating a form configuration file is shown as the second-to-last step above, but you will probably create your form configuration file incrementally, and it will become more complete as you add features to your form server.

See also

Other resources

MAPI Concepts


Choosing a Form's Property Set

 Copy code hover
[image]

Choosing a Form's Property Set
See also Send feedback

Published: July 16, 2012

When you implement your form server, you need to have a property for each piece of information that your message class needs. These properties can be predefined MAPI properties, or they can be custom properties that you define. For more information about working with properties, see MAPI Property Overview.

Your form configuration file will contain a list of properties that your form server exposes for client applications to use, but this does not have to be the entire list of properties used by your form server. Client applications typically use the exposed properties to enable users to sort messages in a folder or customize their interfaces in some way.

MAPI has a large set of predefined properties that suffice for most applications. However, there will be times when a custom message class needs a property that MAPI does not define. You can use custom properties to extend the MAPI predefined set of properties for whatever special information your form server needs to support.

You can use either of the following ways to define custom properties:

  • Choose a name for the property and use the IMAPIProp::GetIDsFromNames method to obtain a property tag for it. The IMAPIProp interface through which you call this method comes from the IMessage pointer that is passed to the form server when the message is created. Note that the property name must be a wide-character string.

  • Define a custom property tag yourself. Custom property tags must be in the range 0x6800 through 0x7BFF. Properties in this range are message-class specific.

For more information about defining custom properties, see Defining New MAPI Properties.

Note Note

Form servers that have a message text often use the PR_RTF_COMPRESSED (PidTagRtfCompressed) property to store it. If your form server uses PR_RTF_COMPRESSED, it should also ensure that the PR_BODY (PidTagBody) property contains a text-only version of the message text, in case the resulting message is read by a client that does not support Rich Text Format (RTF) message text.

See also

Concepts

Developing MAPI Form Servers


Choosing a Message Class

 Copy code hover
[image]

Choosing a Message Class
See also Send feedback

Published: July 16, 2012

As described in MAPI Message Classes, message classes are important for establishing the relationship between types of custom messages and, by extension, between form servers themselves. Fortunately, choosing a message class string is fairly simple. The message class string of a message class is an arbitrary string, but it should use the following conventions:

  • The string should satisfy all the conventions described in the documentation for the PR_MESSAGE_CLASS (PidTagMessageClass) property. Importantly, the string must be composed entirely of ANSI characters and be less than 256 characters long.

  • If your form server is derived from an existing form server or is an extension of an existing form server, your message class string should be formed by adding a period and another word to the message class string of the form server that your form is based on. For example, you might want to implement a form to reschedule a meeting, and your form is based on an existing form for scheduling meetings. If the meeting scheduling form's message class string is "IPM.Meeting", your message class string could be "IPM.Meeting.Reschedule".

  • If your form is not based on any existing form, your message class string should still begin with either the "IPM." or "IPC." prefix, depending on whether the form is intended to be received by a person or by another application. "IPM." designates an interpersonal message that usually ends up in a user's Inbox, and "IPC." designates an interprocess communication message that is not typically delivered to a user's Inbox.

  • If your message class is intended to be human-readable, the message class string should start with "IPM." A message class is generally considered human-readable if it uses any properties that contain plain text, HTML, or Rich Text Format (RTF) data. If your form uses the PR_BODY (PidTagBody) property, it should almost certainly use an "IPM." message class string. For example, if you are implementing a form for purchase orders, and your organization requires that purchase orders be approved by a manager, your message class string could be "IPM.Purchase_Order". Forms that are designed for use with public folders or public folder applications are typically considered to be interpersonal because they are read by people even though they are not actually addressed to any person's e-mail address. The typical prefix for public folder message classes is "IPM.Post".

  • If your message class is intended to be received by another application instead of by a person, the message class string should start with "IPC." For example, if you are implementing a form that enables people to automatically subscribe to mailing lists, your message class string could be "IPC.Subscribe".

  • Your message class string should never end with a period.

The message class string should be put in the [Description] section of the form configuration file, in the MessageClass entry, similar to the following:

MessageClass=IPM.Meeting.Reschedule

After you have chosen an appropriate message class string, you should generate a class identifier for it. Class identifiers can be generated with the Create GUID command that is included in Visual Studio. The class identifier must be put in the form configuration file's CLSID entry, along with the MessageClass entry, similar to the following:

CLSID={88FFF551-B8C5-11ce-8DE0-00AA0060D242}

Your class identifier will almost certainly be different, of course. For more information, see Creating a Form Configuration File.

When the form is installed on a user's computer, your installation process — whether it is a setup program or something else — must make a registry entry in the HKEY_CLASSES_ROOT\CLSID\ section of the registry for the class identifier. This entry must be set to the message class string. For example, you would create a registry entry similar to the following for the example class identifier above:

HKEY_CLASSES_ROOT\CLSID\{88FFF551-B8C5-11ce-8DE0-00AA0060D242}="IPM.Meeting.Reschedule"

For more information, see Installing a Form into a Library.

See also

Concepts

Developing MAPI Form Servers


Form States

 Copy code hover
[image]

Form States
See also Send feedback

Published: July 16, 2012

Form objects can be in one of five distinct states, depending on what methods have been called in them and whether any errors have occurred in performing those methods. The states are described in the following topics:

  • Uninitialized State

  • Normal State

  • NoScribble State

  • HandsOffAfterSave State

  • HandsOffFromNormal State

The states primarily relate to the status of the data in the form object. The different states reflect whether the data needs to be saved, whether the form object should allow modifications to the data, and what point in the process of saving the data the form is in. As such, the form states and transitions between them have more to do with your form server's implementation of IPersistMessage : IUnknown interface methods than any other. Knowledge of these states is very useful for proper implementation of the MAPI form interfaces that your form server must implement.

The topics in this section describe the various states, along with the allowed actions that cause transitions to other states. Any transitions not listed in the topics are not allowed. If your form objects make disallowed transitions between states, they will not behave in the ways that messaging clients expect and could cause unpredictable client or form object behavior.

Note Note

Some state transitions depend on information from previous states. Your form server will most likely have to implement a flag in its form objects to indicate whether the values of the message's properties have been changed to facilitate later state changes.

See also

Concepts

Developing MAPI Form Servers


Uninitialized State

 Copy code hover
[image]

Uninitialized State
See also Send feedback

Published: July 16, 2012

The Uninitialized state is the initial state form objects should be in when they are first created. Form objects become initialized with message data when a client application calls the IPersistMessage::InitNew or IPersistMessage::Load method on the form object. The following table describes allowed transitions from the Unitialized state.

IPersistMessage method | Action | New state
IPersistMessage::InitNew | Load the form object with default data. | Normal
IPersistMessage::Load | Load the form object with data from the target message. | Normal
IPersistMessage::GetClassID | Return success, or set the last error to and return E_UNEXPECTED. | Uninitialized
IPersistMessage::GetLastError | Return the last error. | Uninitialized
Other IPersistMessage : IUnknown methods or methods from other interfaces | Set the last error to and return E_UNEXPECTED. | Uninitialized

See also

Concepts

Normal State
Form States


Normal State

 Copy code hover
[image]

Normal State
See also Send feedback

Published: July 16, 2012

The Normal state is where the form object spends most of its time, waiting for client applications to initiate an action such as saving changes or closing the form. The following table describes allowed transitions from the Normal state.

IPersistMessage method | Action | New state
IPersistMessage::Save( pMessage == NULL, fSameAsLoad == TRUE) -or- IPersistMessage::Save( pMessage != NULL, fSameAsLoad == FALSE) | Recursively save any embedded OLE objects that have been modified. Save message data back to the message object. Store the fSameAsLoad flag for later use in the NoScribble state. | NoScribble
IPersistMessage::Save( pMessage != NULL, fSameAsLoad == TRUE) | This is the same as the previous case, except that this Save call is used in low-memory situations and must not fail for lack of memory. | NoScribble
IPersistMessage::HandsOffMessage | Recursively invoke the HandsOffMessage method on embedded messages or the OLE IPersistStorage::HandsOffStorage method on embedded OLE objects. Release the message object and any embedded messages or objects. | HandsOffFromNormal
IPersistMessage::SaveCompleted, IPersistMessage::InitNew or IPersistMessage::Load | Set the last error to and return E_UNEXPECTED. | Normal
IPersistMessage::GetLastError | Return the last error. | Normal
Other IPersistMessage : IUnknown methods or methods from other interfaces | Implement as described in the documentation for the IPersistMessage : IUnknown interface. | Normal

See also

Concepts

Form States


NoScribble State

 Copy code hover
[image]

NoScribble State
See also Send feedback

Published: July 16, 2012

The NoScribble state indicates that changes to a message are being saved. The actual saving of values stored in the form object's user interface occurs when the form object's IPersistMessage::Save method is called by the client application. The following table describes allowed transitions from the NoScribble state.

IPersistMessage method | Action | New state
IPersistMessage::SaveCompleted( pMessage == NULL) | If fSameAsLoad flag was TRUE on the IPersistMessage::Save call that caused the form to enter the NoScribble state and the message has been modified, internally mark the changes as saved and call the IMAPIViewAdviseSink::OnSaved method. | Normal
IPersistMessage::SaveCompleted( pMessage != NULL) | Call the IPersistMessage::HandsOffMessage method (similar to the OLE IPersistStorage::HandsOffStorage method) followed by the normal SaveCompleted actions. If SaveCompleted was successful, enter the Normal state. Otherwise, enter the HandsOffAfterSave state. | Normal or HandsOffAfterSave
HandsOffMessage | Recursively invoke the HandsOffMessage method on embedded messages or the OLE IPersistStorage::HandsOffStorage method on embedded OLE objects. Release the message object and any embedded messages or objects. | HandsOffAfterSave
Save, IPersistMessage::InitNew, or IPersistMessage::Load | Set the last error to and return E_UNEXPECTED. | NoScribble
IPersistMessage::GetLastError | Return the last error. | NoScribble
Other IPersistMessage : IUnknown methods or methods from other interfaces | Set the last error to and return E_UNEXPECTED. | NoScribble

See also

Concepts

Form States


HandsOffAfterSave State

 Copy code hover
[image]

HandsOffAfterSave State
See also Send feedback

Published: July 16, 2012

The HandsOffAfterSave state is part of the process of saving the contents of a form to permanent storage. When in this state, the form object should refrain from making changes to the in-memory copies of values of the message's properties, because there may not be another opportunity to save those changes. The following table describes allowed transitions from the HandsOffAfterSave state.

IPersistMessage method | Action | New state
IPersistMessage::SaveCompleted( pMessage != NULL) | Open any embedded objects. The data in the message stored in pMessage is guaranteed to be the same as the message in the previous IPersistMessage::Save call. If the SaveCompleted call succeeds, enter the Normal state. Otherwise, set the last error to E_OUTOFMEMORY and stay in the HandsOffAfterSave state. | Normal or HandsOffAfterSave
IPersistMessage::SaveCompleted( pMessage == NULL) | Set the last error to E_INVALIDARG or E_UNEXPECTED. | HandsOffAfterSave
IPersistMessage::HandsOffMessage, Save, or IPersistMessage::InitNew | Set the last error to and return E_UNEXPECTED. | HandsOffAfterSave
IPersistMessage::Load | Load the form object with data from the target message. This call can occur when the form object is going to the next or previous message in a folder. | Normal
IPersistMessage::GetLastError | Return the last error. | HandsOffAfterSave
Other IPersistMessage : IUnknown methods or methods from other interfaces | Set the last error to and return E_UNEXPECTED. | HandsOffAfterSave

See also

Concepts

Form States


HandsOffFromNormal State

 Copy code hover
[image]

HandsOffFromNormal State
See also Send feedback

Published: July 16, 2012

The HandsOffFromNormal state is very similar to the HandsOffAfterSave state. It is part of the process of saving the contents of a form to permanent storage. When in this state, the form object should refrain from making changes to the in-memory copies of values of the message's properties, because there may not be another opportunity to save those changes. The following table describes allowed transitions from the HandsOffFromNormal state.

IPersistMessage method | Action | New state
IPersistMessage::SaveCompleted( pMessage != NULL) | Replace the message object's message with pMessage, which is the replacement for the message revoked by the previous call to IPersistMessage::HandsOffMessage. The data in the new message is guaranteed to be the same as in the revoked message. The message should not be marked as clean, nor should IMAPIViewAdviseSink::OnSaved be called after this call. If the SaveCompleted call succeeds, enter the Normal state. Otherwise, stay in the HandsOffFromNormal state. | Normal or HandsOffFromNormal
IPersistMessage::SaveCompleted( pMessage == NULL) | Set the last error to E_UNEXPECTED. | HandsOffFromNormal
HandsOffMessage, IPersistMessage::Save, IPersistMessage::InitNew, or IPersistMessage::Load | Set the last error to E_UNEXPECTED. | HandsOffFromNormal
IPersistMessage::GetLastError | Return the last error. | HandsOffFromNormal
Other IPersistMessage : IUnknown methods or methods from other interfaces | Set the last error to E_UNEXPECTED. | HandsOffFromNormal

See also

Concepts

Form States


Writing Form Server Code

 Copy code hover
[image]

Writing Form Server Code
See also Send feedback

Published: July 16, 2012

You can think of a form server as the following:

  • A Win32 program that displays an interface and handles windows messages by way of the standard Windows message pump mechanisms.

  • An object that registers its class factory with OLE and is activated by OLE automation methods.

  • A MAPI object that follows the MAPI rules for interactions with other MAPI components.

Your code has to handle all three of those broad requirements simultaneously.

See the COM and ActiveX Object Services section in the Windows SDK for details about registering your form server's class factory. Handling windows messages and displaying an interface are standard Windows programming techniques that do not have any special requirements with respect to MAPI forms. Again, the Windows SDK has details about Windows programming. This document contains what you need to know to implement the required and optional MAPI form interfaces so that they follow the MAPI rules for interactions with other MAPI components — primarily the MAPI form manager and messaging client applications.

All of the interfaces that you can use when you implement form servers are derived — either directly or indirectly — from the OLE base class IUnknown. This means that all your implementations of these interfaces will need to have QueryInterface, AddRef, and Release methods. You can save yourself a lot of work if you use multiple inheritance to implement all of the required interfaces in one new class of your own, so that all the interfaces you use can share a single implementation of the required IUnknown methods. For more information, see the IUnknown::AddRef, IUnknown::QueryInterface, and IUnknown::Release methods. There are no special considerations with respect to MAPI form servers for these methods.

While not all of the MAPI form interfaces are mandatory for all form servers, the methods in any given interface are mandatory. That is, if you choose to implement a particular interface, you must implement all of the methods in the interface. This is different from the situation with some other MAPI components, such as message transports. Fortunately, the methods in the MAPI form interfaces are relatively straightforward, so implementing all of them does not put a great burden on developers.

The MAPI form interfaces are independent of the type of development tool used to create a form server. This allows forms to be created by using different development tools. The only requirement is that all form servers must support the required MAPI form interfaces.

Not all of the MAPI interfaces that relate to forms are required by all form servers. The optional interfaces allow you to implement some advanced form functions that are not needed by most form servers. The following table lists the interfaces, what they are for, and whether you must implement them.

Interface | Description | Status
IMAPIForm : IUnknown | The primary interface that clients use to load form servers, execute form verbs, and shut down form servers. This is also the interface derived from the OLE IUnknown that is used to inform other OLE components regarding what interfaces a form object implements. | Required
IPersistMessage : IUnknown | Used when loading messages into and saving messages from form objects. | Required
IMAPIFormAdviseSink : IUnknown | Used by form objects to keep track of messaging client status and to find out whether the form object is capable of displaying the next or previous message in a folder. | Optional
IClassFactory | The OLE class factory interface used by form objects for compliance with the OLE class factory mechanism. | Required
IMAPIFormFactory : IUnknown | Used if your form server supports more than one type of form. In this case, the IMAPIFormFactory interface allows client applications to access the multiple IClassFactory interfaces (one per type of form that your form server supports) that your form server must also implement. | Optional

See also

Concepts

Developing MAPI Form Servers


Declaring Form Interfaces

 Copy code hover
[image]

Declaring Form Interfaces
See also Send feedback

Published: July 16, 2012

You can simplify the declarations of your implementations of MAPI form interfaces by using the MAPI_interface_METHOD macros, where interface is a form interface defined in the Mapiform.h header file. You are not required to use these macros, but if you do not, you should take particular care that your declarations conform to the declarations in the Mapiform.h header file. For example, you could declare your form server's form object class like the following:

C++ Copy code Copy code
class CMyForm : public IPersistMessage, public IMAPIForm,
                public IMAPIFormAdviseSink
{
public:
    CMyForm(CClassFactory *);    // constructorr takes a class factory object
    ~CMyForm(void);

// MAPI methods that need to be implemented.
    MAPI_IUNKNOWN_METHODS(IMPL);
    MAPI_GETLASTERROR_METHOD(IMPL);
    MAPI_IPERSISTMESSAGE_METHODS(IMPL);
    MAPI_IMAPIFORM_METHODS(IMPL);
    MAPI_IMAPIFORMADVISESINK_METHODS(IMPL);

// Add other implementation specific items.

};

See also

Concepts

Writing Form Server Code


Integrating MAPI Form Server Code with Windows Code

 Copy code hover
[image]

Integrating MAPI Form Server Code with Windows Code
See also Send feedback

Published: July 16, 2012

Recall that your form server is a Win32 application. As such, there are some tasks related to loading your form server into memory and exiting cleanly. Like all Windows applications, the entry point for your form server is the WinMain function. This function is the appropriate place to perform the following tasks:

  • Creating and registering a window class so that your form server can interact with other OLE components.

  • Creating and registering a window class or classes for your form objects' user interfaces.

  • Calling the MAPIInitialize function. MAPIInitialize handles the required OLE initialization for you, as well. This must be done once per instance of your form server.

  • Registering a global atom with a string representation of the form server's class identifier (CLSID). This atom should exist for the lifetime of the form server.

  • Calling the OLE function CoRegisterClassObject to register your form server's class factory with OLE.

  • Creating a main window to receive messages. This window probably does not need to be visible because the user will be interacting with the specific windows associated with individual form objects. However, during development, the main window can be a convenient place for debugging output or control of your form server.

  • Creating a message loop that runs for the lifetime of the form server, translating and dispatching windows messages to active form objects.

When your form server exits, it should perform the following tasks:

  • Call the OLE function CoRevokeClassObject to revoke your message class's OLE registration.

  • Call MAPIUninitialize to properly close the form server's connection to MAPI.

  • Delete the global atom that contains the string representation of the class identifier.

See also

Concepts

Writing Form Server Code


Implementing the IClassFactory Interface for Form Servers

 Copy code hover
[image]

Implementing the IClassFactory Interface for Form Servers
See also Send feedback

Published: July 16, 2012

IClassFactory is the OLE interface that client applications use to create new form objects of your form server's message class. The following table lists the IClassFactory methods that are required.

Method | Description
CreateInstance | Creates a new form object.
LockServer | Locks the form server in memory so that startup overhead can be avoided when multiple form objects are created.

For all the information necessary to implement these methods, see the COM and ActiveX Object Services section in the Windows SDK.

See also

Concepts

Writing Form Server Code


Creating a Form Configuration File

 Copy code hover
[image]

Creating a Form Configuration File
See also Send feedback

Published: July 16, 2012

A form configuration file provides information about a form both to the form manager being used and to client applications. A form configuration file contains an extensive specification for a form, including the properties published by the form for use by messaging clients, the verbs implemented by the form, and the platforms supported by the form.

A form configuration file is a file with a .cfg extension, and has a format similar to a Windows initialization file. It is a plain text file with a number of sections. Each section begins with a section name, enclosed in square brackets. Each section contains one or more lines that define values and settings relevant to that section. Values have one of the following types:

  • String

  • Displayed string

  • Platform string

  • Path name

  • Integer

  • GUID

For more information about the sections of a .cfg file, see File Format of Form Configuration Files.

See also

Concepts

Developing MAPI Form Servers


Form Server Interactions

 Copy code hover
[image]

Form Server Interactions
See also Send feedback

Published: July 16, 2012

The topics in this section describe interactions between client applications, the MAPI form manager, form servers, and form objects for a variety of common actions such as opening a message and composing a new message.

See also

Concepts

Developing MAPI Form Servers


Retrieving Form Properties

 Copy code hover
[image]

Retrieving Form Properties
See also Send feedback

Published: July 16, 2012

To issue a query that is meaningful to a custom message type, an application needs to know the properties that are expected on that message. To get a list of properties that a custom message class uses, a client application queries the MAPI form manager. The form manager gets this information from the appropriate form configuration file so that client applications can use this information without the overhead of activating the form server itself. To do this, the client application calls the IMAPIFormMgr::ResolveMessageClass method as follows:

C++ Copy code Copy code
IMAPIFormInfo *pfrminf = NULL;
hr = pfrmmgr->ResolveMessageClass("IPM.Demo", 0L, NULL, &pfrminf);

Note that the third argument to ResolveMessageClass is the folder that contains the associated contents table that the query will search for form servers. NULL indicates that the form manager should search all available form containers. If the query is to run against a particular folder, it is better to include the appropriate IMAPIFolder pointer instead.

See also

Concepts

Form Server Interactions


Launching a Form to Read a Message

 Copy code hover
[image]

Launching a Form to Read a Message
See also Send feedback

Published: July 16, 2012

Form server implementers should expect the following sequence of method calls to their form server and form objects when a client application loads a message:

  1. The client application opens the form manager with a call to the MAPIOpenFormMgr function.

  2. The client application calls the IMAPIFormMgr::LoadForm method, which returns an object with IMAPIForm. The form manager may be released now if it will not be used for further form activations. Note that a call to LoadForm may take some time because the form manager may have to install the form server's executable files before proceeding.

  3. Optionally, the client application can prepare IMAPIViewContext to control operations that may cause the form object to load the previous or next message in the folder. The client application can use the IMAPIForm::SetViewContext method to change the default view context that was set in the LoadForm call.

  4. The client application calls the IPersistMessage::Load method to load message data into the form object.

  5. The client application calls IMAPIForm::DoVerb to invoke the open verb, passing the optional IMAPIViewContext interface pointer.

See also

Concepts

Form Server Interactions


Launching a New Compose Form

 Copy code hover
[image]

Launching a New Compose Form
See also Send feedback

Published: July 16, 2012

Form server implementers should expect the following sequence of method calls to their form server and form objects when a client application opens a new message for composing:

  1. The client application calls the IMAPIFormMgr::ResolveMessageClass method to get class information about the form server's message class.

  2. The client application calls IMAPIFormMgr::CreateForm to get a new form object.

  3. The MAPI form manager loads the form server, if it is not already in memory, and gets an IMAPIForm interface from the form server.

  4. The client application takes the resulting IMAPIForm interface and calls the IUnknown::QueryInterface method to get the object's IPersistMessage interface.

  5. The client application calls the IPersistMessage::InitNew method to associate the form object with IMessage, view context, and advise sink objects.

  6. The client application calls the IMAPIForm::DoVerb method to invoke the open verb.

See also

Concepts

Form Server Interactions


Launching a Form Server

 Copy code hover
[image]

Launching a Form Server
See also Send feedback

Published: July 16, 2012

The series of interactions that occurs when a form is loaded from persistent storage (that is, from a form library) to display a message is as follows:

  1. The messaging client gets the message's message class, message flags, and message status. This step is optional; if these pieces of data are not provided in step 2, the form manager will retrieve them.

  2. The messaging client calls IMAPIFormMgr::LoadForm with the target message.

  3. The form manager loads the form server from the appropriate form library. If the form server for the target message is not installed, the form manager installs the form's executable files, as well.

  4. The form manager calls IUnknown::QueryInterface on the form object to obtain the form object's IMAPIForm : IUnknown and IPersistMessage : IUnknown interfaces.

  5. The form manager calls IPersistMessage::Load with the message site and message interfaces from the viewer object.

  6. The form object calls back to the messaging client's IMAPIMessageSite::GetSiteStatus method.

  7. The form manager calls the form object's IMAPIForm::SetViewContext method with the view context interface from the messaging client.

  8. The form object calls back to the messaging client's IMAPIViewContext::SetAdviseSink method.

  9. The form object calls back to the messaging client's IMAPIViewContext::GetViewStatus method.

  10. The messaging client calls the form object's IMAPIForm::Advise method with the view context interfaces from the viewer object and the message site object.

  11. The messaging client calls the form object's IMAPIForm::DoVerb method.

  12. The form object creates its user interface, if necessary, and interacts with the user.

See also

Concepts

Form Server Interactions


Installing a Form into a Library

 Copy code hover
[image]

Installing a Form into a Library
See also Send feedback

Published: July 16, 2012

The default MAPI form manager supplied with the Windows SDK does not provide a user interface for installing forms in the various form libraries. Because of this, you will have to create a small application — or detailed set of instructions — that users can use to install the form.

If you implement an installation application, the series of actions it must perform to install a form into a folder's associated contents table are as follows:

  1. Call the MAPIOpenFormMgr function to open the form manager.

  2. Use IMAPIFormMgr::OpenFormContainer or IMAPIFormMgr::SelectFormContainer method to select and open the target container for the form.

  3. Use the IMAPIFormContainer::InstallForm function to install the form.

    Steps 4 through 6 are for installation into a local form library:

  4. Copy all files to the appropriate place on the local disk, if installation is to the local form library on the user's workstation. If necessary, modify the form configuration file to reflect current paths of components. The form configuration file can contain relative paths, in which case this step may not be necessary.

  5. Complete the appropriate OLE registration steps to associate the message type with the form server being installed.

  6. If the form was installed into the local form library, copy the form's icon (.ico) and configuration (.cfg) files into the %WINDOWS%\FORMS\CONFIGS directory so the form can be automatically restored in case the form library is corrupted or deleted. This step is recommended but not mandatory.

Note Note

You can simplify installation to a local form library by replacing steps 1 and 2 with a call to the MAPIOpenLocalFormContainer function.

See also

Concepts

Developing MAPI Form Servers


MAPI Entry Identifiers

 Copy code hover
[image]

MAPI Entry Identifiers
See also Send feedback

Published: July 16, 2012

Entry identifiers are pieces of binary data stored in an ENTRYID structure that are used to uniquely identify and open a MAPI object. Most MAPI objects have entry identifiers. Entry identifiers for objects are analogous to file names for files. However, they are not transmittable and cannot be used on systems other than the system they originated on.

Entry Identifiers

Message store providers assign entry identifiers to message stores, folders, and messages; address book providers assign them to address book containers, distribution lists, and messaging users. Entry identifiers are also used to open an object represented by a row in a table, such as a status object in the status table. Objects store their entry identifiers in their PR_ENTRYID (PidTagEntryId) property.

Whereas service providers create, assign, and examine entry identifiers, client applications use them only as tools for opening objects. To clients, entry identifiers are opaque pieces of binary data and have nothing to do with the underlying messaging system.

Clients call an object's IMAPIProp::GetProps method to retrieve its PR_ENTRYID property or a table's IMAPITable::QueryColumns method to retrieve the column that holds the PR_ENTRYID property.

Entry identifiers are passed as parameters to the OpenEntry and CompareEntryIDs methods. Several MAPI objects implement the OpenEntry and CompareEntryIDs methods. With OpenEntry, clients can open an object. With CompareEntryIDs, clients can compare two entry identifiers to determine whether they refer to the same object. Because entry identifiers are not necessarily binary comparable, clients must compare them by the CompareEntryIDs method.

Clients should always pass naturally aligned entry identifiers in their calls to service providers, because although service providers should handle entry identifiers that are arbitrarily aligned, this is not always the case. A naturally aligned memory address enables the computer to access any data type it supports at that address without generating an alignment fault. The natural alignment factor is typically the same alignment factor used by the system memory allocator and is usually 8 bytes.

Entry identifiers come in two types: short-term and long-term. Short-term entry identifiers are faster to construct, but their uniqueness is guaranteed only over the life of the current session on the current workstation. Long-term entry identifiers have a more prolonged lifespan. Short-term entry identifiers are used primarily for rows in tables and entries in dialog boxes, whereas long-term entry identifiers are used for many objects such as messages, folders, and distribution lists.

See also

Concepts

MAPI Application Development


Constructing Entry Identifiers

 Copy code hover
[image]

Constructing Entry Identifiers
See also Send feedback

Published: July 16, 2012

Entry identifiers are constructed with the ENTRYID structure. The ENTRYID structure is composed of a flag that describes the attributes of the entry identifier and the actual entry identifier.

ENTRYID Structure

The ENTRYID structure is defined as follows:

C++ Copy code Copy code
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_NOTRECI — Indicates the entry identifier cannot be used as a recipient on a message.

  • MAPI_NOTRESERVED — Indicates that other users cannot access the entry identifier.

  • MAPI_NOW — Indicates that the entry identifier cannot be used at other times.

  • MAPI_SHORTTERM — Indicates that 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 — Indicates that the entry identifier cannot be used on other sessions.

  • MAPI_NOTRESERVED — Indicates that the entry identifier can be used by other service providers for other objects.

The ab member of entry identifiers that is created by address book and message store providers is composed of two pieces: a 16-byte MAPIUID structure 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 that can be created by using the Microsoft Visual Studio Create GUID tool.

A service provider registers its MAPIUID structure with MAPI during the logon process in a call to the IMAPISupport::SetProviderUID method. 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.

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 information in this part of its entry identifiers:

  • Version information — 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 — 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.

Although service providers can recycle their entry identifiers, they should avoid this practice. 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.

See also

Concepts

MAPI Entry Identifiers


Short-Term Entry Identifiers

 Copy code hover
[image]

Short-Term Entry Identifiers
See also Send feedback

Published: July 16, 2012

A short-term entry identifier is assigned by a service provider to an object when the identifier must be constructed quickly and does not need to last over time or distance. The uniqueness of a short-term entry identifier is guaranteed only over the life of the current session on the current workstation. Typically, a short-term entry identifier is valid only until the object that it represents is released.

Short-term entry identifiers are assigned to rows in tables and to entries in dialog boxes, where it is necessary to provide data quickly for browsing. For example, message store providers assign short-term entry identifiers to rows of messages in a contents table and to recipients in a recipients table. Clients can use these short-term entry identifiers to open the objects represented by the table rows. However, unlike long-term entry identifiers that can be used with any of the OpenEntry methods, short-term entry identifiers should be used with the container's OpenEntry method.

Implementing Short-Term Entry Identifiers

The most common ways to implement short-term entry identifiers include the following:

  • Making the short-term entry identifiers the same as the long-term identifiers, leaving all of the flags unset.

  • Making the short-term entry identifiers different from the long-term identifiers, setting all of the flags.

Clients can identify a short-term entry identifier of the second type by examining its abFlags member as follows:

C++ Copy code Copy code
abFlags[0] = 0xFF;

Some service providers clear one or more flags to create short-term entry identifiers that have greater validity. For example, the following abFlags members represent short-term entry identifiers that can be used for multiple days or for multiple sessions:

C++ Copy code Copy code
abFlags[0] = 0xFF & ~MAPI_NOW;
abFlags[0] = 0xFF & ~MAPI_THISSESSION;

Clients quickly acquire, use, and discard short-term entry identifiers. For the most part, they can be used in the same manner as long-term entry identifiers. They can be retrieved from a table, passed to the OpenEntry method, and compared with the CompareEntryIDs method. The one exception is that they are never returned from the IMAPIProp::GetProps method. The properties returned from GetProps are always long-term entry identifiers.

See also

Concepts

MAPI Entry Identifiers


Long-Term Entry Identifiers

 Copy code hover
[image]

Long-Term Entry Identifiers
See also Send feedback

Published: July 16, 2012

A long-term entry identifier is assigned by a service provider to an object when an object requires an identifier with a prolonged lifespan. Long-term entry identifiers are always valid for weeks or months and can be valid on other workstations, depending on the provider. The long-term identifiers created by address book providers for custom recipients are universally valid.

Long-term entry identifiers are assigned to message stores, folders, messages, address book containers, messaging users, and distribution lists. When client applications call the IMAPIProp::GetProps method of these objects, it is always a long-term entry identifier that is returned.

Long-term entry identifiers must be unique across all message stores in the active profile; therefore, when a message or folder is copied from one message store to another, it must be assigned a new entry identifier. When a message store object is moved, the message store provider that implements the move determines whether the original entry identifier will remain valid. Some service providers assign new entry identifiers to moved objects; others do not. If there is a change, the new entry identifier will be included in the information passed to clients when they are notified of the move.

Typically, message store providers implement the following behavior when they move folders:

  • When a folder is moved from one message store to another store of a different type, the entry identifier is guaranteed to change.

  • When a folder is moved from one message store to another store of the same type, the entry identifier almost always changes.

  • When a folder is moved to another location within the same message store, the entry identifier might or might not change, depending on the message store provider.

Renaming a folder without changing its parent folder usually does not cause the entry identifier to change.

See also

Concepts

MAPI Entry Identifiers


MAPI Record and Search Keys

 Copy code hover
[image]

MAPI Record and Search Keys
See also Send feedback

Published: July 16, 2012

Record keys and search keys are binary identifiers that are assigned to many MAPI objects. Unlike an object's entry identifier, its record or search key is directly comparable as well as transmittable.

Record Keys

A record key is used to compare two objects. Message store and address book objects must have record keys, which are stored in their PR_RECORD_KEY (PidTagRecordKey) property. Because a record key identifies an object and not its data, every instance of an object has a unique record key. The scope of a record key for folders and messages is the message store. The scope for address book containers, messaging users, and distribution lists is the set of top-level containers provided by MAPI for use in the integrated address book.

Record keys can be duplicated in another resource. For example, different messages in two different message stores can have the same record key. This is different from long-term entry identifiers; because long-term entry identifiers contain a reference to the service provider, they have a wider scope. A message store's record key is similar in scope to a long-term entry identifier; it should be unique across all message store providers. To ensure this uniqueness, message store providers typically set their record key to a value that is the combination of their PR_MDB_PROVIDER (PidTagStoreProvider) property and an identifier that is unique to the message store.

Search Keys

A search key is used to compare the data in two objects. An object's search key is stored in its PR_SEARCH_KEY (PidTagSearchKey) property. Because a search key represents an object's data and not the object itself, two different objects with the same data can have the same search key. When an object is copied, for example, both the original object and its copy have the same data and the same search key.

Messages and messaging users have search keys. The search key of a message is a unique identifier of the message's data. Message store providers furnish a message's PR_SEARCH_KEY property at message creation time. The search key of an address book entry is computed from its address type (PR_ADDRTYPE (PidTagAddressType)) and address (PR_EMAIL_ADDRESS (PidTagEmailAddress)). If the address book entry is writeable, its search key might not be available until the address type and address have been set by using the IMAPIProp::SetProps method and the entry has been saved by using the IMAPIProp::SaveChanges method. When these address properties change, it is possible for the corresponding search key not to be synchronized with the new values until the changes have been committed with a SaveChanges call.

The value of an object's record key can be the same as or different than the value of its search key, depending on the service provider. Some service providers use the same value for an object's search key, record key, and entry identifier. Other service providers assign unique values for each of its objects' identifiers.

See also

Concepts

MAPI Application Development


MAPI Folders

 Copy code hover
[image]

MAPI Folders
See also Send feedback

Published: July 16, 2012

Folders are MAPI objects that serve as the basic unit of organization for messages. Arranged hierarchically, folders can contain messages and other folders. Folders make it easier to locate and work with messages.

Folders implement the IMAPIFolder interface, which indirectly inherits from the IUnknown interface through the IMAPIContainer and IMAPIProp interfaces. Clients use IMAPIFolder to create, copy, and delete messages and folders, to retrieve and set message status, and to set or clear the read flag for a message. Although message store providers are required to support all the methods in IMAPIFolder, some methods introduce a level of complexity that message store providers might want to avoid. MAPI saves message store providers some work by implementing some of the more complex folder functionality in the IMAPISupport interface. Rather than implementing their own copy methods, for example, message store providers can call the copy methods in the support object and get the same results.

There are three kinds of folders:

  • Root folders.

  • Generic folders.

  • Search folders.

Every message store has at least a root folder. The root folder appears at the top of the hierarchy and contains messages and other folders. Root folders cannot be moved, copied, renamed, or deleted. There is only one root folder for each message store.

Most other folders are generic folders. Like root folders, generic folders contain messages and other folders. Unlike root folders, they can be moved, copied, renamed, and deleted. Generic folders can be created in the root folder or other generic folders. When a client creates a generic folder in another folder, the new folder is called a subfolder, or child folder. The folder in which the new folder is placed is referred to as the parent folder of the new folder. Generic folders that have the same parent folder are called sibling folders. Both sibling and non-sibling folders may or may not have unique names, depending on the message store provider. Message store providers that require sibling folders to have unique names return the error value MAPI_E_COLLISION when a client attempts to create two folders with the same name in the same parent.

A search folder contains links to messages that match a set of predefined criteria. Because search folders contain links rather than actual messages, they are in effect read-only. They cannot contain other folders or have messages or folders moved or copied into them. They cannot have new messages created in them; and they themselves cannot be moved, copied, or renamed. When a message is deleted from a search folder, it is actually deleted from the folder that contains the message.

Folder type is stored in the PR_FOLDER_TYPE (PidTagFolderType) property. Every folder has this property set to either FOLDER_GENERIC, FOLDER_ROOT, or FOLDER_SEARCH, depending on its type.

Every folder has one entry identifier and one record key. The entry identifier, PR_ENTRYID (PidTagEntryId), is used by clients and service providers to open the folder. The record key, PR_RECORD_KEY (PidTagRecordKey), is a binary value that is used to compare the folder with other folders.

A folder has other properties to identify related folders and the message store. The following properties are required:

  • PR_PARENT_ENTRYID (PidTagParentEntryId)

  • PR_STORE_ENTRYID (PidTagStoreEntryId)

  • PR_STORE_RECORD_KEY (PidTagStoreRecordKey)

Some folders support the PR_ACCESS (PidTagAccess) property which describes the type of operations a user can perform. For example, one of the valid settings for PR_ACCESS is MAPI_ACCESS_DELETE, which indicates that the folder can be removed. Another setting, MAPI_ACCESS_MODIFY, indicates that the folder should be modifiable.

For a complete list of required folder properties, see the IMAPIFolder interface.

See also

Concepts

MAPI Application Development


IPM Subtree

 Copy code hover
[image]

IPM Subtree
See also Send feedback

Published: July 16, 2012

MAPI creates a tree of folders beneath the root folder of a message store for all clients that send messages to and receive messages from human, rather than computer, recipients. Messages exchanged between human recipients are known as interpersonal messages, and this tree is known as the interpersonal message, or IPM, subtree.

An IPM subtree for a delivery store consists of at least the following folders:

  • Inbox

  • Outbox

  • Sent Items

  • Deleted Items

These are the default names and roles for each of these folders; a client can specify its own names if the default names are not appropriate. MAPI assigns default names and associations for these folders to keep messages from inadvertently disappearing if a client neglects to establish receiving folders for messages.

In a Microsoft Office Outlook context, an IPM subtree consists of additional default folders for Calendar, Contacts, Tasks, Notes, and Journal.

The Inbox typically holds incoming messages, and the Outbox holds outgoing messages (that is, messages waiting to be sent). The Sent Items folder holds a copy of each sent message if the client has set the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property to the entry identifier of this folder. The Deleted Items folder contains messages marked for removal.

See also

Concepts

MAPI Folders


MAPI Special Folders

 Copy code hover
[image]

MAPI Special Folders
See also Send feedback

Published: July 16, 2012

MAPI defines a few folders that are special because they serve predefined roles as default folders for certain types of messages. These special folders typically cannot be deleted, and they have special entry identifier properties.

There are eight special folders, some that are part of the interpersonal message (IPM) subtree. MAPI creates these folders before a client receives access to its message store, after which the client might be able to delete the folders, if necessary. Some message store providers allow deletion, while others do not. The following table describes these folders.

MAPI Folders
Folder | Description
Outbox folder | Contains outgoing IPM messages.
Deleted Items folder | Contains IPM messages that are marked for deletion.
Sent Items folder | Contains IPM messages that have been sent.
IPM root folder | Contains folders for managing IPM messages.
Receive folder | Contains incoming messages for a particular message class.
Search-results root folder | Contains folders for managing search results.
Common-views root folder | Contains folders for managing views for the message store.
Personal-views root folder | Contains folders for managing views for a particular user.

The first four folders relate to the IPM subtree, a tree of folders that MAPI creates when a message store is initialized. Default message stores for interactive messaging clients always include the IPM folder subtree and the other special folders in their folder hierarchy. Non-default message stores are required only to support the search-results root folder, the IPM subtree root folder, the Deleted Items folder, and the receive folder. To ensure that the IPM subtree folders exist and are valid, clients can call the HrValidateIPMSubtree function. HrValidateIPMSubtree checks the folders and recreates them if there is a problem.

The root folders for search results, common views, and personal views are not part of the IPM subtree; these folders are created in the root folder for the message store. The search-results root folder contains folders that support contents tables with messages that satisfy a set of search criteria. Although clients are allowed to create search-results folders in any folder, most clients designate a single root folder to be the parent of all the search-results folders created during the session.

The common-views and personal-views root folders contain messages that describe views, or preferred ways of presenting message and folder data. The common-views root folder contains views that clients can use with any folder in the message store; the personal-views folder contains views that have been defined by a particular user for a particular folder or folders.

Clients that work with IPM messages should create all folders and messages under the IPM subtree root folder, rather than the root folder of the message store. This gives non-IPM clients — the clients that deal with messages exchanged between computers or between humans and computers — an easy way to hide their messages from IPM clients.

MAPI assigns special entry identifier properties for these special folders. For a list of the special folder entry identifiers, see Opening a Message Store Folder.

Outlook Special Folders

Outlook special folders are identified by their entry IDs that are stored in the Inbox folder and the root folder for the message store.

Folder | The property to set
Calendar | PR_IPM_APPOINTMENT_ENTRYID (PidTagIpmAppointmentEntryId)
Contacts | PR_IPM_CONTACT_ENTRYID (PidTagIpmContactEntryId)
Journal | PR_IPM_JOURNAL_ENTRYID (PidTagIpmJournalEntryId)
Notes | PR_IPM_NOTE_ENTRYID (PidTagIpmNoteEntryId)
Tasks | PR_IPM_TASK_ENTRYID (PidTagIpmTaskEntryId)
Drafts | PR_IPM_DRAFTS_ENTRYID (PidTagIpmDraftsEntryId)

See also

Concepts

MAPI Folders


MAPI Receive Folders

 Copy code hover
[image]

MAPI Receive Folders
See also Send feedback

Published: July 16, 2012

A receive folder holds inbound messages of a particular message class. Receive folder associations can be established by clients, by the message store provider, or by MAPI. MAPI has two default receive folders: the root folder of the message store, and the Inbox folder of the interpersonal message (IPM) subtree. The root folder of the message store is the default receive folder for all interprocess communication (IPC) messages.

The Inbox folder is created by MAPI for every new message store and acts as the default receive folder for the following message classes:

  • The IPM message class.

  • The report message class.

  • An empty, or missing, class.

All report messages, even those sent in response to an IPC message, are placed in the Inbox folder. IPC client applications that process their own reports must explicitly add a receive folder for the particular class of report. For example, if a client expects to receive messages with the class IPC.Paper.Order, it should call the IMsgStore::SetReceiveFolder method to establish a receive folder for reports with the class Report.IPC.Paper.Order.

Receive folder associations are based on the hierarchical organization of message classes. Clients can explicitly establish an association between a receive folder and a message class or use the MAPI default receive folders. Typically, clients designate one folder to receive messages for a base class and all of its subclasses. For example, a typical client would establish an association for messages with the class MyClass. Then if the client received messages with classes MyClass.Home or MyClass.Home.Kitchen.Computer, these messages would go to the receive folder for the base class, MyClass.

There are three message store methods that clients use to work with receive folders:

  • IMsgStore::GetReceiveFolderTable

  • IMsgStore::GetReceiveFolder

  • IMsgStore::SetReceiveFolder

The receive folder table is a listing of information about all of the receive folders established for a message store. Its required column set includes the message class, record key, and entry identifier.

To retrieve a receive folder for a particular message class, clients pass the message class string to the IMsgStore::GetReceiveFolder method. The message store provider returns an entry identifier for the corresponding folder. To implement GetReceiveFolder, a message store provider should use an algorithm that selects the folder whose associated message class matches the longest possible prefix of the specified message class. For example, assume the message store has the following associations between receive folders and message classes in its receive folder table:

  • IPM messages are placed in the Inbox folder.

  • IPM.Note.Sample messages are placed in the Samples folder.

The following table shows how messages with various classes would be routed to the appropriate receive folder.

Inbound message class | Receive folder
IPM.Note.Sample.Simple | Samples folder
IPM.Note | Inbox folder
IPM.Timecard | Inbox folder
IPM.Note.Sample.Simple.Totally | Samples folder

Clients call the SetReceiveFolder method to make an explicit association between a particular message class and receive folder. When a message is delivered to an empty message class, MAPI places the message in the receive folder that is defined for a prefix of the empty class. For example, if your client has a receive folder established for messages with class IPM and a message with class IPM.Note.Test is delivered, this message will be placed in the receive folder for the IPM message class.

In calling SetReceiveFolder, clients typically pass a message class string and the entry identifier of the new receive folder. However, clients can pass in NULL for one or both of these parameters. The following table describes the behavior that results from specifying NULL for the message class and entry identifier parameters.

SetReceiveFolder parameter

Resulting behavior

Entry identifier set to NULL

The message store deletes the association between the specified message class and its existing receive folder. A new receive folder is not established.

Subsequent calls to GetReceiveFolder with this message class will return the receive folder for a prefix of the message class; for new message stores, GetReceiveFolder will return the Inbox in the IPM subtree.

Message class set to NULL

The message store changes the association for the empty message class to the indicated folder. Incoming messages whose class is otherwise unrecognized will go to this folder.

Entry identifier and message class set to NULL

The message store deletes the class/folder association for the empty message class. You should not set both parameters to NULL, because it typically results in inbound messages being placed in the root folder of the message store, a folder that is invisible to the client.

Although a message's class should never be empty, an empty message class can occur. It is the message store's responsibility to assign the message class to IPM for new outbound messages that have an empty class; it is the transport provider's responsibility to assign IPM.Note as the class for inbound messages that have any empty class.

See also

Concepts

MAPI Folders


MAPI Search Folders

 Copy code hover
[image]

MAPI Search Folders
See also Send feedback

Published: July 16, 2012

A search-results folder holds links to messages in generic folders rather than the actual messages. Clients create a search-results folder by calling the IMAPIFolder::CreateFolder method with FOLDER_SEARCH as the ulFolderType parameter. Clients fill a search-results folder by setting up and applying search criteria — rules that filter out messages with particular characteristics. Search criteria are set up with the IMAPIContainer::SetSearchCriteria method. Clients build one or more SRestriction structures to represent the search criteria to be applied and pass them to SetSearchCriteria. SetSearchCriteria also specifies a list of folders that indicate the search domain and a set of flags that control how the search is performed.

SetSearchCriteria identifies the messages that match the specified restriction. The selected messages (the ones that satisfy the criteria) are displayed as links in the search-results folder. When the client calls the IMAPIContainer::GetContentsTable method to access the contents table of the search-results folder, the selected messages are displayed in the table. Contents tables for search-results folders contain the same columns as contents tables for generic folders. However, for search-results folders, the PR_PARENT_ENTRYID (PidTagParentEntryId) property specifies the entry identifier of the folder where the linked message resides. Search-results folders are not considered parent folders.

Search-results folders have the following limits:

  • The only way that the contents of a search-results folder can be modified is through a call to SetSearchCriteria. For more information about the implementation of SetSearchCriteria, see Knowledge Base article 260322: How To Search Folders with the SetSearchCriteria Method.

  • Messages cannot be moved or copied into search-results folders.

  • Search-results folders cannot contain subfolders.

  • Clients cannot make a search-results folder the subject of a search.

It is possible, however, to modify the properties of a search-results folder and use it to delete a message. When a message is deleted from a search-results folder, it is actually deleted from the real folder. However, deleting the search-results folder itself has no impact on the messages inside; they remain in their generic folders.

See also

Concepts

MAPI Folders


MAPI Hidden Folders

 Copy code hover
[image]

MAPI Hidden Folders
See also Send feedback

Published: July 16, 2012

Hidden folders are generic folders that clients create in the root folder of the message store, rather than in the root folder of an interpersonal message (IPM) subtree. Because these folders are not placed in an IPM subtree, they are generally hidden from the user's view by the message store provider. Hidden folders typically contain information that is relevant to the message store but irrelevant to the user. Clients create hidden folders to store, for example, additional information to be saved with the rest of the folder hierarchy.

MAPI expects all clients to be able to display, create, modify, and delete folders in an IPM subtree. Support for working with folders in other trees is considered optional. However, all message stores that can be used as the default store and that can send and receive messages should fully support hidden folders.

See also

Concepts

MAPI Folders


MAPI View Folders

 Copy code hover
[image]

MAPI View Folders
See also Send feedback

Published: July 16, 2012

View folders are root folders that contain associated information to define alternative display layouts for the contents of interpersonal message (IPM) folders. View folders reside under the root for the message store and, therefore, are not visible in the typical client application. Not every message store includes view folders; only message stores that are configured to work as the default message store for the session must include them.

MAPI supports two view folders:

  • Common — The common view folder contains views that are standard for the message store and can be used by any user of a client that accesses the message store. The entry identifier for the common view folder is stored in the store's PR_COMMON_VIEWS_ENTRYID (PidTagCommonViewsEntryId) property.

  • Personal — The personal view folder contains views that are defined by a particular user. MAPI defines the PR_VIEWS_ENTRYID (PidTagViewsEntryId) property for holding the entry identifier of the personal view folder. Using personal views, for example, one user could look at a group of messages sorted by sender, listing only the message subject and receipt date; another user could look at the same group sorted by date, listing the subject, sender, and message size.

See also

Concepts

MAPI Folders


MAPI Messages

 Copy code hover
[image]

MAPI Messages
See also Send feedback

Published: July 16, 2012

Messages are MAPI objects that are transmitted from one client application to another through the MAPI spooler and service providers by way of a messaging system. Nearly every component in MAPI works with messages. Clients let users create, save, send, and delete messages in addition to copy and move them from one folder to another. Message store providers are responsible for message management and for delivering messages to the MAPI spooler or a transport provider. The MAPI spooler moves messages to an appropriate transport provider, whereas transport providers handle the delivery and receipt of messages to and from a messaging system and set recipient and message option properties. Address book providers work indirectly with messages, supporting properties that describe message recipients.

Messages are stored in folders throughout a message store, typically folders created in the interpersonal message (IPM) root folder. Messages are usually stored at the same level as the standard IPM Inbox, Sent Items, Deleted Items, and Outbox folders, or at lower levels in the hierarchy. However, messages can also be stored outside the IPM subtree.

Messages created in the standard IPM subtree have standard contents (that is, contents that are visible to the user of a client application). Notes and reports are examples of messages that have standard contents. Messages can also be created with associated contents, or contents that are not visible in the typical client. Folders support two different contents tables to hold the different types of messages: a standard contents table for standard messages, and an associated contents table for associated messages. Because MAPI does not set standards for the content of associated messages, they can contain arbitrary information.

A message can have additional data — in the form of a file, another message, or an OLE object — associated with it. This additional data, which is called an attachment, appears either as an icon or, for an RTF message, as a metafile in the message text. A message can have zero, one, or many attachments. Attachments are always transmitted with the message.

A message that is transmitted has one or more recipients (addresses that are associated with a particular messaging system). Some recipients are entries in a container that belongs to an address book provider in the current profile; other recipients are created only to transmit the message. Because recipients and attachments must be accessed through the message with which they are associated, a message's recipients and attachments are known as its subobjects.

Message store providers support messages, attachments, and recipients through methods in three interfaces:

Interface | Description
IMessage | Manages attachments and recipients, sends messages, sets read status.
IMAPIFolder | Creates, copies, and moves messages and subfolders and manages message status.
IAttach | Manages attachment properties.

See also

Concepts

MAPI Application Development


MAPI Message Classes

 Copy code hover
[image]

MAPI Message Classes
See also Send feedback

Published: July 16, 2012

Every message has a message class property, PR_MESSAGE_CLASS (PidTagMessageClass), which identifies the type, purpose, or content of the message. PR_MESSAGE_CLASS is a required property on all new messages. A message's class determines the form that is used to present the message to the user and the folder for placing incoming messages.

Message classes are case-sensitive character strings that contain ASCII characters 32 through 127 and are delimited by periods, but they cannot end with a period. Each string represents a level of subclassing, and there is no limit to the number of levels allowed.

For example, most messages that client applications send and receive fall into the IPM message class, a broad category that describes all interpersonal messages (that is, messages that are meant to be read by a human user, rather than programmatically by a computer). Message store providers more precisely describe an IPM message by creating an IPM subclass. The IPM subclass inherits the properties of the IPM message class. Subclasses of the IPM class are named by concatenating other character strings onto the IPM identifier, such as IPM.Note to describe a note message and IPM.Contact to describe a contact message.

To handle the display and management of IPM messages, clients can use a standard form that MAPI provides. To handle the display and management of new message classes, you as a client application developer have two options:

  1. You can create a new form by using the set of MAPI-defined form interfaces that a standard client can use.

  2. You can write your own client by implementing a complete, standalone application.

Although clients should set the PR_MESSAGE_CLASS property for every outgoing message to a subclass of either IPM or IPC, the message store provider has the ultimate responsibility for setting it. Therefore, if a client sends a message without setting its message class, the message store provider sets it to the appropriate default value for the appropriate type of client. The default message class for interpersonal messaging clients is IPM; the default message class for interprocess communication clients is IPC.

Message classes have a length restriction of 255 characters. However, message classes should not exceed 127 characters to support the message classes used in reports. Report message classes are based on the class of the original message, with two additions: a prefix and a suffix. The prefix REPORT indicates that the message is a report, and the suffix indicates the type of report: DR (delivery report), NDR (nondelivery report), IPNRN (read report), or IPNNRN (nonread report). Note that these length restrictions are given in characters; on platforms that use a double-byte character set, the actual byte count might be higher.

Message store providers should return MAPI_E_INVALID_PARAMETER from their IMAPIProp::SetProps method implementations when a client attempts to assign a string that exceeds the allowable limit for their message class.

See also

Concepts

MAPI Messages


MAPI Report Messages

 Copy code hover
[image]

MAPI Report Messages
See also Send feedback

Published: July 16, 2012

Report messages present status information about a message to its sender.

There are two general types of report messages:

  • Read status reports.

  • Delivery status reports.

Read Status Reports

Read status reports are initiated by message store providers through a call to the IMAPISupport::ReadReceipt method and are sent to the recipient represented by the entry identifier in the PR_REPORT_ENTRYID (PidTagReportEntryId) property. Read status reports are not generated automatically; client applications that want to receive them must explicitly request them.

A read report indicates that the read flag of a message has been set, which can occur when the message is opened, printed, moved, or copied. Whether or not a message store provider generates a read report in response to a move or copy operation depends on where the message is going. If it is being moved or copied to another message store, a read report will most likely always be sent. If it is being moved or copied in the current message store, a read report might or might not be sent.

A nonread report indicates that the read flag of a message is not set and that the message was not opened either before being placed in the Deleted Items folder or before the expiration of a time limit. Clients can call the IMessage::SetReadFlag or IMAPIFolder::SetReadFlags method to set or clear a message's read flag.

Delivery Status Reports

Delivery status is reflected in a delivery report, which is sent when a message has reached its intended recipient, and in a nondelivery report, which is sent when a message could not reach a recipient. Delivery status reports are sent to the recipient represented by the entry identifier in the PR_REPORT_ENTRYID property or to the sender if this property is not present.

Delivery reports are sent by request only and do not include the original message. Nondelivery reports are sent automatically unless a request is made to suppress them. Nondelivery reports include the original message as an attachment to enable the report's recipient to resend the message in case whatever blocked the delivery is no longer a problem. The attached message resembles the original as it existed when the IMessage::SubmitMessage method was called to send it initially.

One or more delivery status reports are generated by transport providers when they call the IMAPISupport::StatusRecips method. Transport providers compose a list of recipients for a message. Whether or not a recipient receives a report and the type of report that is generated depends on the following:

  • Delivery reports go to recipients that set the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) property to TRUE before the message was placed in the message store.

  • Nondelivery reports go to recipients that did not set the PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED (PidTagOriginatorNonDeliveryReportRequested) property to FALSE.

Almost all of the information necessary to display a nondelivery report is contained in the recipient table of the attached message. A few properties are from the report itself. For delivery reports, the necessary information is contained in the recipient table of the report and in a few report properties.

Reports are messages with distinct message classes, based on the class of the sent message. Most service providers use a naming convention whereby the message class is composed of several parts separated by periods. The first part is "Report" and the last part is a constant that represents the report type. The middle part is reserved for the class of the sent message. For example, because a delivery report uses the constant DR, the message class for a delivery report about an IPM.Note message would be Report.IPM.Note.DR.

The following table shows the constants that represent the types of reports.

Report type | Constant used in message class
Read | IPNRN
Nonread | IPNNRN
Delivery | DR
Nondelivery | NDR

Interactive clients can display report messages by using standard forms provided by MAPI, or custom forms that have been registered with the form manager for the report's message class. Clients that receive a nondelivery report for an IPM.Note message, for example, can display the standard MAPI form that presents a list of the failed recipients and a suggested reason for the failure. The form also enables the user to resend the message, if desired.

See also

Concepts

MAPI Messages


Message Properties Overview

 Copy code hover
[image]

Message Properties Overview
See also Send feedback

Published: July 16, 2012

MAPI divides message properties into three types:

  • Message content properties.

  • Message transmission, or envelope, properties.

  • Message recipient properties.

Message content properties describe the text of a message. Every message class has its own set of content properties. MAPI defines content properties for note and report messages; it is up to the clients and message store providers that handle these classes of messages to set the properties appropriately for their implementations. PR_BODY (PidTagBody) and PR_RTF_COMPRESSED (PidTagRtfCompressed) are examples of content properties for note messages. PR_BODY contains the unformatted contents of a note, while PR_RTF_COMPRESSED contains the compressed version of a note's formatted contents. For more information about property identifier ranges, see Property Identifier Ranges.

For new message classes, clients can define content-specific properties in one of two ways:

  • By using property identifiers in the custom message class content properties range: 0x6800 through 0x7BFF.

  • By using named properties that have identifiers that fall in the 0x8000 through 0xFFFE range.

The identifier range for custom message class content properties is available to any client that creates a custom message class. Therefore, one property identifier in this range can be used for multiple message classes. Users of properties in this range cannot make assumptions as to the behavior of the properties.

For named properties, clients create a name that specifies a property set and either a character string or a numeric value for each new property. Clients then associate the property with an identifier in the named property range. Users of named properties access them by name or identifier through the IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs methods.

Envelope properties provide information that is used to transmit a message from one recipient to another. As with message content properties, it is possible for clients or service providers to define their own envelope properties to supplement those that MAPI defines. Clients and transport providers set the envelope properties that MAPI defines based on the definition that MAPI provides. Transport providers that implement special features can define their own envelope properties to expose those features to clients. MAPI sets aside a range of property identifiers that can be used for these special provider-defined properties. Transport providers typically implement a special property page to display these properties and enable clients to change them. PR_SUBJECT (PidTagSubject) and PR_MESSAGE_CLASS (PidTagMessageClass) are examples of envelope properties. For more information, see Property Identifier Ranges.

Recipient properties describe the destination for a sent message. A recipient can be a messaging user, distribution list, or a computer. Recipient properties are defined by MAPI and set by service providers. Some recipient properties are supported by address book providers for their messaging user and distribution list objects; other recipient properties are supported by clients, message store providers, or transport providers. For example, all recipients require an address and an address type; these are properties maintained by an address book provider when the recipient is stored in one of its containers. Recipients also have a type, PR_RECIPIENT_TYPE (PidTagRecipientType), which identifies a recipient as either a primary, carbon copy, or blind carbon copy recipient.

Many message properties are optional, meaning that clients cannot expect them to be available or set to valid values. Some message properties are required but available only when a message is in a particular state. For example, a newly created message is not required to have an entry identifier until after the message has been saved, and it is not required to have a message class until the message is ready to be submitted. Clients should always check the results of their IMAPIProp::GetProps and IMAPIProp::OpenProperty calls and have default values ready as a backup in case a requested property is unavailable.

Most message properties that service providers set are read-only to clients.

See also

Concepts

MAPI Messages


Required Properties for All Messages

 Copy code hover
[image]

Required Properties for All Messages
Send feedback

Published: July 16, 2012

The following table describes properties that clients can expect to set or see supported on messages of all classes.

Property | Description
PR_CREATION_TIMEPidTagCreationTime Canonical Property (PidTagCreationTime) | Set by message store providers on outgoing messages.
PR_DISPLAY_BCC (PidTagDisplayBcc) PR_DISPLAY_CC (PidTagDisplayCc) PR_DISPLAY_TO (PidTagDisplayTo) | Set by message store providers on outgoing messages.
PR_ENTRYID (PidTagEntryId) | Set by message store providers on outgoing messages.
PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime) | Set by message store providers on outgoing messages.
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Set by message store providers on outgoing messages.
PR_MESSAGE_CLASS (PidTagMessageClass) | Can be set by clients on outgoing messages; must be set by message store providers if not set by clients.
PR_MESSAGE_FLAGS (PidTagMessageFlags) | Set by clients on outgoing messages before they are saved and message store providers after they are saved.
PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) | Set by message store providers on outgoing messages.
PR_MESSAGE_SIZE (PidTagMessageSize) | Set by message store providers on outgoing messages.
PR_MESSAGE_CC_ME (PidTagMessageCcMe) PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe) PR_MESSAGE_TO_ME (PidTagMessageToMe) | Set by transport providers on incoming messages.
PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) | Set by message store providers on outgoing messages
PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY (PidTagOriginatorAndDistributionListExpansionHistory) PR_ORIGINATOR_CERTIFICATE (PidTagOriginatorCertificate) PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED (PidTagOriginatorNonDeliveryReportRequested) PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT (PidTagOriginatorRequestedAlternateRecipient) PR_ORIGINATOR_RETURN_ADDRESS (PidTagOriginatorReturnAddress) | Set by transport providers on outgoing messages.
PR_PARENT_ENTRYID (PidTagParentEntryId) PR_PARENT_DISPLAY (PidTagParentDisplay) | Set by message store providers on outgoing messages.
PR_RCVD_REPRESENTING_ADDRTYPE (PidTagReceivedRepresentingAddressType) PR_RCVD_REPRESENTING_EMAIL_ADDRESS (PidTagReceivedRepresentingEmailAddress) PR_RCVD_REPRESENTING_ENTRYID (PidTagReceivedRepresentingEntryId) PR_RCVD_REPRESENTING_NAME (PidTagReceivedRepresentingName) PR_RCVD_REPRESENTING_SEARCH_KEY (PidTagReceivedRepresentingSearchKey) | Set by transport providers on incoming messages.
PR_RECEIVED_BY_ADDRTYPE (PidTagReceivedByAddressType) PR_RECEIVED_BY_EMAIL_ADDRESS (PidTagReceivedByEmailAddress) PR_RECEIVED_BY_ENTRYID (PidTagReceivedByEntryId) PR_RECEIVED_BY_NAME (PidTagReceivedByName) PR_RECEIVED_BY_SEARCH_KEY (PidTagReceivedBySearchKey) | Set by transport providers on incoming messages.
PR_RECIPIENT_TYPE (PidTagRecipientType) | Set by message store providers on incoming messages.
PR_RECORD_KEY (PidTagRecordKey) | Set by message store providers on outgoing messages.
PR_SEARCH_KEY (PidTagSearchKey) | Set by message store providers on outgoing messages.
PR_SENDER_ADDRTYPE (PidTagSenderAddressType) PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress) PR_SENDER_ENTRYID (PidTagSenderEntryId) PR_SENDER_NAME (PidTagSenderName) PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) | Clients can set these properties on outgoing messages, but transport providers must set them.
PR_SENT_REPRESENTING_ADDRTYPE (PidTagSentRepresentingAddressType) PR_SENT_REPRESENTING_EMAIL_ADDRESS (PidTagSentRepresentingEmailAddress) PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId) PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) PR_SENT_REPRESENTING_SEARCH_KEY (PidTagSentRepresentingSearchKey) | Clients can set these properties on outgoing messages, but transport providers must set them.
PR_STORE_ENTRYID (PidTagStoreEntryId) PR_STORE_RECORD_KEY (PidTagStoreRecordKey) | Set by message store providers on outgoing messages.


Required Report Message Properties

 Copy code hover
[image]

Required Report Message Properties
Send feedback

Published: July 16, 2012

The following table describes properties that clients can expect to see supported on report messages.

Property | Description
PR_ORIGINAL_DISPLAY_BCC (PidTagOriginalDisplayBcc) PR_ORIGINAL_DISPLAY_CC (PidTagOriginalDisplayCc) PR_ORIGINAL_DISPLAY_TO (PidTagOriginalDisplayTo) | Set by creator of report, usually MAPI.
PR_ORIGINAL_SUBJECT (PidTagOriginalSubject) | Set by creator of report, usually MAPI.
PR_ORIGINAL_SUBMIT_TIME (PidTagOriginalSubmitTime) | Set by creator of report, usually MAPI.
PR_CONVERSATION_INDEX (PidTagConversationIndex) PR_CONVERSATION_TOPIC (PidTagConversationTopic) | Set by creator of report, usually MAPI.
PR_MESSAGE_CLASS (PidTagMessageClass) | Set by creator of report, usually MAPI.
PR_REPORT_TEXT (PidTagReportText) | Set by creator of report, usually MAPI.
PR_BODY (PidTagBody) | Set by client before report is displayed.
PR_REPORT_TIME (PidTagReportTime) | Set by creator of report, usually MAPI.
PR_ORIGINAL_DELIVERY_TIME (PidTagOriginalDeliveryTime) | Set by creator of report, usually MAPI. For read status reports only.
PR_SUBJECT (PidTagSubject) | Set by client before report is displayed.
PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) | Set by creator of report, usually MAPI.
PR_REPORT_TAG (PidTagReportTag) | Set by creator of report, usually MAPI.
PR_SEARCH_KEY (PidTagSearchKey) | Set by creator of report, usually MAPI.
PR_SENDER_ADDRTYPE (PidTagSenderAddressType) PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress) PR_SENDER_ENTRYID (PidTagSenderEntryId) PR_SENDER_NAME (PidTagSenderName) PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) | Set by creator of report, usually MAPI.


Optional Report Message Properties

 Copy code hover
[image]

Optional Report Message Properties
Send feedback

Published: July 16, 2012

The following properties sometimes appear with report messages:

Table Title
Property | Description
PR_ORIGINAL_AUTHOR_ADDRTYPE (PidTagOriginalAuthorAddressType) | Contains the address type of the author of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS (PidTagOriginalAuthorEmailAddress) | Contains the e-mail address of the author of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_AUTHOR_ENTRYID (PidTagOriginalAuthorEntryId) | Contains the entry identifier of the author of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_AUTHOR_NAME (PidTagOriginalAuthorName) | Contains the display name of the author of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_AUTHOR_SEARCH_KEY (PidTagOriginalAuthorSearchKey) | Contains the search key of the author of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE (PidTagOriginalSentRepresentingAddressType) | Contains the address type of the messaging user on whose behalf the original message was sent.
PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS (PidTagOriginalSentRepresentingEmailAddress) | Contains the e-mail address of the messaging user on whose behalf the original message was sent.
PR_ORIGINAL_SENT_REPRESENTING_ENTRYID (PidTagOriginalSentRepresentingEntryId) | Contains the entry identifier of the messaging user on whose behalf the original message was sent.
PR_ORIGINAL_SENT_REPRESENTING_NAME (PidTagOriginalSentRepresentingName) | Contains the display name of the messaging user on whose behalf the original message was sent.
PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY (PidTagOriginalSentRepresentingSearchKey) | Contains the search key of the messaging user on whose behalf the original message was sent.
PR_ORIGINAL_SENDER_ADDRTYPE (PidTagOriginalSenderAddressType) | Contains the address type of the sender of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_SENDER_EMAIL_ADDRESS (PidTagOriginalSenderEmailAddress) | Contains the e-mail address of the sender of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_SENDER_ENTRYID (PidTagOriginalSenderEntryId) | Contains the entry identifier of the sender of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_SENDER_NAME (PidTagOriginalSenderName) | Contains the display name of the sender of the first version of a message, that is, the message before it is forwarded or replied to.
PR_ORIGINAL_SENDER_SEARCH_KEY (PidTagOriginalSenderSearchKey) | Contains the search key for the sender of the first version of a message, that is, the message before it is forwarded or replied to.


Recipient Properties for All Messages

 Copy code hover
[image]

Recipient Properties for All Messages
Send feedback

Published: July 16, 2012

The following properties are typically present for all message recipients. PR_EMAIL_ADDRESS and PR_SEARCH_KEY are optional; all of the other properties are required.

Table Title
Property | Description
PR_ADDRTYPE (PidTagAddressType) | Contains the messaging user's e-mail address type, such as SMTP.
PR_DISPLAY_NAME (PidTagDisplayName) | Contains the display name for a given MAPI object.
PR_DISPLAY_TYPE (PidTagDisplayType) | Contains a value used to associate an icon with a particular row of a table.
PR_EMAIL_ADDRESS (PidTagEmailAddress) | Contains the messaging user's e-mail address.
PR_ENTRYID (PidTagEntryId) | Contains a MAPI entry identifier used to open and edit properties of a particular MAPI object.
PR_OBJECT_TYPE (PidTagObjectType) | Contains the type of an object.
PR_SEARCH_KEY (PidTagSearchKey) | Contains a binary-comparable key that identifies correlated objects for a search.


Recipient Properties for Delivery Status Reports

 Copy code hover
[image]

Recipient Properties for Delivery Status Reports
Send feedback

Published: July 16, 2012

The following properties are present for delivery status reports for recipients. PR_DELIVER_TIME (PidTagDeliverTime) is not used on non-delivery reports. PR_NDR_DIAG_CODE (PidTagNonDeliveryReportDiagCode) and PR_NDR_REASON_CODE (PidTagNonDeliveryReportReasonCode) are used only on non-delivery reports.

Table Title
Property | Decription
PR_DELIVER_TIME (PidTagDeliverTime) | Contains the date and time at which the original message was delivered.
PR_DISPLAY_NAME (PidTagDisplayName) | Contains the display name for a given MAPI object.
PR_ENTRYID (PidTagEntryId) | Contains a MAPI entry identifier used to open and edit properties of a particular MAPI object.
PR_NDR_DIAG_CODE (PidTagNonDeliveryReportDiagCode) | Contains a diagnostic code that forms part of a non-delivery report.
PR_MESSAGE_CLASS (PidTagMessageClass) | Contains a text string that identifies the sender-defined message class, such as IPM.Note.
PR_NDR_REASON_CODE (PidTagNonDeliveryReportReasonCode) | Contains an encoded reason for non-delivery that forms part of a non-delivery report.
PR_ORIGINAL_DISPLAY_NAME (PidTagOriginalDisplayName) | Contains the original display name for an entry copied from an address book to a personal address book or other writable address book.
PR_ORIGINAL_ENTRYID (PidTagOriginalEntryId) | Contains the original entry identifier for an entry copied from an address book to a personal address book or other writeable address book.
PR_ORIGINAL_SEARCH_KEY (PidTagOriginalSearchKey) | Contains the original search key for an entry copied from an address book to a personal address book or other writeable address book.
PR_RECIPIENT_TYPE (PidTagRecipientType) | Contains the recipient type for a message recipient.
PR_REPORT_TEXT (PidTagReportText) | Contains optional text for a report generated by the messaging system.
PR_REPORT_TIME (PidTagReportTime) | Contains the date and time when the messaging system generated a report.
PR_SEARCH_KEY (PidTagSearchKey) | Contains a binary-comparable key that identifies correlated objects for a search.
PR_DISPLAY_TYPE (PidTagDisplayType) | Contains a value used to associate an icon with a particular row of a table.
PR_OBJECT_TYPE (PidTagObjectType) | Contains the type of an object.


Outlook Items and Fields

 Copy code hover
[image]

Outlook Items and Fields
See also Send feedback

Published: July 16, 2012

Microsoft Outlook provides item types that are specialized for their functionality (for example, mail items, appointments, contacts, tasks, and notes). Outlook provides standard fields for each type of item, commonly referred to as built-in fields. Outlook also allows users to create custom fields, commonly referred to as user-defined fields. Each field is associated with a data type and a value. Examples of data types are Currency, Date/Time, Duration, Integer, Keywords, and Text. Users can define custom fields by using the Forms Designer in Outlook.

At the programmability level, each item is represented by an IMessage object. Each user-defined field is associated with a field definition and a value.

Field Definition

A field definition includes the name, data type, and other information about the field. For each item, Outlook stores the definitions of all user-defined fields in the PidLidPropertyDefinitionStream property of the corresponding IMessage object. The PidLidPropertyDefinitionStream property contains a binary stream known as PropertyDefinition that contains the field definitions. For more information about stream structures for field definitions, see Stream Structures.

Field Value

Each user-defined field of an item has a value that is stored in a corresponding named property. That named property is in the PS_PUBLIC_STRINGS property set, and has a Unicode character string as the property name. The data type of the property corresponds to the type of the field. If the property is not present in the IMessage object, Outlook assumes a reasonable default value for the property. For example, for a string type, Outlook assumes an empty string if the property is not present.

See also

Concepts

How to: Add a Definition for a New User-Defined Field
PropertyDefinition Stream Sample
Stream Structures
PropertyDefinition Stream Structure
FieldDefinition Stream Structure
SkipBlock Stream Structure
FirstSkipBlockContent Stream Structure
PackedAnsiString Stream Structure
PackedUnicodeString Stream Structure


How to: Add a Definition for a New User-Defined Field

 Copy code hover
[image]

How to: Add a Definition for a New User-Defined Field
See also Send feedback

Published: July 16, 2012

When you add a user-defined field to a Microsoft Outlook item, you add a field definition to the corresponding PropertyDefinition stream structure. Use the following procedure to add a new field definition to a PropertyDefinition stream structure.

To add a definition for a new user-defined field

  1. Copy the existing field definitions of the PropertyDefinition stream structure to a new field definitions array.

  2. If any existing field definitions are in the PropDefV1 format, convert them to the PropDefV2 format. For more information about field definition formats, see PropertyDefinition Stream Structure and FieldDefinition Stream Structure.

  3. Create a definition of the new user-defined field in the PropDefV2 format and add it to the array.

  4. Set the Version element of the PropertyDefinition stream structure as 0x0103, if the Version element has not been set to that value.

  5. Increment the FieldDefinitionCount element by 1.

  6. Store the array as the value of the FieldDefinitions element.

See also

Concepts

PropertyDefinition Stream Structure


PropertyDefinition Stream Sample

 Copy code hover
[image]

PropertyDefinition Stream Sample
See also Send feedback

Published: July 16, 2012

This topic describes an example of a PropertyDefinition stream. The stream contains a definition of a user-defined field, TextField1. The type is Text, and the definition is in the PropDefV2 format.

Data Dump

The following is a data dump of the stream as it would be displayed in a binary editor.

Stream offset | Data bytes | ASCII data
0000000000 | 03 01 01 00 00 00 45 00 00 00 08 00 00 00 00 00 | ???...E...?.....
0000000010 | 0A 00 54 00 65 00 78 00 74 00 46 00 69 00 65 00 | ?.T.e.x.t.F.i.e.
0000000020 | 6C 00 64 00 31 00 0A 54 65 78 74 46 69 65 6C 64 | l.d.1.?TextField
0000000030 | 31 00 00 00 00 00 00 00 00 15 00 00 00 0A 54 00 | 1........?...?T.
0000000040 | 65 00 78 00 74 00 46 00 69 00 65 00 6C 00 64 00 | e.x.t.F.i.e.l.d.
0000000050 | 31 00 00 00 00 00 | 1.....

The following is a parse of the sample data for the PropertyDefinition stream:

  • Version: Offset 0x0, 2 bytes: 0x0103 (PropDefV2).

  • FieldDefinitionCount: Offset 0x2, 4 bytes: 0x1 (1).

  • FieldDefinitions: Offset 0x6, array of 1 FieldDefinition stream.

    • Flags: Offset 0x6, 4 bytes: 0x45 (PDO_IS_CUSTOM|PDO_PRINT_SAVEAS|PDO_PRINT_SAVEAS_DEF).

    • VT: Offset 0xA, 2 bytes: 0x8 (VT_BSTR).

    • DispId: Offset 0xC, 4 bytes: 0x0 (0).

    • NmidNameLength: Offset 0x10, 2 bytes: 0xA (10).

    • NmidName: Offset 0x12, array of 10 WCHARs. Unicode string value: "TextField1".

    • NameANSI: Offset 0x26, PackedAnsiString stream.

      • Length: Offset 0x26, 1 byte: 0xA (10).

      • Characters: Offset 0x27, array of 10 CHARs. ANSI string value: "TextField1".

    • FormulaANSI: Offset 0x31, PackedAnsiString stream.

      • Length: Offset 0x31, 1 byte: 0x0 (0).

      • Characters: Offset 0x32, array of 0 CHARs. Empty ANSI string.

    • ValidationRuleANSI: Offset 0x32, PackedAnsiString stream.

      • Length: Offset 0x32, 1 byte: 0x0 (0).

      • Characters: Offset 0x33, array of 0 CHARs. Empty ANSI string.

    • ValidationTextANSI: Offset 0x33, PackedAnsiString stream.

      • Length: Offset 0x33, 1 byte: 0x0 (0).

      • Characters: Offset 0x34, array of 0 CHARs. Empty ANSI string.

    • ErrorANSI: Offset 0x34, PackedAnsiString stream.

      • Length: Offset 0x34, 1 byte: 0x0 (0).

      • Characters: Offset 0x35, array of 0 CHARs. Empty ANSI string.

    • InternalType: Offset 0x35, 4 bytes: 0x0 (iTypeString).

    • SkipBlocks: Offset 0x39, series of SkipBlock streams.

    • First SkipBlock

      • Size: Offset 0x39, 4 bytes: 0x15 (21).

      • Content: Offset 0x3D, array of 21 bytes. This is the first SkipBlock stream, so this array contains a FirstSkipBlockContent stream.

        • FieldName: Offset 0x3D, PackedUnicodeString stream.

          • Length: Offset 0x3D, 1 byte: 0xA (10).

          • Characters: Offset 0x3E, array of 10 WCHARs. Unicode string value: "TextField1".

    • Second SkipBlock

      • Size: Offset 0x52, 4 bytes: 0x0 (0). This is the terminating SkipBlock stream.

See also

Concepts

Outlook Items and Fields
Stream Structures
PropertyDefinition Stream Structure
FieldDefinition Stream Structure
SkipBlock Stream Structure
FirstSkipBlockContent Stream Structure
PackedAnsiString Stream Structure
PackedUnicodeString Stream Structure


FolderUserFields Stream Sample

 Copy code hover
[image]

FolderUserFields Stream Sample
See also Send feedback

Published: July 16, 2012

This topic describes an example of a FolderUserFields stream. The stream contains a definition of a user-defined field, TextField1. The type is Text, and the FolderUserFields stream contains both FolderUserFieldsAnsi and FolderUserFieldsUnicode parts. For more information see Folder Fields Stream Structures.

Data Dump

The following is a data dump of the stream as it would be displayed in a binary editor.

Stream offset | Data bytes | ASCII data
0000000000 | 02 00 00 00 01 00 00 00 0A 00 54 65 78 74 46 69 | ..........TextFi
0000000010 | 65 6C 64 31 29 03 02 00 00 00 00 00 C0 00 00 00 | eld1).......A...
0000000020 | 00 00 00 46 07 00 00 80 00 00 00 00 00 00 00 00 | ...F............
0000000030 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
0000000040 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
0000000050 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
0000000060 | 00 00 00 00 00 00 02 00 00 00 01 00 00 00 0A 00 | ................
0000000070 | 54 00 65 00 78 00 74 00 46 00 69 00 65 00 6C 00 | T.e.x.t.F.i.e.l.
0000000080 | 64 00 31 00 29 03 02 00 00 00 00 00 C0 00 00 00 | d.1.).......A...
0000000090 | 00 00 00 46 07 00 00 80 00 00 00 00 00 00 00 00 | ...F............
00000000A0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00000000B0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00000000C0 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
00000000D0 | 00 00 00 00 00 00 | ......

The following is a parse of the sample data for the FolderUserFields stream:

  • FolderUserFieldsAnsi: Offset 0x0.

    • FieldDefinitionCount: Offset 0x0, 4 bytes: 0x00000002 (2).

    • FieldDefinitions: Offset 0x4, array of 2 FolderFieldDefinitionA streams.

      First array element:

      • FieldType: Offset 0x4, 4 bytes: 0x00000001 (ftString).

      • FieldNameLength: Offset 0x8, 2 bytes: 0x000A (10)

      • FieldName: Offset 0xA, array of 10 CHARs. ANSI string value: "TextField1".

      • Common: Offset 0x14.

        • PropSetGuid: Offset 0x14, 16 bytes: {00020329-0000-0000-C000-000000000046} (PS_PUBLIC_STRINGS).

        • fcapm: Offset 0x24, 4 bytes: 0x80000007 (FCAPM_CAN_EDIT| FCAPM_CAN_SORT| FCAPM_CAN_GROUP|FCAPM_CAN_EDIT_IN_ITEM).

        • dwString: Offset 0x28, 4 bytes: 0x00000000.

        • dwBitmap: Offset 0x2C, 4 bytes: 0x00000000.

        • dwDisplay: Offset 0x30, 4 bytes: 0x00000000.

        • iFmt: Offset 0x34, 4 bytes: 0x00000000.

        • wszFormulaLength: Offset 0x38, 2 bytes: 0x0000 (0).

        • wszFormula: Offset 0x3A, array of 0 WCHARs. Empty string value.

      Second array element:

      • FieldType: Offset 0x3A, 4 bytes: 0x00000000 (ftNone).

      • FieldNameLength: Offset 0x3E, 2 bytes: 0x0000 (0).

      • FieldName: Offset 0x40, array of 0 CHARs. Empty string value.

      • Common: Offset 0x40.

        • PropSetGuid: Offset 0x40, 16 bytes: {00000000-0000-0000-0000-000000000000} (GUID_NULL).

        • fcapm: Offset 0x50, 4 bytes: 0x00000000 (0).

        • dwString: Offset 0x54, 4 bytes: 0x00000000.

        • dwBitmap: Offset 0x58, 4 bytes: 0x00000000.

        • dwDisplay: Offset 0x5C, 4 bytes: 0x00000000.

        • iFmt: Offset 0x60, 4 bytes: 0x00000000.

        • wszFormulaLength: Offset 0x64, 2 bytes: 0x0000 (0).

        • wszFormula: Offset 0x66, array of 0 WCHARs. Empty string value.

  • FolderUserFieldsUnicode: Offset 0x66.

    • FieldDefinitionCount: Offset 0x66, 4 bytes: 0x00000002 (2).

    • FieldDefinitions: Offset 0x6A, array of 2 FolderFieldDefinitionW streams.

      First array element:

      • FieldType: Offset 0x6A, 4 bytes: 0x00000001 (ftString).

      • FieldNameLength: Offset 0x6E, 2 bytes: 0x000A (10).

      • FieldName: Offset 0x70, array of 10 WCHARs. Unicode string value: "TextField1".

      • Common: Offset 0x84.

        • PropSetGuid: Offset 0x84, 16 bytes: {00020329-0000-0000-C000-000000000046} (PS_PUBLIC_STRINGS).

        • fcapm: Offset 0x94, 4 bytes: 0x80000007 (FCAPM_CAN_EDIT| FCAPM_CAN_SORT| FCAPM_CAN_GROUP|FCAPM_CAN_EDIT_IN_ITEM).

        • dwString: Offset 0x98, 4 bytes: 0x00000000.

        • dwBitmap: Offset 0x9C, 4 bytes: 0x00000000.

        • dwDisplay: Offset 0xA0, 4 bytes: 0x00000000.

        • iFmt: Offset 0xA4, 4 bytes: 0x00000000.

        • wszFormulaLength: Offset 0xA8, 2 bytes: 0x0000 (0).

        • wszFormula: Offset 0xAA, array of 0 WCHARs. Empty string value.

      Second array element:

      • FieldType: Offset 0xAA, 4 bytes: 0x00000000 (ftNone).

      • FieldNameLength: Offset 0xAE, 2 bytes: 0x0000 (0).

      • FieldName: Offset 0xB0, array of 0 WCHARs. Empty string value.

      • Common: Offset 0xB0.

        • PropSetGuid: Offset 0xB0, 16 bytes: {00000000-0000-0000-0000-000000000000} (GUID_NULL).

        • fcapm: Offset 0xC0, 4 bytes: 0x00000000 (0).

        • dwString: Offset 0xC4, 4 bytes: 0x00000000.

        • dwBitmap: Offset 0xC8, 4 bytes: 0x00000000.

        • dwDisplay: Offset 0xCC, 4 bytes: 0x00000000.

        • iFmt: Offset 0xD0, 4 bytes: 0x00000000.

        • wszFormulaLength: Offset 0xD4, 2 bytes: 0x0000 (0).

        • wszFormula: Offset 0xD6, array of 0 WCHARs. Empty string value.

See also

Concepts

Outlook Items and Fields
PropertyDefinition Stream Structure
FieldDefinition Stream Structure
SkipBlock Stream Structure
FirstSkipBlockContent Stream Structure
PackedAnsiString Stream Structure
PackedUnicodeString Stream Structure


Stream Structures

 Copy code hover
[image]

Stream Structures
See also Send feedback

Published: July 16, 2012

Definitions of user-defined fields of a Microsoft Outlook item are stored in the PidLidPropertyDefinitionStream property. The value of this property is a binary stream that contains definitions of user-defined fields and data-binding settings for built-in fields for the Outlook item. This section provides information about the structure of the binary stream, broken down in the following stream structures.

Note Note

The names of these stream structures (for example, PropertyDefinition, FieldDefinition, and SkipBlock) and their data elements are not technically part of the programming interface of the Messaging API (MAPI), and are provided here only for documentation purposes of the actual stream structures. Developers can label these stream structures and data elements in their applications as they choose.

  • PropertyDefinition Stream Structure

  • FieldDefinition Stream Structure

  • SkipBlock Stream Structure

  • FirstSkipBlockContent Stream Structure

  • PackedAnsiString Stream Structure

  • PackedUnicodeString Stream Structure

See also

Concepts

Outlook Items and Fields
How to: Add a Definition for a New User-Defined Field
PropertyDefinition Stream Sample


PropertyDefinition Stream Structure

 Copy code hover
[image]

PropertyDefinition Stream Structure
See also Send feedback

Published: July 16, 2012

A PropertyDefinition stream structure is an array of FieldDefinition stream structures that contain definitions for all user-defined fields in a Microsoft Outlook item, and data-binding settings for some built-in fields.

You can programmatically manipulate the PropertyDefinition stream structure. However, you can achieve similar results by using the Outlook Forms Designer and, in particular, the Properties dialog box for a data-bound control.

Field definitions in a PropertyDefinition stream structure can be one of two formats: PropDefV1 and PropDefV2. Outlook supports both PropDefV1 and PropDefV2. All field definitions in a single PropertyDefinition stream structure must be of the same format. For more information about how PropDefV1 and PropDefV2 differ, see FieldDefinition Stream Structure.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the order specified below.

  • Version: WORD (2 bytes), the format of the field definitions in the PropertyDefinition stream structure. The following table shows the possible values.

    Value

    Description

    0x0102

    Format is PropDefV1.

    0x0103

    Format is PropDefV2.

  • FieldDefinitionCount: DWORD (4 bytes), the number of field definitions in this stream. This is the count of array elements in the FieldDefinitions data element.

  • FieldDefinitions: An array of FieldDefinition stream structures. The count of this array is equal to the FieldDefinitionCount data element.

See also

Concepts

Outlook Items and Fields
How to: Add a Definition for a New User-Defined Field
PropertyDefinition Stream Sample
Stream Structures


FieldDefinition Stream Structure

 Copy code hover
[image]

FieldDefinition Stream Structure
See also Send feedback

Published: July 16, 2012

A FieldDefinition stream structure contains either the field definition of a user-defined field, or a set of data-binding settings for a built-in field.

You can programmatically manipulate a FieldDefinition stream structure if the structure contains the field definition of a user-defined field. You should not attempt to programmatically create or modify a FieldDefinition structure if the structure contains settings for a built-in field. You should use the Microsoft Outlook Forms Designer to maintain such settings for built-in fields.

Note Note

Outlook supports two formats of field definitions: PropDefV1 and PropDefV2. The PropDefV1 format of field definitions contains the following data elements: Flags, VT, DispId, NmidNameLength, NmidName, NameANSI, FormulaANSI, ValidationRuleANSI, ValidationTextANSI, and ErrorANSI. The PropDefV2 format contains the same elements and the InternalType and SkipBlocks elements.

Outlook does not maintain a Unicode version for the FormulaANSI, ValidationRuleANSI, and ValidationTextANSI data elements in the PropDefV2 field definition format. If these elements contain non-ASCII characters, those characters may be interpreted inconsistently depending on the ANSI Code Page of the computer on which Outlook is running. Therefore, you should use only string values that consist entirely of ASCII characters for these data elements.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the order specified below.

  • Flags: DWORD (4 bytes), a combination of zero or more flags whose values and meanings are listed in the following table.

    Flag name

    Value

    Description

    PDO_IS_CUSTOM

    0x00000001

    The FieldDefinition structure contains a definition of a user-defined field.

    PDO_REQUIRED

    0x00000002

    For a form control bound to this field, the check box for A value is required for this field is selected in the Validation tab of the Properties dialog box.

    PDO_PRINT_SAVEAS

    0x00000004

    For a form control bound to this field, the check box for Include this field for printing and Save As is selected in the Validation tab of the Properties dialog box.

    PDO_CALC_AUTO

    0x00000008

    For a form control bound to this field, the check box for Calculate this formula automatically is selected in the Value tab of the Properties dialog box.

    PDO_FT_CONCAT

    0x00000010

    This is a field of type Combination and it has the Joining fields and any text fragments with each other option selected in its Combination Formula Field dialog box.

    PDO_FT_SWITCH

    0x00000020

    This field is of type Combination and has the Showing only the first non-empty field, ignoring subsequent ones option selected in the Combination Formula Field dialog box.

    PDO_PRINT_SAVEAS_DEF

    0x00000040

    This flag is not used by Outlook, but it is included for all user-defined field definitions.

  • VT: WORD (2 bytes), the data type of the field, which is a constant from the VARENUM enumeration.

  • DispId: DWORD (4 bytes), the dispatch identifier of the field. For a user-defined field, the value is 0.

  • NmidNameLength: WORD (2 bytes), the number of elements in the NmidName array.

  • NmidName: An array of WCHAR. For a user-defined field definition, this is the Unicode (UTF-16) representation of the field name. The count of this array is equal to NmidNameLength.

  • NameANSI: A PackedAnsiString stream structure. This is the ANSI representation of the field name.

  • FormulaANSI: A PackedAnsiString stream structure. This is an ANSI representation of the calculation formula for the field. It is shown in the Initial Value section of the Value tab of the Properties dialog box of a form control bound to this field.

  • ValidationRuleANSI: A PackedAnsiString stream structure. This is an ANSI representation of the field's validation formula. It is shown in the text box for Validation Formula on the Validation tab of the Properties dialog box of a form control bound to this field.

  • ValidationTextANSI: A PackedAnsiString stream structure. This is an ANSI representation of the field's validation failure text. It is shown in the text box for Display this message if the validation fails on the Validation tab of the Properties dialog box of a form control bound to this field.

  • ErrorANSI: A PackedAnsiString stream structure. Outlook does not use this element; you should set this element to an empty string.

  • InternalType: DWORD (4 bytes), the internal type of the field. This data element is present only if the field definition format is PropDefV2. The internal type is one of the following values, each of which corresponds to a type in the New Field dialog box for user-defined fields.

    Internal type name

    Value

    Corresponding type in New Field dialog box

    iTypeString

    0

    Text

    iTypeNumber

    1

    Number

    iTypePercent

    2

    Percent

    Currency

    3

    Currency

    iTypeBool

    4

    Yes/No

    iTypeDateTime

    5

    Date/Time

    iTypeDuration

    6

    Duration

    iTypeCombination

    7

    Combination, with the Showing only the first non-empty field, ignoring subsequent ones option selected in the Combination Formula Field dialog box.

    iTypeFormula

    8

    Formula

    iTypeResult

    9

    This type is not used for user-defined fields.

    iTypeVariant

    10

    This type is not used for user-defined fields.

    iTypeFloatResult

    11

    This type is not used for user-defined fields.

    iTypeConcat

    12

    Combination, with the Joining fields and any text fragments with each other option selected in the Combination Formula Field dialog box.

    iTypeKeywords

    13

    Keyword

    iTypeInteger

    14

    Integer

  • SkipBlocks: A series of one or more SkipBlock stream structures. This data element is present only if the field definition format is PropDefV2. If the field definition format is PropDefV2, the series should contain at least one SkipBlock structure, the SkipBlock structure that has the Size data element equal to 0, and the series should begin and terminate with this SkipBlock structure.

    The purpose of a SkipBlock structure depends on its relative position in the SkipBlocks series. If the field definition is in PropDefV2 format, and the first structure is not the terminating structure (the Size data element is greater than 0), Outlook assumes the first SkipBlock structure specifies the field name in Unicode (UTF-16).

    Important note Important

    If the first SkipBlock is the terminating structure, the NameANSI data element is used to determine the field name. If that string contains any non-ASCII characters, those characters may be interpreted inconsistently depending on the ANSI code page of the computer on which Outlook is running. To prevent such inconsistencies, be sure you always specify the first SkipBlock in field definitions that you create, at least when the field name includes non-ASCII characters.

    If a future version of a field definition format introduces additional pieces of data in the FieldDefinition stream, this data can be stored as additional SkipBlock stream structures in the SkipBlocks series before the terminating SkipBlock structure that has the Size data element equal to 0. Earlier versions of Outlook can safely ignore these extra SkipBlock structures up to the terminating SkipBlock structure and still correctly process all the blocks that they support.

See also

Concepts

Outlook Items and Fields
Stream Structures
PropertyDefinition Stream Structure


Folder Fields Stream Structures

 Copy code hover
[image]

Folder Fields Stream Structures
See also Send feedback

Published: July 16, 2012

A message's PidTagUserFields property contains a binary stream, FolderUserFields, which contains the folder user-defined field definitions. This topic describes the stream structures for folder user-defined field definitions.

FolderUserFields Stream Structure

A FolderUserFields stream structure consists of either a FolderUserFieldsA structure or a FolderUserFieldsA structure followed by a FolderUserFieldsW structure.

Data elements in this stream are stored immediately following each other in the following specified order:

  • FolderUserFieldsAnsi: A FolderUserFieldsA stream structure.

  • FolderUserFieldsUnicode (optional): A FolderUserFieldsW stream structure.

The presence of FolderUserFieldsUnicode is detected by the total length of the FolderUserFields being greater than the length of FolderUserFieldsAnsi.

Important note Important

FolderUserFieldsAnsi is used for compatibility with older, non-Unicode, versions of MAPI clients, therefore if FolderUserFieldsUnicode is present, the contents of FolderUserFieldsAnsi is ignored. To avoid possible data loss in ANSI conversion, when creating a FolderUserFields stream always include the FolderUserFieldsW part.

FolderUserFieldsA Stream Structure

A FolderUserFieldsA stream structure is an array of FolderFieldDefinitionA stream structures that contain definitions for all user-defined fields in an Outlook folder, unless overridden by the FolderUserFieldsW part of the FolderUserFields structure.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldDefinitionCount: DWORD (4 bytes), the number of field definitions in this stream. This is the count of elements in the FieldDefinitions array.

  • FieldDefinitions: An array of FolderFieldDefinitionA stream structures. The count of this array is equal to the FieldDefinitionCount data element.

Unless this FolderUserFieldsA is overridden by the FolderUserFieldsW part of the FolderUserFields structure, the FieldDefinitions array must be "null-terminated" by having its last FolderFieldDefinitionA element's Common.FieldType field equal to ftNull.

FolderUserFieldsW Stream Structure

A FolderUserFieldsW stream structure is an array of FolderFieldDefinitionW stream structures that contain definitions for all user-defined fields in an Outlook folder.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldDefinitionCount: DWORD (4 bytes), the number of field definitions in this stream. This is the count of elements in the FieldDefinitions array.

  • FieldDefinitions: An array of FolderFieldDefinitionW stream structures. The count of this array is equal to the FieldDefinitionCount data element.

The FieldDefinitions array must be "null-terminated" by having its last FolderFieldDefinitionW element's Common.FieldType field equal to ftNull.

FolderFieldDefinitionA Stream Structure

A FolderFieldDefinitionA stream structure contains a definition of a user-defined field with the field name stored in ANSI.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldType: FldType (4 bytes), the type of this field.

  • FieldNameLength: WORD (2 bytes), the number of elements in the FieldName array.

  • FieldName: An array of CHAR. This is the ANSI CP_ACP codepage representation of the field name. The count of this array is equal to FieldNameLength. The field name must satisfy the restrictions on the Name parameter as specified in the UserProperties.Add Method.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some FieldName values not satisfying these restrictions, however such cases are not covered by this topic.

  • Common: A FolderFieldDefinitionCommon stream structure.

FolderFieldDefinitionW Stream Structure

A FolderFieldDefinitionW stream structure contains a definition of a user-defined field with the field name stored in Unicode.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • FieldType: FldType (4 bytes), the type of this field.

  • FieldNameLength: WORD (2 bytes), the number of elements in the FieldName array.

  • FieldName: An array of WCHAR. This is the Unicode (UTF-16) representation of the field name. The count of this array is equal to FieldNameLength. The field name must satisfy the restrictions on the Name parameter as specified in the UserProperties.Add Method.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some FieldName values not satisfying these restrictions, but such cases are not covered by this topic.

  • Common: A FolderFieldDefinitionCommon stream structure.

FldType Enumeration

FldType enumeration values are listed in the following table.

Name | Value | Meaning
ftNull | 0x0 | This field type is used to null-terminate an array of field definitions.
ftString | 0x1 | Text
ftInteger | 0x3 | Integer
ftTime | 0x5 | Date/Time
ftBoolean | 0x6 | Yes/No
ftDuration | 0x7 | Duration
ftMultiString | 0xB | Keywords
ftFloat | 0xC | Number or Percent
ftCurrency | 0xE | Currency
ftCalc | 0x12 | Formula
ftSwitch | 0x13 | Combination of type showing only the first non-empty field - ignoring subsequent ones.
ftConcat | 0x17 | Combination of type joining fields and any text fragments to each other.

FolderFieldDefinitionCommon Stream Structure

A FolderFieldDefinitionCommon stream structure contains the data of a user-defined field definition that is common to both a FolderFieldDefinitionA and a FolderFieldDefinitionW.

Data elements in this stream are stored in little-endian byte order, immediately following each other in the following specified order:

  • PropSetGuid: GUID (16 bytes), the property set GUID of the folder field's corresponding MAPI property name. This field's value must be equal to PS_PUBLIC_STRINGS, unless the field type is ftNone in which case this field's value must be equal to GUID_NULL.

    Note Note

    For reasons of legacy compatibility, Outlook may be able to handle some PropSetGuid values not satisfying this restriction, however such cases are not covered by this topic.

  • fcapm: DWORD (4 bytes), a combination of zero or more flags the values of which and meanings are listed in the following table. Flags with the same value have meanings dependent on the field's type, that is, FldType value.

    Flag name

    Value

    Meaning

    FCAPM_CAN_EDIT

    0x00000001

    The field is editable.

    FCAPM_CAN_SORT

    0x00000002

    The field is sortable.

    FCAPM_CAN_GROUP

    0x00000004

    The field is groupable.

    FCAPM_MULTILINE_TEXT

    0x00000100

    The field can hold multiple lines of text.

    FCAPM_PERCENT

    0x01000000

    This field of the type ftFloat is a percentage field.

    FCAPM_DATEONLY

    0x01000000

    This field of the type ftTime is a date-only time field.

    FCAPM_UNITLESS

    0x01000000

    For this field of the type ftInteger, no unit is allowed in display format; for example such formats as "Computer - 640 K…" are not allowed.

    FCAPM_CAN_EDIT_IN_ITEM

    0x80000000

    The field can be edited in the item: This is specifically for custom forms.

  • dwString: DWORD (4 bytes). See the first following Note.

  • dwBitmap: DWORD (4 bytes). See the first following Note.

  • dwDisplay: DWORD (4 bytes). See the first following Note.

  • iFmt: INT (4 bytes). For the field types that have the "Format:" combo box in the "New Field", "Edit Field", and "Field Properties" dialogs, the 0-based index of the format selected in that combo box. For the field types without that combo box, this must be 0. The field's value together with the field type uniquely determine the values of the dwString, dwBitmap, and dwDisplay fields, see the first following Note.

  • wszFormulaLength: WORD (2 bytes), the number of elements in the wszFormula array.

  • wszFormula: An array of WCHAR. This is the Unicode (UTF-16) representation of the field's formula string in its standard format. See the second following Note for the description of the standard and UI formats of a field's formula. The count of this array is equal to wszFormulaLength. The formula string must be an empty string unless the field type is ftCalc, ftSwitch or ftConcat.

Note Note

Although the values of dwString, dwBitmap, and dwDisplay are uniquely determined based on the FldType value and the iFmt value, which are redundant, their correct values are still necessary for correct processing of the field definition by Outlook. There is no simple description of the algorithm that performs this determination. Therefore, to find out which dwString, dwBitmap, and dwDisplay values correspond to a given FldType value and iFmt value, perform a test by creating a user-defined field of that type and with that format selected in the "Format:" combo box, assuming its applicability, inspect the resulting FolderUserFields stream that Outlook creates for that user-defined field.

Note Note

The field's formula in its UI format is edited in the "Formula:" textbox of the "New Field", "Edit Field", and "Field Properties" dialogs for the user-defined field. The algorithm to convert a formula from the UI format to the standard format depends on the field type as described in the following:

  • For fields of types ftCalc and ftSwitch, the standard format for built-in fields, which corresponding MAPI properties are not named properties of the kind MNID_STRING, is obtained by replacing field name fragments, that is "[<field_name>]" with fragments "[_<field_dispid_decimal>]". For example, if the UI format of a formula for a field of the type "Formula", that is ftCalc, with the Office UI language being US English is "[Business Phone] & [My custom field]" where "My custom field" is the name of a user-defined field, the standard format of such a formula would be "[_14856] & [My custom field]".

  • For fields of the type ftConcat, the standard format is obtained by performing the following:

    1. Truncate leading and trailing whitespace.

    2. Parse the formula into a sequence of fragments of the following two kinds:

      • A field name in square brackets, that is, [<field_name>].

      • A substring not containing any square brackets.

      Assure that no two fragments of the second kind are adjacent in the sequence. If the formula cannot be parsed this way, it is considered invalid.

    3. Perform the same replacement for fragments of the first kind as for the ftCalc and ftSwitch fields.

    4. For each fragment of the second kind, escape all double-quote (""") characters, if any, with two consecutive double-quote characters, and enclose it in double quotes.

    5. Insert an ampersand string, that is, " & " between each pair of adjacent fragments.

    For example, using the Office UI language US English, if the UI format of a formula for a field of the type ftConcat is " text1 [Business Phone] "text2" [My custom field] ", where "My custom field" is the name of a user-defined field, the standard format for such a formula would be ""text1 " & [_14856] & """text2""" & [My custom field]".

See also

Concepts

FolderUserFields Stream Sample
How to: Add a Definition for a New User-Defined Field


SkipBlock Stream Structure

 Copy code hover
[image]

SkipBlock Stream Structure
See also Send feedback

Published: July 16, 2012

A SkipBlock stream structure is a block of data that starts with an integer that specifies the length of the remaining part of the block. This stream structure exists in a FieldDefinition stream if the field definition is in PropDefV2 format.

The purpose of a SkipBlock stream structure depends on its relative location in a series of like structures in the SkipBlocks data element of a FieldDefinition stream. The SkipBlocks series should contain at least one SkipBlock structure that terminates the series and has the Size data element equal to 0. If the first structure is not the terminating structure (that is, the Size data element is greater than 0), Outlook assumes the first structure specifies the field name in Unicode (UTF-16).

Data elements in this stream are stored in little-endian byte order, immediately following each other in the order specified below.

  • Size: DWORD (4 bytes), the size, in number of bytes, of the Content data element.

  • Content: An array of BYTE. The count of this array is equal to the Size data element. The meaning of the Content data element depends on the location of the SkipBlock structure in the series and the version of Outlook. If the first SkipBlock structure is not the terminating structure, Outlook considers the first SkipBlock structure as the FirstSkipBlockContent stream structure that specifies the field name in Unicode.

See also

Concepts

Outlook Items and Fields
Stream Structures
FieldDefinition Stream Structure
FirstSkipBlockContent Stream Structure


FirstSkipBlockContent Stream Structure

 Copy code hover
[image]

FirstSkipBlockContent Stream Structure
See also Send feedback

Published: July 16, 2012

The FirstSkipBlockContent stream structure is the content of the first SkipBlock structure in the SkipBlocks data element of a FieldDefinition stream. The FirstSkipBlockContent stream is simply a single data element, FieldName:

  • FieldName: PackedUnicodeString, the field name.

See also

Concepts

Outlook Items and Fields
Stream Structures
SkipBlock Stream Structure
PackedUnicodeString Stream Structure


PackedAnsiString Stream Structure

 Copy code hover
[image]

PackedAnsiString Stream Structure
See also Send feedback

Published: July 16, 2012

The PackedAnsiString stream structure contains an ANSI representation of a string, based on the ANSI code page of the computer on which Microsoft Outlook is running. This string is not terminated by a null character. Data elements in this stream are stored in little-endian byte order, immediately following each other in the order listed below. The actual data elements that exist depend on the length of the string in ANSI representation.

  • For a string whose ANSI representation contains less than 255 bytes, the data elements are as follows:

    • Length: BYTE (1 byte), the length, in number of bytes, of the ANSI representation of the string.

    • Characters: An array of CHAR. The count of this array is equal to the Length data element. The data in the array is the ANSI representation of the string.

  • For a string whose ANSI representation contains 255 to 65535 bytes, the data elements are as follows:

    • Prefix: BYTE (1 byte), the value of 255 (0xff).

    • Length: WORD (2 bytes), the length, in number of bytes, of the ANSI representation of the string.

    • Characters: An array of CHAR. The count of this array is equal to the Length data element. The data in the array is the ANSI representation of the string.

See also

Concepts

Outlook Items and Fields
Stream Structures
FieldDefinition Stream Structure


PackedUnicodeString Stream Structure

 Copy code hover
[image]

PackedUnicodeString Stream Structure
See also Send feedback

Published: July 16, 2012

The PackedUnicodeString stream structure contains a Unicode (UTF-16) representation of a string. This string is not terminated by a null character. Data elements in this stream are stored in little-endian byte order, immediately following each other in the order listed below. The actual data elements that exist depend on the length of the string in UTF-16 representation.

  • For a string whose UTF-16 representation contains less than 255 WCHARs, the data elements are as follows:

    • Length: BYTE (1 byte), the length, in number of WCHARs, of the UTF-16 representation of the string.

    • Characters: An array of WCHAR. The count of this array is equal to the Length data element. The data in the array is the UTF-16 representation of the string.

  • For a string whose UTF-16 representation contains 255 to 65535 WCHARs, the data elements are as follows:

    • Prefix: BYTE (1 byte), the value of 255 (0xff).

    • Length: WORD (2 bytes), the length, in number of WCHARs, of the UTF-16 representation of the string.

    • Characters: An array of WCHAR. The count of this array is equal to the Length data element. The data in the array is the UTF-16 representation of the string.

See also

Concepts

Outlook Items and Fields
Stream Structures
FieldDefinition Stream Structure


MAPI Attachments

 Copy code hover
[image]

MAPI Attachments
Send feedback

Published: July 16, 2012

Some message store providers enable clients to associate added information in the form of files, OLE objects, messages, or binary data with messages. This added information is called a message's attachment. Because attachments are created, maintained, and accessed only through their messages, they are considered message subobjects. Rather than having an entry identifier for access, attachments have a sequential number known as an attachment number. This number uniquely identifies the attachment within its message, but not necessarily within the message store. Two different messages can have different attachments with the same attachment number. Attachment numbers are only valid as long as the message is open and are stored in the PR_ATTACH_NUM (PidTagAttachNumber) property.

To access summary information about all of a message's attachments, clients retrieve its attachment table. The attachment table includes information that clients can use to access an attachment directly, such as its attachment number and record key. Clients can retrieve an attachment table by:

  • Calling IMessage::GetAttachmentTable. For more information, see IMessage::GetAttachmentTable.

  • Calling IMAPIProp::OpenProperty. For more information, see IMAPIProp::OpenProperty.

Message store providers are expected to support both of these approaches. The OpenProperty approach requires that the caller specify IID_IMAPITable as the interface identifier and PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) as the property tag. PR_MESSAGE_ATTACHMENTS is a table object property that represents a message's attachment table. Message store providers are required to set PR_MESSAGE_ATTACHMENTS for each message and include it in the array of property tags returned from the IMAPIProp::GetPropList method. For more information, see IMAPIProp::GetPropList.

PR_MESSAGE_ATTACHMENTS can be used:

  • With IMAPIProp::OpenProperty to access an attachment or recipient table.

  • With IMAPIProp::CopyTo or IMAPIProp::CopyProps to exclude or include attachments when copying. For more information, see IMAPIProp::CopyTo and IMAPIProp::CopyProps.

  • In a subobject restriction to indicate that the child restriction should apply to attachments.

For more information, see Attachment Tables.


MAPI Recipients

 Copy code hover
[image]

MAPI Recipients
Send feedback

Published: July 16, 2012

Every message to be transmitted has one or more recipients, or a set of properties that describe where the message is to be delivered. Because recipients are used only in the context of a message, they are considered subobjects of a message instead of separate MAPI objects. Clients and providers work with recipients using the IMessage interface. For more information, see IMessage : IMAPIProp.

Clients access a message's recipients through its recipient table. Every message has a recipient table that contains summary information about each of its recipients. The columns included in the table depend on the state of the message. When a message is under composition, its recipients might have only three columns in the table:

  • Display name, or PR_DISPLAY_NAME (PidTagDisplayName)

  • Recipient type, or PR_RECIPIENT_TYPE (PidTagRecipientType)

  • Row identifier, or PR_ROWID (PidTagRowid)

After the message has undergone the name resolution process, each recipient will also have an entry identifier, or PR_ENTRYID (PidTagEntryId) column. And when the message has been submitted, the rows in the recipient table will add two more columns:

  • Address type, or PR_ADDRTYPE (PidTagAddressType)

  • Transport responsibility, or PR_RESPONSIBILITY (PidTagResponsibility)

Clients can retrieve a message's recipient table by calling its IMessage::GetRecipientTable method or its IMAPIProp::OpenProperty method. For more information, see IMessage::GetRecipientTable and IMAPIProp::OpenProperty. Message store providers are expected to support both of these approaches. The OpenProperty approach requires that the client specify IID_IMAPITable as the interface identifier and PR_MESSAGE_RECIPIENTS as the property tag. PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) is a table object property that represents a message's recipient table. Message store providers are required to set PR_MESSAGE_RECIPIENTS for each message and include it in the array of property tags returned from the IMAPIProp::GetPropList method. For more information, see IMAPIProp::GetPropList.

For more information about how to work with a recipient table, see Recipient Tables.

In addition to being used to access a recipient table, PR_MESSAGE_RECIPIENTS can be used:

  • With IMAPIProp::CopyTo or IMAPIProp::CopyProps to exclude or include recipients when copying. For more information see, IMAPIProp::CopyTo and IMAPIProp::CopyProps.

  • In a subobject restriction to indicate that the child restiction should apply to recipients.

Clients can add recipients to a message by copying entries from the MAPI address book or by creating new entries. These new entries, called one-offs, can exist temporarily or be saved permanently in a modifiable container. Whereas recipients that are taken from the address book have entry identifiers associated with their address book provider, one-off recipients have entry identifiers that are formatted by MAPI. Transport providers and clients associate one-off entry identifiers with various types of addresses.

Transport providers call IMAPISupport::CreateOneOff to create a one-off entry identifier for an address on an outgoing message when:

  • The address belongs to a gateway.

  • The address cannot be handled by an address book provider in the current profile.

For more information, see IMAPISupport::CreateOneOff.

Clients call IAddrBook::CreateOneOff to create a one-off entry identifier for an address on an incoming message when:

  • The address is formatted as a one-off address.

  • The address is formatted as an Internet address.

For more information, see IAddrBook::CreateOneOff.

For more information about one-off entry identifiers and addresses, see One-Off Entry Identifiers and One-Off Addresses.

The properties of a recipient are a combination of address book properties and properties specific to recipients. All recipients have the base address properties, assigned by address book providers. When an entry is used as a recipient for an outgoing message, the base address properties are copied to the ADRLIST structure that holds the properties for all of a message's recipients.

Two properties that are set specifically for recipients are PR_RECIPIENT_TYPE and PR_RESPONSIBILITY. PR_RECIPIENT_TYPE indicates whether a recipient is a primary, carbon copy, blind carbon copy, or a resend recipient. The first three types are assigned to recipients on messages that are being sent for the first time.

If a recipient does not receive the message and an attempt is made to resend it, the recipient is copied and its type is set to MAPI_P1 to indicate that it is a resend recipient. If only some of the recipients receive a message, their PR_RECIPIENT_TYPE properties are marked with the addition of the MAPI_SUBMITTED flag when the message is resent. Clients are required to handle primary recipients, or recipients with their PR_RECIPIENT_TYPE set to MAPI_TO. All other types are optional.

PR_RESPONSIBILITY is set to indicate to the transport provider whether or not it should handle sending to the recipient. When an outgoing message is first sent, all of the recipients set PR_RESPONSIBILITY to FALSE. As a transport provider claims responsibility for sending to one or more of the recipients, their PR_RESPONSIBILITY properties are set to TRUE.


MAPI Address Book

 Copy code hover
[image]

MAPI Address Book
Send feedback

Published: July 16, 2012

The integrated address book is an object that MAPI implements to provide access to an integrated collection of addressing information from all of the address book providers in the profile. With the address book, client applications and service providers do not have to differentiate between the unique addressing schemes of messaging systems. Instead, they can look up the addresses of any recipients in any messaging system, as long as the address book provider for the messaging system is installed.

The address book can be accessed programmatically, without user intervention, or interactively through the use of common dialog boxes. MAPI includes dialog boxes to display a summary list of the entries in the address book, detailed information about a particular recipient, a warning when a user creates a recipient that cannot be mapped to a unique address, and a set of template forms for creating new recipients.

The MAPI address book is similar in structure to a message store in that it is organized hierarchically. The address book provides access to three types of objects implemented by an address book provider:

  • An address book container object.

  • A distribution list object.

  • A messaging user object.

Each of these types of objects is accessed through its unique entry identifier that is assigned by its address book provider.

Address book containers are similar to folders in that they hold objects of different types. An address book container can hold other address book containers as well as messaging user and distribution list objects. Address book containers are used to organize and store address book objects.

To achieve the address book's integrated appearance, address book providers expose zero, one, or more of their top-level containers to MAPI which merges them and displays the results under a single top-level container. Address book providers can choose to expose one set of containers for one type of messaging session and a different set for another session. It is also possible for address book providers to have no top-level containers and expose only a list of templates that can be used to create recipients.

Message recipients are implemented with messaging user and distribution list objects. Messaging users are individual recipients; distribution lists are group recipients. Each messaging user has a unique address of a particular type handled by a particular messaging system. A distribution list is a named collection of recipients. Distribution lists can contain messaging user objects and other distribution lists. When a user of a client application sends a message to a distribution list, the message is being sent to each of the list's messaging user members.

Messaging users and distribution lists have a set of five properties that are known as the base address properties. These are required properties and are briefly described as follows.

Base address property | Description
PR_ADDRTYPE (PidTagAddressType) | Type of address for the recipient. Each address type follows a particular format and is used with a particular messaging system.
PR_DISPLAY_NAME (PidTagDisplayName) | Displayable name for the recipient.
PR_EMAIL_ADDRESS (PidTagEmailAddress) | Address of the recipient.
PR_ENTRYID (PidTagEntryId) | Entry identifier used to access the recipient.
PR_SEARCH_KEY (PidTagSearchKey) | Binary comparable key used to identify the recipient.

MAPI defines many groups of properties that are variations of the base address properties. These other groups describe messaging users and distribution lists in different situations. For example, one group of properties describes the delegate sender of a message and another group the delegate recipient.


MAPI Address Types

 Copy code hover
[image]

MAPI Address Types
Send feedback

Published: July 16, 2012

Every messaging user is associated with an address type, a character string describing the format of the user's address that is stored in the PR_ADDRTYPE (PidTagAddressType) property. Address types map to address formats. That is, by looking at a recipient's address type, client applications can determine how to format an address appropriate for the recipient.

For example, the SMTP address type specifies the standard Internet address:

username@companyname.com.

And, the EX address type specifies an Exchange Server address.

All address book entries must have a valid address type. Clients require their users to specify an address type when creating a type of custom recipient unsupported by the address book provider. For the entries that they support, address book providers are required to supply valid address types.

MAPI defines only one address type: MAPIPDL, which stands for personal distribution list.

To get a list of the address types supported by all of the transport providers in the session, client applications call the IMAPISession::EnumAdrTypes method. For more information, see IMAPISession::EnumAdrTypes.


One-Off Addresses

 Copy code hover
[image]

One-Off Addresses
See also Send feedback

Published: July 16, 2012

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. Clients can create one-off addresses when they add new entries to the address book or new recipients to the recipient list of an outgoing message. One-off addresses can be added to any container that is modifiable.

To create a one-off address, clients use a special template containing edit controls for entering all of the information that makes up a one-off address. One-off addresses, like addresses of other types, use a predefined format. The one-off address format is defined by MAPI as follows:

Display name[Address type:E-mail address]

There are six components to this format and some rules about quoting characters. The components are described in the following table.

Component | Usage | Description
Display name | Optional | If not present, IAddrBook::ResolveName uses the visible part of the e-mail address as the display name. May include blanks. For more information, see IAddrBook::ResolveName.
[ | 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. For more information, see MAPI Address Types.
: | Required | Separates the address type from the e-mail address.
E-mail address | Required | Address of the recipient. May include blanks.

MAPI uses particular sets of quoting characters to allow addresses to contain special characters such as comma (,), left bracket ([), and colon (:) and some untypeable characters such as the carriage return or line feed or any other hexadecimal equivalent. The quoting character is the backslash (\). Therefore, if clients or providers must insert a backslash in an address, they must preceed it with the quoting character ("\\").

Clients and service providers can use this quoting technique in any of the nonfixed, typeable fields. For example, the following entry translates to Bill Lee as the display name, MSPEER as the address type, and \\billll\in as the e-mail address:

Copy code Copy code
Bill Lee[MSPEER:\\\\billl\in]

To insert special nontypeable characters, clients and service providers use a quoting character followed by an x and two hexadecimal digits to represent their hexadecimal equivalent. For example, if an address has a nontypeable character that equates to a carriage return, (\0d) in hexadecimal, a client would enter them as:

Copy code Copy code
Fax Recipient[fax:recipient\x0dbuilding\x0doffice\x0d555-1212\x0d]

IAddrBook::ResolveName also automatically parses most SMTP addresses, looking for addresses with the following format:

Copy code Copy code
XXX@YYY.ZZZ

Although not all of the possible RFC822 formats are handled, this automatic parsing is adequate for most users. ResolveName includes this functionality to enable users to enter SMTP addresses directly into a message and have that message go to the Internet user. The XXX, YYY, and ZZZ components of the address can be one or more characters. The at sign (@) cannot be included in either the XXX, YYY, or ZZZ address components and the YYY component also cannot include the period. Because the following characters are special characters in SMTP addresses, MAPI automatically converts a display name containing these characters into a one-off address:

  • >>

  • @

  • <>

  • .

Every one-off address is assigned a corresponding one-off entry identifier. To make this assignment, clients call IAddrBook::CreateOneOffand transport providers call IMAPISupport::CreateOneOff. For more information, see IAddrBook::CreateOneOff and IMAPISupport::CreateOneOff. When processing incoming messages, transport providers create one-off entry identifiers for gateway addresses and for addresses that cannot be handled by the transport's associated address book providers. Transport providers check the type of each address in a message to determine if it can be handled by an address book provider associated with the transport. If it cannot, transport providers call IMAPISupport::CreateOneOff to associate the address with a one-off entry identifier.

One-off entry identifiers include the following information in the following order:

  1. MAPIUID

  2. Version

  3. Flags

  4. Display name

  5. Address type

  6. E-mail address

In the calls to IAddrBook::CreateOneOff and IMAPISupport::CreateOneOff, clients and transport providers can set a flag that indicates whether or not the recipient represented by the one-off address can process formatted text or embedded OLE objects. To indicate that a recipient can handle formatted text and OLE objects, clients and transport providers set the MAPI_SEND_NO_RICH_INFO flag in the ulFlags parameter. MAPI then sets the one-off recipient's PR_SEND_RICH_INFO (PidTagSendRichInfo) property to FALSE. When this flag is not set, MAPI sets PR_SEND_RICH_INFO to TRUE unless the one-off address is interpreted as an SMTP address. In this one case, PR_SEND_RICH_INFO defaults to FALSE.

See also

Reference

IAddrBook::ResolveName


Address Book Identifiers

 Copy code hover
[image]

Address Book Identifiers
Send feedback

Published: July 16, 2012

All address book providers assign entry identifiers using the PR_ENTRYID (PidTagEntryId) property to their messaging user and distribution list objects. Client applications use these entry identifiers to open and access the objects to which they are assigned.

The address book makes use of three other types of identifiers to represent objects:

  • One-off entry identifiers

  • One-off template entry identifiers

  • Template identifiers

Because of the variety of entry identifiers and the similarity with which they are named, it is easy to become confused about how each type is used and created.

A one-off entry identifier is an entry identifier that is used to open and access the type of recipient known as a one-off, or custom recipient. One-offs are recipients that do not belong to any of the address book providers in the profile. The entry identifiers assigned to one-offs use a format specifically reserved for one-off recipients. Because one-off entry identifiers are used to open and access objects, they are stored in the PR_ENTRYID property.

One-offs and one-off entry identifiers are created:

  • When users of a client application elect to add a recipient that does not represent any entry in the address book to a message's recipient list.

  • When users of a client application elect to add a recipient that does not represent any entry in the address book to a modifiable address book container.

  • When a transport provider receives a message with an address that cannot be handled by its related address book provider.

  • When a transport provider receives a message with an address that belongs to a gateway.

In the first two situations, the client calls IAddrBook::CreateOneOff to associate a one-off entry identifier with the newly created one-off recipient. In the second two situations, the transport provider calls IMAPISupport::CreateOneOff to associate a one-off entry identifier with the foreign address. For more information, see IAddrBook::CreateOneOff and IMAPISupport::CreateOneOff.

A one-off template entry identifier is a short-term entry identifier that is used to open and access a template for creating one-offs. Both address book providers and MAPI supply templates for entering the information that is required to create a recipient of a particular type. Information about these templates, including their entry identifiers, is published in the one-off table. One-off tables are displayed when MAPI calls either the IABLogon::GetOneOffTable method or an address book container's IMAPIProp::OpenProperty method to request the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property or when a provider calls IMAPISupport::GetOneOffTable. For more information, see IABLogon::GetOneOffTable, IMAPIProp::OpenProperty, and IMAPISupport::GetOneOffTable.

To create a new one-off, a user selects one of the templates listed in the one-off table. The client passes the PR_ENTRYID column from the selected row, which is the one-off template entry identifier of the selected template, to IAddrBook::NewEntry in the lpEIDNewEntryTpl parameter. For more information, see IAddrBook::NewEntry. MAPI uses the one-off template entry identifier to display the template and to allow the user to enter the information needed to create the recipient.

A template identifier is an entry identifier that some address book providers assign to their recipients in addition to the entry identifier that is kept in the PR_ENTRYID property. Providers set a recipient's PR_TEMPLATEID (PidTagTemplateid) property to store its template identifier. Some address book providers assign the same value for a recipient's template identifier and entry identifier properties.

Template identifiers are used only by address book providers and by MAPI to bind recipient data in one provider, referred to as the host provider, to code for the recipient in another provider, referred to as the foreign provider. The host provider supplies the storage for the recipient; the foreign provider supplies the logic. The binding process enables a host provider to update the data of a recipient that it stores using the code of a foreign provider.

When the host provider is ready to modify its recipient, it passes the PR_TEMPLATEID property in a call to the IMAPISupport::OpenTemplateID method to initiate the binding process. MAPI continues the process by transferring the template identifier to the appropriate foreign provider through a call to its IABLogon::OpenTemplateID method. For more information, see IMAPISupport::OpenTemplateID and IABLogon::OpenTemplateID. The foreign provider returns a pointer to its IMAPIProp implementation for the recipient, which the host provider can use in place of its own implementation.


One-Off Entry Identifiers

 Copy code hover
[image]

One-Off Entry Identifiers
Send feedback

Published: July 16, 2012

One-off entry identifiers are created by MAPI in the IAddrBook::CreateOneOff method and by components that do not have access to the MAPI subsystem, such as gateway components. For more information, see IAddrBook::CreateOneOff. The following illustration shows the format of a one-off entry identifier.

One-off entry identifier format

One-off entry identifier format

The first field is a special MAPIUID structure that identifies the entry identifier as representing a custom recipient. This MAPIUID structure must be set to the constant MAPI_ONE_OFF_UID. MAPI_ONE_OFF_UID is defined in the header file MAPIDEFS.H.

The version and flags fields are 16-bit words in Intel byte order. The version field must be set to zero. The flags field can be set to the following values:

MAPI_ONE_OFF_NO_RICH_INFO

MAPI_ONE_OFF_UNICODE

The MAPI_ONE_OFF_NO_RICH_INFO flag is set if a recipient should not receive message content in the Transport Neutral Encapsulation Format (TNEF). This flag is set when MAPI_SEND_NO_RICH_INFO is passed to IAddrBook::CreateOneOff method.

The MAPI_ONE_OFF_UNICODE flag is set if the display name and e-mail address are Unicode strings. This flag is set when the MAPI_UNICODE is passed to IAddrBook::CreateOneOff. When the MAPI_UNICODE flag is not passed to CreateOneOff, MAPI assumes that the display name and e-mail address strings are in the workstation's current ANSI character set. ANSI strings generally do not work well in messages that are sent between platforms using different character sets because the code page is not encoded in the entry identifier. To protect against this potential incompatibility, many address types are limited to only those characters that are common across multiple character sets. However, to ensure character set and platform compatibility, clients should use Unicode for the character strings in their messages.

The display name is a null-terminated string that corresponds to the recipient's PR_DISPLAY_NAME (PidTagDisplayName) property and to the lpszName parameter passed to IAddrBook::CreateOneOff. The character set is Unicode if the MAPI_ONE_OFF_UNICODE flag is set and ANSI if it is clear.

The address type is a null-terminated string that corresponds to the recipient's PR_ADDRTYPE (PidTagAddressType) property and to the lpszAdrType parameter passed to IAddrBook::CreateOneOff.

The e-mail address is a null-terminated string that corresponds to the recipient's PR_EMAIL_ADDRESS (PidTagEmailAddress) property and to the lpszAddress parameter passed to IAddrBook::CreateOneOff.

Note Note

There is no padding in one-off entry identifier structures; the bytes are packed exactly as indicated above and the entry identifier length should not include any bytes beyond the terminating null character of the e-mail address.

Clients and address book providers that manually construct one-off entry identifiers might also need to generate values for the PR_RECORD_KEY (PidTagRecordKey) and PR_SEARCH_KEY (PidTagSearchKey) properties. The record key is identical to the entry identifier. The search key should be formed by concatenating the following fields in the following order:

  1. The address type, converted to uppercase characters.

  2. A colon (:).

  3. The e-mail address, converted to uppercase characters.

  4. A terminating null character.

No character set conversion must be done when generating the search key.


Using Multiple Exchange Accounts

 Copy code hover
[image]

Using Multiple Exchange Accounts
See also Send feedback

Published: July 16, 2012

Microsoft Outlook 2010 and Microsoft Outlook 2013 support integration with multiple exchange e-mail accounts. In Outlook 2010 or Outlook 2013, a user could add two exchange accounts to the same profile and still enjoy rich Exchange features such as the published global address list (GAL), Exchange Out-of-Office configuration, and folder sharing.

Those familiar with the MAPI profile sections for Microsoft Office Outlook 2007 and earlier know that Exchange settings, such as the e-mail user name and server name, are stored in the fixed Exchange Global Profile section, pbGlobalProfileSectionGuid. For more information about the Exchange Global Profile, see How To Open the Global Profile Section. In Outlook 2010 and Outlook 2013, each Exchange account needs its own profile section to store settings, making the pbGlobalProfileSectionGuid obsolete.

Outlook 2010 and Outlook 2013 Exchange settings are still stored in the profile, but a unique identifier for the profile section that contains their settings is dynamically allocated per profile. The location of the Exchange settings in the profile is stored in the PidTagExchangeProfileSectionId Canonical Property, which can be found in the message service profile section of the Exchange account. This property can also be found in the profile section for each provider in this message service of the account. The unique identifier is not stored on the server and will be different across profiles.

Outlook 2010 and Outlook 2013 use the PidTagExchangeProfileSectionId as a unique identifier to specify an Exchange account. When used in this manner, this unique identifier is known as the emsmdbUID. For some MAPI and Outlook operations, an emsmdbUID might be required to specify which Exchange account should be used for the operation.

In order to support multiple Exchange accounts, you must use some calls to new functions in your code. Replace any call that uses an entryID and either IAddrBook::OpenEntry or IAddrBook::CompareEntryIDs on IMailUser : IMAPIProp and IDistList : IMAPIContainer with one of the following functions.

  • HrCompareABEntryIDsWithExchangeContext

  • HrDoABDetailsWithExchangeContext

  • HrDoABDetailsWithProviderUID

  • HrGetGALFromEmsmdbUID

  • HrOpenABEntryUsingDefaultContext

  • HrOpenABEntryWithExchangeContext

  • HrOpenABEntryWithProviderUID

  • HrOpenABEntryWithProviderUIDSupport

  • HrOpenABEntryWithResolvedRow

  • HrOpenABEntryWithSupport

Legacy support

Any MAPI clients written before the creation of this new emsmdbUID section are still supported. These clients will continue to retrieve the previous global section, pbGlobalProfileSectionGuid. Queries for this profile section will be redirected to one designated Exchange account that handles legacy inquiries. The account that handles the legacy calls can be determined by looking at the message service table and adding a column for PR_EMSMDB_LEGACY. Only one message service will have this set to true, and its PidTagExchangeProfileSectionId is called the legacy emsmdbUID.

Note Note

Configurable MAPI settings such as the default store and the default account have no effect on which account handles legacy calls. The account that handles the legacy calls cannot be configured.

The emsmdbUID of the legacy account is copied to the Outlook Global Profile Section. If this property does not exist, querying for the message services table will determine what account is the legacy handler and set the value in the Outlook Global Profile Section.

To be clear, the Outlook Global Profile Section differs from the Exchange Global Profile Section, and in Outlook 2010 and Outlook 2013 the Exchange Global Profile Section is no longer really global because you can have multiple Exchange accounts. The Outlook Global Profile section contains properties about Outlook, such as the state of the folder MRU or the state of the global connection.

Address Book Account Contexts

To resolve addresses correctly with multiple Exchange accounts, use the new functions that take an account context so that calls to the address book search the correct Exchange account.

Some previous address book APIs were deprecated because the APIs were not fully multiple Exchange capable. This account context is usually an emsmdbUID.

In addition to the emsmdbUID, multiple Exchange accounts also have an emsabpUID.

  1. The emsmdbUID value identifies the account context.

  2. The emsabpUID value identifies an Exchange address book provider.

The emsabpUID value is typically used when resolving a recipient. When resolving a recipient using IAddrBook::ResolveName, an Exchange recipient row contains the PR_AB_PROVIDERS (0x3D010102) property, which contains the emsabpUID value. This emsabpUID value identifies the Exchange address book provider for the specific recipient.

If you want to determine the emsabpUID value for a particular emsmdbUID, open up the profile section for the emsmdbUID and get the PR_EMSABP_USER_UID (0x0x3D1A0102) property.

If you are calling IAddrBook::PrepareRecips, make sure that the Exchange recipients in the list that you pass in contain the PR_AB_PROVIDERS property that has the emsabpUID that corresponds to the address book provider that the recipient belongs to. Calling IAddrBook::PrepareRecips on a row that you obtained from IAddrBook::ResolveName requires no additional action, but some code will call IAddrBook::PrepareRecips on rows that contain only the PR_ENTRYID property. Rows in this and similar situations should contain both PR_ENTRYID and PR_AB_PROVIDERS with the PR_AB_PROVIDERS property set to the correct emsabpUID.

A simple description of the process for resolving multiple Exchange accounts is as follows:

  • Given the service unique identifier, your code looks in the table of the message store of the PR_SERVICE_UID property that matches the one that you have. From there, you can determine the correct PR_MDB_PROVIDER. This row contains the appropriate store.

  • Given an emsmdbUID, your code looks in the message services table for the row that exposes the PidTagExchangeProfileSectionId that matches the emsmdbUID.

See also

Reference

HrCompareABEntryIDsWithExchangeContext
HrDoABDetailsWithExchangeContext
HrDoABDetailsWithProviderUID
HrGetGALFromEmsmdbUID
HrOpenABEntryUsingDefaultContext
HrOpenABEntryWithExchangeContext
HrOpenABEntryWithProviderUID
HrOpenABEntryWithProviderUIDSupport
HrOpenABEntryWithResolvedRow
HrOpenABEntryWithSupport
PidTagExchangeProfileSectionId Canonical Property

Other resources

How To Open the Global Profile Section


MAPI Status Objects

 Copy code hover
[image]

MAPI Status Objects
Send feedback

Published: July 16, 2012

Status objects report information about MAPI resources. For example, a service provider, the MAPI send/receive process, or the address book.

There is a status object supplying information about each individual service provider in the current profile. MAPI is responsible for implementing status objects for the subsystem, the MAPI send/receive process, and the address book. The subsystem status object supplies global information. The status object for the integrated address book supplies the status of all address book providers currently operating.

Every status object is included in the status table, a table maintained by MAPI that provides clients with all of the status information for the session. For more information, see Status Tables. Clients can access a particular status object either through the table or, for a service provider, through its logon object. For example, to access an address book provider's status object, a client can call IABLogon::OpenStatusEntry. For more information, see IABLogon::OpenStatusEntry.

Clients can use status objects to:

  • Learn about the state of a session.

  • Monitor a service provider.

  • Control message transmission.

  • View or change a resource's configuration and status.

Every status object implements the IMAPIStatus interface. For more information, see IMAPIStatus : IMAPIProp. However, not every status object fully supports every IMAPIStatus method. Because there is variation in the methods that are supported by a status object, clients need to learn about a particular status object before they can use it. Status objects are required to publish information about their features in the following three properties:

PR_RESOURCE_METHODS (PidTagResourceMethods)

PR_RESOURCE_TYPE (PidTagResourceType)

PR_RESOURCE_FLAGS (PidTagResourceFlags)

For more information about implementing a status object, see Status Object Implementation. For more information about using a status object, see Status Table and Status Objects.


MAPI Profiles

 Copy code hover
[image]

MAPI Profiles
Send feedback

Published: July 16, 2012

A profile stores information about service providers and message services that are installed on a computer. For every session, a client at logon time selects one profile that describes the providers and services to be used. A client can choose from a collection of profiles and, if desired, establish one as the default. The default profile is the profile that is selected automatically when a client starts a session and has not explicitly specified a profile.

Also in these topics, you will find a discussion of the nickname cache, which is stored in a binary stream.

  • Nickname cache

  • Autocomplete Stream

  • Binary File Parsing

Profile Sections

Profiles are divided into sections that clients and service providers access to display profile properties to users or to make configuration changes. A profile section is a MAPI object that implements the IProfSect interface, an interface that derives from IMAPIProp and has no additional methods. For more information, see IProfSect : IMAPIProp. Its only purpose is to manipulate the properties of a profile section. To retrieve an IProfSect pointer to a particular profile section, clients and service providers call the following methods.

Clients can call: | IMAPISession::OpenProfileSection
Service providers can call: | IMAPISupport::OpenProfileSection
Either clients or providers can call: | IProviderAdmin::OpenProfileSection

Profiles are organized hierarchically much like the MAPISVC.INF file. At the top of the hierarchy, there are profile sections that contain information relevant to the profile. The middle level includes sections that contain information about a particular message service and the lower level includes sections that contain information about one of the service providers in a message service.

Every profile has several required properties that are stored in one or more of the sections of the profile. For example, every profile has the PR_PROFILE_NAME (PidTagProfileName) and PR_SEARCH_KEY (PidTagSearchKey) properties. A profile's search key is set to the value defined in MAPIGUID.H as MUID_PROFILE_INSTANCE and is always guaranteed to be unique among all profiles. Although two profiles can have the same name, they cannot have the same search key. Search keys should be treated as binary data instead of data of any particular type.

Message store providers are required to include their message store's PR_DISPLAY_NAME (PidTagDisplayName) property in the profile sections for the profile and for their message store provider and to keep these entries synchronized. When a message store is created, the provider sets PR_DISPLAY_NAME based on the value stored in these profile sections.

There are two major differences between profile sections and other objects that inherit from IMAPIProp:

  • Profile sections do not support transactions.

  • Profile sections do not support named properties, returning MAPI_E_NO_SUPPORT from their IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs implementations. For more information, see IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs.

Because profile sections do not support transactions, any changes made with calls to IMAPIProp::CopyProps, CopyTo, or SetProps immediately take effect. For more information, see IMAPIProp::CopyProps. Clients and service providers can call a profile section's IMAPIProp::SaveChanges method and it will succeed, but it does not affect the profile section data. For more information, see IMAPIProp::SaveChanges. Having changes occur immediately can affect how service providers implement the property sheets that clients use to display profile properties to users. Service providers that want users to be able to postpone or undo changes must implement their property sheets with copies of profile sections instead of the real sections. By using copies, users can make changes and then later cancel those changes, leaving the original profile sections untouched.

The order in which information appears in a profile affects how MAPI configures resources and makes assignments in a session. The following assignments are affected by profile order:

  • Default message store

  • Personal address book

  • Default message store search path

  • Default address book search path

  • Transport provider order

MAPI sets the default message store to be the first message store in the profile that has the STATUS_DEFAULT_STORE flag set in its PR_RESOURCE_FLAGS (PidTagResourceFlags) property, which indicates that it can be the default store. Clients can override this setting by calling IMAPISession::SetDefaultStore. For more information, see IMAPISession::SetDefaultStore.

MAPI creates a transport order for handling outgoing and incoming messages. When more than one transport provider has registered for a message of a particular type, MAPI uses this order to determine which provider should handle the message. MAPI sets the transport order to be the order in which the transport providers were added to the profile with one exception--the transports that set the STATUS_XP_PREFER_LAST flag in their PR_RESOURCE_FLAGS property are positioned last in the order. Clients can set the transport order by calling IMsgServiceAdmin::MsgServiceTransportOrder. For more information, see IMsgServiceAdmin::MsgServiceTransportOrder.

These guidelines for ordering service providers and message services might sometimes conflict. If there is a conflict, your code should resolve the conflict. You can use the Mail Control Panel program to inspect a profile that you have created to determine whether the providers have been configured as expected.


Nickname cache

 Copy code hover
[image]

Nickname cache
See also Send feedback

Published: July 16, 2012

Microsoft Office Outlook 2007, Microsoft Outlook 2010, and Microsoft Outlook 2013 interact with the nickname cache, also known as the "autocomplete stream." The autocomplete stream is where Outlook persists the autocomplete list, which is the list of names that displays in the To, Cc, and Bcc edit boxes while a user is composing an email. This topic describes how Outlook 2007, Outlook 2010, and Outlook 2013 interact with the autocomplete stream and also discusses the binary format of the file and the recommended ways for interacting with the autocomplete stream.

For applications that interact with Outlook 2010 or Outlook 2013, the autocomplete stream is stored as a MAPI property and can be modified using the MAPI or the PropertyAccessor object of the message. The PropertyAccessor object is exposed in the Outlook 2010 or Outlook 2013 object models.

There are no dependencies on the Outlook 2007 object model or MAPI APIs. Therefore, applications that make changes to the autocomplete stream within Outlook 2007 can be written using any programming language.

Interacting with the Autocomplete Stream

When the To, Cc, or Bcc edit boxes are accessed on a message, the autocomplete stream is loaded and the list of user names is displayed. Outlook interacts with the autocomplete stream in two ways:

  1. Loading the autocomplete stream

  2. Saving changes to the data in the autocomplete stream

The means of storing the autocomplete data differs between Outlook 2007 and Outlook 2010 or Outlook 2013 as follows:

Outlook 2007

For Outlook 2007, the autocomplete stream is stored in a file with the same name as the profile and an extension of .nk2. For example, if the default profile of "outlook" is used, the file will be called "outlook.nk2". The .nk2 file is stored in %APPDATA%\Microsoft\Outlook. For more information about the nickname cache binary file format, see Outlook 2003/2007 NK2 File Format and Developer Guidelines.

Outlook 2010 and Outlook 2013

Outlook 2010 or Outlook 2013 reads the autocomplete stream from a message in the Associated Contents table of the Inbox of the mail account's delivery store. This hidden message has a message class and subject of IPM.Configuration.Autocomplete. The autocomplete stream is stored on this message in the PR_ROAMING_BINARYSTREAM property (PidTagRoamingBinary Canonical Property). The autocomplete data may be temporarily cached in an autocomplete .dat file located in %USERPROFILE%\AppData\Local\Microsoft\Outlook\RoamCache. However, the .dat file is only a cache and is not used to write back to the delivery store when the user exits Outlook 2010 or Outlook 2013.

Loading the Autocomplete Stream

Outlook loads the autocomplete stream whenever an item with addressing functionality is initialized. For example, email addresses are used in a new mail, a mail reply, a contact item, a meeting request, and so on. To load the data, Outlook reads all of the contents of the stream into memory.

For autocomplete operations, Outlook interacts exclusively with this in-memory structure for the duration of the outlook.exe process lifetime. Outlook only saves the structure on shutdown. See the following section "Saving the Autocomplete Stream" for more information on this process.

Saving the Autocomplete Stream

Outlook saves the autocomplete stream on shutdown if the autocomplete list has changed in any of the following ways:

  • A new nickname entry is added through resolving a name, picking a recipient from the address book dialog, or sending mail to a recipient that was not already in the list.

  • An entry is modified by sending mail to an existing recipient in the list.

  • An entry is removed by the user through the UI.

  • Other minor scenarios not relevant to this topic.

Saving changes to the autocomplete data involves writing the in-memory structure back to an Autocomplete Stream. When interacting with Outlook 2007, the stream is saved to a local .nk2 file. For Outlook 2010 or Outlook 2013, the autocomplete stream writes back to the Associated Contents table of the Inbox of the mail account's delivery store.

Recommendations

  • Never partially modify the autocomplete stream. The supported interaction is to 1) read the entire autocomplete stream into memory, 2) modify the memory structure, and 3) write the entire stream back to either the Associated Contents table of the Inbox of the mail account's delivery store (for Outlook 2010 or Outlook 2013) or to the local .nk2 file (Outlook 2007).

  • Do not interact with the autocomplete stream while Outlook is running. If Outlook is running while you modify the stream, it will likely overwrite your changes when it shuts down.

  • Do not write properties of type PT_MV_UNICODE and PR_MV_STRING8 into an autocomplete stream to be consumed by Microsoft Outlook 2003. These properties are only understood by Outlook 2007, Outlook 2010, and Outlook 2013.

  • When developing code that interacts with Outlook 2007, we recommend that you lock the .nk2 file from modification by other processes while you are reading and writing it using standard file locking APIs (for example, LockFile in C/C++ and FileStream.Lock in C#).

  • Only modify the properties of types that are from the row-set of the autocomplete stream. For more information about the autocomplete stream properties and property types, see Autocomplete Stream.

See also

Concepts

Autocomplete Stream
MAPI Profiles

Other resources

Outlook 2003/2007 NK2 File Format and Developer Guidelines


Autocomplete Stream

 Copy code hover
[image]

Autocomplete Stream
Send feedback

Published: July 16, 2012

In addition to knowing how Microsoft Outlook interacts with the autocomplete stream, you must also understand the binary format of the autocomplete stream.

The autocomplete stream is a set of recipient property rows that are saved as a binary stream together with some bookkeeping metadata that is used only by Microsoft Outlook 2013, Microsoft Outlook 2010, Microsoft Office Outlook 2007, and Microsoft Outlook 2003. The metadata is relevant to Outlook interactions with the autocomplete stream so third parties must preserve what is in each metadata block when they save a modified autocomplete stream. In other words, third parties should modify only the row-set part of the binary format and preserve what was already in the metadata blocks of the autocomplete stream.

Stream Visualization

The high-level layout of the autocomplete stream is as follows:

Metadata (4 bytes)

Major Version Number (4 bytes)

Minor Version Number (4 bytes)

Number of rows n (4 bytes)

Number of properties p in row one (4 bytes)

Property 1's property tag (4 bytes)

Property 1's reserved data (4 bytes)

Property 1's value union (8 bytes)

Property 1's value data (0 or variable bytes)

… (property 2 through property P-1)

Property p's property tag (4 bytes)

Property p's reserved data (4 bytes)

Property p's value union (8 bytes)

Property p's value data (0 or variable bytes)

Number of properties q in row two (4 bytes)

… (row two's properties)

… (row 3 through row n-1)

Number of properties r in row n (4 bytes)

… (row n's properties)

Extra information byte count EI (4 bytes)

Extra information (EI bytes)

Metadata (8 bytes)

For an example of a binary structure, see Binary Example in the Outlook 2003/2007 NK2 File Format and Developer Guidelines.

High-level Layout

Broadly speaking, the layout of the autocomplete stream is as follows:

Value Data | Number of Bytes
Metadata | 4
Major Version Number | 4
Minor Version Number | 4
Row-set | Variable
Extra information byte count EI | 4
Extra information | EI
Metadata | 8

When reading this stream, if the major version is different than 12, then this stream should not be read or written. The current minor version of the autocomplete stream is 0, which has the Extra Information Byte count set to 0. If the minor version is different than 0, then there will be information in the extra information that needs to be read when reading the stream and preserved when writing the stream. The minor version will also need to be preserved when writing the stream. If both of these are not preserved, instances of Outlook that wrote the extra information will lose data.

Note Note

Applications must not add custom data to the Extra Information field or change the minor version as this functionality is to support Outlook extensions to the format and not arbitrary third-party extensions.

Row-set Layout

The row-set layout is as follows:

Value Data | Number of Bytes
Number of rows | 4
Rows | Variable

The number of rows identifies how many rows come in the next part of the binary stream sequence.

Row Layout

Each row is of the following format:

Value Data | Number of Bytes
Number of properties | 4
Properties | Variable

The number of properties identifies how many properties come in the next part of the binary stream sequence.

Property Layout

Each property is of the following format:

Value Data | Number of Bytes
Property Tag | 4
Reserved Data | 4
Property Value Union |
Value Data | 0 or variable (depending on the prop tag)

Interpreting the Property Value

The Property Value Union and the Value Data are to be interpreted based on the property tag in the first 4 bytes of the property block. This property tag is in the same format as a MAPI property tag. Bits 0 through 15 of the property tag are the property's type. Bits 16 through 31 are the property's identifier. The property type determines how the rest of the property should be read.

Static Value

Some properties have no Value Data and only have data in the union. The following property types (which come from the Property Tag) should interpret the 8-byte Property Union data as follows:

Prop Type | Property Union Interpretation
PT_I2 | short int
PT_LONG | long
PT_R4 | float
PT_DOUBLE | double
PT_BOOLEAN | short int
PT_SYSTIME | FILETIME
PT_I8 | LARGE_INTEGER

Dynamic Values

Other properties have data in a Value Data block after the first 16 bytes that contain the Property Tag, the Reserved Data, and the Property Value Union. Unlike static values, the data that is stored in the 8-byte Property Value union is irrelevant on reading. When writing, make sure that you fill these 8 bytes with something. However, the content of the 8 bytes is not important. In dynamic values, the property tag's type determines how to interpret the Value Data.

PT_STRING8

Value Data | Number of Bytes
Number of bytes n | 4
Bytes to be interpreted as an ANSI string (includes NULL terminator) | n

PT_CLSID

Value Data | Number of Bytes
Bytes to be interpreted as a GUID | 16

PT_BINARY

Value Data | Number of Bytes
Number of bytes n | 4
Bytes to be interpreted as a byte array | n

PT_ERROR

Value Data | Number of Bytes
Number of bytes n | 4
Bytes to be interpreted as a byte array | n

PT_MV_BINARY

Value Data | Number of Bytes
Number of binary arrays X | 4
A run of bytes that contains X binary arrays. Each array should be interpreted exactly like the PT_BINARY byte run. | Variable

PT_MV_STRING8 (Outlook 2007, Outlook 2010, and Outlook 2013)

Value Data | Number of Bytes
Number of ANSI strings X | 4
A run of bytes that contains X ANSI strings. Each string should be interpreted exactly like the PT_STRING8 byte run. | Variable

PT_MV_UNICODE (Outlook 2007, Outlook 2010, Outlook 2013)

Value Data | Number of Bytes
Number of UNICODE strings X | 4
A run of bytes that contains X UNICODE strings. Each string should be interpreted exactly like the PT_UNICODE byte run. | Variable

Significant properties

As mentioned previously in this topic, the binary blocks that represent properties have property tags that correspond to properties on address book recipients. For properties that are not listed here, you can look up the property description at http://msdn.microsoft.com/en-us/library/cc433490(EXCHG.80).aspx.

Property Name | Property Tag | Description (see MSDN for more information)
PR_NICK_NAME_W (not transmitted on recipients, specific to autocomplete stream only) | 0x6001001f | This property must be first in each recipient row. It functionally serves as a key identifier for the recipient row.
PR_ENTRYID | 0x0FFF0102 | The address book entry identifier for the recipient.
PR_DISPLAY_NAME_W | 0x3001001F | The recipient's display name.
PR_EMAIL_ADDRESS_W | 0x3003001F | The recipient's e-mail address (e.g. johndoe@contoso.com or /o=Contoso/OU=Foo/cn=Recipients/cn=johndoe)
PR_ADDRTYPE_W | 0x3002001F | The recipient's address type (e.g. SMTP or EX).
PR_SEARCH_KEY | 0x300B0102 | The recipient's MAPI search key.
PR_SMTP_ADDRESS_W | 0x39FE001f | The recipient's SMTP address.
PR_DROPDOWN_DISPLAY_NAME_W (not transmitted on recipients, specific to autocomplete stream only) | 0X6003001f | The display string that appears in the autocomplete list.
PR_NICK_NAME_WEIGHT (not transmitted on recipients, specific to autocomplete stream only) | 0x60040003 | The weight of this autocomplete entry. The weight is used to determine in what order autocomplete entries occur when matching the autocomplete list. Entries with higher weight will show before entries with lower weight. The complete autocomplete list is sorted by this property. The weight periodically decreases over time and increases when the user sends an e-mail to this recipient. See the description later in this topic for more information about this property.

PR_NICK_NAME_WEIGHT

The set of rows in the autocomplete stream is sorted in descending order by the PR_NICK_NAME_WEIGHT property and the autocomplete stream should always preserve this sorted characteristic. Therefore, any changes to a row's weight should also ensure that the row's position maintains the sorted order of the complete set of rows. Any additions to the row-set should be inserted to the correct position to maintain the sorted order.

The minimum value of this weight is 0x1 and the maximum value is LONG_MAX. Any other values for the weight are considered invalid.

When Outlook 2007 sends a mail to or resolves a recipient, it will increase that recipient's weight by 0x2000.


MAPI Primary Identity

 Copy code hover
[image]

MAPI Primary Identity
Send feedback

Published: July 16, 2012

Most MAPI sessions have a particular service provider that supplies the primary identity for the session. Typically, it is an address book provider, which supplies identity through one of its messaging user objects or distribution lists. In fact, MAPI recommends that message services that include an address book provider use one of its objects for the primary identity. When a service provider that belongs to a message service supplies the primary identity, all of the other service providers in the message service share this identity.

The MAPISVC.INF configuration file has entries relating to identity at both the message service and service provider level. Message service sections must include an entry that states whether or not the service can supply the primary identity; service provider sections include a similar entry only when the provider can supply an identity.

The following table lists the entries that appear in the message service and service provider sections in the MAPISVC.INF file.

Primary identity supplier | PR_RESOURCE_FLAGS setting
Message service | SERVICE_PRIMARY_IDENTITY
Not the message service | SERVICE_NO_PRIMARY_IDENTITY
Service provider | STATUS_PRIMARY_IDENTITY

Although multiple message services can declare their ability to provide a session's primary identity, only one message service is selected to do so. This selection can occur:

  • When a profile is created.

  • When a client calls IMsgServiceAdmin::SetPrimaryIdentity to explicitly establish a particular message service as the provider of the session identity. For more information. See IMsgServiceAdmin::SetPrimaryIdentity.

When a profile is created, MAPI designates the first message service to be configured that includes a provider with the STATUS_PRIMARY_IDENTITY flag set in its PR_RESOURCE_FLAGS (PidTagResourceFlags) property to supply the primary identity. Within the designated message service, the first provider to be configured with this resource flag set is chosen to provide the identity for the service. The STATUS_PRIMARY_IDENTITY flag is cleared for all other providers in the designated service and other message services in the profile. If at any time the provider supplying primary identity is removed from the profile, MAPI assigns the role to the next provider to be configured that can supply identity. This is determined by the appearance of the PR_RESOURCE_FLAGS=STATUS_PRIMARY_IDENTITY entry in the provider's section in MAPISVC.INF.

When a client calls a message service's IMsgServiceAdmin::SetPrimaryIdentity method, it specifies the MAPIUID for a service provider within the target service. For more information, see MAPIUID. The service provider represented by the MAPIUID is assigned to supply the primary identity for the message service and for the session, and all of the other providers in the service will share this identity.

Every provider in the message service responsible for supplying the primary identity updates its row in the status table to include the following properties.

Primary identity property | Set to
PR_IDENTITY_DISPLAY (PidTagIdentityDisplay) | Display name of the object supplying the primary identity.
PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey) | Search key for the object supplying the primary identity.
PR_IDENTITY_ENTRYID (PidTagIdentityEntryId) | Entry identifier for the object supplying the primary identity.

To retrieve the entry identifier for the object supplying the primary identity

  • Call the IMAPISession::QueryIdentity method. For more information, see IMAPISession::QueryIdentity. QueryIdentity searches the status table for the row that contains the value STATUS_PRIMARY_IDENTITY in its PR_RESOURCE_FLAGS column and returns the corresponding PR_IDENTITY_ENTRYID as the entry identifier for the primary identity.


Managing Memory in MAPI

 Copy code hover
[image]

Managing Memory in MAPI
Send feedback

Published: July 16, 2012

Knowing how and when to allocate and free memory is an important part of programming with MAPI. MAPI provides both functions and macros that your client or service provider can use to manage memory in a consistent way. The three functions are as follows:

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

When clients and service providers use these functions, the issue of who "owns" — that is, knows how to release — a particular block of memory is eliminated. A client calling a service provider method need not pass a buffer large enough to hold a return value of any size. The service provider can simply allocate the appropriate amount of memory using MAPIAllocateBuffer and, if necessary, MAPIAllocateMore, and the client can later release it at will using MAPIFreeBuffer, independent of the service provider.

The memory macros are used to allocate structures or arrays of structures of a specific size. Clients and service providers should use these macros rather than allocate the memory manually. For example, if a client needs to perform name resolution processing on a recipient list with three entries, the SizedADRLIST macro can be used to create an ADRLIST structure to pass to IAddrBook::ResolveName with the correct number of ADRENTRY members. All of the memory macros are defined in the MAPIDEFS.H header file. These macros are:

SizedADRLIST | SizedDtblPage
SizedDtblButton | SizedENTRYID
SizedDtblCheckBox | SizedSPropProblemArray
SizedDtblComboBox | SizedSPropTagArray
SizedDtblEdit | SizedSRowSet
SizedDtblGroupBox | SizedSSortOrderSet
SizedDtblLabel |

MAPI also supports the use of the COM interface IMalloc for memory management. Service providers are given an IMalloc interface pointer by MAPI at initialization time and can also retrieve one through the MAPIGetDefaultMalloc function. The main advantage to using the IMalloc methods for managing memory over the MAPI functions is that with the COM methods it is possible to reallocate an existing buffer. The MAPI memory functions do not support reallocation.


Managing Memory for ADRLIST and SRowSet Structures

 Copy code hover
[image]

Managing Memory for ADRLIST and SRowSet Structures
See also Send feedback

Published: July 16, 2012

The requirement to allocate all memory for a buffer whenever possible with a single MAPIAllocateBuffer call does not apply when using the address list, or ADRLIST, and row set, or SRowSet, structures.

These two structures are exceptions to the standard rules for allocating and releasing memory. They contain multiple levels of structures and are designed to enable individual members to be added or removed. Therefore, each property must be a separate allocation. Where most structures are freed with one call to MAPIFreeBuffer, each individual entry in an ADRLIST or SRowSet structure must be freed with its own call to MAPIFreeBuffer or a single call to either FreeProws or FreePadrlist. For more information, see MAPIFreeBuffer, ADRLIST, and SRowSet. FreeProws and FreePadrlist are functions provided by MAPI for simplifying the freeing of these data structures. For more information, see FreeProws and FreePadrlist. FreePadrlist frees the memory for the ADRLIST structure plus all associated memory for the structure members; FreeProws does the same for the SRowSet structure.

The following diagram shows the layout of an ADRLIST data structure, indicating the separate memory allocations required. The gray boxes show memory that can be allocated and released with one call.

ADRLIST memory allocation

ADRLIST memory allocation

See also

Concepts

Managing Memory in MAPI


Allocating and Freeing Memory in MAPI

 Copy code hover
[image]

Allocating and Freeing Memory in MAPI
Send feedback

Published: July 16, 2012

In addition to specifying how to allocate and free memory, MAPI defines a model for knowing when memory passed between public interface method and API function calls should be freed. The model applies only to memory allocated for parameters that are not pointers to interfaces, such as strings and pointers to structures. Interface pointers use the reference counting mechanism implemented through IUnknown. When allocating and freeing non-MAPI related memory internally within a client application or service provider, use whatever mechanism makes sense.

The model defines parameters as one of three types. They can be input parameters, set by the caller with information to be used by the called function or method, output parameters, set by the called function or method and returned to the caller, or input-output parameters, a combination of the two types. Output parameters are frequently pointers to data or pointers to pointers to data. Although the called function is responsible for allocating the data for output parameters, the caller allocates the memory for the pointer.

The rules for allocating and releasing memory for these types of parameters are explained in the following table.

Type | Memory allocation | Memory release
Input | Caller is responsible and can use any mechanism. | Caller is responsible and can use any mechanism.
Output | Called function is responsible and must use MAPIAllocateBuffer. For more information, see MAPIAllocateBuffer. | Caller is responsible and must use MAPIFreeBuffer. For more information, see MAPIFreeBuffer.
Input-output | Caller is responsible for the initial allocation and called function can reallocate if necessary using MAPIAllocateBuffer. | Called function is responsible for initial freeing if reallocation is necessary. Caller must free the final return value.

During failure conditions, implementers of interface methods need to pay attention to output and input-output parameters because the caller generally has no way to clean them up. If an error is returned, then each output or input-output parameter must either be left at the value initialized by the caller or set to a value that can be cleaned up without any action on the part of the caller. For example, an output pointer-parameter of void ** ppv must be left as it was on input or can be set to NULL (*ppv = NULL).


Error Handling in MAPI

 Copy code hover
[image]

Error Handling in MAPI
Send feedback

Published: July 16, 2012

Success, warning, and error values are returned using a 32-bit number known as a result handle, or HRESULT. An HRESULT is really not a handle to anything; it is merely a 32-bit value with several fields encoded in the value. A zero result indicates success and a nonzero result indicates failure.

MAPI on 32-bit platforms works solely with HRESULT values.

The following illustration shows the HRESULT format for 32-bit platforms.

HRESULT format

The high order bit in the HRESULT indicates whether the return value represents success or failure. If set to zero, the value indicates success. If set to 1, it indicates failure.

The R, C, N, and r bits are reserved in the HRESULT.

The facility field in both versions indicates the area of responsibility for the error. There are several facilities, but the vast majority of MAPI errors use FACILITY_ITF to represent interface errors. The most common facilities that are currently used are: FACILITY_NULL, FACILITY_ITF, FACILITY_DISPATCH, FACILITY_RPC, and FACILITY_STORAGE. If new facilities are necessary, Microsoft allocates them because they need to be unique. The following table describes the various facility fields.

Facility | Description
FACILITY_NULL | For broadly applicable common status codes such as S_OK or E_OUTOF_MEMORY; the value is zero.
FACILITY_ITF | For most status codes returned from interface methods; the value is defined by the interface. That is, two HRESULT values with exactly the same 32-bit value returned from two different interfaces might have different meanings.
FACILITY_DISPATCH | For late binding IDispatch interface errors.
FACILITY_RPC | For status codes returned from remote procedure calls.
FACILITY_STORAGE | For status codes returned from IStorage or IStream method calls relating to structured storage. Status codes with code (lower 16 bits) values in the range of Windows error codes (that is, less than 256) have the same meaning as the corresponding Windows errors.

The code field is a unique number that is assigned to represent the error or warning.


Return Value Naming Convention

 Copy code hover
[image]

Return Value Naming Convention
Send feedback

Published: July 16, 2012

The MAPICODE.H header file contains many of the values that a client or service provider might return from an interface method implementation or might see returned from a call.

The codes to represent warning and failure conditions follow a different naming convention that begins with the prefix MAPI, an underscore, and either a W or an E to indicate the type of code. The rest of the code is a short character string to describe the condition. Each word in the string is separated by an underscore. For example, the error value MAPI_E_TOO_COMPLEX indicates that the implementation could not handle whatever was being requested in the call. The warning value MAPI_W_PARTIAL_COMPLETION indicates that the call succeeded, but that there were problems. Only part of the operation was completed successfully.


Using Macros for Error Handling

 Copy code hover
[image]

Using Macros for Error Handling
Send feedback

Published: July 16, 2012

There are several macros for making it easier to work with HRESULT values.

There are two sets of macros that test for failure or success: HR_SUCCEEDED and HR_FAILED and SUCCEEDED and FAILED. SUCCEEDED is the same as HR_SUCCEEDED and FAILED is the same as HR_FAILED.

In this case, use the ResultFromScode macro to set the HRESULT variable to the corresponding HRESULT value for S_OK.

Commonly used macros are briefly described in the following table.

Macro | Description
MAKE_HRESULT | Constructs an HRESULT from its components.
HR_SUCCEEDED | Tests an HRESULT for a success or warning condition.
HR_FAILED | Tests an HRESULT for an error condition.
HRESULT_CODE | Extracts the error code part of the HRESULT.
HRESULT_FACILITY | Extracts the facility from the HRESULT.
HRESULT_SEVERITY | Extracts the severity bit from the SEVERITY.
SUCCEEDED | Tests an HRESULT for a success or warning condition.
FAILED | Tests an HRESULT for an error condition.


MAPI Return Value Documentation

 Copy code hover
[image]

MAPI Return Value Documentation
Send feedback

Published: July 16, 2012

The reference entries in this Reference document only those return values that require some handling by client applications. Return values that indicate common error conditions and can be deduced by checking for failure are not included in the documentation. For example, many interface methods can return MAPI_E_INVALID_PARAMETER if a caller specifies the wrong value for an input parameter. This value is typically not listed in the set of expected return values because there is no need to look specifically for MAPI_E_INVALID_PARAMETER and no need to process it differently from any other error. On the other hand, some service providers do not support event notification and will return MAPI_E_NO_SUPPORT to the Advise method made by clients through IMAPISession. Because clients need to explicitly check for this value and provide code for handling the condition that it represents should it occur, MAPI_E_NO_SUPPORT is included in the list of return values for IMAPISession::Advise.

The following table describes error values that are commonly returned from methods and functions and require explicit handling on the part of a client or service provider. These values fall into four categories: values that indicate invalid input data, values that indicate resource problems, values that indicate character set incompatibility, and values that indicate failure of an unknown origin.

Return value | Description
MAPI_E_INVALID_PARAMETER | One or more of the parameters passed into the method or functions were not valid.
MAPI_E_UNKNOWN_FLAGS | One or more values for a flags parameter were not valid.
MAPI_E_DISK_ERROR | There was a problem writing to or reading from disk.
MAPI_E_NOT_ENOUGH_DISK | Not enough disk space was available to complete the operation.
MAPI_E_NOT_ENOUGH_MEMORY | Not enough memory was available to complete the operation.
MAPI_E_NOT_ENOUGH_RESOURCES | Not enough system resources were available to complete the operation.
MAPI_E_BAD_CHARWIDTH | An incompatibility exists in the character sets supported by the caller and the implementation.
MAPI_E_CALL_FAILED | An error of unexpected or unknown origin occurred.

The constants that represent MAPI return values are listed in the MAPICODE.H header file. Some of the constants map to Win32 errors; the mapping of these constants to numeric values can be found in the Win32 header file, WINERROR.H.

Errors regarding invalid data passed in by a caller can be determined through either the parameter validation API functions provided by MAPI or a set of macros.

Character set incompatibility arises when either of the following situations occurs:

  • A client or service provider sets the MAPI_UNICODE flag on a method or function call and the implementation does not support Unicode. Setting MAPI_UNICODE indicates that character strings passed in as input are Unicode strings and that character strings passed back as output are expected to be Unicode strings.

  • A client or service provider does not set the MAPI_UNICODE flag on a method or function call and the implementation only supports Unicode.


Strategies for Error Handling

 Copy code hover
[image]

Strategies for Error Handling
Send feedback

Published: July 16, 2012

Because interface methods are virtual, it is not possible to know, as a caller, the full set of values that can be returned from any one call. One implementation of a method might return five values; another might return eight. The reference entries in the MAPI documentation list a few values that can be returned for each method; these are the values that your client or service provider can check for and handle because they have special meanings. Other values can be returned, but because they are not meaningful, special code to handle those is not necessary. A simple check for success or failure is adequate.

A few of the interface methods return warnings. If a method that your client or service provider calls can return a warning, use the HR_FAILED macro to test the return value rather than a check for zero or nonzero. Warnings, although nonzero, differ from error codes in that they do not have the high bit set. If your client or service provider does not use the macro, it is likely that a warning might be mistaken for a failure.

Although most interface methods and functions return HRESULT values, some functions return unsigned long values. Also, some methods used in the MAPI environment come from COM and return COM error values rather than MAPI error values. Keep in mind the following guidelines when making calls:

  • Never rely on or use the return values from IUnknown::AddRef or IUnknown::Release. These return values are for diagnostic purposes only.

  • IUnknown::QueryInterface always returns generic COM errors where the facility is FACILITY_NULL or FACILITY_RPC, rather than MAPI errors.

  • All other interface methods return MAPI interface errors with a facility of FACILITY_ITF, or FACILITY_RPC or FACILITY_NULL errors.

When a call is made to an unsupported MAPI method, one of four possible errors can be returned:

MAPI_E_NO_SUPPORT

MAPI_E_INTERFACE_NOT_SUPPORTED

MAPI_E_INVALID_PARAMETER

MAPI_E_VERSION.


MAPI Extended Errors

 Copy code hover
[image]

MAPI Extended Errors
Send feedback

Published: July 16, 2012

Implementers of interface methods can choose to simply return success (S_OK) and failure (MAPI_E_CALL_FAILED) or differentiate between error conditions, returning as many error values as make sense for the situation. Most situations can use one of the error values defined by MAPI in the MAPICODE.H header file. However, for situations that are not covered by a predefined value, the value MAPI_E_EXTENDED_ERROR can be used. MAPI_E_EXTENDED_ERROR indicates to the caller that more information about the error is available. The caller retrieves the additional information by calling the GetLastError method on the same object that returned MAPI_E_EXTENDED_ERROR.

GetLastError can be called to retrieve information about any error code, not only MAPI_E_EXTENDED_ERROR. Many MAPI objects implement interfaces that include the GetLastError method. GetLastError returns a single MAPIERROR structure that, in theory, includes a concatenation of all the errors generated by the previous method call. For more information, see MAPIERROR. As a caller, it is wise not to depend on having this extra error information available because object implementers are not required to provide it. However, it is strongly recommended that whenever implementers return MAPI_E_EXTENDED_ERROR, they make it possible for callers to retrieve a MAPIERROR structure with useful information about the error.

Because GetLastError is also an API function that is part of the Windows SDK, it can be easy to forget that in MAPI, GetLastError is an interface method and can only be called on MAPI objects. Another easy mistake to make is calling GetLastError on the wrong object. GetLastError must be called on the object that generated the error. For example, if your client makes a session call, and MAPI forwards the call to a service provider to do the work, your client should not call GetLastError on the service provider object. IMAPISession::GetLastError is the correct call; GetLastError should be invoked on the session object. For more information, see IMAPISession::GetLastError.


Deferring MAPI Errors

 Copy code hover
[image]

Deferring MAPI Errors
See also Send feedback

Published: July 16, 2012

Some interface methods accept the MAPI_DEFERRED_ERRORS flag as an input parameter. When this flag is set, the method does not have to return immediately with a value; it can let the caller know the result of the call at some later time.

Deferring errors helps service providers in their implementation of complex methods, making processing faster. Rather than handling many requests and returning a value for each, deferring errors allows the calls to be bundled within the service provider. Processing many requests at once cuts down on network traffic, thereby improving performance. Deferring errors is especially useful in calls to delete or copy properties, which can be very time-consuming operations.

When a client makes a call without setting the MAPI_DEFERRED_ERRORS flag that can only be handled in a deferred manner, service providers can either defer the errors regardless or return MAPI_E_TOO_COMPLEX. Most clients should defer errors as a preferable strategy to failing the call.

Setting the MAPI_DEFERRED_ERRORS flag changes a client's error handling implementation in that the returned information can be delivered at any time rather than at a planned time. It is possible for an error to be returned when it is too late to do anything about it or after data about the original request is no longer available. For example, if a client calls IMsgStore::OpenEntry to open a deleted folder with MAPI_DEFERRED_ERRORS set, the client will not know of the problem until an IMAPIProp::GetProps call is made to retrieve one of the folder's properties. GetProps will then return MAPI_E_NOT_FOUND.

See also

Reference

IMsgStore::OpenEntry
IMAPIProp::GetProps


Sending Messages by Using MAPI

 Copy code hover
[image]

Sending Messages by Using MAPI
See also Send feedback

Published: July 16, 2012

Client applications call the IMessage::SubmitMessage method to send a message. SubmitMessage calls IMAPIProp::SaveChanges to save the message before transferring control to either the MAPI spooler or directly to a transport provider.

The MAPI spooler receives the message if any of the following occur:

  • The message store provider and transport provider are not tightly coupled.

  • The message requires preprocessing.

  • The tightly coupled message store and transport cannot handle all of the recipients to whom the message is addressed.

A tightly coupled message store must take into account a message's status before it presents it to the MAPI spooler to be downloaded to a transport provider. There are situations where a message may appear to require the MAPI spooler, but the MAPI spooler should really not be involved.

For example, consider the situation where a user submits a message from the Inbox. The client is using a tightly coupled store and transport. If the tightly coupled message store uses the message's location as the sole criteria for deciding about whether or not to allow the MAPI spooler to handle the message, the MAPI spooler will always receive the message. To avoid this kind of problem, a tightly coupled message store must check the message status in addition to message location. Specifically, the transport provider should not request that the MAPI spooler download any message that is actively submitted.

The message transmission process involves the message store provider, one or more transport providers, and MAPI. The topics in this section provide detailed information about specific roles in the message transmission process.

See also

Reference

IMessage::SubmitMessage
IMAPIProp::SaveChanges


Delegate Access

 Copy code hover
[image]

Delegate Access
Send feedback

Published: July 16, 2012

Delegate access refers to the user's ability to send a message as another user or receive a message for another user. Delegate access is a service provider-independent feature of MAPI that transport providers can support if they choose. However, no provider is required to do so. Delegate access is valuable when it is necessary for a user to send messages as, or filter incoming messages for, another user or when a user must access another user's message store. Before allowing a delegate user to connect to another user's store, the message store provider must verify that the delegate user has the proper authority.

There are two groups of properties that are used to support delegate access:

PR_SENT_REPRESENTING_ADDRTYPE (PidTagSentRepresentingAddressType)

PR_SENT_REPRESENTING_EMAIL_ADDRESS (PidTagSentRepresentingEmailAddress)

PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId)

PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName)

PR_SENT_REPRESENTING_SEARCH_KEY (PidTagSentRepresentingSearchKey)

PR_RCVD_REPRESENTING_ADDRTYPE (PidTagReceivedRepresentingAddressType)

PR_RCVD_REPRESENTING_EMAIL_ADDRESS (PidTagReceivedRepresentingEmailAddress)

PR_RCVD_REPRESENTING_ENTRYID (PidTagReceivedRepresentingEntryId)

PR_RCVD_REPRESENTING_NAME (PidTagReceivedRepresentingName)

PR_RCVD_REPRESENTING_SEARCH_KEY (PidTagReceivedRepresentingSearchKey)

On outgoing messages, the PR_SENT_REPRESENTING properties identify the messaging user that should act as the sender. Clients can set these properties as an option. If the PR_SENT_REPRESENTING properties are not set by the time the message reaches a transport provider that supports delegate access, it is the provider's responsibility to set them along with the PR_SENDER properties.

On incoming messages, the PR_RCVD_REPRESENTING properties identify the user that should act as the recipient. Transport providers responsible for delivering delegate messages must set both the PR_RCVD_REPRESENTING and PR_RECEIVED_BY properties. Clients receiving a delegate message should copy the values of the PR_SENT_REPRESENTING properties to the corresponding PR_RCVD_REPRESENTING properties.

For example, suppose John is receiving Sally's messages while Sally is on vacation. The PR_RCVD_REPRESENTING properties identify John as the delegate recipient. When John sends a reply to a message that he has received for Sally, the message's PR_SENDER properties identify John as the sender. Because John is representing Sally, the PR_SENT_REPRESENTING properties identify Sally.

Transport providers handling incoming delegate messages should usually deliver these messages as the messaging user identified by the PR_SENT_REPRESENTING properties rather than as the user identified by the PR_SENDER properties. The exception to this rule is when it is necessary to match access privilege and transport types. In this case, a transport provider can choose a sending identity.

If the PR_SENT_REPRESENTING properties are unavailable for an incoming delegate message, the transport provider handling delivery must set them, using the values of the corresponding PR_SENDER properties. If the PR_SENT_REPRESENTING properties are available but the transport provider does not support delegate access, it can use the PR_SENDER properties for delivery.


Sending Messages with TNEF

 Copy code hover
[image]

Sending Messages with TNEF
Send feedback

Published: July 16, 2012

Many transport providers automatically send all outgoing messages with the Transport Neutral Encapsulation Format (TNEF). TNEF is used to transmit the formatted text that many clients and message store providers support in their messages, attachments of various types, and custom properties for custom message classes. Although the default mode for most transport providers is to send outgoing messages with TNEF, some transport providers do not support it. The lack of support for TNEF is not an issue for standard messaging clients that send and receive IPM messages. However, for form-based clients or clients that require custom properties, the use of TNEF is essential. Designers of clients that rely on forms or custom properties must be aware of the capabilities of the transport providers that they use.

Message recipients can control whether or not a transport provider transmits messages with TNEF by setting the PR_SEND_RICH_INFO property. For more information, see PR_SEND_RICH_INFO (PidTagSendRichInfo). When a recipient's PR_SEND_RICH_INFO property is set to TRUE, a transport provider that supports TNEF transmits it with the message. When the property is set to FALSE, the formatting is discarded. When PR_SEND_RICH_INFO does not exist, it is up to the transport provider to choose a default course of action.

When clients and service providers create a custom recipient, they can affect the value of its PR_SEND_RICH_INFO property by passing the MAPI_SEND_NO_RICH_INFO flag in the ulFlags parameter to the IAddrBook::CreateOneOff or IMAPISupport::CreateOneOff call. For more information, see IAddrBook::CreateOneOff and IMAPISupport::CreateOneOff. Passing MAPI_SEND_NO_RICH_INFO causes MAPI to set the custom recipient's PR_SEND_RICH_INFO property to FALSE; in most cases not passing the flag causes MAPI to set the property to TRUE. The one exception is if the custom recipient's address is interpreted to be an Internet address. In this one situation, MAPI sets PR_SEND_RICH_INFO to FALSE.


Sending Messages: MAPI Spooler Tasks

 Copy code hover
[image]

Sending Messages: MAPI Spooler Tasks
Send feedback

Published: July 16, 2012

The MAPI spooler is involved in the message transmission process when the message store is not tightly coupled with a transport provider, when the tightly coupled store and transport cannot handle a recipient, and when the message requires preprocessing.

After any necessary preprocessing, the MAPI spooler performs the following steps:

  1. If the message is not locked, locks the message by using the IMsgStore::SetLockState method.

  2. Has the transport provider send the message to all recipients that have their PR_RESPONSIBILITY (PidTagResponsibility) property set to FALSE.

  3. Calls the appropriate function (RemovePreprocessInfo) for cleaning up any additional information that was added to the message for use during preprocessing if the PR_PREPROCESS (PidTagPreprocess) property has been set. This function is specified when the transport provider registers its preprocessor function.

  4. Calls IMsgStore::FinishedMsg method. In FinishedMsg, the message store provider:

    • Unlocks the message.

    • Calls the IMAPISupport::DoSentMail method to perform outbound hook processing if a messaging hook provider exists. It then copies the message to the folder identified by the entry identifier in the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property, if not superseded by a messaging hook provider's sent message processing. Finally, it deletes the message if the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property has been set to TRUE.


Sending Messages: Message Store Provider Tasks

 Copy code hover
[image]

Sending Messages: Message Store Provider Tasks
Send feedback

Published: July 16, 2012

A message store provider gets involved with the message sending process when a client calls the message's IMessage::SubmitMessage method. If multiple messages are to be sent, the message store must send them in the same order that the client used for its SubmitMessage calls.

The message store provider determines whether or not to involve the MAPI spooler. If the message store provider is not tightly coupled, the message requires preprocessing, or the tightly coupled store and transport cannot handle all of the recipients, the MAPI spooler must be involved.

The following procedure describes the tasks required of a message store provider for sending a message.

In IMessage::SubmitMessage, the message store provider

  1. Calls IMAPISupport::PrepareSubmit if the message has the MSGFLAG_RESEND flag set in its PR_MESSAGE_FLAGS (PidTagMessageFlags) property and returns any errors to the client. PrepareSubmit checks the PR_RECIPIENT_TYPE (PidTagRecipientType) property of each recipient in the message's recipient list.

    • If the MAPI_SUBMITTED flag is set, indicating that the recipient did not receive the original message, PrepareSubmit clears the flag and sets the PR_RESPONSIBILITY (PidTagResponsibility) property to TRUE.

    • If the MAPI_SUBMITTED flag is not set, indicating that the recipient did receive the original messsage, PrepareSubmit changes the PR_RECIPIENT_TYPE property to MAPI_P1 and sets the PR_RESPONSIBILITY property to TRUE and returns any error generated by PrepareSubmit to the client.

  2. Sets the MSGFLAG_SUBMIT flag in the message's PR_MESSAGE_FLAGS property.

  3. Makes sure that there is a column for PR_RESPONSIBILITY in the recipient table and sets it to FALSE to indicate that no transport has of yet assumed responsibility for transmitting the message.

  4. Sets the date and time of origination in the PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) property.

  5. Calls IMAPISupport::ExpandRecips to:

    • Expand all personal distribution lists and custom recipients and replace all changed display names with their original names.

    • Remove duplicate names.

    • Check for any required preprocessing, and if preprocessing is required, set the NEEDS_PREPROCESSING flag and the PR_PREPROCESS (PidTagPreprocess) property, a property reserved for MAPI.

    • Set the NEEDS_SPOOLER flag if the message store is tightly coupled with a transport and it cannot handle all of the recipients.

  6. Performs the following tasks if the NEEDS_PREPROCESSING message flag is set:

    • Puts the message in the outgoing queue with the SUBMITFLAG_PREPROCESS bit set in the PR_SUBMIT_FLAGS (PidTagSubmitFlags) property.

    • Notifies the MAPI spooler that the queue has changed.

    • Returns control to the client, and message flow continues in the MAPI spooler.

    • The MAPI spooler performs the following tasks:

      1. Locks the message by calling IMsgStore::SetLockState.

      2. Performs the needed preprocessing by calling all of the preprocessing functions in the order of registration. Transport providers call IMAPISupport::RegisterPreprocessor to register preprocessing functions.

      3. Calls IMessage::SubmitMessage on the open message to indicate to the message store that preprocessing is complete.

Note Note

The following two steps will occur in the client process if there was no preprocessing and will occur when the MAPI spooler calls SubmitMessage if there was preprocessing.

  1. Performs the following tasks if the message store is tightly coupled to a transport and the NEEDS_SPOOLER flag was returned from IMAPISupport::ExpandRecips:

    • Handles any recipients that it can handle.

    • Sets the PR_RESPONSIBILITY property to TRUE for any recipients that it handles.

    • Performs the following tasks if all recipients are known to this tightly coupled store and transport:

      1. Calls IMAPISupport::CompleteMsg if the message was preprocessed or the message store provider wants the MAPI spooler to complete message processing which is recommended so that messaging hooks can be invoked. Message flow continues with the MAPI spooler as described in the following procedure.

      2. Performs the following tasks if the message was not preprocessed or the message store provider does not want the MAPI spooler to complete message processing:

        • Copies the message to the folder identified by the entry identifier in the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property, if set.

        • Deletes the message if the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property has been set to TRUE.

        • Unlocks the message if it is locked.

        • Returns to the client. Message flow is complete.

  2. Performs the following tasks if the message store is not tightly coupled to a transport, not all of the recipients were known to the message store, or the NEEDS_SPOOLER flag is set:

    • Puts the message in the outgoing queue without setting the SUBMITFLAG_PREPROCESS bit in the PR_SUBMIT_FLAGS property.

    • Notifies the MAPI spooler that the outgoing queue has changed by generating a table notification.

    • Returns to the client, and message flow continues with a set of tasks performed by the MAPI spooler.

When a message is to be handled by the MAPI spooler, the message store provider sets the message's PR_SUBMIT_FLAGS property to SUBMITFLAG_LOCKED. The SUBMITFLAG_LOCKED flag indicates that the MAPI spooler has locked the message for its exclusive use. The other value for PR_SUBMIT_FLAGS, SUBMITFLAG_PREPROCESS, is set when the message requires preprocessing by one or more preprocessor functions registered by a transport provider.


Sending Messages: Transport Provider Tasks

 Copy code hover
[image]

Sending Messages: Transport Provider Tasks
Send feedback

Published: July 16, 2012

To transmit a message, transport providers

  • Set the message's PR_RESPONSIBILITY (PidTagResponsibility) property to TRUE after the transport provider has either sent the message or attempted to send the message. If an attempt to send a message fails, transport providers should call IMAPISupport::StatusRecips to generate a nondelivery report. If the message is sent successfully and the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) property is set to TRUE, create an ADRLIST structure containing the successful recipients, setting the PR_DELIVER_TIME (PidTagDeliverTime) property for each, and call StatusRecips to generate a delivery report. For more information about creating delivery and non-delivery reports, see the following topics: MAPI Report Messages, Required Report Message Properties, Optional Report Message Properties, and Sending Message Delivery Reports.

  • Set the message's PR_SENDER group of properties to the identity of the user that has logged on. This group includes: PR_SENDER_ENTRYID (PidTagSenderEntryId), PR_SENDER_NAME (PidTagSenderName), PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey), PR_SENDER_ADDRTYPE (PidTagSenderAddressType), and PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress).

  • Set the message's PR_SENT_REPRESENTING properties, if possible, to either the identity of the user that has logged on or to a valid delegate identity. The PR_SENT_REPRESENTING properties are used to implement the sending of messages by one user on behalf of another user. Transport providers that do not support these properties should ignore them on outbound messages.

  • Set the message's PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) property to indicate when the client called IMessage::SubmitMessage.

  • Set the message's PR_PROVIDER_SUBMIT_TIME (PidTagProviderSubmitTime) property to indicate the date and time that the message store provider marked the message as having been sent.

When a message is sent to a variety of recipients with several messaging systems, each transmitted copy will have a different sender identity.

The transport provider or tightly coupled message store and transport is also responsible for setting originator and reply-to information. Originator information is stored in the PR_ORIGINATOR properties and reply-to information is stored in the PR_REPLY properties. The client can set these properties; however, the transport provider is allowed to ignore and overwrite the client's settings.


Sending Across Messaging Domains

 Copy code hover
[image]

Sending Across Messaging Domains
Send feedback

Published: July 16, 2012

A messaging domain represents one or more messaging systems that share a common address format. Communication across multiple messaging domains involves translating a message sent in the format of the original messaging domain into the format of the destination messaging domain. Because not all address formats are compatible, a gateway is needed to translate the addressing information from the source format into the destination format. To ensure validity across messaging domains, client applications store important addressing information in MAPI properties. In addition, gateways perform the translation, examining the properties known to need translation and changing them to a format that the destination messaging domain can use.

Previously, MAPI allowed this addressing information to be associated with only the users who comprise a message's current recipient list. The properties describing each member of the recipient list underwent the required translation by the gateway to ensure validity across messaging domains. However, some applications require that their messages include addressing information about users that perhaps were recipients in the past, will be recipients in the future, or will never be recipients. For example, routing applications, which send messages in a specified order to a group of users, embed addressing information about these users in the messages. The embedded information typically includes the address and address type of the future recipients, and perhaps also their roles and positions in the routing order, their names, and one or more binary identifiers per recipient.

To enable messages to include information about these nonrecipient users, MAPI now includes a strategy for ensuring that this nonrecipient information is also translated correctly across messaging domains. This strategy is based on the concept of gateway-mappable properties.


Gateway Mappable Properties

 Copy code hover
[image]

Gateway Mappable Properties
Send feedback

Published: July 16, 2012

Gateway-mappable properties are properties that may require translation when sent from one messaging domain to another. MAPI's gateway-mappable properties enable messages to include information that requires a gateway to ensure the destination messaging system uses it properly. Although gateway developers are not required to provide this translation capability, they should consider gateway-mappable properties as an opportunity to improve handling of message content.

MAPI specifies five types of gateway-mappable properties:

  • Display name

  • E-mail address

  • E-mail type

  • Entry identifier

  • Search key

This is the set of addressing properties that are associated with recipients, senders, report recipients, and delegated senders and recipients. To help your client define these properties so that a gateway handles them specially, MAPI specifies a naming convention using named properties and property sets. Five property sets exist to hold named properties, the addressing properties that require mapping. There is one property set for each type of mappable property. The property sets that will hold these named addressing properties are as follows.

Property set | Description
PS_ROUTING_DISPLAY_NAME | Contains string properties used as display names.
PS_ROUTING_EMAIL_ADDRESSES | Contains string properties used as e-mail addresses.
PS_ROUTING_ADDRTYPE | Contains string properties used as e-mail address types.
PS_ROUTING_ENTRYID | Contains binary properties used as long-term entry identifiers.
PS_ROUTING_SEARCH_KEY | Contains binary properties used as search keys.


Client Naming Responsibilities

 Copy code hover
[image]

Client Naming Responsibilities
Send feedback

Published: July 16, 2012

Clients must follow a naming convention for their properties that need to be translated by a gateway. All properties to be translated should be created as named properties in one of the five property sets designated to hold mappable properties:

PS_ROUTING_EMAIL_ADDRESSES

PS_ROUTING_ADDRTYPE

PS_ROUTING_DISPLAY_NAME

PS_ROUTING_ENTRYID

PS_ROUTING_SEARCH_KEY

Addressing properties that relate to the same user must be given the same name. Gateways rely on this naming convention, which enables them to match an address with its correct address type. For address parsing, the mapping between address and address type must be accurate.

MAPI named properties are represented with the MAPINAMEID data structure, which specifies that the property name can be either a Unicode string or a 32-bit integer. For more information, see MAPINAMEID. Integer naming is recommended for groups of addresses because it is a straightforward way to differentiate between sets of mappable properties, and it can easily serve as an index to the user. The alternative to using integers is to assign one string as the name for all five of a user's mappable properties. If only one user requires mapping, assigning a string is acceptable. However, when there are multiple users, it is better to use integer naming. The name, whether it be numeric or string-based, should be stored in either a message class-specific property or in a property belonging to a property set that is defined by the client application.

Note Note

Avoid translating integer names to strings, such as "route_recipient_1" and "route_recipient_2." This effort is unnecessary.

To illustrate how this naming convention works, consider a routing application that sends a message to each member of a four-person team. When one member receives the message, he or she must respond to it before it can be sent along with the compiled responses to the next member. The original message contains a recipient list with one entry: the first member of the team. Embedded within the message are the gateway-mappable properties for the other three team members. Each member has five core user properties residing in the gateway-mappable property sets, that are assigned a unique number as a name.

The following table illustrates the settings for each set of gateway-mappable properties stored for the three remaining team members to whom the message is routed when the first team member is finished with it.

Property Set | Second Team Member | Third Team Member | Fourth Team Member
PS_ROUTING_EMAIL_ADDRESSES | Address = 0 | Address = 1 | Address = 2
PS_ROUTING_ADDRTYPE | Address type = 0 | Address type = 1 | Address type = 2
PS_ROUTING_DISPLAY_NAME | Display name = 0 | Display name = 1 | Display name = 2
PS_ROUTING_ENTRYID | Entry identifier = 0 | Entry identifier = 1 | Entry identifier = 2
PS_ROUTING_SEARCH_KEY | Search key = 0 | Search key = 1 | Search key = 2

Clients that use mappable search keys as references to other message properties must recognize that the other message properties will not be translated unless they are placed in one of these mappable property sets. When a message with unmapped references to mapped search keys is sent to a destination in another messaging domain, the references are invalid. To enable these other properties to remain synchronized with the search keys, you can assign them string names in the PS_ROUTING_SEARCH_KEY property set that do not interfere with the names given to any of the core mappable properties. For example, suppose a client needs to transmit a property that contains the search key for the last person in a long routing list. The client can create a named property in the PS_ROUTING_SEARCH_KEY property set called "last_search_key." Because it is stored in a mappable property set, the "last_search_key" property is translated along with the rest of the gateway-mappable properties.


Gateway Mapping Responsibilities

 Copy code hover
[image]

Gateway Mapping Responsibilities
Send feedback

Published: July 16, 2012

When a MAPI-aware gateway receives a message containing named properties in one of the special property sets designated to contain gateway-mappable properties, the gateway should map all of the properties to the protocol of the destination messaging system. Although MAPI recommends that gateways handle all named properties in the special property sets, gateways are expected to handle only two: e-mail address and address type. Because the e-mail address and address type properties directly affect message transmission, it is critical that gateways support the mapping of these two properties. Because search keys consist of a user's address type and address, they should also be translated if at all possible.

Entry identifiers are not expected to be handled frequently. To enable mapping of an entry identifier that originates in one messaging system to an entry identifier that is usable by another messaging system, the gateway must be able to use the format of both systems. Because most gateways are not aware of entry identifier formats, the translation of entry identifiers is rare.

Another mappable property that is not expected to be translated frequently is the display name. Gateways should store display names and transmit them, but not necessarily translate them.


Event Notification in MAPI

 Copy code hover
[image]

Event Notification in MAPI
Send feedback

Published: July 16, 2012

Event notification is the communication of information between two MAPI objects. Through one of the objects, a client or service provider registers for notification of a change or error, called an event, which may take place in the other object. After the event occurs, the first object is notified of the change or error. The object receiving the notification is called the advise sink; the object responsible for the notification is called the advise source.

There are three types of advise sink objects (all types are standard MAPI objects):

  • Advise sink objects.

  • Form advise sink objects.

  • View advise sink objects.

Advise sink objects are the most common type. Advise sinks are typically implemented by client applications to receive address book and message store notifications and support the IMAPIAdviseSink : IUnknown interface. IMAPIAdviseSink contains a single method, IMAPIAdviseSink::OnNotify. Form and view advise sinks are less common; they are implemented to receive notifications about changes to custom forms. Form advise sinks support the IMAPIFormAdviseSink : IUnknown interface and view advise sinks support the IMAPIViewAdviseSink : IUnknown interface. Because most clients implement standard advise sink objects, assume that discussions of notifications relate to address book and message store notifications rather than forms notifications. For more information about forms notifications, see MAPI Forms Notifications and Writing Form Server Code.

Advise source objects are implemented by service providers and by MAPI. Not all service providers support event notification; it is optional, but strongly recommended. Message store and address book providers usually support object notifications on several of their objects and table notifications on their contents and hierarchy tables. Transport providers do not support notifications directly; they rely on alternative methods of communication with clients.

Unlike advise sinks, advise source objects are not a unique type of MAPI object. Many MAPI objects, such as message stores and tables, can take on the role of advise source. An advise source is any MAPI object that does the following:

  • Implements an Advise method to receive notification registrations.

  • Implements an Unadvise method to receive notification cancellations.

  • Generates notifications of the appropriate type to the appropriate advise sink objects that have registered by calling their IMAPIAdviseSink::OnNotify methods.

Clients that implement advise sink objects call Advise when they want to register for a notification, in most cases passing in the entry identifier of the object with which registration should occur, and Unadvise when they want to cancel the registration. Clients pass a parameter to Advise that indicates which of the several types of events they want to monitor. Advise returns a nonzero number that represents a successful connection between the advise sink and advise source.

Before calling Advise, clients can determine whether a message store provider supports notification by checking that the STORE_NOTIFY_OK flag is set in the message store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property. There is no way for clients to determine ahead of time whether or not an address book provider supports notifications. Clients must attempt to register and if the attempt fails, they can assume notifications are unsupported.

When an event for which a client has registered occurs, the advise source notifies the advise sink by calling its IMAPIAdviseSink::OnNotify method with a notification data structure that contains information about the event. An advise sink's implementation of OnNotify can perform tasks in response to the notification, such as updating data in memory or refreshing a screen display.

Service providers can implement support for notifications manually or take advantage of the help provided in three IMAPISupport methods: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. The Subscribe and Unsubscribe methods handle notification registration and deregistration for providers; the Notify method handles sending notifications when appropriate.

To use the support object methods for notification registration, service providers call IMAPISupport::Subscribe in their Advise methods and pass to Subscribe the advise sink pointer that clients pass to Advise. If an entry identifier is passed as an input parameter to specify an advise source, service providers convert it to a binary key. Subscribe creates a unique connection number and it is this number that service providers return to clients. Service providers can release the client's advise sink object pointer at any time after the Advise call has completed.

When clients call Unadvise to cancel a registration, service providers either decrement the reference count on the client's advise sink pointer or call Unsubscribe to do the same.

When it is time to generate a notification, service providers perform any internal processing that relates to the notification and initializes a NOTIFICATION structure by setting all of its unused members to zero. This technique for initializing the NOTIFICATION structure can help clients create smaller, faster, and less error-prone OnNotify implementations.

The following illustration shows the communication between advise sink objects, advise source objects, and MAPI. MAPI is involved only when the advise source calls the IMAPISupport methods for notification support.

Event notification calls

Event notification calls

The MFCMAPI CAdviseSink class (using the AdviseSink.h and AdviseSink.cpp files) implements the advise sink object for all calls to Advise. For more information about MFCMAPI, see MFCMAPI as a Code Sample and MFCMAPI.


MAPI Notification Events

 Copy code hover
[image]

MAPI Notification Events
Send feedback

Published: July 16, 2012

When client applications register for event notification, they must specify one or more events. The events that they can specify depend on the set of events that the intended advise source supports. There are ten types of notifications that clients and service providers can register for, each represented by a constant. Status object notification is an exception. Status object notification is an internal MAPI notification; clients cannot register for it and service providers cannot generate it. The following table describes the types of events and the advise source objects that can support them. The event constant is included with the event type.

Event type | Description | Advise source objects
Critical error (fnevCriticalError) | A global error or event has occurred, such as a session shutdown in progress. | Session, all types of message store and address book objects, table, status
Object modified (fnevObjectModified) | A MAPI object has changed. | Folders, messages, all types of address book objects
Object created (fnevObjectCreated) | A MAPI object has been created. | Folders, messages, all types of address book objects
Object moved (fnevObjectMoved) | A MAPI object has been moved. | Folders, messages, all types of address book objects
Object deleted (fnevObjectDeleted) | A MAPI object has been deleted. | Folders, messages, all types of address book objects
Object copied (fnevObjectCopied) | A MAPI object has been copied. | Folders, messages, all types of address book objects
Extended event (fnevExtended) | An internal event defined by a particular service provider has occurred. | Any advise source object
Search complete (fnevSearchComplete) | A search operation has finished and the results of the search are available. | Folders
Table modified (fnevTableModified) | Information in a MAPI table object has changed. | Tables
New mail (fnevNewMail) | A message has been delivered and is waiting to be processed. | Message store, folders

The extended event is defined by a service provider to represent an event that cannot be covered by any of the other predefined events. Only clients that know before they register that a service provider supports an extended event can register for that event. It is not possible for clients to determine without advance knowledge if a service provider supports an extended event and, if it does, how to handle such an event when it is received.


MAPI Forms Notifications

 Copy code hover
[image]

MAPI Forms Notifications
Send feedback

Published: July 16, 2012

Registering for and handling notifications from form objects is a different process than for other MAPI objects. Advise sinks for form notifications implement either the IMAPIViewAdviseSink or IMAPIFormAdviseSink interface rather than IMAPIAdviseSink. IMAPIViewAdviseSink : IUnknown and IMAPIFormAdviseSink : IUnknown each have multiple methods, one for each of the possible events that the corresponding advise source is capable of generating. For example, IMAPIFormAdviseSink has two methods: IMAPIFormAdviseSink::OnChange to handle a change to the form viewer's status and IMAPIFormAdviseSink::OnActivateNext to display a new message with the correct form.

The event handling strategy for forms is similar to the event handling strategy implemented in OLE. Clients do not register for specific event types as they do for most MAPI objects. The assumption is that registering for notification enables them to receive any type of event that can be generated by the particular advise source. Because IMAPIAdviseSink::OnNotify must be written so as to handle all registered events, implementing it can be complex for clients that register for many different events. Because the methods in the form advise sink objects target a single event, implementing these methods is simpler.


Threading in MAPI

 Copy code hover
[image]

Threading in MAPI
Send feedback

Published: July 16, 2012

A thread is the basic entity to which an operating system allocates CPU time. A thread has its own registers, stack, priority, and storage, but shares an address space and process resources such as access tokens. Threads also share memory, with one thread reading what another thread has written.

MAPI clients use the following generic threading models.

Threading model | Description
Single threading model | All objects are used on the single thread.
Apartment threading model | An object can be used only on the thread that created it.
Free threading, or thread-party, model | An object can be used on any thread.

MAPI uses the free threading model, supporting thread-safe objects that can be used on any thread at any time. OLE uses the apartment threading model. The apartment threading model supports objects that must be explicitly transferred when a thread other than the one that created the object needs to use that object.

The mechanism that OLE uses to transfer objects from one thread to another is known as marshaling. Marshaling involves a stub object and a proxy object. These special objects package the parameters of the interface in the object to be marshaled, transfer these parameters to the other thread, and unpackage them upon arrival. Conflict between the two multithreaded models arises when a free-threading MAPI object is sent to another process using OLE "lightweight" Remote Procedure Call, or LRPC. LRPC changes the object's semantics from free threading to apartment threading by interposing stub and proxy interfaces with apartment threading behavior between the object and its caller. Awareness of the situations in MAPI that lead to this conflict can help clients and service providers prevent problems from occurring.

A MAPI object can be accessed:

  • Through direct calls to its methods using an interface pointer returned by a service provider or MAPI linked to the client's process, such as the session object returned from MAPILogonEx.

  • Through indirect calls to its methods using an interface pointer returned by any service provider, such as the folder object copied from another folder in IMAPIFolder::CopyFolder.

  • Through a callback function, such as the IMAPIAdviseSink::OnNotify method passed to a service provider or to MAPI in an Advise call or the methods that can show progress on a lengthy operation.


Using Thread-Safe Objects

 Copy code hover
[image]

Using Thread-Safe Objects
Send feedback

Published: July 16, 2012

Client applications can assume that objects used directly or as callbacks are always thread-safe except in the following cases:

  • A transport provider's status object obtained through a client call to IMAPISession::OpenEntry with an entry identifier from the provider's status table row.

  • All MAPI form objects obtained through a client call to MAPIOpenFormMgr. Form objects obey apartment model rules and clients must use them and all objects contained by them only on the thread that created them.

When a client accesses a transport provider's row in the status table that includes the entry identifier of the associated status object, the client can call OpenEntry with that entry identifier to open the status object. This status object is not thread-safe because transport providers run in the context of the MAPI spooler and do not maintain a separate context for their status object. The status object obeys apartment model rules and clients must use it only on the thread that created it.

A client must also invoke MAPIInitialize on every thread before using any MAPI objects and MAPIUninitialize when that use is complete. These calls should be made even if the objects to be used are passed to the thread from an external source. MAPIInitialize and MAPIUninitialize can be called from anywhere except from within a Win32 DllMain function, a function that is invoked by the system when processes and threads are initialized and terminated, or upon calls to the LoadLibrary and FreeLibrary functions.

Indirect use objects should never be assumed to be thread-safe. Indirect use objects are returned by methods that require destination interface pointers as input parameters. Examples of such methods are IMAPIProp::CopyTo and CopyProps, IMAPIFolder::CopyFolder and CopyMessage, and IMsgServiceAdmin::CopyMsgService. If a service provider wants to call such an object from a thread other than the one on which it was passed, the provider is responsible for explicitly marshaling the object.


Implementing Thread-Safe Objects

 Copy code hover
[image]

Implementing Thread-Safe Objects
Send feedback

Published: July 16, 2012

With objects that are returned from interface method calls directly, it is the provider's responsibility to ensure thread-safety. With callback objects, it is the client application's responsibility.

A client can implement a thread-safe notification callback by calling the MAPI utility HrThisThreadAdviseSink. HrThisThreadAdviseSink transforms a non-thread-safe advise sink into a thread-safe one. For progress callbacks, there is no such utility. A client can choose to use the MAPI thread-safe progress object or create one manually.

A thread-safe object might or might not also be thread-aware. A thread-aware object maintains a separate context for every thread that is using it. Service providers are not required to support thread-awareness in their thread-safe objects, although supporting thread-awareness can be useful in some situations. Two MAPI tables always provide their own context by definition. One table used on different threads does not and should not provide unique context.

A client can choose between receiving notifications on the same thread that was used for the MAPIInitialize call, on the same thread that was used for the Advise call, or on a separate thread owned by MAPI. To ensure that notifications arrive on the same thread that was used to call MAPIInitialize, a client calls MAPIInitialize and passes zero in the ulFlags member of the MAPIINIT_0 structure. Notifications are then delivered during the main message loop.

To receive notifications on the MAPI-owned thread, a client calls MAPIInitialize with the ulFlags member of the MAPIINIT_0 structure set to MAPI_MULTITHREAD_NOTIFICATIONS. The Advise call is made with the client's advise sink object rather than a wrapped version.

To ensure that notifications arrive on the same thread that was used to call Advise, a client calls HrThisThreadAdviseSink and passes the newly created wrapped advise sink to Advise rather than the original advise sink. MAPIInitialize can be called with either flag value.


Client Shutdown in MAPI

 Copy code hover
[image]

Client Shutdown in MAPI
Send feedback

Published: July 16, 2012

Beginning in Microsoft Outlook 2010 and now including Microsoft Outlook 2013, MAPI clients can shut down the same way as before, or they can use fast shutdown. For fast shutdown to occur successfully, the MAPI client, MAPI provider, and administrator of the client computer have to support fast shutdown.

The topics in this section describe MAPI support for a client to perform fast shutdown.

Fast Shutdown Overview

This topic introduces the basic mechanism of fast shutdown.

Fast Shutdown User Options

This topic describes the choices available for administrators to adopt fast shutdown at the user level for the user's MAPI clients.

Best Practices for Fast Shutdown

This topic recommends best practices to use the fast shutdown interfaces to help prevent data loss during a MAPI client shutdown.


Fast Shutdown Overview

 Copy code hover
[image]

Fast Shutdown Overview
See also Send feedback

Published: July 16, 2012

Fast shutdown is a mechanism for a MAPI client to initiate a quick shutdown of the client process, notifying all providers with which the client has an active MAPI session to save data and settings before the client process exits. This topic describes the basic mechanism of fast shutdown.

Starting in Microsoft Outlook 2010 and now including Microsoft Outlook 2013, the MAPI subsystem provides the IMAPIClientShutdown : IUnknown interface. Outlook and other MAPI clients can adopt fast shutdown as the default mechanism to exit the client process. A user-level setting in the Windows registry of the client computer controls the adoption of fast shutdown for all MAPI clients for that user on that computer. For details about the registry settings, see Fast Shutdown User Options.

If a MAPI client needs to adopt fast shutdown, it must use the IMAPIClientShutdown : IUnknown interface. The following is the typical course of events when the client attempts to shut down:

  1. The MAPI client initiates the shutdown by calling the IMAPIClientShutdown::QueryFastShutdown method to determine whether the MAPI subsystem supports fast shutdown.

  2. The MAPI subsystem responds with the available fast shutdown support to the client's IMAPIClientShutdown::QueryFastShutdown call by using the following procedure:

    1. The MAPI subsystem calls the IMAPIProviderShutdown::QueryFastShutdown method for each MAPI provider with which the MAPI client process has an active MAPI session, if the provider has implemented the IMAPIProviderShutdown : IUnknown interface.

      Note Note

      The MAPI subsystem always queries and notifies MAPI providers through the IMAPIProviderShutdown : IUnknown interface within each MAPI session in the following order:

      1. Transport providers.

      2. Address book providers.

      3. Store providers.

    2. Depending on the fast shutdown registry setting for that user on the client computer, the MAPI subsystem specifies the appropriate return code to IMAPIClientShutdown::QueryFastShutdown. The return code is either S_OK or MAPI_E_NO_SUPPORT.

  3. The MAPI client calls the IMAPIClientShutdown::NotifyProcessShutdown method to indicate to the MAPI subsystem the intention to shut down.

  4. The MAPI subsystem indicates to each loaded MAPI provider that the MAPI client will shut down. For those providers that have implemented the IMAPIProviderShutdown : IUnknown interface, the MAPI subsystem calls the corresponding IMAPIProviderShutdown::NotifyProcessShutdown method.

  5. The MAPI client calls the IMAPIClientShutdown::DoFastShutdown method to indicate to the MAPI subsystem that the client process is exiting immediately.

  6. The MAPI subsystem indicates to each loaded MAPI provider that the MAPI client process is exiting. For those providers that have implemented the IMAPIProviderShutdown : IUnknown interface, the MAPI subsystem calls the corresponding IMAPIProviderShutdown::DoFastShutdown method. At this point, these MAPI providers should verify that all necessary actions, such as saving data and settings, are complete in preparation for the MAPI client to immediately disconnect all references and exit.

See also

Concepts

Client Shutdown in MAPI
Fast Shutdown User Options
Best Practices for Fast Shutdown


Fast Shutdown User Options

 Copy code hover
[image]

Fast Shutdown User Options
See also Send feedback

Published: July 16, 2012

This topic describes the three Windows registry settings that are available, starting in Microsoft Outlook 2010 and now including Microsoft Outlook 2013, for fast shutdown of a user's MAPI clients. Administrators can use these registry settings to specify the preferred client shutdown behavior depending on the MAPI providers' support for client fast shutdown. The administrator's setting, in turn, determines how the MAPI subsystem responds to the MAPI client's call to IMAPIClientShutdown::QueryFastShutdown in terms of available fast shutdown support.

Even though a registry setting reflects the administrator's preference at the user level for fast shutdown for all MAPI clients, a MAPI client developer can decide whether the client supports fast shutdown independently of other MAPI clients and the administrator's registry setting. Nonetheless, for fast shutdown to take place successfully, the user must have the necessary registry setting, a MAPI client must initiate the fast shutdown by using the IMAPIClientShutdown : IUnknown interface, and MAPI providers that work with the client should implement the IMAPIProviderShutdown : IUnknown interface to support client fast shutdown.

The following list describes the three user-level options.

  • Option 1: The MAPI subsystem enables fast shutdown, unless MAPI providers explicitly opt out.

    Starting in Outlook 2010, this is the default behavior when Outlook is the MAPI client; it is not necessarily the default behavior for other MAPI clients. To explicitly specify this option for Outlook, administrators can choose to set the following registry key and value.

    Registry key:

    [HKEY_CURRENT_USER\Software\Policies\Microsoft\Office\14.0\Outlook\Options\Shutdown]

    Value:

    "FastShutdownBehavior"=dword:00000000

    When a MAPI client initiates a fast shutdown and calls IMAPIClientShutdown::QueryFastShutdown to query for fast shutdown support, the MAPI subsystem responds to the query by returning S_OK as long as no MAPI provider that has an active MAPI session with the MAPI client has explicitly opted out of fast shutdown support. A MAPI provider opts out of fast shutdown by implementing the IMAPIProviderShutdown::QueryFastShutdown method to return an error (MAPI_E_NO_SUPPORT). If one or more MAPI providers return an error in IMAPIProviderShutdown::QueryFastShutdown, the MAPI subsystem returns MAPI_E_NO_SUPPORT to IMAPIClientShutdown::QueryFastShutdown. Unless a MAPI provider opts out, the MAPI subsystem returns S_OK, even if one or more providers have not implemented the IMAPIProviderShutdown : IUnknown interface.

  • Option 2: The MAPI subsystem enables fast shutdown only if every MAPI provider explicitly opts in.

    Administrators must explicitly set the following registry key and value to specify this preference for client fast shutdown.

    Registry key:

    [HKEY_CURRENT_USER\Software\Policies\Microsoft\Office\14.0\Outlook\Options\Shutdown]

    Value:

    "FastShutdownBehavior"=dword:00000001

    When a MAPI client initiates a fast shutdown and calls IMAPIClientShutdown::QueryFastShutdown to query for fast shutdown support, the MAPI subsystem responds to the query by returning S_OK if all MAPI providers that have active sessions with the MAPI client support fast shutdown. A MAPI provider demonstrates its support by implementing IMAPIProviderShutdown::QueryFastShutdown to return a non-error code (S_OK). If one or more such MAPI providers return MAPI_E_NO_SUPPORT, or do not implement IMAPIProviderShutdown::QueryFastShutdown, the MAPI subsystem returns an error code to IMAPIClientShutdown::QueryFastShutdown.

  • Option 3: An administrator disables support for client fast shutdown.

    Administrators must explicitly set the following registry key and value to disable support for client fast shutdown.

    Registry key:

    [HKEY_CURRENT_USER\Software\Policies\Microsoft\Office\14.0\Outlook\Options\Shutdown]

    Value:

    "FastShutdownBehavior"=dword:00000002

    When a MAPI client initiates a fast shutdown and calls IMAPIClientShutdown::QueryFastShutdown to query for fast shutdown support, the MAPI subsystem responds to the query by returning MAPI_E_NO_SUPPORT, regardless of whether any MAPI provider supports fast shutdown. Under this registry setting, the MAPI subsystem never calls the IMAPIProviderShutdown::QueryFastShutdown or IMAPIProviderShutdown::DoFastShutdown method of any of the providers.

See also

Concepts

Client Shutdown in MAPI
Fast Shutdown Overview
Best Practices for Fast Shutdown


Best Practices for Fast Shutdown

 Copy code hover
[image]

Best Practices for Fast Shutdown
See also Send feedback

Published: July 16, 2012

This topic recommends best practices for administrators, MAPI clients, and MAPI providers to use Windows registry settings and the fast shutdown interfaces to minimize data loss during client shutdown.

  • For a MAPI client to carry out fast shutdown successfully so that provider processes do not incur data loss, the MAPI client should first call the IMAPIClientShutdown::QueryFastShutdown method. The client should then proceed with the IMAPIClientShutdown::NotifyProcessShutdown and IMAPIClientShutdown::DoFastShutdown methods based on the MAPI subsystem's support for fast shutdown, as indicated by the return value of IMAPIClientShutdown::QueryFastShutdown. As a MAPI client, Microsoft Outlook does not call IMAPIClientShutdown::NotifyProcessShutdown or IMAPIClientShutdown::DoFastShutdown if IMAPIClientShutdown::QueryFastShutdown returns an error. If the administrator has disabled fast shutdown in the Windows registry, the MAPI subsystem would return MAPI_E_NO_SUPPORT to IMAPIClientShutdown::QueryFastShutdown. In this case, the MAPI subsystem would not inform MAPI providers of an immediate client process exit. Therefore, if a MAPI client disregards this error return code, proceeds to do fast shutdown, and disconnects all external references, all loaded MAPI providers will have data loss.

  • MAPI providers should implement the IMAPIProviderShutdown : IUnknown interface to carry out timely and necessary steps to avoid data loss due to the client disconnecting external references before the client exits. A provider should postpone everything else that is nonessential to saving data to its primary data store. For example, a transport provider should postpone unnecessary background operations that check for new mail, an address book provider should postpone downloading recent changes from its server, and a store provider should postpone maintenance tasks such as compacting or indexing.

  • Users who want MAPI clients to exit as soon as they close them should use the default registry setting that enables fast shutdown unless a provider opts out.

  • Once a MAPI client calls IMAPIClientShutdown::DoFastShutdown, it should not make any additional calls to MAPI, including the MAPIUninitialize function. The client should not use MAPI for the rest of the client process's lifetime.

  • A MAPI client should never directly call a provider's IMAPIProviderShutdown interface. MAPI clients should always use the IMAPIClientShutdown : IUnknown interface.

  • If a MAPI provider needs to ensure that fast shutdown is not used while it is loaded, it should implement the IMAPIProviderShutdown interface and return MAPI_E_NO_SUPPORT for the IMAPIProviderShutdown::QueryFastShutdown method. However, for MAPI clients such as Outlook, this will cause the client to abandon fast shutdown and take a longer time to shut down.

See also

Concepts

Client Shutdown in MAPI
Fast Shutdown Overview
Fast Shutdown User Options


Structured Storage in MAPI

 Copy code hover
[image]

Structured Storage in MAPI
Send feedback

Published: July 16, 2012

Structured storage refers to the hierarchical organization of storage introduced with COM. In a structured storage environment, storage is organized into two or three types of objects:

  • Stream objects

  • Lock bytes objects

  • Storage objects

Stream and lock bytes are lower-level objects that directly access the data. Stream objects implement the IStream interface which defines methods for reading, writing, positioning, and copying bytes of data. Lock bytes objects implement another COM interface, ILockBytes, to access data with a byte array. Byte arrays are typically used to provide customized access to underlying storage.

Storage objects are layered on top of the stream or lock bytes objects; they can contain one or more of these objects as well as other storage objects. Storage objects implement the IStorage interface which defines methods for creating, accessing, and maintaining nested objects.

Because IStream, ILockBytes, and IStorage are COM interfaces rather than MAPI interfaces, their methods return COM error values rather than MAPI values. Clients and service providers calling methods in these interfaces must use the API function MapStorageSCode to translate these values into MAPI error values. For more information, see MapStorageSCode.

Clients and service providers use structured storage for working with properties that are too large to maintain with the IMAPIProp methods, typically large string and binary properties. One of the common ways that clients or service providers access them is by specifying IStream or IStorage as the interface identifier in a call to the IMAPIProp::OpenProperty method. For example, clients call OpenProperty with PR_ATTACH_DATA_BIN as the property tag and IID_IStream as the interface identifier to access a binary attachment in a message.

Clients and service providers can implement their own stream and storage objects or call API functions to access implementations supplied by MAPI or COM. Because the supplied implementations serve most purposes, clients and service providers rarely need to create their own.

When a client calls OpenProperty on a MAPI object to access one of its properties through a storage object, the service provider will typically open the storage object in direct mode. However, this is typical rather than required behavior. Clients should assume that all storage objects opened or created by service providers are transacted and require a call to IStorage::Commit. They should also remember that changes to storage objects will not be made permanent until they call IMAPIProp::SaveChanges after the final Commit to save the MAPI object. For more information, see IMAPIProp::SaveChanges.

MAPI and COM provide several API functions for defining or accessing storage and stream objects. The commonly used functions are described in the following table.

Functions for Accessing Storage and Stream Objects
Function | Description
HrIStorageFromStream | Creates a storage object to access a stream or lock bytes object.
OpenIMsgOnIStg | Creates a message object to access a storage object.
OpenStreamOnFile | Creates a stream object to access a file.
WrapCompressedRTFStream | Creates a stream object that contains the compressed or uncompressed version of a stream holding the rich text of a message.

To retrieve the names of the streams in a given substorage

  1. Call the substorage's IStorage::EnumElements method to get an IEnumSTATSTG interface.

  2. Call IEnumSTATSTG::Next with as many STATSTG structures at a time as you can. If you ask for 100 at a time, Next will usually return S_FALSE with the contents of pceltFetched set to the number that were actually retrieved.

  3. Check for the STATSTG structures that are flagged with STGTY_STREAM.

  4. Release the pwcsName parameter.

To create a storage object to access an existing stream or lock bytes object

  • Clients call HrIStorageFromStream.

To create a message object to access an existing storage object

  • Service providers and clients call OpenIMsgOnIStg. The message object that is created differs from the message objects typically created by message store providers in that it does not support all of the IMessage : IMAPIProp interface methods, such as IMessage::SubmitMessage. An optional input parameter to OpenIMsgOnIStg is a callback function that conforms to the MSGCALLRELEASE prototype. This function is called by the new message object when the message's reference count reaches zero. Implementing a MSGCALLRELEASE function can be useful for performing final processing before the new message is completely removed.

OpenStreamOnFile is commonly used for storing file attachments because it creates a stream that reads from and writes to a file. OpenProperty with PR_ATTACH_DATA_BIN as the property tag creates a stream for storing binary attachment data.

To compress or uncompress a stream containing message text in the Rich Text Format

  • Clients call WrapCompressedRTFStream. WrapCompressedRTFStream creates a stream that wraps the RTF stream. The wrapper stream does not implement all of the IStream methods; the following methods are excluded: Seek, SetSize, Revert, LockRegion, UnlockRegion, Stat, and Clone. This is because the stream objects created by WrapCompressedRTFStream do not support either SetSize or Stat, there is not an easy way to either extend or retrieve their size. The best strategy is to pick a reasonable buffer size and read or write in a loop.

Note Note

COM has a storage object implementation based on a byte array that returns an IEnumSTATSTG object from the EnumElements method that is problematic. In particular, the QueryInterface method does not work correctly. Service providers that implement their own storage objects using the COM implementation should create a thin wrapper for the IEnumSTATSTG object that forwards calls on to the underlying IEnumSTATSTG methods but implements its own AddRef, Release, QueryInterface, and Clone methods.


MAPI Character Sets

 Copy code hover
[image]

MAPI Character Sets
Send feedback

Published: July 16, 2012

MAPI-compliant client applications and service providers can use ANSI characters (single byte) or Unicode characters (double byte). OEM character sets are not supported. An OEM string passed to a MAPI method or function will cause that method or function to fail. Client applications that work with filenames in the OEM character set must be careful to convert them to ANSI before passing them to a MAPI method or function.

Supporting the Unicode character set is optional, both for clients and service providers. All service providers should write their code so that they can compile regardless of whether or not they support Unicode. Clients compile conditionally, depending on their level of support, but service providers do not. They should not have to be recompiled when the character set changes. Nothing in service provider code should be conditional.

When clients or service providers that support Unicode make a method call that includes character strings as input or output parameters, they set the MAPI_UNICODE flag. Setting this flag indicates to the implementation that all incoming strings are Unicode strings. On output, setting this flag requests that all strings passed back from the implementation should be Unicode strings if possible. Method implementers that support Unicode will comply with the request; method implementers that do not provide Unicode support will not comply. String properties that are not in Unicode format are of type PT_STRING8.

MAPI defines the fMapiUnicode constant in the header file MAPIDEFS.H to represent the default character set. If a client or service provider supports Unicode, fMapiUnicode is set to MAPI_UNICODE. Clients and service providers that do not support Unicode set fMapiUnicode to zero.

Service providers that do not support Unicode should:

  • Refuse to perform conversions between character sets.

  • Never pass the MAPI_UNICODE flag in method calls.

  • Return MAPI_E_BAD_CHARWIDTH when the MAPI_UNICODE flag is passed in.

  • Declare ANSI string properties explicitly.

Service providers can also return MAPI_E_BAD_CHARWIDTH when they only support Unicode and clients do not pass the MAPI_UNICODE flag.

The current version of MAPI supports Unicode in the following methods:

IAddrBook::Address

IAddrBook::CreateOneOff

IAddrBook::Details

IAddrBook::ResolveName

IMAPIProp::GetLastError (IAddrBook implementation only)

For these methods, callers can expect any returned strings to be Unicode strings. Character strings returned from MAPI implementations of any other method will be ANSI character strings.


Formatted Text in MAPI

 Copy code hover
[image]

Formatted Text in MAPI
Send feedback

Published: July 16, 2012

The text of a message can be stored and transmitted using plain text or formatted text. Formatted text enhances the message text by altering its appearance with, for example, one or more fonts, font sizes, or text colors. It is recommended that all clients and whenever possible, all message store providers, support formatted text. Supporting formatted text in messages adds value by improving message readability and making message handling easier and more efficient.

Formatted text can be implemented in a variety of ways. The most common way is with the Rich Text Format (RTF). MAPI defines three transmittable properties for holding message text information: PR_BODY (PidTagBody) for plain text, PR_HTML (PidTagHtml) for HTML, and PR_RTF_COMPRESSED (PidTagRtfCompressed) for RTF text that has been compressed. Because the formatted version of a message text can be twice as large as the version without the formatting, the RTF text is compressed before it is transferred with the message and stored in the PR_RTF_COMPRESSED property. When it is time to display the message on the screen, it is uncompressed using a utility function provided by MAPI.

MAPI defines these two message text properties and mechanisms for conversion between them so that RTF-aware clients can interoperate with clients and messaging systems that do not support formatted text.

Synchronizing Text and Formatting

Describes how to keep RTF message text synchronized with the formatting.

Supporting Formatted Text in Outgoing Messages: Client Responsibilities

Describes client application responsibilities for supporting formatted text in outgoing messages.

Supporting Formatted Text in Incoming Messages: Client Responsibilities

Describes client application responsibilities for supporting formatted text in incoming messages.

Supporting Formatted Text: Message Store Responsibilities

Describes message store responsibilities for supporting formatted text.

Supporting Formatted Text: Rendering Attachments

Describes how to choose where attachments are rendered.

Supporting Formatted Text: Gateway Responsibilities

Describes the gateway responsibilities for outgoing and incoming formatted text messages.


Synchronizing Text and Formatting

 Copy code hover
[image]

Synchronizing Text and Formatting
Send feedback

Published: July 16, 2012

The main challenge in sending Rich Text Format (RTF) messages is keeping the text synchronized with the formatting. To ensure that when messages arrive at their destination they are as their originators intended and that the text and formatting are synchronized, MAPI provides the RTFSync function. RTFSync is typically called by RTF-aware clients before displaying incoming messages and by the MAPI spooler when it downloads messages to a transport provider. Callers specify the area of possible discrepancy by passing one or two flags to RTFSync:

  • RTF_SYNC_BODY_CHANGED to indicate a modification in message text.

  • RTF_SYNC_RTF_CHANGED to indicate a modification in message formatting.

The synchronization process that occurs in RTFSync is a sophisticated cyclic redundancy check (CRC) of the message text that ignores some characters and converts others. Characters that most likely were added by transport providers are ignored. MAPI defines several properties for working with RTF as described in the following table.

RTF property | Description
PR_RTF_SYNC_BODY_TAG (PidTagRtfSyncBodyTag) | Indicates the beginning of the real message text.
PR_RTF_SYNC_BODY_CRC (PidTagRtfSyncBodyCrc) | Contains the result of the cyclic redundancy check of the message text.
PR_RTF_SYNC_BODY_COUNT (PidTagRtfSyncBodyCount) | Contains the number of characters in PR_RTF_SYNC_BODY_CRC.
PR_RTF_IN_SYNC (PidTagRtfInSync) | Set to TRUE when the message text and formatting have been synchronized.
PR_RTF_SYNC_PREFIX_COUNT (PidTagRtfSyncPrefixCount) | Contains the number of nonwhitespace characters that preceed the message text.
PR_RTF_SYNC_TRAILING_COUNT (PidTagRtfSyncTrailingCount) | Contains the number of nonwhitespace characters that trail the message text.


Supporting Formatted Text in Outgoing Messages: Client Responsibilities

 Copy code hover
[image]

Supporting Formatted Text in Outgoing Messages: Client Responsibilities
Send feedback

Published: July 16, 2012

Client applications set the PR_BODY (PidTagBody) property, the PR_RTF_COMPRESSED (PidTagRtfCompressed) property, or the PR_HTML (PidTagHtml) property for an outgoing message. Clients that support only plain text set only the PR_BODY property. Rich Text Format (RTF)-aware clients might set both PR_BODY and PR_RTF_COMPRESSED properties, or only PR_RTF_COMPRESSED, depending on the message store provider being used. HTML-aware clients set the PR_HTML property.

It is important for a client to check its message store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property to determine whether the store supports RTF. If the message store is not RTF-aware, an RTF-aware client sets both the PR_BODY and PR_RTF_COMPRESSED properties for each outgoing message.

If the message store is RTF-aware, only the PR_RTF_COMPRESSED property needs to be set.

To set PR_RTF_COMPRESSED and ensure that the synchronization process occurs as necessary, RTF-aware clients

  1. Call the IMAPIProp::OpenProperty method to open the PR_RTF_COMPRESSED property, setting both the MAPI_CREATE and MAPI_MODIFY flags. MAPI_CREATE ensures that any new data replaces any old data and MAPI_MODIFY enables you to make those replacements.

  2. Call the WrapCompressedRTFStream function, passing STORE_UNCOMPRESSED_RTF if the message store sets the STORE_UNCOMPRESSED_RTF bit in its PR_STORE_SUPPORT_MASK property, to get an uncompressed version of the PR_RTF_COMPRESSED stream returned from OpenProperty.

  3. Write the message text data to the uncompressed stream returned from WrapCompressedRTFStream.

  4. Commit and release both the uncompressed and compressed streams.

At this point, if the message store provider supports RTF, you have done all that is required. You can depend on the message store provider to handle the synchronization process and the creation of the PR_BODY property, if necessary. However, if the message store provider does not support RTF, you must call the RTFSync function to synchronize the text with the formatting, setting the RTF_SYNC_RTF_CHANGED flag.


Supporting Formatted Text in Incoming Messages: Client Responsibilities

 Copy code hover
[image]

Supporting Formatted Text in Incoming Messages: Client Responsibilities
Send feedback

Published: July 16, 2012

As messages are transferred between messaging systems, the MAPI spooler makes sure that the rich text formatting remains synchronized with the message text. The MAPI spooler calls the RTFSync function from within a wrapped version of the message that it passes to the transport provider. The transport provider saves the changes made to the message by calling the IMAPIProp::SaveChanges method and then routes it to the new recipient.

When the recipient's RTF-aware client application opens the message to display the text, it must synchronize the text with the formatting and open either PR_RTF_COMPRESSED (PidTagRtfCompressed) or PR_BODY (PidTagBody), depending on which property is available.

To open a message, RTF-aware clients

  1. Call RTFSync to synchronize the message text with the formatting if the message store is not RTF-aware. The RTF_SYNC_BODY_CHANGED flag should be passed in the ulFlags parameter if the PR_RTF_IN_SYNC (PidTagRtfInSync) property is missing or set to FALSE. Clients working with RTF-aware message stores need not make the RTFSync call because the message store takes care of it.

  2. Call IMAPIProp::SaveChanges if the message text has been updated.

  3. Call IMAPIProp::OpenProperty to open the PR_RTF_COMPRESSED property. If PR_RTF_COMPRESSED is not available, you should open the PR_BODY property instead to display the message content.

  4. Call the WrapCompressedRTFStream function to create an uncompressed version of the compressed RTF data, if available.

  5. Display the uncompressed RTF data or the plain text data to the user.

RTFSync returns a Boolean value that indicates whether or not the message has been updated. If this value returns TRUE, call SaveChanges at some point to make the update permanent. The call does not have to be made immediately after RTFSync returns.

Note Note

Because so many components handle the formatted text before you receive it, there is the possibility of corruption. This corruption could come from the message store provider, a third party application, a gateway, or a transmission error.


Supporting Formatted Text: Message Store Responsibilities

 Copy code hover
[image]

Supporting Formatted Text: Message Store Responsibilities
Send feedback

Published: July 16, 2012

Message store providers use the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property to publish whether or not they can handle Rich Text Format (RTF), HTML text and, if they are RTF-aware, whether they store the formatted text in a compressed or uncompressed format. Message store providers indicate that they are RTF-aware by setting the STORE_RTF_OK bit and that they store the formatted text in an uncompressed form by setting the STORE_UNCOMPRESSED_RTF bit. Message store providers indicate they are HTML-aware by setting the STORE_HTML_OK bit.

While it is important for an RTF-aware client to check for the STORE_RTF_OK bit to determine whether or not a message store supports RTF, it is not necessary for a client to be concerned with the format of an RTF-aware store's formatted text.

All message stores must support non-RTF-aware clients. A non-RTF-aware message store must delete the PR_RTF_IN_SYNC (PidTagRtfInSync) property during a call to the message's IMAPIProp::SaveChanges method if a client has changed PR_BODY (PidTagBody) without updating either PR_RTF_IN_SYNC or PR_RTF_COMPRESSED (PidTagRtfCompressed). Deleting PR_RTF_IN_SYNC causes the PR_RTF_COMPRESSED property to be recomputed from the PR_BODY property the next time an RTF-aware client calls RTFSync.

Most RTF-aware message stores are not given the message text by clients; it must be computed on request. Because this computation is time consuming and expensive, clients should use PR_RTF_COMPRESSED whenever possible. To compute the PR_BODY property, the message store provider must uncompress the contents of the PR_RTF_COMPRESSED property and remove the rich text formatting. Clients that do not support the PR_RTF_COMPRESSED property require this computation to take place for every message.

When copying messages, message store providers that do not use the IMAPISupport::DoCopyProps or IMAPISupport::DoCopyTo methods run the risk of creating a message with no content if their implementation excludes the PR_BODY property and relies on PR_RTF_COMPRESSED. It is possible for the data in the PR_RTF_COMPRESSED property to be corrupt. Before excluding either of these message content properties in the copy operation, check for corruption as follows:

  1. If the value of PR_RTF_COMPRESSED is not larger than the compressed RTF, the property is corrupt.

  2. If the magic value in the RTF header is not dwMagicCompressedRTF or dwMagicUncompressedRTF, the property is corrupt.

Message store providers using the support methods need not be concerned with implementing a check for PR_RTF_COMPRESSED corruption; MAPI ensures that the appropriate properties exist and are valid.

There are three different levels of RTF support that message store providers can implement; MAPI recommends that RTF-aware message store providers implement their support at the middle or highest level. All RTF-aware message store providers take care of generating PR_BODY from the data included in PR_RTF_COMPRESSED on outgoing messages and make a call to RTFSync to synchronize text and formatting on incoming messages.

The differences between these three levels are described in the following table.

Level of support | Description
Low | Message store provider calls RTFSync whenever changes are saved to a message and extracts the data for the PR_BODY property from PR_RTF_COMPRESSED rather than requiring clients to set it. Both PR_BODY and PR_RTF_COMPRESSED are stored.
Middle | Message store provider stores only the PR_RTF_COMPRESSED property, computing PR_BODY when necessary.
High | Message store provider stores neither PR_BODY or the auxiliary RTF properties. RTFSync is called when the message text has changed and the formatting remains unchanged or when a new message is downloaded by a transport provider.


Supporting Formatted Text: Rendering Attachments

 Copy code hover
[image]

Supporting Formatted Text: Rendering Attachments
Send feedback

Published: July 16, 2012

A client application that cares about where in a message its attachments are rendered sets the PR_RENDERING_POSITION (PidTagRenderingPosition) property for these attachments during message composition. A client that does not care about rendering placement leaves this property unset.

When a client opens a message with attachments, it attempts to retrieve each attachment's PR_RENDERING_POSITION property to determine where in the message text the attachment should be rendered. A client can use one of the following methods to retrieve PR_RENDERING_POSITION:

  • IMAPIProp::GetProps on the open attachment to retrieve the PR_RENDERING_POSITION property.

  • IMessage::GetAttachmentTable on the open message to retrieve its attachment table. PR_RENDERING_POSITION is a required column in all attachment tables. This is the preferred method because it results in better performance.

RTF-aware message stores can choose whether to return an accurate or approximate value for PR_RENDERING_POSITION. Because message stores recalculate an attachment's PR_RENDERING_POSITION value when asked for the message's PR_BODY property, some RTF-aware message stores only guarantee the accuracy of rendering positions when a client asks first for PR_BODY. RTF-aware message stores are allowed to provide clients with approximate rendering position values to enhance performance. Providing an approximate rather than an accurate rendering position saves time and is sufficient for most situations.

RTF-aware message stores should base their approximation on the value specified by the client responsible for creating the attachment. Although all clients should set PR_RENDERING_POSITION, message store providers should be prepared to deal with the possibility of its absence. When the client does not set PR_RENDERING_POSITION, a message store can set it to -1 to indicate that the rendering position is not within the message text. Attachments with a rendering position of -1 can be displayed at any place within the message depending on the client. Many clients position these types of attachments at the top of the message.

The degree of accuracy for a PR_RENDERING_POSITION property depends on whether or not a message store saves both a message's PR_BODY (PidTagBody) and PR_RTF_COMPRESSED (PidTagRtfCompressed) properties or only PR_RTF_COMPRESSED. If the client generates PR_BODY and the message store saves it along with the formatted text, the rendering positions will be accurate. However, if the message store must generate its own version of PR_BODY because it only saves PR_RTF_COMPRESSED, it is probable that the rendering positions will be somewhat inaccurate. This is because of the differences in the way that clients and message store providers generate the PR_BODY property.

To calculate an accurate PR_RENDERING_POSITION value, an RTF-aware store uses a tag embedded in the formatted text. The utility function RTFSync can be called to perform this calculation and update an attachment's rendering position. Depending on the amount of state information available, the message store can pass either RTF_SYNC_BODY_CHANGED, RTF_SYNC_RTF_CHANGED, or both values to RTFSync.


Supporting Formatted Text: Gateway Responsibilities

 Copy code hover
[image]

Supporting Formatted Text: Gateway Responsibilities
Send feedback

Published: July 16, 2012

To handle Rich Text Format for outgoing messages, gateways

  1. Retrieve only a message's PR_RTF_COMPRESSED (PidTagRtfCompressed) property from the message store. The main advantage in retrieving only the PR_RTF_COMPRESSED property is that the message text does not need to be sent between machines if the gateway and the message store exist on different machines.

  2. Generate the message text from the formatted text either by calling the RTF library function HrTextFromCompressedRTFStream or, if the message is stored locally, RTFSync. The RTF_SYNC_RTF_CHANGED flag should be set in the call to RTFSync. For more information, see RTFSync.

  3. Make any irreversible modifications to the message text, such as dropping unsupported characters.

  4. Ensure that both PR_RTF_IN_SYNC (PidTagRtfInSync) and all of the RTF auxilliary properties are either set or absent.

  5. If any modifications were made, call RTFSync with both the RTF_SYNC_RTF_CHANGED and RTF_SYNC_BODY_CHANGED flags set. RTFSync will recalculate the RTF auxilliary properties from the modified text.

  6. Make any reversable modifications to the message text, such as inserting attachment placeholders and performing nondestructive code page conversions.

  7. Send the message.

To handle Rich Text Format for incoming messages, gateways

  1. Reverse any message text modifications that were made directly before the message was sent.

  2. Call RTFSync if the message contains both the PR_RTF_COMPRESSED and PR_BODY (PidTagBody) properties.

  3. Update the message in the message store with the PR_RTF_COMPRESSED property if the message contains it; update with the PR_BODY property only if PR_RTF_COMPRESSED is absent.

  4. Discard PR_BODY if the message contains both this property and PR_RTF_COMPRESSED.

Gateways call RTFSync to avoid transmitting both the message text and formatted text if the message store is on a different machine. If the gateway is local, it can set both properties and allow the message store to perform the synchronization.


MAPI Idle Engine

 Copy code hover
[image]

MAPI Idle Engine
Send feedback

Published: July 16, 2012

MAPI provides several functions that are collectively known as the idle engine. These functions allow clients, address book providers, and message store providers to perform various tasks during slow times in the session or in response to a slow time. For example, clients and service providers can defer slow operations or close files that have remained unused for a lengthy period. Transport providers typically do not use the idle engine because the IXPLogon::Idle method takes its place. For more information, see IXPLogon::Idle.

To use the idle engine, clients and service providers create a callback function that contains the tasks that should occur when the MAPI subsystem is idle. When MAPI detects idle time, it invokes this callback function. The callback function follows the FNIDLE prototype, defined as follows:

BOOL (STDAPICALLTYPE FNIDLE) (LPVOID lpvContext)

For more information, see FNIDLE.

The functions that make up the idle engine are:

ChangeIdleRoutine

DeregisterIdleRoutine

EnableIdleRoutine

FtgRegisterIdleRoutine

MAPIDeInitIdle

MAPIInitIdle

To register a callback function, clients and service providers call the FtgRegisterIdleRoutine function. The input parameters include an optional priority, a block of memory that is passed to your callback function as input, an amount of time to be used in any way appropriate, and a set of option flags.

Clients and service providers can specify a priority in the priIdle parameter that controls how the idle function runs or specify zero if priority is not an issue. Because negative numbers represent higher priorities than positive numbers or zero, compression and search operations should be assigned negative numbers. Tasks that occur once should be assigned positive numbers.

To deregister an active callback function, clients and service providers call the DeregisterIdleRoutine function. Because DeregisterIdleRoutine operates asynchronously, it is possible for the callback function to be invoked at any time during the deregister call and possibly even after DeregisterIdleRoutine has returned.

To modify some or all of the characteristics of a callback function, clients and service providers call the ChangeIdleRoutine function. ChangeIdleRoutine makes changes according to how the flags parameter ircIdle is set; ChangeIdleRoutine can change the function itself, its priority, time setting, and input parameter.

MAPI defines idle the same as the operating system, when the operating system has a definition. On Win32, MAPI creates a thread with idle-class priority to schedule idle tasks. This thread keeps track of the time and posts a message to the thread that is to execute the idle task when the time for its execution arrives. Win32 schedules threads, not processes. If tasks that have a priority higher than the idle priority are occurring on the workstation, the idle task should not get scheduled for execution until the tasks have completed.

All idle tasks run on the thread that called MAPIInitIdle. MAPI has a separate thread for scheduling, but when an idle task becomes eligible, it posts a message back over to the initialization thread and the idle task is executed there. The implications for different types of clients are as follows.

Threading model | Implication
Single-threaded | No problem. Idle functions execute on your client's main thread and are serialized through the message loop.
Free-threaded | Idle functions must be thread-safe, but your client already has the necessary infrastructure. Your client might not need the MAPI idle engine at all.
Apartment-threaded | Idle function has to execute on the same thread that registered it if it wants to use MAPI, OLE, or any other COM interfaces. The most straightforward way is to register an idle function with MAPI that posts a message to the right thread and dispatch the "real" idle function directly from that thread's message loop.


MAPI File Formats

 Copy code hover
[image]

MAPI File Formats
Send feedback

Published: July 16, 2012

MAPI publishes the formats of various configuration files that clients and service providers use to describe message services and their service providers and forms.

The following table describes these files by name or type:

Configuration file | Description
MapiSvc.inf | Contains configuration information for the MAPI subsystem, message services, and service providers.
Files with the .cfg extension | Contains configuration information for a form.

For detailed information about the file format of MapiSvc.inf, see File Format of MapiSvc.inf.

For detailed information about the file format of a form configuration file, see File Format of Form Configuration Files.


File Format of MapiSvc.inf

 Copy code hover
[image]

File Format of MapiSvc.inf
Send feedback

Published: July 16, 2012

The MapiSvc.inf file acts as the central database for MAPI message service configuration information. MapiSvc.inf contains information about each of the message services installed on the workstation, information about the service providers that belong to each message service, and information about the MAPI subsystem. MapiSvc.inf is the primary source of information for profiles. That is, when a new profile is being built or an existing one modified, relevant information for each message service or service provider is copied from MapiSvc.inf.

MapiSvc.inf is divided into linked hierarchical sections:

  1. Section containing information that applies to all profiles. This section has three parts:

    • [Services] section, providing links to each of the subsequent message service sections.

    • [Help File Mappings] section, containing information about .HLP files provided by message services.

    • [Default Services] section, listing message services that make up a default installation.

  2. Section containing information that applies to individual message services. Entries in these sections provide links to subsequent service provider sections.

  3. Section containing information that applies to individual service providers in a message service.

The following illustration shows the organization of a typical MapiSvc.inf file. There are three message services: AB, MsgService, and MS. The name on the right hand side of the equal sign for each message service is the service's display name. Each message service has its own section elsewhere in the file that is linked to one or more service provider sections. There is one service provider section for every service provider that belongs to the message service. The AB and MS message services are single provider services whereas three service providers belong to the MsgService service.

MapiSvc.inf file organization

MapiSvc.inf file organization

MAPI provides a skeletal version of the MapiSvc.inf file that contains the entries for the MAPI subsystem. Each message service implementer adds entries that are appropriate both for their service and the service providers that belong to their service. Some of the entries are required while others are optional. For example, MAPI requires that you specify the name and path of each of the service providers in your message service. Without this information, they cannot be loaded.

You can add required and optional information in either the section for your message service and/or to the service provider sections. Where you put the information describing your message service depends on the number of service providers in the service. Because this information applies to each service provider in the service, you must make it accessible to all providers. Store it either in the message service section, the preferred option, or in all of the service provider sections. Store information once to avoid unnecessary replication and the need to keep multiple copies synchronized.

If your message service is a single provider service, store all of the message service information in the section for the service provider rather than in the section for the service. Accessing the service provider section is faster and more direct than accessing the message service section.

Store only public configuration data in the MapiSvc.inf file. Information that is private or requires extra protection, such as passwords or other credentials, should not be included in this file. Instead, opt either not to store information of this type at all or keep it in the profile as secure properties. Secure properties have built-in protection features such as encryption.


MapiSvc.inf [Help File Mappings] Section

 Copy code hover
[image]

MapiSvc.inf [Help File Mappings] Section
Send feedback

Published: July 16, 2012

The [Help File Mappings] section contains entries that each map one message service to the file that provides Help for errors generated by the service. Entries in this section use the following format:

[Help File Mappings]message service name = Help file name

The message service name is the name of the installed message service; the Help file name is the name of the file where the error information resides. The example following shows a typical [Help File Mappings] section that contains entries for three services: MAPI, the MsgService service, and the MS service.

Copy code Copy code
[Help File Mappings]
MAPI=MAPI.HLP
MsgService=MYHELP.HLP
MS=STORE.HLP


MapiSvc.inf [Services] Section

 Copy code hover
[image]

MapiSvc.inf [Services] Section
Send feedback

Published: July 16, 2012

The [Services] section lists the message services that are installed on a computer. Entries in this section use the following format:

[Services]

message-service section name = message service name

The message-service section name is a string defined by the message service that links this entry to a corresponding section for the service elsewhere in mapisvc.inf. The message service name is the name of the installed service. The following section shows three message services: the Default Address Book, My Own Service, and the Message Store Service. These services are fictional, for illustration purposes only. Each message service implementer would substitute the appropriate entry for his or her message service in this section.

Copy code Copy code
[Services]
AB=Default Address Book
MsgService=My Own Service
MS=Message Store Service

Each entry in this section has a corresponding section of its own where information for the message service is stored. For example, the corresponding section for the Default Address Book is called [AB].


MapiSvc.inf [Default Services] Section

 Copy code hover
[image]

MapiSvc.inf [Default Services] Section
Send feedback

Published: July 16, 2012

The [Default Services] section lists all of the message services that are selected as default message services. These default message services are a subset of the message services listed in the [Services] section. When a profile configuration program creates a default profile, the message services in this section are automatically included.

The entries use the same format as entries in the [Services] section, as shown following:

[Default Services]
message-service section name = message service name

The following entries would be included in the [Default Services] section for the mapisvc.inf shown in the earlier illustration:

Copy code Copy code
[Default Services]
AB=Default Address Book
MsgService=My Own Service


MapiSvc.inf Message Service Sections

 Copy code hover
[image]

MapiSvc.inf Message Service Sections
Send feedback

Published: July 16, 2012

mapisvc.inf includes one message service section for each of the entries listed in the [Services] section. There are two types of entries in these sections: one for setting certain properties and the other for listing names of sections that are related to the message service being configured.


Property Entries in MapiSvc.inf Message Service Sections

 Copy code hover
[image]

Property Entries in MapiSvc.inf Message Service Sections
Send feedback

Published: July 16, 2012

Entries that set properties use this format:

property tag= property value

The property tag can be a standard MAPI property tag if the configuration data represents one of the properties predefined by MAPI, or a nonstandard tag if the data does not represent a MAPI property. The nonstandard tag is made by combining the value for a property identifier with a property type. The result is an 8 digit hexadecimal number. The property value can be whatever makes sense for the property tag.

Message service sections can contain a variety of entries depending on the message service being configured. The following MAPI properties are typically included in a message services section in the listed format:

PR_DISPLAY_NAME = string

PR_SERVICE_DLL_NAME = name of DLL file

PR_SERVICE_ENTRY_NAME = name of entry point function

PR_SERVICE_SUPPORT_FILES = list of files

PR_SERVICE_DELETE_FILES = list of files

PR_RESOURCE_FLAGS = bitmask

The PR_DISPLAY_NAME (PidTagDisplayName) string is the name of the message service that is shown in the user interface, the name that the user associates with the message service. The display name is an optional entry in mapisvc.inf. Sometimes the display name will be made up of two parts; a part assigned by the message service and a part assigned by the user. If the user is responsible for assigning one of the parts, this is typically handled with a special dialog box known as a property sheet supplied by the message service under the control of a client application.

The information provided for the PR_SERVICE_DLL_NAME (PidTagServiceDllName) entry is the name of the DLL that contains the message service. The information provided for the PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) entry is the name of the entry point function within that DLL that MAPI calls to configure the message service.

The files listed in the PR_SERVICE_SUPPORT_FILES (PidTagServiceSupportFiles) entry are files that must be installed with the message service. Likewise, the files in the PR_SERVICE_DELETE_FILES (PidTagServiceDeleteFiles) entry must be removed when the message service is removed.

The PR_RESOURCE_FLAGS (PidTagResourceFlags) entry is a collection of options defined for the message service. For example, the SERVICE_SINGLE_COPY bit is set when the message service can only appear once in a given profile. The SERVICE_NO_PRIMARY_IDENTITY bit is set if the message service does not provide identity information.

Two examples of nonstandard property entries follow. The first entry specifies the path to the file used by the Default Address Book as the property value; the second entry specifies a numeric property value. Both entries have meaning specific to the AB message service.

Copy code Copy code
6600001e=full path to file
66040003=integer


List Entries in MapiSvc.inf Message Service Sections

 Copy code hover
[image]

List Entries in MapiSvc.inf Message Service Sections
Send feedback

Published: July 16, 2012

There are two types of section list entries: one that lists service provider sections and one that lists miscellaneous message service-specific sections. These two types of entries appear in mapisvc.inf using the following formats:

Copy code Copy code
Providersprovider section1, provider section2, ...... provider sectionX
Sectionssection name1, section name2, ......section nameX

Each section in the Providers entry maps to an individual section providing configuration information for a service provider that belongs to the message service. Each section in the Sections entry maps to a section that contains extra configuration information needed by the message service. Message service implementers define extra sections when they want to include special information that does not fit in the standard sections. Message services that have complicated configurations typically use the Sections entry to add extra information. Every message services section has a Providers entry with at least one section in the list; not all message service sections have a Sections entry.

Two examples of message service sections follow. The first section is for the Default Address Book service from the earlier illustration, a straightforward message service with a single service provider. The second section is for the MsgService service, a more complex sample message service with three service providers.

Copy code Copy code
[AB]
PR_DISPLAY_NAME=Default Address Book
Providers=AB Provider
PR_SERVICE_DLL_NAME=AB.DLL
PR_SERVICE_SUPPORT_FILES=AB.DLL
PR_SERVICE_ENTRY_NAME=DABServiceEntry
PR_RESOURCE_FLAGS=SERVICE_NO_PRIMARY_IDENTITY
[MsgService]
PR_DISPLAY_NAME=My Own Service
Providers=MsgService Prov1, MsgService Prov2, MsgService Prov3
Sections=First_Special_Section, Second_Special_Section
PR_SERVICE_DLL_NAME=MYSERV.DLL
PR_SERVICE_SUPPORT_FILES=MYSERV.DLL, MYXXX.DLL, MYZZZ.DLL
PR_SERVICE_ENTRY_NAME=MyServiceEntry
PR_RESOURCE_FLAGS=SERVICE_SINGLE_COPY
66040003=00000000

The Sections entry in the [MsgService] section lists two additional sections, one called [First_Special_Section] and the other called [Second_Special_Section]. The data that might appear in extra sections is meaningful to the specific message service. These sections appear following to illustrate extra sections.

Copy code Copy code
[First_Special_Section]
UID=13DB0C8AA05101A9BB000AA002FC45A
66020003=01000000
66000003=00040000
66010003=06000000
66050003=03000000


MapiSvc.inf Service Provider Sections

 Copy code hover
[image]

MapiSvc.inf Service Provider Sections
Send feedback

Published: July 16, 2012

mapisvc.inf includes one service provider section for each of the entries listed in the Providers entry in the preceding message services section. Service provider sections are similar to message service sections in that both types of sections contain entries in this format:

property tag = property value

However, service provider sections and message service sections differ in that such property entries are the only type of entry included in service provider sections. There can be no additional or linked sections for service providers; all service provider information must be contained within the one section.

Some of the properties set in message service sections are also set in service provider sections because these properties make sense for both. The PR_DISPLAY_NAME property is an example. Both service providers and message services have a name that is used for display in the configuration user interface. Depending on the service provider, that name may or may not be the same. Other properties are specific to service providers.

Typical service provider sections include the following entries, all of which are required:

PR_DISPLAY_NAME = string

PR_PROVIDER_DISPLAY = string

PR_PROVIDER_DLL_NAME = name of DLL file

PR_RESOURCE_TYPE = long

PR_RESOURCE_FLAGS = bitmask

The PR_PROVIDER_DLL_NAME (PidTagProviderDllName) entry is similar to PR_SERVICE_DLL_NAME; it indicates the filename for the DLL that contains the service provider. Message service code may be stored with one of its service providers in the same DLL file or exist as a separate DLL. Note that no suffix is included in the entry regardless of the target platform; MAPI takes care of adding a suffix if necessary.

PR_RESOURCE_TYPE (PidTagResourceType) entry represents the type of service provider; service providers set it to the appropriate predefined constant. Valid values include MAPI_STORE_PROVIDER, MAPI_TRANSPORT_PROVIDER, and MAPI_AB_PROVIDER.

Another property entry that applies to both message services and service providers, the PR_RESOURCE_FLAGS (PidTagResourceFlags) entry indicates options. The settings for this property entry can differ depending on the service provider. For example, some message store providers might set PR_RESOURCE_FLAGS to STATUS_NO_DEFAULT_STORE if they can never operate as the default message store.

Three examples of service provider sections follow. The [AB Provider] section is the service provider section for the Default Address Book service. The [MsgService Prov1] and [MsgService Prov2] sections belong to My Own Service; the first is an address-book provider section and the second is a message-store provider section.

Copy code Copy code
[AB Provider]
PR_DISPLAY_NAME=Default Address Book
PR_PROVIDER_DISPLAY=Default Address Book
PR_PROVIDER_DLL_NAME=AB.DLL
PR_RESOURCE_TYPE=MAPI_AB_PROVIDER
6600001e=C:\WINNT35\System32\DEFAB.TXT
[MsgService Prov1]
PR_DISPLAY_NAME=My Own Service
PR_PROVIDER_DISPLAY=My Own Address Book
PR_PROVIDER_DLL_NAME=MYXXX.DLL
PR_RESOURCE_TYPE=MAPI_AB_PROVIDER
[MsgService Prov2]
PR_DISPLAY_NAME=My Folders
PR_PROVIDER_DISPLAY=My Own Message Store
PR_RESOURCE_TYPE=MAPI_STORE_PROVIDER
PR_PROVIDER_DLL_NAME=MYZZZ.DLL
PR_RESOURCE_FLAGS=STATUS_NO_DEFAULT_STORE
66060003=00000000
66030003=00000000
34140102=78b2fa70aff711cd9bc800aa002fc45a
66090003=06000000
660A0003=03000000


Registering Services and Service Providers in MapiSvc.inf

 Copy code hover
[image]

Registering Services and Service Providers in MapiSvc.inf
Send feedback

Installing a new provider on a system requires updating the MapiSvc.inf file to point to the new provider. Standard properties set during configuration, which include the following, inform MAPI where to find the provider's dynamic-link library (.dll):

  • The PR_SERVICE_DLL_NAME is specified in the [Message Service] section.

  • The PR_PROVIDER_DLL_NAME is specified in the [Service Provider] section.

Note Note

The expectation is that you set the name of your provider's .dll (without the suffix "32"). MAPI then loads your provider by looking for it on the path.

Putting a Path in MapiSvc.inf

Most applications install under Program Files, requiring an update to the path variable to allow MAPI providers to work. With a few restrictions Microsoft Outlook 2010 and Outlook 2013 can accommodate full paths to MAPI providers.

When registering your provider in MapiSvc.inf, you could put the full path to the provider in the MAPI properties PR_SERVICE_DLL_NAME and PR_PROVIDER_DLL_NAME.

In either property, the full path must be without the suffix "32", because MAPI continues to append that to the filename before looking for your file. This means that if you register the path "c:\mypath\myprovider.dll", MAPI will attempt to load "c:\mypath\myprovider32.dll".

Because Outlook's MAPI was not originally designed to accommodate full paths, it accomplishes this insertion of the "32" suffix by looking for the first period in the string, which means that paths that contain other periods cannot work, so you cannot use paths such as "c:\my.path\myprovider.dll" or "c:\mypath\my.provider.dll".

Sometimes in a store provider you will generate entry identifiers using the WrapStoreEntryID function, which takes as a parameter the name of your provider.

Important note Important

If you are using full paths in MapiSvc.inf, you must use the same path in any calls to WrapStoreEntryID.

Additionally, the path you use may be converted to and from Unicode using the code page provided by the GetACP function.

Caution note Caution

You will experience failure if you choose a path that contains characters that cannot survive such a roundtrip through the MultiByteToWideChar and WideCharToMultiByte functions.

For a demonstration of this functionality, the Wrapped PST sample on CodePlex has been revised - the pertinent functionality is in MergeWithMapiSvc and GenerateProviderPath.


File Format of Form Configuration Files

 Copy code hover
[image]

File Format of Form Configuration Files
Send feedback

Published: July 16, 2012

A form configuration file is a formatted file created by form developers to define a form.

Because form configuration files are used by form managers to load forms, each form must be defined using a form configuration file. Form configuration files must have the .cfg filename extension. The file follows the general syntax of a Windows initialization file (.ini file). It is divided into named sections, and each section contains a series of entries and values. Values have one of the following types: string, displayed string, platform string, path, integer, or globally unique identifier, GUID. Form configuration files can be created with any text editor or word processor that is capable of saving text files.


Form Configuration File [Description] Section

 Copy code hover
[image]

Form Configuration File [Description] Section
Send feedback

Published: July 16, 2012

The [Description] section lists all properties of the form that are associated with controls in the form's user interface, plus attributes that are used in locating the form. The MessageClass, Clsid, and DisplayName entries, which identify the name of the form's message class, its GUID, and the message class's display name, respectively, are required entries used to locate the form within the form library. The remaining entries are optional. The format of the [Description] section is:

The [Description] section lists all properties of the form that are associated with controls in the form's user interface, plus attributes that are used in locating the form. The MessageClass, Clsid, and DisplayName entries, which identify the name of the form's message class, its GUID, and the message class's display name, respectively, are required entries used to locate the form within the form library. The remaining entries are optional. The format of the [Description] section is:

[Description] MessageClass = string

Clsid = guid

DisplayName = displayedstring

SmallIcon = path

LargeIcon = path

Optional entries are:

Category = displayed string

Subcategory = displayed string

Comment = displayed string

Owner = displayed string

Number = displayed string

Version = integer

Locale = string

Hidden = integer

DesignerToolName = string

DesignerToolGuid = clsid

DesignerRuntimeGuid = clsid

ComposeInFolder = 0|1

ComposeCommand = string

The Category and Subcategory entries are used by form installers to set up the default categorization of forms within client application's user interface. For example a hierarchy could be set up where "Help Desk" is the category and "Software" and "Hardware" were the subcategories. This categorization can then be used by viewer applications to display messages in a more organized way. The Comment, Owner, and Number entries are all comment strings that appear in client application's user interface. These are form specific properties that can be used at the discretion of the form developer. For example, the Comment entry can be used to indicate the purpose of the form, the Owner entry used to indicate the person or organization responsible for maintaining the form, and the number used to track different version of the form. For the Comment entry, up to ten lines of comments can be included. The first line of comments uses the word "Comment" as the key, the second line of comments uses "Comment1" as the key, and so on through "Comment9."

The LargeIcon and SmallIcon entries are used to specify the path for the icon resources used to display icons in the client application's user interface, typically this is for table rows that include the PR_ICON (PidTagIcon) or PR_MINI_ICON (PidTagMiniIcon) property columns. Icon file names can be specified as pathnames relative to the directory where the form configuration file is installed. The Version entry is used to indicate the version number of the form. Locale is the three-letter language identifier of the destination form library. A list of these identifiers can be found in the Win32 Programmer's Reference.

The Hidden entry indicates whether the form should be displayed in a form library provider's user interface: 1 indicates that the file is hidden and 0 indicates that the form is visible. An example form configuration file is shown following.

The ComposeInFolder entry controls whether the form is designed to be placed in the current folder or in the user's Inbox when the user saves the message while composing it: 1 indicates that the form should go in the current folder and 0 indicates that it should go in the Inbox.

The ComposeCommand entry is the string to be placed in the client application's compose menu. If this is not specified, the DisplayName entry will be used.

Copy code Copy code
[Description]
MessageClass = IPM.Help
Clsid = {00020D31-0000-0000-C000-000000000046}
DisplayName = Help Desk Request Form

;optional entries

Category = Help Desk Requests
Subcategory = New Requests
Comment = Use this form to request network assistance
Owner = Help Desk
Number = 1
SmallIcon = C:\WINDOWS|EFORMS\HELPDESK\HDSMALL.ICO
LargeIcon = C:\WINDOWS|EFORMS\HELPDESK\HDLARGE.ICO
Version = 1.00
Locale = enu
Hidden = 0
ComposeInFolder = 0
ComposeCommand = &Help Desk Request


Form Configuration File [Extensions] Section

 Copy code hover
[image]

Form Configuration File [Extensions] Section
Send feedback

Published: July 16, 2012

The [Extensions] section lists the extended attributes of the form, typically a named property set, which are any attributes beyond the basic ones listed in the [Description] section of the form configuration file. Extended attributes are properties returned from calls to the GetProps method of the IMAPIFormInfo object with the high bit set in the property tag. Client applications can determine a form's extended attributes, if any, by retrieving these tags. To do so, clients call the IMAPIProp::GetIDsFromNames method, passing in the names of the form's properties and call the IMAPIProp::GetProps method to get the properties.

[Extensions]

Extension.string1 = string2

Each extension property section defines one extension attribute using the MAPI named property syntax. The property type must be either PT_LONG or PT_STRING8. Property sets that contains named strings are not supported. The format of the [Extension] section is:

[Extension.string2]

Type = integer

NmidPropset = guid

NmidInteger = integer

Value = string | integer

An example of an [Extensions] section and a subsequent related section is shown following.

Copy code Copy code
[Extensions]
Extension.A = 1
[Extension.1]
Type = 30
NmidPropset = {00020D0C-0000-0000-C000-000000000046}
NmidInteger = 1
Value = 11220000


Form Configuration File [Platforms] Section

 Copy code hover
[image]

Form Configuration File [Platforms] Section
Send feedback

Published: July 16, 2012

The [Platforms] section lists the complete set of platforms supported by this form. Each platform entry consists of the prefix Platform.string, where string is an arbitrary string code for the platform. Each string corresponds to the CPU entry of an individual [Platforms] sections. Each entry in a [Platforms] section defines a platform string that references a subsequent [Platform.platform string] section as shown here.

The [Platforms] section lists the complete set of platforms supported by this form. Each platform entry consists of the prefix Platform.string, where string is an arbitrary string code for the platform. Each string corresponds to the CPU entry of an individual [Platforms] sections. Each entry in a [Platforms] section defines a platform string that references a subsequent [Platform.platform string] section as shown here.

[Platforms]

Platform.string = platform string

Following is an example of a [Platforms] section.

Copy code Copy code
[Platforms]
Platform.1 = NTx86
Platform.2 = Win95

Each [Platform.platform string] section contains the two required entries, CPU and OSVersion. The CPU entry specifies the processor, and the OSVersion entry specifies the operating system. Valid CPU values are described in the following table.

CPU Entry | Processor
Ix86 | Intel 80x86 and Pentium series processors, as well as equivalent processors from AMD, Cyrix, NextGen and other manufacturers.
MIPS | MIPS R4000 series processors.
AXP | Digital Equipment Corporation Alpha AXP processor.
PPC | Motorola Power PC series processors.
M68 | Mororola 68x00 series processors.

Valid OSVersion values are described in the following table.

OSVersion Entry | Operating System
Win3.1 | Windows 3.1 and Windows for Workgroups 3.11.
WinNT3.5 | Windows NT 3.5 or lower.
Win95 | Windows 95.
WinNT4.0 | Windows NT 4.0.
Mac7 | Macintosh System 7.

Additionally, the [Platform.platform string] section must contain either a File or LinkTo entry. The File entry lists the form server application executable file that the form library maintains and loads into a new subdirectory in the disk cache when the form is launched. If a LinkTo entry is used instead, it contains the name of a different platform string from which the File information is taken. This is useful if one version of a form supports multiple platforms.

The Registry entry is used whenever the File entry is used, it identifies the registry key for the form library where the executable file for the form server application is stored. Strings preceded by a backslash ( \ ) are placed at the root of the registry. Strings not preceded by a backslash are placed in the HKEY_CLASSES_ROOT\CLSID\GUID\ registry key, where GUID is the GUID of the form. The characters "%d" can be used to indicate the pathname of the directory from which the form configuration file has been read. This is useful for specifying other files with pathnames relative to the form configuration file. Multiple File or Registry entries can be specified by using File or Registry as a prefix followed by any other text. The format for the [Platform.platform string] section is:

[Platform.platform string]

CPU = string

OSVersion = string

File = path

LinkTo = string

Registry = string

The following are two example [Platform.platform string] sections, one using the File entry and one using the LinkTo entry.

Copy code Copy code
[Platform.NTx86]
CPU = ix86
OSVersion = WinNT3.5
File = \helpdesk.exe
Registry = Local Server = %d\helpdesk.exe
[Platform.Win95]
CPU = ix86
OSVersion = Win95
LinkTo = NTx86

The [Platform.platform string] section is ignored when adding a form to the local form library, when it is assumed that the installer has placed the files constituting the message class handler into available local storage as named in the handler's section in the OLE registry, and has done the OLE registration in the system's registry.


Form Configuration File [Properties] Section

 Copy code hover
[image]

Form Configuration File [Properties] Section
Send feedback

Published: July 16, 2012

The [Properties] section lists the complete set of properties that the form uses and publishes; that is, the properties it creates in its custom messages that MAPI client applications can use when displaying columns, filtering contents tables, setting up search-results folders, and so on. Each entry in this property list references a subsequent [Property.string] section as shown following.

[Properties]

Property.string = string

The format of a [Property.string] section is:

[Property.string]

Type = integer

NmidPropset = guid

NmidString = string

NmidInteger = integer

DisplayName = string

Flags = integer

SpecialType = 0|1

Enum1 = string

Each [Property.string] section describes a single property. The Type entry specifies the MAPI property type, for example 3 (PT_I4), of the property. The NmidPropset entry is optional; together with either the NmidString entry or the NmidInteger entry, the NmidPropset entry gives the name of the property. NmidString gives the name of the property, while NmidInteger gives the identifier of the property. NmidString and NmidInteger are mutually exclusive.

If set, NmidPropset should contain the name of the property set; if absent, NmidPropset is set to a default based on the following rule: If NmidInteger is present and its value is less than 0x8000, NmidPropset is set to PS_MAPI. If the value of NmidInteger is set to an integer greater than 0x8000, or if it is absent, NmidPropset is set to PS_PUBLIC_STRINGS.

The DisplayName entry contains the label for the property. The SpecialType entry, if present and nonzero indicates that this property is a special property. At present, the only special property type defined is SpecialType = 1, which indicates string enumerated properties. If SpecialType is set to 1, the Enum1 entry references the [Enum1.string] section.

Following is an example of a [Properties] section and a [Properties.string] section.

Copy code Copy code
[Properties]
Property.1 = Fire Hazard
Property.2 = Safe
[Property.Fire Hazard]
Type = 1
NmidPropSet = {E47F4480-8400-101B-934D-04021C007002]
NmidString = FireHazard
DisplayName = Fire Hazard
SpecialType = 1
Enum1 = HazardEnum

The Enum1 entry in the preceeding example references to a subsequent [Enum1.string] section describing an enumeration of a particular type. Such an enumeration associates the first property in the [Property.string] section with an integer property, called the index. Such an enumeration also contains a list of the possible values that the display-index pair can assume. Specifying a property type for the enumeration is unnecessary because by definition an Enum1 entry always has the PT_I4 type. The format for the [Enum1.string] section is:

[Enum1.string]

NmidPropset = guid

NmidString = string

NmidInteger = integer

EnumCount = integer

Val.integer.Display = string

Val.integer.Index = integer

The following is an example property definition for an enumerated property named Fire Hazard with possible values of Low, Medium, and High.

Copy code Copy code
[Properties]
Property1 = Fire Hazard
[Enum1.HazardEnum]
IdxNmidPropset={E47F4480-8400-101B-934D-04021C007002]
IdxNmidString=FireHazardEnum
EnumCount = 3
Val.1.Display = Low
Val.1.Index = 1
Val.2.Display = Medium
Val.2.Index = 2
Val.3.Display = High
Val.3.Index = 3

[Enum1.string] sections can be used by applications for two purposes: to speed up the filtering of properties by using the index instead of the string and to sort by a different order than the alphanumeric order of the string values. For example, sorting could be done based on Low-Medium-High order instead of High-Medium-Low order.


Form Configuration File [Verbs] Section

 Copy code hover
[image]

Form Configuration File [Verbs] Section
Send feedback

Published: July 16, 2012

The [Verbs] section lists the complete set of verbs supported by the form. The format of the [Verbs] section is:

[Verbs]

Verb1 = string

Following is an example of a [Verbs] section.

Copy code Copy code
[Verbs]
Verb1=1
Verb2=2

Each verb is defined in a separate [Verb.string] section. A [Verb.string] section describes a single verb offered by the form. The DisplayName entry in a [Verb.string] section specifies the command name displayed in the user interface. The Code entry corresponds to the verb number passed in the IMAPIForm::DoVerb method. The syntax for the [Verb.string] section is:

[Verb.string]

DisplayName = displayed string

Code = integer

Flags = integer

Attribs = integer

Following is an example of a [Verb.string] section.

Copy code Copy code
[Verb.1]
DisplayName=Reply
code=1
Flags=0
Attribs=2
[Verb.2]
DisplayName=Delete
Code=2
Flags=0
Attribs=2

Verbs listed in this section are retrieved by a client using the IMAPIFormInfo::CalcVerbSet method. Verbs are activated by calling the form's IMAPIForm::DoVerb method and passing it the code number of the verb to be performed.


Transport-Neutral Encapsulation Format (TNEF)

 Copy code hover
[image]

Transport-Neutral Encapsulation Format (TNEF)
Send feedback

Published: July 16, 2012

TNEF is a format for converting a set of MAPI properties—a MAPI message—into a serial data stream. The TNEF functions are primarily used by transport providers that need to encode MAPI message properties for transmission through a messaging system that does not support those properties directly. For example, an SMTP-based transport uses TNEF to encode properties like PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName), which do not have direct representations in the structure of an SMTP message.

The TNEF implementation defines several TNEF-specific attributes, each of which corresponds to a particular MAPI property. These attributes are used to encode their respective MAPI properties into the TNEF stream. In addition, a special attribute is defined that can be used to encapsulate any MAPI property that does not have a specific attribute corresponding to it. The reason these attributes are defined — instead of simply using a uniform encoding method for all MAPI properties — is to enable backward compatibility with non-MAPI-compliant software that is using TNEF.

The remainder of this section describes the structure and syntax of a TNEF stream, the mapping between MAPI properties and TNEF attributes, and important considerations for certain TNEF attributes.


TNEF Stream Structure

 Copy code hover
[image]

TNEF Stream Structure
Send feedback

Published: July 16, 2012

A TNEF stream begins with a 32-bit signature that identifies the stream as a TNEF stream. Following the signature is a 16-bit unsigned integer that is used as a key to cross-reference attachments to their location in the tagged message text. The remainder of the stream is a sequence of TNEF attributes. Message attributes appear first in the TNEF stream, and attachment attributes follow. Attributes that belong to a particular attachment are grouped together, beginning with the attAttachRenddata attribute.

Most of the constant values used in TNEF streams are defined in the TNEF.H header file. Notably, TNEF_SIGNATURE, LVL_MESSAGE, LVL_ATTACHMENT, and all the TNEF attribute identifiers are defined in this file. Other constants have the values indicated by their interpretation to a C language compiler. Typically, such constants are used to give the sizes of the following item. For example, sizeof(ULONG) in an item's definition indicates that an integer representing the size of the following unsigned long integer should occur in that place in the TNEF stream.

All integers in a TNEF stream are stored in little-endian binary form, but are shown in hexadecimal throughout this section. Checksum values are simply 16-bit unsigned integers that are the sum, modulo 65536, of the bytes of data that the checksum applies to. All attribute lengths are unsigned long integers, including any terminating null characters.

The key is a nonzero, 16-bit unsigned integer that signifies the initial value of the attachment reference keys. The attachment reference keys are assigned to each attachment sequentially beginning with the initial value that is passed to the OpenTnefStream function by the service provider that is using TNEF. The service provider should generate a random initial value for the key to minimize the chance that two messages use the same key.

The TNEF implementation uses attribute identifiers to map attributes to their corresponding MAPI properties. An attribute identifier is a 32-bit unsigned integer made up of two word values. The high-order word indicates the data type, such as string or binary, and the low-order word identifies the particular attribute. The data types in the high order word are:

Type | Value
atpTriples | 0x0000
atpString | 0x0001
atpText | 0x0002
atpDate | 0x0003
atpShort | 0x0004
atpLong | 0x0005
atpByte | 0x0006
atpWord | 0x0007
atpDword | 0x0008
atpMax | 0x0009

The low-order word values for each attribute are defined in the TNEF.H header file.


TNEF Stream Syntax

 Copy code hover
[image]

TNEF Stream Syntax
Send feedback

Published: July 16, 2012

This topic presents a Bakus-Nauer like description of the TNEF stream syntax. In this description, nonterminal elements that have a further definition are in italics. Constants and literal items are in bold. Sequences of elements are listed in order on a single line. For example, the Stream item consists of the constant TNEF_SIGNATURE, followed by a Key, followed by an Object. When an item has more than one possible implementation, the alternatives are listed on consecutive lines. For example, an Object can consist of a Message_Seq, a Message_Seq followed by an Attach_Seq, or just an Attach_Seq.

TNEF_Stream:

TNEF_SIGNATURE Key Object

Key:

a nonzero 16-bit unsigned integer

TNEF enabled transports generate this value before using the TNEF implementation to generate a TNEF stream.

Object:

Message_Seq Message_Seq Attach_Seq Attach_Seq

Message_Seq:

attTnefVersion attTnefVersion Msg_Attribute_Seq attTnefVersion attMessageClass attTnefVersion attMessageClass Msg_Attribute_Seq attMessageClass attMessageClass Msg_Attribute_Seq Msg_Attribute_Seq

attTnefVersion:

LVL_MESSAGE attTnefVersion sizeof(ULONG) 0x00010000 checksum

attMessageClass:

LVL_MESSAGE attMessageClass msg_class_length msg_class checksum

Msg_Attribute_Seq:

Msg_Attribute Msg_Attribute Msg_Attribute_Seq

Msg_Attribute:

LVL_MESSAGE attribute-ID attribute-length attribute-data checksum

Attribute-ID is one of the TNEF attribute identifiers, such as attSubject. Attribute-length is the length in bytes of the attribute data. Attribute-data is the data associated with the attribute.

Attach_Seq:

attRenddata attRenddata Att_Attribute_Seq

attRenddata:

LVL_ATTACHMENT attRenddata sizeof(RENDDATA) renddata checksum

Renddata is the data associated with the RENDDATA structure that contains the rendering information for the corresponding attachment. The RENDDATA structure is defined in the TNEF.H header file.

Att_Attribute_Seq:

Att_Attribute Att_Attribute Att_Attribute_Seq

Att_Attribute:

LVL_ATTACHMENT attribute-ID attribute-length attribute-data checksum

Attribute-ID, attribute-length, and attribute-data have the same meanings as for the Msg_Attribute item.


Mapping of TNEF Attributes to MAPI Properties

 Copy code hover
[image]

Mapping of TNEF Attributes to MAPI Properties
Send feedback

Published: July 16, 2012

The following table lists all the attributes defined in the TNEF implementation and their mappings to MAPI properties. In some cases, multiple MAPI properties are encoded as a single attribute. Some attributes have extended descriptions later in this section.

TNEF attribute | MAPI property or properties
attAidOwner | PR_OWNER_APPT_ID (PidTagOwnerAppointmentId)
attAttachCreateDate | PR_CREATION_TIME (PidTagCreationTime)
attAttachData | PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) or PR_ATTACH_DATA_OBJ (PidTagAttachDataObject)
attAttachment | For information about this mapping, see TNEF Attributes.
attAttachMetaFile | PR_ATTACH_RENDERING (PidTagAttachRendering)
attAttachModifyDate | PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime)
attAttachRenddata | PR_ATTACH_METHOD (PidTagAttachMethod), PR_RENDERING_POSITION (PidTagRenderingPosition)
attAttachTitle | PR_ATTACH_FILENAME (PidTagAttachFilename)
attAttachTransportFilename | PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName)
attBody | PR_BODY (PidTagBody)
attConversationID | PR_CONVERSATION_KEY (PidTagConversationKey) This property has been deprecated in Exchange Server: Its use persists in Outlook only, for locating IPM.MessageManager messages.
attDateEnd | PR_END_DATE (PidTagEndDate) See attDate Attributes for details.
attDateModified | PR_LAST_MODIFICATION_TIME See attDate Attributes for details.
attDateRecd | PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) See attDate Attributes for details.
attDateSent | PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) See attDate Attributes for details.
attDateStart | PR_START_DATE (PidTagStartDate) See attDate Attributes for details.
attFrom | PR_SENDER_ENTRYID (PidTagSenderEntryId) and PR_SENDER_NAME (PidTagSenderName)
attMAPIProps | For information about this attribute, see attMAPIProps.
attMessageClass | PR_MESSAGE_CLASS (PidTagMessageClass)
attMessageID | PR_SEARCH_KEY (PidTagSearchKey) See TNEF Correlation in X.400 Gateways and Transports.
attMessageStatus | PR_MESSAGE_FLAGS (PidTagMessageFlags)
attOriginalMessageClass | PR_ORIG_MESSAGE_CLASS (PidTagOriginalMessageClass)
attOwner | See attOwner.
attParentID | PR_PARENT_KEY (PidTagParentKey) This property has been deprecated. See API Elements Deprecated in This Edition for more information.
attPriority | PR_PRIORITY (PidTagPriority)
attRecipTable | PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients)
attRequestRes | PR_RESPONSE_REQUESTED (PidTagResponseRequested)
attSentFor | PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId)
attSubject | PR_SUBJECT (PidTagSubject)


TNEF Attributes

 Copy code hover
[image]

TNEF Attributes
Send feedback

Published: July 16, 2012

This section provides additional information about certain TNEF attributes. For more information about the MAPI properties that the attributes are mapped to, see the reference entries for the individual properties.


attMAPIProps

 Copy code hover
[image]

attMAPIProps
Send feedback

Published: July 16, 2012

The attMAPIProps attribute is special in that it can be used to encode any MAPI property that does not have a counterpart in the set of existing TNEF-defined attributes. The attribute data is a counted set of MAPI properties laid end-to-end. The format of this encoding, which allows for any set of MAPI properties, is as follows:

Property_Seq:

property-count Property_Value,...

There must be as many Property_Value items as the property-count value indicates.

Property_Value:

property-tag Property property-tag Proptag_Name Property

The property-tag is simply the value associated with the property identifier, such as 0x0037001F for PR_SUBJECT (PidTagSubject).

Property:

Value value-count Value,...

Value:

value-data value-size value-data padding value-size value-IID value-data padding

Proptag_Name:

name-guid name-kind name-id name-guid name-kind name-string-length name-string padding

The encapsulation of each property varies based on the property identifier and the property type. Property tags, identifiers, and types are defined in the Mapitags.h and Mapidefs.h header files.

If the property is a named property, then the property tag is immediately followed by the MAPI property name, consisting of a globally unique identifier (GUID), a type, and either an identifier or a Unicode string.

Multivalued properties and properties with variable length values, such as the PT_BINARY, PT_STRING8, PT_UNICODE, or PT_OBJECT property types, are treated in the following way. First the number of values, encoded as a 32-bit unsigned long, is placed in the TNEF stream, followed by the individual values. Each property's value-data is encoded as its size in bytes followed by the value-data itself. The value-data is padded out to a 4-byte boundary, although the amount of padding is not included in the value-size.

If the property is of type PT_OBJECT, the value-size is followed by the interface identifier of the object. The current implementation of TNEF only supports the IID_IMessage, IID_IStorage, and IID_Istream interface identifiers. The size of the interface identifier is included in the value-size.

If the object is an embedded message (that is, it has a property type of PT_OBJECT and an interface identifier of IID_Imessage), the value data is encoded as an embedded TNEF stream. The actual encoding of an embedded message in TNEF implementation is done by opening a second TNEF object for the original stream and processing the stream inline.


attDate Attributes

 Copy code hover
[image]

attDate Attributes
Send feedback

Published: July 16, 2012

All MAPI properties relating to dates and times are mapped to TNEF attributes that have the attDate prefix. These are all encoded as DTR structures. The dates and times for attachment attributes are encoded as DTR structures as well.

All MAPI properties relating to dates and times are mapped to TNEF attributes that have the attDate prefix. These are all encoded as DTR structures. The dates and times for attachment attributes are encoded as DTR structures as well.

A DTR structure is very similar to the SYSTEMTIME structure defined in the Win32 header files. The DTR structure is encoded in the TNEF stream as sizeof(DTR) bytes starting with the first member of the structure. The DTR structure is defined in the TNEF.H header file.


attOriginalMessageClass

 Copy code hover
[image]

attOriginalMessageClass
Send feedback

Published: July 16, 2012

A message class is stored as a string. The encoded string usually holds the MAPI-specified name of the message class.


attConversationID and attParentID

 Copy code hover
[image]

attConversationID and attParentID
See also Send feedback

Published: July 16, 2012

The Windows for Workgroups 3.1 Mail conversation key is a text string. The MAPI equivalent is a binary value. To provide backward compatibility, the TNEF implementation converts the binary data to text and adds a terminating null character.

Note Note

The corresponding properties in MAPI to which these TNEF attributes are mapped, PR_CONVERSATION_KEY and PR_PARENT_KEY, have been deprecated in Exchange Server: Use of PR_CONVERSATION_KEY, the PidTagConversationKey Canonical Property, persists in Outlook only, for locating IPM.MessageManager messages.

Remarks

The PR_CONVERSATION_KEY property is the otherwise obsolete precursor of the PR_CONVERSATION_INDEX, PidTagConversationIndex Canonical Property and PR_CONVERSATION_TOPIC, PidTagConversationTopic Canonical Property, which should be used instead.

See also

Concepts

IPM Subtree
MAPI Special Folders


attFrom

 Copy code hover
[image]

attFrom
Send feedback

Published: July 16, 2012

The attFrom attribute is encoded as a TRP structure which encodes the display name and e-mail address of the sender, followed by the display name and address of the sender, followed by any necessary padding. The format for attFrom is as follows:

attFrom:

TRP-structure sender-display-name sender-address padding

The sender-display-name is a null-terminated string that is padded with an additional null character, if necessary, to reach a 2-byte boundary. The padding at the end of the attFrom encoding consists of as many null characters as needed to reach a sizeof(TRP) boundary.

TRP-structure:

trpidOneOff cbgrtrp cch cb

For the attFrom item, the TRP-structure is always a one-off encoding, so the trpid off the TRP-structure field is always trpidOneOff. The cbgrtrp, cch, and cb items correspond to the remaining fields of the TRP structure.

The cbgrtrp field is calculated as the sum of (sizeof(TRP) *2), the length of the null-terminated sender-display-name with its padding, and the length of the null-terminated sender-address.

The cch field is calculated as the length of the null-terminated display-name with its padding.

The cb field is calculated as the length of the null-terminated sender-address.

sender-address:

address-type : address '\0'

The sender-address is a string that is composed of four parts, the address-type, a literal colon (:), the address itself, and a terminating null character. For example, the string "fax:1-909-555-1234\0" would be a legal sender-address value.


attOwner

 Copy code hover
[image]

attOwner
Send feedback

Published: July 16, 2012

The attOwner attribute is encoded as counted strings laid end-to-end. The format for attOwner is as follows:

attOwner:

display-name-length display-name address-length email-address

email-address

type : address

Unlike other length values, the display-name-length and address-length are unsigned 16-bit values instead of unsigned long integers. They still include terminating null characters, however. The type and address strings in the email-address entry are separated by a literal colon (:) character, such as "smtp:joe@nowhere.com". Only the combined type:address string is null-terminated.

The mapping of MAPI properties to the attOwner attribute is dependent on the message class of the message being encoded.


attSentFor

 Copy code hover
[image]

attSentFor
Send feedback

Published: July 16, 2012

The attSentFor attribute is encoded as counted strings laid end-to-end. The format for attSentFor is as follows:

attSentFor:

display-name-length display-name address-length email-address

email-address

type : address

Unlike other length values, the display-name-length and address-length are unsigned 16-bit values instead of unsigned long integers. They still include terminating null characters, however. The type and address strings in the email-address entry are separated by a literal colon (:) character, such as "smtp:joe@nowhere.com". Only the combined type:address string is null-terminated.


attRecipTable

 Copy code hover
[image]

attRecipTable
Send feedback

Published: July 16, 2012

When a recipient table is being encoded, each recipient is encoded as a row of MAPI properties. The format is as follows:

Row_Seq:

row-countProperty_Sequence, ...

The format of Property_Seq is the same as in the attMAPIProps attribute.


attPriority

 Copy code hover
[image]

attPriority
Send feedback

Published: July 16, 2012

MAPI message priorities are mapped to TNEF values for backward compatibility as follows:

Priority | MAPI value | TNEF value
normal | -1 | 3
high | 0 | 2
low | 1 | 1


attMessageStatus

 Copy code hover
[image]

attMessageStatus
Send feedback

Published: July 16, 2012

MAPI message flags are mapped to TNEF flags to preserve backward compatibility. All the flags are grouped together and encoded in a single byte. The mappings are as follows:

MAPI message flags | TNEF flags
MSGFLAG_READ | fmsRead
MSGFLAG_UNMODIFED | ~fmsModified
MSGFLAG_SUBMIT | fmsSubmitted
MSGFLAG_HASATTACH | fmsHasAttach
MSGFLAG_UNSENT | fmsLocal

These flags are defined in the TNEF.H header file.


attAttachRenddata

 Copy code hover
[image]

attAttachRenddata
Send feedback

Published: July 16, 2012

The attAttachRenddata attribute is encoded as a RENDDATA structure that describes how and where the attachment is rendered in the message text. The RENDDATA structure is simply encoded in the TNEF stream as sizeof(RENDDATA) bytes beginning with the first member of the RENDDATA structure. If the value of the RENDDATA structure's dwFlags member is set to MAC_BINARY, then the data for the following attachment is stored in MacBinary format; otherwise, the attachment data is encoded as usual.


OLE Attachments

 Copy code hover
[image]

OLE Attachments
Send feedback

Published: July 16, 2012

Attachments that are OLE objects are encoded as OLE 1 stream objects for backward compatibility. If the original object is really an OLE 2 IStorage object, then the object must be converted to an OLE 1 stream. This conversion is performed using the OleConvertIStorageToOLESTREAM function, which is part of the Win32 OLE libraries.


TNEF Correlation

 Copy code hover
[image]

TNEF Correlation
Send feedback

Published: July 16, 2012

Some messaging systems perform a correlation check on any Transport-Neutral Encapsulation Format (TNEF) stream attached to an inbound message to verify that the TNEF stream does in fact belong to that message. This involves matching the value of some field in the header of the inbound message with a copy of that value stored in some property in the TNEF stream. Values that are presumably unique for each message, such as message ID numbers, are typically used for this. The transport or gateway that created the TNEF stream is responsible for choosing an appropriate value from the message header and placing a copy into an appropriate property before encoding the outgoing message's properties into the TNEF stream. Gateways or transports that receive the message can then extract that property from the TNEF stream and verify that its value matches the value of the corresponding header field on the inbound message.

If the values do not match, the gateway or transport should discard the TNEF stream and process only the native message envelope. Such checks are prudent because non-MAPI-based mail clients may attach a file that contains a TNEF stream from an old message to a forwarding or even an unrelated message; if not checked, such an error may cause the loss of message text.

The header field value chosen must be unique to the message. There is no fixed header field for all messaging systems because different messaging systems use different header fields, but typically the messaging system assigns a unique identifier to the message which is suitable for this purpose. For example, SMTP systems typically use the MessageID header, while X.400 systems typically use the IM_THIS_IPM attribute.


TNEF Correlation in SMTP Gateways and Transports

 Copy code hover
[image]

TNEF Correlation in SMTP Gateways and Transports
Send feedback

Published: July 16, 2012

Gateways and transports that connect to internet based systems, those that use SMTP, use the value of the MessageID SMTP header and the PR_TNEF_CORRELATION_KEY property to implement TNEF correlation.

The value of the MessageID header of the outbound message should be copied to the PR_TNEF_CORRELATION_KEY (PidTagTnefCorrelationKey) property and encoded in the attMAPIProps attribute of the TNEF stream. Note that PR_TNEF_CORRELATION_KEY is a binary property, while the MessageID is a string; the null terminator should be included in the copy and in the comparison.

This technique is used by all Microsoft software that connects MAPI-based messaging systems to the Internet, such as Microsoft Exchange Server. This technique should be used by any SMTP gateways and transports that connect to systems that support MAPI clients in order to maximize interoperability.


TNEF Correlation in X.400 Gateways and Transports

 Copy code hover
[image]

TNEF Correlation in X.400 Gateways and Transports
Send feedback

Published: July 16, 2012

Gateways and transports that connect to X.400-based systems, use the value of the IM_THIS_IPM X.400 attribute and the attMessageID TNEF attribute to implement TNEF correlation.

The value of the IM_THIS_IPM attribute of the outbound message is copied to attMessageID in the TNEF stream. The IM_THIS_IPM X.400 attribute is typically a string, while the attMessageID TNEF attribute is a string of hexadecimal digits representing a binary value. Therefore, each character in the IM_THIS_IPM X.400 attribute, including the terminating null character, must be converted to a 2-character hexadecimal string representing the ASCII value of that character. For instance, if the IM_THIS_IPM X.400 attribute is the following string:

3030322D3030312D305337533A3A3936303631312D313533373030

then the value of attMessageID would be the following sequence of hexadecimal digits:

33 30 33 30 33 32 32 44

33 30 33 30 33 31 32 44

33 30 35 33 33 37 35 33

33 41 33 41 33 39 33 36

33 30 33 36 33 31 33 31

32 44 33 31 33 35 33 33

33 37 33 30 33 30 00

This technique is used by the Microsoft Exchange Server X.400 Connector. This technique should be used by any X.400 gateways and transports that connect to Microsoft Exchange Server in order to maximize interoperability.

For greatest compatibility with future as well as present Microsoft software, the IM_THIS_IPM X.400 attribute should also be copied to the PR_TNEF_CORRELATION_KEY (PidTagTnefCorrelationKey) property. However, since PR_TNEF_CORRELATION_KEY is a binary property, no translation into a hexadecimal string is necessary.


MAPI Programming Elements

 Copy code hover
[image]

MAPI Programming Elements
See also Send feedback

Published: July 16, 2012

This section contains conceptual overviews of the programming elements in the MAPI Reference.

See also

Other resources

MAPI Concepts


MAPI Object and Interface Overview

 Copy code hover
[image]

MAPI Object and Interface Overview
See also Send feedback

Published: July 16, 2012

A MAPI object is a C++ object class or C data structure inherited from one or more MAPI interfaces, or collections of related functions. These collections of related functions are known to C++ developers as pure virtual functions. For a pure virtual function, MAPI supplies only the function prototype, not an implementation. It is expected that a client application, a service provider, or MAPI will provide this implementation by creating an object class that inherits from the interface and conforms to the function descriptions of the Messaging API. A MAPI interface can be instantiated only through an inherited class.

There are many different MAPI objects, each object inheriting from an interface that is ultimately inherited from the IUnknown interface. IUnknown is the OLE Component Object Model (COM) base interface. It provides MAPI objects with a standard mechanism for communication and control. COM dictates how object implementers handle issues such as memory management, parameter management, and multithreading. By conforming to this model, an object implementer adheres to a contract as specified by the interfaces included in the object.

Many MAPI interfaces are inherited directly from IUnknown, while others are inherited indirectly through one of two other base interfaces: IMAPIProp : IUnknown for property management and IMAPIContainer : IMAPIProp for folder and address book access. Base interfaces are never implemented as separate, standalone objects; they are always implemented as part of other objects, objects that implement derived interfaces.

MAPI defines many types of objects, each implemented by one or more MAPI components. Objects implemented by clients are used by MAPI, by service providers, and by custom form components. Objects implemented by service providers are typically used by MAPI and by clients. Objects implemented by form library providers and form servers are used by other form components and by clients.

See also

Reference

IMAPIProp : IUnknown
IMAPIContainer : IMAPIProp

Other resources

MAPI Concepts


Component Object Model and MAPI

 Copy code hover
[image]

Component Object Model and MAPI
See also Send feedback

Published: July 16, 2012

The Windows SDK documentation includes a comprehensive discussion of the rules for implementing objects that conform to the Component Object Model (COM). These rules address how to do the following:

  • Design interfaces and objects.

  • Implement the IUnknown interface.

  • Manage memory.

  • Handle reference counting.

  • Implement apartment-threaded objects.

Although all MAPI objects are considered COM-based because they implement interfaces that inherit from IUnknown, MAPI deviates in some situations from the standard COM rules. This deviation allows developers more flexibility in their implementations. For example, a MAPI interface, like any COM interface, describes a contract between implementer and caller. Once the interface is created and published, its definition cannot and does not change. MAPI does not deviate from this description, but it relaxes the description somewhat. Implementers can choose to not implement particular methods, returning one of the following error values to the caller:

  • MAPI_E_NO_SUPPORT

  • MAPI_E_TOO_COMPLEX

  • MAPI_E_BAD_CHARWIDTH

  • MAPI_E_TYPE_NO_SUPPORT

The other deviations from the standard COM rules are described in the following table.

COM programming rule | MAPI variation
All string parameters in interface methods should be Unicode. | MAPI interfaces are defined to permit either Unicode or ANSI string parameters. Many methods that have a string parameter also have a ulFlags parameter; the width of a string parameter is indicated by the value of the MAPI_UNICODE flag in ulFlags. Some MAPI interfaces do not support Unicode and return MAPI_E_BAD_CHARWIDTH when the MAPI_UNICODE flag is set.
All interface methods should have a return type of HRESULT. | MAPI has at least one method that returns a non-HRESULT value: IMAPIAdviseSink::OnNotify.
Callers and implementers should allocate and free memory for interface parameters by using the standard COM task allocators. | All MAPI methods use the linked allocators MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer to manage memory for interface parameters. All MAPI implementations of interfaces defined by OLE, such as IStream, use the standard COM task allocators.
All out pointer parameters must explicitly be set to NULL when a method fails. | MAPI interfaces require that out pointer parameters either be set to NULL or remain unchanged when a method fails. All MAPI implementations of interfaces defined by OLE explicitly set out parameters to NULL on failure.
Implement aggregatable objects whenever possible. | MAPI interfaces are not aggregatable.

See also

Reference

MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer

Concepts

MAPI Object and Interface Overview


Objects and the MAPI Architecture

 Copy code hover
[image]

Objects and the MAPI Architecture
See also Send feedback

Published: July 16, 2012

All of the objects that MAPI defines fall into one or more layers in the MAPI architecture. The client interface layer contains all the objects that a client application, form viewer, or form server can implement. The service provider interface layer contains the objects that a service provider of any type can implement. This layer includes objects implemented by address books, message stores, transport providers, and form libraries. The layer that represents the MAPI subsystem is positioned between the client and service provider interface layers. The MAPI layer contains all of the objects that MAPI implements for clients or service providers to use.

The following illustration shows where each of the MAPI objects fits into the MAPI architecture. The objects are represented with the names of their derived interfaces. For example, an advise sink object is shown as IMAPIAdviseSink : IUnknown, the interface that derives from IUnknown and that every advise sink object implements. The interfaces that bridge layers are either used or implemented by multiple components. Although the MAPI layer appears to separate the client and provider layers, implying that all communication must flow through MAPI, this is not the case. Clients can and do communicate directly to service provider objects.

Object layers in MAPI

Object layers in MAPI

See also

Reference

IMAPIAdviseSink : IUnknown

Concepts

MAPI Object and Interface Overview


MAPI Object Inheritance Hierarchy

 Copy code hover
[image]

MAPI Object Inheritance Hierarchy
See also Send feedback

Published: July 16, 2012

All interfaces implemented by MAPI objects ultimately inherit from IUnknown, the OLE interface that enables objects to communicate. Most interfaces directly inherit from IUnknown, but some inherit from one of two other base interfaces: IMAPIProp : IUnknown or IMAPIContainer : IMAPIProp. The following illustration shows the complete inheritance hierarchy in MAPI.

MAPI inheritance hierarchy

MAPI inheritance hierarchy

See also

Reference

IMAPIProp : IUnknown
IMAPIContainer : IMAPIProp

Concepts

MAPI Object and Interface Overview


MAPI Object Containment Hierarchy

 Copy code hover
[image]

MAPI Object Containment Hierarchy
See also Send feedback

Published: July 16, 2012

The containment relationship between objects specifies the dependencies that some objects have on other objects for access. For a client application, access to particular objects enables access to others. In some cases, the containment relationship between objects implemented by a service provider follows a logical hierarchy. In other cases, it is arbitrary.

A client must obtain access to a MAPI session object before it can use many other objects (for example, service providers and the MAPI address book).

Message store containment is based on the hierarchical relationship between objects in the message store: the message store object itself, folders, messages, and attachments. Logically, attachments are contained in messages, messages in folders, and folders in the message store. The containment relationship matches this logical hierarchy. To gain access to a message, for example, a client must first access the folder in which the message is contained. Profiles and status objects are examples of a more arbitrary containment relationship. Both of these objects are available through the session.

With some objects, containers provide the only access. Attachments and recipients are examples of objects that are totally dependent on their containers. The only access to an attachment or a recipient is through the message to which it belongs. Other objects have alternate access paths. These objects are assigned binary identifiers, known as entry identifiers, by the service providers that create them. Entry identifiers can be used to access their objects directly, enabling clients to bypass the containment tree.

The following illustration shows the MAPI containment hierarchy. The session is at the top of the tree because it is through the session that a client gains access to all other objects. The next level includes the message store table, a table object that lists properties for all of the message store providers in the current session, and the address book to supply access to all of the address book providers. The message store table and address book are used to access the objects implemented by particular service providers, shown next, in containment order.

MAPI containment hierarchy

MAPI containment hierarchy

See also

Concepts

MAPI Object and Interface Overview


MAPI-Implemented Objects

 Copy code hover
[image]

MAPI-Implemented Objects
See also Send feedback

Published: July 16, 2012

MAPI implements several objects for use by client applications and service providers. The session object allows clients to use session services, to access tables, and to communicate with service providers. The address book object provides clients with integrated access to all of the different address book providers.

MAPI supplies multiple table and status objects for clients to use for viewing and monitoring session and service provider information. For example, MAPI provides a profile table with information about all of the profiles that are installed on the computer and a message service table with information about all of the message services in the current profile. MAPI provides three different status objects: one that represents the overall subsystem, one for the MAPI spooler, and one for the integrated address book.

MAPI implements four different objects for managing the configuration of message services, service providers, and profiles. Both clients and service providers use provider administration and profile section objects; these objects enable them to configure service providers and access profile properties. Clients use only message service and profile administration objects, the objects that support the administration of message services and profiles.

MAPI provides two objects for service providers: a support object and a TNEF object. All service providers use one or more support objects; there are four different support object implementations. MAPI supplies an implementation to support configuration as well as specific implementations to support address book, message store, and transport providers. The TNEF object is used by transport providers that support the Transport Neutral Encapsulation Format (TNEF).

Two utility objects, table data and property data, are typically used by service providers. Table data objects help in the implementation of table objects; property data objects help to set and view property access and help in the implementation of IMAPIProp : IUnknown, the base property interface.

The following table summarizes the purpose for each object that MAPI implements.

MAPI object | Description
Address book | Provides access to the integrated view of recipient information that belongs to all of the address book providers in the active profile.
Message service administration | Provides access to message service information for configuration.
Profile administration | Provides access to profile information for configuration.
Profile section | A part of a profile used to describe a particular message service or service provider.
Property data | Maintains access to properties and helps implement IMAPIProp.
Provider administration | Provides access to service provider information for configuration.
Session | Represents a connection to underlying messaging systems and provides clients with access to MAPI resources.
Status | Provides access to the state of the MAPI subsystem, the address book, or the MAPI spooler.
Support | Helps service providers handle client requests.
Table | Provides access to a summary view of object data in row and column format, similar to a database table.
Table data | Maintains access to underlying table data and implements table objects.
TNEF | Supports the use of the Transport Neutral Encapsulation Format (TNEF).

The following illustration shows the relationship between the objects that MAPI implements, the interfaces from which they inherit, and the components that use them.

Objects that MAPI implements

Objects that MAPI implements

See also

Reference

IMAPIProp : IUnknown

Concepts

MAPI Object and Interface Overview


MAPI Client Objects

 Copy code hover
[image]

MAPI Client Objects
See also Send feedback

Published: July 16, 2012

Standard messaging client applications implement only one object — an advise sink. Advise sinks inherit from the IMAPIAdviseSink : IUnknown interface and are used by MAPI and service providers for event notification. Some clients also implement progress objects to support the display of progress dialog boxes.

More complex clients that support custom forms implement another advise sink object and a few other objects, such as the message site object that inherits from the IMAPIMessageSite : IUnknown interface and the view context object that inherits from the IMAPIViewContext : IUnknown interface. The additional advise sink object inherits from the IMAPIViewAdviseSink : IUnknown interface.

The following table summarizes the MAPI objects implemented by standard messaging clients and by clients that support the viewing of custom forms.

Client object | Description
Advise sink | Provides a callback function for events that occur in the message store, address book, or the session.
Message site | Handles the manipulation of form objects.
Progress | Displays a dialog box to show the progress of an operation.
View advise sink | Provides callback functions for events that occur in a form.
View context | Supports commands for printing and saving forms and for navigating between forms.

The following illustration shows the relationship between these different client objects, the interfaces from which they inherit, and the MAPI components that use them.

Client objects and corresponding interfaces

Clients use many more objects than they implement. All clients use a session object to gain access to a wide variety of service provider objects and objects that MAPI implements. Clients interact with service providers either indirectly, through the session, the address book, or the status objects that MAPI supplies, or directly through a variety of objects that particular service providers implement. To make direct contact with address book providers, clients use address book containers, messaging users, and distribution lists. To access a message store provider directly, clients use the message store object, folders, messages, and attachments. When service providers support a status object, clients can use the status object to monitor the service provider's state.

Clients that support service provider and message service configuration use three objects that MAPI implements: the message service administration object, profile administration object, and provider administration object. Clients that display custom forms use several form objects that a form library provider or a form server implements.

See also

Reference

IMAPIMessageSite : IUnknown
IMAPIViewContext : IUnknown
IMAPIViewAdviseSink : IUnknown

Concepts

MAPI Object and Interface Overview


MAPI Service Provider Objects

 Copy code hover
[image]

MAPI Service Provider Objects
See also Send feedback

Published: July 16, 2012

Service providers implement many objects. Some are used primarily by MAPI and some are used by client applications. A few objects are implemented by all types of service providers; the rest are specific to a single provider type. The following table describes all of the service provider objects.

Service provider object | Description
Address book container | Contains recipient information for one address book provider in the active profile; address book providers can have one or more address book containers.
Attachment | Contains additional data, such as a file or OLE object, to be associated with a message.
Control | Enables or disables a button and initiates processing when the button is clicked.
Distribution list | Describes a grouping of individual message recipients.
Folder | Contains messages and other message containers.
Logon | Handles service provider event notification and client requests.
Messaging user | Describes an individual recipient of a message.
Message | Contains information that can be sent to one or more recipients.
Message store | Acts as a hierarchically organized database of messages.
Provider | Handles service provider startup and shutdown.
Spooler hook | Performs special processing on inbound and outbound messages.
Status | Provides access to the service provider's state.
Table | Provides access to a summary view of object data in row and column format, similar to a database table.

All service providers implement a provider object and a logon object. Provider objects are strictly for bookkeeping; they are used by MAPI to control the startup and shutdown processes. Logon objects service some client requests indirectly. For example, the message store provider's logon object handles notification registration and requests to open message store objects.

Provider and logon objects implement a different interface depending on the type of service provider that supplies the implementation. A message store provider implements the IMSProvider : IUnknown and IMSLogon : IUnknown interfaces in its provider and logon objects, an address book provider implements the IABProvider : IUnknown and IABLogon : IUnknown interfaces, and a transport provider implements the IXPProvider : IUnknown and IXPLogon : IUnknown interfaces.

Message hook providers implement spooler hook objects, or objects that filter inbound and outbound messages.

Service providers typically use only a few objects. Most frequently, they use a support object that MAPI provides to help implement client requests. The support object is customized for the type of provider that is using it. For all service providers, the support object includes methods for handling event notification, displaying configuration properties, opening objects, and error handling. The rest of the methods are specific to its use; there are customized versions for address book, message store, and transport providers, and for configuration support. For example, the address book support object displays details and custom recipient dialog boxes. The message store support object supports copy and move operations for folders and messages. The transport provider support object includes methods for facilitating interaction with the MAPI spooler.

Some service providers use table data and property data objects — utility objects that MAPI implements. Table data objects enable service providers to manage the underlying data of a table. Property data objects enable service providers to set object and property access.

Transport providers that support the Transport Neutral Encapsulation Format (TNEF) for transferring properties use a TNEF object that MAPI implements to support the ITnef : IUnknown interface. For more information, see Developing a TNEF-Enabled Transport Provider.

See also

Reference

ITnef : IUnknown
IMSProvider : IUnknown
IMSLogon : IUnknown
IABProvider : IUnknown
IABLogon : IUnknown
IXPProvider : IUnknown
IXPLogon : IUnknown

Concepts

Developing a TNEF-Enabled Transport Provider


MAPI Address Book Provider Objects

 Copy code hover
[image]

MAPI Address Book Provider Objects
See also Send feedback

Published: July 16, 2012

In addition to the standard provider and logon objects, address book providers implement address book containers, distribution lists, messaging users, tables, status objects, and controls.

The following illustration shows these objects, their corresponding interfaces, and the MAPI components that use them.

Objects that address book providers implement

See also

Concepts

MAPI Service Provider Objects


MAPI Message Store Provider Objects

 Copy code hover
[image]

MAPI Message Store Provider Objects
See also Send feedback

Published: July 16, 2012

Message store providers implement provider and logon objects, as do all service providers. They also implement a message store object, folders, messages, attachments, and tables. As an option, some message store providers implement status objects.

The following illustration shows each message store object with its corresponding interface and the MAPI component that uses it.

Objects that message store providers implement

See also

Concepts

MAPI Service Provider Objects


MAPI Transport Provider Objects

 Copy code hover
[image]

MAPI Transport Provider Objects
See also Send feedback

Published: July 16, 2012

In addition to the standard provider and logon objects implemented by all service providers, transport providers are required to implement a status object. For the other service provider types, implementing a status object is optional. However, MAPI requires it for transport providers. Transport providers that support the downloading of message headers from a remote server also implement a folder and a table.

The following illustration shows each of the objects that transport providers can implement with their corresponding interfaces. The illustration also indicates whether MAPI or a client is the object's user.

Objects that transport providers implement

See also

Concepts

MAPI Service Provider Objects


MAPI Custom Form Objects

 Copy code hover
[image]

MAPI Custom Form Objects
See also Send feedback

Published: July 16, 2012

Objects for custom forms are implemented by three different components:

  • A form server.

  • A form library provider.

  • A form viewer.

A form server is similar in functionality to an OLE compound document object application. It is an executable component that implements the form; it controls its display and the operations that a user can perform. MAPI starts a form server upon request when a user wants to view a message together with a message class that is displayed by using a form supported by the form server. Form servers implement three objects: a form factory object that resembles the standard OLE class factory, a form advise sink for handling form-specific events, and the form itself.

A form library provider supplies access for clients to a form's property set, to its container, and to the object that links messages of a specific class to the server that can open the form for that class. Form library providers implement three objects: a form information object, a form container, and a form manager for binding a message to the appropriate form server based on the message's class.

A form viewer is a component that is included in clients that support the display of custom forms in their folder viewers. Form viewers are not independent MAPI components, as are form library providers and form servers. Form viewers start form servers and provide context for them. Form viewers implement three objects: a message site, a view context, and an advise sink for handling view-specific events.

The following table describes all of the custom form objects.

Form object | Description
Form | Controls the display and operation of a custom form for viewing messages of a specific class.
Form advise sink | Handles notifications from the form viewer.
Form factory | Creates an instance of a form and allows its server to remain in memory.
Form container | Contains form information.
Form information | Contains messages and other message containers.
Form manager | Provides access to an integrated view of custom form information that is related to all of the installed forms. Also matches message classes with corresponding form class identifiers.
Message site | Handles the manipulation of form objects from inside the client, and provides access to a form manager object.
View context | Supports form commands for activating next and previous messages and for saving or printing.
View advise sink | Handles notifications from the form server.

The following illustration shows the relationship between custom form components, the objects and interfaces that they implement, and the components that are users of the objects. Notice that, unlike most other MAPI objects, the form object implements two interfaces that are not related by direct inheritance. When an object exposes multiple independent interfaces, a user of the object that has a pointer to one of the interfaces can retrieve a pointer to any of the other interfaces. This ability to navigate between an object's interface implementations is a feature of the IUnknown::QueryInterface method.

Custom form components

Custom form components

See also

Concepts

MAPI Object and Interface Overview


Using MAPI Objects

 Copy code hover
[image]

Using MAPI Objects
See also Send feedback

Published: July 16, 2012

Clients and service providers use MAPI objects by calling the methods in their interface implementations. This is the only way that MAPI objects can be used; methods that are implemented by an object outside of a MAPI interface are not publicly accessible. Because all of an object's interfaces are related through inheritance, an object's user can call methods in either the base interface or one of the inherited interfaces as if they belong to the same interface.

When an object's user wants to make a call to a method and that object implements several interfaces related through inheritance, the user need not know to which interface the method belongs. The user can call any of the methods on any of the interfaces with a single pointer to the object. For example, the following illustration shows how a client application uses a folder object. Folder objects implement the IMAPIFolder : IMAPIContainer interface, which inherits from IUnknown indirectly through IMAPIProp : IUnknown and IMAPIContainer : IMAPIProp. A client can call one of the IMAPIProp methods, such as IMAPIProp::GetProps, and one of the IMAPIFolder : IMAPIContainer methods, such as IMAPIFolder::CreateMessage, in the same way with the same object pointer. A client is not aware of or affected by the fact that these calls belong to different interfaces.

Client use of a folder object

Client use of a folder object

These calls translate into code differently depending on whether the client making the calls is written in C or C++. Before any call to a method can be made, a pointer to the interface implementation must be retrieved. Interface pointers can be obtained in the following ways:

  • Calling a method on a different object.

  • Calling an API function.

  • Calling the IUnknown::QueryInterface method on the target object.

MAPI provides several methods and API functions that return pointers to interface implementations. For example, clients can call the IMAPISession::GetMsgStoresTable method to retrieve a pointer to a table object that provides access to message store provider information through the IMAPITable : IUnknown interface. Service providers can call the API function CreateTable to retrieve a pointer to a table data object. When there is no function or method available and clients or service providers already have a pointer to an object, they can call the object's QueryInterface method to retrieve a pointer to another of the object's interface implementations.

See also

Concepts

MAPI Object and Interface Overview


Implementing MAPI Objects

 Copy code hover
[image]

Implementing MAPI Objects
See also Send feedback

Published: July 16, 2012

MAPI objects can be implemented by using C++ classes or C data structures, depending on the language and the API set a client or service provider is using. Service providers can be written in C or C++ with the MAPI service provider interface; client applications can also use C or C++. If possible, clients and service providers that use the object-oriented programming interface should use C++.

C++ is the preferred choice because MAPI is an object-oriented technology, and C++ lends itself more readily to object-oriented development. The resulting code is simpler and more straightforward, making it easier to maintain. The MAPI documentation is written primarily for C++ developers; all of the syntax descriptions for the MAPI interface methods in this Reference are in C++.

Developers can use Microsoft Visual Studio and third-party development tools to develop solutions that call MAPI. Note that developers should use C or unmanaged C++, but not managed C++ to write MAPI solutions.

When a MAPI object is implemented, a client or service provider creates code for all of the interface methods, code for any private methods that are specific to the implementation, and code to support private data members for maintaining state information. The code for the interface methods must follow the specifications published by MAPI that document expected behavior.

There are many macros in the Mapidefs.h header file and OLE header files that clients and service providers in either language can use to help them with their definitions of MAPI objects. For example, there is a macro to define the methods of each of the MAPI interfaces. The macro to define the methods of the IUnknown interface appears in Mapidefs.h as follows:

C++ Copy code Copy code
#define MAPI_IUNKNOWN_METHODS(IPURE)          \
    MAPIMETHOD(QueryInterface)                \
        (THIS_ REFIID riid, LPVOID FAR * ppvObj) IPURE;    \
    MAPIMETHOD_(ULONG,AddRef)  (THIS) IPURE;               \
    MAPIMETHOD_(ULONG,Release) (THIS) IPURE;   \

See also

Concepts

MAPI Object and Interface Overview


Implementing Objects in C++

 Copy code hover
[image]

Implementing Objects in C++
See also Send feedback

Published: July 16, 2012

C++ clients and service providers define MAPI objects by creating classes that inherit from the interfaces they are implementing. Each of the interface methods is public, as are the constructor and destructor for the class. If the class has additional methods, they can be public or private, depending on the implementation. All data members are private.

The following example code shows how to define a C++ status object. The CMyMAPIObject class inherits from the IMAPIStatus : IMAPIProp interface. Many of the macros used in this example are defined in the OLE header file Compobj.h. The first members of the class are the methods of the base interface, followed by the methods of the inherited interfaces in order of inheritance. Following the interface definitions are any additional methods, the constructor and destructor, and the data members.

C++ Copy code Copy code
class  CMyMAPIObject : public IMAPIStatus
{
public:
// Methods of IUnknown.
    STDMETHODIMP QueryInterface (REFIID riid, LPVOID * ppvObj);
    STDMETHODIMP_(ULONG) AddRef ();
    STDMETHODIMP_(ULONG) Release ();
    MAPI_IMAPIPROP_METHODS(IMPL);
    MAPI_IMAPISTATUS_METHODS(IMPL);
// Other methods specific to CMyMAPIObject.
    BOOL WINAPI Method1 ();
    void WINAPI Method2 ();
// Constructors and destructors.
public :
    CMyMAPIObject () {};
    ~CMyMAPIObject () {};
// Data members specific to CMyMAPIObject.
private :
    ULONG               m_cRef;
    CAnotherObj *       m_pObj;
};

To use an instance of the CMyMAPIObject class, C++ clients or service providers make a call to one of its methods as follows:

C++ Copy code Copy code
lpMyObj->ValidateState(ulUIParam, ulFlags);

See also

Concepts

Implementing MAPI Objects


Implementing Objects in C

 Copy code hover
[image]

Implementing Objects in C
See also Send feedback

Published: July 16, 2012

Client applications and service providers written in C define MAPI objects by creating a data structure and an array of ordered function pointers known as a virtual function table, or vtable. A pointer to the vtable must be the first member of the data structure.

In the vtable itself, there is one pointer for every method in each interface supported by the object. The order of the pointers must follow the order of the methods in the interface specification published in the Mapidefs.h header file. Each function pointer in the vtable is set to the address of the actual implementation of the method. In C++, the compiler automatically sets up the vtable. In C, it does not.

The following illustration shows how this works. The box on the far left represents a client that needs to use a service provider object. Through the session, the client obtains a pointer to the object, lpObject. The vtable appears first in the object followed by private data and methods. The vtable pointer points to the actual vtable, which contains pointers to each of the implementations of the methods in the interface.

Object implementation

The following code example shows how a C service provider can define a simple status object. The first member is the vtable pointer; the rest of the object is made up of data members.

Copy code Copy code
typedef struct _MYSTATUSOBJECT
{
    const STATUS_Vtbl FAR *lpVtbl;

    ULONG              cRef;
    ANOTHEROBJ        *pObj;
    LPMAPIPROP         lpProp;
    LPFREEBUFFER       lpFreeBuf;

} MYSTATUSOBJECT, *LPMYSTATUSOBJ;

Because this object is a status object, the vtable includes pointers to implementations of each of the methods in the IMAPIStatus : IMAPIProp interface, as well as pointers to implementations of each of the methods in the base interfaces — IUnknown and IMAPIProp. The order of methods in the vtable matches the specified order as defined in the Mapidefs.h header file.

JavaScript Copy code Copy code
static const MYOBJECT_Vtbl vtblSTATUS =
{
    STATUS_QueryInterface,
    STATUS_AddRef,
    STATUS_Release,
    STATUS_GetLastError,
    STATUS_SaveChanges,
    STATUS_GetProps,
    STATUS_GetPropList,
    STATUS_OpenProperty,
    STATUS_SetProps,
    STATUS_DeleteProps,
    STATUS_CopyTo,
    STATUS_CopyProps,
    STATUS_GetNamesFromIDs,
    STATUS_GetIDsFromNames,
    STATUS_ValidateState,
    STATUS_SettingsDialog,
    STATUS_ChangePassword,
    STATUS_FlushQueues
};

Clients and service providers written in C use objects indirectly through the vtable and add an object pointer as the first parameter in every call. Every call to a MAPI interface method requires a pointer to the object being called as its first parameter. C++ defines a special pointer known as the this pointer for this purpose. The C++ compiler implicitly adds the this pointer as the first parameter to every method call. In C there is no such pointer; it must be explicitly added.

The following code demonstrates how a client can make a call to an instance of MYSTATUSOBJECT:

Copy code Copy code
lpMyObj->lpVtbl->ValidateState(lpMyObj, ulUIParam, ulFlags);

See also

Concepts

Implementing MAPI Objects


Implementing the IUnknown Interface

 Copy code hover
[image]

Implementing the IUnknown Interface
See also Send feedback

Published: July 16, 2012

The methods of the IUnknown interface, implemented in every MAPI object, support interobject communication and object management.

IUnknown has three methods: IUnknown::AddRef, IUnknown::QueryInterface, and IUnknown::Release. QueryInterface enables one object to determine whether another object supports a particular interface. With QueryInterface, two objects with no prior knowledge of each other's functionality can interact. If the object that implements QueryInterface does support the interface in question, it returns a pointer to the implementation of the interface. If the object does not support the requested interface, it returns the MAPI_E_INTERFACE_NOT_SUPPORTED value.

When QueryInterface returns a requested interface pointer, it must also increase the new object's reference count. An object's reference count is a numeric value used to manage the object's lifespan. When the reference count is greater than 1, the object's memory cannot be freed because it is actively being used. It is only when the reference count drops to 0 that the object can be released safely.

The other two IUnknown methods, AddRef and Release, manage the reference count. AddRef increments the reference count, while Release decrements it. All methods or API functions that return interface pointers, such as QueryInterface, must call AddRef to increment the reference count. All implementations of methods that receive interface pointers must call Release to decrement the count when the pointer is no longer needed. Release checks for an existing reference count, freeing the memory associated with the interface only if the count is 0.

Note Note

Because AddRef and Release are not required to return accurate values, callers of these methods must not use the return values to determine whether an object is still valid or has been destroyed.

See also

Concepts

Implementing MAPI Objects


Implementing IUnknown in C++

 Copy code hover
[image]

Implementing IUnknown in C++
See also Send feedback

Published: July 16, 2012

Implementing the IUnknown::QueryInterface, IUnknown::AddRef, and IUnknown::Release methods of the IUnknown interface in C++ is fairly simple. After some standard validation of the parameters that are passed in, an implementation of QueryInterface checks the identifier of the requested interface against the list of supported interfaces. If the requested identifier is among those supported, AddRef is called and the this pointer is returned. If the requested identifier is not on the supported list, the output pointer is set to NULL and the MAPI_E_INTERFACE_NOT_SUPPORTED value is returned.

The following code example shows how you can implement QueryInterface in C++ for a status object, an object that is a subclass of the IMAPIStatus : IMAPIProp interface. IMAPIStatus inherits from IUnknown through IMAPIProp : IUnknown. Therefore, if a caller asks for any of these interfaces, the this pointer can be returned because the interfaces are related through inheritance.

C++ Copy code Copy code
HRESULT CMyMAPIObject::QueryInterface (REFIID   riid,
                                       LPVOID * ppvObj)
{
    // Always set out parameter to NULL, validating it first.
    if (!ppvObj)
        return E_INVALIDARG;
    *ppvObj = NULL;
    if (riid == IID_IUnknown || riid == IID_IMAPIProp ||
        riid == IID_IMAPIStatus)
    {
        // Increment the reference count and return the pointer.
        *ppvObj = (LPVOID)this;
        AddRef();
        return NOERROR;
    }
    return E_NOINTERFACE;
}

The following code example shows how to implement the AddRef and Release methods for the CMyMAPIObject object. Because implementing AddRef and Release is straightforward, many service providers choose to implement them inline. The calls to the Win32 functions InterlockedIncrement and InterlockedDecrement ensure thread safety. The memory for the object is freed by the destructor, which is called when the Release method deletes the object.

C++ Copy code Copy code
ULONG CMyMAPIObject::AddRef()
{
    InterlockedIncrement(m_cRef);
    return m_cRef;
}
ULONG CMyMAPIObject::Release()
{
    // Decrement the object's internal counter.
    ULONG ulRefCount = InterlockedDecrement(m_cRef);
    if (0 == m_cRef)
    {
        delete this;
    }
    return ulRefCount;
}

See also

Concepts

Implementing MAPI Objects
Implementing the IUnknown Interface


Implementing IUnknown in C

 Copy code hover
[image]

Implementing IUnknown in C
See also Send feedback

Published: July 16, 2012

Implementations of the IUnknown::QueryInterface method in C are very similar to C++ implementations. There are two basic steps to the implementation:

  1. Validating parameters.

  2. Checking the identifier of the requested interface against the list of interfaces supported by the object and returning either the E_NO_INTERFACE value or a valid interface pointer. If an interface pointer is returned, the implementation should also call the IUnknown::AddRef method to increment the reference count.

The main difference between an implementation of QueryInterface in C and C++ is the additional first parameter in the C version. Because the object pointer is added to the parameter list, a C implementation of QueryInterface must have more parameter validation than a C++ implementation. The logic for checking the interface identifier, incrementing the reference count, and returning an object pointer should be identical in both languages.

The following code example shows how to implement QueryInterface in C for a status object.

Copy code Copy code
STDMETHODIMP STATUS_QueryInterface(LPMYSTATUSOBJ lpMyObj, REFIID riid,
                                   LPVOID FAR * lppvObj)
{
    HRESULT hr = hrSuccess;
    // Validate the object pointer.
    if (!lpMyObj || lpMyObj->lpVtbl != &vtblSTATUS )
    {
        hr = ResultFromScode(E_INVALIDARG);
        return hr;
    }
    // Validate other parameters.
    if (!lppvObj)
    {
        hr = ResultFromScode(E_INVALIDARG);
        return hr;
    }
    // Set the output pointer to NULL.
    *lppvObj = NULL;
    // Check the interface identifier.
    if (memcmp(riid, &IID_IUnknown, sizeof(IID)) &&
        memcmp(riid, &IID_IMAPIProp, sizeof(IID)) &&
        memcmp(riid, &IID_IMAPIStatus, sizeof(IID)))
    {
        hr = ResultFromScode(E_NOINTERFACE);
        return hr;
    }
    // The interface is supported. Increment the reference count and return.
    lpMyObj->lpVtbl->AddRef(lpMyObj);
    *lppvObj = lpMyObj;
    return hr;
}

Whereas the implementation of the AddRef method in C is similar to a C++ implementation, a C implementation of the IUnknown::Release method can get more elaborate than a C++ version. This is because much of the functionality involved with freeing an object can be incorporated into the C++ constructor and destructor, and C has no such mechanism. All of this functionality must be included in the Release method. Also, because of the additional parameter and its explicit vtable, more validation is required.

The following AddRef method call illustrates a typical C implementation for a status object.

Copy code Copy code
STDMETHODIMP_(ULONG) STATUS_AddRef(LPMYSTATUSOBJ lpMyObj)
{
    LONG cRef;
    // Check to see whether it has a lpVtbl object member.
    if (!lpMyObj || lpMyObj->lpVtbl != &vtblSTATUS)
    {
        return 1;
    }
    // Check the method.
    if (STATUS_AddRef != lpMyObj->lpVtbl->AddRef)
    {
        return 1;
    }
    InterlockedIncrement(lpMyObj->cRef);
    cRef = ++lpMyObj->cRef;
    InterlockedDecrement (lpMyObj->cRef);
    return cRef;
}

The following code example shows a typical implementation of Release for a C status object. If the reference count is 0 after it is decremented, a C status object implementation should perform the following tasks:

  • Release any held pointers to objects.

  • Set the vtable to NULL, facilitating debugging in the case where an object's user called Release yet continued to try to use the object.

  • Call MAPIFreeBuffer to free the object.

Copy code Copy code
STDMETHODIMP_(ULONG) STATUS_Release(LPMYSTATUSOBJ lpMyObj)
{
    LONG cRef;
    // Check the size of the vtable.
    if (!lpMyObj)
    {
        return 1;
    }
    // Check whether the vtable is correct.
    if (lpMyObj->lpVtbl != &vtblSTATUS)
    {
        return 1;
    }
    InterlockedIncrement(lpMyObj->cRef);
    cRef = --lpMyObj->cRef;
    InterlockedIncrement (lpMyObj->cRef);
    if (cRef == 0)
    {
        lpMyObj->lpVtbl->Release(lpMyObj);
        DeleteCriticalSection(&lpMyObj->cs);
        // Release the IMAPIProp pointer.
        lpMyObj->lpProp->Release(lpMyObj->lpProp);
        lpMyObj->lpVtbl = NULL;
        lpMyObj->lpFreeBuff(lpMyObj);
        return 0;
    }
    return cRef;
}

See also

Concepts

Implementing MAPI Objects
Implementing the IUnknown Interface


Implementing a Sample Object

 Copy code hover
[image]

Implementing a Sample Object
See also Send feedback

Published: July 16, 2012

Advise sink objects — objects that support the IMAPIAdviseSink : IUnknown interface — are MAPI objects that client applications implement for processing notifications. IMAPIAdviseSink inherits directly from IUnknown and contains only one method, OnNotify. Therefore, to implement an advise sink object, a client creates code for the three methods in IUnknown and for OnNotify.

The Mapidefs.h header file defines an IMAPIAdviseSink interface implementation by using DECLARE_MAPI_INTERFACE, as follows:

C++ Copy code Copy code
#define      INTERFACE  IMAPIAdviseSink
DECLARE_MAPI_INTERFACE_(IMAPIAdviseSink, IUnknown)
{
    BEGIN_INTERFACE
    MAPI_IUNKNOWN_METHODS(PURE)
    MAPI_IMAPIADVISESINK_METHODS(PURE)
};

Clients that implement advise sink objects can define their interfaces in their objects manually or with the MAPI_IUNKNOWN_METHODS and MAPI_IMAPIADVISESINK_METHODS macros. Object implementers should use the interface macros whenever possible to ensure consistency across objects and to save time and effort.

Implementing the IUnknown::AddRef and IUnknown::Release methods is relatively simple because typically only a few lines of code are needed. Therefore, clients and service providers that implement objects can make their AddRef and Release implementations inline. The following code shows how to define a C++ advise sink object with inline implementations of AddRef and Release.

C++ Copy code Copy code
class  CMAPIAdviseSink : public IMAPIAdviseSink
{
public:
    STDMETHODIMP QueryInterface
                    (REFIID                     riid,
                     LPVOID *                   ppvObj);
    inline STDMETHODIMP_(ULONG) AddRef
                    () { InterlockedIncrement(m_cRef);
                         ++m_cRef;
                         InterlockedDecrement(m_cRef);
                         return m_cRef; };
    inline STDMETHODIMP_(ULONG) Release
                    () { InterlockedIncrement(m_cRef);
                         ULONG ulCount = --m_cRef;
                         InterlockedDecrement(m_cRef);
                         if (!ulCount)  delete this;
                         return ulCount;};
    MAPI_IMAPIADVISESINK_METHODS(IMPL);
    BOOL WINAPI AddConnection (LPMDB pMDBObj, ULONG ulConnection);
    void WINAPI RemoveAllLinks (LPMDB pMDBObj);
// Constructors and destructors.
public :
    inline CMAPIAdviseSink  (CStoreClient * pStore)
                            { m_cRef = 1;
                              m_ulConnection = 0;
                              m_pStore = pStore;
                              AddRef;};
    ~CMAPIAdviseSink () {Release};
private :
    ULONG               m_cRef;
    CStoreClient *      m_pStore;
    ULONG               m_ulConnection;
};

In C, the advise sink object is composed of the following elements:

  • A pointer to a vtable that contains pointers to implementations of each of the methods in IUnknown and IMAPIAdviseSink.

  • Data members.

The following code example shows how to define an advise sink object in C and construct its vtable.

Copy code Copy code
// Object definition.
typedef struct _ADVISESINK
{
    const ADVISE_Vtbl FAR *    lpVtbl;
    ULONG             cRef;
    STORECLIENT      *pStore;
    ULONG             ulConnection;
} ADVISESINK, *LPADVISESINK;
// vtable definition.
static const ADVISE_Vtbl vtblADVISE =
{
    ADVISE_QueryInterface,
    ADVISE_AddRef,
    ADVISE_Release,
    ADVISE_OnNotify
};

After you declare an object in C, you must initialize it by setting the vtable pointer to the address of the constructed vtable, as shown in the following code:

Copy code Copy code
LPADVISESINK lpMyObj = NULL;
HRESULT hr = (*lpAllocateBuffer) (sizeof(ADVISESINK),
                 (LPVOID *)&lpMyObj);
lpMyObj->lpVtbl = &vtblADVISE;

See also

Concepts

MAPI Property Overview
Implementing MAPI Objects


MAPI Property Overview

 Copy code hover
[image]

MAPI Property Overview
See also Send feedback

Published: July 16, 2012

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 a table or a property sheet. Tables provide users with a read-only view of some of the properties belonging to multiple objects. The data is displayed in row and column format, with each row representing an object and each column a property. Property sheets are tabbed dialog boxes that display related properties for a single object. Property sheets can provide read-only or read/write access to the data. Whether or not a user is allowed to make changes is up to the implementer of the property sheet.

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:

  • Data, or value, of the property.

  • Data type of the property's value, such as integer or Boolean.

  • Numeric value within a particular range that uniquely identify the property and component responsible for maintaining it. For example, there is a range to hold message content properties defined by MAPI and another range to hold message content properties defined by a client for a custom message class.

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.

See also

Other resources

MAPI Concepts


MAPI Property Tags

 Copy code hover
[image]

MAPI Property Tags
See also Send feedback

Published: July 16, 2012

A property tag is a 32-bit number that contains a unique property identifier in bits 16 through 31 and a property type in bits 0 through 15 as shown in the following illustration.

Property tag elements

Property tag elements

Property tags are used to identify MAPI properties and every property must have one, regardless of whether the property is defined by MAPI, a client, or a service provider. MAPI defines a set of property tag constants for its properties in the Mapitags.h header file; these properties are referred to as the "MAPI-defined properties".

The property tag constants follow a naming convention for consistency and ease of use. There are two parts to the name of each property tag: a PR_ prefix and one or more character strings that describe the contents of the property. Multiple character strings are separated by underscores. For example, the property tag for the address type of a message recipient is PR_ADDRTYPE (PidTagOrgAddrtype) and the entry identifier for the folder designated to receive a copy of every outbound message is PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId).

A few macros are available to help work with property tags, among them PROP_TYPE, PROP_ID, and PROP_TAG. PROP_TYPE extracts the property type from the property tag; PROP_ID extracts the identifier. PROP_TAG builds a property tag from a property type and identifier.

See also

Concepts

MAPI Property Overview


MAPI Property Identifier Overview

 Copy code hover
[image]

MAPI Property Identifier Overview
See also Send feedback

Published: July 16, 2012

A property identifier is a number that is used to indicate what a property is used for and who is responsible for it. Property identifiers are divided by MAPI into ranges; where an identifier falls in the range indicates its use and ownership.

The range of property identifiers runs from 0x0001 through 0xFFFF. Property identifiers 0x0000 and 0xFFFF are reserved in all cases, meaning that these identifiers must remain unused. The range for properties defined by MAPI runs from 0x0001 to 0x3FFF. These properties are referred to as MAPI-defined properties. The range 0x4000 to 0x7FFF belongs to message and recipient properties, and either clients or service providers can define properties in this range. Properties in the range of 0x0001 to 0x7FFF are referred to as tagged properties. Beyond 0x8000 is the range for what is known as named properties, or properties that include a 32-bit globally unique identifier (GUID) and either a Unicode character string or numeric value. Clients can use named properties to customize their property set.

Service providers can define secure profile properties in the range 0x67F0 through 0x67FF. Secure profile properties are used for information that requires additional protection, such as passwords. These properties can be hidden and encrypted. Whether or not secure properties are included in the default list of properties returned by the IMAPIProp::GetPropList method depends on the provider's implementation. Usually these properties are not included. The IProfSect : IMAPIProp interface is used for accessing the properties of a profile section, including secure properties.

Some of the property ranges are restricted to transmittable properties or nontransmittable properties. Transmittable properties are transferred with a message; nontransmittable properties are not transferred with a message. Nontransmittable properties usually contain information that is of value only to clients and service providers operating with the current session. These properties would not necessarily be useful to another messaging system and another set of service providers. The concept of transmittable properties applies primarily to transport providers. To determine whether a property is transmittable or not, pass its property tag to the FIsTransmittable macro, defined in the Mapitags.h header file.

For a complete description of the identifier ranges, see Property Identifier Ranges.

See also

Concepts

MAPI Property Overview


MAPI Property Type Overview

 Copy code hover
[image]

MAPI Property Type Overview
See also Send feedback

Published: July 16, 2012

Property types are constants defined by MAPI in the MAPIDEFS.H header file 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.

Property types follow a similar naming convention to the one used for property tags. Many property types have both a single-value and multiple-value version. Single valued properties contain one value of its type such as a single integer or character string. The constant used to represent a single value property has two parts: the prefix PT_ and a string describing the actual type, such as LONG or STRING8.

Multiple-value properties contain more than one value of its type. Unlike OLE variant arrays, every value in a multivalued property is of the same type. The constant used to represent multivalued properties is created by combining the MV_FLAG flag with the corresponding single value constant representing the base type. There are three parts: the prefix PT_ followed by MV_ followed by a string that describes the type. For example, the type for a property containing multiple integers is PT_MV_LONG and for multiple character strings is PT_MV_STRING8.

The following illustration shows the structure of an SPropValue structure to describe a multiple-value integer, a property of type PT_MV_LONG. The Value member is expanded to include a count of the number of integer values in the property and a pointer to an array of those values.

Multiple-value properties

Although support for multiple-value properties is optional, MAPI recommends that clients and service providers support both types of properties because doing so enables greater interaction between MAPI-compliant components.

The following illustration lists all of the different property type constants, showing where they are stored in an SPropValue structure. The size of the Value member is dependent on the particular type. Notice that not all of the single-value types have multiple-value equivalents.

Property type constants

Property type constants

Clients and service providers working with a property need to follow two steps:

  1. Determine if the property is available or unavailable.

  2. If available, retrieve the property's value.

Sometimes a client or service provider need only check for the existence of a property; other times it is necessary to check for a specific value. For example, transport providers have three different courses of action for processing the PR_SEND_RICH_INFO (PidTagSendRichInfo) property, a Boolean value that indicates whether or not a message should be transmitted with formatted text. If PR_SEND_RICH_INFO is set to TRUE, the transport provider transmits the formatted text. If it is set to FALSE, the formatted text is discarded before transmission. If PR_SEND_RICH_INFO is unavailable, the transport provider follows its default course of action, whatever that is for the particular provider.

MAPI defines a special property type, PT_UNSPECIFIED, that a client or service provider can use to retrieve a property when the property type is unknown.To retrieve a property without advance knowledge of its type, a client or service provider calls an object's IMAPIProp::GetProps method and passes a property tag made up of the property's identifier and the PT_UNSPECIFIED property type. GetProps returns an SPropValue structure for the property, replacing PT_UNSPECIFIED with the appropriate type. Service providers implementing GetProps are required to support PT_UNSPECIFIED.

Some MAPI objects support properties that are themselves objects. Object properties have the type PT_OBJECT. Instead of using IMAPIProp::GetProps to access these properties, clients and service providers typically user either the IMAPIProp::OpenProperty method, specifying the appropriate interface for access, or a method on the object supporting the property.

Because accessing the value of an object property involves using one of the interfaces for the object, GetProps is inappropriate. With GetProps, the caller accesses a property's value through an SPropValue structure. With IMAPIProp::OpenProperty, the caller retrieves a pointer to an interface that can access the object. OpenProperty can always be used to retrieve an object property. The other option, calling a method on the object, is not available with every object property.

For example, every folder supports two tables, a hierarchy table and a contents table. These tables are properties of the folder; their property tags are PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) and PR_CONTAINER_CONTENTS (PidTagContainerContents). Tables are objects that require the IMAPITable interface for access. A client can call the folder's IMAPIContainer::GetHierarchyTable method to access the hierarchy table, the folder's IMAPIContainer::GetContentsTable method to access the contents table, or the folder's IMAPIProp::OpenProperty method to access either table. To call OpenProperty, a client passes the property tag for the property as the first parameter and an interface identifier for the interface to be used for access as the second parameter. These parameters would be PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS and IID_IMAPITable.

For a complete list of the single-value and multiple-value property types, see Property Types.

See also

Concepts

MAPI Property Overview


MAPI String Properties

 Copy code hover
[image]

MAPI String Properties
See also Send feedback

Published: July 16, 2012

MAPI provides three different property types to describe string properties:

PT_TSTRING

PT_STRING8

PT_UNICODE

String properties are most commonly defined as PT_TSTRING. The PT_TSTRING property type conditionally compiles to one of the other string property types, depending depending on whether the UNICODE macro has been defined. PT_STRING8 describes 8-bit null-terminated character strings in the ANSI format; PT_UNICODE describes double-byte null-terminated character strings.

Either a client or a service provider, or both client and provider can choose to support Unicode character strings. It is not required. A client that supports only PT_STRING8 strings can operate with a provider that supports Unicode and vice versa. To enable this interoperability, clients and service providers pass a flag, the MAPI_UNICODE flag, to indicate that Unicode is supported in methods that involve the exchange of character strings.

For example, suppose a client supports Unicode and needs to retrieve the display name of a folder. All of the client's PT_TSTRING properties are compiled to type PT_UNICODE. When the client calls the folder's IMAPIProp::GetProps method to retrieve its PR_DISPLAY_NAME (PidTagDisplayName) property, it passes the MAPI_UNICODE flag to request that the display name string be returned in the Unicode format.

Clients and service providers need to be aware that specifying a character set in a method call is only a request. Supporting one or both character sets is up to the implementer of the object. However, service providers are encouraged to support both character sets because it allows them to achieve more widespread distribution than providers that support only one set.

String properties can grow to be quite large as can binary properties — properties that use the property type PT_BINARY. To ease working with large properties, MAPI allows service providers setting these properties to enforce size limits. These limits can vary, depending on:

  • Whether the properties are being read or written.

  • How the service provider implements the IMAPIProp methods.

  • Runtime considerations, such as memory constraints.

  • Character set translation issues.

Size limits can also be placed on string and binary properties when they are used in the column set of a table because it is sometimes impossible to make all of a large property's value visible. Many service providers truncate large string or binary properties that are used in tables to 255 bytes.

When a client calls an object's GetProps or SetProps method to work with a large string or binary property and the call fails because of the property size, the method returns the error value MAPI_E_NOT_ENOUGH_MEMORY. If it is GetProps that is failing for a specific property, the client can recover by calling IMAPIProp::OpenProperty and requesting the IStream for access by specifying IID_IStream as the interface identifier. Using OpenProperty, the client can retrieve a large property using an interface such as IStream that is better suited for working with large properties.

See also

Concepts

MAPI Property Overview


MAPI Canonical Properties

 Copy code hover
[image]

MAPI Canonical Properties
See also Send feedback

Published: July 16, 2012

A canonical property is a virtual property that represents a MAPI property, or multiple MAPI properties defined with the same property identifier. Canonical properties are only intended to facilitate consistent identification of MAPI properties in discussions or documentation outside of code. Unlike MAPI-defined tagged property names, canonical property names are not defined as global constants in MAPI header files.

Naming Conventions

Canonical property names begin with a prefix, "Pid", which represents "property identifier." Depending on whether the property is a tagged property, a named property with a numerical identifier, or a named property with a string name, the prefix is further qualified as "PidTag," "PidLid," and "PidName" respectively. For example, PidTagAccount represents the tagged properties, PR_ACCOUNT (PidTagAccount), PR_ACCOUNT_A (PidTagAccount), and PR_ACCOUNT_W (PidTagAccount), that specify a recipient's account name; PidLidContacts represents the dispidContacts property, a named property that has a numerical identifier and that specifies the name of contacts associated with a message; and PidNamePhishingStamp represents "http://schemas.microsoft.com/outlook/phishingstamp," a named property that has a string name, and that specifies the string marking messages that are likely to be phishing.

Representing Similar Properties Using One Canonical Property

Identifying Properties in MAPI

All properties in MAPI are identified by a property identifier that is an unsigned 16-bit value. The property identifier and the property type (another unsigned 16-bit value) constitute a property tag for the property.

MAPI uses a property tag to uniquely define properties. Properties that have the same property tag, like PR_BUSINESS2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber) and PR_OFFICE2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber), are considered identical properties in MAPI. For a list of property tags that MAPI has defined for its own properties, see the MAPI header file, Mapitags.h.

Note that MAPI divides property identifiers into ranges. Where an identifier falls in the range indicates its use and ownership. The property identifiers of tagged properties fall in the range of 0x0001 to 0x7FFF. Within this range are the property identifiers of MAPI-defined properties, which fall in the range of 0x0001 to 0x3FFF. The property identifiers of named properties fall in the range from 0x8000 to 0x8FFF.

Named properties are additionally attributed by a property set, and either a long ID (LID), which is an unsigned 32-bit value, or a string. A property set is a GUID that identifies a group of named properties with a similar purpose. The property set and LID or string name are used to get or set the named property.

Property Type

Aside from identifiers, a property is attributed by a data type that specifies the type of values allowed for that property.

For properties that are of the string type, depending on the support for Unicode in the underlying platform, the property can be of type PT_STRING8 (null-terminated 8-bit character string) or PT_UNICODE (null-terminated Unicode string). A property can be defined with the PT_TSTRING type, and depending on compilation settings, PT_TSTRING defaults to a Unicode string for platforms that support Unicode, or to a PT_STRING8 string for platforms that support ANSI or DBCS. It is common that a string-typed property is identified by three similar names, such as PR_ACCOUNT, PR_ACCOUNT_A, and PR_ACCOUNT_W, which are of the type PT_TSTRING, PT_STRING8, and PT_UNICODE respectively.

For more information on property types and macros related to types, see the MAPI header file, Mapidefs.h.

Identifying Similar Properties

In the current MAPI property landscape, it is not uncommon to find that a property has been exposed under different property names, all of which are defined with the same property identifier. For example, the tagged properties, PR_BUSINESS2_TELEPHONE_NUMBER and PR_OFFICE2_TELEPHONE_NUMBER, are defined in Mapitags.h to have the same property identifier and type. Closely related to these two properties are:

  • PR_BUSINESS2_TELEPHONE_NUMBER_A

  • PR_BUSINESS2_TELEPHONE_NUMBER_W

  • PR_OFFICE2_TELEPHONE_NUMBER_A

  • PR_OFFICE2_TELEPHONE_NUMBER_W

The properties with the "_A" suffix are typed as PT_STRING8, and those with the "_W" suffix are typed as PT_UNICODE.

The purpose of a canonical property, PidTagBusiness2TelephoneNumber in this example, is to facilitate referencing such closely affiliated MAPI properties using one identifier, and in a consistent way (using the "Pid" prefix) across all MAPI properties. To find which real MAPI properties a canonical property represents, see Mapping Canonical Property Names to MAPI Names. To find the canonical property that a MAPI property is associated with, see Mapping MAPI Names to Canonical Property Names.

MAPI Support of Canonical Property Names

Because canonical properties are not real properties and are not defined in MAPI header files, you should not use canonical property names in code; instead, you should continue to use the exact MAPI property names in code. For example, you can refer PR_BUSINESS2_TELEPHONE_NUMBER and PR_OFFICE2_TELEPHONE_NUMBER outside of code as PidTagBusiness2TelephoneNumber, and use either PR_BUSINESS2_TELEPHONE_NUMBER or PR_OFFICE2_TELEPHONE_NUMBER in code.

If you must use canonical property names in your code, you must first define them in your own header files.

Canonical Property Names and Exchange Protocol Specifications

Canonical names are referenced in Microsoft Exchange Server protocol specifications that are used by Exchange Server to communicate with other Microsoft products. For more information about message object properties referenced by Exchange protocol specifications, see [MS-OXPROPS].

See also

Concepts

MAPI Property Tags
MAPI Property Identifier Overview
MAPI Property Type Overview


Mapping Canonical Property Names to MAPI Names

 Copy code hover
[image]

Mapping Canonical Property Names to MAPI Names
Send feedback

Published: July 16, 2012

This topic maps each canonical property name to the MAPI property or properties it represents. The topic contains three tables: a table for named properties with numerical identifiers, a second table for named properties with string identifiers, and a third table for tagged properties.

For more information about how canonical properties relate to MAPI properties, see MAPI Canonical Properties.

Named Properties with Numerical Identifiers

Canonical Property Name | Actual Named Property
PidLidAddressBookProviderArrayType | dispidABPArrayType
PidLidAddressBookProviderEmailList | dispidABPEmailList
PidLidAddressCountryCode | dispidAddressCountryCode
PidLidAgingDontAgeMe | dispidAgingDontAgeMe
PidLidAllAttendeesString | dispidAllAttendeesString
PidLidAnniversaryEventEntryId | dispidAnniversaryEventEID
PidLidAppointmentAuxiliaryFlags | dispidApptAuxFlags
PidLidAppointmentColor | dispidApptColor
PidLidAppointmentCounterProposal | dispidApptCounterProposal
PidLidAppointmentDuration | dispidApptDuration
PidLidAppointmentEndWhole | dispidApptEndWhole
PidLidAppointmentLastSequence | dispidApptLastSequence
PidLidAppointmentMessageClass | dispidApptMessageClass
PidLidAppointmentNotAllowPropose | dispidApptNotAllowPropose
PidLidAppointmentProposalNumber | dispidApptProposalNum
PidLidAppointmentProposedDuration | dispidApptProposedDuration
PidLidAppointmentProposedEndWhole | dispidApptProposedEndWhole
PidLidAppointmentProposedStartWhole | dispidApptProposedStartWhole
PidLidAppointmentRecur | dispidApptRecur
PidLidAppointmentReplyName | dispidApptReplyName
PidLidAppointmentReplyTime | dispidApptReplyTime
PidLidAppointmentSequence | dispidApptSequence
PidLidAppointmentSequenceTime | dispidApptSeqTime
PidLidAppointmentStartWhole | dispidApptStartWhole
PidLidAppointmentStateFlags | dispidApptStateFlags
PidLidAppointmentSubType | dispidApptSubType
PidLidAppointmentTimeZoneDefinitionEndDisplay | dispidApptTZDefEndDisplay
PidLidAppointmentTimeZoneDefinitionRecur | dispidApptTZDefRecur
PidLidAppointmentTimeZoneDefinitionStartDisplay | dispidApptTZDefStartDisplay
PidLidAppointmentUnsendableRecipients | dispidApptUnsendableRecips
PidLidAttendeeCriticalChange | LID_ATTENDEE_CRITICAL_CHANGE
PidLidAutoFillLocation | dispidAutoFillLocation
PidLidAutoLog | dispidAutoLog
PidLidAutoProcessState | dispidSniffState
PidLidBilling | dispidBilling
PidLidBirthdayEventEntryId | dispidBirthdayEventEID
PidLidBusinessCardCardPicture | dispidBCCardPicture
PidLidBusinessCardDisplayDefinition | dispidBCDisplayDefinition
PidLidBusyStatus | dispidBusyStatus
PidLidCalendarType | LID_CALENDAR_TYPE
PidLidCategories | dispidCategories
PidLidCcAttendeesString | dispidCCAttendeesString
PidLidChangeHighlight | dispidChangeHighlight
PidLidClassification | dispidClassification
PidLidClassificationDescription | dispidClassDesc
PidLidClassificationGuid | dispidClassGuid
PidLidClassificationKeep | dispidClassKeep
PidLidClassified | dispidClassified
PidLidCleanGlobalObjectId | dispidCleanGlobalObjId
PidLidClipEnd | dispidClipEnd
PidLidClipStart | dispidClipStart
PidLidCommonEnd | dispidCommonEnd
PidLidCommonStart | dispidCommonStart
PidLidCompanies | dispidCompanies
PidLidContactCharacterSet | dispidContactCharSet
PidLidContactItemData | dispidContactItemData
PidLidContactLinkEntry | dispidContactLinkEntry
PidLidContactLinkName | dispidContactLinkName
PidLidContactLinkSearchKey | dispidContactLinkSearchKey
PidLidContacts | dispidContacts
PidLidContactUserField1 | dispidContactUserField1
PidLidContactUserField2 | dispidContactUserField2
PidLidContactUserField3 | dispidContactUserField3
PidLidContactUserField4 | dispidContactUserField4
PidLidCurrentVersion | dispidCurrentVersion
PidLidCurrentVersionName | dispidCurrentVersionName
PidLidCustomFlag | dispidCustomFlag
PidLidDistributionListChecksum | dispidDLChecksum
PidLidDistributionListMembers | dispidDLMembers
PidLidDistributionListName | dispidDLName
PidLidDistributionListOneOffMembers | dispidDLOneOffMembers
PidLidEmail1AddressType | dispidEmail1AddrType
PidLidEmail1DisplayName | dispidEmail1DisplayName
PidLidEmail1EmailAddress | dispidEmail1EmailAddress
PidLidEmail1OriginalDisplayName | dispidEmail1OriginalDisplayName
PidLidEmail1OriginalEntryId | dispidEmail1OriginalEntryID
PidLidEmail2AddressType | dispidEmail2AddrType
PidLidEmail2DisplayName | dispidEmail2DisplayName
PidLidEmail2EmailAddress | dispidEmail2EmailAddress
PidLidEmail2OriginalDisplayName | dispidEmail2OriginalDisplayName
PidLidEmail2OriginalEntryId | dispidEmail2OriginalEntryID
PidLidEmail3AddressType | dispidEmail3AddrType
PidLidEmail3DisplayName | dispidEmail3DisplayName
PidLidEmail3EmailAddress | dispidEmail3EmailAddress
PidLidEmail3OriginalDisplayName | dispidEmail3OriginalDisplayName
PidLidEmail3OriginalEntryId | dispidEmail3OriginalEntryID
PidLidExceptionReplaceTime | dispidExceptionReplaceTime
PidLidFax1AddressType | dispidFax1AddrType
PidLidFax1DisplayName | dispidFax1DisplayName
PidLidFax1EmailAddress | dispidFax1EmailAddress
PidLidFax1EmailType | dispidFax1EmailType
PidLidFax1EntryId | dispidFax1EntryID
PidLidFax1OriginalDisplayName | dispidFax1OriginalDisplayName
PidLidFax1OriginalEntryId | dispidFax1OriginalEntryID
PidLidFax1RichTextFormat | dispidFax1RTF
PidLidFax2AddressType | dispidFax2AddrType
PidLidFax2DisplayName | dispidFax2DisplayName
PidLidFax2EmailAddress | dispidFax2EmailAddress
PidLidFax2EmailType | dispidFax2EmailType
PidLidFax2EntryId | dispidFax2EntryID
PidLidFax2OriginalDisplayName | dispidFax2OriginalDisplayName
PidLidFax2OriginalEntryId | dispidFax2OriginalEntryID
PidLidFax2RichTextFormat | dispidFax2RTF
PidLidFax3AddressType | dispidFax3AddrType
PidLidFax3DisplayName | dispidFax3DisplayName
PidLidFax3EmailAddress | dispidFax3EmailAddress
PidLidFax3EmailType | dispidFax3EmailType
PidLidFax3EntryId | dispidFax3EntryID
PidLidFax3OriginalDisplayName | dispidFax3OriginalDisplayName
PidLidFax3OriginalEntryId | dispidFax3OriginalEntryID
PidLidFax3RichTextFormat | dispidFax3RTF
PidLidFExceptionalAttendees | dispidFExceptionalAttendees
PidLidFExceptionalBody | dispidFExceptionalBody
PidLidFileUnder | dispidFileUnder
PidLidFileUnderId | dispidFileUnderId
PidLidFileUnderList | dispidFileUnderList
PidLidFInvited | dispidFInvited
PidLidFlagRequest | dispidRequest
PidLidFlagString | dispidFlagStringEnum
PidLidForwardInstance | dispidFwrdInstance
PidLidFShouldTNEF | dispidFShouldTNEF
PidLidFreeBusyLocation | dispidFreeBusyLocation
PidLidGlobalObjectId | LID_GLOBAL_OBJID
PidLidHasPicture | dispidHasPicture
PidLidHeaderItem | dispidHeaderItem
PidLidHomeAddress | dispidHomeAddress
PidLidHomeAddressCountryCode | dispidHomeAddressCountryCode
PidLidHtml | dispidHTML
PidLidImageAttachmentsCompressionLevel | dispidImgAttchmtsCompressLevel
PidLidImapDeleted | dispidImapDeleted
PidLidInstantMessagingAddress | dispidInstMsg
PidLidIntendedBusyStatus | dispidIntendedBusyStatus
PidLidInternetAccountName | dispidInetAcctName
PidLidInternetAccountStamp | dispidInetAcctStamp
PidLidIsException | LID_IS_EXCEPTION
PidLidIsInterpersonalFax | dispidIsIPFax
PidLidIsRecurring | LID_IS_RECURRING
PidLidIsSilent | LID_IS_SILENT
PidLidLinkedTaskItems | dispidLinkedTaskItems
PidLidLocation | dispidLocation
PidLidLogDocumentPosted | dispidLogDocPosted
PidLidLogDocumentPrinted | dispidLogDocPrinted
PidLidLogDocumentRouted | dispidLogDocRouted
PidLidLogDocumentSaved | dispidLogDocSaved
PidLidLogDuration | dispidLogDuration
PidLidLogEnd | dispidLogEnd
PidLidLogFlags | dispidLogFlags
PidLidLogStart | dispidLogStart
PidLidLogType | dispidLogType
PidLidLogTypeDesc | dispidLogTypeDesc
PidLidMeetingType | dispidMeetingType
PidLidMeetingWorkspaceUrl | dispidMWSURL
PidLidMileage | dispidMileage
PidLidNonSendableBcc | dispidNonSendableBCC
PidLidNonSendableCc | dispidNonSendableCC
PidLidNonSendableTo | dispidNonSendableTo
PidLidNonSendBccTrackStatus | dispidNonSendBccTrackStatus
PidLidNonSendCcTrackStatus | dispidNonSendCcTrackStatus
PidLidNonSendToTrackStatus | dispidNonSendToTrackStatus
PidLidNoteColor | dispidNoteColor
PidLidNoteHeight | dispidNoteHeight
PidLidNoteWidth | dispidNoteWidth
PidLidNoteX | dispidNoteX
PidLidNoteY | dispidNoteY
PidLidOfflineStatus | dispidOfflineStatus
PidLidOldLocation | dispidOldLocation
PidLidOldWhenEndWhole | dispidOldWhenEndWhole
PidLidOldWhenStartWhole | dispidOldWhenStartWhole
PidLidOriginalStoreEntryId | dispidOrigStoreEid
PidLidOtherAddress | dispidOtherAddress
PidLidOtherAddressCountryCode | dispidOtherAddressCountryCode
PidLidOwnerCriticalChange | LID_OWNER_CRITICAL_CHANGE
PidLidPercentComplete | dispidPercentComplete
PidLidPostalAddressId | dispidPostalAddressId
PidLidPostRssChannel | dispidPostRssChannel
PidLidPostRssChannelLink | dispidPostRssChannelLink
PidLidPrivate | dispidPrivate
PidLidPropertyDefinitionStream | dispidPropDefStream
PidLidRecallTime | dispidRecallTime
PidLidRecurrencePattern | dispidRecurPattern
PidLidRecurrenceType | dispidRecurType
PidLidRecurring | dispidRecurring
PidLidReferenceEntryId | dispidReferenceEID
PidLidReminderDelta | dispidReminderDelta
PidLidReminderFileParameter | dispidReminderFileParam
PidLidReminderOverride | dispidReminderOverride
PidLidReminderPlaySound | dispidReminderPlaySound
PidLidReminderSet | dispidReminderSet
PidLidReminderSignalTime | dispidReminderNextTime
PidLidReminderTime | dispidReminderTime
PidLidRemoteAttachment | dispidRemoteAttachment
PidLidRemoteEntryId | dispidRemoteEID
PidLidRemoteMessageClass | dispidRemoteMsgClass
PidLidRemoteSearchKey | dispidRemoteSearchKey
PidLidRemoteTransferSize | dispidRemoteXferSize
PidLidRemoteTransferTime | dispidRemoteXferTime
PidLidRemoteTransport | dispidRemoteXP
PidLidResendTime | dispidResendTime
PidLidResponseStatus | dispidResponseStatus
PidLidSendMeetingAsIcal | dispidSendMtgAsICAL
PidLidSharingCapabilities | dispidSharingCaps
PidLidSharingConfigurationUrl | dispidSharingConfigUrl
PidLidSharingFlavor | dispidSharingFlavor
PidLidSharingInitiatorEntryId | dispidSharingInitiatorEid
PidLidSharingInitiatorName | dispidSharingInitiatorName
PidLidSharingInitiatorSmtp | dispidSharingInitiatorSmtp
PidLidSharingLocalType | dispidSharingLocalType
PidLidSharingProviderGuid | dispidSharingProviderGuid
PidLidSharingProviderName | dispidSharingProviderName
PidLidSharingProviderUrl | dispidSharingProviderUrl
PidLidSharingRemoteName | dispidSharingRemoteName
PidLidSharingRemoteStoreUid | dispidSharingRemoteStoreUid
PidLidSharingRemoteType | dispidSharingRemoteType
PidLidSharingRemoteUid | dispidSharingRemoteUid
PidLidSharingResponseTime | dispidSharingResponseTime
PidLidSharingResponseType | dispidSharingResponseType
PidLidSideEffects | dispidSideEffects
PidLidSmartNoAttach | dispidSmartNoAttach
PidLidSpamOriginalFolder | dispidSpamOriginalFolder
PidLidTaskAcceptanceState | dispidTaskDelegValue
PidLidTaskAccepted | dispidTaskAccepted
PidLidTaskActualEffort | dispidTaskActualEffort
PidLidTaskAssigner | dispidTaskDelegator
PidLidTaskAssigners | dispidTaskMyDelegators
PidLidTaskComplete | dispidTaskComplete
PidLidTaskDateCompleted | dispidTaskDateCompleted
PidLidTaskDeadOccurrence | dispidTaskDeadOccur
PidLidTaskDueDate | dispidTaskDueDate
PidLidTaskEstimatedEffort | dispidTaskEstimatedEffort
PidLidTaskFCreator | dispidTaskFCreator
PidLidTaskFFixOffline | dispidTaskFFixOffline
PidLidTaskFRecurring | dispidTaskFRecur
PidLidTaskGlobalId | dispidTaskGlobalObjId
PidLidTaskHistory | dispidTaskHistory
PidLidTaskLastDelegate | dispidTaskLastDelegate
PidLidTaskLastUpdate | dispidTaskLastUpdate
PidLidTaskLastUser | dispidTaskLastUser
PidLidTaskMode | dispidTaskMode
PidLidTaskMultipleRecipients | dispidTaskMultRecips
PidLidTaskOrdinal | dispidTaskOrdinal
PidLidTaskOwner | dispidTaskOwner
PidLidTaskOwnership | dispidTaskOwnership
PidLidTaskRecurrence | dispidTaskRecur
PidLidTaskResetReminder | dispidTaskResetReminder
PidLidTaskStartDate | dispidTaskStartDate
PidLidTaskState | dispidTaskState
PidLidTaskStatus | dispidTaskStatus
PidLidTaskStatusOnComplete | dispidTaskSOC
PidLidTaskUpdates | dispidTaskUpdates
PidLidTaskVersion | dispidTaskVersion
PidLidTimeZone | LID_TIME_ZONE
PidLidTimeZoneDescription | dispidTimeZoneDesc
PidLidTimeZoneStruct | dispidTimeZoneStruct
PidLidToAttendeesString | dispidToAttendeesString
PidLidToDoOrdinalDate | dispidToDoOrdinalDate
PidLidToDoSubOrdinal | dispidToDoSubOrdinal
PidLidToDoTitle | dispidToDoTitle
PidLidUserX509Certificate | dispidEMSAbX509Cert
PidLidUseTnef | dispidUseTNEF
PidLidValidFlagStringProof | dispidValidFlagStringProof
PidLidVerbResponse | dispidVerbResponse
PidLidVerbStream | dispidVerbStream
PidLidWhere | LID_WHERE
PidLidWorkAddress | dispidWorkAddress
PidLidWorkAddressCity | dispidWorkAddressCity
PidLidWorkAddressCountry | dispidWorkAddressCountry
PidLidWorkAddressCountryCode | dispidWorkAddressCountryCode
PidLidWorkAddressPostalCode | dispidWorkAddressPostalCode
PidLidWorkAddressPostOfficeBox | dispidWorkAddressPostOfficeBox
PidLidWorkAddressState | dispidWorkAddressState
PidLidWorkAddressStreet | dispidWorkAddressStreet
PidLidYomiCompanyName | dispidYomiCompanyName
PidLidYomiFirstName | dispidYomiFirstName
PidLidYomiLastName | dispidYomiLastName

Named Properties with String Identifiers

Canonical Property Name | Actual Named Property
PidNameAcceptLanguage | Accept-Language
PidNameApplicationName | AppName
PidNameAttachmentMacContentType | AttachmentMacContentType
PidNameAttachmentMacInfo | AttachmentMacInfo
PidNameAudioNotes | UMAudioNotes
PidNameAuthor | Author
PidNameByteCount | ByteCount
PidNameCategory | Category
PidNameCharacterCount | CharCount
PidNameComments | Comments
PidNameCompany | Company
PidNameContentBase | Content-Base
PidNameContentClass | Content-Class
PidNameContentTransferEncoding | Content-Transfer-Encoding
PidNameContentType | Content-Type
PidNameCreateDateTimeReadOnly | CreateDtmRo
PidNameCrossReference | Xref
PidNameEditTime | EditTime
PidNameExchangeJunkEmailMoveStamp | http://schemas.microsoft.com/exchange/junkemailmovestamp
PidNameHiddenCount | HiddenCount
PidNameKeywords | Keywords
PidNameLastAuthor | LastAuthor
PidNameLastPrinted | LastPrinted
PidNameLastSaveDateTime | LastSaveDtm
PidNameLineCount | LineCount
PidNameManager | Manager
PidNameMultimediaClipCount | MMClipCount
PidNameNoteCount | NoteCount
PidNameOutlookPhishingstamp | http://schemas.microsoft.com/outlook/phishingstamp
PidNamePageCount | PageCount
PidNameParagraphCount | ParCount
PidNamePresentationFormat | PresFormat
PidNameRevisionNumber | RevNumber
PidNameRightsManagementLicense | DRMLicense
PidNameSecurity | Security
PidNameSlideCount | SlideCount
PidNameSubject | Subject
PidNameTemplate | Template
PidNameTitle | Title
PidNameWordCount | WordCount
PidNameXSharingCapabilities | X-Sharing-Capabilities
PidNameXSharingConfigUrl | X-Sharing-Config-Url
PidNameXSharingFlavor | X-Sharing-Flavor
PidNameXSharingLocalType | X-Sharing-Local-Type
PidNameXSharingProviderGuid | X-Sharing-Provider-Guid
PidNameXSharingProviderName | X-Sharing-Provider-Name
PidNameXSharingProviderUrl | X-Sharing-Provider-Url
PidNameXSharingRemoteName | X-Sharing-Remote-Name
PidNameXSharingRemoteStoreUid | X-Sharing-Remote-Store-Uid
PidNameXSharingRemoteType | X-Sharing-Remote-Type
PidNameXSharingRemoteUid | X-Sharing-Remote-Uid

Tagged Properties

Canonical Property Name | Actual Tagged Properties
PidTag7BitDisplayName | PR_7BIT_DISPLAY_NAME, PR_7BIT_DISPLAY_NAME_A, PR_7BIT_DISPLAY_NAME_W
PidTagAbDefaultDir | PR_AB_DEFAULT_DIR
PidTagAbDefaultPab | PR_AB_DEFAULT_PAB
PidTagAbProviderId | PR_AB_PROVIDER_ID
PidTagAbProviders | PR_AB_PROVIDERS
PidTagAbSearchPath | PR_AB_SEARCH_PATH
PidTagAbSearchPathUpdate | PR_AB_SEARCH_PATH_UPDATE
PidTagAccess | PR_ACCESS
PidTagAccessControlListTable | PR_ACL_TABLE
PidTagAccessLevel | PR_ACCESS_LEVEL
PidTagAccount | PR_ACCOUNT, PR_ACCOUNT_A, PR_ACCOUNT_W
PidTagAcknowledgementMode | PR_ACKNOWLEDGEMENT_MODE
PidTagAdditionalRenEntryIds | PR_ADDITIONAL_REN_ENTRYIDS
PidTagAdditionalRenEntryIdsEx | PR_ADDITIONAL_REN_ENTRYIDS_EX
PidTagAddressBookChooseDirectoryAutomatically | PR_AB_CHOOSE_DIRECTORY_AUTOMATICALLY
PidTagAddressType | PR_ADDRTYPE, PR_ADDRTYPE_A, PR_ADDRTYPE_W
PidTagAgingGranularity | PR_AGING_GRANULARITY
PidTagAgingPeriod | PR_AGING_PERIOD
PidTagAlternateRecipient | PR_ALTERNATE_RECIPIENT
PidTagAlternateRecipientAllowed | PR_ALTERNATE_RECIPIENT_ALLOWED
PidTagAnr | PR_ANR, PR_ANR_A, PR_ANR_W
PidTagAssistant | PR_ASSISTANT, PR_ASSISTANT_A, PR_ASSISTANT_W
PidTagAssistantTelephoneNumber | PR_ASSISTANT_TELEPHONE_NUMBER, PR_ASSISTANT_TELEPHONE_NUMBER_A, PR_ASSISTANT_TELEPHONE_NUMBER_W
PidTagAssociatedContentCount | PR_ASSOC_CONTENT_COUNT
PidTagAssociatedSharingProvider | PR_ASSOCIATED_SHARING_PROVIDER
PidTagAttachAdditionalInformation | PR_ATTACH_ADDITIONAL_INFO
PidTagAttachContentBase | PR_ATTACH_CONTENT_BASE, PR_ATTACH_CONTENT_BASE_A, PR_ATTACH_CONTENT_BASE_W
PidTagAttachContentId | PR_ATTACH_CONTENT_ID, PR_ATTACH_CONTENT_ID_A, PR_ATTACH_CONTENT_ID_W
PidTagAttachContentLocation | PR_ATTACH_CONTENT_LOCATION, PR_ATTACH_CONTENT_LOCATION_A, PR_ATTACH_CONTENT_LOCATION_W
PidTagAttachDataBinary | PR_ATTACH_DATA_BIN
PidTagAttachDataObject | PR_ATTACH_DATA_OBJ
PidTagAttachEncoding | PR_ATTACH_ENCODING
PidTagAttachExtension | PR_ATTACH_EXTENSION, PR_ATTACH_EXTENSION_A, PR_ATTACH_EXTENSION_W
PidTagAttachFilename | PR_ATTACH_FILENAME, PR_ATTACH_FILENAME_A, PR_ATTACH_FILENAME_W
PidTagAttachFlags | PR_ATTACH_FLAGS
PidTagAttachLongFilename | PR_ATTACH_LONG_FILENAME, PR_ATTACH_LONG_FILENAME_A, PR_ATTACH_LONG_FILENAME_W
PidTagAttachLongPathname | PR_ATTACH_LONG_PATHNAME, PR_ATTACH_LONG_PATHNAME_A, PR_ATTACH_LONG_PATHNAME_W
PidTagAttachmentContactPhoto | PR_ATTACHMENT_CONTACTPHOTO
PidTagAttachmentFlags | PR_ATTACHMENT_FLAGS
PidTagAttachmentHidden | PR_ATTACHMENT_HIDDEN
PidTagAttachmentLinkId | PR_ATTACHMENT_LINKID
PidTagAttachMethod | PR_ATTACH_METHOD
PidTagAttachMimeSequence | PR_ATTACH_MIME_SEQUENCE
PidTagAttachMimeTag | PR_ATTACH_MIME_TAG, PR_ATTACH_MIME_TAG_A, PR_ATTACH_MIME_TAG_W
PidTagAttachNumber | PR_ATTACH_NUM
PidTagAttachPathname | PR_ATTACH_PATHNAME, PR_ATTACH_PATHNAME_A, PR_ATTACH_PATHNAME_W
PidTagAttachPayloadClass | PR_ATTACH_PAYLOAD_CLASS, PR_ATTACH_PAYLOAD_CLASS_A, PR_ATTACH_PAYLOAD_CLASS_W
PidTagAttachPayloadProviderGuidString | PR_ATTACH_PAYLOAD_PROV_GUID_STR, PR_ATTACH_PAYLOAD_PROV_GUID_STR_A, PR_ATTACH_PAYLOAD_PROV_GUID_STR_W
PidTagAttachRendering | PR_ATTACH_RENDERING
PidTagAttachSize | PR_ATTACH_SIZE
PidTagAttachTag | PR_ATTACH_TAG
PidTagAttachTransportName | PR_ATTACH_TRANSPORT_NAME, PR_ATTACH_TRANSPORT_NAME_A, PR_ATTACH_TRANSPORT_NAME_W
PidTagAuthorizingUsers | PR_AUTHORIZING_USERS
PidTagAutoForwardComment | PR_AUTO_FORWARD_COMMENT, PR_AUTO_FORWARD_COMMENT_A, PR_AUTO_FORWARD_COMMENT_W
PidTagAutoForwarded | PR_AUTO_FORWARDED
PidTagBirthday | PR_BIRTHDAY
PidTagBody | PR_BODY, PR_BODY_A, PR_BODY_W
PidTagBodyContentLocation | PR_BODY_CONTENT_LOCATION, PR_BODY_CONTENT_LOCATION_A, PR_BODY_CONTENT_LOCATION_W
PidTagBodyCrc | PR_BODY_CRC
PidTagBodyHtml | PR_BODY_HTML, PR_BODY_HTML_A, PR_BODY_HTML_W
PidTagBusiness2TelephoneNumber | PR_BUSINESS2_TELEPHONE_NUMBER, PR_BUSINESS2_TELEPHONE_NUMBER_A, PR_BUSINESS2_TELEPHONE_NUMBER_W, PR_OFFICE2_TELEPHONE_NUMBER
PidTagBusiness2TelephoneNumbers | PR_BUSINESS2_TELEPHONE_NUMBER_A_MV
PidTagBusinessFaxNumber | PR_BUSINESS_FAX_NUMBER, PR_BUSINESS_FAX_NUMBER_A, PR_BUSINESS_FAX_NUMBER_W
PidTagBusinessHomePage | PR_BUSINESS_HOME_PAGE, PR_BUSINESS_HOME_PAGE_A, PR_BUSINESS_HOME_PAGE_W
PidTagBusinessTelephoneNumber | PR_BUSINESS_TELEPHONE_NUMBER, PR_BUSINESS_TELEPHONE_NUMBER_A, PR_BUSINESS_TELEPHONE_NUMBER_W, PR_OFFICE_TELEPHONE_NUMBER, PR_OFFICE_TELEPHONE_NUMBER_W
PidTagCallbackTelephoneNumber | PR_CALLBACK_TELEPHONE_NUMBER, PR_CALLBACK_TELEPHONE_NUMBER_A, PR_CALLBACK_TELEPHONE_NUMBER_W
PidTagCarTelephoneNumber | PR_CAR_TELEPHONE_NUMBER, PR_CAR_TELEPHONE_NUMBER_A, PR_CAR_TELEPHONE_NUMBER_W
PidTagChildrensNames | PR_CHILDRENS_NAMES, PR_CHILDRENS_NAMES_A, PR_CHILDRENS_NAMES_W
PidTagClientSubmitTime | PR_CLIENT_SUBMIT_TIME
PidTagComment | PR_COMMENT, PR_COMMENT_A, PR_COMMENT_W
PidTagCommonViewsEntryId | PR_COMMON_VIEWS_ENTRYID
PidTagCompanyMainTelephoneNumber | PR_COMPANY_MAIN_PHONE_NUMBER, PR_COMPANY_MAIN_PHONE_NUMBER_A, PR_COMPANY_MAIN_PHONE_NUMBER_W
PidTagCompanyName | PR_COMPANY_NAME, PR_COMPANY_NAME_A, PR_COMPANY_NAME_W
PidTagComputerNetworkName | PR_COMPUTER_NETWORK_NAME, PR_COMPUTER_NETWORK_NAME_A, PR_COMPUTER_NETWORK_NAME_W
PidTagConflictEntryId | PR_CONFLICT_ENTRYID
PidTagConflictItems | PR_CONFLICT_ITEMS
PidTagContactAddressBookDisplayNames | PR_CONTAB_DISPLAY_NAMES
PidTagContactAddressBookFolderEntryId | PR_CONTAB_FOLDER_ENTRYID
PidTagContactAddressBookFolderEntryIds | PR_CONTAB_FOLDER_ENTRYIDS
PidTagContactAddressBookFolderName | PR_CONTAB_FOLDER_NAME, PR_CONTAB_FOLDER_NAME_W
PidTagContactAddressBookFolderNames | PR_CONTAB_FOLDER_NAMES
PidTagContactAddressBookMultipleAddressFlag | PR_CONTAB_MULTI_ADDR_FLAG
PidTagContactAddressBookMultipleAddressFlags | PR_CONTAB_MULTI_ADDR_FLAGS
PidTagContactAddressBookSortFlag | PR_CONTAB_SORT_FLAG
PidTagContactAddressBookStoreEntryIds | PR_CONTAB_STORE_ENTRYIDS
PidTagContactAddressBookStoreName | PR_CONTAB_STORE_NAME, PR_CONTAB_STORE_NAME_W
PidTagContactAddressBookStoreNames | PR_CONTAB_STORE_NAMES
PidTagContactAddressBookStoreSupportMask | PR_CONTAB_STORE_SUPPORT_MASK
PidTagContactAddressBookStoreSupportMasks | PR_CONTAB_STORE_SUPPORT_MASKS
PidTagContactAddressBookUid | PR_CONTAB_UID
PidTagContactAddressTypes | PR_CONTACT_ADDRTYPES, PR_CONTACT_ADDRTYPES_A, PR_CONTACT_ADDRTYPES_W
PidTagContactVersion | PR_CONTACT_VERSION
PidTagContainerClass | PR_CONTAINER_CLASS, PR_CONTAINER_CLASS_A, PR_CONTAINER_CLASS_W
PidTagContainerContents | PR_CONTAINER_CONTENTS
PidTagContainerFlags | PR_CONTAINER_FLAGS
PidTagContainerHierarchy | PR_CONTAINER_HIERARCHY
PidTagContentConfidentialityAlgorithmId | PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID
PidTagContentCorrelator | PR_CONTENT_CORRELATOR
PidTagContentCount | PR_CONTENT_COUNT
PidTagContentIdentifier | PR_CONTENT_IDENTIFIER, PR_CONTENT_IDENTIFIER_A, PR_CONTENT_IDENTIFIER_W
PidTagContentIntegrityCheck | PR_CONTENT_INTEGRITY_CHECK
PidTagContentLength | PR_CONTENT_LENGTH
PidTagContentReturnRequested | PR_CONTENT_RETUsRN_REQUESTED
PidTagContentUnreadCount | PR_CONTENT_UNREAD
PidTagControlFlags | PR_CONTROL_FLAGS
PidTagControlId | PR_CONTROL_ID
PidTagControlStructure | PR_CONTROL_STRUCTURE
PidTagControlType | PR_CONTROL_TYPE
PidTagConversationIndex | PR_CONVERSATION_INDEX
PidTagConversationKey | PR_CONVERSATION_KEY
PidTagConversationTopic | PR_CONVERSATION_TOPIC, PR_CONVERSATION_TOPIC_A, PR_CONVERSATION_TOPIC_W
PidTagConversionEits | PR_CONVERSION_EITS
PidTagConversionProhibited | PR_CONVERSION_PROHIBITED
PidTagConversionWithLossProhibited | PR_CONVERSION_WITH_LOSS_PROHIBITED
PidTagConvertedEits | PR_CONVERTED_EITS
PidTagCorrelate | PR_CORRELATE
PidTagCorrelateMtsid | PR_CORRELATE_MTSID
PidTagCountry | PR_COUNTRY, PR_COUNTRY_A, PR_COUNTRY_W, PR_BUSINESS_ADDRESS_COUNTRY, PR_BUSINESS_ADDRESS_COUNTRY_A, PR_BUSINESS_ADDRESS_COUNTRY_W
PidTagCreateTemplates | PR_CREATE_TEMPLATES
PidTagCreationTime | PR_CREATION_TIME
PidTagCustomerId | PR_CUSTOMER_ID, PR_CUSTOMER_ID_A, PR_CUSTOMER_ID_W
PidTagDefaultPostMessageClass | PR_DEF_POST_MSGCLASS
PidTagDefaultProfile | PR_DEFAULT_PROFILE
PidTagDefaultStore | PR_DEFAULT_STORE
PidTagDefaultViewEntryId | PR_DEFAULT_VIEW_ENTRYID
PidTagDefCreateDl | PR_DEF_CREATE_DL
PidTagDefCreateMailuser | PR_DEF_CREATE_MAILUSER
PidTagDeferredDeliveryTime | PR_DEFERRED_DELIVERY_TIME
PidTagDeferredSendNumber | PR_DEFERRED_SEND_NUMBER
PidTagDeferredSendTime | PR_DEFERRED_SEND_TIME
PidTagDeferredSendUnits | PR_DEFERRED_SEND_UNITS
PidTagDelegatedByRule | PR_DELEGATED_BY_RULE
PidTagDelegateFlags | PR_DELEGATE_FLAGS
PidTagDeleteAfterSubmit | PR_DELETE_AFTER_SUBMIT
PidTagDeliverTime | PR_DELIVER_TIME
PidTagDeliveryPoint | PR_DELIVERY_POINT
PidTagDeltaX | PR_DELTAX
PidTagDeltaY | PR_DELTAY
PidTagDepartmentName | PR_DEPARTMENT_NAME, PR_DEPARTMENT_NAME_A, PR_DEPARTMENT_NAME_W
PidTagDepth | PR_DEPTH
PidTagDetailsTable | PR_DETAILS_TABLE
PidTagDiscardReason | PR_DISCARD_REASON
PidTagDisclosureOfRecipients | PR_DISCLOSURE_OF_RECIPIENTS
PidTagDiscreteValues | PR_DISCRETE_VALUES
PidTagDisplayBcc | PR_DISPLAY_BCC, PR_DISPLAY_BCC_A, PR_DISPLAY_BCC_W
PidTagDisplayCc | PR_DISPLAY_CC, PR_DISPLAY_CC_A, PR_DISPLAY_CC_W
PidTagDisplayName | PR_DISPLAY_NAME, PR_DISPLAY_NAME_A, PR_DISPLAY_NAME_W
PidTagDisplayNamePrefix | PR_DISPLAY_NAME_PREFIX, PR_DISPLAY_NAME_PREFIX_A, PR_DISPLAY_NAME_PREFIX_W
PidTagDisplayTo | PR_DISPLAY_TO, PR_DISPLAY_TO_A, PR_DISPLAY_TO_W
PidTagDisplayType | PR_DISPLAY_TYPE
PidTagDisplayTypeEx | PR_DISPLAY_TYPE_EX
PidTagDistributionListExpansionHistory | PR_DL_EXPANSION_HISTORY
PidTagDistributionListExpansionProhibited | PR_DL_EXPANSION_PROHIBITED
PidTagEmailAddress | PR_EMAIL_ADDRESS, PR_EMAIL_ADDRESS_A, PR_EMAIL_ADDRESS_W
PidTagEmsAbServer | PR_EMS_AB_SERVER, PR_EMS_AB_SERVER_A PR_EMS_AB_SERVER_W
PidTagEndDate | PR_END_DATE
PidTagEntryId | PR_ENTRYID
PidTagExceptionEndTime | PR_EXCEPTION_ENDTIME
PidTagExceptionReplaceTime | PR_EXCEPTION_REPLACETIME
PidTagExceptionStartTime | PR_EXCEPTION_STARTTIME
PidTagExpiryNumber | PR_EXPIRY_NUMBER
PidTagExpiryTime | PR_EXPIRY_TIME
PidTagExpiryUnits | PR_EXPIRY_UNITS
PidTagExplicitConversion | PR_EXPLICIT_CONVERSION
PidTagExtendedFolderFlags | PR_EXTENDED_FOLDER_FLAGS
PidTagExtendedRuleMessageActions | PR_EXTENDED_RULE_MSG_ACTIONS
PidTagExtendedRuleMessageCondition | PR_EXTENDED_RULE_MSG_CONDITION
PidTagExtendedRuleSizeLimit | PR_EXTENDED_RULE_SIZE_LIMIT
PidTagFinderEntryId | PR_FINDER_ENTRYID
PidTagFlagCompleteTime | PR_FLAG_COMPLETE_TIME
PidTagFlagStatus | PR_FLAG_STATUS
PidTagFolderAssociatedContents | PR_FOLDER_ASSOCIATED_CONTENTS
PidTagFolderType | PR_FOLDER_TYPE
PidTagFollowupIcon | PR_FOLLOWUP_ICON
PidTagFormCategory | PR_FORM_CATEGORY, PR_FORM_CATEGORY_A, PR_FORM_CATEGORY_W
PidTagFormCategorySub | PR_FORM_CATEGORY_SUB, PR_FORM_CATEGORY_SUB_A, PR_FORM_CATEGORY_SUB_W
PidTagFormClassId | PR_FORM_CLSID
PidTagFormContactName | PR_FORM_CONTACT_NAME, PR_FORM_CONTACT_NAME_A, PR_FORM_CONTACT_NAME_W
PidTagFormDesignerGuid | PR_FORM_DESIGNER_GUID
PidTagFormDesignerName | PR_FORM_DESIGNER_NAME, PR_FORM_DESIGNER_NAME_A, PR_FORM_DESIGNER_NAME_W
PidTagFormHidden | PR_FORM_HIDDEN
PidTagFormHostMap | PR_FORM_HOST_MAP
PidTagFormMessageBehavior | PR_FORM_MESSAGE_BEHAVIOR
PidTagFormVersion | PR_FORM_VERSION, PR_FORM_VERSION_A, PR_FORM_VERSION_W
PidTagFreeBusyCountMonths | PR_FREEBUSY_COUNT_MONTHS
PidTagFreeBusyEntryIds | PR_FREEBUSY_ENTRYIDS
PidTagFreeBusyPublishEnd | PR_FREEBUSY_PUBLISH_END
PidTagFreeBusyPublishStart | PR_FREEBUSY_PUBLISH_START
PidTagFreeBusyRangeTimestamp | PR_FREEBUSY_RANGE_TIMESTAMP
PidTagFtpSite | PR_FTP_SITE, PR_FTP_SITE_A, PR_FTP_SITE_W
PidTagGender | PR_GENDER
PidTagGeneration | PR_GENERATION, PR_GENERATION_A, PR_GENERATION_W
PidTagGivenName | PR_GIVEN_NAME, PR_GIVEN_NAME_A, PR_GIVEN_NAME_W
PidTagGovernmentIdNumber | PR_GOVERNMENT_ID_NUMBER, PR_GOVERNMENT_ID_NUMBER_A, PR_GOVERNMENT_ID_NUMBER_W
PidTagHasAttachments | PR_HASATTACH
PidTagHasDeferredActionMessages | PR_HAS_DAMS
PidTagHobbies | PR_HOBBIES, PR_HOBBIES_A, PR_HOBBIES_W
PidTagHome2TelephoneNumber | PR_HOME2_TELEPHONE_NUMBER, PR_HOME2_TELEPHONE_NUMBER_A, PR_HOME2_TELEPHONE_NUMBER_W
PidTagHome2TelephoneNumbers | PR_HOME2_TELEPHONE_NUMBER_A_MV
PidTagHomeAddressCity | PR_HOME_ADDRESS_CITY, PR_HOME_ADDRESS_CITY_A, PR_HOME_ADDRESS_CITY_W
PidTagHomeAddressCountry | PR_HOME_ADDRESS_COUNTRY, PR_HOME_ADDRESS_COUNTRY_A, PR_HOME_ADDRESS_COUNTRY_W
PidTagHomeAddressPostalCode | PR_HOME_ADDRESS_POSTAL_CODE, PR_HOME_ADDRESS_POSTAL_CODE_A, PR_HOME_ADDRESS_POSTAL_CODE_W
PidTagHomeAddressPostOfficeBox | PR_HOME_ADDRESS_POST_OFFICE_BOX, PR_HOME_ADDRESS_POST_OFFICE_BOX_A, PR_HOME_ADDRESS_POST_OFFICE_BOX_W
PidTagHomeAddressStateOrProvince | PR_HOME_ADDRESS_STATE_OR_PROVINCE, PR_HOME_ADDRESS_STATE_OR_PROVINCE_A, PR_HOME_ADDRESS_STATE_OR_PROVINCE_W
PidTagHomeAddressStreet | PR_HOME_ADDRESS_STREET, PR_HOME_ADDRESS_STREET_A, PR_HOME_ADDRESS_STREET_W
PidTagHomeFaxNumber | PR_HOME_FAX_NUMBER, PR_HOME_FAX_NUMBER_A, PR_HOME_FAX_NUMBER_W
PidTagHomeTelephoneNumber | PR_HOME_TELEPHONE_NUMBER, PR_HOME_TELEPHONE_NUMBER_A, PR_HOME_TELEPHONE_NUMBER_W
PidTagHtml | PR_HTML
PidTagIcon | PR_ICON
PidTagIconIndex | PR_ICON_INDEX
PidTagIdentityDisplay | PR_IDENTITY_DISPLAY, PR_IDENTITY_DISPLAY_A, PR_IDENTITY_DISPLAY_W
PidTagIdentityEntryId | PR_IDENTITY_ENTRYID
PidTagIdentitySearchKey | PR_IDENTITY_SEARCH_KEY
PidTagImapCachedMsgsize | None
PidTagImplicitConversionProhibited | PR_IMPLICIT_CONVERSION_PROHIBITED
PidTagImportance | PR_IMPORTANCE
PidTagIncompleteCopy | PR_INCOMPLETE_COPY
PidTagInConflict | PR_IN_CONFLICT
PidTagInferenceEnabled | PR_INFERENCES_ENABLED
PidTagInitialDetailsPane | PR_INITIAL_DETAILS_PANE
PidTagInitials | PR_INITIALS, PR_INITIALS_A, PR_INITIALS_W
PidTagInReplyToId | PR_IN_REPLY_TO_ID, PR_IN_REPLY_TO_ID_A, PR_IN_REPLY_TO_ID_W
PidTagInstanceKey | PR_INSTANCE_KEY
PidTagInternetApproved | PR_INTERNET_APPROVED, PR_INTERNET_APPROVED_A, PR_INTERNET_APPROVED_W
PidTagInternetArticleNumber | PR_INTERNET_ARTICLE_NUMBER
PidTagInternetCodepage | PR_INTERNET_CPID
PidTagInternetControl | PR_INTERNET_CONTROL, PR_INTERNET_CONTROL_A, PR_INTERNET_CONTROL_W
PidTagInternetDistribution | PR_INTERNET_DISTRIBUTION, PR_INTERNET_DISTRIBUTION_A, PR_INTERNET_DISTRIBUTION_W
PidTagInternetFollowupTo | PR_INTERNET_FOLLOWUP_TO, PR_INTERNET_FOLLOWUP_TO_A, PR_INTERNET_FOLLOWUP_TO_W
PidTagInternetLines | PR_INTERNET_LINES
PidTagInternetMailOverrideFormat | PR_INETMAIL_OVERRIDE_FORMAT
PidTagInternetMessageId | PR_INTERNET_MESSAGE_ID, PR_INTERNET_MESSAGE_ID_A, PR_INTERNET_MESSAGE_ID_W
PidTagInternetNntpPath | PR_INTERNET_NNTP_PATH, PR_INTERNET_NNTP_PATH_A, PR_INTERNET_NNTP_PATH_W
PidTagInternetOrganization | PR_INTERNET_ORGANIZATION, PR_INTERNET_ORGANIZATION_A, PR_INTERNET_ORGANIZATION_W
PidTagInternetReferences | PR_INTERNET_REFERENCES, PR_INTERNET_REFERENCES_A, PR_INTERNET_REFERENCES_W
PidTagInternetReturnPath | PR_INTERNET_RETURN_PATH, PR_INTERNET_RETURN_PATH_A, PR_INTERNET_RETURN_PATH_W
PidTagIpmAppointmentEntryId | PR_IPM_APPOINTMENT_ENTRYID
PidTagIpmContactEntryId | PR_IPM_CONTACT_ENTRYID
PidTagIpmDraftsEntryId | PR_IPM_DRAFTS_ENTRYID
PidTagIpmJournalEntryId | PR_IPM_JOURNAL_ENTRYID
PidTagIpmNoteEntryId | PR_IPM_NOTE_ENTRYID
PidTagIpmOutboxEntryId | PR_IPM_OUTBOX_ENTRYID
PidTagIpmReturnRequested | PR_IPM_RETURN_REQUESTED
PidTagIpmSentMailEntryId | PR_IPM_SENTMAIL_ENTRYID
PidTagIpmSubtreeEntryId | PR_IPM_SUBTREE_ENTRYID
PidTagIpmTaskEntryId | PR_IPM_TASK_ENTRYID
PidTagIpmWastebasketEntryId | PR_IPM_WASTEBASKET_ENTRYID
PidTagIsdnNumber | PR_ISDN_NUMBER, PR_ISDN_NUMBER_A, PR_ISDN_NUMBER_W
PidTagItemTemporaryflags | PR_ITEM_TMPFLAGS
PidTagJunkAddRecipientsToSafeSendersList | PR_JUNK_ADD_RECIPS_TO_SSL
PidTagJunkIncludeContacts | PR_JUNK_INCLUDE_CONTACTS
PidTagJunkPermanentlyDelete | PR_JUNK_PERMANENTLY_DELETE
PidTagJunkPhishingEnableLinks | PR_JUNK_PHISHING_ENABLE_LINKS
PidTagJunkThreshold | PR_JUNK_THRESHOLD
PidTagKeyword | PR_KEYWORD, PR_KEYWORD_A, PR_KEYWORD_W
PidTagLanguage | PR_LANGUAGE, PR_LANGUAGE_A, PR_LANGUAGE_W
PidTagLanguages | PR_LANGUAGES, PR_LANGUAGES_A, PR_LANGUAGES_W
PidTagLastModificationTime | PR_LAST_MODIFICATION_TIME
PidTagLastVerbExecuted | PR_LAST_VERB_EXECUTED
PidTagLastVerbExecutionTime | PR_LAST_VERB_EXECUTION_TIME
PidTagLatestDeliveryTime | PR_LATEST_DELIVERY_TIME
PidTagListHelp | PR_LIST_HELP, PR_LIST_HELP_A, PR_LIST_HELP_W
PidTagListSubscribe | PR_LIST_SUBSCRIBE, PR_LIST_SUBSCRIBE_A, PR_LIST_SUBSCRIBE_W
PidTagListUnsubscribe | PR_LIST_UNSUBSCRIBE, PR_LIST_UNSUBSCRIBE_A, PR_LIST_UNSUBSCRIBE_W
PidTagLocaleId | PR_LOCALE_ID
PidTagLocality | PR_LOCALITY, PR_LOCALITY_A, PR_LOCALITY_W, PR_BUSINESS_ADDRESS_LOCALITY, PR_BUSINESS_ADDRESS_LOCALITY_A, PR_BUSINESS_ADDRESS_LOCALITY_W
PidTagLocation | PR_LOCATION, PR_LOCATION_A, PR_LOCATION_W
PidTagMailPermission | PR_MAIL_PERMISSION
PidTagManagerName | PR_MANAGER_NAME, PR_MANAGER_NAME_A, PR_MANAGER_NAME_W
PidTagMappingSignature | PR_MAPPING_SIGNATURE
PidTagMemberEntryId | PR_MEMBER_ENTRYID
PidTagMemberId | PR_MEMBER_ID
PidTagMemberName | PR_MEMBER_NAME
PidTagMemberRights | PR_MEMBER_RIGHTS
PidTagMessageAttachments | PR_MESSAGE_ATTACHMENTS
PidTagMessageCcMe | PR_MESSAGE_CC_ME
PidTagMessageClass | PR_MESSAGE_CLASS, PR_MESSAGE_CLASS_A, PR_MESSAGE_CLASS_W
PidTagMessageCodepage | PR_MESSAGE_CODEPAGE
PidTagMessageDeliveryId | PR_MESSAGE_DELIVERY_ID
PidTagMessageDeliveryTime | PR_MESSAGE_DELIVERY_TIME
PidTagMessageDownloadTime | PR_MESSAGE_DOWNLOAD_TIME
PidTagMessageEditorFormat | PR_MSG_EDITOR_FORMAT
PidTagMessageFlags | PR_MESSAGE_FLAGS
PidTagMessageHandlingSystemCommonName | PR_MHS_COMMON_NAME, PR_MHS_COMMON_NAME_A, PR_MHS_COMMON_NAME_W
PidTagMessageLocaleId | PR_MESSAGE_LOCALE_ID
PidTagMessageRecipientMe | PR_MESSAGE_RECIP_ME
PidTagMessageRecipients | PR_MESSAGE_RECIPIENTS
PidTagMessageSecurityLabel | PR_MESSAGE_SECURITY_LABEL
PidTagMessageSize | PR_MESSAGE_SIZE
PidTagMessageSizeExtended | PR_MESSAGE_SIZE_EXTENDED
PidTagMessageStatus | PR_MSG_STATUS
PidTagMessageSubmissionId | PR_MESSAGE_SUBMISSION_ID
PidTagMessageToMe | PR_MESSAGE_TO_ME
PidTagMiddleName | PR_MIDDLE_NAME, PR_MIDDLE_NAME_A, PR_MIDDLE_NAME_W
PidTagMiniIcon | PR_MINI_ICON
PidTagMobileTelephoneNumber | PR_MOBILE_TELEPHONE_NUMBER, PR_MOBILE_TELEPHONE_NUMBER_A, PR_MOBILE_TELEPHONE_NUMBER_W, PR_CELLULAR_TELEPHONE_NUMBER, PR_CELLULAR_TELEPHONE_NUMBER_A, PR_CELLULAR_TELEPHONE_NUMBER_W
PidTagNextSendAcct | PR_NEXT_SEND_ACCT
PidTagNickname | PR_NICKNAME, PR_NICKNAME_A, PR_NICKNAME_W
PidTagNonDeliveryReportDiagCode | PR_NDR_DIAG_CODE
PidTagNonDeliveryReportFromEntryId | PR_NDR_FROM_ENTRYID
PidTagNonDeliveryReportFromName | PR_NDR_FROM_NAME
PidTagNonDeliveryReportFromSearchKey | PR_NDR_FROM_SEARCH_KEY
PidTagNonDeliveryReportReasonCode | PR_NDR_REASON_CODE
PidTagNonIpmSubtreeEntryId | PR_NON_IPM_SUBTREE_ENTRYID
PidTagNonReceiptNotificationRequested | PR_NON_RECEIPT_NOTIFICATION_REQUESTED
PidTagNonReceiptReason | PR_NON_RECEIPT_REASON
PidTagNormalizedSubject | PR_NORMALIZED_SUBJECT, PR_NORMALIZED_SUBJECT_A, PR_NORMALIZED_SUBJECT_W
PidTagObjectType | PR_OBJECT_TYPE
PidTagObsoletedMessageIds | PR_OBSOLETED_IPMS
PidTagOfficeLocation | PR_OFFICE_LOCATION, PR_OFFICE_LOCATION_A, PR_OFFICE_LOCATION_W
PidTagOrdinalMost | PR_ORDINAL_MOST
PidTagOrganizationalIdNumber | PR_ORGANIZATIONAL_ID_NUMBER, PR_ORGANIZATIONAL_ID_NUMBER_A, PR_ORGANIZATIONAL_ID_NUMBER_W
PidTagOrgEmailAddress | PR_ORG_EMAIL_ADDRESS
PidTagOriginalAuthorAddressType | PR_ORIGINAL_AUTHOR_ADDRTYPE, PR_ORIGINAL_AUTHOR_ADDRTYPE_A, PR_ORIGINAL_AUTHOR_ADDRTYPE_W
PidTagOriginalAuthorEmailAddress | PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS, PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_A, PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_W
PidTagOriginalAuthorEntryId | PR_ORIGINAL_AUTHOR_ENTRYID
PidTagOriginalAuthorName | PR_ORIGINAL_AUTHOR_NAME, PR_ORIGINAL_AUTHOR_NAME_A, PR_ORIGINAL_AUTHOR_NAME_W
PidTagOriginalAuthorSearchKey | PR_ORIGINAL_AUTHOR_SEARCH_KEY
PidTagOriginalDeliveryTime | PR_ORIGINAL_DELIVERY_TIME
PidTagOriginalDisplayBcc | PR_ORIGINAL_DISPLAY_BCC, PR_ORIGINAL_DISPLAY_BCC_A, PR_ORIGINAL_DISPLAY_BCC_W
PidTagOriginalDisplayCc | PR_ORIGINAL_DISPLAY_CC, PR_ORIGINAL_DISPLAY_CC_A, PR_ORIGINAL_DISPLAY_CC_W
PidTagOriginalDisplayName | PR_ORIGINAL_DISPLAY_NAME, PR_ORIGINAL_DISPLAY_NAME_A, PR_ORIGINAL_DISPLAY_NAME_W
PidTagOriginalDisplayTo | PR_ORIGINAL_DISPLAY_TO, PR_ORIGINAL_DISPLAY_TO_A, PR_ORIGINAL_DISPLAY_TO_W
PidTagOriginalEits | PR_ORIGINAL_EITS
PidTagOriginalEntryId | PR_ORIGINAL_ENTRYID
PidTagOriginallyIntendedRecipAddrtype | PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE, PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_A, PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_W
PidTagOriginallyIntendedRecipEmailAddress | PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS, PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_A, PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_W
PidTagOriginallyIntendedRecipEntryId | PR_ORIGINALLY_INTENDED_RECIP_ENTRYID
PidTagOriginallyIntendedRecipientName | PR_ORIGINALLY_INTENDED_RECIPIENT_NAME
PidTagOriginalMessageClass | PR_ORIG_MESSAGE_CLASS, PR_ORIG_MESSAGE_CLASS_A, PR_ORIG_MESSAGE_CLASS_W
PidTagOriginalSearchKey | PR_ORIGINAL_SEARCH_KEY
PidTagOriginalSenderAddressType | PR_ORIGINAL_SENDER_ADDRTYPE, PR_ORIGINAL_SENDER_ADDRTYPE_A, PR_ORIGINAL_SENDER_ADDRTYPE_W
PidTagOriginalSenderEmailAddress | PR_ORIGINAL_SENDER_EMAIL_ADDRESS, PR_ORIGINAL_SENDER_EMAIL_ADDRESS_A, PR_ORIGINAL_SENDER_EMAIL_ADDRESS_W
PidTagOriginalSenderEntryId | PR_ORIGINAL_SENDER_ENTRYID
PidTagOriginalSenderName | PR_ORIGINAL_SENDER_NAME, PR_ORIGINAL_SENDER_NAME_A, PR_ORIGINAL_SENDER_NAME_W
PidTagOriginalSenderSearchKey | PR_ORIGINAL_SENDER_SEARCH_KEY
PidTagOriginalSensitivity | PR_ORIGINAL_SENSITIVITY
PidTagOriginalSentRepresentingAddressType | PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE, PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_A, PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_W
PidTagOriginalSentRepresentingEmailAddress | PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS, PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_A, PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_W
PidTagOriginalSentRepresentingEntryId | PR_ORIGINAL_SENT_REPRESENTING_ENTRYID
PidTagOriginalSentRepresentingName | PR_ORIGINAL_SENT_REPRESENTING_NAME, PR_ORIGINAL_SENT_REPRESENTING_NAME_A, PR_ORIGINAL_SENT_REPRESENTING_NAME_W
PidTagOriginalSentRepresentingSearchKey | PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY
PidTagOriginalSubject | PR_ORIGINAL_SUBJECT, PR_ORIGINAL_SUBJECT_A, PR_ORIGINAL_SUBJECT_W
PidTagOriginalSubmitTime | PR_ORIGINAL_SUBMIT_TIME
PidTagOriginatingMtaCertificate | PR_ORIGINATING_MTA_CERTIFICATE
PidTagOriginatorAndDistributionListExpansionHistory | PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY
PidTagOriginatorCertificate | PR_ORIGINATOR_CERTIFICATE
PidTagOriginatorDeliveryReportRequested | PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED
PidTagOriginatorNonDeliveryReportRequested | PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED
PidTagOriginatorRequestedAlternateRecipient | PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT
PidTagOriginatorReturnAddress | PR_ORIGINATOR_RETURN_ADDRESS
PidTagOriginCheck | PR_ORIGIN_CHECK
PidTagOtherAddressCity | PR_OTHER_ADDRESS_CITY, PR_OTHER_ADDRESS_CITY_A, PR_OTHER_ADDRESS_CITY_W
PidTagOtherAddressCountry | PR_OTHER_ADDRESS_COUNTRY, PR_OTHER_ADDRESS_COUNTRY_A, PR_OTHER_ADDRESS_COUNTRY_W
PidTagOtherAddressPostalCode | PR_OTHER_ADDRESS_POSTAL_CODE, PR_OTHER_ADDRESS_POSTAL_CODE_A, PR_OTHER_ADDRESS_POSTAL_CODE_W
PidTagOtherAddressPostOfficeBox | PR_OTHER_ADDRESS_POST_OFFICE_BOX, PR_OTHER_ADDRESS_POST_OFFICE_BOX_A, PR_OTHER_ADDRESS_POST_OFFICE_BOX_W
PidTagOtherAddressStateOrProvince | PR_OTHER_ADDRESS_STATE_OR_PROVINCE, PR_OTHER_ADDRESS_STATE_OR_PROVINCE_A, PR_OTHER_ADDRESS_STATE_OR_PROVINCE_W
PidTagOtherAddressStreet | PR_OTHER_ADDRESS_STREET, PR_OTHER_ADDRESS_STREET_A, PR_OTHER_ADDRESS_STREET_W
PidTagOtherTelephoneNumber | PR_OTHER_TELEPHONE_NUMBER, PR_OTHER_TELEPHONE_NUMBER_A, PR_OTHER_TELEPHONE_NUMBER_W
PidTagOwnerAppointmentId | PR_OWNER_APPT_ID
PidTagOwnStoreEntryId | PR_OWN_STORE_ENTRYID
PidTagPagerTelephoneNumber | PR_PAGER_TELEPHONE_NUMBER, PR_PAGER_TELEPHONE_NUMBER_A, PR_PAGER_TELEPHONE_NUMBER_W
PidTagParentDisplay | PR_PARENT_DISPLAY, PR_PARENT_DISPLAY_A, PR_PARENT_DISPLAY_W
PidTagParentEntryId | PR_PARENT_ENTRYID
PidTagPersonalHomePage | PR_PERSONAL_HOME_PAGE, PR_PERSONAL_HOME_PAGE_A, PR_PERSONAL_HOME_PAGE_W
PidTagPhysicalDeliveryBureauFaxDelivery | PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY
PidTagPhysicalDeliveryMode | PR_PHYSICAL_DELIVERY_MODE
PidTagPhysicalDeliveryReportRequest | PR_PHYSICAL_DELIVERY_REPORT_REQUEST
PidTagPhysicalForwardingAddress | PR_PHYSICAL_FORWARDING_ADDRESS
PidTagPhysicalForwardingAddressRequested | PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED
PidTagPhysicalForwardingProhibited | PR_PHYSICAL_FORWARDING_PROHIBITED
PidTagPhysicalRenditionAttributes | PR_PHYSICAL_RENDITION_ATTRIBUTES
PidTagPostalAddress | PR_POSTAL_ADDRESS, PR_POSTAL_ADDRESS_A, PR_POSTAL_ADDRESS_W
PidTagPostalCode | PR_POSTAL_CODE, PR_POSTAL_CODE_A, PR_POSTAL_CODE_W, PR_BUSINESS_ADDRESS_POSTAL_CODE, PR_BUSINESS_ADDRESS_POSTAL_CODE_A, PR_BUSINESS_ADDRESS_POSTAL_CODE_W
PidTagPostOfficeBox | PR_POST_OFFICE_BOX, PR_POST_OFFICE_BOX_A, PR_POST_OFFICE_BOX_W, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_A, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_W
PidTagPreferredByName | PR_PREFERRED_BY_NAME, PR_PREFERRED_BY_NAME_A, PR_PREFERRED_BY_NAME_W
PidTagPreprocess | PR_PREPROCESS
PidTagPrimaryFaxNumber | PR_PRIMARY_FAX_NUMBER, PR_PRIMARY_FAX_NUMBER_A, PR_PRIMARY_FAX_NUMBER_W
PidTagPrimarySendAccount | PR_PRIMARY_SEND_ACCT
PidTagPrimaryTelephoneNumber | PR_PRIMARY_TELEPHONE_NUMBER, PR_PRIMARY_TELEPHONE_NUMBER_A, PR_PRIMARY_TELEPHONE_NUMBER_W
PidTagPriority | PR_PRIORITY
PidTagProcessed | PR_PROCESSED
PidTagProfession | PR_PROFESSION, PR_PROFESSION_A, PR_PROFESSION_W
PidTagProfileHomeServerFQDN | PR_PROFILE_HOME_SERVER_FQDN
PidTagProfileName | PR_PROFILE_NAME, PR_PROFILE_NAME_A, PR_PROFILE_NAME_W
PidTagProfileServerFullVersion | PR_PROFILE_SERVER_FULL_VERSION
PidTagProfileServerVersion | PR_PROFILE_SERVER_VERSION
PidTagProfileType | PR_PROFILE_TYPE
PidTagProofOfDelivery | PR_PROOF_OF_DELIVERY
PidTagProofOfDeliveryRequested | PR_PROOF_OF_DELIVERY_REQUESTED
PidTagProofOfSubmission | PR_PROOF_OF_SUBMISSION
PidTagProofOfSubmissionRequested | PR_PROOF_OF_SUBMISSION_REQUESTED
PidTagProviderDisplay | PR_PROVIDER_DISPLAY, PR_PROVIDER_DISPLAY_A, PR_PROVIDER_DISPLAY_W
PidTagProviderDisplayName | PR_PROVIDER_DISPLAY_NAME, PR_PROVIDER_DISPLAY_NAME_W
PidTagProviderDllName | PR_PROVIDER_DLL_NAME, PR_PROVIDER_DLL_NAME_A, PR_PROVIDER_DLL_NAME_W
PidTagProviderIcon | PR_PROVIDER_ICON, PR_PROVIDER_ICON_W
PidTagProviderItemId | PR_PROVIDER_ITEMID
PidTagProviderOrdinal | PR_PROVIDER_ORDINAL
PidTagProviderParentItemId | PR_PROVIDER_PARENT_ITEMID
PidTagProviderSubmitTime | PR_PROVIDER_SUBMIT_TIME
PidTagProviderUid | PR_PROVIDER_UID
PidTagPstConfigurationFlags | PR_PST_CONFIG_FLAGS
PidTagPstPasswordSzNew | PR_PST_PW_SZ_NEW, PR_PST_PW_SZ_NEW_A, PR_PST_PW_SZ_NEW_W
PidTagPstPasswordSzOld | PR_PST_PW_SZ_OLD, PR_PST_PW_SZ_OLD_A, PR_PST_PW_SZ_OLD_W
PidTagPstPath | PR_PST_PATH, PR_PST_PATH_A, PR_PST_PATH_W
PidTagPstPathHint | PR_PST_PATH_HINT, PR_PST_PATH_HINT_A, PR_PST_PATH_HINT_W
PidTagPstRememberPassword | PR_PST_REMEMBER_PW
PidTagRadioTelephoneNumber | PR_RADIO_TELEPHONE_NUMBER, PR_RADIO_TELEPHONE_NUMBER_A, PR_RADIO_TELEPHONE_NUMBER_W
PidTagRead | PR_READ
PidTagReadReceiptEntryId | PR_READ_RECEIPT_ENTRYID
PidTagReadReceiptRequested | PR_READ_RECEIPT_REQUESTED
PidTagReadReceiptSearchKey | PR_READ_RECEIPT_SEARCH_KEY
PidTagReceiptTime | PR_RECEIPT_TIME
PidTagReceivedByAddressType | PR_RECEIVED_BY_ADDRTYPE, PR_RECEIVED_BY_ADDRTYPE_A, PR_RECEIVED_BY_ADDRTYPE_W
PidTagReceivedByEmailAddress | PR_RECEIVED_BY_EMAIL_ADDRESS, PR_RECEIVED_BY_EMAIL_ADDRESS_A, PR_RECEIVED_BY_EMAIL_ADDRESS_W
PidTagReceivedByEntryId | PR_RECEIVED_BY_ENTRYID
PidTagReceivedByName | PR_RECEIVED_BY_NAME, PR_RECEIVED_BY_NAME_A, PR_RECEIVED_BY_NAME_W
PidTagReceivedBySearchKey | PR_RECEIVED_BY_SEARCH_KEY
PidTagReceivedRepresentingAddressType | PR_RCVD_REPRESENTING_ADDRTYPE, PR_RCVD_REPRESENTING_ADDRTYPE_A, PR_RCVD_REPRESENTING_ADDRTYPE_W
PidTagReceivedRepresentingEmailAddress | PR_RCVD_REPRESENTING_EMAIL_ADDRESS, PR_RCVD_REPRESENTING_EMAIL_ADDRESS_A, PR_RCVD_REPRESENTING_EMAIL_ADDRESS_W
PidTagReceivedRepresentingEntryId | PR_RCVD_REPRESENTING_ENTRYID
PidTagReceivedRepresentingName | PR_RCVD_REPRESENTING_NAME, PR_RCVD_REPRESENTING_NAME_A, PR_RCVD_REPRESENTING_NAME_W
PidTagReceivedRepresentingSearchKey | PR_RCVD_REPRESENTING_SEARCH_KEY
PidTagReceiveFolderSettings | PR_RECEIVE_FOLDER_SETTINGS
PidTagRecipientCertificate | PR_RECIPIENT_CERTIFICATE
PidTagRecipientDisplayName | PR_RECIPIENT_DISPLAY_NAME, PR_RECIPIENT_DISPLAY_NAME_W
PidTagRecipientEntryId | PR_RECIPIENT_ENTRYID
PidTagRecipientFlags | PR_RECIPIENT_FLAGS
PidTagRecipientNumber | PR_RECIPIENT_NUMBER
PidTagRecipientNumberForAdvice | PR_RECIPIENT_NUMBER_FOR_ADVICE, PR_RECIPIENT_NUMBER_FOR_ADVICE_A, PR_RECIPIENT_NUMBER_FOR_ADVICE_W
PidTagRecipientProposed | PR_RECIPIENT_PROPOSED
PidTagRecipientProposedEndTime | PR_RECIPIENT_PROPOSEDENDTIME
PidTagRecipientProposedStartTime | PR_RECIPIENT_PROPOSEDSTARTTIME
PidTagRecipientReassignmentProhibited | PR_RECIPIENT_REASSIGNMENT_PROHIBITED
PidTagRecipientStatus | PR_RECIPIENT_STATUS
PidTagRecipientTrackStatus | PR_RECIPIENT_TRACKSTATUS
PidTagRecipientTrackStatusTime | PR_RECIPIENT_TRACKSTATUS_TIME
PidTagRecipientType | PR_RECIPIENT_TYPE
PidTagRecordKey | PR_RECORD_KEY
PidTagRedirectionHistory | PR_REDIRECTION_HISTORY
PidTagReferredByName | PR_REFERRED_BY_NAME, PR_REFERRED_BY_NAME_A, PR_REFERRED_BY_NAME_W
PidTagRegisteredMailType | PR_REGISTERED_MAIL_TYPE
PidTagRelatedMessageIds | PR_RELATED_IPMS
PidTagRemindersOnlineEntryId | PR_REM_ONLINE_ENTRYID
PidTagRemoteProgress | PR_REMOTE_PROGRESS
PidTagRemoteProgressText | PR_REMOTE_PROGRESS_TEXT, PR_REMOTE_PROGRESS_TEXT_A, PR_REMOTE_PROGRESS_TEXT_W
PidTagRemoteValidateOk | PR_REMOTE_VALIDATE_OK
PidTagRenderingPosition | PR_RENDERING_POSITION
PidTagReplyRecipientEntries | PR_REPLY_RECIPIENT_ENTRIES
PidTagReplyRecipientNames | PR_REPLY_RECIPIENT_NAMES, PR_REPLY_RECIPIENT_NAMES_A, PR_REPLY_RECIPIENT_NAMES_W
PidTagReplyRequested | PR_REPLY_REQUESTED
PidTagReplyTemplateId | PR_REPLY_TEMPLATE_ID
PidTagReplyTime | PR_REPLY_TIME
PidTagReportDisposition | PR_REPORT_DISPOSITION, PR_REPORT_DISPOSITION_A, PR_REPORT_DISPOSITION_W
PidTagReportDispositionMode | PR_REPORT_DISPOSITION_MODE, PR_REPORT_DISPOSITION_MODE_A, PR_REPORT_DISPOSITION_MODE_W
PidTagReportDispositionOptions | PR_REPORT_DISPOSITION_OPTIONS, PR_REPORT_DISPOSITION_OPTIONS_A, PR_REPORT_DISPOSITION_OPTIONS_W
PidTagReportDispositionToEmailAddresses | PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES, PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_A, PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_W
PidTagReportDispositionToNames | PR_REPORT_DISPOSITION_TO_NAMES, PR_REPORT_DISPOSITION_TO_NAMES_A, PR_REPORT_DISPOSITION_TO_NAMES_W
PidTagReportOriginalSender | PR_REPORT_ORIGINAL_SENDER, PR_REPORT_ORIGINAL_SENDER_A, PR_REPORT_ORIGINAL_SENDER_W
PidTagReportEntryId | PR_REPORT_ENTRYID
PidTagReportingDistributionListName | PR_REPORTING_DL_NAME
PidTagReportingMessageTransferAgentCertificate | PR_REPORTING_MTA_CERTIFICATE
PidTagReportName | PR_REPORT_NAME, PR_REPORT_NAME_A, PR_REPORT_NAME_W
PidTagReportSearchKey | PR_REPORT_SEARCH_KEY
PidTagReportTag | PR_REPORT_TAG
PidTagReportText | PR_REPORT_TEXT, PR_REPORT_TEXT_A, PR_REPORT_TEXT_W
PidTagReportTime | PR_REPORT_TIME
PidTagRequestedDeliveryMethod | PR_REQUESTED_DELIVERY_METHOD
PidTagResolveMethod | PR_RESOLVE_METHOD
PidTagResourceFlags | PR_RESOURCE_FLAGS
PidTagResourceMethods | PR_RESOURCE_METHODS
PidTagResourcePath | PR_RESOURCE_PATH, PR_RESOURCE_PATH_A, PR_RESOURCE_PATH_W
PidTagResourceType | PR_RESOURCE_TYPE
PidTagResponseRequested | PR_RESPONSE_REQUESTED
PidTagResponsibility | PR_RESPONSIBILITY
PidTagReturnedMessageid | PR_RETURNED_IPM
PidTagRoamingBinary | PR_ROAMING_BINARYSTREAM
PidTagRoamingDatatypes | PR_ROAMING_DATATYPES
PidTagRoamingDictionary | PR_ROAMING_DICTIONARY
PidTagRoamingXmlStream | PR_ROAMING_XMLSTREAM
PidTagRowid | PR_ROWID
PidTagRowType | PR_ROW_TYPE
PidTagRpcOverHttpFlags | PR_ROH_FLAGS
PidTagRpcOverHttpProxyAuthScheme | PR_ROH_PROXY_AUTH_SCHEME
PidTagRpcOverHttpProxyPrincipalName | PR_ROH_PROXY_PRINCIPAL_NAME
PidTagRpcOverHttpProxyServer | PR_ROH_PROXY_SERVER
PidTagRtfCompressed | PR_RTF_COMPRESSED
PidTagRtfInSync | PR_RTF_IN_SYNC
PidTagRtfSyncBodyCount | PR_RTF_SYNC_BODY_COUNT
PidTagRtfSyncBodyCrc | PR_RTF_SYNC_BODY_CRC
PidTagRtfSyncBodyTag | PR_RTF_SYNC_BODY_TAG, PR_RTF_SYNC_BODY_TAG_A, PR_RTF_SYNC_BODY_TAG_W
PidTagRtfSyncPrefixCount | PR_RTF_SYNC_PREFIX_COUNT
PidTagRtfSyncTrailingCount | PR_RTF_SYNC_TRAILING_COUNT
PidTagRuleActions | PR_RULE_ACTIONS
PidTagRuleCondition | PR_RULE_CONDITION
PidTagRuleId | PR_RULE_ID
PidTagRuleLevel | PR_RULE_LEVEL
PidTagRuleMsgName | PR_RULE_MSG_NAME
PidTagRuleMsgProvider | PR_RULE_MSG_PROVIDER
PidTagRuleName | PR_RULE_NAME
PidTagRuleProvider | PR_RULE_PROVIDER
PidTagRuleProviderData | PR_RULE_PROVIDER_DATA
PidTagRuleSequence | PR_RULE_SEQUENCE
PidTagRulesTable | PR_RULES_TABLE
PidTagRuleState | PR_RULE_STATE
PidTagRuleUserFlags | PR_RULE_USER_FLAGS
PidTagScheduleInfoAppointmentTombstone | PR_SCHDINFO_APPT_TOMBSTONE
PidTagScheduleInfoAutoAcceptAppointments | PR_SCHDINFO_AUTO_ACCEPT_APPTS
PidTagScheduleInfoDelegateEntryIds | PR_SCHDINFO_DELEGATE_ENTRYIDS
PidTagScheduleInfoDelegateNames | PR_SCHDINFO_DELEGATE_NAMES
PidTagScheduleInfoDelegatorWantsCopy | PR_SCHDINFO_BOSS_WANTS_COPY
PidTagScheduleInfoDelegatorWantsInfo | PR_SCHDINFO_BOSS_WANTS_INFO
PidTagScheduleInfoDisallowOverlappingAppts | PR_SCHDINFO_DISALLOW_OVERLAPPING_APPTS
PidTagScheduleInfoDisallowRecurringAppts | PR_SCHDINFO_DISALLOW_RECURRING_APPTS
PidTagScheduleInfoDontMailDelegates | PR_SCHDINFO_DONT_MAIL_DELEGATES
PidTagScheduleInfoFreeBusy | PR_SCHDINFO_FREEBUSY
PidTagScheduleInfoFreeBusyAway | PR_SCHDINFO_FREEBUSY_OOF
PidTagScheduleInfoFreeBusyBusy | PR_SCHDINFO_FREEBUSY_BUSY
PidTagScheduleInfoFreeBusyMerged | PR_SCHDINFO_FREEBUSY_MERGED
PidTagScheduleInfoFreeBusyTentative | PR_SCHDINFO_FREEBUSY_TENTATIVE
PidTagScheduleInfoMonthsAway | PR_SCHDINFO_MONTHS_OOF
PidTagScheduleInfoMonthsBusy | PR_SCHDINFO_MONTHS_BUSY
PidTagScheduleInfoMonthsMerged | PR_SCHDINFO_MONTHS_MERGED
PidTagScheduleInfoMonthsTentative | PR_SCHDINFO_MONTHS_TENTATIVE
PidTagScheduleInfoResourceType | PR_SCHDINFO_RESOURCE_TYPE
PidTagSearch | PR_SEARCH
PidTagSearchAttachments | PR_SEARCH_ATTACHMENTS_W
PidTagSearchFolderDefinition | PR_WB_SF_DEFINITION
PidTagSearchFolderEfpFlags | PR_WB_SF_EFP_FLAGS
PidTagSearchFolderExpiration | PR_WB_SF_EXPIRATION
PidTagSearchFolderId | PR_WB_SF_ID
PidTagSearchFolderLastUsed | PR_WB_SF_LAST_USED
PidTagSearchFolderStorageType | PR_WB_SF_STORAGE_TYPE
PidTagSearchFolderTag | PR_WB_SF_TAG
PidTagSearchFolderTemplateId | PR_WB_SF_TEMPLATE_ID
PidTagSearchRecipientEmailBcc | PR_SEARCH_RECIP_EMAIL_BCC_W
PidTagSearchRecipientEmailCc | PR_SEARCH_RECIP_EMAIL_CC_W
PidTagSearchRecipientEmailTo | PR_SEARCH_RECIP_EMAIL_TO_W
PidTagSearchKey | PR_SEARCH_KEY
PidTagSelectable | PR_SELECTABLE
PidTagSenderAddressType | PR_SENDER_ADDRTYPE, PR_SENDER_ADDRTYPE_A, PR_SENDER_ADDRTYPE_W
PidTagSenderEmailAddress | PR_SENDER_EMAIL_ADDRESS, PR_SENDER_EMAIL_ADDRESS_A, PR_SENDER_EMAIL_ADDRESS_W
PidTagSenderEntryId | PR_SENDER_ENTRYID
PidTagSenderName | PR_SENDER_NAME, PR_SENDER_NAME_A, PR_SENDER_NAME_W
PidTagSenderSearchKey | PR_SENDER_SEARCH_KEY
PidTagSenderSmtpAddress | PR_SENDER_SMTP_ADDRESS, PR_SENDER_SMTP_ADDRESS_A, PR_SENDER_SMTP_ADDRESS_W
PidTagSendInternetEncoding | PR_SEND_INTERNET_ENCODING
PidTagSendRichInfo | PR_SEND_RICH_INFO
PidTagSensitivity | PR_SENSITIVITY
PidTagSentMailEntryId | PR_SENTMAIL_ENTRYID
PidTagSentRepresentingAddressType | PR_SENT_REPRESENTING_ADDRTYPE, PR_SENT_REPRESENTING_ADDRTYPE_A, PR_SENT_REPRESENTING_ADDRTYPE_W
PidTagSentRepresentingEmailAddress | PR_SENT_REPRESENTING_EMAIL_ADDRESS, PR_SENT_REPRESENTING_EMAIL_ADDRESS_A, PR_SENT_REPRESENTING_EMAIL_ADDRESS_W
PidTagSentRepresentingEntryId | PR_SENT_REPRESENTING_ENTRYID
PidTagSentRepresentingName | PR_SENT_REPRESENTING_NAME, PR_SENT_REPRESENTING_NAME_A, PR_SENT_REPRESENTING_NAME_W
PidTagSentRepresentingSearchKey | PR_SENT_REPRESENTING_SEARCH_KEY
PidTagSentRepresentingSmtpAddress | PR_SENT_REPRESENTING_SMTP_ADDRESS, PR_SENT_REPRESENTING_SMTP_ADDRESS_A, PR_SENT_REPRESENTING_SMTP_ADDRESS_W
PidTagServiceDeleteFiles | PR_SERVICE_DELETE_FILES, PR_SERVICE_DELETE_FILES_A, PR_SERVICE_DELETE_FILES_W
PidTagServiceDllName | PR_SERVICE_DLL_NAME, PR_SERVICE_DLL_NAME_A, PR_SERVICE_DLL_NAME_W
PidTagServiceEntryName | PR_SERVICE_ENTRY_NAME
PidTagServiceExtraUids | PR_SERVICE_EXTRA_UIDS
PidTagServiceInstallId | PR_SERVICE_INSTALL_ID, PR_SERVICE_INSTALL_ID_A, PR_SERVICE_INSTALL_ID_W
PidTagServiceName | PR_SERVICE_NAME, PR_SERVICE_NAME_A, PR_SERVICE_NAME_W
PidTagServices | PR_SERVICES
PidTagServiceSupportFiles | PR_SERVICE_SUPPORT_FILES, PR_SERVICE_SUPPORT_FILES_A, PR_SERVICE_SUPPORT_FILES_W
PidTagServiceUid | PR_SERVICE_UID
PidTagSmtpAddress | PR_SMTP_ADDRESS, PR_SMTP_ADDRESS_A, PR_SMTP_ADDRESS_W
PidTagSpoolerStatus | PR_SPOOLER_STATUS
PidTagSpouseName | PR_SPOUSE_NAME, PR_SPOUSE_NAME_A, PR_SPOUSE_NAME_W
PidTagStartDate | PR_START_DATE
PidTagStateOrProvince | PR_STATE_OR_PROVINCE, PR_STATE_OR_PROVINCE_A, PR_STATE_OR_PROVINCE_W, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_A, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_W
PidTagStatus | PR_STATUS
PidTagStatusCode | PR_STATUS_CODE
PidTagStatusString | PR_STATUS_STRING, PR_STATUS_STRING_A, PR_STATUS_STRING_W
PidTagStoreEntryId | PR_STORE_ENTRYID
PidTagStoreEntryIdEmsmdbV1 Canonical Property | PR_STORE_ENTRYID_EMSMDB_V1
PidTagStoreProvider | PR_MDB_PROVIDER
PidTagStoreProviders | PR_STORE_PROVIDERS
PidTagStoreRecordKey | PR_STORE_RECORD_KEY
PidTagStoreState | PR_STORE_STATE
PidTagStoreSupportMask | PR_STORE_SUPPORT_MASK
PidTagStoreUnicodeMask | PR_STORE_UNICODE_MASK
PidTagStreetAddress | PR_STREET_ADDRESS, PR_STREET_ADDRESS_A, PR_STREET_ADDRESS_W, PR_BUSINESS_ADDRESS_STREET, PR_BUSINESS_ADDRESS_STREET_A, PR_BUSINESS_ADDRESS_STREET_W
PidTagSubfolders | PR_SUBFOLDERS
PidTagSubject | PR_SUBJECT, PR_SUBJECT_A, PR_SUBJECT_W
PidTagSubjectMessageId | PR_SUBJECT_IPM
PidTagSubjectPrefix | PR_SUBJECT_PREFIX, PR_SUBJECT_PREFIX_A, PR_SUBJECT_PREFIX_W
PidTagSubmitFlags | PR_SUBMIT_FLAGS
PidTagSupplementaryInfo | PR_SUPPLEMENTARY_INFO, PR_SUPPLEMENTARY_INFO_A, PR_SUPPLEMENTARY_INFO_W
PidTagSurname | PR_SURNAME, PR_SURNAME_A, PR_SURNAME_W
PidTagSwappedToDoData | PR_SWAPPED_TODO_DATA
PidTagSwappedToDoStore | PR_SWAPPED_TODO_STORE
PidTagTelecommunicationsDeviceForDeafTelephoneNumber | PR_TTYTDD_PHONE_NUMBER, PR_TTYTDD_PHONE_NUMBER_A, PR_TTYTDD_PHONE_NUMBER_W
PidTagTelexNumber | PR_TELEX_NUMBER, PR_TELEX_NUMBER_A, PR_TELEX_NUMBER_W
PidTagTemplateid | PR_TEMPLATEID
PidTagTextAttachmentCharset | None
PidTagTitle | PR_TITLE, PR_TITLE_A, PR_TITLE_W
PidTagTnefCorrelationKey | PR_TNEF_CORRELATION_KEY
PidTagTnefUnprocessedProps | PR_TNEF_UNPROCESSED_PROPS
PidTagToDoItemFlags | PR_TODO_ITEM_FLAGS
PidTagTransmittableDisplayName | PR_TRANSMITABLE_DISPLAY_NAME, PR_TRANSMITABLE_DISPLAY_NAME_A, PR_TRANSMITABLE_DISPLAY_NAME_W
PidTagTransportKey | PR_TRANSPORT_KEY
PidTagTransportMessageHeaders | PR_TRANSPORT_MESSAGE_HEADERS, PR_TRANSPORT_MESSAGE_HEADERS_A, PR_TRANSPORT_MESSAGE_HEADERS_W
PidTagTransportProviders | PR_TRANSPORT_PROVIDERS
PidTagTtyTddPhoneNumber | PR_TTYTDD_PHONE_NUMBER
PidTagTypeOfX400User | PR_TYPE_OF_MTS_USER
PidTagUrlComponentName | PR_URL_COMP_NAME, PR_URL_COMP_NAME_A, PR_URL_COMP_NAME_W
PidTagUserCertificate | PR_USER_CERTIFICATE
PidTagUserX509Certificate | PR_USER_X509_CERTIFICATE
PidTagValidFolderMask | PR_VALID_FOLDER_MASK
PidTagViewDescriptorName | PR_VD_NAME, PR_VD_NAME_W
PidTagViewDescriptorVersion | PR_VD_VERSION
PidTagViewsEntryId | PR_VIEWS_ENTRYID
PidTagWeddingAnniversary | PR_WEDDING_ANNIVERSARY
PidTagWizardNoPabPage | PR_WIZARD_NO_PAB_PAGE
PidTagWizardNoPstPage | PR_WIZARD_NO_PST_PAGE
PidTagX400ContentType | PR_X400_CONTENT_TYPE
PidTagXCoordinate | PR_XPOS
PidTagYCoordinate | PR_YPOS


Mapping MAPI Names to Canonical Property Names

 Copy code hover
[image]

Mapping MAPI Names to Canonical Property Names
Send feedback

Published: July 16, 2012

This topic maps each MAPI property to the corresponding canonical property name. The topic contains three tables: a table for named properties with numerical identifiers, a second table for named properties with string identifiers, and a third table for tagged properties.

For more information about how canonical properties relate to MAPI properties, see MAPI Canonical Properties.

Named Properties with Numerical Identifiers

Actual Named Property | Canonical Property Name
dispidABPArrayType | PidLidAddressBookProviderArrayType
dispidABPEmailList | PidLidAddressBookProviderEmailList
dispidAddressCountryCode | PidLidAddressCountryCode
dispidAgingDontAgeMe | PidLidAgingDontAgeMe
dispidAllAttendeesString | PidLidAllAttendeesString
dispidAnniversaryEventEID | PidLidAnniversaryEventEntryId
dispidApptAuxFlags | PidLidAppointmentAuxiliaryFlags
dispidApptColor | PidLidAppointmentColor
dispidApptCounterProposal | PidLidAppointmentCounterProposal
dispidApptDuration | PidLidAppointmentDuration
dispidApptEndWhole | PidLidAppointmentEndWhole
dispidApptLastSequence | PidLidAppointmentLastSequence
dispidApptMessageClass | PidLidAppointmentMessageClass
dispidApptNotAllowPropose | PidLidAppointmentNotAllowPropose
dispidApptProposalNum | PidLidAppointmentProposalNumber
dispidApptProposedDuration | PidLidAppointmentProposedDuration
dispidApptProposedEndWhole | PidLidAppointmentProposedEndWhole
dispidApptProposedStartWhole | PidLidAppointmentProposedStartWhole
dispidApptRecur | PidLidAppointmentRecur
dispidApptReplyName | PidLidAppointmentReplyName
dispidApptReplyTime | PidLidAppointmentReplyTime
dispidApptSeqTime | PidLidAppointmentSequenceTime
dispidApptSequence | PidLidAppointmentSequence
dispidApptStartWhole | PidLidAppointmentStartWhole
dispidApptStateFlags | PidLidAppointmentStateFlags
dispidApptSubType | PidLidAppointmentSubType
dispidApptTZDefEndDisplay | PidLidAppointmentTimeZoneDefinitionEndDisplay
dispidApptTZDefRecur | PidLidAppointmentTimeZoneDefinitionRecur
dispidApptTZDefStartDisplay | PidLidAppointmentTimeZoneDefinitionStartDisplay
dispidApptUnsendableRecips | PidLidAppointmentUnsendableRecipients
dispidAutoFillLocation | PidLidAutoFillLocation
dispidAutoLog | PidLidAutoLog
dispidBCCardPicture | PidLidBusinessCardCardPicture
dispidBCDisplayDefinition | PidLidBusinessCardDisplayDefinition
dispidBilling | PidLidBilling
dispidBirthdayEventEID | PidLidBirthdayEventEntryId
dispidBusyStatus | PidLidBusyStatus
dispidCategories | PidLidCategories
dispidCCAttendeesString | PidLidCcAttendeesString
dispidChangeHighlight | PidLidChangeHighlight
dispidClassDesc | PidLidClassificationDescription
dispidClassGuid | PidLidClassificationGuid
dispidClassification | PidLidClassification
dispidClassified | PidLidClassified
dispidClassKeep | PidLidClassificationKeep
dispidCleanGlobalObjId | PidLidCleanGlobalObjectId
dispidClipEnd | PidLidClipEnd
dispidClipStart | PidLidClipStart
dispidCommonEnd | PidLidCommonEnd
dispidCommonStart | PidLidCommonStart
dispidCompanies | PidLidCompanies
dispidContactCharSet | PidLidContactCharacterSet
dispidContactItemData | PidLidContactItemData
dispidContactLinkEntry | PidLidContactLinkEntry
dispidContactLinkName | PidLidContactLinkName
dispidContactLinkSearchKey | PidLidContactLinkSearchKey
dispidContacts | PidLidContacts
dispidContactUserField1 | PidLidContactUserField1
dispidContactUserField2 | PidLidContactUserField2
dispidContactUserField3 | PidLidContactUserField3
dispidContactUserField4 | PidLidContactUserField4
dispidCurrentVersion | PidLidCurrentVersion
dispidCurrentVersionName | PidLidCurrentVersionName
dispidCustomFlag | PidLidCustomFlag
dispidDLChecksum | PidLidDistributionListChecksum
dispidDLMembers | PidLidDistributionListMembers
dispidDLName | PidLidDistributionListName
dispidDLOneOffMembers | PidLidDistributionListOneOffMembers
dispidEmail1AddrType | PidLidEmail1AddressType
dispidEmail1DisplayName | PidLidEmail1DisplayName
dispidEmail1EmailAddress | PidLidEmail1EmailAddress
dispidEmail1OriginalDisplayName | PidLidEmail1OriginalDisplayName
dispidEmail1OriginalEntryID | PidLidEmail1OriginalEntryId
dispidEmail2AddrType | PidLidEmail2AddressType
dispidEmail2DisplayName | PidLidEmail2DisplayName
dispidEmail2EmailAddress | PidLidEmail2EmailAddress
dispidEmail2OriginalDisplayName | PidLidEmail2OriginalDisplayName
dispidEmail2OriginalEntryID | PidLidEmail2OriginalEntryId
dispidEmail3AddrType | PidLidEmail3AddressType
dispidEmail3DisplayName | PidLidEmail3DisplayName
dispidEmail3EmailAddress | PidLidEmail3EmailAddress
dispidEmail3OriginalDisplayName | PidLidEmail3OriginalDisplayName
dispidEmail3OriginalEntryID | PidLidEmail3OriginalEntryId
dispidEMSAbX509Cert | PidLidUserX509Certificate
dispidExceptionReplaceTime | PidLidExceptionReplaceTime
dispidFax1AddrType | PidLidFax1AddressType
dispidFax1DisplayName | PidLidFax1DisplayName
dispidFax1EmailAddress | PidLidFax1EmailAddress
dispidFax1EmailType | PidLidFax1EmailType
dispidFax1EntryID | PidLidFax1EntryId
dispidFax1OriginalDisplayName | PidLidFax1OriginalDisplayName
dispidFax1OriginalEntryID | PidLidFax1OriginalEntryId
dispidFax1RTF | PidLidFax1RichTextFormat
dispidFax2AddrType | PidLidFax2AddressType
dispidFax2DisplayName | PidLidFax2DisplayName
dispidFax2EmailAddress | PidLidFax2EmailAddress
dispidFax2EmailType | PidLidFax2EmailType
dispidFax2EntryID | PidLidFax2EntryId
dispidFax2OriginalDisplayName | PidLidFax2OriginalDisplayName
dispidFax2OriginalEntryID | PidLidFax2OriginalEntryId
dispidFax2RTF | PidLidFax2RichTextFormat
dispidFax3AddrType | PidLidFax3AddressType
dispidFax3DisplayName | PidLidFax3DisplayName
dispidFax3EmailAddress | PidLidFax3EmailAddress
dispidFax3EmailType | PidLidFax3EmailType
dispidFax3EntryID | PidLidFax3EntryId
dispidFax3OriginalDisplayName | PidLidFax3OriginalDisplayName
dispidFax3OriginalEntryID | PidLidFax3OriginalEntryId
dispidFax3RTF | PidLidFax3RichTextFormat
dispidFExceptionalAttendees | PidLidFExceptionalAttendees
dispidFExceptionalBody | PidLidFExceptionalBody
dispidFileUnder | PidLidFileUnder
dispidFileUnderId | PidLidFileUnderId
dispidFileUnderList | PidLidFileUnderList
dispidFInvited | PidLidFInvited
dispidFlagStringEnum | PidLidFlagString
dispidFreeBusyLocation | PidLidFreeBusyLocation
dispidFShouldTNEF | PidLidFShouldTNEF
dispidFwrdInstance | PidLidForwardInstance
dispidHasPicture | PidLidHasPicture
dispidHeaderItem | PidLidHeaderItem
dispidHomeAddress | PidLidHomeAddress
dispidHomeAddressCountryCode | PidLidHomeAddressCountryCode
dispidHTML | PidLidHtml
dispidImapDeleted | PidLidImapDeleted
dispidImgAttchmtsCompressLevel | PidLidImageAttachmentsCompressionLevel
dispidInetAcctName | PidLidInternetAccountName
dispidInetAcctStamp | PidLidInternetAccountStamp
dispidInstMsg | PidLidInstantMessagingAddress
dispidIntendedBusyStatus | PidLidIntendedBusyStatus
dispidIsIPFax | PidLidIsInterpersonalFax
dispidLinkedTaskItems | PidLidLinkedTaskItems
dispidLocation | PidLidLocation
dispidLogDocPosted | PidLidLogDocumentPosted
dispidLogDocPrinted | PidLidLogDocumentPrinted
dispidLogDocRouted | PidLidLogDocumentRouted
dispidLogDocSaved | PidLidLogDocumentSaved
dispidLogDuration | PidLidLogDuration
dispidLogEnd | PidLidLogEnd
dispidLogFlags | PidLidLogFlags
dispidLogStart | PidLidLogStart
dispidLogType | PidLidLogType
dispidLogTypeDesc | PidLidLogTypeDesc
dispidMeetingType | PidLidMeetingType
dispidMileage | PidLidMileage
dispidMWSURL | PidLidMeetingWorkspaceUrl
dispidNonSendableBCC | PidLidNonSendableBcc
dispidNonSendableCC | PidLidNonSendableCc
dispidNonSendableTo | PidLidNonSendableTo
dispidNonSendBccTrackStatus | PidLidNonSendBccTrackStatus
dispidNonSendCcTrackStatus | PidLidNonSendCcTrackStatus
dispidNonSendToTrackStatus | PidLidNonSendToTrackStatus
dispidNoteColor | PidLidNoteColor
dispidNoteHeight | PidLidNoteHeight
dispidNoteWidth | PidLidNoteWidth
dispidNoteX | PidLidNoteX
dispidNoteY | PidLidNoteY
dispidOfflineStatus | PidLidOfflineStatus
dispidOldLocation | PidLidOldLocation
dispidOldWhenEndWhole | PidLidOldWhenEndWhole
dispidOldWhenStartWhole | PidLidOldWhenStartWhole
dispidOrigStoreEid | PidLidOriginalStoreEntryId
dispidOtherAddress | PidLidOtherAddress
dispidOtherAddressCountryCode | PidLidOtherAddressCountryCode
dispidPercentComplete | PidLidPercentComplete
dispidPostalAddressId | PidLidPostalAddressId
dispidPostRssChannel | PidLidPostRssChannel
dispidPostRssChannelLink | PidLidPostRssChannelLink
dispidPrivate | PidLidPrivate
dispidPropDefStream | PidLidPropertyDefinitionStream
dispidRecallTime | PidLidRecallTime
dispidRecurPattern | PidLidRecurrencePattern
dispidRecurring | PidLidRecurring
dispidRecurType | PidLidRecurrenceType
dispidReferenceEID | PidLidReferenceEntryId
dispidReminderDelta | PidLidReminderDelta
dispidReminderFileParam | PidLidReminderFileParameter
dispidReminderNextTime | PidLidReminderSignalTime
dispidReminderOverride | PidLidReminderOverride
dispidReminderPlaySound | PidLidReminderPlaySound
dispidReminderSet | PidLidReminderSet
dispidReminderTime | PidLidReminderTime
dispidRemoteAttachment | PidLidRemoteAttachment
dispidRemoteEID | PidLidRemoteEntryId
dispidRemoteMsgClass | PidLidRemoteMessageClass
dispidRemoteSearchKey | PidLidRemoteSearchKey
dispidRemoteXferSize | PidLidRemoteTransferSize
dispidRemoteXferTime | PidLidRemoteTransferTime
dispidRemoteXP | PidLidRemoteTransport
dispidRequest | PidLidFlagRequest
dispidResendTime | PidLidResendTime
dispidResponseStatus | PidLidResponseStatus
dispidSendMtgAsICAL | PidLidSendMeetingAsIcal
dispidSharingCaps | PidLidSharingCapabilities
dispidSharingConfigUrl | PidLidSharingConfigurationUrl
dispidSharingFlavor | PidLidSharingFlavor
dispidSharingInitiatorEid | PidLidSharingInitiatorEntryId
dispidSharingInitiatorName | PidLidSharingInitiatorName
dispidSharingInitiatorSmtp | PidLidSharingInitiatorSmtp
dispidSharingLocalType | PidLidSharingLocalType
dispidSharingProviderGuid | PidLidSharingProviderGuid
dispidSharingProviderName | PidLidSharingProviderName
dispidSharingProviderUrl | PidLidSharingProviderUrl
dispidSharingRemoteName | PidLidSharingRemoteName
dispidSharingRemoteStoreUid | PidLidSharingRemoteStoreUid
dispidSharingRemoteType | PidLidSharingRemoteType
dispidSharingRemoteUid | PidLidSharingRemoteUid
dispidSharingResponseTime | PidLidSharingResponseTime
dispidSharingResponseType | PidLidSharingResponseType
dispidSideEffects | PidLidSideEffects
dispidSmartNoAttach | PidLidSmartNoAttach
dispidSniffState | PidLidAutoProcessState
dispidSpamOriginalFolder | PidLidSpamOriginalFolder
dispidTaskAccepted | PidLidTaskAccepted
dispidTaskActualEffort | PidLidTaskActualEffort
dispidTaskComplete | PidLidTaskComplete
dispidTaskDateCompleted | PidLidTaskDateCompleted
dispidTaskDeadOccur | PidLidTaskDeadOccurrence
dispidTaskDelegator | PidLidTaskAssigner
dispidTaskDelegValue | PidLidTaskAcceptanceState
dispidTaskDueDate | PidLidTaskDueDate
dispidTaskEstimatedEffort | PidLidTaskEstimatedEffort
dispidTaskFCreator | PidLidTaskFCreator
dispidTaskFFixOffline | PidLidTaskFFixOffline
dispidTaskFRecur | PidLidTaskFRecurring
dispidTaskGlobalObjId | PidLidTaskGlobalId
dispidTaskHistory | PidLidTaskHistory
dispidTaskLastDelegate | PidLidTaskLastDelegate
dispidTaskLastUpdate | PidLidTaskLastUpdate
dispidTaskLastUser | PidLidTaskLastUser
dispidTaskMode | PidLidTaskMode
dispidTaskMultRecips | PidLidTaskMultipleRecipients
dispidTaskMyDelegators | PidLidTaskAssigners
dispidTaskOrdinal | PidLidTaskOrdinal
dispidTaskOwner | PidLidTaskOwner
dispidTaskOwnership | PidLidTaskOwnership
dispidTaskRecur | PidLidTaskRecurrence
dispidTaskResetReminder | PidLidTaskResetReminder
dispidTaskSOC | PidLidTaskStatusOnComplete
dispidTaskStartDate | PidLidTaskStartDate
dispidTaskState | PidLidTaskState
dispidTaskStatus | PidLidTaskStatus
dispidTaskUpdates | PidLidTaskUpdates
dispidTaskVersion | PidLidTaskVersion
dispidTimeZoneDesc | PidLidTimeZoneDescription
dispidTimeZoneStruct | PidLidTimeZoneStruct
dispidToAttendeesString | PidLidToAttendeesString
dispidToDoOrdinalDate | PidLidToDoOrdinalDate
dispidToDoSubOrdinal | PidLidToDoSubOrdinal
dispidToDoTitle | PidLidToDoTitle
dispidUseTNEF | PidLidUseTnef
dispidValidFlagStringProof | PidLidValidFlagStringProof
dispidVerbResponse | PidLidVerbResponse
dispidVerbStream | PidLidVerbStream
dispidWorkAddress | PidLidWorkAddress
dispidWorkAddressCity | PidLidWorkAddressCity
dispidWorkAddressCountry | PidLidWorkAddressCountry
dispidWorkAddressCountryCode | PidLidWorkAddressCountryCode
dispidWorkAddressPostalCode | PidLidWorkAddressPostalCode
dispidWorkAddressPostOfficeBox | PidLidWorkAddressPostOfficeBox
dispidWorkAddressState | PidLidWorkAddressState
dispidWorkAddressStreet | PidLidWorkAddressStreet
dispidYomiCompanyName | PidLidYomiCompanyName
dispidYomiFirstName | PidLidYomiFirstName
dispidYomiLastName | PidLidYomiLastName
LID_ATTENDEE_CRITICAL_CHANGE | PidLidAttendeeCriticalChange
LID_CALENDAR_TYPE | PidLidCalendarType
LID_GLOBAL_OBJID | PidLidGlobalObjectId
LID_IS_EXCEPTION | PidLidIsException
LID_IS_RECURRING | PidLidIsRecurring
LID_IS_SILENT | PidLidIsSilent
LID_OWNER_CRITICAL_CHANGE | PidLidOwnerCriticalChange
LID_TIME_ZONE | PidLidTimeZone
LID_WHERE | PidLidWhere

Named Properties with String Identifiers

Actual Named Property | Canonical Property Name
Accept-Language | PidNameAcceptLanguage
AppName | PidNameApplicationName
AttachmentMacContentType | PidNameAttachmentMacContentType
AttachmentMacInfo | PidNameAttachmentMacInfo
Author | PidNameAuthor
ByteCount | PidNameByteCount
Category | PidNameCategory
CharCount | PidNameCharacterCount
Comments | PidNameComments
Company | PidNameCompany
Content-Base | PidNameContentBase
Content-Class | PidNameContentClass
Content-Transfer-Encoding | PidNameContentTransferEncoding
Content-Type | PidNameContentType
CreateDtmRo | PidNameCreateDateTimeReadOnly
DRMLicense | PidNameRightsManagementLicense
EditTime | PidNameEditTime
HiddenCount | PidNameHiddenCount
http://schemas.microsoft.com/exchange/junkemailmovestamp | PidNameExchangeJunkEmailMoveStamp
http://schemas.microsoft.com/outlook/phishingstamp | PidNameOutlookPhishingstamp
Keywords | PidNameKeywords
LastAuthor | PidNameLastAuthor
LastPrinted | PidNameLastPrinted
LastSaveDtm | PidNameLastSaveDateTime
LineCount | PidNameLineCount
Manager | PidNameManager
MMClipCount | PidNameMultimediaClipCount
NoteCount | PidNameNoteCount
PageCount | PidNamePageCount
ParCount | PidNameParagraphCount
PresFormat | PidNamePresentationFormat
RevNumber | PidNameRevisionNumber
Security | PidNameSecurity
SlideCount | PidNameSlideCount
Subject | PidNameSubject
Template | PidNameTemplate
Title | PidNameTitle
UMAudioNotes | PidNameAudioNotes
WordCount | PidNameWordCount
X-Sharing-Capabilities | PidNameXSharingCapabilities
X-Sharing-Config-Url | PidNameXSharingConfigUrl
X-Sharing-Flavor | PidNameXSharingFlavor
X-Sharing-Local-Type | PidNameXSharingLocalType
X-Sharing-Provider-Guid | PidNameXSharingProviderGuid
X-Sharing-Provider-Name | PidNameXSharingProviderName
X-Sharing-Provider-Url | PidNameXSharingProviderUrl
X-Sharing-Remote-Name | PidNameXSharingRemoteName
X-Sharing-Remote-Store-Uid | PidNameXSharingRemoteStoreUid
X-Sharing-Remote-Type | PidNameXSharingRemoteType
X-Sharing-Remote-Uid | PidNameXSharingRemoteUid
Xref | PidNameCrossReference

Tagged Properties

Actual Tagged Property | Canonical Property Name
PR_7BIT_DISPLAY_NAME_A | PidTag7BitDisplayName
PR_7BIT_DISPLAY_NAME_W | PidTag7BitDisplayName
PR_7BIT_DISPLAY_NAME | PidTag7BitDisplayName
PR_AB_CHOOSE_DIRECTORY_AUTOMATICALLY | PidTagAddressBookChooseDirectoryAutomatically
PR_AB_DEFAULT_DIR | PidTagAbDefaultDir
PR_AB_PROVIDER_ID | PidTagAbProviderId
PR_AB_PROVIDERS | PidTagAbProviders
PR_AB_SEARCH_PATH_UPDATE | PidTagAbSearchPathUpdate
PR_AB_SEARCH_PATH | PidTagAbSearchPath
PR_ACCESS_LEVEL | PidTagAccessLevel
PR_ACCESS | PidTagAccess
PR_ACCOUNT_A | PidTagAccount
PR_ACCOUNT_W | PidTagAccount
PR_ACCOUNT | PidTagAccount
PR_ACKNOWLEDGEMENT_MODE | PidTagAcknowledgementMode
PR_ACL_TABLE | PidTagAccessControlListTable
PR_ADDITIONAL_REN_ENTRYIDS_EX | PidTagAdditionalRenEntryIdsEx
PR_ADDITIONAL_REN_ENTRYIDS | PidTagAdditionalRenEntryIds
PR_ADDRTYPE_A | PidTagAddressType
PR_ADDRTYPE_W | PidTagAddressType
PR_ADDRTYPE | PidTagAddressType
PR_AGING_GRANULARITY | PidTagAgingGranularity
PR_AGING_PERIOD | PidTagAgingPeriod
PR_ALTERNATE_RECIPIENT_ALLOWED | PidTagAlternateRecipientAllowed
PR_ALTERNATE_RECIPIENT | PidTagAlternateRecipient
PR_ANR_A | PidTagAnr
PR_ANR_W | PidTagAnr
PR_ANR | PidTagAnr
PR_ASSISTANT_A | PidTagAssistant
PR_ASSISTANT_W | PidTagAssistant
PR_ASSISTANT | PidTagAssistant
PR_ASSISTANT_TELEPHONE_NUMBER_A | PidTagAssistantTelephoneNumber
PR_ASSISTANT_TELEPHONE_NUMBER_W | PidTagAssistantTelephoneNumber
PR_ASSISTANT_TELEPHONE_NUMBER | PidTagAssistantTelephoneNumber
PR_ASSOC_CONTENT_COUNT | PidTagAssociatedContentCount
PR_ASSOCIATED_SHARING_PROVIDER | PidTagAssociatedSharingProvider
PR_ATTACH_ADDITIONAL_INFO | PidTagAttachAdditionalInformation
PR_ATTACH_CONTENT_BASE_A | PidTagAttachContentBase
PR_ATTACH_CONTENT_BASE_W | PidTagAttachContentBase
PR_ATTACH_CONTENT_BASE | PidTagAttachContentBase
PR_ATTACH_CONTENT_ID_A | PidTagAttachContentId
PR_ATTACH_CONTENT_ID_W | PidTagAttachContentId
PR_ATTACH_CONTENT_ID | PidTagAttachContentId
PR_ATTACH_CONTENT_LOCATION_A | PidTagAttachContentLocation
PR_ATTACH_CONTENT_LOCATION_W | PidTagAttachContentLocation
PR_ATTACH_CONTENT_LOCATION | PidTagAttachContentLocation
PR_ATTACH_DATA_BIN | PidTagAttachDataBinary
PR_ATTACH_DATA_OBJ | PidTagAttachDataObject
PR_ATTACH_ENCODING | PidTagAttachEncoding
PR_ATTACH_EXTENSION_A | PidTagAttachExtension
PR_ATTACH_EXTENSION_W | PidTagAttachExtension
PR_ATTACH_EXTENSION | PidTagAttachExtension
PR_ATTACH_FILENAME_A | PidTagAttachFilename
PR_ATTACH_FILENAME_W | PidTagAttachFilename
PR_ATTACH_FILENAME | PidTagAttachFilename
PR_ATTACH_FLAGS | PidTagAttachFlags
PR_ATTACH_LONG_FILENAME_A | PidTagAttachLongFilename
PR_ATTACH_LONG_FILENAME_W | PidTagAttachLongFilename
PR_ATTACH_LONG_FILENAME | PidTagAttachLongFilename
PR_ATTACH_LONG_PATHNAME_A | PidTagAttachLongPathname
PR_ATTACH_LONG_PATHNAME_W | PidTagAttachLongPathname
PR_ATTACH_LONG_PATHNAME | PidTagAttachLongPathname
PR_ATTACH_METHOD | PidTagAttachMethod
PR_ATTACH_MIME_SEQUENCE | PidTagAttachMimeSequence
PR_ATTACH_MIME_TAG_A | PidTagAttachMimeTag
PR_ATTACH_MIME_TAG_W | PidTagAttachMimeTag
PR_ATTACH_MIME_TAG | PidTagAttachMimeTag
PR_ATTACH_NUM | PidTagAttachNumber
PR_ATTACH_PATHNAME_A | PidTagAttachPathname
PR_ATTACH_PATHNAME_W | PidTagAttachPathname
PR_ATTACH_PATHNAME | PidTagAttachPathname
PR_ATTACH_PAYLOAD_CLASS_A | PidTagAttachPayloadClass
PR_ATTACH_PAYLOAD_CLASS_W | PidTagAttachPayloadClass
PR_ATTACH_PAYLOAD_CLASS | PidTagAttachPayloadClass
PR_ATTACH_PAYLOAD_PROV_GUID_STR_A | PidTagAttachPayloadProviderGuidString
PR_ATTACH_PAYLOAD_PROV_GUID_STR_W | PidTagAttachPayloadProviderGuidString
PR_ATTACH_PAYLOAD_PROV_GUID_STR | PidTagAttachPayloadProviderGuidString
PR_ATTACH_RENDERING | PidTagAttachRendering
PR_ATTACH_SIZE | PidTagAttachSize
PR_ATTACH_TAG | PidTagAttachTag
PR_ATTACH_TRANSPORT_NAME_A | PidTagAttachTransportName
PR_ATTACH_TRANSPORT_NAME_W | PidTagAttachTransportName
PR_ATTACH_TRANSPORT_NAME | PidTagAttachTransportName
PR_ATTACHMENT_CONTACTPHOTO | PidTagAttachmentContactPhoto
PR_ATTACHMENT_FLAGS | PidTagAttachmentFlags
PR_ATTACHMENT_HIDDEN | PidTagAttachmentHidden
PR_ATTACHMENT_LINKID | PidTagAttachmentLinkId
PR_AUTHORIZING_USERS | PidTagAuthorizingUsers
PR_AUTO_FORWARD_COMMENT_A | PidTagAutoForwardComment
PR_AUTO_FORWARD_COMMENT_W | PidTagAutoForwardComment
PR_AUTO_FORWARD_COMMENT | PidTagAutoForwardComment
PR_AUTO_FORWARDED | PidTagAutoForwarded
PR_BIRTHDAY | PidTagBirthday
PR_BODY_A | PidTagBody
PR_BODY_CONTENT_LOCATION_A | PidTagBodyContentLocation
PR_BODY_CONTENT_LOCATION_W | PidTagBodyContentLocation
PR_BODY_CONTENT_LOCATION | PidTagBodyContentLocation
PR_BODY_CRC | PidTagBodyCrc
PR_BODY_HTML_A | PidTagBodyHtml
PR_BODY_HTML_W | PidTagBodyHtml
PR_BODY_HTML | PidTagBodyHtml
PR_BODY_W | PidTagBody
PR_BODY | PidTagBody
PR_BUSINESS_ADDRESS_COUNTRY_A | PidTagCountry
PR_BUSINESS_ADDRESS_COUNTRY_W | PidTagCountry
PR_BUSINESS_ADDRESS_COUNTRY | PidTagCountry
PR_BUSINESS_ADDRESS_LOCALITY_A | PidTagLocality
PR_BUSINESS_ADDRESS_LOCALITY_W | PidTagLocality
PR_BUSINESS_ADDRESS_LOCALITY | PidTagLocality
PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_A | PidTagPostOfficeBox
PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_W | PidTagPostOfficeBox
PR_BUSINESS_ADDRESS_POST_OFFICE_BOX | PidTagPostOfficeBox
PR_BUSINESS_ADDRESS_POSTAL_CODE_A | PidTagPostalCode
PR_BUSINESS_ADDRESS_POSTAL_CODE_W | PidTagPostalCode
PR_BUSINESS_ADDRESS_POSTAL_CODE | PidTagPostalCode
PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_A | PidTagStateOrProvince
PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_W | PidTagStateOrProvince
PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE | PidTagStateOrProvince
PR_BUSINESS_ADDRESS_STREET_A | PidTagStreetAddress
PR_BUSINESS_ADDRESS_STREET_W | PidTagStreetAddress
PR_BUSINESS_ADDRESS_STREET | PidTagStreetAddress
PR_BUSINESS_FAX_NUMBER_A | PidTagBusinessFaxNumber
PR_BUSINESS_FAX_NUMBER_W | PidTagBusinessFaxNumber
PR_BUSINESS_FAX_NUMBER | PidTagBusinessFaxNumber
PR_BUSINESS_HOME_PAGE_A | PidTagBusinessHomePage
PR_BUSINESS_HOME_PAGE_W | PidTagBusinessHomePage
PR_BUSINESS_HOME_PAGE | PidTagBusinessHomePage
PR_BUSINESS_TELEPHONE_NUMBER_A | PidTagBusinessTelephoneNumber
PR_BUSINESS_TELEPHONE_NUMBER_W | PidTagBusinessTelephoneNumber
PR_BUSINESS_TELEPHONE_NUMBER | PidTagBusinessTelephoneNumber
PR_BUSINESS2_TELEPHONE_NUMBER_A_MV | PidTagBusiness2TelephoneNumbers
PR_BUSINESS2_TELEPHONE_NUMBER_A | PidTagBusiness2TelephoneNumber
PR_BUSINESS2_TELEPHONE_NUMBER_W | PidTagBusiness2TelephoneNumber
PR_BUSINESS2_TELEPHONE_NUMBER | PidTagBusiness2TelephoneNumber
PR_CALLBACK_TELEPHONE_NUMBER_A | PidTagCallbackTelephoneNumber
PR_CALLBACK_TELEPHONE_NUMBER_W | PidTagCallbackTelephoneNumber
PR_CALLBACK_TELEPHONE_NUMBER | PidTagCallbackTelephoneNumber
PR_CAR_TELEPHONE_NUMBER_A | PidTagCarTelephoneNumber
PR_CAR_TELEPHONE_NUMBER_W | PidTagCarTelephoneNumber
PR_CAR_TELEPHONE_NUMBER | PidTagCarTelephoneNumber
PR_CELLULAR_TELEPHONE_NUMBER | PidTagMobileTelephoneNumber
PR_CELLULAR_TELEPHONE_NUMBER_A | PidTagMobileTelephoneNumber
PR_CELLULAR_TELEPHONE_NUMBER_W | PidTagMobileTelephoneNumber
PR_CHILDRENS_NAMES_A | PidTagChildrensNames
PR_CHILDRENS_NAMES_W | PidTagChildrensNames
PR_CHILDRENS_NAMES | PidTagChildrensNames
PR_CLIENT_SUBMIT_TIME | PidTagClientSubmitTime
PR_COMMENT_A | PidTagComment
PR_COMMENT_W | PidTagComment
PR_COMMENT | PidTagComment
PR_COMMON_VIEWS_ENTRYID | PidTagCommonViewsEntryId
PR_COMPANY_MAIN_PHONE_NUMBER_A | PidTagCompanyMainTelephoneNumber
PR_COMPANY_MAIN_PHONE_NUMBER_W | PidTagCompanyMainTelephoneNumber
PR_COMPANY_MAIN_PHONE_NUMBER | PidTagCompanyMainTelephoneNumber
PR_COMPANY_NAME_A | PidTagCompanyName
PR_COMPANY_NAME_W | PidTagCompanyName
PR_COMPANY_NAME | PidTagCompanyName
PR_COMPUTER_NETWORK_NAME_A | PidTagComputerNetworkName
PR_COMPUTER_NETWORK_NAME_W | PidTagComputerNetworkName
PR_COMPUTER_NETWORK_NAME | PidTagComputerNetworkName
PR_CONFLICT_ENTRYID | PidTagConflictEntryId
PR_CONFLICT_ITEMS | PidTagConflictItems
PR_CONTAB_DISPLAY_NAMES | PidTagContactAddressBookDisplayNames
PR_CONTAB_FOLDER_ENTRYID | PidTagContactAddressBookFolderEntryId
PR_CONTAB_FOLDER_ENTRYIDS | PidTagContactAddressBookFolderEntryIds
PR_CONTAB_FOLDER_NAME_W | PidTagContactAddressBookFolderName
PR_CONTAB_FOLDER_NAME | PidTagContactAddressBookFolderName
PR_CONTAB_FOLDER_NAMES | PidTagContactAddressBookFolderNames
PR_CONTAB_MULTI_ADDR_FLAG | PidTagContactAddressBookMultipleAddressFlag
PR_CONTAB_MULTI_ADDR_FLAGS | PidTagContactAddressBookMultipleAddressFlags
PR_CONTAB_SORT_FLAG | PidTagContactAddressBookSortFlag
PR_CONTAB_STORE_ENTRYIDS | PidTagContactAddressBookStoreEntryIds
PR_CONTAB_STORE_NAME_W | PidTagContactAddressBookStoreName
PR_CONTAB_STORE_NAME | PidTagContactAddressBookStoreName
PR_CONTAB_STORE_NAMES | PidTagContactAddressBookStoreNames
PR_CONTAB_STORE_SUPPORT_MASK | PidTagContactAddressBookStoreSupportMask
PR_CONTAB_STORE_SUPPORT_MASKS | PidTagContactAddressBookStoreSupportMasks
PR_CONTAB_UID | PidTagContactAddressBookUid
PR_CONTACT_ADDRTYPES_A | PidTagContactAddressTypes
PR_CONTACT_ADDRTYPES_W | PidTagContactAddressTypes
PR_CONTACT_ADDRTYPES | PidTagContactAddressTypes
PR_CONTACT_VERSION | PidTagContactVersion
PR_CONTAINER_CLASS_A | PidTagContainerClass
PR_CONTAINER_CLASS_W | PidTagContainerClass
PR_CONTAINER_CLASS | PidTagContainerClass
PR_CONTAINER_CONTENTS | PidTagContainerContents
PR_CONTAINER_FLAGS | PidTagContainerFlags
PR_CONTAINER_HIERARCHY | PidTagContainerHierarchy
PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID | PidTagContentConfidentialityAlgorithmId
PR_CONTENT_CORRELATOR | PidTagContentCorrelator
PR_CONTENT_COUNT | PidTagContentCount
PR_CONTENT_IDENTIFIER_A | PidTagContentIdentifier
PR_CONTENT_IDENTIFIER_W | PidTagContentIdentifier
PR_CONTENT_IDENTIFIER | PidTagContentIdentifier
PR_CONTENT_INTEGRITY_CHECK | PidTagContentIntegrityCheck
PR_CONTENT_LENGTH | PidTagContentLength
PR_CONTENT_RETURN_REQUESTED | PidTagContentReturnRequested
PR_CONTENT_UNREAD | PidTagContentUnreadCount
PR_CONTROL_FLAGS | PidTagControlFlags
PR_CONTROL_ID | PidTagControlId
PR_CONTROL_STRUCTURE | PidTagControlStructure
PR_CONTROL_TYPE | PidTagControlType
PR_CONVERSATION_INDEX | PidTagConversationIndex
PR_CONVERSATION_KEY | PidTagConversationKey
PR_CONVERSATION_TOPIC_A | PidTagConversationTopic
PR_CONVERSATION_TOPIC_W | PidTagConversationTopic
PR_CONVERSATION_TOPIC | PidTagConversationTopic
PR_CONVERSION_EITS | PidTagConversionEits
PR_CONVERSION_PROHIBITED | PidTagConversionProhibited
PR_CONVERSION_WITH_LOSS_PROHIBITED | PidTagConversionWithLossProhibited
PR_CONVERTED_EITS | PidTagConvertedEits
PR_CORRELATE_MTSID | PidTagCorrelateMtsid
PR_CORRELATE | PidTagCorrelate
PR_COUNTRY_A | PidTagCountry
PR_COUNTRY_W | PidTagCountry
PR_COUNTRY | PidTagCountry
PR_CREATE_TEMPLATES | PidTagCreateTemplates
PR_CREATION_TIME | PidTagCreationTime
PR_CUSTOMER_ID_A | PidTagCustomerId
PR_CUSTOMER_ID_W | PidTagCustomerId
PR_CUSTOMER_ID | PidTagCustomerId
PR_DEF_CREATE_DL | PidTagDefCreateDl
PR_DEF_CREATE_MAILUSER | PidTagDefCreateMailuser
PR_DEF_POST_MSGCLASS | PidTagDefaultPostMessageClass
PR_DEFAULT_PROFILE | PidTagDefaultProfile
PR_DEFAULT_STORE | PidTagDefaultStore
PR_DEFAULT_VIEW_ENTRYID | PidTagDefaultViewEntryId
PR_DEFERRED_DELIVERY_TIME | PidTagDeferredDeliveryTime
PR_DEFERRED_SEND_NUMBER | PidTagDeferredSendNumber
PR_DEFERRED_SEND_TIME | PidTagDeferredSendTime
PR_DEFERRED_SEND_UNITS | PidTagDeferredSendUnits
PR_DELEGATE_FLAGS | PidTagDelegateFlags
PR_DELEGATED_BY_RULE | PidTagDelegatedByRule
PR_DELETE_AFTER_SUBMIT | PidTagDeleteAfterSubmit
PR_DELIVER_TIME | PidTagDeliverTime
PR_DELIVERY_POINT | PidTagDeliveryPoint
PR_DELTAX | PidTagDeltaX
PR_DELTAY | PidTagDeltaY
PR_DEPARTMENT_NAME_A | PidTagDepartmentName
PR_DEPARTMENT_NAME_W | PidTagDepartmentName
PR_DEPARTMENT_NAME | PidTagDepartmentName
PR_DEPTH | PidTagDepth
PR_DETAILS_TABLE | PidTagDetailsTable
PR_DISCARD_REASON | PidTagDiscardReason
PR_DISCLOSURE_OF_RECIPIENTS | PidTagDisclosureOfRecipients
PR_DISCRETE_VALUES | PidTagDiscreteValues
PR_DISPLAY_BCC_A | PidTagDisplayBcc
PR_DISPLAY_BCC_W | PidTagDisplayBcc
PR_DISPLAY_BCC | PidTagDisplayBcc
PR_DISPLAY_CC_A | PidTagDisplayCc
PR_DISPLAY_CC_W | PidTagDisplayCc
PR_DISPLAY_CC | PidTagDisplayCc
PR_DISPLAY_NAME_A | PidTagDisplayName
PR_DISPLAY_NAME_PREFIX_A | PidTagDisplayNamePrefix
PR_DISPLAY_NAME_PREFIX_W | PidTagDisplayNamePrefix
PR_DISPLAY_NAME_PREFIX | PidTagDisplayNamePrefix
PR_DISPLAY_NAME_W | PidTagDisplayName
PR_DISPLAY_NAME | PidTagDisplayName
PR_DISPLAY_TO_A | PidTagDisplayTo
PR_DISPLAY_TO_W | PidTagDisplayTo
PR_DISPLAY_TO | PidTagDisplayTo
PR_DISPLAY_TYPE_EX | PidTagDisplayTypeEx
PR_DISPLAY_TYPE | PidTagDisplayType
PR_DL_EXPANSION_HISTORY | PidTagDistributionListExpansionHistory
PR_DL_EXPANSION_PROHIBITED | PidTagDistributionListExpansionProhibited
PR_EMAIL_ADDRESS_A | PidTagEmailAddress
PR_EMAIL_ADDRESS_W | PidTagEmailAddress
PR_EMAIL_ADDRESS | PidTagEmailAddress
PR_EMS_AB_SERVER | PidTagEmsAbServer
PR_EMS_AB_SERVER_A | PidTagEmsAbServer
PR_EMS_AB_SERVER_W | PidTagEmsAbServer
PR_END_DATE | PidTagEndDate
PR_ENTRYID | PidTagEntryId
PR_EXCEPTION_ENDTIME | PidTagExceptionEndTime
PR_EXCEPTION_REPLACETIME | PidTagExceptionReplaceTime
PR_EXCEPTION_STARTTIME | PidTagExceptionStartTime
PR_EXPIRY_NUMBER | PidTagExpiryNumber
PR_EXPIRY_TIME | PidTagExpiryTime
PR_EXPIRY_UNITS | PidTagExpiryUnits
PR_EXPLICIT_CONVERSION | PidTagExplicitConversion
PR_EXTENDED_FOLDER_FLAGS | PidTagExtendedFolderFlags
PR_EXTENDED_RULE_MSG_ACTIONS | PidTagExtendedRuleMessageActions
PR_EXTENDED_RULE_MSG_CONDITION | PidTagExtendedRuleMessageCondition
PR_EXTENDED_RULE_SIZE_LIMIT | PidTagExtendedRuleSizeLimit
PR_FINDER_ENTRYID | PidTagFinderEntryId
PR_FLAG_COMPLETE_TIME | PidTagFlagCompleteTime
PR_FLAG_STATUS | PidTagFlagStatus
PR_FOLDER_ASSOCIATED_CONTENTS | PidTagFolderAssociatedContents
PR_FOLDER_TYPE | PidTagFolderType
PR_FOLLOWUP_ICON | PidTagFollowupIcon
PR_FORM_CATEGORY_A | PidTagFormCategory
PR_FORM_CATEGORY_SUB_A | PidTagFormCategorySub
PR_FORM_CATEGORY_SUB_W | PidTagFormCategorySub
PR_FORM_CATEGORY_SUB | PidTagFormCategorySub
PR_FORM_CATEGORY_W | PidTagFormCategory
PR_FORM_CATEGORY | PidTagFormCategory
PR_FORM_CLSID | PidTagFormClassId
PR_FORM_CONTACT_NAME_A | PidTagFormContactName
PR_FORM_CONTACT_NAME_W | PidTagFormContactName
PR_FORM_CONTACT_NAME | PidTagFormContactName
PR_FORM_DESIGNER_GUID | PidTagFormDesignerGuid
PR_FORM_DESIGNER_NAME_A | PidTagFormDesignerName
PR_FORM_DESIGNER_NAME_W | PidTagFormDesignerName
PR_FORM_DESIGNER_NAME | PidTagFormDesignerName
PR_FORM_HIDDEN | PidTagFormHidden
PR_FORM_HOST_MAP | PidTagFormHostMap
PR_FORM_MESSAGE_BEHAVIOR | PidTagFormMessageBehavior
PR_FORM_VERSION_A | PidTagFormVersion
PR_FORM_VERSION_W | PidTagFormVersion
PR_FORM_VERSION | PidTagFormVersion
PR_FREEBUSY_COUNT_MONTHS | PidTagFreeBusyCountMonths
PR_FREEBUSY_ENTRYIDS | PidTagFreeBusyEntryIds
PR_FREEBUSY_PUBLISH_END | PidTagFreeBusyPublishEnd
PR_FREEBUSY_PUBLISH_START | PidTagFreeBusyPublishStart
PR_FREEBUSY_RANGE_TIMESTAMP | PidTagFreeBusyRangeTimestamp
PR_FTP_SITE_A | PidTagFtpSite
PR_FTP_SITE_W | PidTagFtpSite
PR_FTP_SITE | PidTagFtpSite
PR_GENDER | PidTagGender
PR_GENERATION_A | PidTagGeneration
PR_GENERATION_W | PidTagGeneration
PR_GENERATION | PidTagGeneration
PR_GIVEN_NAME_A | PidTagGivenName
PR_GIVEN_NAME_W | PidTagGivenName
PR_GIVEN_NAME | PidTagGivenName
PR_GOVERNMENT_ID_NUMBER_A | PidTagGovernmentIdNumber
PR_GOVERNMENT_ID_NUMBER_W | PidTagGovernmentIdNumber
PR_GOVERNMENT_ID_NUMBER | PidTagGovernmentIdNumber
PR_HAS_DAMS | PidTagHasDeferredActionMessages
PR_HASATTACH | PidTagHasAttachments
PR_HOBBIES_A | PidTagHobbies
PR_HOBBIES_W | PidTagHobbies
PR_HOBBIES | PidTagHobbies
PR_HOME_ADDRESS_CITY_A | PidTagHomeAddressCity
PR_HOME_ADDRESS_CITY_W | PidTagHomeAddressCity
PR_HOME_ADDRESS_CITY | PidTagHomeAddressCity
PR_HOME_ADDRESS_COUNTRY_A | PidTagHomeAddressCountry
PR_HOME_ADDRESS_COUNTRY_W | PidTagHomeAddressCountry
PR_HOME_ADDRESS_COUNTRY | PidTagHomeAddressCountry
PR_HOME_ADDRESS_POST_OFFICE_BOX_A | PidTagHomeAddressPostOfficeBox
PR_HOME_ADDRESS_POST_OFFICE_BOX_W | PidTagHomeAddressPostOfficeBox
PR_HOME_ADDRESS_POST_OFFICE_BOX | PidTagHomeAddressPostOfficeBox
PR_HOME_ADDRESS_POSTAL_CODE_A | PidTagHomeAddressPostalCode
PR_HOME_ADDRESS_POSTAL_CODE_W | PidTagHomeAddressPostalCode
PR_HOME_ADDRESS_POSTAL_CODE | PidTagHomeAddressPostalCode
PR_HOME_ADDRESS_STATE_OR_PROVINCE_A | PidTagHomeAddressStateOrProvince
PR_HOME_ADDRESS_STATE_OR_PROVINCE_W | PidTagHomeAddressStateOrProvince
PR_HOME_ADDRESS_STATE_OR_PROVINCE | PidTagHomeAddressStateOrProvince
PR_HOME_ADDRESS_STREET_A | PidTagHomeAddressStreet
PR_HOME_ADDRESS_STREET_W | PidTagHomeAddressStreet
PR_HOME_ADDRESS_STREET | PidTagHomeAddressStreet
PR_HOME_FAX_NUMBER_A | PidTagHomeFaxNumber
PR_HOME_FAX_NUMBER_W | PidTagHomeFaxNumber
PR_HOME_FAX_NUMBER | PidTagHomeFaxNumber
PR_HOME_TELEPHONE_NUMBER_A | PidTagHomeTelephoneNumber
PR_HOME_TELEPHONE_NUMBER_W | PidTagHomeTelephoneNumber
PR_HOME_TELEPHONE_NUMBER | PidTagHomeTelephoneNumber
PR_HOME2_TELEPHONE_NUMBER_A_MV | PidTagHome2TelephoneNumbers
PR_HOME2_TELEPHONE_NUMBER_A | PidTagHome2TelephoneNumber
PR_HOME2_TELEPHONE_NUMBER_W | PidTagHome2TelephoneNumber
PR_HOME2_TELEPHONE_NUMBER | PidTagHome2TelephoneNumber
PR_HTML | PidTagHtml
PR_ICON_INDEX | PidTagIconIndex
PR_ICON | PidTagIcon
PR_IDENTITY_DISPLAY_A | PidTagIdentityDisplay
PR_IDENTITY_DISPLAY_W | PidTagIdentityDisplay
PR_IDENTITY_DISPLAY | PidTagIdentityDisplay
PR_IDENTITY_ENTRYID | PidTagIdentityEntryId
PR_IDENTITY_SEARCH_KEY | PidTagIdentitySearchKey
PR_IMPLICIT_CONVERSION_PROHIBITED | PidTagImplicitConversionProhibited
PR_IMPORTANCE | PidTagImportance
PR_IN_CONFLICT | PidTagInConflict
PR_IN_REPLY_TO_ID_A | PidTagInReplyToId
PR_IN_REPLY_TO_ID_W | PidTagInReplyToId
PR_IN_REPLY_TO_ID | PidTagInReplyToId
PR_INCOMPLETE_COPY | PidTagIncompleteCopy
PR_INETMAIL_OVERRIDE_FORMAT | PidTagInternetMailOverrideFormat
PR_INFERENCES_ENABLED | PidTagInferenceEnabled
PR_INITIAL_DETAILS_PANE | PidTagInitialDetailsPane
PR_INITIALS_A | PidTagInitials
PR_INITIALS_W | PidTagInitials
PR_INITIALS | PidTagInitials
PR_INSTANCE_KEY | PidTagInstanceKey
PR_INTERNET_APPROVED | PidTagInternetApproved
PR_INTERNET_APPROVED_A | PidTagInternetApproved
PR_INTERNET_APPROVED_W | PidTagInternetApproved
PR_INTERNET_ARTICLE_NUMBER | PidTagInternetArticleNumber
PR_INTERNET_CONTROL | PidTagInternetControl
PR_INTERNET_CONTROL_A | PidTagInternetControl
PR_INTERNET_CONTROL_W | PidTagInternetControl
PR_INTERNET_CPID | PidTagInternetCodepage
PR_INTERNET_DISTRIBUTION | PidTagInternetDistribution
PR_INTERNET_DISTRIBUTION_A | PidTagInternetDistribution
PR_INTERNET_DISTRIBUTION_W | PidTagInternetDistribution
PR_INTERNET_FOLLOWUP_TO | PidTagInternetFollowupTo
PR_INTERNET_FOLLOWUP_TO_A | PidTagInternetFollowupTo
PR_INTERNET_FOLLOWUP_TO_W | PidTagInternetFollowupTo
PR_INTERNET_LINES | PidTagInternetLines
PR_INTERNET_MESSAGE_ID_A | PidTagInternetMessageId
PR_INTERNET_MESSAGE_ID_W | PidTagInternetMessageId
PR_INTERNET_MESSAGE_ID | PidTagInternetMessageId
PR_INTERNET_NNTP_PATH | PidTagInternetNntpPath
PR_INTERNET_NNTP_PATH_A | PidTagInternetNntpPath
PR_INTERNET_NNTP_PATH_W | PidTagInternetNntpPath
PR_INTERNET_ORGANIZATION | PidTagInternetOrganization
PR_INTERNET_ORGANIZATION_A | PidTagInternetOrganization
PR_INTERNET_ORGANIZATION_W | PidTagInternetOrganization
PR_INTERNET_REFERENCES_A | PidTagInternetReferences
PR_INTERNET_REFERENCES_W | PidTagInternetReferences
PR_INTERNET_REFERENCES | PidTagInternetReferences
PR_INTERNET_RETURN_PATH_A | PidTagInternetReturnPath
PR_INTERNET_RETURN_PATH_W | PidTagInternetReturnPath
PR_INTERNET_RETURN_PATH | PidTagInternetReturnPath
PR_IPM_APPOINTMENT_ENTRYID | PidTagIpmAppointmentEntryId
PR_IPM_CONTACT_ENTRYID | PidTagIpmContactEntryId
PR_IPM_DRAFTS_ENTRYID | PidTagIpmDraftsEntryId
PR_IPM_JOURNAL_ENTRYID | PidTagIpmJournalEntryId
PR_IPM_NOTE_ENTRYID | PidTagIpmNoteEntryId
PR_IPM_OUTBOX_ENTRYID | PidTagIpmOutboxEntryId
PR_IPM_RETURN_REQUESTED | PidTagIpmReturnRequested
PR_IPM_SENTMAIL_ENTRYID | PidTagIpmSentMailEntryId
PR_IPM_SUBTREE_ENTRYID | PidTagIpmSubtreeEntryId
PR_IPM_TASK_ENTRYID | PidTagIpmTaskEntryId
PR_IPM_WASTEBASKET_ENTRYID | PidTagIpmWastebasketEntryId
PR_ISDN_NUMBER_A | PidTagIsdnNumber
PR_ISDN_NUMBER_W | PidTagIsdnNumber
PR_ISDN_NUMBER | PidTagIsdnNumber
PR_ITEM_TMPFLAGS | PidTagItemTemporaryflags
PR_JUNK_ADD_RECIPS_TO_SSL | PidTagJunkAddRecipientsToSafeSendersList
PR_JUNK_INCLUDE_CONTACTS | PidTagJunkIncludeContacts
PR_JUNK_PERMANENTLY_DELETE | PidTagJunkPermanentlyDelete
PR_JUNK_PHISHING_ENABLE_LINKS | PidTagJunkPhishingEnableLinks
PR_JUNK_THRESHOLD | PidTagJunkThreshold
PR_KEYWORD_A | PidTagKeyword
PR_KEYWORD_W | PidTagKeyword
PR_KEYWORD | PidTagKeyword
PR_LANGUAGE_A | PidTagLanguage
PR_LANGUAGE_W | PidTagLanguage
PR_LANGUAGE | PidTagLanguage
PR_LANGUAGES_A | PidTagLanguages
PR_LANGUAGES_W | PidTagLanguages
PR_LANGUAGES | PidTagLanguages
PR_LAST_MODIFICATION_TIME | PidTagLastModificationTime
PR_LAST_VERB_EXECUTED | PidTagLastVerbExecuted
PR_LAST_VERB_EXECUTION_TIME | PidTagLastVerbExecutionTime
PR_LATEST_DELIVERY_TIME | PidTagLatestDeliveryTime
PR_LIST_HELP_A | PidTagListHelp
PR_LIST_HELP_W | PidTagListHelp
PR_LIST_HELP | PidTagListHelp
PR_LIST_SUBSCRIBE_A | PidTagListSubscribe
PR_LIST_SUBSCRIBE_W | PidTagListSubscribe
PR_LIST_SUBSCRIBE | PidTagListSubscribe
PR_LIST_UNSUBSCRIBE_A | PidTagListUnsubscribe
PR_LIST_UNSUBSCRIBE_W | PidTagListUnsubscribe
PR_LIST_UNSUBSCRIBE | PidTagListUnsubscribe
PR_LOCALE_ID | PidTagLocaleId
PR_LOCALITY_A | PidTagLocality
PR_LOCALITY_W | PidTagLocality
PR_LOCALITY | PidTagLocality
PR_LOCATION_A | PidTagLocation
PR_LOCATION_W | PidTagLocation
PR_LOCATION | PidTagLocation
PR_MAIL_PERMISSION | PidTagMailPermission
PR_MANAGER_NAME_A | PidTagManagerName
PR_MANAGER_NAME_W | PidTagManagerName
PR_MANAGER_NAME | PidTagManagerName
PR_MAPPING_SIGNATURE | PidTagMappingSignature
PR_MDB_PROVIDER | PidTagStoreProvider
PR_MEMBER_ENTRYID | PidTagMemberEntryId
PR_MEMBER_ID | PidTagMemberId
PR_MEMBER_NAME | PidTagMemberName
PR_MEMBER_RIGHTS | PidTagMemberRights
PR_MESSAGE_ATTACHMENTS | PidTagMessageAttachments
PR_MESSAGE_CC_ME | PidTagMessageCcMe
PR_MESSAGE_CLASS_A | PidTagMessageClass
PR_MESSAGE_CLASS_W | PidTagMessageClass
PR_MESSAGE_CLASS | PidTagMessageClass
PR_MESSAGE_CODEPAGE | PidTagMessageCodepage
PR_MESSAGE_DELIVERY_ID | PidTagMessageDeliveryId
PR_MESSAGE_DELIVERY_TIME | PidTagMessageDeliveryTime
PR_MESSAGE_DOWNLOAD_TIME | PidTagMessageDownloadTime
PR_MESSAGE_FLAGS | PidTagMessageFlags
PR_MESSAGE_LOCALE_ID | PidTagMessageLocaleId
PR_MESSAGE_RECIP_ME | PidTagMessageRecipientMe
PR_MESSAGE_RECIPIENTS | PidTagMessageRecipients
PR_MESSAGE_SECURITY_LABEL | PidTagMessageSecurityLabel
PR_MESSAGE_SIZE_EXTENDED | PidTagMessageSizeExtended
PR_MESSAGE_SIZE | PidTagMessageSize
PR_MESSAGE_SUBMISSION_ID | PidTagMessageSubmissionId
PR_MESSAGE_TO_ME | PidTagMessageToMe
PR_MHS_COMMON_NAME_A | PidTagMessageHandlingSystemCommonName
PR_MHS_COMMON_NAME_W | PidTagMessageHandlingSystemCommonName
PR_MHS_COMMON_NAME | PidTagMessageHandlingSystemCommonName
PR_MIDDLE_NAME_A | PidTagMiddleName
PR_MIDDLE_NAME_W | PidTagMiddleName
PR_MIDDLE_NAME | PidTagMiddleName
PR_MINI_ICON | PidTagMiniIcon
PR_MOBILE_TELEPHONE_NUMBER_A | PidTagMobileTelephoneNumber
PR_MOBILE_TELEPHONE_NUMBER_W | PidTagMobileTelephoneNumber
PR_MOBILE_TELEPHONE_NUMBER | PidTagMobileTelephoneNumber
PR_MSG_EDITOR_FORMAT | PidTagMessageEditorFormat
PR_MSG_STATUS | PidTagMessageStatus
PR_NDR_DIAG_CODE | PidTagNonDeliveryReportDiagCode
PR_NDR_FROM_ENTRYID | PidTagNonDeliveryReportFromEntryId
PR_NDR_FROM_NAME | PidTagNonDeliveryReportFromName
PR_NDR_FROM_SEARCH_KEY | PidTagNonDeliveryReportFromSearchKey
PR_NDR_REASON_CODE | PidTagNonDeliveryReportReasonCode
PR_NEXT_SEND_ACCT | PidTagNextSendAcct
PR_NICKNAME_A | PidTagNickname
PR_NICKNAME_W | PidTagNickname
PR_NICKNAME | PidTagNickname
PR_NON_IPM_SUBTREE_ENTRYID | PidTagNonIpmSubtreeEntryId
PR_NON_RECEIPT_NOTIFICATION_REQUESTED | PidTagNonReceiptNotificationRequested
PR_NON_RECEIPT_REASON | PidTagNonReceiptReason
PR_NORMALIZED_SUBJECT_A | PidTagNormalizedSubject
PR_NORMALIZED_SUBJECT_W | PidTagNormalizedSubject
PR_NORMALIZED_SUBJECT | PidTagNormalizedSubject
PR_OBJECT_TYPE | PidTagObjectType
PR_OBSOLETED_IPMS | PidTagObsoletedMessageIds
PR_OFFICE_LOCATION_A | PidTagOfficeLocation
PR_OFFICE_LOCATION_W | PidTagOfficeLocation
PR_OFFICE_LOCATION | PidTagOfficeLocation
PR_OFFICE_TELEPHONE_NUMBER | PidTagBusinessTelephoneNumber
PR_OFFICE_TELEPHONE_NUMBER_W | PidTagBusinessTelephoneNumber
PR_OFFICE2_TELEPHONE_NUMBER | PidTagBusiness2TelephoneNumber
PR_ORDINAL_MOST | PidTagOrdinalMost
PR_ORG_EMAIL_ADDRESS | PidTagOrgEmailAddress
PR_ORGANIZATIONAL_ID_NUMBER_A | PidTagOrganizationalIdNumber
PR_ORGANIZATIONAL_ID_NUMBER_W | PidTagOrganizationalIdNumber
PR_ORGANIZATIONAL_ID_NUMBER | PidTagOrganizationalIdNumber
PR_ORIG_MESSAGE_CLASS_A | PidTagOriginalMessageClass
PR_ORIG_MESSAGE_CLASS_W | PidTagOriginalMessageClass
PR_ORIG_MESSAGE_CLASS | PidTagOriginalMessageClass
PR_ORIGIN_CHECK | PidTagOriginCheck
PR_ORIGINAL_AUTHOR_ADDRTYPE_A | PidTagOriginalAuthorAddressType
PR_ORIGINAL_AUTHOR_ADDRTYPE_W | PidTagOriginalAuthorAddressType
PR_ORIGINAL_AUTHOR_ADDRTYPE | PidTagOriginalAuthorAddressType
PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_A | PidTagOriginalAuthorEmailAddress
PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_W | PidTagOriginalAuthorEmailAddress
PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS | PidTagOriginalAuthorEmailAddress
PR_ORIGINAL_AUTHOR_ENTRYID | PidTagOriginalAuthorEntryId
PR_ORIGINAL_AUTHOR_NAME_A | PidTagOriginalAuthorName
PR_ORIGINAL_AUTHOR_NAME_W | PidTagOriginalAuthorName
PR_ORIGINAL_AUTHOR_NAME | PidTagOriginalAuthorName
PR_ORIGINAL_AUTHOR_SEARCH_KEY | PidTagOriginalAuthorSearchKey
PR_ORIGINAL_DELIVERY_TIME | PidTagOriginalDeliveryTime
PR_ORIGINAL_DISPLAY_BCC_A | PidTagOriginalDisplayBcc
PR_ORIGINAL_DISPLAY_BCC_W | PidTagOriginalDisplayBcc
PR_ORIGINAL_DISPLAY_BCC | PidTagOriginalDisplayBcc
PR_ORIGINAL_DISPLAY_CC_A | PidTagOriginalDisplayCc
PR_ORIGINAL_DISPLAY_CC_W | PidTagOriginalDisplayCc
PR_ORIGINAL_DISPLAY_CC | PidTagOriginalDisplayCc
PR_ORIGINAL_DISPLAY_NAME_A | PidTagOriginalDisplayName
PR_ORIGINAL_DISPLAY_NAME_W | PidTagOriginalDisplayName
PR_ORIGINAL_DISPLAY_NAME | PidTagOriginalDisplayName
PR_ORIGINAL_DISPLAY_TO_A | PidTagOriginalDisplayTo
PR_ORIGINAL_DISPLAY_TO_W | PidTagOriginalDisplayTo
PR_ORIGINAL_DISPLAY_TO | PidTagOriginalDisplayTo
PR_ORIGINAL_EITS | PidTagOriginalEits
PR_ORIGINAL_ENTRYID | PidTagOriginalEntryId
PR_ORIGINAL_SEARCH_KEY | PidTagOriginalSearchKey
PR_ORIGINAL_SENDER_ADDRTYPE_A | PidTagOriginalSenderAddressType
PR_ORIGINAL_SENDER_ADDRTYPE_W | PidTagOriginalSenderAddressType
PR_ORIGINAL_SENDER_ADDRTYPE | PidTagOriginalSenderAddressType
PR_ORIGINAL_SENDER_EMAIL_ADDRESS_A | PidTagOriginalSenderEmailAddress
PR_ORIGINAL_SENDER_EMAIL_ADDRESS_W | PidTagOriginalSenderEmailAddress
PR_ORIGINAL_SENDER_EMAIL_ADDRESS | PidTagOriginalSenderEmailAddress
PR_ORIGINAL_SENDER_ENTRYID | PidTagOriginalSenderEntryId
PR_ORIGINAL_SENDER_NAME_A | PidTagOriginalSenderName
PR_ORIGINAL_SENDER_NAME_W | PidTagOriginalSenderName
PR_ORIGINAL_SENDER_NAME | PidTagOriginalSenderName
PR_ORIGINAL_SENDER_SEARCH_KEY | PidTagOriginalSenderSearchKey
PR_ORIGINAL_SENSITIVITY | PidTagOriginalSensitivity
PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_A | PidTagOriginalSentRepresentingAddressType
PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_W | PidTagOriginalSentRepresentingAddressType
PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE | PidTagOriginalSentRepresentingAddressType
PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_A | PidTagOriginalSentRepresentingEmailAddress
PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_W | PidTagOriginalSentRepresentingEmailAddress
PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS | PidTagOriginalSentRepresentingEmailAddress
PR_ORIGINAL_SENT_REPRESENTING_ENTRYID | PidTagOriginalSentRepresentingEntryId
PR_ORIGINAL_SENT_REPRESENTING_NAME_A | PidTagOriginalSentRepresentingName
PR_ORIGINAL_SENT_REPRESENTING_NAME_W | PidTagOriginalSentRepresentingName
PR_ORIGINAL_SENT_REPRESENTING_NAME | PidTagOriginalSentRepresentingName
PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY_A | PidTagOriginalSentRepresentingSearchKey
PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY_W | PidTagOriginalSentRepresentingSearchKey
PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY | PidTagOriginalSentRepresentingSearchKey
PR_ORIGINAL_SUBJECT_A | PidTagOriginalSubject
PR_ORIGINAL_SUBJECT_W | PidTagOriginalSubject
PR_ORIGINAL_SUBJECT | PidTagOriginalSubject
PR_ORIGINAL_SUBMIT_TIME | PidTagOriginalSubmitTime
PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_A | PidTagOriginallyIntendedRecipAddrtype
PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_W | PidTagOriginallyIntendedRecipAddrtype
PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE | PidTagOriginallyIntendedRecipAddrtype
PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_A | PidTagOriginallyIntendedRecipEmailAddress
PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_W | PidTagOriginallyIntendedRecipEmailAddress
PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS | PidTagOriginallyIntendedRecipEmailAddress
PR_ORIGINALLY_INTENDED_RECIP_ENTRYID | PidTagOriginallyIntendedRecipEntryId
PR_ORIGINALLY_INTENDED_RECIPIENT_NAME | PidTagOriginallyIntendedRecipientName
PR_ORIGINATING_MTA_CERTIFICATE | PidTagOriginatingMtaCertificate
PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY | PidTagOriginatorAndDistributionListExpansionHistory
PR_ORIGINATOR_CERTIFICATE | PidTagOriginatorCertificate
PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED | PidTagOriginatorDeliveryReportRequested
PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED | PidTagOriginatorNonDeliveryReportRequested
PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT | PidTagOriginatorRequestedAlternateRecipient
PR_ORIGINATOR_RETURN_ADDRESS | PidTagOriginatorReturnAddress
PR_OTHER_ADDRESS_CITY_A | PidTagOtherAddressCity
PR_OTHER_ADDRESS_CITY_W | PidTagOtherAddressCity
PR_OTHER_ADDRESS_CITY | PidTagOtherAddressCity
PR_OTHER_ADDRESS_COUNTRY_A | PidTagOtherAddressCountry
PR_OTHER_ADDRESS_COUNTRY_W | PidTagOtherAddressCountry
PR_OTHER_ADDRESS_COUNTRY | PidTagOtherAddressCountry
PR_OTHER_ADDRESS_POST_OFFICE_BOX_A | PidTagOtherAddressPostOfficeBox
PR_OTHER_ADDRESS_POST_OFFICE_BOX_W | PidTagOtherAddressPostOfficeBox
PR_OTHER_ADDRESS_POST_OFFICE_BOX | PidTagOtherAddressPostOfficeBox
PR_OTHER_ADDRESS_POSTAL_CODE_A | PidTagOtherAddressPostalCode
PR_OTHER_ADDRESS_POSTAL_CODE_W | PidTagOtherAddressPostalCode
PR_OTHER_ADDRESS_POSTAL_CODE | PidTagOtherAddressPostalCode
PR_OTHER_ADDRESS_STATE_OR_PROVINCE_A | PidTagOtherAddressStateOrProvince
PR_OTHER_ADDRESS_STATE_OR_PROVINCE_W | PidTagOtherAddressStateOrProvince
PR_OTHER_ADDRESS_STATE_OR_PROVINCE | PidTagOtherAddressStateOrProvince
PR_OTHER_ADDRESS_STREET_A | PidTagOtherAddressStreet
PR_OTHER_ADDRESS_STREET_W | PidTagOtherAddressStreet
PR_OTHER_ADDRESS_STREET | PidTagOtherAddressStreet
PR_OTHER_TELEPHONE_NUMBER_A | PidTagOtherTelephoneNumber
PR_OTHER_TELEPHONE_NUMBER_W | PidTagOtherTelephoneNumber
PR_OTHER_TELEPHONE_NUMBER | PidTagOtherTelephoneNumber
PR_OWN_STORE_ENTRYID | PidTagOwnStoreEntryId
PR_OWNER_APPT_ID | PidTagOwnerAppointmentId
PR_PAGER_TELEPHONE_NUMBER_A | PidTagPagerTelephoneNumber
PR_PAGER_TELEPHONE_NUMBER_W | PidTagPagerTelephoneNumber
PR_PAGER_TELEPHONE_NUMBER | PidTagPagerTelephoneNumber
PR_PARENT_DISPLAY_A | PidTagParentDisplay
PR_PARENT_DISPLAY_W | PidTagParentDisplay
PR_PARENT_DISPLAY | PidTagParentDisplay
PR_PARENT_ENTRYID | PidTagParentEntryId
PR_PERSONAL_HOME_PAGE_A | PidTagPersonalHomePage
PR_PERSONAL_HOME_PAGE_W | PidTagPersonalHomePage
PR_PERSONAL_HOME_PAGE | PidTagPersonalHomePage
PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY | PidTagPhysicalDeliveryBureauFaxDelivery
PR_PHYSICAL_DELIVERY_MODE | PidTagPhysicalDeliveryMode
PR_PHYSICAL_DELIVERY_REPORT_REQUEST | PidTagPhysicalDeliveryReportRequest
PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED | PidTagPhysicalForwardingAddressRequested
PR_PHYSICAL_FORWARDING_ADDRESS | PidTagPhysicalForwardingAddress
PR_PHYSICAL_FORWARDING_PROHIBITED | PidTagPhysicalForwardingProhibited
PR_PHYSICAL_RENDITION_ATTRIBUTES | PidTagPhysicalRenditionAttributes
PR_POST_OFFICE_BOX_A | PidTagPostOfficeBox
PR_POST_OFFICE_BOX_W | PidTagPostOfficeBox
PR_POST_OFFICE_BOX | PidTagPostOfficeBox
PR_POSTAL_ADDRESS_A | PidTagPostalAddress
PR_POSTAL_ADDRESS_W | PidTagPostalAddress
PR_POSTAL_ADDRESS | PidTagPostalAddress
PR_POSTAL_CODE_A | PidTagPostalCode
PR_POSTAL_CODE_W | PidTagPostalCode
PR_POSTAL_CODE | PidTagPostalCode
PR_PREFERRED_BY_NAME_A | PidTagPreferredByName
PR_PREFERRED_BY_NAME_W | PidTagPreferredByName
PR_PREFERRED_BY_NAME | PidTagPreferredByName
PR_PREPROCESS | PidTagPreprocess
PR_PRIMARY_FAX_NUMBER_A | PidTagPrimaryFaxNumber
PR_PRIMARY_FAX_NUMBER_W | PidTagPrimaryFaxNumber
PR_PRIMARY_FAX_NUMBER | PidTagPrimaryFaxNumber
PR_PRIMARY_SEND_ACCT | PidTagPrimarySendAccount
PR_PRIMARY_TELEPHONE_NUMBER_A | PidTagPrimaryTelephoneNumber
PR_PRIMARY_TELEPHONE_NUMBER_W | PidTagPrimaryTelephoneNumber
PR_PRIMARY_TELEPHONE_NUMBER | PidTagPrimaryTelephoneNumber
PR_PRIORITY | PidTagPriority
PR_PROCESSED | PidTagProcessed
PR_PROFESSION_A | PidTagProfession
PR_PROFESSION_W | PidTagProfession
PR_PROFESSION | PidTagProfession
PR_PROFILE_HOME_SERVER_FQDN | PidTagProfileHomeServerFQDN
PR_PROFILE_NAME_A | PidTagProfileName
PR_PROFILE_NAME_W | PidTagProfileName
PR_PROFILE_NAME | PidTagProfileName
PR_PROFILE_SERVER_FULL_VERSION | PidTagProfileServerFullVersion
PR_PROFILE_SERVER_VERSION | PR_PROFILE_SERVER_VERSION
PR_PROFILE_TYPE | PidTagProfileType
PR_PROOF_OF_DELIVERY_REQUESTED | PidTagProofOfDeliveryRequested
PR_PROOF_OF_DELIVERY | PidTagProofOfDelivery
PR_PROOF_OF_SUBMISSION_REQUESTED | PidTagProofOfSubmissionRequested
PR_PROOF_OF_SUBMISSION | PidTagProofOfSubmission
PR_PROVIDER_DISPLAY_A | PidTagProviderDisplay
PR_PROVIDER_DISPLAY_NAME_W | PidTagProviderDisplayName
PR_PROVIDER_DISPLAY_NAME | PidTagProviderDisplayName
PR_PROVIDER_DISPLAY_W | PidTagProviderDisplay
PR_PROVIDER_DISPLAY | PidTagProviderDisplay
PR_PROVIDER_DLL_NAME_A | PidTagProviderDllName
PR_PROVIDER_DLL_NAME_W | PidTagProviderDllName
PR_PROVIDER_DLL_NAME | PidTagProviderDllName
PR_PROVIDER_ICON_W | PidTagProviderIcon
PR_PROVIDER_ICON | PidTagProviderIcon
PR_PROVIDER_ITEMID | PidTagProviderItemId
PR_PROVIDER_ORDINAL | PidTagProviderOrdinal
PR_PROVIDER_PARENT_ITEMID | PidTagProviderParentItemId
PR_PROVIDER_SUBMIT_TIME | PidTagProviderSubmitTime
PR_PROVIDER_UID | PidTagProviderUid
PR_PST_CONFIG_FLAGS | PidTagPstConfigurationFlags
PR_PST_PATH | PidTagPstPath
PR_PST_PATH_A | PidTagPstPath
PR_PST_PATH_W | PidTagPstPath
PR_PST_PATH_HINT | PidTagPstPathHint
PR_PST_PATH_HINT_A | PidTagPstPathHint
PR_PST_PATH_HINT_W | PidTagPstPathHint
PR_PST_PW_SZ_NEW | PidTagPstPasswordSzNew
PR_PST_PW_SZ_NEW_A | PidTagPstPasswordSzNew
PR_PST_PW_SZ_NEW_W | PidTagPstPasswordSzNew
PR_PST_PW_SZ_OLD | PidTagPstPasswordSzOld
PR_PST_PW_SZ_OLD_A | PidTagPstPasswordSzOld
PR_PST_PW_SZ_OLD_W | PidTagPstPasswordSzOld
PR_PST_REMEMBER_PW | PidTagPstRememberPassword
PR_RADIO_TELEPHONE_NUMBER_A | PidTagRadioTelephoneNumber
PR_RADIO_TELEPHONE_NUMBER_W | PidTagRadioTelephoneNumber
PR_RADIO_TELEPHONE_NUMBER | PidTagRadioTelephoneNumber
PR_RCVD_REPRESENTING_ADDRTYPE_A | PidTagReceivedRepresentingAddressType
PR_RCVD_REPRESENTING_ADDRTYPE_W | PidTagReceivedRepresentingAddressType
PR_RCVD_REPRESENTING_ADDRTYPE | PidTagReceivedRepresentingAddressType
PR_RCVD_REPRESENTING_EMAIL_ADDRESS_A | PidTagReceivedRepresentingEmailAddress
PR_RCVD_REPRESENTING_EMAIL_ADDRESS_W | PidTagReceivedRepresentingEmailAddress
PR_RCVD_REPRESENTING_EMAIL_ADDRESS | PidTagReceivedRepresentingEmailAddress
PR_RCVD_REPRESENTING_ENTRYID | PidTagReceivedRepresentingEntryId
PR_RCVD_REPRESENTING_NAME_A | PidTagReceivedRepresentingName
PR_RCVD_REPRESENTING_NAME_W | PidTagReceivedRepresentingName
PR_RCVD_REPRESENTING_NAME | PidTagReceivedRepresentingName
PR_RCVD_REPRESENTING_SEARCH_KEY | PidTagReceivedRepresentingSearchKey
PR_READ_RECEIPT_ENTRYID | PidTagReadReceiptEntryId
PR_READ_RECEIPT_REQUESTED | PidTagReadReceiptRequested
PR_READ_RECEIPT_SEARCH_KEY | PidTagReadReceiptSearchKey
PR_READ | PidTagRead
PR_RECEIPT_TIME | PidTagReceiptTime
PR_RECEIVE_FOLDER_SETTINGS | PidTagReceiveFolderSettings
PR_RECEIVED_BY_ADDRTYPE_A | PidTagReceivedByAddressType
PR_RECEIVED_BY_ADDRTYPE_W | PidTagReceivedByAddressType
PR_RECEIVED_BY_ADDRTYPE | PidTagReceivedByAddressType
PR_RECEIVED_BY_EMAIL_ADDRESS_A | PidTagReceivedByEmailAddress
PR_RECEIVED_BY_EMAIL_ADDRESS_W | PidTagReceivedByEmailAddress
PR_RECEIVED_BY_EMAIL_ADDRESS | PidTagReceivedByEmailAddress
PR_RECEIVED_BY_ENTRYID | PidTagReceivedByEntryId
PR_RECEIVED_BY_NAME_A | PidTagReceivedByName
PR_RECEIVED_BY_NAME_W | PidTagReceivedByName
PR_RECEIVED_BY_NAME | PidTagReceivedByName
PR_RECEIVED_BY_SEARCH_KEY | PidTagReceivedBySearchKey
PR_RECIPIENT_CERTIFICATE | PidTagRecipientCertificate
PR_RECIPIENT_DISPLAY_NAME_W | PidTagRecipientDisplayName
PR_RECIPIENT_DISPLAY_NAME | PidTagRecipientDisplayName
PR_RECIPIENT_ENTRYID | PidTagRecipientEntryId
PR_RECIPIENT_FLAGS | PidTagRecipientFlags
PR_RECIPIENT_NUMBER | PidTagRecipientNumber
PR_RECIPIENT_NUMBER_FOR_ADVICE_A | PidTagRecipientNumberForAdvice
PR_RECIPIENT_NUMBER_FOR_ADVICE_W | PidTagRecipientNumberForAdvice
PR_RECIPIENT_NUMBER_FOR_ADVICE | PidTagRecipientNumberForAdvice
PR_RECIPIENT_PROPOSED | PidTagRecipientProposed
PR_RECIPIENT_PROPOSEDENDTIME | PidTagRecipientProposedEndTime
PR_RECIPIENT_PROPOSEDSTARTTIME | PidTagRecipientProposedStartTime
PR_RECIPIENT_REASSIGNMENT_PROHIBITED | PidTagRecipientReassignmentProhibited
PR_RECIPIENT_STATUS | PidTagRecipientStatus
PR_RECIPIENT_TRACKSTATUS_TIME | PidTagRecipientTrackStatusTime
PR_RECIPIENT_TRACKSTATUS | PidTagRecipientTrackStatus
PR_RECIPIENT_TYPE | PidTagRecipientType
PR_RECORD_KEY | PidTagRecordKey
PR_REDIRECTION_HISTORY | PidTagRedirectionHistory
PR_REFERRED_BY_NAME_A | PidTagReferredByName
PR_REFERRED_BY_NAME_W | PidTagReferredByName
PR_REFERRED_BY_NAME | PidTagReferredByName
PR_REGISTERED_MAIL_TYPE | PidTagRegisteredMailType
PR_RELATED_IPMS | PidTagRelatedMessageIds
PR_REM_ONLINE_ENTRYID | PidTagRemindersOnlineEntryId
PR_REMOTE_PROGRESS_TEXT_A | PidTagRemoteProgressText
PR_REMOTE_PROGRESS_TEXT_W | PidTagRemoteProgressText
PR_REMOTE_PROGRESS_TEXT | PidTagRemoteProgressText
PR_REMOTE_PROGRESS | PidTagRemoteProgress
PR_REMOTE_VALIDATE_OK | PidTagRemoteValidateOk
PR_RENDERING_POSITION | PidTagRenderingPosition
PR_REPLY_RECIPIENT_ENTRIES | PidTagReplyRecipientEntries
PR_REPLY_RECIPIENT_NAMES_A | PidTagReplyRecipientNames
PR_REPLY_RECIPIENT_NAMES_W | PidTagReplyRecipientNames
PR_REPLY_RECIPIENT_NAMES | PidTagReplyRecipientNames
PR_REPLY_REQUESTED | PidTagReplyRequested
PR_REPLY_TEMPLATE_ID | PidTagReplyTemplateId
PR_REPLY_TIME | PidTagReplyTime
PR_REPORT_DISPOSITION | PidTagReportDisposition
PR_REPORT_DISPOSITION_A | PidTagReportDisposition
PR_REPORT_DISPOSITION_W | PidTagReportDisposition
PR_REPORT_DISPOSITION_MODE | PidTagReportDispositionMode
PR_REPORT_DISPOSITION_MODE_A | PidTagReportDispositionMode
PR_REPORT_DISPOSITION_MODE_W | PidTagReportDispositionMode
PR_REPORT_DISPOSITION_OPTIONS | PidTagReportDispositionOptions
PR_REPORT_DISPOSITION_OPTIONS_A | PidTagReportDispositionOptions
PR_REPORT_DISPOSITION_OPTIONS_W | PidTagReportDispositionOptions
PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES | PidTagReportDispositionToEmailAddresses
PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_A | PidTagReportDispositionToEmailAddresses
PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_W | PidTagReportDispositionToEmailAddresses
PR_REPORT_DISPOSITION_TO_NAMES | PidTagReportDispositionToNames
PR_REPORT_DISPOSITION_TO_NAMES_A | PidTagReportDispositionToNames
PR_REPORT_DISPOSITION_TO_NAMES_W | PidTagReportDispositionToNames
PR_REPORT_ENTRYID | PidTagReportEntryId
PR_REPORT_NAME_A | PidTagReportName
PR_REPORT_NAME_W | PidTagReportName
PR_REPORT_NAME | PidTagReportName
PR_REPORT_ORIGINAL_SENDER | PidTagReportOriginalSender
PR_REPORT_ORIGINAL_SENDER_A | PidTagReportOriginalSender
PR_REPORT_ORIGINAL_SENDER_W | PidTagReportOriginalSender
PR_REPORT_SEARCH_KEY | PidTagReportSearchKey
PR_REPORT_TAG | PidTagReportTag
PR_REPORT_TEXT_A | PidTagReportText
PR_REPORT_TEXT_W | PidTagReportText
PR_REPORT_TEXT | PidTagReportText
PR_REPORT_TIME | PidTagReportTime
PR_REPORTING_DL_NAME | PidTagReportingDistributionListName
PR_REPORTING_MTA_CERTIFICATE | PidTagReportingMessageTransferAgentCertificate
PR_REQUESTED_DELIVERY_METHOD | PidTagRequestedDeliveryMethod
PR_RESOLVE_METHOD | PidTagResolveMethod
PR_RESOURCE_FLAGS | PidTagResourceFlags
PR_RESOURCE_METHODS | PidTagResourceMethods
PR_RESOURCE_PATH_A | PidTagResourcePath
PR_RESOURCE_PATH_W | PidTagResourcePath
PR_RESOURCE_PATH | PidTagResourcePath
PR_RESOURCE_TYPE | PidTagResourceType
PR_RESPONSE_REQUESTED | PidTagResponseRequested
PR_RESPONSIBILITY | PidTagResponsibility
PR_RETURNED_IPM | PidTagReturnedMessageid
PR_ROAMING_BINARYSTREAM | PidTagRoamingBinary
PR_ROAMING_DATATYPES | PidTagRoamingDatatypes
PR_ROAMING_DICTIONARY | PidTagRoamingDictionary
PR_ROAMING_XMLSTREAM | PidTagRoamingXmlStream
PR_ROH_FLAGS | PidTagRpcOverHttpFlags
PR_ROH_PROXY_AUTH_SCHEME | PidTagRpcOverHttpProxyAuthScheme
PR_ROH_PROXY_PRINCIPAL_NAME | PidTagRpcOverHttpProxyPrincipalName
PR_ROH_PROXY_SERVER | PidTagRpcOverHttpProxyServer
PR_ROW_TYPE | PidTagRowType
PR_ROWID | PidTagRowid
PR_RTF_COMPRESSED | PidTagRtfCompressed
PR_RTF_IN_SYNC | PidTagRtfInSync
PR_RTF_SYNC_BODY_COUNT | PidTagRtfSyncBodyCount
PR_RTF_SYNC_BODY_CRC | PidTagRtfSyncBodyCrc
PR_RTF_SYNC_BODY_TAG_A | PidTagRtfSyncBodyTag
PR_RTF_SYNC_BODY_TAG_W | PidTagRtfSyncBodyTag
PR_RTF_SYNC_BODY_TAG | PidTagRtfSyncBodyTag
PR_RTF_SYNC_PREFIX_COUNT | PidTagRtfSyncPrefixCount
PR_RTF_SYNC_TRAILING_COUNT | PidTagRtfSyncTrailingCount
PR_RULE_ACTIONS | PidTagRuleActions
PR_RULE_CONDITION | PidTagRuleCondition
PR_RULE_ID | PidTagRuleId
PR_RULE_LEVEL | PidTagRuleLevel
PR_RULE_MSG_NAME | PidTagRuleMsgName
PR_RULE_MSG_PROVIDER | PidTagRuleMsgProvider
PR_RULE_NAME | PidTagRuleName
PR_RULE_PROVIDER | PidTagRuleProvider
PR_RULE_PROVIDER_DATA | PidTagRuleProviderData
PR_RULE_SEQUENCE | PidTagRuleSequence
PR_RULE_STATE | PidTagRuleState
PR_RULE_USER_FLAGS | PidTagRuleUserFlags
PR_RULES_TABLE | PidTagRulesTable
PR_SCHDINFO_APPT_TOMBSTONE | PidTagScheduleInfoAppointmentTombstone
PR_SCHDINFO_AUTO_ACCEPT_APPTS | PidTagScheduleInfoAutoAcceptAppointments
PR_SCHDINFO_BOSS_WANTS_COPY | PidTagScheduleInfoDelegatorWantsCopy
PR_SCHDINFO_BOSS_WANTS_INFO | PidTagScheduleInfoDelegatorWantsInfo
PR_SCHDINFO_DELEGATE_ENTRYIDS | PidTagScheduleInfoDelegateEntryIds
PR_SCHDINFO_DELEGATE_NAMES | PidTagScheduleInfoDelegateNames
PR_SCHDINFO_DISALLOW_OVERLAPPING_APPTS | PidTagScheduleInfoDisallowOverlappingAppts
PR_SCHDINFO_DISALLOW_RECURRING_APPTS | PidTagScheduleInfoDisallowRecurringAppts
PR_SCHDINFO_DONT_MAIL_DELEGATES | PidTagScheduleInfoDontMailDelegates
PR_SCHDINFO_FREEBUSY_BUSY | PidTagScheduleInfoFreeBusyBusy
PR_SCHDINFO_FREEBUSY_MERGED | PidTagScheduleInfoFreeBusyMerged
PR_SCHDINFO_FREEBUSY_OOF | PidTagScheduleInfoFreeBusyAway
PR_SCHDINFO_FREEBUSY_TENTATIVE | PidTagScheduleInfoFreeBusyTentative
PR_SCHDINFO_FREEBUSY | PidTagScheduleInfoFreeBusy
PR_SCHDINFO_MONTHS_BUSY | PidTagScheduleInfoMonthsBusy
PR_SCHDINFO_MONTHS_MERGED | PidTagScheduleInfoMonthsMerged
PR_SCHDINFO_MONTHS_OOF | PidTagScheduleInfoMonthsAway
PR_SCHDINFO_MONTHS_TENTATIVE | PidTagScheduleInfoMonthsTentative
PR_SCHDINFO_RESOURCE_TYPE | PidTagScheduleInfoResourceType
PR_SEARCH_KEY | PidTagSearchKey
PR_SEARCH | PidTagSearch
PR_SEARCH_ATTACHMENTS_W | PidTagSearchAttachments
PR_SEARCH_RECIP_EMAIL_BCC_W | PidTagSearchRecipientEmailBcc
PR_SEARCH_RECIP_EMAIL_CC_W | PidTagSearchRecipientEmailCc
PR_SEARCH_RECIP_EMAIL_TO_W | PidTagSearchRecipientEmailTo
PR_SELECTABLE | PidTagSelectable
PR_SEND_INTERNET_ENCODING | PidTagSendInternetEncoding
PR_SEND_RICH_INFO | PidTagSendRichInfo
PR_SENDER_ADDRTYPE_A | PidTagSenderAddressType
PR_SENDER_ADDRTYPE_W | PidTagSenderAddressType
PR_SENDER_ADDRTYPE | PidTagSenderAddressType
PR_SENDER_EMAIL_ADDRESS_A | PidTagSenderEmailAddress
PR_SENDER_EMAIL_ADDRESS_W | PidTagSenderEmailAddress
PR_SENDER_EMAIL_ADDRESS | PidTagSenderEmailAddress
PR_SENDER_ENTRYID | PidTagSenderEntryId
PR_SENDER_NAME_A | PidTagSenderName
PR_SENDER_NAME_W | PidTagSenderName
PR_SENDER_NAME | PidTagSenderName
PR_SENDER_SEARCH_KEY | PidTagSenderSearchKey
PR_SENDER_SMTP_ADDRESS_A | PidTagSenderSmtpAddress
PR_SENDER_SMTP_ADDRESS_W | PidTagSenderSmtpAddress
PR_SENDER_SMTP_ADDRESS | PidTagSenderSmtpAddress
PR_SENSITIVITY | PidTagSensitivity
PR_SENT_REPRESENTING_ADDRTYPE_A | PidTagSentRepresentingAddressType
PR_SENT_REPRESENTING_ADDRTYPE_W | PidTagSentRepresentingAddressType
PR_SENT_REPRESENTING_ADDRTYPE | PidTagSentRepresentingAddressType
PR_SENT_REPRESENTING_EMAIL_ADDRESS_A | PidTagSentRepresentingEmailAddress
PR_SENT_REPRESENTING_EMAIL_ADDRESS_W | PidTagSentRepresentingEmailAddress
PR_SENT_REPRESENTING_EMAIL_ADDRESS | PidTagSentRepresentingEmailAddress
PR_SENT_REPRESENTING_ENTRYID | PidTagSentRepresentingEntryId
PR_SENT_REPRESENTING_NAME_A | PidTagSentRepresentingName
PR_SENT_REPRESENTING_NAME_W | PidTagSentRepresentingName
PR_SENT_REPRESENTING_NAME | PidTagSentRepresentingName
PR_SENT_REPRESENTING_SEARCH_KEY | PidTagSentRepresentingSearchKey
PR_SENT_REPRESENTING_SMTP_ADDRESS_A | PidTagSentRepresentingSmtpAddress
PR_SENT_REPRESENTING_SMTP_ADDRESS_W | PidTagSentRepresentingSmtpAddress
PR_SENT_REPRESENTING_SMTP_ADDRESS | PidTagSentRepresentingSmtpAddress
PR_SENTMAIL_ENTRYID | PidTagSentMailEntryId
PR_SERVICE_DELETE_FILES_A | PidTagServiceDeleteFiles
PR_SERVICE_DELETE_FILES_W | PidTagServiceDeleteFiles
PR_SERVICE_DELETE_FILES | PidTagServiceDeleteFiles
PR_SERVICE_DLL_NAME_A | PidTagServiceDllName
PR_SERVICE_DLL_NAME_W | PidTagServiceDllName
PR_SERVICE_DLL_NAME | PidTagServiceDllName
PR_SERVICE_ENTRY_NAME | PidTagServiceEntryName
PR_SERVICE_EXTRA_UIDS | PidTagServiceExtraUids
PR_SERVICE_INSTALL_ID_A | PidTagServiceInstallId
PR_SERVICE_INSTALL_ID_W | PidTagServiceInstallId
PR_SERVICE_INSTALL_ID | PidTagServiceInstallId
PR_SERVICE_NAME_A | PidTagServiceName
PR_SERVICE_NAME_W | PidTagServiceName
PR_SERVICE_NAME | PidTagServiceName
PR_SERVICE_SUPPORT_FILES_A | PidTagServiceSupportFiles
PR_SERVICE_SUPPORT_FILES_W | PidTagServiceSupportFiles
PR_SERVICE_SUPPORT_FILES | PidTagServiceSupportFiles
PR_SERVICE_UID | PidTagServiceUid
PR_SERVICES | PidTagServices
PR_SMTP_ADDRESS_A | PidTagSmtpAddress
PR_SMTP_ADDRESS_W | PidTagSmtpAddress
PR_SMTP_ADDRESS | PidTagSmtpAddress
PR_SPOOLER_STATUS | PidTagSpoolerStatus
PR_SPOUSE_NAME_A | PidTagSpouseName
PR_SPOUSE_NAME_W | PidTagSpouseName
PR_SPOUSE_NAME | PidTagSpouseName
PR_START_DATE | PidTagStartDate
PR_STATE_OR_PROVINCE_A | PidTagStateOrProvince
PR_STATE_OR_PROVINCE_W | PidTagStateOrProvince
PR_STATE_OR_PROVINCE | PidTagStateOrProvince
PR_STATUS_CODE | PidTagStatusCode
PR_STATUS_STRING_A | PidTagStatusString
PR_STATUS_STRING_W | PidTagStatusString
PR_STATUS_STRING | PidTagStatusString
PR_STATUS | PidTagStatus
PR_STORE_ENTRYID | PidTagStoreEntryId
PR_STORE_ENTRYID_EMSMDB_V1 | PidTagStoreEntryIdEmsmdbV1
PR_STORE_PROVIDERS | PidTagStoreProviders
PR_STORE_RECORD_KEY | PidTagStoreRecordKey
PR_STORE_STATE | PidTagStoreState
PR_STORE_SUPPORT_MASK | PidTagStoreSupportMask
PR_STORE_UNICODE_MASK | PidTagStoreUnicodeMask
PR_STREET_ADDRESS_A | PidTagStreetAddress
PR_STREET_ADDRESS_W | PidTagStreetAddress
PR_STREET_ADDRESS | PidTagStreetAddress
PR_SUBFOLDERS | PidTagSubfolders
PR_SUBJECT_A | PidTagSubject
PR_SUBJECT_IPM | PidTagSubjectMessageId
PR_SUBJECT_PREFIX_A | PidTagSubjectPrefix
PR_SUBJECT_PREFIX_W | PidTagSubjectPrefix
PR_SUBJECT_PREFIX | PidTagSubjectPrefix
PR_SUBJECT_W | PidTagSubject
PR_SUBJECT | PidTagSubject
PR_SUBMIT_FLAGS | PidTagSubmitFlags
PR_SUPPLEMENTARY_INFO_A | PidTagSupplementaryInfo
PR_SUPPLEMENTARY_INFO_W | PidTagSupplementaryInfo
PR_SUPPLEMENTARY_INFO | PidTagSupplementaryInfo
PR_SURNAME_A | PidTagSurname
PR_SURNAME_W | PidTagSurname
PR_SURNAME | PidTagSurname
PR_SWAPPED_TODO_DATA | PidTagSwappedToDoData
PR_SWAPPED_TODO_STORE | PidTagSwappedToDoStore
PR_TELEX_NUMBER_A | PidTagTelexNumber
PR_TELEX_NUMBER_W | PidTagTelexNumber
PR_TELEX_NUMBER | PidTagTelexNumber
PR_TEMPLATEID | PidTagTemplateid
PR_TITLE_A | PidTagTitle
PR_TITLE_W | PidTagTitle
PR_TITLE | PidTagTitle
PR_TNEF_CORRELATION_KEY | PidTagTnefCorrelationKey
PR_TNEF_UNPROCESSED_PROPS | PidTagTnefUnprocessedProps
PR_TODO_ITEM_FLAGS | PidTagToDoItemFlags
PR_TRANSMITABLE_DISPLAY_NAME_A | PidTagTransmittableDisplayName
PR_TRANSMITABLE_DISPLAY_NAME_W | PidTagTransmittableDisplayName
PR_TRANSMITABLE_DISPLAY_NAME | PidTagTransmittableDisplayName
PR_TRANSPORT_KEY | PidTagTransportKey
PR_TRANSPORT_MESSAGE_HEADERS_A | PidTagTransportMessageHeaders
PR_TRANSPORT_MESSAGE_HEADERS_W | PidTagTransportMessageHeaders
PR_TRANSPORT_MESSAGE_HEADERS | PidTagTransportMessageHeaders
PR_TRANSPORT_PROVIDERS | PidTagTransportProviders
PR_TTYTDD_PHONE_NUMBER_A | PidTagTelecommunicationsDeviceForDeafTelephoneNumber
PR_TTYTDD_PHONE_NUMBER_W | PidTagTelecommunicationsDeviceForDeafTelephoneNumber
PR_TTYTDD_PHONE_NUMBER | PidTagTtyTddPhoneNumber
PR_TTYTDD_PHONE_NUMBER | PidTagTelecommunicationsDeviceForDeafTelephoneNumber
PR_TYPE_OF_MTS_USER | PidTagTypeOfX400User
PR_URL_COMP_NAME_A | PidTagUrlComponentName
PR_URL_COMP_NAME_W | PidTagUrlComponentName
PR_URL_COMP_NAME | PidTagUrlComponentName
PR_USER_CERTIFICATE | PidTagUserCertificate
PR_USER_X509_CERTIFICATE | PidTagUserX509Certificate
PR_VALID_FOLDER_MASK | PidTagValidFolderMask
PR_VD_NAME_W | PidTagViewDescriptorName
PR_VD_NAME | PidTagViewDescriptorName
PR_VD_VERSION | PidTagViewDescriptorVersion
PR_VIEWS_ENTRYID | PidTagViewsEntryId
PR_WB_SF_DEFINITION | PidTagSearchFolderDefinition
PR_WB_SF_EFP_FLAGS | PidTagSearchFolderEfpFlags
PR_WB_SF_EXPIRATION | PidTagSearchFolderExpiration
PR_WB_SF_ID | PidTagSearchFolderId
PR_WB_SF_LAST_USED | PidTagSearchFolderLastUsed
PR_WB_SF_STORAGE_TYPE | PidTagSearchFolderStorageType
PR_WB_SF_TAG | PidTagSearchFolderTag
PR_WB_SF_TEMPLATE_ID | PidTagSearchFolderTemplateId
PR_WEDDING_ANNIVERSARY | PidTagWeddingAnniversary
PR_WIZARD_NO_PAB_PAGE | PidTagWizardNoPabPage
PR_WIZARD_NO_PST_PAGE | PidTagWizardNoPstPage
PR_X400_CONTENT_TYPE | PidTagX400ContentType
PR_XPOS | PidTagXCoordinate
PR_YPOS | PidTagYCoordinate


MAPI Objects and Properties

 Copy code hover
[image]

MAPI Objects and Properties
See also Send feedback

Published: July 16, 2012

Some properties are supported by many different types of objects. The following properties are examples of properties that are used by multiple objects:

  • PR_ENTRYID (PidTagEntryId) is a binary identifier used to open objects.

  • PR_OBJECT_TYPE (PidTagObjectType) is a constant used to identify the kind of object.

  • PR_DISPLAY_NAME (PidTagDisplayName) is a character string used to describe an object to the user.

Other properties make sense for a single type of object. The following properties are examples of properties that apply to one type of object:

  • PR_MESSAGE_CLASS (PidTagMessageClass) is a character string used to describe the type of a message.

  • PR_ROWID (PidTagRowid) is an integer used to identify a row in a table.

  • PR_ATTACH_SIZE (PidTagAttachSize) is an integer used to store the number of bytes in an attachment.

Still other properties are applicable only for a single type of object in a particular state. Properties of this type are typically message properties. When a message is first created, its set of properties is very small. As it is sent by a client to a recipient through the messaging system, the number of properties needed to describe the message increases. Some of these added properties appear only on the message as it is being delivered while others appear only on the message as it is being sent. Messages also have properties that are associated with the class to which they belong. Report messages, for example, have properties that are not supported by messages of other classes, such as note messages.

Every object has some required properties and may or may not have other optional properties. Required properties are properties that must exist on an object before the object can be successfully saved with its IMAPIProp::SaveChanges method. Clients or service providers using an object can depend on the availability of required properties after the SaveChanges call. That is, they can be sure that a call to the object's IMAPIProp::GetProps method or IMAPIProp::OpenProperty method to retrieve these properties will succeed.

Optional properties are properties that, depending on the object's implementer, may or may not be supported by an object. A client or service provider using the object cannot expect optional properties to be available through the GetProps or OpenProperty methods and to be set to valid values.

For a list or properties in the this Reference, see MAPI Properties. Descriptions of properties belonging to each of the message store and address book objects can be found in the discussion of the object's standard interface. For example, folder properties are discussed with IMAPIFolder and messaging user properties are discussed with IMailUser. Message properties, including report message properties, are described with IMessage and in Message Properties Overview. Properties belonging to each of the different types of tables are described in the appropriate MAPI Tables topic. For example, hierarchy table properties are described in Hierarchy Tables. Properties belonging to form servers are describing in Choosing a Form's Property Set.

When a client or service provider calls an object's GetProps method to retrieve several of its properties and one of these properties is unavailable, GetProps returns the warning MAPI_W_ERRORS_RETURNED. The call is considered to be successful because some of the properties were returned. When a client or service provider calls OpenProperty and the target property is unavailable, the method fails with the error MAPI_E_NOT_FOUND. It is important to check that a requested property is returned before attempting to work with it.

Depending on the object, the service provider supplying the implementation, and the property, a property can have read/write or read-only permission. Read/write permission allows a client or service provider using the property to change its value; read-only permission allows only the service provider owning the object to make changes.

To find out exactly which properties are currently set for an object, call IMAPIProp::GetPropList. The GetPropList method lets a caller find out what is available before an attempt to open a potentially nonexistent property is made. Because there is no standard set of properties that all objects of a specific type support, it is impossible to guess whether or not an object supports a particular property. Calling GetPropList eliminates the guess work.

See also

Concepts

MAPI Objects and Properties


Handling MAPI Property Errors

 Copy code hover
[image]

Handling MAPI Property Errors
See also Send feedback

Published: July 16, 2012

Instead of complete failure or success, the following IMAPIProp methods report partial success:

GetProps

SetProps

DeleteProps

CopyTo

CopyProps

GetProps reports partial success when it can retrieve at least one of the requested properties for an object. GetProps indicates partial success by returning the warning MAPI_W_ERRORS_RETURNED and placing information about the unavailable properties in the property value array pointed to by the lppPropArray parameter. An unavailable property's entry in this array contains PT_ERROR for the property type in the ulPropTag member and MAPI_E_NOT_FOUND or another appropriate error value for the Value member. For example, if a client calls a folder's GetProps method to retrieve three properties and the third is unavailable, the message store provider places PT_ERROR in the third property type in the property value array and MAPI_E_NOT_FOUND in the third property value.

The other IMAPIProp methods report partial success differently. These methods report partial success by returning S_OK and placing error information in an SPropProblemArray structure. Unlike the property value array in GetProps that contains data regardless of whether the method succeeded or failed, the property problem array in these methods exists only if there are errors and only if the caller has registered interest in learning about the errors. Callers must specify a valid SPropProblemArray pointer to register for error information.

When an error value is returned from SetProps, DeleteProps, CopyTo, or CopyProps, this indicates failure instead of partial success. The property problem array, if available, is not valid. Clients should not try to access data held in the structure nor should they try to free the structure itself. The appropriate response is to call IMAPIProp::GetLastError.

GetLastError is similar to the function of the same name provided in the Windows SDK. Both provide more detailed information about an error than is available with the return value. They both return information about the previous error that has occurred. The difference is that the Win32 GetLastError function reports on an error generated by the calling thread and the IMAPIProp::GetLastError method reports on an error generated by the current object. That is, if a client calls DeleteProps on a message and MAPI_E_NO_ACCESS is returned to indicate that the message is read-only, GetLastError returns data provided by the message.

See also

Concepts

MAPI Property Overview


Defining New MAPI Properties

 Copy code hover
[image]

Defining New MAPI Properties
See also Send feedback

Published: July 16, 2012

In spite of the wealth of properties supplied by MAPI for use by clients and service providers, MAPI enables new properties to be created if necessary. Some of the valid scenarios for defining new public properties include a client creating properties to support a new message class and a service provider creating new properties to expose unique messaging system features.

It is typically not valid for a service provider to define new properties for an existing MAPI object or message class. One of the primary benefits of using MAPI is that standard identifiers and formats for a large number of messaging system elements are set up, enabling users to seamlessly mix and match service providers. Service providers that use nonstandard properties do not work as well with other service providers.

Clients can create content properties for new message classes by:

  • Using property identifiers within a designated range for message class-specific content properties.

    - Or -

  • Using named properties.

The first option is preferable because not all service providers support named properties. MAPI defines two separate ranges for clients to use for new message class-specific content properties:

  • 0x6800 to 0x7BFF for transmittable properties

  • 0x7C00 to 0x7FFF for nontransmittable properties

Property identifiers must fall in predefined ranges to help prevent collisions between properties defined by different vendors or users. However, users of properties in these ranges cannot make assumptions as to the behavior of the properties. Every client that creates a new message class has access to these ranges; a property with identifier xxxx can mean one behavior for one message class and another behavior for another message class.

Named properties are used to guarantee a specific property is unique to a message class. Named property identifiers start in the 0x8000 range. Clients define one or more names and then call the message store's IMAPIProp::GetIDsFromNames method to associate an identifier with each name. Named properties can be used by clients or service providers to define new properties for any object only if the owner of the object supports named properties. Users of these properties call GetIDsFromNames and a related IMAPIProp method, GetNamesFromIDs, to map between a name and its identifier.

All properties, new or existing, must use the set of predefined property types. New property types cannot be added and existing types cannot be modified or deleted. Simple, small properties, such as single-character or 16-bit integer properties, can be stored in any appropriate type. For example, integers can be stored as ULONG and strings can be stored as PT_STRING8.

Use the PT_BINARY type to indicate a counted byte array. This property type is useful for extending the types of data that can be stored in an object. Bytes are transmitted in sequence and no assumptions are made about the meaning of the data. When a client application reads data out of such a property, the data is unchanged from how it was stored. The client must perform any necessary byte swapping when moving data across CPUs.

See also

Concepts

MAPI Property Overview


Permissions for MAPI Objects and Properties

 Copy code hover
[image]

Permissions for MAPI Objects and Properties
See also Send feedback

Published: July 16, 2012

Access permission, or the set of permissable operations, can be a characteristic of MAPI objects and of individual properties supported by those objects. Object access is determined by an object's parent. For a message, its folder determines access permissions. For a messaging user or distribution list, its address book container makes this determination. When an object such as a message resides in two folders, the permissions for the two copies of the object can be different.

Clients using these objects can request the highest level of access permitted for the object by setting the MAPI_BEST_ACCESS flag on the IMAPISession::OpenEntry call. Depending on the service provider implementing the object, the client may or may not be granted the level of access necessary. Clients can determine the level of access that they were granted by calling the object GetProps method to retrieve the PR_ACCESS (PidTagAccess) property. However, because the service provider must dynamically generate the value for this property, it is recommended that clients retrieve it only when necessary.

To determine whether a container such as a folder, address book container, or distribution list allows modification, call its GetProps method to retrieve the PR_ACCESS_LEVEL (PidTagAccessLevel) property. Container level access affects clients in terms of how they display their user interfaces. It also impacts the implementers of objects within containers in terms of their user interface display and their general implementation.

Access to a particular property is determined by the property schema set up by MAPI for the object that owns the property. Property schemas specify the set of required and optional properties for an object and their access permission. Unlike object access which is determined by the object's parent, property access is global. Every object, regardless of the access requirements of the object's parent, has the same permissions for the property as determined by the schema.

When a property is read-only, it will always be available with a GetProps or OpenProperty call. However, depending on the implementation of the object supporting the property, there are two possible outcomes for the SetProps method for modifying a property and the DeleteProps method for removing it:

  • Fail and return MAPI_E_NO_ACCESS

  • Succeed with no action taken

Property and object access can also be retrieved or set by using the IPropData interface that inherits from the IMAPIProp interface. MAPI provides an implementation of IPropData that is based on data in memory. Service providers can use IPropData to implement IMAPIProp in certain circumstances, such as for their status object or if they are using a database that does not have built-in transactions. IPropData works exclusively in memory, making it unnecessary to lock and unlock data.

See also

Concepts

MAPI Property Overview


Retrieving MAPI Properties

 Copy code hover
[image]

Retrieving MAPI Properties
See also Send feedback

Published: July 16, 2012

When a client or service provider retrieves a property from an object, the object makes available the property's value, type, and identifier.

Clients and service providers can retrieve an object's properties by calling one of the following:

IMAPIProp::GetProps

IMAPIProp::OpenProperty

HrGetOneProp

The GetProps method is used to retrieve one or more properties that do not need a specialized or alternate interface for access. This implies that the properties available with GetProps are small, such as integers and Boolean values.

To retrieve multiple properties

  1. Allocate an SPropTagArray structure large enough to hold the number of properties to be retrieved.

  2. Set the cValues member of the SPropTagArray structure to the number of properties to be retrieved and set each aulPropTag member to the identifier and type, if possible, of one of the target properties. If the type is unknown, set it to PT_UNSPECIFIED. If both the type and the identifier are unknown, locate this information by calling IMAPIProp::GetPropList. GetPropList returns a property tag array with all of the object's supported properties. If only a property name is available, call IMAPIProp::GetIDsFromNames to access the associated identifier.

  3. Call IMAPIProp::GetProps to open the property or properties.

The OpenProperty method is used to open larger properties that require an alternate interface such as IStream or IMAPITable for access. OpenProperty is typically used to open large character string, binary, and object properties and can only open one property at a time. Callers pass in the identifier of the additional interface that is required as one of the input parameters.

Some of the common uses of OpenProperty include opening PR_BODY (PidTagBody), the property that holds the body of a text-based message, PR_ATTACH_DATA_OBJ (PidTagAttachDataObject), the property that holds an OLE object or message attachment, and PR_CONTAINER_CONTENTS (PidTagContainerContents), the property that holds a folder or address book container contents table.

Depending on the property, a different interface is requested from OpenProperty. IStream, an interface that allows property data to be read and written as a stream of bytes, is typically used to access PR_BODY. Either IMessage or IStream can be used to access PR_ATTACH_DATA_OBJ. Embedded message attachments that are standard messages use IMessage whereas messages in the TNEF format use IStream. Because PR_CONTAINER_CONTENTS is a table object, it is accessed with IMAPITable.

To retrieve an attachment's PR_ATTACH_DATA_BIN property

  1. Call the OpenStreamOnFile function to open a stream for the file.

  2. Call the message's IMAPIProp::OpenProperty method to retrieve the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property with the IStream interface. Set both the MAPI_MODIFY and MAPI_CREATE flags.

  3. Allocate a STATSTG structure and pass it in a call to the file stream's IStream::Stat method to determine its size. Another way to determine stream size is to call IStream::Seek with the flag STREAM_SEEK_END.

  4. Call the stream's IStream::CopyTo method to copy the data from the file's stream into the attachment stream.

  5. When the copy operation is finished, release both streams by calling their IUnknown::Release methods.

When IStream is used for property access, some service providers automatically send the size of the property back with the stream. Calling OpenProperty with the MAPI_DEFERRED_ERRORS flag can delay the opening of the property and the return of the stream size. If IStream::Stat is called to retrieve this size after OpenProperty with the MAPI_DEFERRED_ERRORS flag set, performance will be impacted because this sequence of calls forces an extra remote procedure call. To avoid the performance hit, clients can call any MAPI method between the calls to OpenProperty and to Stat.

The HrGetOneProp function, like OpenProperty, opens one property at a time. HrGetOneProp should only be used when the target object exists on the local machine. When the target object is not locally available, using HrGetOneProp repeatedly can result in multiple remote procedure calls and a performance degradation.

Callers that need several properties can either call HrGetOneProp or OpenProperty in a loop or make one call to GetProps. Calling GetProps once is more efficient.

Note Note

Secure properties are not automatically available with other properties in a GetProps, HrGetOneProp, or GetPropList call. Secure properties must be explicitly requested using their property identifiers.

See also

Concepts

MAPI Property Overview


Updating MAPI Properties

 Copy code hover
[image]

Updating MAPI Properties
See also Send feedback

Published: July 16, 2012

Clients and service providers can update a property value by calling:

  • An object's IMAPIProp::SetProps method to update the value of one or more of an object's properties.

  • The HrSetOneProp function to update only one property at a time. Use HrSetOneProp only if the target object is local; this function can cause performance degradation when used with remote objects.

The following procedure illustrates how to use SetProps to update the message class, or PR_MESSAGE_CLASS_A (PidTagMessageClass) property, of a message.

To update the message class of a message

  1. Allocate an SPropValue structure for the message class and set its members as appropriate.

    C++ Copy code Copy code
    SPropValue spvMsgClass;
spvMsgClass.ulPropTag = PR_MESSAGE_CLASS_A;
spvMsgClass.Value.lpszA = "IPM.NewClass";

  2. Call the message's IMAPIProp::SetProps method to set the new message class.

    C++ Copy code Copy code
    hRes = lpMessage->SetProps(1, (LPSPropValue) &spvMsgClass, NULL);

See also

Concepts

MAPI Property Overview


Copying MAPI Properties

 Copy code hover
[image]

Copying MAPI Properties
See also Send feedback

Published: July 16, 2012

Clients and service providers can copy one or more of an object's properties with the following IMAPIProp methods and API functions:

  • The IMAPIProp::CopyTo method copies all of an object's properties to another object, optionally excluding selected properties. CopyTo is used for copying or moving any type of object.

  • The IMAPIProp::CopyProps method copies selected properties of an object. CopyProps is used mainly with messages. When a client creates a forwarded copy of a message or a reply, CopyProps handles copying the appropriate properties from the original message.

  • The PropCopyMore function copies a single property value from one location to another. Use PropCopyMore with caution. It is possible — when copying one value at a time — to allocate many small blocks of memory and cause memory to fragment.

  • The ScCopyProps function copies property values in bulk. ScCopyProps can copy property values that have been built from disjointed blocks of memory. It returns a new property array.

  • If the property array returned by ScCopyProps is to be stored on disk, use the ScRelocProps function to adjust the pointers. ScRelocProps should be called twice; once to adjust the addresses before writing the data operation and then again during the read operation. The ScRelocProps function assumes that the property value array was originally allocated in a single allocation.

The API functions described in the preceding list copy properties in memory rather than from one object to another object. These functions are presently supported, but might not be supported in a future release.

See also

Concepts

MAPI Property Overview


Saving MAPI Properties

 Copy code hover
[image]

Saving MAPI Properties
See also Send feedback

Published: July 16, 2012

Many objects support a transaction model of processing whereby changes to properties are not made permanent until they are committed at a later time. Whereas changes to properties are handled by the IMAPIProp::SetProps and IMAPIProp::DeleteProps methods, the commit step is handled by IMAPIProp::SaveChanges. It isn't until after a successful call to SaveChanges that the most recent version of an object's properties can be accessed.

When SaveChanges returns the error value MAPI_E_OBJECT_CHANGED, this is a warning that another client is simultaneously committing changes to the object. It is possible, depending on the provider implementing the object, for multiple clients to successfully open an object by calling its OpenEntry method with the MAPI_MODIFY flag set, giving them read/write access. The object that is returned from such an OpenEntry call is a snapshot of the storage data. Each subsequent attempt to change this data can overwrite the previous attempt.

Upon receiving MAPI_E_OBJECT_CHANGED from SaveChanges, a client has the option to:

  • Make a copy of the object to hold the changes.

  • Make another call to SaveChanges, specifying FORCE_SAVE.

Calling SaveChanges with the FORCE_SAVE flag overwrites the previous save and makes a client's changes permanent.

See also

Concepts

MAPI Property Overview


MAPI Named Properties

 Copy code hover
[image]

MAPI Named Properties
See also Send feedback

Published: July 16, 2012

MAPI provides a facility for assigning names to properties, for mapping these names to unique identifiers, and for making this mapping persistent. Persistent name to identifier mapping ensures that property names remain valid across sessions.

To define a named property, a client or service provider makes up a name and stores it in a MAPINAMEID structure. Because names are made up of a 32-bit globally unique identifier, or GUID, and either a Unicode character string or numeric value, creators of named properties can create meaningful names without fear of duplication. Names are unique and they can be used without regard to the value of their identifiers.

To support named properties, a service provider implements two methods — IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs — to translate between names and identifiers and to allow its IMAPIProp::GetPropsIMAPIProp::SetProps methods to retrieve and modify properties with identifiers in the named property range. The range for named property identifiers is between 0x8000 and 0xFFFE.

Any object that implements the IMAPIProp interface can support named properties. Address book providers that allow entries from other providers to be copied into their containers and message store providers that can be used to create arbitrary message types are required to supply this support. It is an option for all other service providers. Providers that do not support named properties return MAPI_E_NO_SUPPORT from the GetIDsFromNames and GetNamesFromIDs methods and refuse to set any properties with identifiers of 0x8000 or greater, returning MAPI_E_UNEXPECTED in the SPropProblemarray.

Creating names for properties is one way for clients to define new properties for existing or custom message classes. Service providers can use named properties to expose unique features of their messaging systems. Yet another use for named properties is to provide an alternate way of referring to properties with identifiers below 0x8000.

For example, a client could use code similar to the following code to retrieve the names for all of an object's named properties:

C++ Copy code Copy code
LPSPropTagArray FAR *    lppPropTags = NULL;
LPGUID                   lpPropSetGuid = NULL;
ULONG FAR *              lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;

lpMAPIProp->GetNamesFromIDs (lppPropTags,
                             lpPropSetGuid,
                             0,
                             lpcPropNames,
                             lpppPropNames);

To request all names from the PS_PUBLIC_STRINGS property set, a client would replace the NULL in the property set parameter to PS_PUBLIC_STRINGS as follows:

C++ Copy code Copy code
LPSPropTagArray FAR *    lppPropTags = NULL;
LPGUID                   lpPropSetGuid = &PS_PUBLIC_STRINGS;
ULONG FAR *              lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;

lpMAPIProp->GetNamesFromIDs (lppPropTags,
                             lpPropSetGuid,
                             0,
                             lpcPropNames,
                             lpppPropNames);

See also

Concepts

MAPI Property Overview


Supporting Named Properties

 Copy code hover
[image]

Supporting Named Properties
Send feedback

Published: July 16, 2012

Any object that implements the IMAPIProp : IUnknown interface can support named properties. Support for named properties is required for:

  • Address book providers that allow entries from other providers to be copied into their containers.

  • Message store providers that can be used to create arbitrary message types.

Named property support is optional for all other service providers. Service providers that do support named properties must implement name-to-identifier mapping in the IMAPIProp::GetNamesFromIDs and IMAPIProp::GetIDsFromNames methods. Clients call GetNamesFromIDs to retrieve the corresponding names for one or more property identifiers in the over 0x8000 range and GetIDsFromNames to either create or retrieve the identifiers for one or more names.

Service providers that do not support named properties must:

  • Fail calls to IMAPIProp::SetProps to set properties with identifiers of 0x8000 or greater by returning MAPI_E_UNEXPECTED_ID in the SPropProblem array.

  • Return MAPI_E_NO_SUPPORT from the IMAPIProp::GetNamesFromIDs and IMAPIProp::GetIDsFromNames methods .


Property Names and Property Sets

 Copy code hover
[image]

Property Names and Property Sets
See also Send feedback

Published: July 16, 2012

The name of every named property has two parts:

  • A globally unique identifier, or GUID, that specifies a property set.

  • A Unicode character string or 32-bit numeric value.

Names of named properties are described using a MAPINAMEID structure. This structure contains a property set member, a member for specifying the name in either numeric or string format, and a member for identifying which format is used. Because the property set is part of the property's name, it is not optional. MAPI has defined several property sets for use by clients and service providers, but if an existing property set is inappropriate, a new property set can be defined. Clients and service providers can define their own property sets by calling CoCreateGUID function. Typically these property sets are created for custom client applications.

MAPI's property sets are represented by the following constants:

PS_MAPI

PS_PUBLIC_STRINGS

PS_ROUTING_EMAIL_ADDRESSES

PS_ROUTING_ADDRTYPE

PS_ROUTING_SEARCH_KEY

PS_ROUTING_DISPLAY_NAME

PS_ROUTING_ENTRYID

The PS_MAPI property set is reserved; it is used by service providers to generate names for properties with identifiers below the named property range. The PS_PUBLIC_STRINGS property set is used by clients for named properties of IPM messages. Because named properties in the PS_PUBLIC_STRINGS property set appear in a client's user interface, nonvisible messages such as those that belong to the IPC message class should avoid creating named properties with this property set. Instead, they should create properties in the message class-specific range, 0x6800 through 0x7FFF.

The other property sets hold named properties describing recipients that are typically members of a routing list. Containing the same type of information as the properties that are associated with recipient list properties, properties in these property sets are understood by gateways to require mapping for a target messaging system. Because there are five types of information for describing properties, MAPI has defined five different property sets. A client sending a message that must include an address and address type for its routing list members assigns a named property for each member in the PS_ROUTING_EMAIL_ADDRESSES and PS_ROUTING_ADDRTYPE property sets. This ensures that the address and address type remain viable when sent to a foreign messaging system.

See also

Concepts

MAPI Named Properties


Mappings and Mapping Signatures

 Copy code hover
[image]

Mappings and Mapping Signatures
See also Send feedback

Published: July 16, 2012

When a service provider supports named properties, each set of identifier and name pairs is referred to as a mapping. Service providers can support one mapping or several. That is, one message store provider, for example, can implement the GetIDsFromNames and GetNamesFromIDs methods for all of its message, folder, and message store objects to work with a single list of names and their corresponding identifiers. Another message store provider might have one list for every folder and the messages contained within it, or implement a unique list for every message and every folder. Message store providers that use a unique mapping for every message must not allow named properties to appear in their folder contents tables because for a given property name, the property identifier will differ from message to message. MAPI recommends that providers keep it simple and operate with a single list for all of their objects including tables.

For every mapping, service providers must supply a mapping signature. A mapping signature is a binary value, usually a GUID, that uniquely identifies a set of property identifiers and their corresponding names. Mapping signatures are stored in an object's PR_MAPPING_SIGNATURE (PidTagMappingSignature) property. Service providers must change the value for their PR_MAPPING_SIGNATURE property whenever a change is made to the mapping that it represents. For example, PR_MAPPING_SIGNATURE must be updated if a new identifier is assigned to a name or a new name and identifier pair is added.

Clients working with the named properties of objects use the objects' PR_MAPPING_SIGNATURE properties in comparison and copy operations. To compare named property identifiers belonging to two objects, clients not using mapping signatures must call IMAPIProp::GetNamesFromIDs on both objects to retrieve the names for each of the identifiers. Using the mapping signatures of objects can render this call unnecessary. When two objects have the same value for their PR_MAPPING_SIGNATURE properties, they use the same mapping. Identifiers that use the same mapping can be compared directly. Service providers that implement IMAPIProp::CopyTo and IMAPIProp::CopyProps can also take advantage of an object's mapping signature. When copying named properties between objects, service providers can avoid the conversion step when the source and destination objects have the same mapping signature.

See also

Reference

IMAPIProp : IUnknown

Concepts

MAPI Named Properties


Handling Named Property Errors

 Copy code hover
[image]

Handling Named Property Errors
See also Send feedback

Published: July 16, 2012

When a request is made to IMAPIProp::GetIDsFromNames or IMAPIProp::GetNamesFromIDs that is too large for the implementer to handle, the error value MAPI_E_TOO_BIG is returned. Callers must divide their request into several requests, calling the appropriate method in a loop.

When a call results in partial success, such as when the request is for names that map to specific identifiers and one or more names cannot be found, GetNamesFromIDs returns MAPI_W_ERRORS_RETURNED and places PT_ERROR in the property type for the missing property in the property tag array.

Sometimes a client makes a call to GetNamesFromIDs that results in no properties being returned, such as when there are no properties in a specified property set, or when all named properties are of a type excluded by the flags. Clients can expect service providers to:

  • Return S_OK.

  • Set the contents of the property tag array pointer to a newly allocated property tag array with its cValues member set to zero.

  • Set the contents of the MAPINAMEID structure array to NULL.

  • Set the contents of the count of MAPINAMEID structures to zero.

See also

Concepts

MAPI Named Properties


Transmitting and Copying Named Properties

 Copy code hover
[image]

Transmitting and Copying Named Properties
See also Send feedback

Published: July 16, 2012

Whenever a named property is sent, moved, or copied, the name remains constant but the identifier must change to adhere to the mapping of the destination object. The only exception to this rule is when the source and destination have the same mapping signature, making remapping unnecessary.

It is the responsibility of the transport provider to remap the names of transmitted named properties to appropriate identifiers that work at the destination. The sending transport provider cannot know what the correct mapping is at the destination; it must transmit the names and rely on the receiving transport provider to map them to identifiers that work. The MAPI implementation of TNEF handles the remapping of named properties for transport providers. Transport providers can either handle the remapping manually or use the TNEF implementation.

A similar remapping of named properties must occur when these properties are copied between message stores. However, because message store providers can retrieve the name to identifier mapping of the destination, they can remap the properties right away and not have to rely on the destination message store.

See also

Concepts

MAPI Named Properties


Commonly Used Property Sets
Send feedback

Published: July 16, 2012

This topic lists commonly used sets of named properties.

Commonly Used Property Sets

The following table lists each property set with its GUID and functional area.

Area | Property Set Name and GUID Value
Common | PS_PUBLIC_STRINGS{00020329-0000-0000-C000-000000000046}
Common | PSETID_Common{00062008-0000-0000-C000-000000000046}
Contact | PSETID_Address{00062004-0000-0000-C000-000000000046}
Email | PS_INTERNET_HEADERS{00020386-0000-0000-C000-000000000046}
Calendar | PSETID_Appointment{00062002-0000-0000-C000-000000000046}
Calendar | PSETID_Meeting{6ED8DA90-450B-101B-98DA-00AA003F1305}
Journal | PSETID_Log{0006200A-0000-0000-C000-000000000046}
Messaging | PSETID_Messaging{41F28F13-83F4-4114-A584-EEDB5A6B0BFF}
Sticky note | PSETID_Note{0006200E-0000-0000-C000-000000000046}
RSS feed | PSETID_PostRss{00062041-0000-0000-C000-000000000046}
Task | PSETID_Task{00062003-0000-0000-C000-000000000046}
Unified messaging | PSETID_UnifiedMessaging{4442858E-A9E3-4E80-B900-317A210CC15B}
Common | PS_MAPI{00020328-0000-0000-C000-000000000046}
Sync | SETID_AirSync{71035549-0739-4DCB-9163-00F0580DBBDF}
Sharing | PSETID_Sharing{00062040-0000-0000-C000-000000000046}
General messaging | PSETID_Report{00062013-0000-0000-C000-000000000046}
Remote messaging | PSETID_Remote{00062014-0000-0000-C000-000000000046}


Property Identifiers and Types

 Copy code hover
[image]

Property Identifiers and Types
Send feedback

Published: July 16, 2012

All MAPI properties are represented by property tags. A property tag is a 32-bit unsigned integer value that contains the property's identifier in the high order 16 bits and the property's type in the low order 16 bits. Property tags for all of the properties defined by MAPI are included in the mapitags.h header file.

Property identifiers are used to indicate what a property is used for and who is responsible for it. Property identifiers are divided by MAPI into ranges; where an identifier falls in the range indicates its use and ownership.

Property types are used to indicate the format of the property's data. MAPI defines all of the valid types. Clients and service providers creating new properties must use one of these types. All of the property types are included in the mapidefs.h header file.


Property Identifier Ranges

 Copy code hover
[image]

Property Identifier Ranges
Send feedback

Published: July 16, 2012

The following table summarizes the different ranges for property identifiers, describing the owner for the properties in each range.

Identifier range | Description
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.
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::GetNamesFromIDs and IMAPIProp::GetIDsFromNames methods.
FFFF | Reserved by MAPI for the special error value PROP_ID_INVALID.

The range between 3000 and 3FFF is reserved for properties that are not related to either messages or recipients. MAPI divides this range into sub-ranges by types of object; the following table shows this further breakdown.

Identifier range | Type of property
3000 - 33FF | Common properties that appear on multiple objects, such as PR_DISPLAY_NAME and PR_ENTRYID.
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


Property Types

 Copy code hover
[image]

Property Types
Send feedback

Published: July 16, 2012

MAPI supports both single-value and multiple-value properties. With a single-value property, there is one value of the base type for the property. With a multiple-value property, there are multiple values of the base type.

The single-value and multiple-value property types that MAPI supports are described in the following table. For each single-value type that has a corresponding multiple-value type, the multiple-value type appears in parentheses after the single-value type.

Property Type | Hex Value | Description
PT_UNSPECIFIED | 0000 | Indicates that the property type is unknown. This property type is reserved for use with interface methods.
PT_NULL | 0001 | Indicates no property value. This property type is reserved for use with interface methods and is the same as the OLE type VT_NULL.
PT_I2 (PT_MV_I2) | 0002 | Signed 16-bit (2-byte) integer. This property type is the same as PT_SHORT (PT_MV_SHORT) and the OLE type VT_I2.
PT_I4 (PT_MV_I4) | 0003 | Signed or unsigned 32-bit (4-byte) integer. This property type is the same as PT_LONG (PT_MV_LONG) and the OLE type VT_I4.
PT_FLOAT (PT_MV_FLOAT) | 0004 | 32-bit (8-byte) floating point value. This property type is the same as PT_R4 (PT_MV_R4) and the OLE type VT_R4.
PT_DOUBLE (PT_MV_DOUBLE) | 0005 | 64-bit (8-byte) floating point value. This property type is the same as PT_R8 and the OLE types VT_R8 and VT_DOUBLE.
PT_CURRENCY (PT_MV_CURRENCY ) | 0006 | 64-bit (8-byte) integer interpreted as decimal. This property type is compatible with the Microsoft Visual Basic CURRENCY type and is the same as the OLE type VT_CY.
PT_APPTIME (PT_MV_APPTIME) | 0007 | Double value that is interpreted as date and time. The integer part is the date and the fraction part is the time. This property type is the same as the OLE type VT_DATE and is compatible with the Microsoft Visual Basic time representation.
PT_ERROR | 000A | SCODE value; 32-bit (4-byte) unsigned integer. This property type is the same as the OLE type VT_ERROR.
PT_BOOLEAN (PT_MV_12) | 000B | 16-bit (2-byte) Boolean value where zero equals false and non-zero equals true. This property type is the same as the OLE type VT_BOOL.
PT_OBJECT | 000D | Pointer to an object that implements the IUnknown interface. This property type is similar to several OLE types such as VT_UNKNOWN.
PT_I8 (PT_MV_I8) | 0014 | Signed or unsigned 64-bit (8-byte) integer that uses the LARGE_INTEGER structure. This property type is the same as PT_I8 and the OLE type VT_I8.
PT_STRING8 (PT_MV_STRING8) | 001E | Null-terminated 8-bit (2-byte) character string. This property type is the same as the OLE type VT_LPSTR.
PT_TSTRING (PT_MV_TSTRING) | 001F | Null-terminated 16-bit (2-byte) character string. Properties with this type have the property type reset to PT_UNICODE when compiling with the UNICODE symbol and to PT_STRING8 when not compiling with the UNICODE symbol. This property type is the same as the OLE type VT_LPSTR for resulting PT_STRING8 properties and VT_LPWSTR for PT_UNICODE properties
PT_SYSTIME (PT_MV_SYSTIME) | 0040 | 64-bit (8-byte) integer data and time value in the form of a FILETIME structure. This property type is the same as the OLE type VT_FILETIME.
PT_CLSID (PT_MV_CLSID) | 0048 | CLSID structure value. This property type is the same as the OLE type VT_CLSID.
PT_SVREID | 00FB | Variable size, a 16-bit (2-byte) COUNT followed by a structure.
PT_SRESTRICT | 00FD | Variable size, a byte array representing one or more Restriction structures.
PT_ACTIONS | 00FE | Variable size, a 16-bit (2-byte) COUNT of actions (not bytes) followed by that many Rule Action structures.
PT_BINARY (PT_MV_BINARY) | 0102 | SBinary structure value, a counted byte array.
Note Note

To determine the Hex value for the multi-valued property type, OR the PT_MV flag (0x00001000) to the Hex value for the property type. For example, the Hex value for PT_MV_UNICODE is 0x101F and the Hex value for PT_MV_BINARY is 0x1102.


Mapping of Internet Mail Attributes to MAPI Properties

 Copy code hover
[image]

Mapping of Internet Mail Attributes to MAPI Properties
Send feedback

Published: July 16, 2012

This appendix describes how a MAPI transport provider or MAPI-aware gateway which connects to the Internet should translate between MAPI message properties and Simple Mail Transport Protocol (SMTP) message attributes. SMTP is the messaging protocol used on much of the Internet. SMTP defines a set of message headers — the message envelope — and a message content format. SMTP is fully documented in a set of two documents, RFC 821 and RFC 822, which can be found at a number of FTP and WWW sites on the Internet.

For information on the SMTP protocol used to communicate with SMTP-based mail agents, see RFC 821, "Simple Mail Transfer Protocol," at http://www.rfc-editor.org.

For addressing and standard message headers, see RFC 822, "Standard for the Format of ARPA Internet Text Messages," at http://www.rfc-editor.org.

For MIME, see RFC 1521, "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies," at http://www.rfc-editor.org.

The goal of mapping SMTP message attributes to MAPI properties (and vice versa) is to ensure that the full content of MAPI messages, over and above that which can be encoded using native SMTP message attributes, can be reliably exchanged among different MAPI components that must communicate over the Internet. This document is based on work already done on such components at Microsoft.

This document assumes familiarity with MAPI transports, TNEF, and SMTP mail. It strives to be concise rather than abundantly clear.

As a convention, "outbound" refers to mail traveling from a MAPI-compliant UA or MTA to the Internet, and "inbound" refers to mail traveling from the Internet to a MAPI component.


SMTP Addresses

 Copy code hover
[image]

SMTP Addresses
Send feedback

Published: July 16, 2012

The format of SMTP e-mail addresses is defined in RFC 822. MAPI components should handle any address that complies with that standard. However, there is a particular form of RFC 822 address that best encodes MAPI addresses:

display-name<email-address>

The angle brackets are included as literals. Blanks are common in display names; they need not be quoted. A typical address might look like this one, which belongs to one of the coauthors of RFC 1521:

Nathaniel Borenstein <nsb@bellcore.com>

If the display name contains characters that have special meaning in SMTP addresses, such as < or @, the entire display name should be enclosed in double quotes. On outbound mail, if the total length of the e-mail address plus display name exceeds 255 characters, the display name should be dropped.

The parts of an SMTP address map into MAPI properties as follows:

SMTP address component | MAPI property
display-name for all recipients | PR_DISPLAY_NAME (PidTagDisplayName)
display-name for From field | PR_SENDER_NAME (PidTagSenderName)
display-name for Sender field | PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName)
email-address | PR_EMAIL_ADDRESS (PidTagEmailAddress)
implicit, always "SMTP" | PR_ADDRTYPE (PidTagAddressType)

If there is no display name for an address on inbound mail, the entire e-mail address should be used instead. The address type is always SMTP.

Recipient properties are taken from the MAPI message's recipient table; sender properties are taken from the message itself.


Message Envelope

 Copy code hover
[image]

Message Envelope
Send feedback

Published: July 16, 2012

RFC 822 headers are mapped to MAPI properties as follows. PR_SENDER_* is an abbreviation for the following 5 properties:

PR_SENDER_NAME (PidTagSenderName)

PR_SENDER_ADDRTYPE (PidTagSenderAddressType)

PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress)

PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey)

PR_SENDER_ENTRYID (PidTagSenderEntryId)

Similar abbreviations are used for PR_SENT_REPRESENTING_* and other groups of message properties.

SMTP header | MAPI property
From: | Outbound: PR_SENDER_*; inbound: PR_SENDER_* and PR_SENT_REPRESENTING_*
Date: | Outbound: current time; inbound: PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)
To: | PR_DISPLAY_NAME (PidTagDisplayName) and PR_EMAIL_ADDRESS (PidTagEmailAddress) for recipients where PR_RECIPIENT_TYPE (PidTagRecipientType) is MAPI_TO
Cc: | PR_DISPLAY_NAME and PR_EMAIL_ADDRESS for recipients where PR_RECIPIENT_TYPE is MAPI_CC
Bcc: | PR_DISPLAY_NAME and PR_EMAIL_ADDRESS for recipients where PR_RECIPIENT_TYPE is MAPI_BCC
Received: | No corresponding MAPI property; put local host name and your component name here
Return-receipt-to: | PR_REPORT_NAME (PidTagReportName) and PR_REPORT_ENTRYID (PidTagReportEntryId)
Reply-to: | PR_REPLY_RECIPIENT_ENTRIES (PidTagReplyRecipientEntries) and PR_REPLY_RECIPIENT_NAMES (PidTagReplyRecipientNames)
Subject: | PR_SUBJECT (PidTagSubject) No particular length limitation.
MIME-version: | Always "1.0"
X-MS-Attachment: | For compatibility with MS Mail SMTP gateway.filename size mm-dd-yyy hh:mm Details below.
entire SMTP message envelope | PR_TRANSPORT_MESSAGE_HEADERS (PidTagTransportMessageHeaders)
header name TBD | PR_SEND_RICH_INFO (PidTagSendRichInfo) for sender only. The TBDheader should be used to determine whether the sender is capable of interpreting TNEF content in a reply.
MessageID: | PR_TNEF_CORRELATION_KEY (PidTagTnefCorrelationKey)
Content-type | Either text/plain or multipart/mixed. See "Message Content" section.

The X-MS-Attachment header is formatted as four tokens, separated by a space:

name size date time

The first token is the filename, which may contain embedded spaces, so this header should be parsed from the right on inbound messages. The size is in bytes; the date is formatted as mm-dd-yyyy, and the time as hh:mm.

Note Note

MessageID is not mapped to PR_SEARCH_KEY because the SMTP domain has specific requirements on the format of the message identifier which make it impossible to encode an arbitrary MAPI message identifier. Instead, MessageID is mapped to PR_TNEF_CORRELATION_KEY. This property is a transport-defined property that is set by the transport sending an outbound message and used by a transport receiving an inbound message. For more information, see Developing a TNEF-Enabled Transport Provider.


Message Content

 Copy code hover
[image]

Message Content
Send feedback

Published: July 16, 2012

There are two possible encodings for the message content: one using MIME, the other using uuencode. MIME is the preferred encoding. In addition, MAPI defines a per-recipient property, PR_SEND_RICH_INFO (PidTagSendRichInfo), which governs whether or not TNEF information should be included in an outgoing message. So there are a total of four ways of encoding message content:

  • MIME with TNEF

  • MIME without TNEF

  • uuencode with TNEF

  • uuencode without TNEF

How to choose MIME or uuencode for outbound messages is not specified.

The following properties are excluded from TNEF: PR_SENDER_*, PR_ATTACH_DATA_*, PR_BODY. All other transmittable message properties are included in the TNEF stream.

The following suggestions are intended to provide a list of parameters that the implementation can decide how to support:

  • Whether to encode using MIME or uuencode for outbound messages: boolean.

  • Character set to use for outbound messages: string (copied directly to charset parameter) or enumeration (translated internally to charset string).


Message Text

 Copy code hover
[image]

Message Text
Send feedback

Published: July 16, 2012

For outbound messages in MIME mode, the content-type depends on whether there are attachments and what the message text looks like. If there are attachments, the Content-type is multipart/mixed; the message text and each attachment become a separate part of the message content, each with its own content-type. If there are no attachments, the content-type of the message is text/plain and there is only one part.

The message text is not line-wrapped unless some line exceeds 140 characters in length. If one does, the entire text is wrapped to 76 columns and the quoted-printable encoding is used to preserve line breaks. The content-type depends on what characters are found in the message text, as follows:

  • If only 7-bit characters are found and no line exceeds 140 characters in length, the message is ASCII text. Content-type: text/plain; charset=us-ascii (Content-Transfer-Encoding=7bit is assumed.)

  • If long lines or 8-bit characters are found, the message is text and the character set is determined by the locale. It should be chosen from the character sets defined by ISO standard 8859. Content-type: text/plain; charset=iso-8859-1 (or another valid charset)

    Content-Transfer-Encoding: quoted-printable

For inbound MIME messages, if the first message content part has Content-type: text/* (that is, any text type) and its character set is recognized, it is mapped to PR_BODY (PidTagBody). A first message content part not meeting this criterion becomes an attachment. Any subsequent parts also become attachments.

In uuencode mode, message text in outbound messages is line-wrapped to 78 columns, as for MS Mail 3.x. The content-type is "text/plain." To preserve the original message's paragraph breaks under these circumstances, observe the following conventions in the wrapped text. There are three possible reasons for ending a line of text, each with its own character sequence:

  • Line-break. The original text contained a newline entered by the user (paragraph mark). In the transport, this maps to a newline with no preceding blanks. If the user enters a newline preceded by blanks, the blanks should be stripped out.

  • Line-nobreak. The original text contained a word too long to fit on a single line of the message. In the transport, this maps to a newline preceded by two blanks.

  • Line-wrap. The original text contained no newline, the text is too long to fit on a single line of the message, but it can be broken between two words. In the transport, this maps to a newline preceded by a single blank.


Attached Files and Messages

 Copy code hover
[image]

Attached Files and Messages
See also Send feedback

Published: July 16, 2012

If MIME with TNEF is used while encoding message content,all attachment properties and content are in the TNEF stream. The TNEF itself is a single, binary attached file named Winmail.dat, encoded as described for MIME without TNEF.

If MIME is used without TNEF, attached files are sent as MIME message content parts. The filename is placed in the name parameter to the Content-type header for the attachment. The character set for the attachment is placed in the charset parameter to the Content-type; it and the content-transfer-encoding are determined by scanning the entire attachment content. URL attachments are treated specially:

  • If the attachment is a URL (an attached file with extension .URL), and the access mode defined in it is anonymous FTP, it is encoded as an external message, and the content of the file (the URL) is copied into the header of the external message. Content-type: message/external-body; access-type=anon-ftp(Content-Transfer-Encoding: 7bit is assumed.)

  • If only 7-bit characters are found and no line exceeds 140 characters in length, the attachment is ASCII text. Content-type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit

  • If long lines or up to 25% 8-bit characters are found, the attachment content is text and the character set is determined by the locale. It should be chosen from the character sets defined by ISO standard 8859. Content-type: text/plain; charset=ISO-8859-1(for example)

    Content-Transfer-Encoding: quoted-printable

  • If 25% or more of the characters have the high bit set, the attachment is binary. It is encoded using the Base64 algorithm. Content-type: application/octet-stream (by default; based on file extension)

    Content-Transfer-Encoding: base64

On outbound messages, the content-type should be derived from the filename's three-letter extension. This mapping exists in the system registry; under there is a string value named "Content Type" that gives the MIME content type if one is defined. This example is for a TIFF image file:

HKEY_LOCAL_MACHINE\

Software\

Microsoft\

Classes\

.tif

Content Type = "image/tiff"

If there is no mapping for the file extension, the default application/octet stream should be used.

On inbound messages, the content-type for an attachment should always be copied to the MAPI property PR_ATTACH_MIME_TAG (PidTagAttachMimeTag). Even if a filename is defined for an attached file, the extension mapped by the content-type should be used in the PR_ATTACH_FILENAME (PidTagAttachFilename) and PR_ATTACH_EXTENSION (PidTagAttachExtension) properties.

The name parameter is officially deprecated by RFC 821. As standards evolve, Microsoft will consider specifying an alternate mapping for attached filenames.

Outbound attached messages are sent as Content-type: message/rfc822 Messages within attached messages are encoded recursively, in their proper place. Inbound message content parts with Content-Type: multipart/digest are also mapped to embedded messages.

If uuencode with TNEF is used while encoding message content, all attachment properties and content are in the TNEF stream. The TNEF itself is a single, binary attached file named Winmail.dat, encoded as described for Uuencode without TNEF.

If uuencode is used without TNEF, all attached files are treated as binary and uuencoded, following the message text. The file name is present in the uuencode header:

begin 0755 Winmail.dat

... data ...

end

Attached messages are textized into the message text. The hierarchy of attached messages is always flattened; that is, messages within attached messages are pulled out to the top level.

Embedded OLE objects are discarded.

Attachment rendering positions are transmitted literally, using the property PR_ATTACH_RENDERING (PidTagAttachRendering) in the TNEF. If TNEF is not used, they are lost. Incoming attachments with no rendering position (including when there is no TNEF) have their rendering position set to 0xFFFFFFFF, that is, no position in the message text.

See also

Concepts

Mapping of Internet Mail Attributes to MAPI Properties


MAPI Service Providers

 Copy code hover
[image]

MAPI Service Providers
See also Send feedback

Published: July 16, 2012

There are three common types of service providers:

  • Address book providers.

  • Message store providers.

  • Transport providers.

Address book and message store providers have many similarities. They register a unique identifier with MAPI that they use for constructing entry identifiers for their objects. They provide a hierarchy of objects and properties that clients can access and manipulate. For their container objects, they support a hierarchy table and a contents table. They support event notification on these tables and optionally on individual objects so that clients can be informed of changes that occur during the session. When operations become lengthy, they can display a progress indicator to inform the user of the operation's status. Clients can communicate with address book and message store providers either indirectly through MAPI by using the IAddrBook : IMAPIProp and IMAPISession : IUnknown interfaces or directly by using one of the service provider interfaces in the following table.

Address book provider interfaces | Message store provider interfaces
IABContainer : IMAPIContainer | IMsgStore : IMAPIProp
IDistList : IMAPIContainer | IMAPIFolder : IMAPIContainer
IMailUser : IMAPIProp | IMessage : IMAPIProp
 | IAttach : IMAPIProp

Transport providers differ from address book and message store providers in the way they communicate with MAPI and with clients. Transport providers typically wait for MAPI to prompt them for information rather than initiate communication. Unlike the other providers, transport providers do not support a variety of objects and tables that are commonly accessed by clients. However, they do support a status object, as do all service providers, and publish its properties in the status table. Whereas address book and message store providers call the IMAPISupport::SetProviderUID method to register unique identifiers for constructing their entry identifiers, transport providers call the IXPLogon::AddressTypes method to register unique identifiers, as well as address types for assuming responsibility for the delivery of particular messages.

Your service provider should have three header files: one public header file and two internal files. Use the public header file for configuration and for documenting properties and their values. Include in one of the internal header files all the necessary public MAPI headers; this header file should be included in all of your service provider source files. Use the other internal file to define resource identifiers.

Address book, message store, and transport providers perform the following tasks:

  • Supply an entry point function.

  • Supply a provider and logon object to handle logon and initialization.

  • If the provider belongs to a message service, supply a message service entry point function.

  • Support configuration by implementing a property sheet.

  • Implement a status object and support the status table.

  • Handle shut down.

See also

Other resources

MAPI Concepts


Service Provider Development Basics

 Copy code hover
[image]

Service Provider Development Basics
See also Send feedback

Published: July 16, 2012

This section contains overview information that you should review prior to creating your own MAPI service providers.

See also

Concepts

Developing a MAPI Address Book Provider
Developing a MAPI Transport Provider
Developing a MAPI Message Store Provider
MAPI Service Providers
MAPI Service Provider Overview


Support Object Overview

 Copy code hover
[image]

Support Object Overview
See also Send feedback

Published: July 16, 2012

MAPI furnishes a support object, an object that implements the IMAPISupport : IUnknown interface, for all service providers during logon and for all message services during configuration.

Support objects are not accessible by clients; they are implemented by MAPI and called only by service providers. The IMAPISupport interface is specified in the Mapispi.h header file. Its identifier is IID_IMAPISup and its pointer type is LPMAPISUP. No MAPI properties are exposed by support objects.

A provider can be given one or more support objects, depending on the number of times MAPI logs the provider on or the number of times the provider's message service entry function is called. Typically, a provider will be logged on at least once per session. Address book and transport providers are logged on every time a client starts a session with a profile entry that requests them. Message store providers are logged on every time a client calls the IMAPISession::OpenMsgStore method.

In the case of multiple logons in a session, you can choose either to retain and use each support object separately or to retain and use only the first, discarding each subsequent support object. To retain a support object, call its IUnknown::AddRef method. Calling AddRef on a support object that you want to retain throughout a session is extremely important; if the call is not made, MAPI releases the support object and frees its memory.

The purpose of the support object is to provide implementations for a fairly large number of methods commonly used by the providers. Each support object also contains contextual data specific to its own instance, such as the session the provider is running in, the profile section the provider is using, and error information for the session.

There are four different types of support objects: one for each major provider type (address book, message store, and transport) and one for configuration support.

MAPI customizes each support object by including implementations of methods that are relevant for its usage. Implementations of some methods, such as IMAPISupport::OpenProfileSection, are included in all support objects. Implementations of other methods, such as IMAPISupport::SpoolerNotify, apply only to particular support objects. Only message store and transport providers can use this method; when an address book provider or a message service try to call it, MAPI returns MAPI_E_NO_SUPPORT.

Support objects can be used to accomplish many tasks, such as the following:

  • Accessing a profile section.

  • Copying folders or messages. For more information, see Copying or Moving a Message or a Folder.

  • Accessing objects that belong to other providers. For more information, see Supporting Object Access and Comparison.

  • Handling event notification. For more information, see Supporting Event Notification.

  • Allocating and freeing memory.

  • Obtaining a unique identifier.

  • Invalidating objects.

  • Handling errors.

  • Registering message preprocessors.

  • Preparing message delivery reports.

At logon time, MAPI calls the logon method of each service provider's provider object. For address book providers, MAPI calls IABProvider::Logon. For message store providers, MAPI calls IMSProvider::Logon. For transport providers, MAPI calls IXPProvider::TransportLogon. MAPI passes a pointer to the appropriate support object in one of the parameters to this method. The logon method in turn instantiates a logon object, passing it the support object pointer. The logon object calls the support object's IUnknown::AddRef method to retain it, if necessary. For more information about the logon process for service providers, see Starting a Service Provider.

When a client logs off, MAPI calls the logon object's logoff method. The logoff method calls the support object's IUnknown::Release method to indicate that the provider no longer intends to call any of the support methods. As with logon, the logoff methods have slightly different names. The IABLogon and IMSLogon interfaces have Logoff methods; the IXPLogon interface has a TransportLogoff method.

Message service entry point functions are called when a logon attempt fails with the error MAPI_E_UNCONFIGURED or when a client initiates a configuration request. MAPI instantiates a configuration support object and calls the message service entry point function for either the unconfigured provider or the provider whose configuration is about to change. Unlike the other support objects, configuration support objects are valid only until the entry point function returns; message services do not call these objects' AddRef methods to retain them.

Typically, MAPI makes calls to a provider's message service entry point function, but sometimes a provider is asked to make the call. This can occur when a client calls a provider's IMAPIStatus::SettingsDialog method to prompt the provider to display its configuration property sheet. SettingsDialog should call IMAPISupport::GetSvcConfigSupportObj to obtain a configuration support object that it can pass to the message service entry point function.

The IMAPISupport::GetMemAllocRoutines method is available for determining the addresses of the memory allocation and deallocation functions without having to link with MAPI. Using GetMemAllocRoutines also makes it easier to trace memory leaks by surrounding the allocation function calls with debugging code. If you call GetMemAllocRoutines, as is recommended, do so before calling the CreateIProp function, which requires the allocation function addresses as parameters.

When you need to create a new address book or message store object, create and set a search key for the object in its PR_SEARCH_KEY (PidTagSearchKey) property. Call IMAPISupport::NewUID to obtain a unique identifier to use in building a search key. Do not use your own hard-coded MAPIUID. A provider's MAPIUID should be used only for entry identifiers. For more information about constructing search keys, see MAPI Record and Search Keys.

A client application can sometimes release an object without releasing one or more of its affiliated objects. In such a case, a provider may need to render an unreleased object unusable. To do this, the provider frees all of the resources connected with the object and then calls IMAPISupport::MakeInvalid to invalidate the object's vtable. MakeInvalid replaces the vtable's IUnknown methods (QueryInterface, AddRef, and Release) with standard MAPI implementations and causes all other methods to return MAPI_E_INVALID_OBJECT. MakeInvalid also frees all the object's memory other than the vtable.

See also

Concepts

MAPI Service Providers


Starting a Service Provider

 Copy code hover
[image]

Starting a Service Provider
See also Send feedback

Published: July 16, 2012

At some point after a client starts a session with MAPI, your service provider will be started. Transport providers are started when a client makes a request for their services. Address book and message store providers are started during the client's logon process.

A client calls IMAPISession::OpenAddressBook to load each of the address book providers included in the profile and IMAPISession::OpenMsgStore to load a specific message store provider. Address book providers that are part of a message service are started before any of the other providers in the service.

MAPI starts each service provider in the active profile by doing the following:

  • Locating the name of its DLL in the profile. You are required to register the name of your provider DLL in the Mapisvc.inf configuration file to ensure that it appears in the profile. When your service provider is added to a profile, either individually or as part of a message service, all of the [Service Provider] sections from Mapisvc.inf that apply to your provider are copied into the profile. For more information about the structure of Mapisvc.inf, see File Format of MapiSvc.inf.

  • Calling the Windows API function LoadLibrary to load the DLL. Because MAPI calls LoadLibrary either every time it uses a service provider DLL (regardless of whether it has already been loaded) or only the first time, your service provider must not make assumptions about the number of times that it will be loaded. For every call to LoadLibrary, MAPI makes a call to the Windows API function FreeLibrary when a service provider DLL is no longer needed.

  • Calling the entry point function for the provider. MAPI calls your provider's entry point function to initiate the logon process. Entry point functions ensure that you are using a version of the service provider interface (SPI) that is compatible with the version being used by MAPI. These functions also return pointers to newly created provider objects. For more information about creating an entry point function for your provider, see Implementing a Service Provider Entry Point Function.

See also

Concepts

MAPI Service Providers


Implementing a Service Provider Entry Point Function

 Copy code hover
[image]

Implementing a Service Provider Entry Point Function
See also Send feedback

Published: July 16, 2012

Every service provider DLL has an entry point function that MAPI calls to load it. Be aware that this entry point function is not the same as DllMain, the Win32 DLL entry point function.

Depending on the type of your provider, your provider entry point function conforms to a different prototype. MAPI defines different entry point function prototypes for service providers.

Provider | Entry point function prototype
Message store providers | MSProviderInit
Transport providers | XPProviderInit
Address book providers | ABProviderInit

Much of the functionality in these prototypes is the same for all service provider types.

Address book, message store, and transport providers perform the following two main tasks in their entry point functions:

  1. Check the version of the service provider interface (SPI) to be sure that MAPI is using a version that is compatible with the version that your service provider is using. Use the lpulMAPIVer parameter, which contains the MAPI SPI version, and the lpulProviderVer parameter, which contains your SPI version, to perform the check. These parameters are 32-bit unsigned integers composed of three parts:

    • Bits 24 through 31 represent the major version.

    • Bits 16 through 23 represent the minor version.

    • Bits 0 through 15 represent the update identifier. Although the major version number rarely changes, the minor version number changes whenever MAPI is released and the SPI has changed. The update identifier is the Microsoft internal build version; it is used to track changes during the development process. MAPI defines the CURRENT_SPI_VERSION constant, documented in the Mapispi.h header file, to indicate the present SPI version. Fail your check with the error MAPI_E_VERSION if you are using a version of the SPI that is newer than the version that MAPI is using.

  2. Create an instance of a provider object. Because your provider can be started and initialized multiple times, you should create a new instance each time this occurs. Providers are started multiple times when they appear in multiple profiles that are in use simultaneously by one or more clients, or when they appear multiple times in a single profile. Just as the entry point function prototype differs depending on the type of your provider, so does the type of provider object.

    If you are writing an address book provider, implement IABProvider : IUnknown. If you are writing a message store provider, implement IMSProvider : IUnknown. For more information, see Loading Message Store Providers.

    If you are writing a transport provider, implement IXPProvider : IUnknown. For more information, see Initializing the Transport Provider.

See also

Concepts

Starting a Service Provider


Implementing Service Provider Logon

 Copy code hover
[image]

Implementing Service Provider Logon
See also Send feedback

Published: July 16, 2012

MAPI calls a method in your provider object to begin the logon process by using the pointer that you return from your entry point function. The method varies as follows, depending on the type of your service provider:

  • IABProvider::Logon for address book providers

  • IMSProvider::Logon for message store providers

  • IXPProvider::TransportLogon for transport providers

Perform the following tasks in whatever logon method you implement:

  1. Increment the reference count on the support object that is passed as an input parameter by calling its IUnknown::AddRef method.

  2. Call the support object's IMAPISupport::OpenProfileSection method to access your profile section.

  3. Call the profile section's IMAPIProp::SetProps method to set the following properties:

    • PR_DISPLAY_NAME (PidTagDisplayName)

    • PR_ENTRYID (PidTagEntryId)

    • PR_PROVIDER_DISPLAY (PidTagProviderDisplay)

    • PR_RECORD_KEY (PidTagRecordKey)

      Note Note

      Do not attempt to set the profile section's PR_RESOURCE_FLAGS or PR_PROVIDER_DLL_NAME properties. At logon time, these properties are read-only.

  4. Check that the properties you need for configuration are either stored in the profile or are available from the user. For more information about checking your configuration, see Verifying Service Provider Configuration.

  5. Call the support object's IMAPISupport::SetProviderUID method to register a unique identifier, or MAPIUID, if your provider is an address book or message store provider. Transport providers register MAPIUID structures when MAPI calls their IXPLogon::AddressTypes method. For more information about registering a MAPIUID, see Registering Service Provider Unique Identifiers.

  6. Instantiate a logon object and return with one of the following values:

    • S_OK to indicate a successful logon.

    • MAPI_E_UNCONFIGURED to indicate that one or more of the configuration properties were unavailable.

    • MAPI_E_USER_CANCEL to indicate that the user canceled the configuration dialog box, causing configuration properties to be unavailable.

    • MAPI_E_FAILONEPROVIDER to indicate that your provider could not be configured, but that MAPI should allow it to be used regardless. Logon methods should return this value to report a nonfatal error, such as when the provider requires a password and cannot prompt the user for it because the user interface is disabled.

The preceding list of tasks describes a minimum implementation for a service provider logon method. You can include additional functionality, if necessary. For example, some providers call IMAPISupport::ModifyStatusRow to update the status table in their logon method.

Note Note

To achieve the best performance at logon time, avoid calling either IMAPISupport::PrepareSubmit or IMAPISupport::SpoolerNotify. Before these calls can complete and return control to your logon method, the MAPI spooler must be started.

See also

Concepts

Starting a Service Provider


Verifying Service Provider Configuration

 Copy code hover
[image]

Verifying Service Provider Configuration
See also Send feedback

Published: July 16, 2012

Your logon method (IABProvider::Logon, IMSProvider::Logon, or IXPProvider::TransportLogon) must verify your provider's configuration. This involves checking that all of the properties needed for full operation are set correctly. Every provider requires a different number of properties; configuration depends on your provider and the degree of user interaction you allow. Some service providers keep all of the necessary properties in the profile. Other service providers keep a partial set of properties in the profile and prompt the user for missing values. Still other providers do not store properties in the profile at all, relying on the user to supply all of the information needed for configuration.

To retrieve properties stored in the profile

  1. Call IMAPISupport::OpenProfileSection, passing the MAPIUID of your provider as an input parameter.

  2. Call the profile section's IMAPIProp::GetProps or IMAPIProp::GetPropList methods to retrieve individual properties or a property list.

To set properties from user information

Display a property sheet, if MAPI has not set a flag prohibiting the display. The following flags indicate that a user interface cannot be presented.

Flag | Service provider
AB_NO_DIALOG | Address book provider
LOGON_NO_DIALOG | Transport provider
MDB_NO_DIALOG | Message store provider

If your provider does not store all of its configuration properties in the profile, requiring user interaction, and MAPI passes one of the dialog box suppression flags to your logon method, return MAPI_E_UNCONFIGURED. Also return this error when the dialog suppression flag is not set, but the user does not supply all of the required information.

When your service provider fails its logon method with MAPI_E_UNCONFIGURED, MAPI calls your entry point function again. If the information cannot be located with the second call, the session might terminate, depending on how important your service provider is.

The following illustration shows the logic required for configuration in your service provider logon method.

Configuration verification flowchart

Configuration verification flowchart

See also

Concepts

Implementing Service Provider Logon


Implementing a Logon Object

 Copy code hover
[image]

Implementing a Logon Object
See also Send feedback

Published: July 16, 2012

Every address book, message store, and transport provider instantiates a logon object as part of its implementation of IABProvider::Logon, IMSProvider::Logon, or IXPProvider::TransportLogon. Logon objects implement methods that help MAPI service client requests. Depending on your type of service provider, your logon object will support one of the following interfaces.

Logon object interface | Service provider
IABLogon : IUnknown | Address book provider
IMSLogon : IUnknown | Message store provider
IXPLogon : IUnknown | Transport provider

Address book and message store providers implement the following features in their logon objects:

  • Support for event notification (Advise and Unadvise methods). For an overview of event notification, see Event Notification in MAPI. For more information about supporting notification in your logon object, see Supporting Event Notification.

  • Entry identifier comparison (CompareEntryIDs method). For general information about entry identifiers, see MAPI Entry Identifiers. For more information about comparing entry identifiers in your logon object's CompareEntryIDs method, see Supporting Object Access and Comparison.

  • Access to additional error information (GetLastError method). For more information about handling errors in MAPI, see Error Handling in MAPI.

  • Access to objects implemented by the service provider (OpenEntry method). For more information, see Supporting Object Access and Comparison.

  • Access to a status object (OpenStatusEntry method). For general information about status objects, see MAPI Status Objects. For specific information about implementing a status object, see Status Object Implementation.

  • A logoff process (Logoff method). For more information, see Shutting Down a Service Provider.

If your provider is an address book provider, you will also implement the following methods and associated features:

  • IABLogon::GetOneOffTable to provide a listing of the templates that you support for creating new recipients. For more information, see One-Off Tables or Implementing a Provider One-Off Table.

  • IABLogon::OpenTemplateID to provide access to the implementation of a recipient whose data resides in a host address book provider. For more information, see Acting as a Foreign Address Book Provider.

  • IABLogon::PrepareRecips to ensure that the appropriate properties are available for all of the recipients in a recipient list. For more information, see IABLogon::PrepareRecips.

A transport provider's logon object, which implements IXPLogon : IUnknown, is quite different from the logon objects implemented by the other types of service providers. It has only two features in common with the other logon objects: access to a status object through the IXPLogon::OpenStatusEntry method and a logoff operation through the IXPLogon::TransportLogoff method. Transport providers implement the following unique features in their logon objects:

  • Registration for address types (IXPLogon::AddressTypes method). For more information about registering an address type, see Transport Provider and MAPI Spooler Operational Model.

  • Control of message transmission (IXPLogon::StartMessage, IXPLogon::EndMessage, and IXPLogon::SubmitMessage methods). For more information, see Message Reception Model, Interacting with the MAPI Spooler, and Message Submission Model.

  • Internal state validation (IXPLogon::ValidateState method).

  • Ability to download or upload messages on demand (IXPLogon::FlushQueues method). For more information, see Implementing the FlushQueues Method.

  • Ability to query for pending messages (IXPLogon::Poll method). For more information, see Message Reception Model.

  • Idle state detection (IXPLogon::Idle method).

  • Interaction with the MAPI spooler (IXPLogon::TransportNotify method).

See also

Concepts

Implementing Service Provider Logon


Registering Service Provider Unique Identifiers

 Copy code hover
[image]

Registering Service Provider Unique Identifiers
See also Send feedback

Published: July 16, 2012

Address book, message store, and transport providers use a unique identifier known as a MAPIUID to register to service objects of various types. A MAPIUID is a 16-byte identifier that contains a GUID. You can create a MAPIUID by using the following procedure:

  1. Define a constant.

  2. Invoke the Visual Studio Create GUID tool.

For example, an address book provider might include the following constant in a header file to define a MAPIUID:

#define AB_UID_PROVIDER { 0Xe3, 0x3c, 0x67, 0xa0, \ 0xc8, 0x1f, 0x11, 0xce, \ 0xb2, 0xe4, 0x0, 0xaa, \ 0x0, 0x51, 0xe, 0x3b }

To register a MAPIUID if your provider is an address book or message store provider

  1. Call IMAPISupport::SetProviderUID.

  2. Register a MAPIUID for each logon object that you instantiate and include this MAPIUID in the first 16 bytes of the ab member of every entry identifier that you create. MAPI uses MAPIUID structures to associate objects with service providers. When a client calls the IMAPISession::OpenEntry method to open an object, MAPI examines the MAPIUID portion of the entry identifier, matching it against the registered MAPIUID, to determine which logon object should receive the open request.

  3. If your provider is a transport, register one or more MAPIUID structures when MAPI calls your IXPLogon::AddressTypes method. MAPI uses the MAPIUID structures registered by transport providers to assign responsibility for message delivery.

Although service providers typically register a single MAPIUID, you can register multiple MAPIUID structures. If your address book or message store provider supports multiple logon objects, perhaps by permitting a user to add more than one instance of your provider to their profile, you might want to implement a different MAPIUID for each logon object. There are a few other reasons to support more than one MAPIUID:

  • You must support more than one version of your provider and the entry identifiers must represent the appropriate version. Assign a different MAPIUID for each version.

  • You want to distinguish between the types of objects you support. For example, an address book provider might want to register one MAPIUID to use in the entry identifiers of its messaging user objects and a different MAPIUID to use for distribution lists.

When there are multiple logon objects that are concurrently active, it makes sense to have unique MAPIUID structures for each one. This increases the accuracy with which MAPI matches entry identifiers to service providers and saves some work. When every logon object has its own unique identifier, MAPI can guarantee that any request it routes to a logon object can be handled by that object. When logon objects share MAPIUID structures, MAPI routes the request to the first logon object that is identified by the MAPIUID. If one of your logon objects receives a request that it cannot process because it does not handle the entry identifier, pass the request on to your next logon object before returning an error.

See also

Concepts

Implementing Service Provider Logon


Shutting Down a Service Provider

 Copy code hover
[image]

Shutting Down a Service Provider
See also Send feedback

Published: July 16, 2012

When a client calls the IMAPISession::Logoff method to end the session and shut down all active service providers, MAPI in turn calls the following methods:

  • IABLogon::Logoff for address book providers.

  • IMSLogon::Logoff for message store providers.

  • IXPLogon::TransportLogoff for transport providers.

These methods have similar implementations. The main tasks that a logoff method performs are as follows:

  • Releasing all open objects, including subobjects and status objects.

  • Calling the support object's IUnknown::Release method to decrement its reference count.

  • Removing all of your provider's registered MAPIUID structures.

  • Removing your provider's row in the status table.

  • Performing any tasks that relate to cleaning up resources, such as the following:

    • Terminating a connection with a remote server.

    • Decrementing the reference count on the logon object.

    • Removing the logon object from the list of logon objects that your provider stores.

    • In debug mode, issuing traces to locate objects that have leaked memory.

When your logoff method returns, MAPI calls the following:

  • Your logon object's IUnknown::Release method.

  • Your provider object's Shutdown method to perform any final cleanup tasks. Depending on the type of your provider, one of the following methods is called:

    • IABProvider::Shutdown for address book providers

    • IMSProvider::Shutdown for message store providers

    • IXPProvider::Shutdown for transport providers

  • Your provider object's IUnknown::Release method.

If your provider is a message store, a client call to IMsgStore::StoreLogoff will also initiate the shutdown process. StoreLogoff shuts down one particular message store provider and has no effect on the session. Only a message store provider can be shut down with this method; there is no explicit way to shut down a particular address book or transport provider. For information about how to respond to a StoreLogoff call, see Shutting Down a Message Store Provider.

Your provider's DLL will be unloaded when MAPI calls the Win32 API function FreeLibrary, a call that is made after the last active client has called MAPIUninitialize. By this time, your service provider will have finished shutting down.

See also

Concepts

MAPI Service Providers


Shutting Down a Message Store Provider

 Copy code hover
[image]

Shutting Down a Message Store Provider
See also Send feedback

Published: July 16, 2012

If your provider is a message store provider, it can be shut down in one of the following ways:

  • When a client or the MAPI spooler calls IMsgStore::StoreLogoff. Shutting down a message store provider with StoreLogoff causes the shutdown to occur in an orderly and controlled manner.

  • When a client calls IMAPISession::Logoff.

Your implementation of IMsgStore::StoreLogoff should begin by calling IMAPISupport::StoreLogoffTransports to inform MAPI that it is being shut down, indicating that any related transport providers should be logged off. When IMsgStore::StoreLogoff returns, its caller invokes your message store's IUnknown::Release method. Implement this Release method by calling the support object's IUnknown::Release method.

MAPI performs the following tasks in its implementation of IUnknown::Release for message stores:

  1. Removes all of the MAPIUID structures registered by the message store provider.

  2. Removes the message store provider's row from the status table.

  3. Calls IMSLogon::Logoff to release all open objects, subobjects, and status objects.

  4. Calls IUnknown::Release to release the message store provider's logon object.

Some clients might omit the call to IMsgStore::StoreLogoff, initiating the shutdown of your message store provider with the call to the message store's IUnknown::Release method. A shutdown under these circumstances without the call to StoreLogoff is less orderly and controlled. Write your message store's Release method to handle this possibility and keep track of whether or not a call to IMAPISupport::StoreLogoffTransports has occurred. StoreLogoffTransports must be called once during the shutdown process. If you detect in your Release method that StoreLogoffTransports has not yet been called, invoke it with the LOGOFF_ABORT flag.

See also

Concepts

Shutting Down a Service Provider


Invalidating an Object

 Copy code hover
[image]

Invalidating an Object
See also Send feedback

Published: July 16, 2012

As part of your provider's shutdown process, you might want to invalidate an object. Invalidating an object involves replacing its vtable with a vtable that contains implementations for the three IUnknown methods: AddRef, Release, and QueryInterface. Invalidate an object by calling IMAPISupport::MakeInvalid, a method that is included in the support object of each of the three common provider types. Providers typically make this call in the implementation of their logon object's Logoff method.

Invalidating an object gives MAPI the ultimate responsibility for freeing the memory associated with an object. You can free all of the resources connected with an object and then call MakeInvalid to invalidate all of the methods in its inherited interfaces. Calls to any of these methods will return MAPI_E_INVALID_OBJECT. Using MakeInvalid is an option that many service providers choose to ignore.

See also

Concepts

Shutting Down a Service Provider


Supporting Object Access and Comparison

 Copy code hover
[image]

Supporting Object Access and Comparison
See also Send feedback

Published: July 16, 2012

Service providers can use the IMAPISupport::OpenEntry and IMAPISupport::CompareEntryIDs methods to open and compare objects that belong to their provider or to other providers:

Like IMAPISession::OpenEntry for clients, providers can use their support object's OpenEntry method to access any object as long they know the object's entry identifier. Unlike the session method, the support method requires that you specify a valid entry identifier in the lpEntryID parameter. It cannot be NULL.

To illustrate how a transport provider might use IMAPISupport::OpenEntry, consider the following scenario. The transport provider has received a message formatted in Rich Text Format and does not know whether the target recipient can handle this format. Before delivering the message, the transport provider needs to do the following:

  1. Call the message's IMessage::GetRecipientTable method to access the recipient table and the recipient's entry identifier, its PR_ENTRYID (PidTagEntryId) property.

  2. Pass the entry identifier to IMAPISupport::OpenEntry to open the recipient, typically either a messaging user or distribution list. The lpInterface parameter should be set to NULL because the provider cannot know ahead of time the object type of the recipient. The support object's OpenEntry method calls IMAPISession::OpenEntry to determine the address book provider responsible for the recipient. The session object then calls the appropriate address book provider's OpenEntry method to open the recipient and return an interface pointer to the transport provider.

  3. Call the recipient's IMAPIProp::GetProps method to retrieve its PR_SEND_RICH_INFO (PidTagSendRichInfo) property. If PR_SEND_RICH_INFO is set to TRUE, the recipient can handle formatted text.

If you have opened several objects from other providers, you may need to find out whether two entry identifiers refer to the same object. For example, you may have a short-term entry identifier and a long-term entry identifier and these identifiers may or may not identify the same object. To avoid redundant processing, call the IMAPISupport::CompareEntryIDs method to compare these entry identifiers. You must use this method for entry identifier comparison because entry identifiers cannot be compared directly.

See also

Concepts

MAPI Service Providers


Supporting Event Notification

 Copy code hover
[image]

Supporting Event Notification
See also Send feedback

Published: July 16, 2012

Because supporting event notification can be complicated, MAPI supplies three support object methods that implement the most difficult parts of the process. These methods work as a unit, and a provider must use all three or none of them.

The MAPI support methods use notification keys to manage the connections between the advise sinks and the objects that generate the notifications. A notification key is a NOTIFKEY structure that contains binary data that identifies an object across processes. A notification key is typically copied from the long-term entry identifier of the advise source object. If the client has supplied an entry identifier in the call to Advise, you can use it for the notification key. If the lpEntryID parameter to Advise is NULL, use the entry identifier of the outermost possible container object, such as the message store.

To use the support methods, call IMAPISupport::Subscribe whenever a client calls your Advise method to register for a notification. Allocate a NOTIFKEY structure and create a unique notification key for your advise source object. For example, a message store provider that is prompted to notify a client when a message is received into a particular folder creates a notification key for that folder. Pass a pointer to the NOTIFKEY structure in the call to Subscribe along with a pointer to the client's advise sink. Subscribe calls the advise sink's IUnknown::AddRef method to increment its reference count and MAPI retains the pointer until the registration is canceled.

You can pass the NOTIFY_SYNC flag to Subscribe to request that Notify behave synchronously and not return until it has made all calls to the IMAPIAdviseSink::OnNotify methods of registered advise sinks. Set this flag only for your own internal use. Do not set it when you respond to a client Advise call. Event notification between clients and providers is always asynchronous. That is, MAPI guarantees that the call during which an event happens will return to the client before any of the OnNotify calls are made.

If you set the NOTIFY_SYNC flag, do not make any changes to any of the advise sink objects, and do not pass a wrapper advise sink created by HrThisThreadAdviseSink to Subscribe. HrThisThreadAdviseSink creates a thread-safe version of an advise sink to be used with asynchronous notification only.

If an advise sink registered for synchronous notification returns from OnNotify with the CALLBACK_DISCONTINUE flag set, IMAPISupport::Notify sets the NOTIFY_CANCELED flag and returns without making any calls to OnNotify.

Once Subscribe has returned, you will no longer have any need to hold onto your copy of the client's advise sink. Call its IUnknown::Release method to release it. Subscribe returns a nonzero connection number that you should return to the client. The connection number represents the link between the advise source and the advise sink. It remains valid until the client makes a successful call to Unadvise.

When the client is ready to cancel a registration, it calls your Unadvise method. Pass the connection number from the Unadvise call to IMAPISupport::Unsubscribe. Unsubscribe calls the advise sink's IUnknown::Release method. As with Advise and Unadvise, calls to Subscribe and Unsubscribe must be paired. You must make one call to Unsubscribe for every call that is made to Subscribe. However, you do not have to call Subscribe every time your Advise method is called. Conversely, you can call it for setting up internal notifications.

When an event occurs, allocate one or more NOTIFICATION structures of the type appropriate for the event and call IMAPISupport::Notify. Notify generates a notification for each registered advise sink. You should set all the unused members of the NOTIFICATION structure to zero. This technique for initializing the NOTIFICATION structure can help clients create smaller, faster, and less error-prone OnNotify implementations.

Note that a separate NOTIFICATION structure is necessary for each event, even for multiple events of the same type. For example, if three clients are registered for table notification on a particular table and five rows are added to the table, you must create five OBJECT_NOTIFICATION structures for your Notify call. A batch notification such as this results in better performance than calling Notify five times. For each Notify call, MAPI calls the IMAPIAdviseSink::OnNotify method of every registered advise sink. If there are no registered advise sinks, MAPI ignores the call.

Service providers that send batched notifications must order them so that they can be interpreted from the first notification to the last. This ordering is especially necessary when a notification batch contains a series of events, such as TABLE_ROW_ADDED with one event that refers to a prior row that was added in another event in the same batch.

See also

Concepts

MAPI Service Providers


Message Service Implementation

 Copy code hover
[image]

Message Service Implementation
See also Send feedback

Published: July 16, 2012

A message service is one or more related service providers grouped together for the purpose of simplifying installation and configuration. All service providers should be included in a message service.

To implement a message service with one or more providers, use the following procedure:

  1. Design the message service, determining the number and type of service providers to be included. For more information about how to design a message service, see Designing a Message Service.

  2. Create a setup program to install the service providers in the message service. For more information about writing a message service setup program, see Supporting Message Service Installation.

  3. Create an entry point function to perform configuration. For more information about writing a message service entry point function, see Supporting Message Service Configuration and MSGSERVICEENTRY.

  4. Create a public header file that contains the property tags and descriptions of valid values for any custom properties that the message service supports.

See also

Concepts

MAPI Service Providers


Designing a Message Service

 Copy code hover
[image]

Designing a Message Service
See also Send feedback

Published: July 16, 2012

Before you begin to write code to support your message service, it is important to create a design. Resolve the following issues in your design process:

  1. Determine how many service providers should be included in the message service. Include only related service providers (that is, providers that work with the same messaging system) in your service. Unrelated service providers do not belong in the same message service. Use the profile for integrating unrelated service providers and message services.

  2. Determine what type of service providers should be included in the message service. Most messge services include one provider of each of the common types. That is, the typical message service has one address book provider, one message store provider, and one transport provider.

  3. Determine how many DLLs should contain the message service. The number of DLLs that a message service uses depends on the following:

    • The degree of complexity that you as the writer of the message service are willing to handle.

    • The type of service providers in the message service.

    • The relationship that the message service might have with another message service.

    Because MAPI stores only one entry point for each provider type, do not include multiple providers of the same type in a single DLL. If it makes sense to include multiple providers of one type, either implement them in separate DLLs or have them share an entry point function. Another option is to implement related message services, or message services that are able to use the same installation and configuration code and the same DLL entry point function, in one DLL.

    If possible, keep it simple and use one DLL that contains the implementation of all the service providers in the message service and all the code to install and configure the message service. If this is not possible, you can implement one DLL for the installation and configuration code and either a single DLL for all of the service providers or one DLL for each provider.

  4. Determine a name for the message service DLL or DLLs.

See also

Concepts

Message Service Implementation


Supporting Message Service Installation

 Copy code hover
[image]

Supporting Message Service Installation
See also Send feedback

Published: July 16, 2012

The setup program for installing your message service should do the following:

  1. Copy message service files, such as the message service and service provider DLLs, from a CD or disk, to a local drive on the workstation. The files that need to be copied depend on your message service. Typically you will copy at least one DLL.

  2. Add entries to the Mapisvc.inf configuration file. For more information about how to modify this file to support the service providers in your message service, see File Format of MapiSvc.inf.

  3. Add entries, as appropriate, to the system registry for message services. For more information about how the entries should appear in the system registry, see Installing the MAPI Subsystem.

  4. Create a default profile if one does not yet exist by using one of the following items:

    • The Profile Wizard to create a profile by using user interaction through a series of dialog boxes. For more information about using the Profile Wizard, see Creating a Profile by Using the Profile Wizard.

    • The Control Panel to create a profile by using user interaction. The Control Panel offers the user more flexibility than the Profile Wizard for configuring the message services and setting profile properties.

Place the setup program in a designated public directory. This is important because most configuration clients, such as the Control Panel, require that users enter the name of the directory. The Control Panel invokes a setup program when a user clicks the Add button, invokes the Have Disk dialog box, and specifies the path to the program. The Control Panel runs the program and calls your message service's entry point function with the ulContext parameter set to MSG_SERVICE_INSTALL.

Caution note Caution

Because profiles are an expendable part of the MAPI architecture, be sure that your installation program does not store anything in the default profile that would be difficult to recreate. There are no utilities for profile recovery, for moving profiles from one computer to another, for off-line backup, or for individual or global restoration from backup copies.

See also

Concepts

Message Service Implementation


Supporting Message Service Configuration

 Copy code hover
[image]

Supporting Message Service Configuration
See also Send feedback

Published: July 16, 2012

To support message service configuration, use the following procedure:

  1. Implement an entry point function that conforms to the MSGSERVICEENTRY prototype. Message service entry point functions manage access to configuration data and are called in the following circumstances:

    • When a client logs on to retrieve information to configure your message service.

    • When a client wants to view or change a configuration property.

    Although most message services will provide entry point functions, as they should, these functions are not strictly required. Message services can provide access to configuration data in other ways. However, using an entry point function standardizes and simplifies the process of configuration.

    MAPI expects all message service entry point functions to be able to store and retrieve properties from the profile sections that are associated with their message service. You can support this functionality interactively, programmatically, or both interactively and programmatically.

    To support interactive configuration, provide a property sheet that displays the properties involved in configuring your message service. As an option, you can also supply property sheets for each configurable provider. Some message services restrict users to a read-only view of configuration properties; other message services allow users to make changes.

    To support programmatic configuration, your message service entry point function must be able to work without user intervention. If your message service can be called by the Profile Wizard, you must support programmatic configuration. If your message service does not allow itself to be configured by using the Profile Wizard, you can choose whether or not to support programmatic configuration.

    For more information about how to support configuration in a message service entry point function, see MSGSERVICEENTRY.

  2. Publish the name of your message service entry point function in the Mapisvc.inf configuration file by including the following entry in the message service section:

    PR_SERVICE_ENTRY_NAME=<name of message service>

  3. Create one or more property sheet dialog boxes for displaying configuration data.

  4. Perform the following tasks if you want to allow the Profile Wizard to configure your message service:

    • Implement an entry point function that conforms to the WIZARDENTRY prototype.

    • Implement a standard Windows dialog box procedure that conforms to the SERVICEWIZARDDLGPROC prototype.

    • Enhance your message service entry point function to respond to additional events.

See also

Concepts

Message Service Implementation


Property Sheet Implementation

 Copy code hover
[image]

Property Sheet Implementation
See also Send feedback

Published: July 16, 2012

A property sheet is a dialog box for displaying the properties of an object. The properties can be read-only, enabling the user only to view them, or read/write, enabling the user to make changes. A property sheet contains one or more overlapping child windows called pages. Each page contains control windows for setting a group of related properties. Users navigate from page to page by selecting a tab that brings the corresponding page to the foreground of the property sheet.

Service providers must implement a property sheet that displays a minimal set of properties related to configuration in the message service. If you allow these message service properties to be changed, you can either allow users of client applications, such as the Control Panel, to make the changes or implement the changes programmatically. Implementing property sheets to display and edit other types of properties is optional.

Typically, you will need to display a property sheet in the following situations:

  • When a client calls your status object's IMAPIStatus::SettingsDialog method.

  • When MAPI calls your provider object's logon method.

  • When MAPI calls the entry point function for your provider's message service.

Transport providers also implement property sheets to display properties related to message options, and address book providers implement property sheets to view and edit detailed information about messaging users and distribution lists, advanced search criteria, and templates for entering new users.

You can use one of the following three techniques to create a property sheet:

  • Manually, as you would any dialog box.

  • By using the property sheet common control provided in the Windows SDK.

  • By using a MAPI display table.

Providers should choose the last option (create a property sheet by using a display table). This is the simplest option because it eliminates the need to work with the Windows user interface.

To implement a property sheet built from a display table for your message service properties, use the following procedure:

  1. Call IMAPISupport::OpenProfileSection to open a section in the current profile. Pass your MAPIUID or NULL to open your provider's profile section.

  2. Call CreateIProp to create a property data object.

  3. Call the profile section's IMAPIProp::CopyTo method to copy all of the section's properties to the property data object.

  4. Create a display table either by building one or more DTPAGE structures that describe the controls to appear on the property sheet and calling the BuildDisplayTable function, or by implementing custom code.

  5. Call IMAPISupport::DoConfigPropsheet to display a property sheet that has the copied properties. Pass a pointer to the property data object as the lpConfigData parameter and a pointer to the display table as the lpDisplayTable parameter. If you want to override the default access mode for this property sheet, do not set the DT_EDITABLE flag for each control in the display table that represents a read-only property.

  6. When all of the changes have been made in the property sheet, call the property data object's IMAPIProp::CopyTo method to copy the changed properties back to the profile section.

For an overview of display tables, see Display Tables.

For detailed information about display tables, see Display Table Implementation.

For information about implementing a control, see Control Object Implementation.

To retrieve the index of a control that a user selects in a display table list box, wait until the user clicks OK or Apply. At this point, the entry identifier of the selected item is written back to the IMAPIProp : IUnknown interface as the value of the property specified by the ulPRSetProperty member in the DTBLLBX structure.

If you need to be able to add or remove items from your list box, using a display table and the IMAPISupport::DoConfigPropsheet method will not work. Instead, consider implementing a property sheet with the Win32 property sheet API contained in the comdlg32.dll file.

See also

Concepts

MAPI Service Providers


Display Table Implementation

 Copy code hover
[image]

Display Table Implementation
See also Send feedback

Published: July 16, 2012

A display table is used to show a property sheet, a special dialog box that is composed of one or more tabbed property pages dedicated to displaying and possibly editing one or more properties. Associated with every display table is an IAttach : IMAPIProp interface implementation. The IMAPIProp implementation maintains the property data that is presented in the property sheet.

The rows in a display table represent the controls in the property sheet. Most controls can be associated with properties maintained with the IMAPIProp implementation. When a user changes the value of a modifiable control, the corresponding property is updated.

The columns in a display table represent properties of the control, such as its position in the property sheet, its type, associated structure, and identifier. For a complete list of required display table columns, see Display Tables.

MAPI displays a property sheet to the user of a client application by reading property values from the IMAPIProp implementation associated with the display table or from the display table directly. As the user works with the property sheet, changing values in the controls, MAPI calls IMAPIProp::SetProps to save a changed control if the control's DT_SET_IMMEDIATE flag is set. For controls without the DT_SET_IMMEDIATE flag set, changes to properties are saved when the user dismisses the dialog box by clicking the OK or Apply Now button. When either of these buttons or the Cancel button is clicked, MAPI removes the property sheet from view.

MAPI gains access to your display table either by calling the IMAPIProp::OpenProperty method in the IMAPIProp implementation and requesting the PR_DETAILS_TABLE (PidTagDetailsTable) property or by inheriting it in a call that you have made to MAPI, such as IMAPISupport::DoConfigPropsheet.

The first access technique is used when address book providers are asked to show details about messaging users or distribution lists. The following processing occurs:

  1. A client calls the IAddrBook::Details method.

  2. MAPI calls the address book provider's IABLogon::OpenEntry method to access the messaging user that represents the selected entry.

  3. MAPI calls the messaging user's IMAPIProp::OpenProperty method to retrieve the PR_DETAILS_TABLE property, the display table for the details dialog box.

  4. MAPI displays the dialog box, handling the user's interaction with the information, and removes it when the user has finished.

See also

Concepts

MAPI Service Providers


Creating Display Tables and Related Structures

 Copy code hover
[image]

Creating Display Tables and Related Structures
See also Send feedback

Published: July 16, 2012

Creating a display table is similar to writing a program with a scripting language. You can create a display table either by calling BuildDisplayTable or writing custom code to populate the rows and columns of the table. In general, you should use the BuildDisplayTable technique because it is simpler.

Before you can call BuildDisplayTable to prompt MAPI to create a display table, there is a hierarchy of structures that you must build. The top-level structure, DTPAGE, describes a single tabbed property page. In every DTPAGE structure is a DTCTL structure that describes a single control, such as an edit box or an option button. Each DTCTL structure contains a structure that is specific to the type of control. For example, if the DTCTL structure describes an edit box control, it will contain a DTBLEDIT structure. The DTCTL structure for an option button contains a DTBLRADIOBUTTON structure.

These structures relate directly to BuildDisplayTable; they have no meaning outside the context of this function. When you call BuildDisplayTable, you pass one or more DTPAGE structures as input parameters. The DTPAGE structures contain an array of DTCTL structures and a count of the number of DTCTL structures in the array. There is one structure for every control to display in the dialog box. DTPAGE structures also have a character string that represents the name of a corresponding Help file and dialog box resource.

Each DTCTL structure in a DTPAGE structure contains the following data that is used to set properties for the control:

  • The control type for setting PR_CONTROL_TYPE (PidTagControlType).

  • Control flags for setting PR_CONTROL_FLAGS (PidTagControlFlags).

  • Notification data for setting PR_CONTROL_ID (PidTagControlId).

  • The control structure for setting PR_CONTROL_STRUCTURE (PidTagControlStructure).

DTCTL structures also contain a resource identifier and, for edit and combo box controls, a character filter.

The control structure member of a DTCTL structure describes the data that is unique for the type of control. MAPI defines a different structure for each control type. For example, the data of an edit control is represented by a DTBLEDIT structure; the data of a list box is represented by a DTBLLBX structure.

The relationship between the three types of display table structures is shown in the following illustration. The dialog box described by this display table has two controls: a label and an edit control. The DTBLLBX structure has a label offset member, as do several of the control structures, that describes where the character string for the label begins. Label character strings are typically placed in memory immediately following the structure.

Display table structures

Display table structures

See also

Concepts

Display Table Implementation


Displaying Table Controls

 Copy code hover
[image]

Displaying Table Controls
See also Send feedback

Published: July 16, 2012

There are many different types of controls, none unique to MAPI. However, MAPI defines its own structures that are used in conjunction with BuildDisplayTable to describe the unique set of data involved with each control.

The following table lists the structures that describe each type of control.

Control structure | Description
DTBLBUTTON | Describes a button control.
DTBLCHECKBOX | Describes a check box control.
DTBLCOMBOBOX | Describes a combo box control.
DTBLDDLBX | Describes a drop-down list box control.
DTBLEDIT | Describes an edit control.
DTBLGROUPBOX | Describes a group box control.
DTBLLABEL | Describes a label control.
DTBLLBX | Describes a list box control.
DTBLMVDDLBOX | Describes a multiple-value drop-down list box control.
DTBLMVLISTBOX | Describes a multiple-value list box control.
DTBLPAGE | Describes a tabbed page control.
DTBLRADIOBUTTON | Describes an option button control.

See also

Concepts

Display Table Implementation


Displaying Table Rows and Columns

 Copy code hover
[image]

Displaying Table Rows and Columns
See also Send feedback

Published: July 16, 2012

A property page can be used by an address book provider to enable users to define new e-mail recipients.

The corresponding display table contains four rows, one for each control. The values for the columns that indicate position are as follows.

Control | XPOS | YPOS | DELTAX | DELTAY
Display name label | 14 | 18 | 49 | 8
Display name edit box | 76 | 16 | 89 | 12
E-mail address label | 14 | 42 | 50 | 8
E-mail address edit box | 76 | 40 | 89 | 12
Check box | 14 | 64 | 90 | 12

This next table suggests appropriate values for the control's type, its PR_CONTROL_TYPE (PidTagControlType) property, and bitmask of flags, its PR_CONTROL_FLAGS (PidTagControlFlags) property.

Control | Type | Flags
Display name label | DTCT_LABEL | 0
Display name edit box | DTCT_EDIT | DT_EDITABLE | DT_REQUIRED
E-mail address label | DTCT_LABEL | 0
E-mail address edit box | DTCT_EDIT | DT_EDITABLE | DT_REQUIRED
Check box | DTCT_CHECKBOX | DT_EDITABLE

The final table lists each control with the contents of its associated control structure. Notice that the value for each of the label controls appears in memory directly following the structure.

Control | Structure
Display name label | {sizeof(DTBLLABEL), 0} "Display name:"
Display name edit box | {sizeof(DTBLEDIT), 0, 80, PR_DISPLAY_NAME}
E-mail address label | {sizeof(DTBLLABEL), 0} "E-mail address:"
E-mail address edit box | {sizeof(DTBLEDIT), 0, 80, PR_EMAIL_ADDRESS}
Check box | PR_SEND_RICH_INFO
Note Note

The OK, Cancel, and Help buttons are not included in the display table. The user interface can add context to a dialog box by adding controls not in the display table.

See also

Concepts

Display Table Implementation


Control Object Implementation

 Copy code hover
[image]

Control Object Implementation
See also Send feedback

Published: July 16, 2012

Control objects, or objects that support the IMAPIControl : IUnknown interface, are implemented by providers to add functionality to a button that appears on a MAPI dialog box. Control objects can only be implemented for buttons.

IMAPIControl has three methods: GetLastError, GetState, and Activate.

MAPI calls GetState to determine whether or not to disable the button. GetState is called in the following situations:

  • When the dialog box on which the button appears is first displayed.

  • When a display table notification is issued for the button.

Set the contents of the lpulState parameter to MAPI_DISABLED if the user cannot interact with the button and MAPI_ENABLED if the user can interact.

When the user clicks the button, MAPI calls Activate. Activate performs the task that has been associated with the button. This task can be anything appropriate for your provider, such as displaying a dialog box or updating a property. If the task is unsuccessful because the user canceled it, return MAPI_E_USER_CANCEL. For other causes of failure, return the appropriate error value.

If the task is successful and it is linked to a property change that is reflected in another control on the dialog box, call ITableData::HrNotify. HrNotify is called to issue a display table notification with the changed property's PR_CONTROL_ID (PidTagControlId) property in the TABLE_NOTIFICATION structure. Do not place the new property value in the structure; instead, return it when IMAPIProp::GetProps is called. Although typically a display table notification cannot be used to disable or enable a control, it can be used with a button. MAPI will refresh the changed control to respond to the notification.

MAPI calls the control's GetLastError method when Activate returns an error other than MAPI_E_USER_CANCEL. If GetLastError places extended error information in the MAPIERROR structure that it returns in the contents of the lppMAPIError parameter, MAPI displays it for the user.

See also

Concepts

MAPI Service Providers


Status Object Implementation

 Copy code hover
[image]

Status Object Implementation
See also Send feedback

Published: July 16, 2012

All service providers must implement a status object and furnish properties from it to the session status table. You can include one or more rows in the status table, depending on the number of resources that you control. A transport provider, for example, should create a row in the status table for each message queue it manages. When changes occur, the appropriate status table row must be updated. Status objects are implemented to provide access both to the information included in the status table and to additional information not included in the table.

To implement a status object

  1. Implement the OpenStatusEntry method of your logon object. When clients want to open your status object, they call IMAPISession::OpenEntry. MAPI fulfills the open request by calling your provider's OpenStatusEntry method, causing your provider to open its status object and return to the client a pointer to its IMAPIStatus implementation. In your OpenStatusEntry implementation, complete the following steps:

    1. Perform the following tasks if your logon object has not yet created a status object:

      1. Call the support object's IMAPISupport::OpenProfileSection method to access your provider's profile section.

      2. Create a new status object.

      3. Store a reference to the profile section in your provider's status object and call the profile section's IUnknown::AddRef method to increment its reference count.

      4. Store a reference to the logon object in your provider's status object and call the logon object's IUnknown::AddRef method to increment its reference count.

      5. Store a reference to the status object in your provider's logon object.

    2. Call the status object's IUnknown::AddRef method to increment its reference count in the logon object.

    3. Set the status object's PR_OBJECT_TYPE (PidTagObjectType) property to MAPI_STATUS.

    4. Set the lppMAPIStatus output parameter to point to the status object, and return.

    5. Check the ulFlags input parameter. If it is set to MAPI_MODIFY and your provider supports read/write access to its status object, return a writeable object. However, if your provider does not support read/write access to its status object, do not fail. Return a status object that is read-only. Clients that expect to receive read/write status objects should verify that read/write permission has been granted before attempting to make any changes.

  2. Set all of the required status object and status table properties. The properties that you include in your status table row should be available through your status object, except for the properties calculated by MAPI. The required properties are as follows:

    • PR_DISPLAY_NAME (PidTagDisplayName)

    • PR_PROVIDER_DLL_NAME (PidTagProviderDllName)

    • PR_PROVIDER_DISPLAY (PidTagProviderDisplay)

    • PR_RESOURCE_TYPE (PidTagResourceType)

    • PR_RESOURCE_METHODS (PidTagResourceMethods)

    • PR_RESOURCE_FLAGS (PidTagResourceFlags)

    • PR_STATUS_CODE (PidTagStatusCode)

  3. Implement the IMAPIStatus : IMAPIProp methods that are appropriate for your provider. Depending on your provider, you do not need to implement all of the four methods in IMAPIStatus. Every provider should implement a read-only version of the methods of the IMAPIProp : IUnknown interface and the IMAPIStatus::ValidateState method. Transport providers should also implement IMAPIStatus::FlushQueues, and all providers should support IMAPIStatus::SettingsDialog. However, support for IMAPIStatus::ChangePassword is optional. Only service providers that require passwords and want to allow users to change them programmatically need to implement this method. For every method that you support, set the corresponding bit in the PR_RESOURCE_METHODS property. For example, if you support ValidateState and SettingsDialog only, set PR_RESOURCE_METHODS to the following:

    STATUS_VALIDATE_STATE | STATUS_SETTINGS_DIALOG

    Clients should check the value of PR_RESOURCE_METHODS before attempting to call your status object. Handle calls to any of your unsupported methods by returning MAPI_E_NO_SUPPORT.

  4. Call IMAPISupport::ModifyStatusRow during logon to add your row or rows to the status table. Pass a property value array that contains the column information for the row and 0 for the ulFlags parameter. If at some point later in the session your provider's status changes and it becomes necessary to update the column information, call ModifyStatusRow again with the STATUSROW_UPDATE flag set.

For more information about status objects, see MAPI Status Objects.

See also

Concepts

MAPI Service Providers


MAPI Progress Indicators

 Copy code hover
[image]

MAPI Progress Indicators
See also Send feedback

Published: July 16, 2012

Many of the operations that you perform for clients can take a long time to complete. To inform clients of the progress of a lengthy operation, you can show an indicator that displays graphically the finished portion of an operation at any given point from the start of the operation to its completion. The progress indicator shows a percentage of the total operation to be completed.

The following methods support lengthy operations and the display of a progress indicator:

  • IMAPIFolder::CopyMessages, IMAPIFolder::CopyFolder, IMAPIFolder::DeleteMessages, IMAPIFolder::DeleteFolder, IMAPIFolder::EmptyFolder, and IMAPIFolder::SetReadFlags.

  • IMAPIProp::CopyProps and IMAPIProp::CopyTo.

  • IMAPISupport::DoCopyProps, IMAPISupport::DoCopyTo, IMAPISupport::CopyFolder, and IMAPISupport::CopyMessages.

  • IMessage::DeleteAttach.

  • IABContainer::CopyEntries.

To display a progress indicator, MAPI defines a progress object. Progress objects implement the IMAPIProgress : IUnknown interface, an interface that includes methods for establishing the range of the indicator and creating the display. MAPI provides a progress object implementation as do some clients. You should use a client's implementation, if one is supplied, as an input parameter to the method performing the operation. If the client passes NULL instead of a pointer to a progress object, use MAPI's implementation by calling the IMAPISupport::DoProgressDialog method.

See also

Concepts

MAPI Service Providers


MAPI Progress Objects

 Copy code hover
[image]

MAPI Progress Objects
See also Send feedback

Published: July 16, 2012

With the methods and data of a progress object, you can control how the indicator reports progress. Although a client or MAPI implements the progress object, most of the burden of ensuring the correctness of the progress display falls on service providers. You can guarantee its accuracy by specifying a particular order and value for the parameters that are passed to progress object methods.

The following parameters are passed to progress objects:

  • A bitmask of flags, set with IMAPIProgress::SetLimits and retrieved with IMAPIProgress::GetFlags.

  • A minimum value (local and global), set with SetLimits and retrieved with IMAPIProgress::GetMin.

  • A maximum value (local and global), set with SetLimits and retrieved with IMAPIProgress::GetMax.

  • A value that indicates the current percentage of completion of the operation, passed to IMAPIProgress::Progress.

  • A count of the number of objects that have so far been processed, passed to Progress.

  • A count of the total number of objects involved in the operation, passed to Progress.

All service providers begin their progress display processing with a call to IMAPIProgress::GetFlags to retrieve the present flags setting. Currently, the flags can be set only to MAPI_TOP_LEVEL. Clients and MAPI initialize the flag to MAPI_TOP_LEVEL, relying on service providers to clear it when appropriate.

The flags value is set to MAPI_TOP_LEVEL while you are working with the top-level object in the operation. The top-level object is the object that is called by the client to begin an operation. In a folder copy operation, this is the folder being copied. In a folder delete operation, this is the folder being deleted. When you make a call to process a lower level object, or subobject, clear the flags value. In a folder copy operation, subobjects are the subfolders that are in the folder being copied.

MAPI allows you to differentiate between top-level objects and subobjects with the MAPI_TOP_LEVEL flag so that all objects involved in an operation can use the same IMAPIProgress implementation to show progress, thereby causing the indicator display to proceed smoothly in a single positive direction. Whether or not the MAPI_TOP_LEVEL flag is set affects the settings of the other parameters in subsequent calls to the progress object.

Because it can be nontrivial to set appropriate parameter values for a progress display at all levels of a multilevel operation, some service providers elect not to show progress for subobjects.

To avoid showing progress for subobjects

  • Pass NULL for the lpProgress parameter in the call to process a subobject. For example, if you are copying folders, this is the call to a subfolder's IMAPIFolder::CopyFolder method.

  • Write special code to determine how to interpret the lpProgress parameter. Because a NULL value for the lpProgress parameter can also mean that the client should display progress by using the MAPI implementation, special code is necessary to determine when to ignore the lpProgress parameter and when to call IMAPISupport::DoProgressDialog.

Call IMAPIProgress::SetLimits to set or clear the MAPI_TOP_LEVEL flag and to set local and global minimum and maximum values. The value of the flags setting affects whether the progress object understands the minimum and maximum values to be local or global. When the MAPI_TOP_LEVEL flag is set, these values are considered global and are used to calculate progress for the entire operation. Progress objects initialize the global minimum value to 0 and the global maximum value to 1000.

When MAPI_TOP_LEVEL is not set, the minimum and maximum values are considered local and are used internally by providers to display progress for lower level subobjects. Progress objects save the local minimum and maximum values only so that they can be returned to providers when GetMin and GetMax are called.

The value, object count, and object total parameters are input to the IMAPIProgress::Progress method. The value parameter, a number that indicates the percentage of progress, is required. If the MAPI_TOP_LEVEL flag is set, you can also pass an object count and an object total. Some clients use these values to display a phrase such as "5 items completed out of 10" with the progress indicator. Progress on an operation can be reported strictly as a percentage or as a percentage and in terms of the number of items that have been processed out of the total to be processed. For example, if you are a message store provider and you are performing a copy operation that is copying 10 folders, the progress indicator can supply the user with additional information by displaying a phrase such as "1 of 10", "2 of 10", "3 of 10", and so on until the operation is complete.

See also

Concepts

MAPI Progress Indicators


How to: Display a Progress Indicator

 Copy code hover
[image]

How to: Display a Progress Indicator
See also Send feedback

Published: July 16, 2012

To display a progress indicator, call IMAPIProgress::GetFlags to retrieve the current flags setting.

If the MAPI_TOP_LEVEL flag is set, complete the following steps:

  1. Set a variable equal to the total number of items to process in the operation. For example, if you are copying the contents of a folder, this value will be equal to the number of the subfolders in the folder plus the number of messages.

  2. Set a variable equal to 1000 divided by the number of items.

  3. If you are showing progress for subobjects, call the progress object's IMAPIProgress::SetLimits method and pass the following values for the three parameters:

    • Set the lpulMin parameter to 0.

    • Set the lpulMax parameter to 1000.

    • Set the lpulFlags parameter to MAPI_TOP_LEVEL.

  4. For each object to be processed, complete the following steps:

    1. Call IMAPIProgress::SetLimits and pass the following values for the three parameters:

      • Set the lpulMin parameter to the variable set in step 2 multiplied by the current item minus 1.

      • Set the lpulMax parameter to the variable set in step 2 multiplied by the current object.

      • Set the lpulFlags parameter to 0.

    2. Perform whatever processing should be done on this object. If this is a subobject and you want to display progress on subobjects, pass a pointer to the progress object in the lpProgress parameter to the method.

    3. Call IMAPIProgress::Progress and pass the following values for the three parameters:

      • Set the ulValue parameter to the variable set in step 2 multiplied by the current object.

      • Set the ulCount parameter to the current object.

      • Set the ulTotal parameter to the variable set in step 1, the total number of objects.

If the MAPI_TOP_LEVEL flag is not set, complete the following steps:

  1. Call the progress object's IMAPIProgress::GetMin method to retrieve the minimum value for the display.

  2. Call IMAPIProgress::GetMax to retrieve the maximum value for the display.

  3. Set a variable equal to the total number of objects to be processed.

  4. Set a variable equal to the result of subtracting the minimum value from the maximum value and then dividing by the total number of objects.

  5. For each object to be processed, complete the following steps:

    1. If your provider is showing progress for subobjects, call IMAPIProgress::SetLimits and pass the following values for the three parameters:

      • Set the lpulMin parameter to the minimum value plus the current item minus 1 multiplied by the variable set in step 4.

      • Set the lpulMax parameter to the minimum value plus the current unit multiplied by the variable set in step 4.

      • Set the lpulFlags parameter to 0.

    2. Perform whatever processing should be done on this object. If the object is a subobject, and your provider displays progress for subobjects, pass a pointer to the progress object in the lpProgress parameter to the method.

    3. Call IMAPIProgress::Progress and pass the following values for the three parameters:

      • Set the ulValue parameter to variable set in step 2 multiplied by the current object.

      • Set the ulCount parameter to 0.

      • Set the ulTotal parameter to 0.

The following code example illustrates the logic required to show progress at all levels of an operation that copies the contents of a folder that contains five subfolders.

C++ Copy code Copy code
lpProgress->GetFlags (lpulFlags);
ulFlags = *lpulFlags;

/* The folder in charge of the display. It contains 5 subfolders. */
if (ulFlags & MAPI_TOP_LEVEL)
{
    ulItems = 5                         // 5 subfolders in this folder
    ulScale = (ulMax / ulItems)         // 200 because ulMax = 1000
    lpProgress->SetLimits(0, ulMax, MAPI_TOP_LEVEL)

    for (i = 1; i <= ulItems; i++)      // for each subfolder to copy
    {
        lpProgress->SetLimits( (i - 1) * ulScale, i * ulScale, 0)
        CopyOneFolder(lpFolder(i), lpProgress)
        lpProgress->Progress( i * ulScale, i, ulItems)
    }
}
else
/* One of the subfolders to be copied. It contains 3 messages. */
{
    lpProgress->GetMin(&ulMin);
    lpProgress->GetMax(&ulMax);
    ulItems = 3;
    ulDelta = (ulMax - ulMin) / ulItems;
    for (i = 1; i <= ulItems; i++)
    {
        lpProgress->SetLimits(ulMin + (i - 1) * ulDelta,
                              ulMin + i * ulDelta, 0)
        CopyOneFolder(lpFolder(i), lpProgress)

        /* Pass 0 for ulCount and ulTotal because this is not the */
        /* top-level display, and that information is unavailable  */
        lpProgress->Progress( i * ulDelta, 0, 0)
    }
}

See also

Concepts

MAPI Progress Indicators


Developing a MAPI Address Book Provider

 Copy code hover
[image]

Developing a MAPI Address Book Provider
Send feedback

Published: July 16, 2012

An address book provider supplies recipient information to client applications, to message store and transport providers, and to MAPI. Recipient information is organized hierarchically into storage compartments known as containers. Every address book in the profile contributes one or more top-level, or parent, containers to the MAPI address book, an integrated view of recipient information from all address book providers in a session. It is through the MAPI address book that clients and other service providers gain access to the data of an address book provider.

MAPI builds the integrated address book by:

  1. Retrieving the top-level containers from each address book provider.

  2. Retrieving each container's hierarchy table.

  3. Copying each hierarchy table into an integrated hierarchy table. It is the integrated hierarchy table that is exposed to the client.

MAPI imposes few requirements on address book provider writers. The range of possible features you can implement as an address book writer is varied and flexible. For example, your provider could be limited to supplying a read-only view of a particular type of recipient information or implement a full set of features, perhaps allowing clients or providers to make additions or modifications to the recipient data and to impose search criteria for defining customized views.

Your provider's data can reside locally in a file or database or on a remote server. Some address book providers are meant to work with a particular messaging system, tightly coupled with a transport provider, while others can operate with any messaging system.

MAPI defines a special type of address book provider called a personal address book, or PAB, that implements a single modifiable container and can hold recipient information copied from other containers as well as information created directly. Although any address book provider can implement a PAB and multiple PABs can be added to a profile, only one of these providers can be designated to operate as the PAB during any one session.


Required Features for Address Book Providers

 Copy code hover
[image]

Required Features for Address Book Providers
Send feedback

Published: July 16, 2012

Address book providers can work with recipient information that is temporary or permanent, local or remote, understandable by one or more messaging systems, and formatted for a disk file or database table. There are a variety of features that an address book provider can implement, thereby adding value and improving interoperability with clients and other providers. However, a few features are required.

The following table describes features that are required of all address book providers and the steps that you need to take to implement them.

Feature

How to implement

Session logon

  1. Implement an entry point function. For more information, see Implementing an Address Book Provider Entry Point Function.

  2. Implement the IABProvider::Logon method. For more information, see Implementing Address Book Provider Logon and Logoff.

Session logoff

Implement the IABProvider::Shutdown method. For more information, see Implementing Address Book Provider Logon and Logoff.

Create entry identifiers

Provide support for the PR_ENTRYID (PidTagEntryId) property. For more information, see MAPI Entry Identifiers and Address Book Identifiers.

Contribute to the status table

  1. Implement the appropriate methods of the IMAPIStatus : IMAPIProp interface. For more information, see Status Object Implementation.

  2. Support the required status table properties. For more information, see Status Tables.

  3. Call IMAPISupport::ModifyStatusRow.

Provide limited status object support

  1. Implement the IMAPIStatus::ValidateState method.

  2. Return MAPI_E_NO_SUPPORT from the other IMAPIStatus methods.

Support interactive and programmatic configuration

  1. Implement a message service entry point function.

  2. Implement a display table. For more information, see Display Tables and Display Table Implementation.

  3. Implement a property sheet or call the IMAPISupport::DoConfigPropsheet method. For more information, see Property Sheet Implementation.

In addition, if your provider supports recipient creation, you must supply a list of creation templates. Supply this list by implementing the IABLogon::GetOneOffTable method to include all of the templates supported by your provider and the IMAPIProp::OpenProperty method of each container to open the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property and include all the templates supported by the container. For more information, see Implementing One-Off Tables.


Implementing an Address Book Provider Entry Point Function

 Copy code hover
[image]

Implementing an Address Book Provider Entry Point Function
Send feedback

Published: July 16, 2012

When a client application calls MAPILogonEx to begin a session using a profile that contains your address book provider, MAPI loads your provider and all others that are part of the profile. MAPI learns of the name of your provider's entry point function by looking in the profile. Remember that this function is not the same as a DLL entry point function; see the documentation for DllMain in the Win32 documentation.

There are several entries, some of which must appear in the mapisvc.inf configuration file, that are included in the profile section of every address book provider. The following table lists these profile section entries and whether or not the mapisvc.inf file must include them.

Profile section entry | mapisvc.inf requirement
PR_DISPLAY_NAME=string | Optional
PR_PROVIDER_DISPLAY=string | Required
PR_PROVIDER_DLL_NAME=DLL filename | Required
PR_RESOURCE_TYPE=long | Required
PR_RESOURCE_FLAGS=bitmask | Optional

Your address book provider can place this information into a profile directly by calling its profile section's IMAPIProp::SetProps method or indirectly by modifying MAPISVC.INF. Profiles are built using the relevant information in MAPISVC.INF for the selected service providers or message services. For more information about the organization and contents of MAPISVC.INF, see File Format of MapiSvc.inf.

The name of your address book provider's DLL entry point function must be ABProviderInit and it must conform to the ABProviderInit prototype. Perform the following tasks in your provider's DLL entry point function:

  • Check the version of the service provider interface (SPI) to make sure MAPI is using a version that is compatible with the version that your address book provider is using.

  • Instantiate an address book provider object.

Do not call either MAPIInitialize or MAPIUninitialize in this function.

The DLL entry point function instantiates a provider object and returns to MAPI a pointer to that object.


Implementing Address Book Provider Logon and Logoff

 Copy code hover
[image]

Implementing Address Book Provider Logon and Logoff
Send feedback

Published: July 16, 2012

Address book providers support session logon and logoff by implementing the methods of the IABProvider : IUnknown interface. The IABProvider interface inherits directly from IUnknown and adds only two other methods: Logon and Shutdown.

Logoff

MAPI will call your provider's IABProvider::Logon method at the beginning of every session and whenever your provider is added to the current profile and the client supports dynamic reconfiguration. When MAPI calls the IABProvider::Logon method, your address book provider begins its logon process.

To implement IABProvider::Log

  1. Initialize all of the output parameter pointers passed in by MAPI.

  2. Call the support object's IUnknown::AddRef method to increment its reference count.

  3. Call the support object's IMAPISupport::OpenProfileSection method to open the section of the profile that contains configuration information about your provider. Pass NULL for the lpUID parameter and the MAPI_MODIFY flag if you intend to make changes.

  4. Call the profile section's IMAPIProp::GetProps method to retrieve the properties that your provider needs for logon, such as the name of the data file or database table.

  5. Check that the properties are all available and valid. If necessary and allowed, display a dialog box to prompt the user to make corrections or additions to invalid or missing information and call the profile section's IMAPIProp::SetProps method to save any changes. Some of the common properties that should be available include:

    PR_DISPLAY_NAME (PidTagDisplayName)

    PR_ENTRYID (PidTagEntryId)

    PR_PROVIDER_DISPLAY (PidTagProviderDisplay)

    PR_RECORD_KEY (PidTagRecordKey)

    Note Note

    Do not set PR_RESOURCE_FLAGS (PidTagResourceFlags) or PR_PROVIDER_DLL_NAME (PidTagProviderDllName). At logon time, these properties are read-only.

  6. If one or more configuration properties are unavailable, fail and return the value MAPI_E_UNCONFIGURED.

  7. Call IMAPISupport::SetProviderUID to register a MAPIUID. Your provider can create a MAPIUID by:

    • Calling the IMAPISupport::NewUID method.

    • Calling the UUIDGEN.EXE tool to define a GUID that your provider uses to include in one of its header files.

  8. If desired, save a newly created MAPIUID in the current profile by calling the profile section's IMAPIProp::SetProps method.

  9. Release the profile section by calling its IUnknown::Release method.

  10. Instantiate a new logon object and set the contents of the lppABLogon parameter to the address of this new object.

Because it is possible for MAPI to call your Logon method several times during a session, it is wise to support this possibility in your implementation by being able to create multiple logon objects and keep track of each object that is created. Supporting multiple Logon calls enables a user of a client application, for example, to log on to a session with different identities or use different delivery destinations.

Shutdown is called when the session is ending. MAPI calls your IABProvider::Shutdown method as one of the last tasks involved in shutting down a session. MAPI has released all of your provider's logon objects and, when your provider receives this call, it can assume that this is the last call it will receive. In your implementation of IABProvider::Shutdown, perform any final cleanup that you feel is necessary. For example, your provider might call MAPIDeinitIdle if it has called MAPIInitIdle to use the idle engine during the session or the IUnknown::Release method of any objects that have yet to be released.

If your provider has no final cleanup, its implementation can be made up of a single line of code:

Copy code Copy code
return S_OK;


Required Features for Address Book Containers

 Copy code hover
[image]

Required Features for Address Book Containers
Send feedback

Published: July 16, 2012

Most address book providers support at least one container, some of them modifiable. Address book containers can supply contents and hierarchy tables, search capabilities, and name resolution. Modifiable containers allow the deletion of entries such as messaging users, distribution lists, or other containers and the addition of entries from entries in other containers or from one-off templates.

The following table describes features that are required of address book providers that have containers, modifiable or read-only, and how you implement them.

Feature

How to implement

Access messaging users

Implement the IABLogon::OpenEntry method. For more information, see Opening Address Book Entries.

Compare messaging users

Implement the IABLogon::CompareEntryIDs method. For more information, see Comparing Address Book Entries.

Create messaging users

1. Provide a list of creation templates in a one-off table by supporting the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property. For more information, see Implementing a Container One-Off Table.

2. Implement the IABContainer::CreateEntry method. For more information, see Adding Address Book Entries.

Copy messaging users

Implement the IABContainer::CopyEntries method. For more information, see Copying Address Book Entries.

Remove messaging users

Implement the IABContainer::DeleteEntries method. For more information, see Removing Address Book Entries.

Provide summary information about messaging users

Support the container property PR_CONTAINER_CONTENTS (PidTagContainerContents). For more information, see Contents Tables.

Provide detailed information about messaging users

Support the PR_DETAILS_TABLE (PidTagDetailsTable) property on messaging users and distribution lists. For more information, see Displaying Recipient Information and Display Tables.

Provide detailed information about a container

Support the PR_DETAILS_TABLE property on the container. For more information, see Displaying Recipient Information and Display Tables.

Provide a hierarchical list of containers

Support the container property PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy). For more information, see Hierarchy Tables.

Support messaging user properties

Implement the IMailUser : IMAPIProp interface.

Resolve ambiguous names

  1. Support the PR_ANR (PidTagAnr) property restriction.

  2. Optionally implement the IABContainer::ResolveNames method. For more information, see Implementing Name Resolution.


Opening Address Book Entries

 Copy code hover
[image]

Opening Address Book Entries
Send feedback

Published: July 16, 2012

When a client or provider has requested that one of your objects be opened, MAPI calls your provider's IABLogon::OpenEntry method. MAPI determines that the entry identifier representing the target object belongs to your provider by examining the MAPIUID portion of the entry identifier and matching it to the MAPIUID that your provider registered in the call to IMAPISupport::SetProviderUID. MAPI then calls your OpenEntry method. Your provider must respond by retrieving the corresponding object — a container, distribution list, or messaging user.

A NULL entry identifier indicates a request to open the address book provider's root container. Clients open the root container to access its hierarchy table and its recipients. Address book providers that only supply templates for creating one-off recipients do not support the OpenEntry call for the root container.

To implement IABLogon::OpenEntry

  1. Check that the entry identifier is a valid identifier that your provider supports. If it is not a valid entry identifier, return MAPI_E_INVALID_ENTRYID.

  2. Check the flag that is passed in with the ulFlags parameter. If MAPI has passed in MAPI_MODIFY and your provider does not allow its objects to be modified, fail and return the MAPI_E_ACCESS_DENIED error value.

  3. Check that the interface requested in the lpInterface parameter is valid for the type of object your provider has been asked to open. If an invalid parameter has been passed in, fail and return the MAPI_E_INTERFACE_NOT_SUPPORTED error value.

  4. If the cbEntryID parameter is zero, this is a request to open your provider's root container. Create the root container and return a pointer to its IABContainer interface implementation.

  5. If your provider implements several logon objects, each with its own registered MAPIUID, map the MAPIUID contained in the entry identifier with the appropriate logon object.

  6. Determine which type of object the entry identifier represents: a messaging user, distribution list, or container belonging to your provider or a one-off messaging user or distribution list so that the appropriate value can be set for the lpulObjectType parameter.

  7. Create the object of the appropriate type and set the following basic properties:

    PR_DISPLAY_TYPE (PidTagDisplayType)

    PR_ENTRYID (PidTagEntryId)

    PR_OBJECT_TYPE (PidTagObjectType)

    PR_ADDRTYPE (PidTagAddressType)

    Calculate PR_EMAIL_ADDRESS (PidTagEmailAddress) and PR_DISPLAY_NAME (PidTagDisplayName) from information in the entry identifier.

  8. Return a pointer to the interface implementation for the object.


Comparing Address Book Entries

 Copy code hover
[image]

Comparing Address Book Entries
Send feedback

Published: July 16, 2012

Your provider's IABLogon::CompareEntryIDs implementation compares the entry identifiers for two of your provider's objects. MAPI calls this method after determining that the two entry identifiers contain your provider's registered MAPIUID. Therefore, your CompareEntryIDs method need not check that the entry identifiers passed in for the lpEntryID1 and lpEntryID2 parameters belong to your provider.

Calling IABLogon::CompareEntryIDs is equivalent to retrieving the PR_RECORD_KEY (PidTagRecordKey) property for each of the two objects and comparing them directly.

To implement CompareEntryIds

  1. Check the type of the entry identifiers passed in if your provider stores that information. For example, one entry identifier might belong to a messaging user while the other might belong to a distribution list. If the types do not match, set the contents of the lpulResult parameter to FALSE and return.

  2. Compare the sizes of the two entry identifiers. If they are not the same, set the contents of the lpulResult parameter to FALSE and return.

  3. Check that the size of the entry identifiers is the correct size for their type. If not, set the contents of the lpulResult parameter to FALSE and return the error value MAPI_E_UNKNOWN_ENTRYID.

  4. Check if the entry identifiers are the same. If they compare equally, set the contents of the lpulResult parameter to TRUE and return. Otherwise, set it to FALSE before returning.

  5. If your provider is comparing a short-term entry identifier with a long-term identifier, they should compare equally.


Adding Address Book Entries

 Copy code hover
[image]

Adding Address Book Entries
Send feedback

Published: July 16, 2012

To add a messaging user or distribution list to a container, a client calls IAddrBook::NewEntry or a provider calls IMAPISupport::NewEntry with the entry identifier of the target container in the lpEIDContainer parameter. MAPI in turn calls the container's IABContainer::CreateEntry method to create the entry using a one-off template from a one-off table. A one-off template allows the client to create a new recipient of a particular type. Most of the fields are editable. The template pointed to by the lpEntryID parameter might be one that your provider supplies or it might be a template from a foreign provider, if your provider supports foreign templates. Implementations of CreateEntry for providers that can create recipients from a foreign template are always more complex than implementations for providers that cannot.

To implement IABContainer::CreateEntry

  1. Determine the type of entry identifier specified by the lpEntryID parameter.

  2. If the entry identifier represents a template for a messaging user, distribution list, or address book container owned by your provider:

    1. Create and initialize the appropriate object. Your provider can set some initial properties if desired. These properties depend on the type of recipient being created.

    2. Return a pointer to the object's implementation in the contents of the lppMAPIPropEntry parameter.

  3. If the entry identifier represents a template for a foreign provider:

    1. Call IMAPISupport::OpenEntry to open the foreign object.

    2. Call the object's IMAPIProp::GetProps method, passing NULL for the property tag array, to retrieve its properties.

    3. Edit the property value array returned from GetProps by changing the property tag to PR_NULL for all properties that will not apply to the new object and should not be transferred.

    4. Create an entry identifier for the new object.

    5. Create a new object of the appropriate type, either messaging user or distribution list.

    6. Initialize the new object by setting default properties.

    7. Check whether or not the foreign object supports the PR_TEMPLATEID (PidTagTemplateid) property.

    8. If the foreign object supports PR_TEMPLATEID, call IMAPISupport::OpenTemplateID to retrieve a property object interface from the foreign provider and set the contents of the lppMAPIPropEntry parameter to the foreign property object implementation.

    9. If the foreign object does not support PR_TEMPLATEID, set the contents of the lppMAPIPropEntry parameter to your provider's implementation of the new object.

    10. Call the IMAPIProp::SetProps method of the object pointed to by the lppMAPIPropEntry parameter to set the appropriate properties from the foreign object.


Copying Address Book Entries

 Copy code hover
[image]

Copying Address Book Entries
Send feedback

Published: July 16, 2012

Your container's IABContainer::CopyEntries method is called when one or more recipients from the same or another container are to be copied into this container. CopyEntries has four input parameters: an array of entry identifiers representing the recipients to be copied, a window handle for the progress indicator, a progress object pointer, and a flags value. Your provider should display progress if the AB_NO_DIALOG flag is not set and use the progress object from the lpProgress parameter if it is not NULL. If lpProgress is NULL, call IMAPISupport::DoProgressDialog to use the MAPI progress object. For more information about displaying progress, see Displaying a Progress Indicator.

In addition to AB_NO_DIALOG to suppress a progress indicator, one of two other flags can be set to request a type of duplicate entry checking: CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT. The CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags are only suggestions as to how your provider determines duplicate entries and can be ignored. MAPI suggests that your provider implement support for these flags as follows.

Duplicate entry flag | Suggested implementation
CREATE_CHECK_DUP_LOOSE | Check if the display name in the entry to be created matches the display name of an entry already in the container.
CREATE_CHECK_DUP_STRICT | Check if both the display name and the search key in the entry to be created match the display name and search key of a container entry.

The last flag, CREATE_REPLACE, indicates that the new entry should replace the existing one if your provider has determined that an entry to be created is a duplicate of an entry already in your container.

If your provider is a personal address book, include the PR_DETAILS_TABLE (PidTagDetailsTable) property in every copy operation. Including the details display table of a copied recipient enables your container to display the details of the recipient rather than having to call the original container to create the display.

To implement IABContainer::CopyEntries

  1. Determine if each entry identifier in the lpEntries parameter is in a format that your provider handles and if it is not, fail and return MAPI_E_INVALID_ENTRYID.

  2. If an entry identifier represents a messaging user, distribution list, or container that your provider handles:

    1. Call your IMAPISupport::OpenEntry method to open the corresponding recipient.

    2. Copy the recipient to your container.

  3. If the entry identifier represents a foreign recipient:

    1. Call your container's IABContainer::CreateEntry method to create a new recipient.

    2. Set initial properties on the new recipient.

  4. Call the new object's IMAPIProp::SaveChanges method to save it.

  5. Update the container's contents table to reflect the new recipient.

  6. Call IMAPISupport::Notify to send a table notification to registered clients.


Removing Address Book Entries

 Copy code hover
[image]

Removing Address Book Entries
Send feedback

Published: July 16, 2012

Your container's IABContainer::DeleteEntries method is called to remove one or more recipients. DeleteEntries has two parameters: an array of entry identifiers representing the recipients to be deleted and a reserved flags value. Deleting a recipient affects the contents table of your container; in addition to deleting the recipient, your container must delete the contents table row that represents the recipient. When the row has been removed from the table, your container must issue a table notification to each registered client.

To implement IABContainer::DeleteEntries

  1. Delete each recipient represented by the entry identifier from your container.

  2. If your container's contents table is open:

    • Send an fnevTableModified notification with the ulTableEvent member set to TABLE_ROW_DELETED to registered clients for each deleted contents table row. If your provider uses the notification utility, call IMAPISupport::Notify to send these notifications.

    • If your provider supports object notifications, also send an fnevObjectDeleted notification.


Implementing Name Resolution

 Copy code hover
[image]

Implementing Name Resolution
Send feedback

Published: July 16, 2012

Address book providers are responsible for supporting name resolution — the process of associating an entry identifier with a display name. Clients initiate name resolution when they call IAddrBook::ResolveName to ensure that each member of an outgoing message's recipient list corresponds to a valid address.

Your provider can support name resolution by:

  • Supporting the PR_ANR (PidTagAnr) property restriction, a requirement for all address book containers.

  • Implementing the IABContainer::ResolveNames method, an option for all address book containers.

If you choose to support IABContainer::ResolveNames, attempt to locate an exact match for each unresolved display name in the ADRLIST structure passed in with the lpAdrList parameter. You can identifiy an unresolved display name because it is missing the PR_ENTRYID (PidTagEntryId) property in the property value array in its aEntries member of the ADRLIST structure. Ignore any entries that have zero properties associated with them.

Report the result of your attempt at resolution in the lpFlagList parameter, an array of flags that corresponds to the array of display names in lpAdrList. The flags are positional such that the first flag corresponds to the first aEntries member in the ADRLIST structure, the second flag corresponds to the second aEntries member, and so on.

There are three possible results for each unresolved entry:

  • No match was found, meaning that none of the entries in your container entries match the entry in the ADRLIST structure. Set the corresponding entry in the lpFlagList parameter to MAPI_UNRESOLVED.

  • Several matches can be found, meaning that there are multiple container entries that match the entry in the ADRLIST structure. Set the corresponding entry in the lpFlagList parameter to MAPI_AMBIGUOUS. Do not change the number of entries in the ADRLIST structure.

  • An exact match can be found, meaning that there is only one container entry that matches the entry in the ADRLIST structure. Set the corresponding member in the lpFlagList parameter to MAPI_RESOLVED and add the entry identifier to the array of properties associated with the ADRLIST entry.

If you choose not to support IABContainer::ResolveNames, return MAPI_E_NO_SUPPORT from your implementation.

All address book providers are required to support ambiguous name resolution — the PR_ANR property restriction — on their containers' contents tables. To provide this support, handle the PR_ANR restriction in your implementation of IMAPITable::Restrict by performing a "best guess" type of search, matching against one or more particular properties that make sense for your provider. You can choose to use the same property or properties every time, such as PR_DISPLAY_NAME (PidTagDisplayName) or PR_ACCOUNT (PidTagAccount), or allow an administrator to choose from a list of acceptable properties.

Although most providers supply their own contents table implementation, you can customize the implementation supplied by MAPI through the CreateTable function. However, because the MAPI implementation does not support restrictions of any kind, you must create a wrapper object to include a customized version of Restrict that intercepts the call.


Displaying Recipient Information

 Copy code hover
[image]

Displaying Recipient Information
Send feedback

Published: July 16, 2012

MAPI provides a common dialog box for showing recipient details. The details dialog box is created from a display table and an IMAPIProp implementation. The display table describes the appearance of the details display and the IMAPIProp implementation controls the data for the recipient. Your provider is responsible for supplying the display table and the IMAPIProp implementation for each recipient.

The easiest way to create the display table is to define a DTPAGE structure and call BuildDisplayTable. However, some providers, specifically read-only providers that allow the creation of one-off recipients, use IPropData. The IMAPIProp implementation can be any type of property object.

There are two methods for invoking this dialog box: IAddrBook::Details and IMAPISupport::Details. When your provider calls one of these methods to request details for a recipient, MAPI first opens the recipient by calling its container's IMAPIContainer::OpenEntry method. Next it calls the recipient's IMAPIProp::OpenProperty method to request the PR_DETAILS_TABLE (PidTagDetailsTable) property. PR_DETAILS_TABLE is the property that represents a recipient's details display table.

The IPropData : IMAPIProp interface can be used to monitor changes on display table controls as described in the following procedure.

To monitor changes to a control

  1. Before the user gains access to the control, call IPropData::HrSetObjAccess to set the control's access to IPROP_CLEAN.

  2. Allow the user to work with the dialog box.

  3. When the user has finished, call IPropData::HrGetPropAccess to retrieve the current access level of the control.

  4. If the access level is IPROP_DIRTY, the user has modified the control. Your provider should:

    • Call IPropData::HrSetPropAccess to set the access level back to IPROP_CLEAN.

    • Call the property data object's IMAPIProp::GetProps method to retrieve the changed property and update it by calling IMAPIProp::SetProps.

  5. If the access level is still IPROP_CLEAN, the control has not been modified.

For more information about creating display tables, see Display Tables.


Optional Features for Address Book Providers

 Copy code hover
[image]

Optional Features for Address Book Providers
Send feedback

Published: July 16, 2012

There are many optional features for address book providers. Some of the more commonly implemented features include:

  • Acting as a foreign provider by allowing entries from one of your containers to be added to another provider's container.

  • Acting as a host provider by adding entries from another provider to one of your containers.

  • Advanced searching.

  • Prefix scrolling through contents tables.

  • Support for distribution lists.

  • Support for event notification.

The following table briefly describes these optional features and how you implement them:

Feature

How to implement

Supply templates for creating entries for message recipient lists

Implement the IABLogon::GetOneOffTable method. For more information, see One-Off Tables and Implementing One-Off Tables.

Group recipients into a named unit

Support the properties of distribution lists by implementing the IDistList : IMAPIContainer interface.

Act as a foreign address book provider by allowing entries to be added to a container in another provider

Support binding code to data in the host provider by:

  1. Supporting the PR_TEMPLATEID (PidTagTemplateid) property on messaging users and distribution lists. For more information, see Address Book Identifiers.

  2. Implementing the IABLogon::OpenTemplateID method. For more information, see Acting as a Foreign Address Book Provider.

Acting as a host address book provider by inserting entries from another provider

Support binding data to code from a foreign provider by calling the IMAPISupport::OpenTemplateID method. For more information, see Acting as a Host Address Book Provider.

Prefix scrolling

Support restrictions on container contents tables. For more information, see About Restrictions.

Advanced searching in a container

Support the PR_SEARCH (PidTagSearch) property on containers. For more information, see Implementing Advanced Searching.

Event notification

Implement the IABLogon::Advise and IABLogon::Unadvise methods. For more information, see Event Notification in MAPI and Supporting Event Notification.

For event notification, your IABLogon::Advise method will be called by MAPI when a client calls IAddrBook::Advise to register for notifications on any one of your containers, messaging users, or distribution lists. However, because supporting event notification is optional, you can return MAPI_E_NO_SUPPORT from these methods. However, MAPI does recommend that you at least support notifications on your contents tables and encourages you to support all types of object notification except for fnevSearchComplete and the fnevCriticalError event to add value.


Acting as a Foreign Address Book Provider

 Copy code hover
[image]

Acting as a Foreign Address Book Provider
Send feedback

Published: July 16, 2012

A foreign provider is an address book provider that:

  • Assigns template identifiers for its recipients.

  • Supports the IABLogon::OpenTemplateID method.

  • Supplies code for maintaining recipients that exist in the containers of other address book providers known as host providers. This code involves a property object, typically an IMAPIProp interface implementation, which wraps a property object from the host provider.

Acting as a foreign provider is an optional role; not all providers need to support template identifiers and their related code. Implement your provider as a foreign provider if you want to maintain control over recipients that host providers create using templates supplied by your provider.

The format that your provider uses for its entry identifiers can also be used for its template identifiers. Template identifiers must include your provider's registered MAPIUID to enable MAPI to successfully bind recipients to the appropriate providers.

MAPI calls your provider's IABLogon::OpenTemplateID method when a host provider calls IMAPISupport::OpenTemplateID. The host provider passes the template identifier of the recipient in the lpTemplateID parameter in its call to IMAPISupport::OpenTemplateID. MAPI determines that the template identifier belongs to your provider by matching the MAPIUID in the template identifier with the MAPIUID that your provider registered at logon time. MAPI then forwards the host provider's call to your provider through the IABLogon::OpenTemplateID method.

The host provider also passes a pointer to its property object implementation for the recipient in the lpMAPIPropData parameter, an interface identifier in the lpInterface parameter that corresponds to the type of interface implementation passed in lpMAPIPropData, and an optional flag, FILL_ENTRY. Your provider is expected to return in the lppMAPIPropNew parameter a pointer to a property object implementation of the type specified in lpInterface. The returned pointer can either be to the wrapped property object implemented by your provider or to the object supplied by the host provider in lpMAPIPropData. Your provider should return a wrapped property object pointer when:

  • The recipient's display table contains list box controls.

  • The e-mail address for the recipient must be assembled from data in multiple display table controls.

  • Your provider issues display table notifications.

The FILL_ENTRY flag indicates to your provider that the host provider requires all the properties of the recipient to be updated. Your provider is required to fulfill this request.

When a host provider calls your provider's OpenTemplateID method, your provider might:

  • Periodically update the data for a copied entry.

  • Keep a copied entry synchronized with its original, such as when an address book entry is copied to the personal address book.

  • Implement functionality that cannot be implemented by the host provider, such as dynamically populating list boxes in the copied entry's details table from data on a server.

  • Control the interaction among properties in a copied entry or instantiated template. For example, computing PR_EMAIL_ADDRESS from other properties displayed in the details table.

The first two items are examples of tasks that do not require your provider to supply a wrapped property object — an implementation of IMAPIProp that is based on the host provider's implementation. Your provider can simply update the properties as necessary and return, setting the lppMAPIPropNew parameter to point to the pointer passed in by the host provider in the lpMAPIPropData parameter.

The second two tasks require that your provider return to the host provider a property object that wraps the host provider's object with additional functionality, such as the ability to display a property sheet for the entry. This property object will either be a messaging user or distribution list, depending on the type of object passed in by the host provider in the lpMAPIPropData parameter and indicated by the interface identifier in the lpInterface parameter. If the lpMAPIPropData parameter points to a messaging user, your provider's wrapped property object must be an IMailUser implementation. If lpMAPIPropData points to a distribution list, it must be an IDistList implementation.

Your provider's wrapped property object intercepts IMAPIProp method calls to perform context-specific manipulation of the host provider's recipient — the object it is wrapping. MAPI only has one requirement for wrapped property objects: all calls to IMAPIProp::OpenProperty requesting the PR_DETAILS_TABLE (PidTagDetailsTable) property should be passed to the host provider. Your provider's implementation can use the returned table to intercept display table notifications or to add its own if necessary.

The following list includes tasks that are typically implemented in the wrapped property object implemented by foreign providers:

  • Preprocessing and postprocessing property values for the host recipient in IMAPIProp::GetProps.

  • Handling details display table controls, such as buttons and list boxes, in IMAPIProp::OpenProperty.

  • Validating or manipulating property values for the host recipient in IMAPIProp::SetProps.

  • Computing required properties such as PR_EMAIL_ADDRESS and verifying that all of the necessary properties have been set before saving the host recipient in IMAPIProp::SaveChanges.

To implement IABLogon::OpenTemplateID

  1. Check if the template identifier passed in with the lpTemplateID parameter is valid and is in a format that your provider recognizes. If it is not, fail and return MAPI_E_INVALID_ENTRYID.

  2. Create an object of the type indicated by the template identifier, either a messaging user, distribution list, or one-off recipient.

  3. Call the IUnknown::AddRef method in the host provider's property object, which is the object pointed to by the lpMAPIPropData parameter.

  4. If the ulTemplateFlags parameter is set to FILL_ENTRY:

    1. If the new object is a messaging user or distribution list:

      1. Retrieve all of the properties of the new object, possibly by calling its IMAPIProp::GetProps method.

      2. Call the host provider's IMAPIProp::SetProps method to copy all of the retrieved properties to the host provider's property object.

    2. If the new object is a one-off recipient, call the host provider's IMAPIProp::SetProps method to set the following properties:

      • PR_ADDRTYPE (PidTagAddressType) to the address type handled by your provider.

      • PR_TEMPLATEID (PidTagTemplateid) to the template identifier from the lpTemplateID and cbTemplateID parameters.

      • PR_DISPLAY_TYPE (PidTagDisplayType) to DT_MAILUSER or DT_DISTLIST, as appropriate.

  5. Set the contents of the lppMAPIPropNew parameter to point to either your provider's new object or the property object passed in with the lpMAPIPropData parameter, depending on whether your provider determines a wrapped object is necessary.

  6. If a critical error occurs, such as a network failure or an out of memory condition, return the appropriate error value. This value should get propagated to the client with the appropriate MAPIERROR structure, a task performed by the host provider.


Acting as a Host Address Book Provider

 Copy code hover
[image]

Acting as a Host Address Book Provider
Send feedback

Published: July 16, 2012

A host provider is an address book provider that includes recipients from other providers in its containers and relies on the implementation of the recipients by the other providers to partially control their maintenance. A host provider uses the template identifiers of these foreign recipients to bind the data for these recipients to code in the foreign provider. This binding process is initiated when your provider retrieves the PR_TEMPLATEID (PidTagTemplateid) property of a recipient and passes it in a call to IMAPISupport::OpenTemplateID.

When your provider calls IMAPISupport::OpenTemplateID, MAPI matches the MAPIUID within the template identifier with a MAPIUID registered by a provider and calls the provider's IABLogon::OpenTemplateID method. The foreign provider might return a pointer to your provider's property object, to its own property object implementation, or to an implementation that wraps your provider's object. The returned pointer is placed in the contents of the lppMAPIPropNew parameter.

Your provider can choose whether or not to call IMAPISupport::OpenTemplateID with the FILL_ENTRY flag set. Set this flag when the recipient is being created or when a long time has passed since your provider has refreshed the recipient's properties. A common use of the FILL_ENTRY flag is to keep a recipient in your provider synchronized with the original. Implementing this type of synchronization schedule enhances performance.

To keep a foreign recipient synchronized

  1. Determine an appropriate interval for periodic updates.

  2. Timestamp each call to IMAPISupport::OpenTemplateID.

  3. Evaluate whether or not it is necessary to perform a full update based on the amount of time that has expired since the last call. If a full update is necessary, call IMAPISupport::OpenTemplateID with the FILL_ENTRY flag. If it is not necessary, do not set the flag on the call.

When a client makes a request for one of the copied recipient's properties, your provider can choose whether to handle the request itself or use the code supplied by the foreign provider. Your provider can expect the foreign provider to intercept most, if not all, calls to IMAPIProp except for IMAPIProp::OpenProperty. A call to OpenProperty requesting the PR_DETAILS_TABLE (PidTagDetailsTable) property is always forwarded to your provider.

To access template identifier code

  1. Open the recipient and call its IMAPIProp::GetProps method to retrieve the PR_TEMPLATEID (PidTagTemplateid) property. If GetProps fails because PR_TEMPLATEID is unavailable, the foreign provider does not support a template identifier and related code for this recipient. Your provider will need to use its implementation of the recipient for all maintenance.

  2. If the template identifier is returned from GetProps, pass it and a pointer to the recipient's IMAPIProp implementation in a call to the IMAPISupport::OpenTemplateID method. Set the FILL_ENTRY flag if most or all of the recipient's properties need to be updated, such as at creation time or if they have not been updated for a while.

  3. If OpenTemplateID returns the foreign provider's IMAPIProp implementation, return to the client a pointer to this implementation.

  4. If OpenTemplateID does not return an implementation, typically because the foreign provider is not in the profile, return to the client a pointer to your provider's IMAPIProp implementation. The client should be able to work with the object's properties using either interface.


Implementing Advanced Searching

 Copy code hover
[image]

Implementing Advanced Searching
Send feedback

Published: July 16, 2012

Some address book containers support an advanced searching capability that allows clients to search on properties other than PR_DISPLAY_NAME (PidTagDisplayName). To support advanced searches, your provider must implement a special container that is accessible through the PR_SEARCH (PidTagSearch) property of your other containers. PR_SEARCH contains a container object that provides access to a display table that describes the dialog box used to enter and edit the advanced search criteria.

To support advanced searching

  1. Define a property for each of your search criteria.

  2. In the section of code in your container's IMAPIProp::OpenProperty method that handles the PR_SEARCH property:

    1. Check that the client is requesting the IMAPIContainer interface. If an inappropriate interface is being requested, fail and return MAPI_E_INTERFACE_NOT_SUPPORTED.

    2. Create a new search object that supports the IMAPIContainer interface.

  3. At this point, a call will be made to your search container's IMAPIProp::OpenProperty method to retrieve its PR_DETAILS_TABLE (PidTagDetailsTable) property. Your provider must supply a display table, typically through a call to BuildDisplayTable, that describes the container's advanced search dialog box.

  4. MAPI displays the search dialog box, allowing the user to enter the appropriate criteria. When the user has finished, MAPI calls the container's IMAPIProp::SetProps method to store the search criteria.

  5. A call will be made to request your search container's contents table. Populate the contents table with all of the entries in the container that match the criteria.


Implementing One-Off Tables

 Copy code hover
[image]

Implementing One-Off Tables
Send feedback

Published: July 16, 2012

Your provider might implement one or more one-off tables. A one-off table is a summary list of one-off templates used to create recipients, either directly into a container or into the recipient list of an outgoing message. A one-off template is a form users employ for entering data relevant to a particular type of address. When the user is finished working with the template, your provider creates the new recipient and adds it to the message. Typically each template handles a single address type. However, it is possible for a template to handle multiple types or for multiple templates to handle the same type.

Your provider must support the OpenEntry method for each template that it includes in the one-off table. The implementation of OpenEntry should retrieve a display table for the template. MAPI uses the display table to make the template visible to the user.

Although most of the rows in one-off tables represent templates, some of the rows can be used to categorize, or group, templates. Whether or not a row in a one-off table represents a template is indicated by the value of its PR_SELECTABLE (PidTagSelectable) column. Rows that represent templates have the PR_SELECTABLE column set to TRUE; rows that do not represent templates have it set to FALSE.

MAPI defines three types of one-off tables:

  • A one-off table that reflects the templates that an individual container supports

  • A one-off table that reflects all of the templates that your provider supports

  • A one-off table that reflects all of the templates that all of the providers in the profile support plus some that MAPI supports

The first two types are implemented by providers that support the creation recipients, either onto a message or into a container. Your provider can include the same set or a different set of templates in its one-off tables. The main difference between the two types is that your provider table should include templates for creating recipients that can be used on outgoing messages and your container table should include templates for creating recipients to be added to your container. A container may only support a restricted set of templates, but the provider one-off table should include every template the provider supports.

The third type of one-off table is implemented by MAPI; providers gain access to it by calling IMAPISupport::GetOneOffTable. The MAPI one-off table is the union of all of the provider tables; it includes every template supported by every provider in the profile. It also includes templates supported by MAPI. Your provider can use this table in place of the table requested for a container. However, the templates in this table can also be used for creating recipients for outgoing messages.


Implementing a Provider One-Off Table

 Copy code hover
[image]

Implementing a Provider One-Off Table
Send feedback

Published: July 16, 2012

MAPI calls your provider's IABLogon::GetOneOffTable method when the user of a client application adds a recipient to an outgoing message. Typically, the types of addresses requested are unique to your messaging system. If your provider supports recipient creation, it must supply a one-off table that exposes templates for every type of supported recipient address. If your provider does not support recipient creation, return MAPI_E_NO_SUPPORT from the GetOneOffTable call.

MAPI will typically keep your provider's one-off table open for the lifetime of the session, releasing it only when a client calls either the subsystem's or address book's IMAPIStatus::ValidateState method. MAPI registers for notifications on this table so that if templates are added or deleted, these changes can be reflected to the user.

To implement IABLogon::GetOneOffTable

  1. Check the value of the flags parameter, ulFlags. If the MAPI_UNICODE flag is set and your provider does not support Unicode, fail and return MAPI_E_BAD_CHARWIDTH.

  2. Check if your provider's one-off table has already been created. Because one-off tables are typically static, your provider never has to go through the creation process more than once. If a table already exists, return a pointer to it.

  3. If a one-off table does not yet exist, call CreateTable to create one.

  4. Set the following properties for the columns in your table rows:

    • PR_DISPLAY_NAME (PidTagDisplayName) to the name of the type of recipient that the template can create.

    • PR_ENTRYID (PidTagEntryId) to the entry identifier for the one-off template.

    • PR_DEPTH (PidTagDepth) to indicate the hierarchy level in the one-off table display.

    • PR_SELECTABLE (PidTagSelectable) to TRUE to indicate if the row represents a template and FALSE otherwise.

    • PR_ADDRTYPE (PidTagAddressType) to the type of address created by the template.

    • PR_DISPLAY_TYPE (PidTagDisplayType) to DT_MAILUSER or another value that indicates the type of display for the template.

    • PR_INSTANCE_KEY (PidTagInstanceKey) to a unique binary value.

  5. Call ITableData::HrModifyRow to modify the table directly.

  6. Call ITableData::HrGetView to create an IMAPITable interface implementation to return to the caller.


Implementing a Container One-Off Table

 Copy code hover
[image]

Implementing a Container One-Off Table
Send feedback

Published: July 16, 2012

To access the one-off table belonging to one of your containers, MAPI calls the container's IMAPIProp::OpenProperty method to open the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property with the IMAPITable interface. Your container is asked to return its one-off table when a client application is trying to add a recipient to the container. If the container allows any recipients, your provider can either return its own table implementation or call IMAPISupport::GetOneOffTable to return the MAPI implementation.

The set of templates in the container one-off table should reflect the type of recipients that the particular container can hold. Typically, this includes one or two templates, templates for creating an individual messaging user or a distribution list. The entry identifiers for these templates are held in the PR_DEF_CREATE_MAILUSER (PidTagDefCreateMailuser) and PR_DEF_CREATE_DL (PidTagDefCreateDl) properties. However, containers are by no means limited to these types of entries. They can hold other types of recipients or non-recipient entries such as directories.


Developing a MAPI Transport Provider

 Copy code hover
[image]

Developing a MAPI Transport Provider
Send feedback

Published: July 16, 2012

You should be familiar with the MAPI subsystem architecture, the C++ language, and with writing dynamic-link libraries (DLLs) for the various Windows platforms before developing a transport provider.


Transport Provider Overview

 Copy code hover
[image]

Transport Provider Overview
Send feedback

Published: July 16, 2012

A transport provider is a dynamic-link library (DLL) which acts as an intermediary between the MAPI subsystem and one or more underlying messaging systems. A messaging system is some specific mechanism by which messages are sent and received. Some examples of messaging systems are:

  • A shared network file system that the transport provider writes messages to directly.

  • A TCP/IP network interface that the transport provider uses to connect to a messaging server.

  • An online service that users connect to.

  • A host-based messaging or office automation system.

  • A set of remote procedure calls to a messaging server.

  • Anything that can be used to transfer data from one computer to another.

A transport provider DLL must conform to the interface specified by MAPI. As a transport provider developer, you will implement this interface in terms of the functionality present in the messaging system.


Types of Transport Providers

 Copy code hover
[image]

Types of Transport Providers
Send feedback

Published: July 16, 2012

All transport providers support a range of standard features, such as:

  • Providing proper security for the underlying messaging system.

  • Sending and receiving messages from the underlying messaging system.

  • Exposing the address types the transport providers support so the MAPI spooler and client applications can use them appropriately.

  • Accepting delivery for specific recipients.

In addition, MAPI supports two specialized types of providers for specific messaging systems.

Transport type | Added functionality
Remote Transport | Enables interoperability with clients connected remotely.
TNEF Transport | Allows MAPI properties to be preserved on messaging systems that do not support them.

TNEF transports are used for translating messages between messaging systems that support different sets of MAPI properties. TNEF transports use the MAPI ITnef : IUnknown interface to convert any properties that the destination system cannot represent directly into a binary data stream that can be attached to the message. Later, another TNEF transport can use ITnef to decode the data stream and make the original MAPI properties available to client applications. Additionally, TNEF support is required if your transport needs to support custom message classes. For information about implementing TNEF transports, see Developing a TNEF-Enabled Transport Provider.

If your transport provider is not one of these types, you will have to implement it with the basic MAPI functions and networking functions available on your target platform.


Transport Provider Role in the MAPI Subsystem

 Copy code hover
[image]

Transport Provider Role in the MAPI Subsystem
Send feedback

Published: July 16, 2012

Transport provider dynamic-link libraries (DLLs) provide the interface between the MAPI spooler and the part of a messaging system responsible for message sending and receiving. The MAPI spooler and the transport provider work together to handle the responsibilities of sending a message or receiving a message. The MAPI spooler loads the transport provider DLL when it is first used and releases it when it is no longer needed. Multiple transport providers can be installed on the same system, but MAPI supplies the one spooler required.

Client applications do not typically communicate directly with the transport provider. Rather, clients submit messages through a store provider and the MAPI spooler sends outgoing messages to the appropriate transport provider and delivers incoming messages to the appropriate message store. The MAPI spooler does its work and makes its calls to transport providers when foreground applications are idle. After optionally displaying dialog boxes when the transport provider is first logged on, transport providers operate in the background unless called by the client to flush send and receive queues.

Transport providers have the following responsibilities in a MAPI messaging system:

  • Register the address types they can accept with the MAPI spooler so the MAPI spooler can submit messages to the appropriate transport provider depending on the destination address of the messages. One transport provider can register more than one address type. Transport providers can also register specific recipients' addresses with the MAPI spooler. Messages addressed to one of these addresses will be submitted to the transport provider that registered the address with the MAPI spooler. For more information, see Transport Provider and MAPI Spooler Operational Model.

  • Deliver incoming messages to the MAPI spooler. Depending on the nature of the messaging system, a transport provider can either directly notify the MAPI spooler when a new message arrives, or it can request that the MAPI spooler poll the transport provider periodically to check for new messages.

  • Convert MAPI message properties to and from message properties native to the messaging system. For example, the transport provider might have to convert the sender's and recipient's addresses in an outgoing message to a form that is acceptable to the messaging system. Some messaging systems do not support all of the MAPI message properties. For more information about preserving MAPI message properties when delivering messages to a messaging system, see Developing a TNEF-Enabled Transport Provider.

  • Register message and recipient options specific to the transport provider.

  • Perform any verification of credentials required by the messaging system.

  • Access outbound messages using the message object passed to it by the MAPI spooler.

  • Translate message format as required by the underlying messaging system.

  • Notify the MAPI spooler which recipients of an outgoing message the transport provider has accepted responsibility for handling by setting the PR_RESPONSIBILITY (PidTagResponsibility) property for those recipients.

  • Inform the MAPI spooler when an incoming message needs to be handled.

  • Pass incoming message data to the MAPI spooler by using message objects.

  • Assign values to all required MAPI message properties on incoming messages.

  • Delete the message from the underlying messaging system after delivery, if necessary.

  • Provide status information for the MAPI spooler and client applications.

The following illustration shows a transport provider's role with respect to the other components of the MAPI architecture.

Transport provider role in a messaging system

Transport provider role in a messaging system


Transport Provider and MAPI Spooler Operational Model

 Copy code hover
[image]

Transport Provider and MAPI Spooler Operational Model
Send feedback

Published: July 16, 2012

Transport provider initialization, startup, processing, shutdown and deinitialization are accomplished by a series of calls from the MAPI spooler to the transport provider. The calls are sequenced as follows:

  1. The MAPI spooler calls the XPProviderInit function, passes a support object, gets the provider object, and checks that the transport provider and MAPI spooler support a compatible range of MAPI version numbers.

  2. The MAPI spooler calls the IXPProvider::TransportLogon method of the IXPProvider : IUnknown interface. A session is established between the MAPI spooler and the transport provider with the credentials in the current section of the profile. The transport provider returns a logon object.

  3. The MAPI spooler calls the IXPLogon::AddressTypes method. The transport provider returns a list of the unique identifiers (UIDs) and e-mail address types it will accept.

  4. The transport provider calls the IMAPISupport::ModifyStatusRow method to create its row in the MAPI status table.

  5. The MAPI spooler calls the IXPLogon::TransportNotify method to enable message transmission and reception.

  6. If requested by the transport provider in its return for the TransportLogon call, the MAPI spooler periodically calls the IXPLogon::Idle method. Idle processing is useful if the transport provider needs to poll the underlying messaging system for new messages or perform other low-priority tasks.

  7. The MAPI spooler and transport provider send and receive messages. For more information, see Message Submission Model and Message Reception Model. The MAPI spooler services transport requests and calls on support, message, and attachment objects.

  8. The MAPI spooler calls the TransportNotify method to disable message transmission and reception.

  9. The MAPI spooler releases the logon and provider objects. For more information, see the IXPProvider::Shutdown method.


Message Submission Model

 Copy code hover
[image]

Message Submission Model
Send feedback

Published: July 16, 2012

Message submission is accomplished by a series of calls from the MAPI spooler to the transport provider. The calls are sequenced as follows:

  1. The MAPI spooler calls IXPLogon::SubmitMessage, passing in an IMessage : IMAPIProp instance, to begin the process.

  2. The transport provider then places a reference value — a transport-defined identifier used in future references to this message — in the location referenced in SubmitMessage.

  3. The transport provider accesses the message data by using the passed IMessage instance. For each recipient in the passed IMessage for which it accepts responsibility, the transport provider sets the PR_RESPONSIBILITY (PidTagResponsibility) property, and then returns.

  4. The transport provider can use the IMAPISupport::StatusRecips method to indicate if it recognizes any recipients that cannot be delivered to, or to create a standard delivery report. StatusRecips is a convenience for transport providers that have determined that some of the recipients cannot be delivered to or that have received delivery information from their underlying messaging system that the user or client application might find useful.

  5. The MAPI spooler's call to IXPLogon::EndMessage is the final responsibility hand-off for the message from the MAPI spooler to the transport provider.

  6. The MAPI spooler can use IXPLogon::TransportNotify to cancel message processing during the SubmitMessage or EndMessage calls.


Message Reception Model

 Copy code hover
[image]

Message Reception Model
Send feedback

Published: July 16, 2012

The transport provider controls whether the MAPI spooler must poll it for incoming mail or whether it performs a call back to the MAPI spooler when new mail arrives. The transport provider sets the SP_LOGON_POLL flag when it returns from IXPProvider::TransportLogon to request polling. Otherwise, the transport provider uses IMAPISupport::SpoolerNotify when incoming mail is available. After learning that incoming mail is available, the MAPI spooler opens a new message and asks the transport provider to store the received message properties into the message.

This process works as follows:

  1. Available messages are indicated by either the transport provider calling IMAPISupport::SpoolerNotify or by the MAPI spooler calling IXPLogon::Poll.

  2. The MAPI spooler calls IXPLogon::StartMessage to initiate the process.

  3. The transport provider places a reference value in the location referenced in StartMessage. These reference values allow the transport provider and the MAPI spooler to keep track of which message is being processed when there are multiple messages to deliver.

  4. The transport provider stores the message data into the passed IMessage : IMAPIProp instance.

  5. The transport provider calls the IMAPIProp::SaveChanges method on the IMessage instance and returns from StartMessage.

  6. The MAPI spooler calls IXPLogon::TransportNotify if it must stop message delivery.

Note Note

If a transport provider must deliver a large number of messages and the transport provider is using IMAPISupport::SpoolerNotify instead of IXPLogon::Poll, care should be taken not to call SpoolerNotify too frequently in order not to deprive other transport providers of CPU time. The MAPI spooler does have logic to prevent this from happening, but in general the interval between SpoolerNotify calls should be longer than the time it takes your transport provider to process one message.

Also, the MAPI spooler may not process an incoming message immediately. The MAPI spooler may ask the transport provider to perform other tasks before it receives the incoming message.


Required Functionality for Transport Providers

 Copy code hover
[image]

Required Functionality for Transport Providers
Send feedback

Published: July 16, 2012

Every MAPI transport provider must:

  • Follow the general guidelines for working with MAPI and other service providers. For more information, see MAPI Application Development and MAPI Service Providers.

  • Have its transport provider DLL expose to MAPI its XPProviderInit initialization function.

  • Expose to MAPI its implementation of the IXPProvider : IUnknown and IXPLogon : IUnknown interfaces.

  • Expose to MAPI and client applications its implementation of the IMAPIStatus : IMAPIProp interface. For more information about implementing IMAPIStatus, see Status Object Implementation.

  • Implement a property sheet dialog box for configuration. For more information about implementing property sheets, see Property Sheet Implementation.


Interaction of MAPI Providers and Components

 Copy code hover
[image]

Interaction of MAPI Providers and Components
Send feedback

Published: July 16, 2012

MAPI service providers of any kind must follow certain guidelines to work with other MAPI components. Each service provider must:

  • Use the proper provider and logon objects for initialization.

  • Return a dispatch table of provider entry points to the messaging system upon initialization.

  • Register a MAPI status table row for each resource owned by the provider and call the IMAPISupport::ModifyStatusRow method at appropriate times.

  • Use the IMAPISupport::NewUID method to obtain valid unique identifiers (UIDs).

  • Support the common MAPI interfaces on objects it returns.

  • Use the MAPI memory allocation functions to allocate memory returned to client applications and to release memory allocated by other parts of the MAPI subsystem.

  • Maintain a profile section, if necessary, to store credentials to the underlying messaging system.

  • Use the IMAPISupport::RegisterPreprocessor method to register any message preprocessing functions.

  • Include the proper header files (including mapispi.h) that define common constants, structures, interfaces, and return values.

  • Follow address format conventions for common address types.


Interacting with the MAPI Spooler

 Copy code hover
[image]

Interacting with the MAPI Spooler
Send feedback

Published: July 16, 2012

The methods in the IXPLogon : IUnknown interface are used by the MAPI spooler when calling the transport provider. It should be possible for most types of transport providers to implement most of these methods so that they return quickly. This is desirable because if a method takes a long time to return then it should be broken up with calls back to the MAPI spooler to release the CPU for other tasks.

The MAPI spooler does its work and makes its calls to transport providers when foreground applications are idle. After optionally displaying dialog boxes when the transport provider is first logged on (governed by flags passed from MAPI to the transport provider), transport providers operate in the background unless called by the client to flush send and receive queues. Flushing queues is the only time that a transport provider need not release the CPU, and then only if the user is informed that a potentially long action is in progress. The MAPI spooler typically requests that a transport provider flush its queues in response to a user action, so the transport provider typically does not need to do anything to ensure that the user is informed.

A transport provider can independently decide to flush a queue and use the STATUS_INBOUND_FLUSH and STATUS_OUTBOUND_FLUSH bits in the PR_STATUS_CODE (PidTagStatusCode) property of its status row to inform the MAPI spooler that it wants attention so that it can get the job done. The status row is updated using the IMAPISupport::ModifyStatusRow method. In this case the transport provider should probably display a progress indicator or other interface to inform the user that a long action is occuring.

Since network activity often takes more than 0.2 seconds, transport providers should, whenever possible, use asynchronous network requests. This enables them to initiate a request, release the CPU by calling back to the MAPI spooler, and when the MAPI spooler again gives them control, to check to see if their network request has completed. If it has not yet completed, they again release the CPU by calling back to the MAPI spooler with the IMAPISupport::SpoolerYield method.

During message processing, between IXPLogon::SubmitMessage and IXPLogon::EndMessage and during IXPLogon::StartMessage, the transport provider typically makes many calls on objects exposed to it by the MAPI spooler. As part of its handling of these objects, the MAPI spooler helps the transport provider behave appropriately as a background process by yielding on its own when appropriate. A transport provider requiring time-critical processing can declare a critical section to the MAPI spooler using the IMAPISupport::SpoolerNotify support object method. In this case, the CPU is released only on explicit SpoolerYield calls by the transport provider until the transport provider ends critical section processing with another call to SpoolerNotify.

Note Note

This is not the same as a Win32 critical section. This should only be done when the transport provider needs real-time control of external resources such as reading incoming data from a fax line. Since this raises the priority of the MAPI spooler process and can cause the workstation to be unresponsive for the duration of the operation, it is a good idea to notify the user that a potentially long action is underway and provide a progress indicator if possible.


Initializing the Transport Provider

 Copy code hover
[image]

Initializing the Transport Provider
Send feedback

Published: July 16, 2012

The transport-spooler interface defines calls the MAPI spooler makes to a transport provider. Transport providers implement these routines in a dynamic-link library (DLL). The first direct entry point into the DLL used by the MAPI spooler must be the transport provider initialization function XPProviderInit.

MAPI uses the routine GetProcAddress to get the address of the service provider's initialization routine and then calls that routine. The name of the initialization routine is XPProviderInit for transport providers. It is different for other types of MAPI service providers so that one DLL can contain any combination of service provider types, but only one service provider of a particular type. However, one service provider of a given type can implement multiple services of its type. For example, one transport provider can implement message transport functionality to multiple message services.

The mapispi.h header file has a type definition for the function prototype of the transport provider initialization function, and a predefined procedure name for it. By naming the initialization routines in your C and C++ files with the same names used by GetProcAddress and by using a straightforward export declaration in your DLL.DEF file, you automatically get type checking of the parameters on your initialization routine. See the sample transport provider source code for examples. For more information, see Transport Provider Sample.

If a service provider's initialization call succeeds but returns a service provider interface version number too small for MAPI to handle, MAPI immediately calls the Release method of the service provider object and proceeds as if the initialization call had failed with MAPI_E_VERSION. This way MAPI and the service provider jointly define the range of service provider interface version numbers they can handle, and if nothing matches then service provider loading fails with a MAPI_E_VERSION return value.

The last step for the MAPI spooler in getting access to service provider resources is to log on to the transport provider. The MAPI spooler calls the IXPProvider::TransportLogon method of the IXPProvider : IUnknown object returned from XPProviderInit. This is the call where credentials, if used, are checked and dialog boxes can be allowed.

If a process opens a second transport session on the same transport provider and MAPI session, the transport provider DLL should not create a second provider object. The first provider object should be used to log on to the second transport session. A transport provider should be programmed to support multiple transport sessions in a single provider object. A second provider object should only be created if different MAPI sessions are used in the same process.


Releasing the Transport Provider

 Copy code hover
[image]

Releasing the Transport Provider
Send feedback

Published: July 16, 2012

When MAPI or the MAPI spooler finishes using a transport logon object:

  1. MAPI or the MAPI spooler calls the transport provider's IXPLogon::TransportLogoff method.

  2. The transport provider invalidates the status object by calling the IMAPISupport::MakeInvalid method. Whether the transport provider invalidates message objects that are being sent or received at the time of the TransportLogoff call depends on the flags that were passed to TransportLogoff.

  3. The transport provider calls the support object's IUnknown::Release method to remove the transport provider's row from the status table and remove from internal tables any unique identifiers (UIDs) that were set with the IMAPISupport::SetProviderUID method. It decrements the count of known logon objects active on this provider object. If the count reaches zero, MAPI calls the IXPProvider::Shutdown method and Release on the provider object. If this was the last known provider object using this DLL on this process, MAPI calls the FreeLibrary function on the DLL at a later time. Memory for the MAPI support object is freed and the support object Release method returns.

  4. The TransportLogoff method returns S_OK.

  5. MAPI or the MAPI spooler calls Release on the transport provider's logon object. The memory for the object is released.

  6. MAPI or the MAPI spooler calls FreeLibrary on the provider DLL.

For robustness, the logon and provider objects should be able to handle final Release calls on themselves without first having their TransportLogoff or Shutdown methods called. If Release is called in such cases, transport providers should treat the calls as if TransportLogoff or Shutdown had been called with a zero argument followed by Release.


Implementing the FlushQueues Method

 Copy code hover
[image]

Implementing the FlushQueues Method
Send feedback

Published: July 16, 2012

The MAPI spooler uses the IXPLogon::FlushQueues method to download and upload any pending messages to and from a transport provider. Typically, the MAPI spooler will flush the queues for all transport providers that are logged on to the session, starting with the first transport provider as set in the transport order section of the user's profile. Flushing queues is almost always the result of a direct request by the user, so the sending and receiving of messages while queues are flushing is synchronous to the MAPI spooler. Because these calls are synchronous, the transport provider should process them as quickly as possible.

Transport providers must handle the FlushQueues call as described in the following sequence of steps to enable proper message processing and to enable external resources such as modems to be used by other transport providers as part of the MAPI spooler's FlushQueues operation.

Step

Component

Implementation

1.

MAPI spooler

Calls the FlushQueues method for the first transport provider listed in the transport order of the user's profile, passing the requested flags in the ulFlags parameter. FlushQueues is called once with all flags set for the entire upload and download operation.

2.

Transport Provider

Needs to do a number of things before returning from the FlushQueues call. If previously submitted messages are being deferred, the IMAPISupport::SpoolerNotify method should be called with the NOTIFY_SENT_DEFERRED flag set. Note that it is possible for the MAPI spooler to cancel a message that has been deferred before the transport provider has a chance to finish processing the message.

If the transport provider uses an external resource such as a modem, the connection to the external resource should be established.

The STATUS_OUTBOUND_FLUSH bit in the PR_STATUS_CODE (PidTagStatusCode) property of the transport provider's status row must be set using the IMAPISupport::ModifyStatusRow method.

The transport provider should then return S_OK for the FlushQueues call.

3.

MAPI spooler

Checks the transport provider's status row for the STATUS_OUTBOUND_FLUSH bit and calls IXPLogon::SubmitMessage for the first message in the queue.

4.

Transport provider

Handles the message and returns from the SubmitMessage call.

5.

MAPI spooler

If the transport provider returns S_OK from SubmitMessage, the MAPI spooler calls IXPLogon::EndMessage for the message as it does with regular message sending.

If the transport provider returns a value other than S_OK from SubmitMessage, the MAPI spooler handles the value appropriately before calling EndMessage, or before calling SubmitMessage again.

6.

Transport provider

Returns from EndMessage with its message processing status in the lpulFlags parameter.

7.

MAPI spooler and transport provider

The SubmitMessage-EndMessage loop continues until all messages in the queue have been downloaded.

8.

MAPI spooler

Notifies the transport provider that it has finished downloading messages by calling the transport provider's IXPLogon::TransportNotify method with the NOTIFY_END_OUTBOUND_FLUSH flag set.

9.

Transport provider

Frees any external resources used in sending outbound messages so they can be used by other transport providers to flush their queues.

The STATUS_INBOUND_FLUSH bit in the PR_STATUS_CODE property of the transport provider's status row must be set using ModifyStatusRow.

10.

MAPI spooler

Checks the transport provider's status row for the STATUS_INBOUND_FLUSH bit and calls IXPLogon::StartMessage if it is set.

11.

Transport provider

Processes the message and returns from StartMessage. If the transport provider has other messages to upload, it should call SpoolerNotify with the NOTIFY_NEWMAIL flag set.

If the transport provider has no messages to upload, it should call IMAPIProp::SaveChanges on the message the MAPI spooler passed in StartMessage and return.

12.

MAPI spooler

Continues calling StartMessage until SaveChanges is called on a message. After the transport provider has finished uploading, the MAPI spooler calls TransportNotify with the NOTIFY_END_INBOUND_FLUSH flag set.

13.

Transport provider

Clears the STATUS_INBOUND_FLUSH bit in the PR_STATUS_CODE property of its status row using ModifyStatusRow and releases all external resources so they are available for use by other transport providers.

14.

MAPI spooler

Calls FlushQueues for the next transport provider listed in the transport order of the user's profile.

If a client application calls IMAPIStatus::FlushQueues on a transport provider's status object, the transport provider should set the appropriate bit in its status row with ModifyStatusRow. The MAPI spooler then calls the transport provider's IXPLogon::FlushQueues method at the MAPI spooler's convenience. When the transport provider's IXPLogon::FlushQueues method is called as a result of a client application's IMAPIStatus::FlushQueues call, the operation occurs asynchronously to the client application. Otherwise IXPLogon::FlushQueues works synchronously with the MAPI spooler.

For performance reasons, the MAPI spooler will only call a transport provider's FlushQueues method if the STATUS_INBOUND_FLUSH and STATUS_OUTBOUND_FLUSH flags are set in the transport provider's status row. Consequently, a transport provider can stop the FlushQueues operation at any time by clearing the STATUS_OUTBOUND_FLUSH and STATUS_INBOUND_FLUSH flags in its status row. If the MAPI spooler is shutting down and needs to end the FlushQueues operation, it calls TransportNotify with both the NOTIFY_END_INBOUND_FLUSH and NOTIFY_END_OUTBOUND_FLUSH flags set. The transport provider should release all external resources and return.


Setting Properties on Incoming Messages

 Copy code hover
[image]

Setting Properties on Incoming Messages
Send feedback

Published: July 16, 2012

The client applications within the MAPI subsystem expect a number of properties in any received message. When the transport provider brings a message into MAPI, it should set these properties, since it is either the only process with the necessary information to do so, or is at least the best source of the information.

Providers are encouraged to set the values for all of these properties in incoming messages.

Property name | Description
PR_SUBJECT (PidTagSubject) | The subject of the message.
PR_BODY (PidTagBody) | Plain text message text.
PR_RTF_COMPRESSED (PidTagRtfCompressed) | Compressed RTF message text.
PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) | The date and time the message was delivered.
PR_SENDER_NAME (PidTagSenderName) | The display name of the message originator.
PR_SENDER_ENTRYID (PidTagSenderEntryId) | The address book entry of the message originator.
PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) | The address book search key of the message originator.
PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) | The time that the message was submitted to its messaging system by the sender's messaging client.
PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) | The name of the representative delegate for sending.
PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId) | The address book entry of the sending delegate.
PR_SENT_REPRESENTING_SEARCH_KEY (PidTagSentRepresentingSearchKey) | The address book search key of the sending delegate.
PR_RCVD_REPRESENTING_NAME (PidTagReceivedRepresentingName) | The name of the representative delegate for receiving.
PR_RCVD_REPRESENTING_ENTRYID (PidTagReceivedRepresentingEntryId) | The address book entry of the receiving delegate.
PR_RCVD_REPRESENTING_SEARCH_KEY (PidTagReceivedRepresentingSearchKey) | The address book search key of the receiving delegate.
PR_REPLY_RECIPIENT_NAMES (PidTagReplyRecipientNames) | The list of delegated recipient display names, separated by a semicolon and space ("; ").
PR_REPLY_RECIPIENT_ENTRIES (PidTagReplyRecipientEntries) | The list of delegated recipients for a reply.
PR_MESSAGE_TO_ME (PidTagMessageToMe) | Indicates that the recipient was specifically named as a "to" recipient (not in a group).
PR_MESSAGE_CC_ME (PidTagMessageCcMe) | Indicates that the recipient was specifically named as a "cc" recipient (not in a group).
PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe) | Indicates that the recipient was specifically named as a "to", "cc" or "bcc" recipient (not in a group).

Providers that have no apparent mappings can set the PR_SENT_REPRESENTING group of properties to the same values as the PR_SENDER group, the PR_RCVD_REPRESENTING group of properties to the same values as the PR_RECEIVED_BY group, and can build the PR_REPLY_RECIPIENT group of properties based on the values of the PR_SENDER group. For example, PR_SENT_REPRESENTING_NAME can be set to the same value as PR_SENDER_NAME.

The PR_ENTRYID or PR_ENTRYLIST property can be generated, if necessary, by calling the IMAPISupport::CreateOneOff method. The PR_SEARCH_KEY group of properties can be generated by concatenating the PR_ADDRTYPE property associated with a user, a colon (:), and the PR_EMAIL_ADDRESS property associated with the user, then changing the result to uppercase. The Windows API function CharUpperBuff is a convenient function to use for this purpose. What is required of this process is to make a canonical form of the address that can be compared as a binary quantity. Note that this is not necessary if the transport provider is case-sensitive with respect to e-mail addresses.


Optional Transport Provider Features

 Copy code hover
[image]

Optional Transport Provider Features
Send feedback

Published: July 16, 2012

Optional features transport providers can implement include:

  • Registering message and recipient options specific to the transport provider.

  • Maintaining a profile, if necessary, to store configuration information and credentials to the messaging system.

  • Performing any verification of credentials required by the messaging system.

  • Supporting event notification for interested client applications with the IMAPISupport::Notify method.

  • Displaying configuration property sheets and wizard dialog boxes to enable users to configure the transport provider's settings.

  • Providing message delivery reports to client applications.


Implementing Security

 Copy code hover
[image]

Implementing Security
Send feedback

Published: July 16, 2012

If the messaging system requires it, the transport provider is responsible for implementing an appropriate level of security for access to the messaging system. Each incoming or outgoing message sent through a transport provider by the MAPI spooler is handled in the context of a provider logon session. The transport provider can display a logon dialog box to the user that prompts for a user's credentials before establishing such a connection. Alternatively, the transport provider can store the user's previously entered credentials in the secure property range within a profile section and use them for access without prompting.

When implementing your transport provider's security, consider the following:

  • With multiple installed service providers, there can be a multitude of names and passwords associated with a user.

  • MAPI allows multiple sessions with multiple identities. Providers are encouraged to support multiple sessions but are not required to do so.

  • Each session with a transport provider is associated by MAPI with a discrete section in the user's profile. The transport provider can use the IMAPISupport::OpenProfileSection method to gain access to this section, which can be used to store any information associated with this session, including credentials.

  • With multiple installed transport providers, it is not necessarily true that the user only has a single e-mail address. A user can have a separate e-mail address for each installed transport provider or can have a different address for each session on a single provider.

For more information about storing credentials in profile sections, see Message Services and Profiles and IProfSect : IMAPIProp.


Displaying Configuration Property Sheets

 Copy code hover
[image]

Displaying Configuration Property Sheets
Send feedback

Published: July 16, 2012

Transport providers use the IMAPISupport::DoConfigPropsheet method to implement configuration property sheets. When calling DoConfigPropSheet, the transport provider passes in a pointer to an array of properties along with information about how to display them. MAPI then presents the properties to the user by means of a standard dialog box. You are strongly encouraged to use this property sheet mechanism when implementing your transport provider due to the benefit to the user of a consistent interface.

Transport Providers

Transport providers can use the BuildDisplayTable function to simplify construction of a display table for use with DoConfigPropSheet. Transport providers can also use the property sheet API directly. To buffer changes to the properties, transport providers can use the CreateIProp function. This simplifies the handling of cancellations by the user while the user modifies the values stored in the properties. If necessary, a transport provider can also provide a wizard dialog box to simplify configuration tasks for the user.


Sending Message Delivery Reports

 Copy code hover
[image]

Sending Message Delivery Reports
Send feedback

Published: July 16, 2012

Some underlying messaging systems support delivery reports and some do not. How the transport provider determines whether message delivery or nondelivery reports can be sent to client applications is an implementation detail specific to individual transport providers. If delivery reports can be sent to client applications, transport providers use the IMAPISupport::StatusRecips method to notify MAPI of successful or unsuccessful delivery for one or more recipients. MAPI then generates delivery or nondelivery reports corresponding to those recipients. Transport providers can also translate incoming delivery and nondelivery reports that are native to the messaging system into MAPI delivery and nondelivery reports by means of StatusRecips.


Developing a TNEF-Enabled Transport Provider

 Copy code hover
[image]

Developing a TNEF-Enabled Transport Provider
Send feedback

Published: July 16, 2012

To promote interoperability between messaging systems that support different sets of MAPI features, MAPI provides the Transport Neutral Encapsulation Format (TNEF) as a standard way to transfer data. This format encapsulates MAPI properties not supported by an underlying messaging system into a binary stream that can be transferred along with the message when a transport provider sends it. The transport provider that receives the message can then decode the binary stream to retrieve all the properties of the original message and make them available to client applications. The operational model for TNEF is:

  • Messaging clients submit and receive messages to a TNEF transport as normal.

  • The transport separates the properties on outgoing messages into two categories: those that the underlying message system supports and those that it does not. The values of the properties that are supported by the underlying messaging system are translated into the required format.

  • The transport uses the MAPI TNEF methods to encode any unsupported properties into a single data stream. The transport then turns that data stream into a special attachment on the outgoing message, using the underlying messaging system's attachment model, before sending the message.

  • A TNEF enabled transport that receives such a message does two things. First, it translates the incoming message's properties — the ones supported by the underlying message system — into MAPI properties. Second, if the special attachment is present, it uses the MAPI TNEF methods to retrieve additional MAPI properties from the attachment before delivering the message to a client application.

MAPI supplies an implementation of the ITnef interface for use by MAPI transport providers when working with TNEF objects. The OpenTnefStreamEx function is used to create TNEF objects and associate them with a message. TNEF streams are built on top of the OLE IStream interface

Note Note

You use OpenTnefStreamEx to create TNEF objects. The old OpenTnefStream function still exists for compatibility with old source code and should not be used in anything new.

The ITnef interface provides the following methods:

  • AddProps

  • EncodeRecips

  • ExtractProps

  • Finish

  • FinishComponent

  • OpenTaggedBody

  • SetProps

The MAPI TNEF implementation model supports:

  • All MAPI properties without affecting other message properties. In order for MAPI messages to survive transport through a messaging system, all properties that cannot be encoded as properties of the messaging system must be encapsulated. Because it is almost never known at the time a message is sent whether or not a MAPI-compliant client will receive the message, the encapsulation scheme allows a transport provider to encode only those MAPI message properties that the messaging system does not natively support. This means that messages which use TNEF are not "opaque" to messaging systems that are not based on MAPI such as SMTP-based UNIX messaging systems. These systems receive the properties they support in whatever manner is typical for them, and other properties are received as an encoded TNEF data stream. The TNEF transport provider is responsible for differentiating between these two sets of properties and sending the supported set in the proper manner for the messaging system. TNEF makes no assumptions as to the level of support provided by a messaging system. However, in the examples of TNEF usage included in this section, the assumption is made that the messaging system supports at least one single attachment aside from the message. In some cases, the attachment can only be supported through a uuencoded stream and transmitted as part of the message text. Only in very rare circumstances will the messaging system have so little support for message properties that full TNEF encoding of all properties is necessary.

  • A mechanism for determining whether a TNEF stream on an incoming message belongs to the message, based on the MAPI property PR_TNEF_CORRELATION_KEY (PidTagTnefCorrelationKey). This property should be found both in the TNEF stream and in an appropriate message header. If the property has the same value in both places, or is missing in either place, the TNEF stream is assumed to belong to the message. Otherwise, the TNEF stream is ignored. TNEF enabled transports are responsible for choosing a value for this property on outbound messages and encoding it in an appropriate message header (for example, the Message-ID: header for SMTP messages) and in the TNEF stream.


TNEF Processing

 Copy code hover
[image]

TNEF Processing
Send feedback

Published: July 16, 2012

The following series of actions describe how transports use TNEF methods to process outgoing and incoming messages.

To send a message that includes a TNEF stream

  1. Process the message properties that are supported by the messaging system.

  2. Mark the message in an implementation specific way so that the receiving transport provider can determine that the message requires TNEF processing. For example, a TNEF transport provider sending to an SMTP messaging system might add a custom header field like "X-CONTAINS-TNEF" to indicate that the message contains TNEF data.

  3. Obtain a TNEF object and use it to encapsulate the message properties not supported by the messaging system into a TNEF stream.

  4. Encode the TNEF stream using the messaging system's attachment model. For example, if the underlying attachment model is to uuencode attachments and append them to the message text, then the transport provider must uuencode the TNEF stream into another attachment. The transport provider must also implement a method for recognizing which attachment contains the encoded TNEF stream when it receives a message. The standard way to mark this attachment is to give it an attachment filename of "WINMAIL.DAT". If your transport provider does this, any other TNEF-enabled transport providers that follow this convention will be able to interoperate with it.

  5. Use ITnef : IUnknown interface methods to insert tags describing the positions of message attachments in the message text.

  6. Access the tagged message text through IStream methods, and send it to the messaging system.

To retrieve encapsulated properties

  1. Write the properties supported by the messaging system into a new message, including the tagged message text that contains the encapsulated properties.

  2. Decode the TNEF stream from the proper attachment.

  3. Decode any other attachments and write them to new MAPI attachments on a message.

  4. Open the TNEF stream for decoding using the OpenTnefStreamEx function.

  5. Use the ITnef::ExtractProps method to decode the TNEF stream and write the encapsulated properties into the new message. Any encoded properties that are duplicates of nonencoded properties will overwrite the nonencoded properties when the encoded properties are decoded.

  6. Use the ITnef::OpenTaggedBody method to parse the message text to recover attachment positions from the tags in the message text.


Encoding a Message with TNEF

 Copy code hover
[image]

Encoding a Message with TNEF
Send feedback

Published: July 16, 2012

When a message is submitted, the transport provider can create a file that is used to contain the message during transmission. Next, an IStream interface is wrapped around the file. The transport provider then uses ITnef methods to write the message properties to the stream in a tagged format that enables the properties to be easily decoded by the receiving transport providers.

To represent an entire message in a single file

  1. Obtain a TNEF object by passing an IStream object and a message into the OpenTnefStreamEx function.

  2. Get a list of all defined properties for the message by calling the IMAPIProp::GetPropList method.

  3. Use IMAPIProp methods to exclude all properties supported by the messaging system. At an appropriate time, write those properties to the messaging system in the format required by the messaging system.

  4. Call ITnef::AddProps to encode the remaining properties, including all attachments.

  5. Call the ITnef::Finish method to encode the message into the TNEF stream after all the requested properties are added.

  6. Call the ITnef::OpenTaggedBody method to obtain the tagged message text. This tagged text is written out to the messaging system using methods from the OLE IStream interface.

  7. Call the IUnknown::Release method to release the ITnef object.

To process an inbound TNEF message

  1. Get a MAPI message object from the MAPI spooler and write message header properties into the new MAPI message.

  2. Create and initialize an IStream object to contain the TNEF data from the inbound message.

  3. Pass the MAPI message and the IStream object to the OpenTnefStreamEx function.

  4. Decode the information in the TNEF data by calling the ITnef::ExtractProps method.

    Note Note

    Anything decoded by ExtractProps will overwrite properties decoded from the incoming message's envelope. That is, extracted TNEF properties will overwrite the existing properties in a message.

  5. Process the tagged message text by calling ITnef::OpenTaggedBody and parse the text to recover attachment positions.

  6. Save the message by calling IMAPIProp::SaveChanges.

  7. Release the TNEF object by calling the IUnknown::Release method.


Custom Processing with TNEF

 Copy code hover
[image]

Custom Processing with TNEF
Send feedback

Published: July 16, 2012

Transport providers can use custom processing to process the properties on an attachment itself, transmit attachments separately, or transmit them through the messaging system's attachment model. TNEF uses a mechanism that enables the transport provider to send the attachments apart from the message and reconnect them on the receiving side.


Sending Messages by Using TNEF Custom Attachment Processing

 Copy code hover
[image]

Sending Messages by Using TNEF Custom Attachment Processing
Send feedback

Published: July 16, 2012

To customize attachment processing when sending a message:

  1. Obtain a TNEF object by passing an IStream interface and a message into the OpenTnefStreamEx function.

  2. Get a list of all defined properties for the message by calling the IMAPIProp::GetPropList method.

  3. Use IMAPIProp methods to exclude all properties supported by the messaging system. At an appropriate time write those properties to the messaging system in the format required by the messaging system.

  4. Call the ITnef::AddProps method to add only the properties on the message — that is, none of the properties on the attachments — by setting the TNEF_PROP_MESSAGE_ONLY flag.

  5. Call ITnef::AddProps with these items: the TNEF_PROP_EXCLUDE flag, a property tag array that contains the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) or PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property, and an attachment identifier that specifies the attachment to be processed.

  6. Use the ITnef::SetProps method to add the PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName) property tag with a unique string that identifies the attachment to the messaging system if the attachment has a filename that the messaging system cannot support. For example, multiple attachments with the same original filename, or a filename that is not a valid filename for the messaging system. This string will be used with a key number when writing the attachment tags in the tagged message text to associate an attachment with its data. For more information, see, TNEF-Tagged Message Text.

  7. Repeat the AddProps and SetProps calls for each attachment.

  8. Call the ITnef::Finish method to encode the message into the TNEF stream after all the requested properties are added.

  9. Obtain the tagged message text by calling the ITnef::OpenTaggedBody method. This tagged text is read using methods from the IStream interface, encoded using the messaging system's attachment model, and written out to the messaging system.

  10. Call the IUnknown::Release method to release the ITnef object.

  11. Write the remaining attachments to the messaging system through the messaging system's attachment model.

Your transport provider should use the previously described procedure to process attachments. If that is not possible, the transport provider should use the following steps for customized attachment processing:

  1. The transport provider ensures that the PR_ATTACH_TRANSPORT_NAME properties of all the attachments contain unique values that are valid attachment identifiers for the messaging system.

  2. The transport provider then uses a single call to ITnef::AddProps for each attachment, passing in the TNEF_PROP_CONTAINED flag.


Receiving Messages by Using TNEF Custom Attachment Processing

 Copy code hover
[image]

Receiving Messages by Using TNEF Custom Attachment Processing
Send feedback

Published: July 16, 2012

To receive a TNEF message with customized attachment processing:

  1. Import all the transmittable properties — those that the messaging system supports — from the incoming message into a new MAPI message. This includes the message text, which contains the TNEF data stream.

  2. Identify and decode the special attachment that contains the TNEF stream.

  3. Extract all the attachments from the incoming message into MAPI attachments on the new MAPI message. The recovered filenames, or other identifying markers on the attachments, should be placed into the PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName) property of the new attachments so that the ITnef::ExtractProps method can later associate the correct attachment with the attachment tags encoded in the message text.

  4. Create an OLE IStream interface to wrap around the decoded TNEF stream and use that object along with the new MAPI message in a call to the OpenTnefStreamEx function.

  5. Call the ITnef::ExtractProps method to recover the nontransmittable properties on the message from the TNEF data stream.

  6. Call the ITnef::OpenTaggedBody method with the MAPI_CREATE and MAPI_MODIFY flags set. This call removes the attachment tags from the message text and converts them into attachment position information in the MAPI message.

  7. Deliver the message through the MAPI spooler.


TNEF-Tagged Message Text

 Copy code hover
[image]

TNEF-Tagged Message Text
Send feedback

Published: July 16, 2012

Tagged message text is used by TNEF to resolve attachment positions in the parent message. This is done by adding a place holder in the message text at the position of the attachment. This place holder, or attachment tag, describes the attachment in such a way that TNEF knows how to resolve the attachment and its position. The tags are formatted as follows:

[[ <Object Title> : <KeyNum> in <Stream Name> ]] [[ <File Name> : <KeyNum> in <Transport Name> ]]

<Object Title> and <File Name> are variables containing values that are taken from the attachment itself. In cases where these values are not available, the title is defaulted by TNEF based on the attachment type.

The <KeyNum> variable contains the textual representation of the attachment key assigned to the attachment by TNEF. The base value of the key is passed into the OpenTnefStreamEx call. The base value must not be zero and should not be the same for every call to OpenTnefStreamEx. It should suffice to use pseudo random numbers based on the system time from whatever random number generator your run-time library provides, as long as you guarantee that they are never zero.

The <Transport Name> variable contains either the stream name passed into the OpenTnefStreamEx call or the value of the PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName) property.

Note Note

The PR_ATTACH_TRANSPORT_NAME property and the <Transport Name> variable in a message text tag have nothing to do with the name of the transport provider you are implementing. These items represent the name of an attachment for the transport provider and messaging system.

The message text is tagged when a transport provider asks for a tagged message text by calling the ITnef::OpenTaggedBody method. When reading from the tagged text stream, TNEF replaces the single character that was in the message text at the index provided in the PR_RENDERING_POSITION (PidTagRenderingPosition) property with the appropriate tag. When writing to the tagged text stream, TNEF checks the incoming data for tags, finds the associated attachment, and replaces the tag with a single space character.

Note that by using tagged message text, a transport provider can preserve the positioning of attachments regardless of most changes made to the message text by messaging systems.


Encoding Recipient Tables by Using TNEF

 Copy code hover
[image]

Encoding Recipient Tables by Using TNEF
Send feedback

Published: July 16, 2012

The encoding of a recipient table into the TNEF stream is rarely necessary since most messaging systems support recipient lists directly. In general, the recipient properties are transmitted in the message header. When inclusion of the recipient table is necessary, TNEF can encode the recipient table as a part of its usual processing. This is done during the initial phase of TNEF processing. The transport provider can include the message's recipient table by calling the ITnef::AddProps method with the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property specified in the inclusion list. TNEF gets the recipient table from the message, queries the column set, and processes every row of the table into the TNEF stream.

An alternate method is available if the transport provider needs to modify the recipient table before it is encoded. The transport provider can construct the necessary table and then call the ITnef::EncodeRecips method. If NULL is passed in the lpRecipTable parameter, then the recipient table is taken directly from the message as described for ITnef::AddProps.


Developing a MAPI Message Store Provider

 Copy code hover
[image]

Developing a MAPI Message Store Provider
See also Send feedback

Published: July 16, 2012

Like other MAPI service providers, message stores are dynamic-link libraries (DLLs) that present the services of an underlying storage mechanism to MAPI client applications and the MAPI spooler. The message store provider presents the underlying storage mechanism as a hierarchical set of folders and messages that MAPI clients and the MAPI spooler can use.

The following illustration shows the basic MAPI message store architecture.

Message store architecture

Message store architecture

You can implement a message store provider by using any sort of underlying storage mechanism you like. However, you need to be aware of performance concerns. In addition, the underlying storage mechanism must be presented as a hierarchical collection of MAPI objects. These requirements mean that message stores are typically implemented by using an existing database product that supports hierarchical storage of objects in the database and that has a programming interface or well-defined file structure. For example, Microsoft Office Access, SQL, and Oracle databases can be used as the underlying storage mechanism. Some database products have feature sets that make it easier to implement MAPI features, so your choice of database product may be affected by the features that your message store provider needs to support.

Using an existing database as the underlying storage mechanism saves you work because it is usually easier to present database objects to MAPI clients as MAPI objects than to implement your own hierarchical storage mechanism. Doing this enables you to treat MAPI operations at a higher level than if you implement your own hierarchical storage mechanism. For example, searching for a message with a particular subject line becomes a fairly simple matter of constructing and submitting an appropriate database query, rather than implementing complex routines to search your hierarchical storage mechanism.

Message store providers communicate with MAPI clients and the MAPI spooler to perform operations on folders and objects. The message store provider translates those operations into lower level operations on the underlying storage mechanism. The MAPI spooler typically communicates with the message store provider while sending and receiving messages. MAPI clients typically communicate with message store providers to manipulate the folder hierarchy and to read, edit, delete, and send messages.

Both the MAPI spooler and MAPI clients communicate with the message store provider to create new messages. Client applications do this when users compose a message. The MAPI spooler does this when it receives an incoming message. In either case, the new message is usually created in the Inbox folder of the message store, if there is one.

Message store providers make heavy use of MAPI tables, folders, messages, and properties. The implementation details for those objects are documented in MAPI Tables, MAPI Folders, MAPI Messages, and MAPI Property Overview. You should familiarize yourself with that material before attempting to implement a message store provider.

There are two important types of message store providers: those that can act as a user's default message store and those that cannot. A default message store is one in which client applications and the MAPI spooler can perform any messaging task, such as receiving messages or creating folders. A default message store provider must support several more features than the minimum number required for all message store providers.

See also

Other resources

MAPI Concepts


Structure of Message Store Providers

 Copy code hover
[image]

Structure of Message Store Providers
See also Send feedback

Published: July 16, 2012

A message store provider, when it is running in memory, is an IMSProvider : IUnknown interface. The IMSProvider interface allows client applications and the MAPI spooler to log on to and off of the message store. The interfaces that client applications and the MAPI spooler use to access folders and messages in the message store are IMSLogon and IMsgStore interfaces. These interfaces are typically created when the message store is first logged on to, although the MSProviderInit entry point of the message store DLL could also create them.

Because the IMSLogon and IMsgStore interfaces share some methods, it may be easier to create one class object that inherits from both of these interfaces. You can also implement these interfaces in separate objects, and write helper functions internal to your DLL that implement the shared methods that can then be called from the methods in the IMSLogon and IMsgStore interfaces.

The following illustration shows a high-level outline of the object hierarchy within a running message store.

Message store object hierarchy

Message store object hierarchy

See also

Concepts

Developing a MAPI Message Store Provider


Required and Optional Interfaces for Message Store Providers

 Copy code hover
[image]

Required and Optional Interfaces for Message Store Providers
See also Send feedback

Published: July 16, 2012

MAPI defines a set of interfaces that relate to message store providers. Because of the wide range of features that a message store can choose to implement, some of these interfaces are required and some are not. The following table lists the MAPI interfaces that are related to message store providers, specifies whether the interfaces are required or optional, and describes their purpose.

Interface | Status | Description
IMSProvider | Required | Logs on to and off of a message store.
IMSLogon | Required | Opens folders or messages, verifies the message store's identity, and handles notifications.
IMsgStore | Required | Opens folders or messages, finds special folders, and handles message submissions.
IMAPIFolder | Required | Finds and manipulates messages and subfolders.
IMessage | Required | Manipulates attachments and sets some of a message's properties.
IMAPITable | Required | Enables other objects to present collections of data to various MAPI components.
IMAPIStatus | Required | Enables clients to validate the state of a message store and to perform some configuration tasks.
IAttach | Optional | Accesses message attachment properties if the store provider supports file attachments.
IStorage | Optional | Manages structured storage objects if the store provider supports OLE object attachments.
IStream | Optional | Enables message and attachment objects to read and write data to stream objects.
IStreamDocfile | Optional | Enables some service providers to open a storage object, such as a compound file in the OLE 2.0 file format.

The basic information you need to implement IMAPIFolder, IMessage, IMAPIStatus, and IMAPITable is documented in the reference topics for these interfaces. This section contains supplementary information that is more directly related to message store providers. The rest of the MAPI interfaces should be implemented according to the information in this section and in the appropriate reference topics. See the COM and ActiveX Object Services section in the Windows SDK for more information about implementing IStorage, IStream, and IStreamDocFile.

See also

Concepts

Developing a MAPI Message Store Provider


Message Store Features

 Copy code hover
[image]

Message Store Features
See also Send feedback

Published: July 16, 2012

Message store providers are more complex than other MAPI service providers in that message store providers have a wider range of optional features they can implement. The list of required features for a message store provider is fairly short. However, a typical message store provider will support a number of optional features, because many of the optional features are very useful or required by most MAPI clients. The following table lists the major features that message store providers can implement and whether each feature is required or optional for all message store providers and for default message store providers.

Feature | All | Default
Providing status with the MAPI status table. | Required | Required
Implementing folder objects. | Required | Required
Implementing message objects. | Required | Required
Providing read and nonread reports. | Required | Required
Providing a progress interface. | Required | Required
Providing a configuration interface. | Required | Required
Supporting associated contents tables for form and view support. | Optional | Optional
Sending messages with the message store provider. | Optional | Required
Receiving messages with the message store provider. | Optional | Required
Supporting message attachments. | Optional | Optional
Supporting Rich Text Format for messages. | Optional | Optional
Providing notifications. | Optional | Optional
Supporting searches. | Optional | Optional
Supporting tightly coupled message store/transport providers. | Optional | Optional
Supporting non-reuse of entry identifiers. | Optional | Optional

Many of the optional features can be advertised to MAPI and client applications by setting various flags in the message store object's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property. The required features do not have flags associated with them. PR_STORE_SUPPORT_MASK is required on message store, folder, and message objects.

See also

Concepts

Developing a MAPI Message Store Provider


Implementing Folders in Message Stores

 Copy code hover
[image]

Implementing Folders in Message Stores
See also Send feedback

Published: July 16, 2012

A great deal of the information that relates to message store provider support for folders is covered in MAPI Folders. You should be familiar with that information before attempting to implement a message store provider. The MAPI Folders section is heavily oriented to the MAPI client's perspective; this topic covers additional information that is important from the message store provider's point of view.

See also

Concepts

Message Store Features


Exposing Folders in Message Stores

 Copy code hover
[image]

Exposing Folders in Message Stores
See also Send feedback

Published: July 16, 2012

Every message store provider must present a top-level IMAPIFolder interface to client applications. The top-level folder corresponds to the entire message store; it provides access to the folders that users see as the contents of the message store. In addition, the top-level folder is often used as the default receive folder for IPC messages and as the folder from which read reports are sent. Message store providers must also present an IPM subtree — a set of folders used to contain IPM messages — to client applications.

Client applications can open the top-level folder by calling the IMsgStore::OpenEntry method with 0 and NULL for the cbEntryId and lpEntryId parameters, respectively. In most cases, however, client applications open the set of folders that contain IPM messages.

To get a list of folders in the message store's IPM folder tree, use the following procedure:

  1. Use your MAPI session to call the IMAPISession::OpenMsgStore method.

  2. Use the resulting message database pointer to call the IMAPIProp::GetProps method for the PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId) property.

  3. Call the IMsgStore::OpenEntry method with the entry identifier to get an IMAPIFolder pointer.

  4. Call the IMAPIContainer::GetHierarchyTable method to get a table of the contents of the folder.

  5. Call the IMAPITable::QueryRows method to list the folders in the top-level folder.

MAPI clients use these folders to access other folder objects and message objects in the message store. IMAPIFolder, and its parent interface IMAPIContainer, contain the methods your message store provider must implement to populate folders with message objects and respond to client requests to operate on messages.

See also

Concepts

Implementing Folders in Message Stores


Inbox and Outbox Folders in Message Stores

 Copy code hover
[image]

Inbox and Outbox Folders in Message Stores
See also Send feedback

Published: July 16, 2012

To be the default message store, a message store provider must implement Inbox and Outbox folders. They are typically stored in the IPM subtree of a message store. These folders are special in that they are designated as the folders that messages are delivered to and sent from, but no special functionality is required of them. Sending and receiving messages happens by way of defined call sequences between client applications, the MAPI spooler, and the message store provider. The Inbox and Outbox folders are simply folders that are used to hold messages during those call sequences. The important point is not that the folders are special, or even that they are named Inbox and Outbox; the important point is that the message store provider uses them as part of its support for sending and receiving messages.

To support receiving messages, the message store provider must implement the IMsgStore::GetReceiveFolderTable and IMsgStore::GetReceiveFolder methods. For more information, see Receiving Messages by Using Message Store Providers.

To support sending messages, the message store provider must support the IMsgStore::GetOutgoingQueue method, in addition to the other methods used by the MAPI spooler during the message sending process. A message store's outgoing queue does not have to correspond to an actual folder anywhere in the message store's folder tree. However, it is customary for a message store provider to show the contents of the outgoing message queue in the Outbox folder, if there is one. Doing so gives client applications a convenient way to indicate the status of messages that the user has sent, because an Outbox folder can be displayed along with all the other folders in a message store. For more information, see Sending Messages by Using Message Store Providers.

See also

Concepts

Implementing Folders in Message Stores


Special Folders in Message Stores

 Copy code hover
[image]

Special Folders in Message Stores
See also Send feedback

Published: July 16, 2012

Special folders such as the Inbox, Outbox, and search-results folder may be created in advance and protected by the message store provider. If the folders do not exist, MAPI will attempt to create them in the message store by calling the HrValidateIPMSubtree function. For more information, see MAPI Special Folders.

See also

Concepts

Implementing Folders in Message Stores


Implementing Messages in Message Stores

 Copy code hover
[image]

Implementing Messages in Message Stores
See also Send feedback

Published: July 16, 2012

The IMessage : IMAPIProp interface is similar to the IMAPIFolder : IMAPIContainer interface in that both interfaces derive from the IMAPIProp : IUnknown interface. Clients use the IMAPIProp methods to access the contents of a message. The IMessage interface supplies additional methods for manipulating messages (for example, adding attachments or modifying the recipients of a message). The methods in the IMessage interface modify attributes of messages that are not stored directly in the message's properties.

See also

Concepts

Message Store Features


Creating and Storing Messages in Message Stores

 Copy code hover
[image]

Creating and Storing Messages in Message Stores
See also Send feedback

Published: July 16, 2012

How your message store provider creates and stores messages in the underlying storage mechanism depends heavily on the underlying storage mechanism itself. In general, you need only to write code to preserve the properties of a message and their values.

When the message store provider creates a new message, the provider needs to create the message with the required properties for messages. A list of these properties can be found in the documentation for the IMAPIFolder : IMAPIContainer interface. After that, client applications add any additional properties with IMAPIProp methods.

When the message store provider saves a message to the underlying storage mechanism, the provider needs to iterate over the message's properties, and save them to the underlying storage mechanism such that they can be fully recovered if the message is later opened.

MAPI requires that the properties on IMessage interfaces are transacted, meaning that changes made to them do not become permanent until the IMAPIProp::SaveChanges method is called on the message object. The message store provider is responsible for implementing this behavior. Usually this is not difficult; it simply means holding properties in memory while they are being modified and committing them to the underlying storage mechanism when SaveChanges is called.

Some properties on message objects have special semantics for client applications with respect to the SaveChanges method, as follows:

  • Some properties should be read/write before SaveChanges is called, but read-only afterward. For example, PR_MESSAGE_FLAGS (PidTagMessageFlags) is set initially by the client application that creates the message (and thus is read/write) but cannot be changed after the first call to SaveChanges.

  • Some properties have special relations to properties on the folder they are in or to IMAPIFolder methods. For example, the PR_MESSAGE_FLAGS property is related to the flags used on the IMAPIFolder::CreateMessage call.

  • Some properties may not be available until SaveChanges is called for the first time. For example, the PR_ENTRYID (PidTagEntryId) property may not be available until SaveChanges is called.

  • Some properties can have special relationships to other properties on the message object. For example, the PR_BODY (PidTagBody) property is usually derived from the PR_RTF_COMPRESSED (PidTagRtfCompressed) property in message store providers that support Rich Text Format messages.

  • Some properties are used by more than one object type related to message stores. For example, the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property is required on folder and message objects as well as message store objects.

It is the responsibility of the message store provider to implement the correct semantics for such properties.

See also

Concepts

Implementing Messages in Message Stores


Supporting Named Properties in Message Stores

 Copy code hover
[image]

Supporting Named Properties in Message Stores
See also Send feedback

Published: July 16, 2012

Message objects can have properties in them that are not in the set of properties defined by MAPI. Such properties can be unnamed or named. Unnamed properties must reside in a range of property identifiers defined by MAPI. Named custom properties reside in a different range of property identifiers defined by MAPI. They are typically used by custom message types. Your message store provider must support named properties if it is to be used as the default message store. Supporting named properties means implementing the IMAPIProp::GetNamesFromIDs and IMAPIProp::GetIDsFromNames methods, and implementing one or more mapping signatures that identify what names go with what property identifiers. For more information, see Defining New MAPI Properties and Supporting Named Properties.

Most message store providers that support named properties use a single mapping signature for all objects in the message store. This has two benefits. First, it is simpler to implement mapping signatures if there is only one to keep track of. Second, if all objects in the message store use the same mapping signature, client applications are assured that all property identifiers on messages in the message store actually refer to the same named property. This enables client applications to display columns for named properties in their folder view interface.

See also

Concepts

Implementing Messages in Message Stores


Supporting Multivalued Properties in Message Stores

 Copy code hover
[image]

Supporting Multivalued Properties in Message Stores
See also Send feedback

Published: July 16, 2012

The requirements for supporting properties that have multiple values are documented in MAPI Property Overview. Multiple-value property support is not required for message store providers, but it is recommended, particularly for default message store providers. Some other features, such as folder form libraries, do require multiple-value property support.

See also

Concepts

Implementing Messages in Message Stores


Supporting Multiple Client Access to Messages in Message Stores

 Copy code hover
[image]

Supporting Multiple Client Access to Messages in Message Stores
See also Send feedback

Published: July 16, 2012

It is possible for multiple client applications to open a given message simultaneously. Message store providers do not have to follow any particular rules for governing such access. However, if the client applications modify the message and save their changes, the store provider should comply with the following rules:

  • Allow the first call to the IMAPIProp::SaveChanges method to proceed as if it were the only client that has the message open.

  • On the subsequent SaveChanges calls by other clients, the message store provider should ignore the changes and return MAPI_E_OBJECT_CHANGED.

  • Allow client applications to respond to a MAPI_E_OBJECT_CHANGED return code by calling SaveChanges again with the FORCE_SAVE flag. If a client application does this, the message store provider should replace the previous changes with the new ones.

Alternatively, the message store provider can detect the conflict and present an interface that enables the user to choose whether to keep the original message, overwrite the original message with the new changes, or save the new changes to another location.

See also

Concepts

Implementing Messages in Message Stores


Providing Read and Nonread Reports for Message Store Providers

 Copy code hover
[image]

Providing Read and Nonread Reports for Message Store Providers
See also Send feedback

Published: July 16, 2012

If a message store provider can receive messages, it is required to support read reports and nonread reports of messages received by the message store provider. If a received message contains the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property and that property's value is TRUE, the message store should send a notification message to the sender when the user opens the message, indicating that the message has been read. Similarly, if the user deletes the message before opening it, the message store should issue a reply to the sender indicating that the message was not read.

Issuing these reports is a matter of creating an IMessage : IMAPIProp object, filling out the relevant properties on the message, and submitting it to the MAPI spooler as if the message had originated with the user. The IMAPISupport::ReadReceipt method can be used for this.

Note Note

Special care must be taken when a message store makes copies of an unread message with pending read or nonread reports. Such reports should not be generated when users read any copies of a message for which reports have been requested. When making a copy of such a message, the message store provider should include the CLEAR_RN_PENDING and CLEAR_NRN_PENDING flags in its calls to IMAPIFolder::SetReadFlags and IMessage::SetReadFlag.

See also

Concepts

Message Store Features


Implementing a Configuration Interface for Message Store Providers

 Copy code hover
[image]

Implementing a Configuration Interface for Message Store Providers
See also Send feedback

Published: July 16, 2012

Message store providers are required to implement an interface that allows the user to configure the message store provider to run on that user's computer. Typically, the message store provider is configured when the message store provider is added to a user's profile. The message store provider's configuration interface generally handles tasks such as setting user names and passwords for protected message stores, choosing paths to necessary files, and creating the underlying storage mechanism it will use, if necessary.

The configuration interface you implement is accessed through additional entry points in your message service provider's DLL. For more information, see Configuring a Message Service. The message store provider's configuration interface is the only user interface that a message store provider must implement.

See also

Concepts

Message Store Features


Folder-Associated Information Tables

 Copy code hover
[image]

Folder-Associated Information Tables
See also Send feedback

Published: July 16, 2012

MAPI defines the MAPI_ASSOCIATED flag for various MAPI components to use when dealing with associated information tables. Each folder in a message store should have an associated contents table along with its standard contents table. Client applications store special messages in a folder's associated contents table to hold forms and views. In fact, to support forms and views, your message store provider must implement associated contents tables.

To implement associated contents tables, your store provider must do the following:

  • Support the MAPI_ASSOCIATED flag in the IMAPIContainer::GetContentsTable method so client applications can get the folder's associated contents table instead of the standard contents table.

  • Support the MAPI_ASSOCIATED flag in the IMAPIFolder::CreateMessage method so client applications can add messages to a folder's associated contents table.

  • Set the MAPI_ACCESS_CREATE_ASSOCIATED bit in the PR_ACCESS (PidTagAccess) property on folder objects.

  • Support the DEL_ASSOCIATED flag in the IMAPIFolder::EmptyFolder method.

  • Set the MSGFLAG_ASSOCIATED bit in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property for messages in the associated contents table.

  • Expose and respond to the PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) property on folders.

  • Maintain the PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount) property on folders.

There is no bit in the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property to indicate whether your message store provider supports associated contents tables. If your message store provider does not support them, it should return MAPI_E_NO_SUPPORT when client applications call any of the above methods with the MAPI_ASSOCIATED flag.

See also

Concepts

Message Store Features


Sending Messages by Using Message Store Providers

 Copy code hover
[image]

Sending Messages by Using Message Store Providers
See also Send feedback

Published: July 16, 2012

Message store providers are not required to support outgoing message submissions (that is, the ability for client applications to use the message store provider to send messages). Client applications need to use a message store while sending messages, because the message's data must be stored somewhere between the time that the user is finished composing it and the time that the MAPI spooler gives the message to a transport provider for submission to the underlying messaging system. If your message store provider does not support outgoing message submissions, it cannot be used as the default message store.

To support sending messages, your message store provider must do the following:

  • Implement an outgoing message queue.

  • Support the IMessage::SubmitMessage method on message objects created in the message store.

  • Support the IMsgStore methods that are specific to the MAPI spooler: IMsgStore::FinishedMsg, IMsgStore::GetOutgoingQueue, IMsgStore::NotifyNewMail, and IMsgStore::SetLockState.

The SetLockState method is important for proper interoperation between the MAPI spooler and clients. When the MAPI spooler calls SetLockState on an outgoing message, the message store provider must not let clients open the message. If a client does try to open a message that is locked by the MAPI spooler, the message store provider should return MAPI_E_NO_ACCESS. The locked state of a message does not have to be persistent in case the store is shut down while the message is locked by the MAPI spooler.

Regardless of whether the MAPI spooler has locked an outgoing message, the message store provider should not allow a message in the outgoing message queue to be opened for writing. If a client calls the IMSgStore::OpenEntry method on an outgoing message with the MAPI_MODIFY flag, the call should fail and return MAPI_E_SUBMITTED. If a client application calls OpenEntry on an outgoing message with the MAPI_BEST_ACCESS flag, the message store provider should allow read-only access to the message.

When a message is to be handled by the MAPI spooler, the message store provider sets the message's PR_SUBMIT_FLAGS (PidTagSubmitFlags) property to SUBMITFLAG_LOCKED. The SUBMITFLAG_LOCKED value indicates that the MAPI spooler has locked the message for its exclusive use. The other value for PR_SUBMIT_FLAGS, SUBMITFLAG_PREPROCESS, is set when the message requires preprocessing by one or more preprocessor functions registered by a transport provider.

The following procedures describe how the message store, transport, and MAPI spooler interact to send a message from a client to one or more recipients.

The client application calls the IMessage::SubmitMessage method. In SubmitMessage, the message store provider does the following:

  1. Calls IMAPISupport::PrepareSubmit. If MAPI returns an error, the message store provider returns that error to the client.

  2. Sets the MSGFLAG_SUBMIT bit in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message.

  3. Ensures that there is a column for the PR_RESPONSIBILITY (PidTagResponsibility) property in the recipient table and sets it to FALSE to indicate that no transport has yet assumed responsibility for transmitting the message.

  4. Sets the date and time of origination in the PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) property.

  5. Calls IMAPISupport::ExpandRecips to do the following:

    1. Expand all personal distribution lists and custom recipients and replace all changed display names with their original names.

    2. Remove duplicate names.

    3. Check for any required preprocessing and, if preprocessing is required, set the NEEDS_PREPROCESSING flag and the PR_PREPROCESS (PidTagPreprocess) property, which is reserved for MAPI.

    4. Set the NEEDS_SPOOLER flag if the message store is tightly coupled with a transport and it cannot handle all of the recipients.

  6. Performs the following tasks if the NEEDS_PREPROCESSING message flag is set:

    1. Puts the message in the outgoing queue with the SUBMITFLAG_PREPROCESS bit set in the PR_SUBMIT_FLAGS property.

    2. Notifies the MAPI spooler that the queue has changed.

    3. Returns control to the client, and message flow continues in the MAPI spooler. The MAPI spooler performs the following tasks:

      1. Locks the message by calling IMsgStore::SetLockState.

      2. Performs the needed preprocessing by calling all of the preprocessing functions in the order of registration. Transport providers call IMAPISupport::RegisterPreprocessor to register preprocessing functions.

      3. Calls IMessage::SubmitMessage on the open message to indicate to the message store that preprocessing is complete.

If there was no preprocessing, or there was preprocessing and the MAPI spooler called SubmitMessage, the message store provider does the following in the client process:

  • Performs the following tasks if the message store is tightly coupled to a transport and the NEEDS_SPOOLER flag was returned from IMAPISupport::ExpandRecips:

    • Handles any recipients that it can handle.

    • Sets the PR_RESPONSIBILITY property to TRUE for any recipients that it handles.

    • Performs the following tasks if all recipients are known to this tightly coupled store and transport:

      • Calls IMAPISupport::CompleteMsg if the message was preprocessed or the message store provider wants the MAPI spooler to complete message processing. Message flow continues with the MAPI spooler.

      • Performs the following tasks if the message was not preprocessed or the message store provider does not want the MAPI spooler to complete message processing:

        1. Copies the message to the folder identified by the entry identifier in the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property, if set.

        2. Deletes the message if the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property has been set to TRUE.

        3. Unlocks the message if it is locked.

        4. Returns to the client. Message flow is complete.

    • Performs the following tasks if the message was preprocessed or the provider wants the MAPI spooler to complete message processing:

      1. Calls IMAPISupport::CompleteMsg.

      2. Continues message flow with the MAPI spooler. For more information, see Sending Messages: MAPI Spooler Tasks.

    • Performs the following tasks if the message was not preprocessed or the provider does not want the spooler to complete message processing:

      1. Copies the message to the folder identified by the entry identifier in the PR_SENTMAIL_ENTRYID property, if set.

      2. Deletes the message if the PR_DELETE_AFTER_SUBMIT property has been set to TRUE.

      3. Unlocks the message if it is locked.

      4. Returns to the caller. Message flow is complete.

  • Performs the following tasks if the message store is not tightly coupled to a transport, not all of the recipients were known to the message store, or the NEEDS_SPOOLER flag is set:

    1. Puts the message in the outgoing queue without setting the SUBMITFLAG_PREPROCESS bit in the PR_SUBMIT_FLAGS property.

    2. Notifies the MAPI spooler that the outgoing queue has changed by generating a table notification.

    3. Returns to the client, and message flow continues with a set of tasks performed by the MAPI spooler.

See also

Concepts

Message Store Features


Receiving Messages by Using Message Store Providers

 Copy code hover
[image]

Receiving Messages by Using Message Store Providers
See also Send feedback

Published: July 16, 2012

Message store providers do not have to support incoming message submissions (that is, support the ability for transport providers and the MAPI spooler to use the message store provider as a delivery point for messages). However, if your message store provider does not support incoming message submissions, it cannot be used as the default message store.

To support incoming message submissions, your message store provider must do the following:

  • Support the IMsgStore::GetReceiveFolderTable and IMsgStore::GetReceiveFolder methods so client applications can find incoming messages.

  • Support the IMsgStore::NotifyNewMail method so that the MAPI spooler can inform the message store provider that a new message has arrived.

  • Implement notifications so that clients can register for new message notification. Notifications are optional, but your provider should implement them.

The sequence of method calls that occurs when an incoming message is delivered to a message store is as follows:

  1. The MAPI spooler calls IMsgStore::OpenEntry with the Inbox EntryID to get an IMAPIFolder interface.

  2. The MAPI spooler calls IMAPIFolder::CreateMessage to get a new message object.

  3. The MAPI spooler passes the message object to the transport provider.

  4. The transport provider fills in the message's properties with data from the underlying messaging system and calls the message object's IMAPIProp::SaveChanges method.

  5. The message store provider uses its notification method to inform registered clients that a new message has arrived.

  6. The MAPI spooler calls the message store's IMsgStore::NotifyNewMail method.

See also

Concepts

Message Store Features


Supporting Message Attachments for Message Store Providers

 Copy code hover
[image]

Supporting Message Attachments for Message Store Providers
See also Send feedback

Published: July 16, 2012

Your message store provider does not need to support message attachments. However, many client applications expect to be able to add attachments to messages. If your message store will be used to create or store IPM.Note messages, then you should support message attachments. Default message store providers should also support message attachments. For more information, see MAPI Message Classes, and Default Message Stores.

There are five types of attachments that MAPI supports: file attachments, data attachments, message attachments, OLE object attachments, and links. The requirements for supporting each type are different. Clients differentiate between the two types of attachments by means of the PR_ATTACH_METHOD (PidTagAttachMethod) property on attachment objects.

Supporting attachments means implementing the IAttach : IMAPIProp interface. The IAttach interface has no methods of its own; it has only methods that are inherited from the IMAPIProp interface. Because your message store provider must already implement properties for message objects, this greatly simplifies the task of supporting attachments. Implementing IAttach basically means providing a way for clients to access a table of properties for particular attachments on messages.

Data attachments are simply attachments for which the contents of the attachment are stored directly in an attachment's PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property. Data attachments exist primarily to allow clients to attach files to a message when the sender and the recipient of the message do not have access to a common file server. For more information, see the PR_ATTACH_METHOD (PidTagAttachMethod) property.

Message attachments are attachments for which the attachment subobject is another IMessage : MAPIProp object. Because message store providers already support the IMessage interface, supporting message attachments is not difficult.

Supporting OLE object attachments means implementing the OLE IStorage, IStream, and IStreamDocfile interfaces. Your message store provider must be able to convert OLE object data stored in the message into an active OLE object when a client opens the object.

Links come in two types: links to files and links to other messages. Links to files use the ATTACH_BY_REF_ONLY value for the PR_ATTACH_METHOD property along with PR_ATTACH_PATHNAME (PidTagAttachPathname) or PR_ATTACH_LONG_PATHNAME (PidTagAttachLongPathname) to specify the location of a file.

How one implements links to messages may depend on aspects of the local messaging system and, as such, cannot be fully documented here. For example, sending a link to a message that is stored on a server-based message store is typically just a matter of sending the entry identifier of the linked message, providing that both the sender and recipient have access to that server. Other messaging system configurations present other requirements and challenges for implementing links to messages.

See also

Concepts

Message Store Features


Supporting RTF Text for Message Store Providers

 Copy code hover
[image]

Supporting RTF Text for Message Store Providers
See also Send feedback

Published: July 16, 2012

Some client applications allow users to use Rich Text Format (RTF) text in their messages. If your message store provider needs to support RTF text in messages, it needs to handle the PR_RTF_COMPRESSED (PidTagRtfCompressed) property, in addition to the PR_BODY (PidTagBody) property. Primarily, this means storing both properties, and making sure that PR_BODY contains a plain text version of the text in PR_RTF_COMPRESSED. The RTFSync function is useful for this purpose.

There are two flags that can be set in the message store object's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property that tell clients what they can expect from the message store provider with respect to the PR_BODY and PR_RTF_COMPRESSED properties on messages in the message store. The STORE_RTF_OK flag indicates that the store can generate the value of the PR_BODY property from the PR_RTF_COMPRESSED property dynamically, which relieves clients from the burden of synchronizing them explicitly. The STORE_UNCOMPRESSED_RTF flag indicates that the message store provider can support uncompressed data in PR_RTF_COMPRESSED.

Message store providers that do not support RTF text need to delete the PR_RTF_IN_SYNC (PidTagRtfInSync) property when the PR_BODY property changes in order to interoperate properly with client applications that do support RTF text.

See also

Concepts

Message Store Features


Providing Notifications for Message Store Providers

 Copy code hover
[image]

Providing Notifications for Message Store Providers
See also Send feedback

Published: July 16, 2012

While notifications are optional, they are a very important part of a good message store provider. Client applications and the MAPI spooler rely on notifications from the message store provider to get good performance when submitting outgoing messages or receiving incoming messages. Clients and the MAPI spooler can function without receiving notifications from the message store provider, but they will not be able to inform users of changes in the message store without them. Typically, this means that users will be unable to see that a new message has arrived until their client next opens the message store's receive folder.

Clients register for notifications by calling the IMsgStore::Advise method. The client passes in an IMAPIAdviseSink : IUnknown interface, a bitmask that indicates what type of notifications the client is interested in receiving, and an EntryID that indicates which object in the message store the Advise request applies to. When relevant events occur in the object (for example, when a new message arrives in the receive folder in the message store), the message store provider or the object itself should call the IMAPIAdviseSink::OnNotify method for all of the IMAPIAdviseSink objects that have registered for that event type.

Even if your message store provider never notifies other MAPI components of changes in the message store, it should still implement IMsgStore::Advise to return MAPI_E_NO_SUPPORT. This informs other components not to expect notifications from the message store provider.

See also

Concepts

Message Store Features


Grouping and Restricting Tables in Message Store Providers

 Copy code hover
[image]

Grouping and Restricting Tables in Message Store Providers
See also Send feedback

Published: July 16, 2012

Client applications frequently allow users some control over how the contents of a folder are displayed. Typically, a user can choose to have messages grouped according to the value of one or more message properties, or can choose to exclude messages that match certain criteria. This is done by using the IMAPITable : IUnknown interface. Client applications can restrict the rows returned from the table to whatever criteria the user specifies. Therefore, a message store provider needs to implement the following IMAPITable methods.

IMAPITable method | Description
IMAPITable::FindRow | Returns table rows that match the specified criteria.
IMAPITable::QueryColumns | Returns the set of columns in a table or the set of currently used columns.
IMAPITable::QueryRows | Returns one or more rows from a table, starting from a given position.
IMAPITable::Restrict | Applies a restriction to a table so that subsequent calls to FindRow return only rows that match the restriction.
IMAPITable::SetColumns | Specifies which columns should be returned when rows are retrieved from the table.

Restrictions can be complex to implement; for more information, see About Restrictions. For more information about implementing tables, see MAPI Tables.

See also

Concepts

Message Store Features


Supporting Searches in Message Store Providers

 Copy code hover
[image]

Supporting Searches in Message Store Providers
See also Send feedback

Published: July 16, 2012

Client applications frequently have some user interface components devoted to searching for messages in a message store. Search criteria are specified in the IMAPIContainer : IMAPIProp interface by means of the IMAPIContainer::SetSearchCriteria and IMAPIContainer::GetSearchCriteria methods.

Clients use the message store object's PR_FINDER_ENTRYID (PidTagFinderEntryId) property to identify the root folder in the message store that contains folders for search results. The search-results folder is often a folder at the top level of the message store that is not part of the IPM folder tree and is, therefore, hidden.

Whether your message store provider uses a permanent search-results folder or creates one when a client opens the entry identifier stored in the PR_FINDER_ENTRYID property is an implementation detail. It is somewhat easier for your message store provider to use a permanent folder that is created when the message store is created, because doing so avoids the complication of checking the entry identifier whenever any folder is opened to see whether to create a search-results folder. However, not all message store providers can do that; notably, read-only message stores or stores that provide a MAPI interface to a legacy database often are not allowed or are unable to create a permanent search-results folder in the underlying storage mechanism.

See also

Concepts

Message Store Features


Generating and Using Entry Identifiers in Message Store Providers

 Copy code hover
[image]

Generating and Using Entry Identifiers in Message Store Providers
See also Send feedback

Published: July 16, 2012

When a new folder or message is created in a message store, the message store provider has to assign that object an entry identifier so that client applications can refer to it. Message store providers can either reuse the defunct long-term entry identifiers of deleted objects or create new identifiers. There is no requirement one way or the other for message store providers; however, if it is feasible, a message store provider should always generate new long-term entry identifiers for new objects rather than reusing old ones. It is fine to reuse short-term entry identifiers when the objects they refer to are deleted.

The reason for this deletion is that clients can cache entry identifiers, sometimes for long periods of time. If that happens and the message store provider does reuse entry identifiers, it is possible for the entry identifier to refer to a different object when the client opens the entry identifier than when it first obtained the entry identifier. If the message store provider does not reuse entry identifiers — or at least uses an entry identifier generation scheme that does not repeat for a very long time — this problem cannot occur.

Similarly, message store providers should attempt to preserve entry identifiers for folders and messages when they are moved in the message store. If the message store provider can do that, references to objects in the store will not become invalid when the object is moved to a different location in the store.

See also

Concepts

Message Store Features


Default Message Stores

 Copy code hover
[image]

Default Message Stores
See also Send feedback

Published: July 16, 2012

A default message store is one that client applications can use for general purpose messaging tasks. There are a number of optional features for message store providers that become required if the message store provider is to be used as the default message store. They are as follows:

  • Implementing the special folders: the Inbox, Outbox, and search-results folders.

  • Providing read and nonread reports.

  • Allowing incoming and outgoing message submissions.

  • Allowing the creation of messages with arbitrary message classes.

  • Supporting named and multiple-value properties.

  • Supporting the IMSProvider::SpoolerLogon method, even if the message store provider is tightly coupled with a transport provider.

  • Supporting associated contents tables. For more information, see Contents Tables.

  • Supporting notification of the MAPI spooler when there are messages in the outgoing message queue.

See also

Concepts

Developing a MAPI Message Store Provider


Read-Only Message Stores

 Copy code hover
[image]

Read-Only Message Stores
See also Send feedback

Published: July 16, 2012

A read-only message store is one in which neither the MAPI client nor the MAPI spooler can create, modify, or delete the objects in the message store. There are many reasons why you might want to implement a read-only message store. For example, a credit reporting firm could use a read-only store to allow its customers or employees to see but not change individual credit reports. Choosing to make a read-only message store has implications for the structure of the store provider and for the store itself. For example, a read-only message store cannot have an Outbox folder, because then MAPI clients would request that new outgoing messages be created in that folder. Similarly, it is the store provider's responsibility to ensure the integrity of the underlying storage mechanism.

There are three flags that can be set in the message store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property that support different levels of read-only access. The STORE_READONLY flag indicates that all IMAPIProp : IUnknown interfaces on objects in the message store are read-only. The STORE_MODIFY_OK flag indicates that existing messages in the message store may be modified, but new folders and messages may not be created. The STORE_CREATE_OK flag indicates that new messages and folders may be created, but indicates nothing about whether existing objects may be modified.

The fact that MAPI clients and the MAPI spooler may not be able to create, modify, or delete objects in the message store does not mean that the contents of the underlying storage mechanism never change. Nor does it mean that your store provider never needs write permission to the underlying storage mechanism. In some circumstances those two conditions may apply, but not in the general case of a read-only message store. The level of access that your store provider requires and whether or not your store provider ever changes data in the underlying storage mechanism depends mainly on the specific nature of your store provider.

For example, if you are writing a store provider to give MAPI clients access to a database stored on a CD-ROM device, the underlying storage mechanism cannot change and your store provider can have read-only permission for it. If, however, you are writing a store provider to give MAPI clients read-only access to a public folder database, but the store provider needs to keep track of the read/unread status of messages for each user, the store provider will need to write new data to the underlying storage mechanism. However, in neither example does the store provider ever have to create, modify, or delete folders or messages at the request of MAPI clients or the MAPI spooler.

The short list of reasons that a store provider would need to write data to an underlying storage mechanism that is otherwise read-only is as follows:

  • To store the read/unread status of messages.

  • To implement read/nonread notifications.

  • To store views.

  • To cache persistent indexes for user-defined folder sort orders.

  • To store the sort order of a folder's contents (supporting IMAPIFolder::SaveContentsSort).

  • To store search criteria, search state, and results, if the message store provider supports searches (supporting IMAPIContainer::SetSearchCriteria).

If your message store provider can never write data to the underlying storage mechanism, it will need to implement these features by using a separate storage mechanism outside of the underlying storage mechanism. For example, a read-only message store provider could store the read/unread status of messages in the store in a file on the user's computer. This strategy presents additional difficulties but may be the only feasable way for read-only message store providers to implement some features. For example, keeping the contents of the separate storage mechanism synchronized with the objects in the message store is more difficult than storing the read/unread status directly in the message store itself.

Searching presents an additional complication for read-only message store providers. Clients use the folder specified in the message store object's PR_FINDER_ENTRYID (PidTagFinderEntryId) property to locate the folder used for search results. Read-only message store providers often cannot install a permanent search-results folder into the message store. In that situation, the message store provider should store an entry identifier in the PR_FINDER_ENTRYID property that it can recognize when clients open folders so that it can dynamically create a search-results folder instead of reading one from the underlying storage mechanism. However, because many read-only message store providers create all their folders dynamically, this is usually not too much of a burden.

The fact that your message store provider is read-only is advertised in the store provider object's PR_STORE_SUPPORT_MASK property. However, do not count on clients to respect that property; your store provider's code should enforce the read-only status of the underlying storage mechanism.

See also

Concepts

Developing a MAPI Message Store Provider


Supporting Forms and Views in Read-Only Message Stores

 Copy code hover
[image]

Supporting Forms and Views in Read-Only Message Stores
See also Send feedback

Published: July 16, 2012

If your message store provider allows read-only permission to the underlying storage mechanism, client applications and the MAPI form manager will be unable to do certain things. Specifically, clients will be unable to add or modify custom views, and the MAPI form manager will be unable to install forms in the associated contents tables of the store's folders.

For many read-only message stores, that may not be a problem. If that is the case, the message store provider does not need to support associated contents tables at all. However, if your message store provider must be read-only and it must also support a predefined set of views or forms, it will need to support associated contents tables.

The most common strategy for doing this, because clients and the MAPI form manager cannot install the views or forms into the message store themselves, is for the message store provider to hard-code them into the message store. This means that the associated contents table or tables that contain the views or forms will exist in the message store when it is created, before any clients or the MAPI form manager ever access it. Then, when a client requests an associated contents table to get custom views from a form or the MAPI form manager requests an associated contents table to launch a form, the message store provider can provide one.

This requirement that the associated contents tables be created and populated when the message store itself is created implies that your message store provider will need to obtain information about the format of the special messages that clients and the MAPI form manager use to store views and forms. What those formats are will depend on the client and MAPI form manager being used, so a description of them cannot be provided here.

See also

Concepts

Read-Only Message Stores


Tightly Coupled Message Store Providers

 Copy code hover
[image]

Tightly Coupled Message Store Providers
See also Send feedback

Published: July 16, 2012

Message store providers can be tightly coupled with a transport provider. Tightly coupling MAPI service providers means implementing the two providers such that the store provider and transport provider can communicate to make the process of sending and receiving messages more efficient. The benefit of doing this is that performance improvements can result when two service providers can interact with each other directly rather than by means of MAPI spooler. To tightly couple a message store provider to a transport provider, the transport provider must place the message store provider's entry identifier in the PR_OWN_STORE_ENTRYID (PidTagOwnStoreEntryId) property in the transport provider's row in the MAPI status table. This enables MAPI spooler to connect the store provider to the transport provider.

There is no requirement that a message store provider ever be tightly coupled with any other service provider. The most common service provider to tightly couple with a message store provider is a transport provider. This is usually done so that sending and receiving messages can be accomplished without involving the MAPI spooler. For example, when the user submits an outgoing message, the combined message store provider and transport provider can send it directly. The combined service providers do not have to first notify MAPI spooler that there is a new message to process and then wait for MAPI spooler to initiate the process of transferring the message from the message store provider to the transport provider. This has particular benefits when a server-based message store is being used by minimizing network traffic between the user's computer and the server.

In general, there are no well-specified procedures for tightly coupling service providers. However, you should use the following guidelines:

  • If the reason for tightly coupling service providers is performance, be aware that the coupling takes parts of the MAPI subsystem out of the processes that those parts would normally be involved in. This implies that the individual parts in the combined service provider should interact with each other in a way that simulates the interaction they would normally have with the parts of the MAPI subsystem that are not being used.

  • When tightly coupled service providers do interact with other MAPI components, they must still interact with them in exactly the way they would if they were not tightly coupled. For example, if a user is using a combined message store provider and transport provider as their default message store but is using a separate transport provider to send messages — as can happen when a user takes a computer on the road and switches to a remote transport provider — the message store portion of the tightly coupled service provider must still interact with MAPI spooler just as if it were a standalone message store provider.

See also

Concepts

Developing a MAPI Message Store Provider


Loading Message Store Providers

 Copy code hover
[image]

Loading Message Store Providers
See also Send feedback

Published: July 16, 2012

When a client application opens a message store, MAPI loads the message store provider's DLL into memory. After MAPI loads the DLL, a very specific sequence of method calls occurs between the message store provider and MAPI. This method call sequence enables MAPI to get top-level IMSProvider : IUnknown, IMSLogon : IUnknown, and IMsgStore : IMAPIProp interfaces, and allows the message store provider to get a MAPI support object. After the call sequence, the message store provider should be ready to accept logons from clients.

The call sequence when a message provider DLL is loaded is as follows:

  1. The client calls IMAPISession::OpenMsgStore.

  2. If the message store is not already open, MAPI loads the store provider's DLL and calls the DLL's MSProviderInit entry point. If the message store is already open, MAPI skips steps 2 and 3, and then uses the existing IMSProvider : IUnknown interface to complete step 4.

  3. MSProviderInit creates and returns an IMSProvider object.

  4. MAPI calls IMSProvider::Logon, passing the client application's message store entry identifier.

  5. IMSProvider::Logon creates and returns an IMSLogon : IUnknown interface and an IMsgStore : IMAPIProp interface, and then calls the IUnknown::AddRef method on its IMAPISupport : IUnknown interface. If the client's message store entry identifier refers to a message store that is already open, the message store provider can return existing IMSLogon and IMsgStore interfaces and does not need to call AddRef on its support object.

  6. If the client did not set the MAPI_NO_MAIL flag when it logged on and it did not set the MDB_NO_MAIL in step 1, MAPI gives the message store's entry identifier to the MAPI spooler so the MAPI spooler can log on to the message store.

  7. MAPI returns the IMsgStore interface to the client.

  8. The MAPI spooler calls IMSProvider::SpoolerLogon.

  9. IMSProvider::SpoolerLogon returns the same IMSLogon and IMsgStore interfaces from step 5.

Note Note

If the logon call to the message store provider fails because an incorrect password was supplied and the message store provider cannot display an interface to ask for the correct password, it should return MAPI_E_FAILONEPROVIDER from the IMSProvider::Logon method. This will allow clients to prompt the user for a password to try logging on to the message store provider again instead of causing MAPI to fail the provider for the entire session.

See also

Concepts

Developing a MAPI Message Store Provider


MAPI Reference

 Copy code hover
[image]

MAPI Reference
Send feedback

Published: July 16, 2012

This section documents the MAPI programming elements.

In this section

MAPI Interfaces

Contains information about the MAPI interfaces and interface methods.

MAPI Functions, Callbacks, and Macros

Contains information about the functions, callbacks, and macros used in MAPI.

MAPI Properties

Contains information about MAPI properties.

MAPI Structures

Contains information about the structures used in MAPI.

Macros Related to Structures

Contains information about the macros related to structures used in MAPI.

MAPI Data Types

Contains information about the data types used in MAPI.

Related sections

Outlook 2013 MAPI Reference

Getting Started with the Outlook 2013 MAPI Reference

MAPI Samples

MAPI Concepts


MAPI Interfaces

 Copy code hover
[image]

MAPI Interfaces
See also Send feedback

Published: July 16, 2012

The documentation for each interface consists of an introductory section that includes a brief description of the interface's purpose followed by a table that contains the following information.

Header file: | The header file where the interface is defined and that must be included when you compile your source code.
Exposed by: | The object that exposes the interface.
Implemented by: | A list of the components that provide an implementation of the interface.
Called by: | A list of the components that typically call the methods of the interface.
Interface identifier: | The interface identifier GUID.
Pointer type: | The pointer type for the object that exposes the interface.
Transaction model: | For interfaces derived from IMAPIProp. If nontransacted, changes take effect immediately; if transacted, changes do not take effect until IMAPIProp::SaveChanges is called.

Following the first table is another table that lists all the methods of this interface in vtable order. A vtable is an array of function pointers created by the compiler containing one function pointer for each method of a MAPI object. The methods are listed in the same order that they are declared. Methods inherited from other interfaces are not shown in the Vtable Order table but can be used in the same way as documented in the interface that defines them.

After each interface topic, the interface's methods are then documented in alphabetical order. For each method, the documentation includes a brief purpose statement, a syntax block, and the following information.

Heading | Content
Parameters | A description of each parameter in the method.
Return Value | A description of the unique values that the method can return. These are the values that callers should check for in their code.
Remarks | A description of why and how the method is used.
See Also | Cross-references to other topics in this Reference.

See also

Other resources

MAPI Reference


IABContainer : IMAPIContainer

 Copy code hover
[image]

IABContainer : IMAPIContainer
See also Send feedback

Published: July 16, 2012

Provides access to address book containers. MAPI and client applications call the methods of IABContainer to perform name resolution and to create, copy, and delete recipients.

Header file: | Mapidefs.h
Exposed by: | Address book container objects
Implemented by: | Address book providers
Called by: | MAPI and client applications
Interface identifier: | IID_IABContainer
Pointer type: | LPABCONT
Transaction model: | Transacted

Vtable Order

CreateEntry | Creates a new entry, which can be a messaging user, a distribution list, or another container.
CopyEntries | Copies one or more entries, typically messaging users or distribution lists.
DeleteEntries | Removes one or more entries, typically messaging users, distribution lists, or other containers.
ResolveNames | Performs name resolution for one or more recipient entries.
Required properties | Access
PR_CONTAINER_FLAGS (PidTagContainerFlags) | Read/write
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write
PR_ENTRYID (PidTagEntryId) | Read-only
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only
Optional properties | Access
PR_CONTAINER_CONTENTS (PidTagContainerContents) | Read-only
PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) | Read-only
PR_DEF_CREATE_DL (PidTagDefCreateDl) | Read-only
PR_DEF_CREATE_MAILUSER (PidTagDefCreateMailuser) | Read-only
PR_DISPLAY_TYPE (PidTagDisplayType) | Read-only

Remarks

The IABContainer interface inherits indirectly from the IUnknown interface through the IMAPIContainer : IMAPIProp and IMAPIProp : IUnknown interfaces. Address book providers implement the IABContainer interface.

Any number of messaging user objects, distribution lists, and other address book containers can exist in an address book container. As with any container, clients or service providers can use an address book container to open one of its entries or to retrieve a hierarchy table or contents table. Address book containers also provide name resolution and, depending on the provider, the ability to add, remove, or modify entries.

MAPI defines a special address book container called the personal address book (PAB) that holds entries copied from other containers. A PAB is always modifiable. Users typically populate their PAB with entries designating the recipients with which they most frequently communicate. A PAB can also hold one-off addresses and new recipients not yet a part of any address book container.

See also

Concepts

MAPI Interfaces


IABContainer::CopyEntries

 Copy code hover
[image]

IABContainer::CopyEntries
See also Send feedback

Published: July 16, 2012

Copies one or more entries, typically messaging users or distribution lists.

C++
HRESULT CopyEntries(
  LPENTRYLIST lpEntries,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpEntries

[in] A pointer to an array of ENTRYLIST structures that contains the entry identifiers of the entries to copy.

ulUIParam

[in] The handle to the parent window of any dialog boxes or windows that this method displays. The ulUIParam parameter must be zero if the AB_NO_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator, or NULL. If lpProgress is NULL, a progress indicator should be displayed by using the progress object supplied by MAPI through the IMAPISupport::DoProgressDialog method. The lpProgress parameter is ignored if the AB_NO_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls how the copy operation is performed. The following flags can be set:

AB_NO_DIALOG

Suppresses display of a progress indicator. If this flag is not set, a progress indicator is displayed.

CREATE_CHECK_DUP_LOOSE

Indicates that a loose level of duplicate entry checking should be performed. The implementation of loose duplicate entry checking is provider specific. For example, a provider can define a loose match as any two entries that have the same display name.

CREATE_CHECK_DUP_STRICT

Indicates that a strict level of duplicate entry checking should be performed. The implementation of strict duplicate entry checking is provider specific. For example, a provider can define a strict match as any two entries that have both the same display name and messaging address.

CREATE_REPLACE

Indicates that a new entry should replace an existing one if it is determined that the two are duplicates.

Return value

S_OK

The copy operation succeeded.

MAPI_W_PARTIAL_COMPLETION

The copy operation succeeded overall, but one or more of the entries could not be copied. When this value is returned, the call should be handled as successful. To test for this value, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IABContainer::CopyEntries method copies entries from the same container or a different container. A call to CopyEntries is functionally equivalent to making the following calls for each entry to be copied:

  1. The IABContainer::CreateEntry method to create the new entry.

  2. The IMAPIProp::GetProps method to read properties from the entry to be copied.

  3. The IMAPIProp::SetProps method to write properties to the new entry.

  4. The new entry's IMAPIProp::SaveChanges method to perform a save.

  5. The new entry's IUnknown::Release method to release the container's reference.

Notes to Implementers

All containers that support the IABContainer::CopyEntries method must be modifiable. Set your container's AB_MODIFIABLE flag in its PR_CONTAINER_FLAGS (PidTagContainerFlags) property to indicate that it is modifiable.

You must support all of the flags; however, the interpretation and use of these flags is implementation specific—that is, you can determine what the semantics of the CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags mean in the context of your implementation. If you cannot or do not determine whether an entry is a duplicate, always allow the entry to be copied.

If the CREATE_REPLACE flag is set, always copy the entry regardless of whether CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT is set and whether the entry is a duplicate.

If CREATE_REPLACE is not set and CREATE_CHECK_DUP_STRICT is set, check for duplicates. If an entry is determined to be a duplicate, do not copy the entry.

You do not need to support CREATE_REPLACE; not supporting CREATE_REPLACE means that you can safely ignore it and always perform a copy.

Return the warning MAPI_W_PARTIAL_COMPLETION only if a nonduplicate entry cannot be copied.

Notes to Callers

Use the CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags to indicate to the provider how you want the container to perform duplicate-entry checking. If you need to have an entry added regardless of whether it is a duplicate, either do not set either of these flags or set the CREATE_REPLACE flag. CREATE_REPLACE indicates that you do not care if an entry is a duplicate; you always want it to replace the original entry.

See also

Reference

ENTRYLIST
IABContainer::CreateEntry
IMAPIProgress : IUnknown
IMAPIProp::SaveChanges
IABContainer : IMAPIContainer


IABContainer::CreateEntry

 Copy code hover
[image]

IABContainer::CreateEntry
See also Send feedback

Published: July 16, 2012

Creates a new entry, which can be a messaging user, a distribution list, or another container.

C++
HRESULT CreateEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulCreateFlags,
  LPMAPIPROP FAR * lppMAPIPropEntry
);

Parameters

cbEntryID

[in] The count of the bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of a template for creating new entries of a particular type.

ulCreateFlags

[in] A bitmask of flags that controls how entry creation is performed. The following flags can be set:

CREATE_CHECK_DUP_LOOSE

A loose level of duplicate entry checking should be performed. The implementation of loose duplicate entry checking is provider specific. For example, a provider can define a loose match as any two entries that have the same display name.

CREATE_CHECK_DUP_STRICT

A strict level of duplicate entry checking should be performed. The implementation of strict duplicate entry checking is provider specific. For example, a provider can define a strict match as any two entries that have both the same display name and messaging address.

CREATE_REPLACE

A new entry should replace an existing one if it is determined that the two are duplicates.

lppMAPIPropEntry

[out] A pointer to a pointer to the newly created entry.

Return value

S_OK

The new entry was successfully created.

Remarks

The IABContainer::CreateEntry method creates a new entry of a particular type in the specified container, returning a pointer to an interface implementation for further access to the entry. The new entry is created by using a template that has been selected from the container's list of available templates published in its one-off table. Callers access a container's one-off table by calling its IMAPIProp::OpenProperty method and requesting the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property.

Notes to Implementers

All containers that support the IABContainer::CreateEntry method must be modifiable. Set your container's AB_MODIFIABLE flag in its PR_CONTAINER_FLAGS (PidTagContainerFlags) property to indicate that it is modifiable.

You should support all of the ulCreateFlags flags. However, the interpretation and use of these flags is implementation specific—that is, you can determine what the semantics of CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT mean in the context of your implementation. If you cannot or do not determine whether an entry is a duplicate, always allow the entry to be created.

Some providers implement strict entry checking by matching the display name, messaging address, and search key in an entry; other providers limit the match to display name and address. Loose entry checking is often implemented by checking the display name only.

Notes to Host Address Book Provider Implementers

If your container can create entries from the templates of other providers, your implementation of CreateEntry should provide storage for some or all of the properties associated with the created entries. For example, if you provide storage for an entry's PR_DETAILS_TABLE (PidTagDetailsTable) property, you can generate its details dialog box without having to depend on the foreign provider.

If your container can create entries that support the PR_TEMPLATEID (PidTagTemplateid) property, your implementation of CreateEntry must do the following:

  1. Call the IMAPISupport::OpenTemplateID method. OpenTemplateID enables the foreign provider's code for the entry to bind to the new entry being created. Foreign providers support this binding process to maintain control over entries created from their templates into the containers of host address book providers.

  2. Perform any necessary initialization, and populate the new object with all of the properties from the entry in the foreign provider that the object returned in the lppMAPIPropNew parameter from OpenTemplateID.

If OpenTemplateID succeeds, copy the properties to the implementation pointed to by the lppMAPIPropNew parameter rather than directly to the implementation pointed to by the lpMAPIPropData parameter. Initialize the new entry for offline use as you would any other entry from a foreign provider.

If OpenTemplateID returns an error, CreateEntry should fail. Do not allow the entry to be created. Because the foreign provider can make assumptions about the data in your provider, do not create an entry with a template identifier that has not been successfully bound to the foreign provider.

Notes to Callers

When CreateEntry returns, you may or may not be able to immediately access the entry identifier for the new entry. Some address book providers do not make it available until after you have called the new entry's IMAPIProp::SaveChanges method.

Although duplicate checking flags are passed as parameters to CreateEntry, the duplicate checking operation does not occur until SaveChanges is called. Therefore, related errors such as MAPI_E_COLLISION, which indicates that an attempt was made to create an already existing entry, are returned by SaveChanges rather than CreateEntry.

See also

Reference

IABContainer::CopyEntries
IMAPIProp::OpenProperty
IMAPIProp::SaveChanges
PidTagCreateTemplates Canonical Property
IABContainer : IMAPIContainer


IABContainer::DeleteEntries

 Copy code hover
[image]

IABContainer::DeleteEntries
See also Send feedback

Published: July 16, 2012

Removes one or more entries, typically messaging users, distribution lists, or other containers.

C++
HRESULT DeleteEntries(
  LPENTRYLIST lpEntries,
  ULONG ulFlags
);

Parameters

lpEntries

[in] A pointer to an array of ENTRYLIST structures that contain entry identifiers that represent the entries being deleted.

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The specified entries have been successfully deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but one or more of the entries could not be deleted. When this value is returned, the call should be handled as successful. To test for this value, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
Abdlg.cpp | CabDlg::OnDeleteSelectedItem | MFCMAPI uses the DeleteEntries method to delete a specific entry from an address book container.

See also

Reference

IABContainer : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IABContainer::ResolveNames

 Copy code hover
[image]

IABContainer::ResolveNames
See also Send feedback

Published: July 16, 2012

Performs name resolution for one or more recipient entries.

C++
HRESULT ResolveNames(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  LPADRLIST lpAdrList,
  LPFlagList lpFlagList
);

Parameters

lpPropTagArray

[in] A pointer to an SPropTagArray structure that contains an array of property tags describing the properties to be included in the ADRLIST structure returned by the provider. To request the provider's default set of properties, pass NULL in the lpPropTagArray parameter.

ulFlags

[in] A bitmask of flags that controls the type of the text in the returned strings. The following flags can be set:

EMS_AB_ADDRESS_LOOKUP

Only exact proxy address matches will be found; partial matches are ignored. This flag is supported only by the Exchange Address Book Provider.

MAPI_CACHE_ONLY

Only the offline address book will be used to perform name resolution. For example, you can use this flag to enable a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_UNICODE

The returned string properties are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpAdrList

[in, out] On input, a pointer to an ADRLIST structure that contains the list of recipients to be resolved. On output, a pointer to an ADRLIST structure that contains the resolved names.

lpFlagList

[in, out] A pointer to an array of flags, each flag corresponding to an ADRENTRY structure in the lpAdrList parameter, that provides the status of the name resolution operation for the recipient. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:

MAPI_AMBIGUOUS

The corresponding recipient has been resolved, but not to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_RESOLVED

The corresponding recipient has been resolved to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_UNRESOLVED

The corresponding entry has not been resolved. Other containers should try to resolve this recipient.

Return value

S_OK

The name resolution process was successful.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_NO_SUPPORT

The address book provider does not support bulk name resolution by using this method.

Remarks

The ResolveNames method attempts to match unresolved recipients from the array of entries in the lpAdrList parameter to recipients in this address book container. An unresolved recipient typically has only the PR_DISPLAY_NAME (PidTagDisplayName) property and possibly a few other properties. An unresolved recipient does not have the PR_ENTRYID (PidTagEntryId) property, and its corresponding flag in the lpFlagList parameter is set to MAPI_UNRESOLVED. Conversely, a resolved recipient always has at least the PR_ENTRYID property plus several other properties such as PR_EMAIL_ADDRESS (PidTagEmailAddress), PR_DISPLAY_NAME, and PR_ADDRTYPE (PidTagAddressType).

Name resolution typically starts when a client calls the IAddrBook::ResolveName method. Outlook MAPI responds by calling the ResolveNames method of each address book container included in the address book search path, specified by the PR_AB_SEARCH_PATH (PidTagAbSearchPath) property. The entries in the lpAdrList parameter include recipients already resolved because they are in containers for which MAPI has already called ResolveNames, because the entries appear earlier in the search path.

Each container attempts to resolve the unresolved entries by matching the display name of the recipient with the display name of one of its entries. When a unique match is found, ResolveNames adds the PR_ENTRYID property and other properties that are included in the lpPropTagArray parameter to the corresponding entry in the outgoing ADRLIST structure. ResolveNames then sets the entry in the lpFlagList parameter to MAPI_RESOLVED. The entry identifier stored in the PR_ENTRYID property can be short-term or long-term.

After all of the containers in the search path have attempted the name resolution process, MAPI opens a dialog box, if possible, to prompt the user for help in resolving any remaining conflicts.

Clients can also use the returned ADRLIST structure in calls to the IMessage::ModifyRecipients method.

Notes to Implementers

You are not required to support name resolution with the ResolveNames method. Instead, or additionally, you can support it with the PR_ANR (PidTagAnr) property restriction. If you decide to rely on the PR_ANR restriction for name resolution, you can return MAPI_E_NO_SUPPORT. For more information, see Implementing Name Resolution.

Set a recipient's flag entry in the lpFlagList parameter to MAPI_UNRESOLVED if the recipient does not match any of the container's recipients.

When a recipient matches multiple recipients, set its flag to MAPI_AMBIGUOUS and do not change its ADRENTRY structure.

MAPI requires certain properties for recipients that are included in a message's recipient list. You can include them in the ADRENTRY structure as part of the name resolution process or wait for MAPI to request them with calls to the IAddrBook::PrepareRecips and IMAPISupport::ExpandRecips methods. You can eliminate these extra calls and improve performance by including the following properties in the ADRENTRY structures of all resolved recipients:

  • PR_ADDRTYPE

  • PR_DISPLAY_NAME

  • PR_EMAIL_ADDRESS

  • PR_ENTRYID

  • PR_OBJECT_TYPE (PidTagObjectType)

  • PR_SEARCH_KEY (PidTagSearchKey)

  • PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)

If some of the properties in the lpPropTagArray parameter are unavailable—typically because the container entry does not support the properties and they are not included in the recipient's ADRENTRY member in the ADRLIST structure—set the property type of each unavailable property to PT_ERROR.

Do not remove any properties from a resolved recipient's ADRENTRY structure.

If you must replace rather than modify an ADRENTRY structure, free the original ADRENTRY structure first by calling the MAPIFreeBuffer function, and then allocate the replacement ADRENTRY structure with MAPIAllocateBuffer.

See also

Reference

ADRENTRY
ADRLIST
IAddrBook::PrepareRecips
IAddrBook::ResolveName
IMAPISupport::ExpandRecips
IMessage::ModifyRecipients
PidTagAnr Canonical Property
SPropertyRestriction
IABContainer : IMAPIContainer


IABLogon : IUnknown

 Copy code hover
[image]

IABLogon : IUnknown
See also Send feedback

Published: July 16, 2012

Accesses resources in an address book provider.

Header file: | Mapispi.h
Exposed by: | Address book logon objects
Implemented by: | Address book providers
Called by: | MAPI
Interface identifier: | IID_IABLogon
Pointer type: | LPABLOGON

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous address book provider error.
Logoff | Initiates the logoff process.
OpenEntry | Opens a container, messaging user, or distribution list, and returns a pointer to an interface implementation to provide further access.
CompareEntryIDs | Compares two entry identifiers to determine whether they refer to the same object.
Advise | Registers the caller to receive notification of specified events that affect a container, messaging user, or distribution list.
Unadvise | Cancels notifications that were previously set up with a call to the Advise method.
OpenStatusEntry | Opens the provider's status object.
OpenTemplateID | Opens a recipient entry that has data residing in a host address book provider.
GetOneOffTable | Returns a table of one-off templates for creating recipients to be added to the recipient list of an outgoing message.
PrepareRecips | Prepares a recipient list for later use by the messaging system.

Remarks

For general information about the methods of the IABLogon interface, see Implementing Service Provider Logon.

See also

Concepts

MAPI Interfaces


IABLogon::Advise

 Copy code hover
[image]

IABLogon::Advise
See also Send feedback

Published: July 16, 2012

Registers the caller to receive notification of specified events that affect a container, messaging user, or distribution list.

C++
HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG FAR * lpulConnection
);

Parameters

cbEntryID

[in] The count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object about which notifications should be generated.

ulEventMask

[in] A bitmask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event. The following table lists the valid values for the ulEventMask parameter and the structures associated with each value.

Notification event type

Corresponding NOTIFICATION structure

fnevCriticalError

ERROR_NOTIFICATION

fnevObjectCreated

OBJECT_NOTIFICATION

fnevObjectDeleted

OBJECT_NOTIFICATION

fnevObjectModified

OBJECT_NOTIFICATION

fnevObjectCopied

OBJECT_NOTIFICATION

fnevObjectMoved

OBJECT_NOTIFICATION

lpAdviseSink

[in] A pointer to an advise sink object to receive the subsequent notifications.

lpulConnection

[out] A pointer to a nonzero value that represents the notification registration.

Return value

S_OK

The notification registration was successful.

MAPI_E_INVALID_ENTRYID

The entry identifier passed in the lpEntryID parameter is not in the appropriate format.

MAPI_E_NO_SUPPORT

The address book provider does not support notification, possibly because it does not allow changes to be made to its objects.

MAPI_E_UNKNOWN_ENTRYID

The address book provider cannot handle the entry identifier passed in lpEntryID.

Remarks

Address book providers implement the IABLogon::Advise method to register the caller to be notified when a change occurs to an object in one of their containers. Callers can register for notifications regarding messaging users, distribution lists, or entire containers.

Clients typically call the IAddrBook::Advise method to register for address book notifications. MAPI then calls the Advise method of the address book provider that is responsible for the object represented by the entry identifier in lpEntryID.

When a change occurs to the indicated object of the type represented in ulEventMask, a call is made to the OnNotify method of the advise sink pointed to by lpAdviseSink. Data passed in the NOTIFICATION structure to the OnNotify routine describes the event.

Notes to Implementers

You can support notification with or without help from MAPI. MAPI has three support object methods to help service providers implement notification:

  • IMAPISupport::Subscribe

  • IMAPISupport::Unsubscribe

  • IMAPISupport::Notify

If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.

If you elect to support notification yourself, call the AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IABLogon::Unadvise method is called to cancel the registration.

Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until the Unadvise method has been called.

Notes to Callers

The advise sink pointer that you pass in the lpAdviseSink parameter to Advise can point to an object that you have created or that MAPI has created through the HrThisThreadAdviseSink function. You might want to use HrThisThreadAdviseSink if you support multiple threads of execution and want to be sure that that subsequent calls to your OnNotify method occur at an appropriate time on an appropriate thread.

Be prepared for your advise sink object to be released any time after your call to Advise and before your call to Unadvise. Therefore, you should release your advise sink object after Advise returns, unless you have a specific long-term use for it.

For more information about the notification process, see Event Notification in MAPI. For information about how to use the IMAPISupport methods to support notification, see Supporting Event Notification. For more information about multithreading and MAPI, see Threading in MAPI.

See also

Reference

HrThisThreadAdviseSink
IABLogon::Unadvise
IMAPIAdviseSink::OnNotify
NOTIFICATION
IABLogon : IUnknown


IABLogon::CompareEntryIDs

 Copy code hover
[image]

IABLogon::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers to determine whether they refer to the same object.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulRet
);

Parameters

cbEntryID1

[in] The byte count in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The byte count in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulRet

[out] A pointer to the result of the comparison. TRUE to indicate that the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The entry identifiers were successfully compared.

MAPI_E_INVALID_ENTRYID

One or both of the entry identifiers do not belong to the address book provider.

Remarks

Address book providers implement the CompareEntryIDs method to compare two entry identifiers to determine whether they refer to the same object.

CompareEntryIDs is useful because an object can have more than one valid entry identifier; such a situation can occur, for example, when you compare a short-term entry identifier with a long-term entry identifier.

For more information about how to create entry identifiers, see MAPI Entry Identifiers.

See also

Reference

IABLogon : IUnknown


IABLogon::GetLastError

 Copy code hover
[image]

IABLogon::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous address book provider error.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] A handle to the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to a MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if the provider cannot supply a MAPIERROR structure with appropriate information.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the address book provider does not support Unicode, or MAPI_UNICODE was not set and the address book provider supports only Unicode.

Remarks

Address book providers implement the GetLastError method to supply information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can use the MAPIERROR structure pointed to by the lppMAPIError parameter if the address book provider supplies the structure and only if GetLastError returns S_OK. Sometimes the address book provider cannot determine what the last error was or has nothing more to report about the error. In this situation, the address book provider returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IABLogon : IUnknown


IABLogon::GetOneOffTable

 Copy code hover
[image]

IABLogon::GetOneOffTable
See also Send feedback

Published: July 16, 2012

Returns a table of one-off templates for creating recipients to be added to the recipient list of an outgoing message.

C++
HRESULT GetOneOffTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of string columns included in the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] A pointer to a pointer to the one-off table.

Return value

S_OK

The one-off table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the address book provider does not support Unicode, or MAPI_UNICODE was not set and the address book provider supports only Unicode.

MAPI_E_NO_SUPPORT

The address book provider does not supply any one-off templates.

Remarks

MAPI calls the GetOneOffTable method to make available one-off templates to create recipients. The new recipients are added to the recipient list of an outgoing message. Address book providers should support notification on their one-off table to inform MAPI of template modifications. MAPI keeps the one-off table open to enable dynamic updating.

Address book providers can also support a one-off table for each of their containers. Callers retrieve this one-off table by calling the container's IMAPIProp::OpenProperty method and requesting the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property. The templates available through this table are used to add recipients to the container. For a discussion of the differences between the two types of one-off tables, see Implementing One-Off Tables.

For a list of the required columns in an address book provider's one-off table, see One-Off Tables.

See also

Reference

IABContainer::CreateEntry
IAddrBook::NewEntry
IMAPISupport::GetOneOffTable
IABLogon : IUnknown


IABLogon::Logoff

 Copy code hover
[image]

IABLogon::Logoff
See also Send feedback

Published: July 16, 2012

Initiates the logoff process.

C++
HRESULT Logoff(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The logoff process was successfully initiated.

Remarks

The logoff process is typically started when a client calls the IMAPISession::Logoff method to end a session. MAPI then calls each address book provider's IABLogon::Logoff method to start the logoff process.

The IABLogon::Logoff method does the following:

  • Releases all open objects, such as any subobjects or the status object.

  • Releases the provider's support object.

For more information about the logoff process of address book providers, see Shutting Down a Service Provider.

See also

Reference

IABProvider::Logon
IABLogon : IUnknown


IABLogon::OpenEntry

 Copy code hover
[image]

IABLogon::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens a container, messaging user, or distribution list, and returns a pointer to an interface implementation to provide further access.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the container, messaging user, or distribution list to open.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the open object. Passing NULL returns the identifier for the object's standard interface. For containers, the standard interface is IABContainer : IMAPIContainer. The standard interfaces for address book objects are IDistList : IMAPIContainer for a distribution list and IMailUser : IMAPIProp for a messaging user.

ulFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the object should be opened with read/write permission; if the client has read-only permission, the object should be opened with read-only permission.

MAPI_DEFERRED_ERRORS

Allows the OpenEntry method to return successfully, possibly before the calling client has fully accessed the object. If the object is not accessed, making a subsequent object call can raise an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only access, and clients should not assume that read/write permission has been granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppUnk

[out] A pointer to a pointer to the opened object.

Remarks

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

Either the user has insufficient permissions to open the object, or an attempt was made to open a read-only object with read/write permission.

MAPI_E_NOT_FOUND

The entry identifier specified by lpEntryID does not represent an object.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier in the lpEntryID parameter is not of a format recognized by the address book provider.

Remarks

MAPI calls the OpenEntry method to open a container, messaging user, or distribution list.

Notes to Implementers

Before MAPI calls your OpenEntry method, it determines that the entry identifier in the lpEntryID parameter belongs to you and not to another provider. MAPI does this by matching the MAPIUID structure in the entry identifier with the MAPIUID that you registered by calling the IMAPISupport::SetProviderUID method at startup.

Open the object as read-only, unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag is set in the ulFlags parameter. If you do not allow modification for the requested object, do not open the object at all and return MAPI_E_NO_ACCESS.

If MAPI passes NULL for lpEntryID, open the root container in your container hierarchy.

The object that you are being asked to open might be an object copied from another provider. In this case, it will support the PR_TEMPLATEID (PidTagTemplateid) property. If the object does support this property, call the IMAPISupport::OpenTemplateID method to bind to code for this entry in the foreign provider, passing PR_TEMPLATEID in the lpTemplateID parameter and 0 in the ulTemplateFlags parameter. IMAPISupport::OpenTemplateID passes this information to the foreign provider in a call to the foreign provider's IABLogon::OpenTemplateID method. If IMAPISupport::OpenTemplateID raises an error, usually because the foreign provider is unavailable or not included in the profile, try to continue by treating the unbound entry as read-only. For more information about opening foreign address book entries, see Acting as a Host Address Book Provider.

See also

Reference

IABLogon : IUnknown


IABLogon::OpenStatusEntry

 Copy code hover
[image]

IABLogon::OpenStatusEntry
See also Send feedback

Published: July 16, 2012

Opens the provider's status object.

C++
HRESULT OpenStatusEntry(
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPMAPISTATUS FAR * lppEntry
);

Parameters

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface that must be used to access the status object. Passing NULL returns the object's standard interface, IMAPIStatus : IMAPIProp.

ulFlags

[in] A bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only access, and callers should not assume that read/write permission has been granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppEntry

[out] A pointer to a pointer to the opened object.

Return value

S_OK

The call succeeded and the status object has been opened.

Remarks

Address book providers implement the OpenStatusEntry method to grant access to their status object. All address book providers are required to implement a status object that supports, at a minimum, the IMAPIStatus::ValidateState method. For more information, see Status Object Implementation.

See also

Reference

IMAPIStatus : IMAPIProp
IMAPIStatus::SettingsDialog
IMAPIStatus::ValidateState
IABLogon : IUnknown


IABLogon::OpenTemplateID

 Copy code hover
[image]

IABLogon::OpenTemplateID
See also Send feedback

Published: July 16, 2012

Opens a recipient entry that has data residing in a host address book provider.

C++
HRESULT OpenTemplateID(
  ULONG cbTemplateID,
  LPENTRYID lpTemplateID,
  ULONG ulTemplateFlags,
  LPMAPIPROP lpMAPIPropData,
  LPCIID lpInterface,
  LPMAPIPROP FAR * lppMAPIPropNew,
  LPMAPIPROP lpMAPIPropSibling
);

Parameters

cbTemplateID

[in] The byte count in the template identifier pointed to by the lpTemplateID parameter.

lpTemplateID

[in] A pointer to the template identifier, or PR_TEMPLATEID (PidTagTemplateid) property, of the recipient entry to be opened.

ulTemplateFlags

[in] A bitmask of flags used to indicate how to open the entry represented by the template identifier. The following flag can be set:

FILL_ENTRY

The host provider is creating a new entry in its container based on the entry represented by the template identifier. The IABLogon::OpenTemplateID method should either perform specific initialization of the host provider's entry by using the IMAPIProp : IUnknown implementation in the lpMAPIPropData parameter, or return a custom IMAPIProp interface implementation in the lppMAPIPropNew parameter.

lpMAPIPropData

[in] A pointer to the host provider's property object and implementation of an interface derived from IMAPIProp.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the type of interface pointer to be returned in the lppMAPIPropNew parameter. Passing null returns the standard messaging user interface, IMailUser : IMAPIProp.

lppMAPIPropNew

[out] A pointer to the bound property object and an implementation of an interface derived from IMAPIProp.

lpMAPIPropSibling

[out] Reserved; must be null.

Return value

S_OK

The appropriate code was successfully bound to related data in the host provider.

MAPI_E_NO_SUPPORT

The object does not support template IDs.

MAPI_E_UNKNOWN_ENTRYID

The template identifier passed in the lpTemplateID parameter is not recognized by the address book provider.

Remarks

The IABLogon::OpenTemplateID method is implemented only by address book providers that need to maintain control over copies of their entries that are located in the containers of host providers. Providers that implement OpenTemplateID are known as foreign address book providers. Host providers call IMAPISupport::OpenTemplateID to create a copied entry or open the copied entry, and MAPI passes on the call to IABLogon::OpenTemplateID. IABLogon::OpenTemplateID opens the entry and binds the code that controls it to data in the host provider.

Rather than use an entry identifier, IABLogon::OpenTemplateID uses another property, the entry's template identifier, PR_TEMPLATEID. Template identifiers should be supported for entries whose code must be bound to data in a host provider.

Some examples of when an address book provider should implement IABLogon::OpenTemplateID are as follows:

  • To periodically update the data for a copied entry so that it stays synchronized with the original.

  • To implement functionality that the host provider cannot implement, such as dynamically populating a list that appears in the entry's details table from data on a server.

  • To control the interaction between properties in the host provider's entry and the original entry, such as computing the PR_EMAIL_ADDRESS (PidTagEmailAddress) from the values of the edit controls in the details display that contain different components of the address.

Notes to Implementers

When a host provider copies or creates an entry from your provider and you supply a property object implementation through IABLogon::OpenTemplateID, you handle most of the calls to maintain the entry. However, because it is up to the host provider to forward these calls to you, the host provider can intercept any call and perform custom processing before forwarding the call.

You should use the following guidelines in your property object implementations:

  • When IMAPIProp::GetProps is called, determine whether the request is for a computed property and, if it is, handle it. Transfer all requests for noncomputed properties to the host provider.

  • When IMAPIProp::OpenProperty is called to open any table except the details display table, handle the request. Most tables cannot be copied accurately to the host provider. You must generate the IMAPITable implementation for these requested tables. The details table PR_DETAILS_TABLE (PidTagDetailsTable) property must be copied to the host provider. This allows this provider to generate the table locally. You might want to wrap the display table implementation to generate display table notifications.

  • When IMAPIProp::SetProps is called, the host provider can validate the data before letting you set the properties. You can verify that all of the necessary properties were set or computed. If an error is detected, return the appropriate error value and, if you can, any additional explanation through IMAPIProp::GetLastError.

  • When IMAPIProp::SaveChanges is called, the host provider might want to perform processing before you save the entry. You should save any data that is affected by the changed properties, such as a new address, in the host provider's entry.

In general, make your implementation of the entry that you pass back to the host provider intercept all of the methods to perform context-specific manipulation of the relevant properties. If the FILL_ENTRY flag is passed in the ulTemplateFlags parameter, set all properties for the entry.

If you return a new property object in the lppMAPIPropNew parameter, call the IUnknown::AddRef method of the host provider's property object to maintain a reference. All calls through the bound object that the IMAPIProp implementation returned in lppMAPIPropNew should be routed to their corresponding method in the host property object after they are dealt with by the bound object.

The property identifiers of any named properties that are passed through your bound property object are in your provider's identifier namespace. Your implementation of the IMAPIProp::GetNamesFromIDs method should determine the names of the properties so that it can perform any template-specific tasks. Similarly, properties that your provider passes on to the host provider must also be in your namespace. For example, if you set a named property in OpenTemplateID, you should use one of your identifiers for the name—creating it, if necessary, by calling the IMAPIProp::GetIDsFromNames method.

If you do not recognize the entry identifier passed in lpTemplateID, return MAPI_E_UNKNOWN_ENTRYID.

For more information about how to work with address book template identifiers, see Acting as a Foreign Address Book Provider.

See also

Reference

IMAPISupport::OpenTemplateID
IPropData : IMAPIProp
PidTagTemplateid Canonical Property
IABLogon : IUnknown


IABLogon::PrepareRecips

 Copy code hover
[image]

IABLogon::PrepareRecips
See also Send feedback

Published: July 16, 2012

Prepares a recipient list for later use by the messaging system.

C++
HRESULT PrepareRecips(
  ULONG ulFlags,
  LPSPropTagArray lpPropTagArray,
  LPADRLIST lpRecipList
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the text in the returned strings. The following flag can be set:

MAPI_CACHE_ONLY

Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

lpPropTagArray

[in] A pointer to an SPropTagArray structure that contains an array of property tags that indicate the properties that require updating, if any. The lpPropTagArray parameter can be NULL.

lpRecipList

[in] A pointer to an ADRLIST structure that holds the recipient list.

Return value

S_OK

The recipient list was successfully prepared.

MAPI_E_NOT_FOUND

One or more of the recipients in the lpRecipList parameter do not exist.

Return value

A client calls the MAPI IAddrBook::PrepareRecips method to modify or rearrange a set of properties for one or more recipients. The recipients may or may not be part of the recipient list of an outgoing message. MAPI transfers this call to an address book provider's IABLogon::PrepareRecips method.

IABLogon::PrepareRecips performs four main tasks:

  • Ensures that all recipients in the address list pointed to by the lpRecipList parameter have a long-term entry identifier.

  • Ensures that all recipients have the properties specified in the property value array pointed to by the lpPropTagArray parameter.

  • Ensures that the properties from the property value array appear before any other properties that existed before the call.

  • Ensures that the order of the properties in each recipient's ADRENTRY structure in the ADRLIST structure is the same as in the property value array.

The ADRENTRY structure in the lpRecipList parameter contains one ADRENTRY structure for each recipient. Each ADRENTRY structure contains an array of SPropValue structures to describe the recipient's properties. When IABLogon::PrepareRecips returns, the SPropValue structure array for each recipient includes the properties from the lpPropTagArray followed by the other properties for the recipient.

Notes to Implementers

Implementing IABLogon::PrepareRecips involves putting properties in a specific order, retrieving property values, and converting short-term entry identifiers to long-term entry identifiers. The properties that are requested in the lpPropTagArray parameter must be at the start of the property value array associated with each recipient's ADRENTRY structure in the lpRecipList parameter. If values for these properties do not exist, open the associated messaging user or distribution list by using its entry identifier and retrieve the missing property values.

Allocate each SPropValue structure passed in lpRecipList separately so that the structures can be freed individually. If you must allocate additional space for any SPropValue structure, for example, to store the data for a string property, use the MAPIAllocateBuffer function to allocate additional space for the full property value array. Use the MAPIFreeBuffer function to free the original property value array, and then use the MAPIAllocateMore function to allocate any additional memory that is required.

To implement IABLogon::PrepareRecips, use the following procedure:

  1. Check for entries in the lpPropTagArray parameter. If the property value array is empty, there is no work to do. Return a success value.

  2. Process each recipient in the lpRecipList parameter. There is one ADRENTRY structure member for each recipient in the list. Ignore the following types of recipients:

    • Recipients without an entry identifier in the rgPropVals member of their ADRENTRY structure (that is, unresolved recipients).

    • Recipients with an entry identifier that does not belong to your provider. These recipients will be passed to another address book provider.

  3. Open the recipient and retrieve the properties that are already set for the recipient.

  4. Merge the property value array specified in the lpRecipList with the array of properties returned from GetProps. If the same property occurs in both property arrays, use the value from lpRecipList.

  5. If the lpRecipList property value array is big enough to hold all of the necessary properties, just replace it with the merged array. If the lpRecipList property value array is not big enough, replace it with a newly allocated array. Be sure the new array has an updated value in each of its cValues members.

  6. If you do not recognize one or more of the properties in the lpPropTagArray parameter, set the property type in the recipient's ADRENTRY structure to PT_ERROR and the property value either to MAPI_E_NOT_FOUND or to another value that gives a more specific reason for the unavailability of the property. For information about PT_ERROR, see Property Types.

Note Note

Never reallocate the ADRLIST structure that is passed into IABLogon::PrepareRecips or change its number of entries.

See also

Reference

ADRLIST
IMAPIProp::GetProps
PidTagEntryId Canonical Property
SPropValue
IABLogon : IUnknown


IABLogon::Unadvise

 Copy code hover
[image]

IABLogon::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels notifications that were previously set up with a call to the IABLogon::Advise method.

C++
HRESULT Unadvise(
  ULONG ulConnection
);

Parameters

ulConnection

[in] The connection number associated with an active notification registration. A previous call to Advise must have returned the value of ulConnection.

Return value

S_OK

The notification registration was successfully canceled.

Remarks

MAPI calls the Unadvise method to cancel a notification registration for a container, messaging user, or distribution list object.

Notes to Implementers

Your implementation of Unadvise will depend on whether you support notification with MAPI's help or manually. If MAPI provides your support, call the IMAPISupport::Unsubscribe method to cancel the registration. If another thread is in the process of calling the advise sink's IMAPIAdviseSink::OnNotify method, it can be delayed until OnNotify has returned.

For more information about the notification process, see Event Notification in MAPI. For information about how to use the IMAPISupport : IUnknown methods to support notification, see Supporting Event Notification.

See also

Reference

IABLogon::Advise
IMAPIAdviseSink::OnNotify
IABLogon : IUnknown


IABProvider : IUnknown

 Copy code hover
[image]

IABProvider : IUnknown
See also Send feedback

Published: July 16, 2012

Provides a method to log on to an address book provider object and a method to invalidate an address book provider object.

Header file: | Mapispi.h
Exposed by: | Address book provider objects
Implemented by: | Address book providers
Called by: | MAPI
Interface identifier: | IID_IABProvider
Pointer type: | LPABPROVIDER

Vtable Order

Logon | Establishes a connection to an active session.
Shutdown | Cancels a connection to an active session.

See also

Concepts

MAPI Interfaces


IABProvider::Logon

 Copy code hover
[image]

IABProvider::Logon
See also Send feedback

Published: July 16, 2012

Establishes a connection to an active session.

C++
HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG ulFlags,
  ULONG FAR * lpulcbSecurity,
  LPBYTE FAR * lppbSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPABLOGON FAR * lppABLogon
);

Parameters

lpMAPISup

[in] A pointer to the address book provider's support object.

ulUIParam

[in] A handle to the parent window for the logon dialog box that the Logon method displays, if permitted. The ulUIParam parameter contains the value of the parameter of the same name passed to MAPI in the previous call to the MAPILogonEx function.

lpszProfileName

[in] A pointer to the name of the session profile.

ulFlags

[in] A bitmask of flags that controls how the logon is performed. The following flags can be set:

AB_NO_DIALOG

The provider should not display a dialog box during logon. If this flag is not set, the provider can display a dialog box to prompt the user for missing configuration information.

MAPI_DEFERRED_ERRORS

Enables Logon to return successfully, possibly before the logon process is finished.

MAPI_UNICODE

All strings should be in Unicode format. If the MAPI_UNICODE flag is not set, the strings should be in ANSI format.

lpulcbSecurity

[in, out] A pointer to the size, in bytes, of the security credentials structure pointed to by the lppbSecurity parameter. On input, the value must be nonzero; on output, the value must be zero. In both cases, the pointers must be valid.

lppbSecurity

[in, out] A pointer to a pointer to security credentials. On input, the value must be nonzero; on output, the value must be zero. In both cases the pointer must be valid.

lppMAPIError

[out] A pointer to a pointer to a MAPIERROR structure. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppABLogon

[out] A pointer to a pointer to the provider's logon object.

Return value

S_OK

A connection to an active session was successfully established.

MAPI_E_FAILONEPROVIDER

The provider cannot log on, but MAPI can continue to log on the other providers in the message service to which the provider belongs.

MAPI_E_UNCONFIGURED

The provider has insufficient information to complete the logon. MAPI calls the provider's message service entry function.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the logon dialog box.

Remarks

Connections are established with each address book provider in the session profile when a client calls the IMAPISession::OpenAddressBook method. OpenAddressBook then calls each provider's Logon method.

The profile name pointed to by the lpszProfileName parameter is displayed in the character set of the user's client as indicated by the presence or absence of the MAPI_UNICODE flag in the ulFlags parameter.

Notes to Implementers

In your implementation of the Logon method, call the IMAPISupport::SetProviderUID method to register a unique identifier, or MAPIUID structure. Each of your objects will have an entry identifier that includes this MAPIUID. MAPI uses the MAPIUID to match an object with its provider. For example, when a client calls the IMAPISession::OpenEntry method to open a messaging user, OpenEntry examines the MAPIUID portion of the entry identifier that was passed in and matches it with a MAPIUID registered by an address book provider.

If a client logs on to your provider more than once, you may want to register a different MAPIUID for each logon. Registering unique MAPIUID structures enables MAPI to correctly route requests to the appropriate provider instance. However, you may want to have every logon object share one MAPIUID. In this case, you must be able to handle the routing yourself instead of relying on MAPI. For more information about how to create a MAPIUID, see Registering Service Provider Unique Identifiers.

The support object that MAPI passes to your Logon method in the lpMAPISup parameter provides access to many of the methods included in the IMAPISupport : IUnknown interface. MAPI creates a support object that is customized to your type of provider. For example, if you need to log on to an underlying messaging system or directory service when you establish your connection, you can call the IMAPISupport::OpenProfileSection method to retrieve security credentials for this particular logon session.

If Logon is successful, be sure that you call the support object's IUnknown::AddRef method to increment its reference count. This enables your provider to hold onto the support object pointer for the rest of the session. If you do not call this AddRef method, MAPI will unload your provider.

You can include the profile name passed in the lpszProfileName parameter in error dialog boxes, logon screens, or other user interfaces. To use the profile name, copy it to storage that you have allocated.

Create a logon object and return a pointer to it in the lppABLogon parameter. MAPI uses this logon object to make calls to the methods in your IABLogon implementation.

If you require a password during logon, display a logon dialog box only if the AB_NO_DIALOG flag is not set. If the user cancels the logon process, typically by clicking the Cancel button in the dialog box, return MAPI_E_USER_CANCEL from Logon.

Typically, when an address book provider cannot log on, MAPI disables the message service to which the failing provider belongs—that is, MAPI will not try to establish connections for any of the other providers that belong to the service for the rest of the session's lifetime. However, if your provider cannot establish a connection and you want not to disable the entire service, return either MAPI_E_FAILONEPROVIDER or MAPI_E_UNCONFIGURED. MAPI will not disable the message service to which the provider belongs.

Return MAPI_E_FAILONEPROVIDER if an error occurs that is not serious enough to prevent the other providers in the message service from establishing connections. Return MAPI_E_UNCONFIGURED if the necessary configuration information is missing from the profile and you cannot display a dialog box to prompt the user. MAPI will respond by calling your provider's message service entry point function with MSG_SERVICE_CONFIGURE set as the ulContext parameter to give the service a chance to configure itself, either programmatically or using a property sheet. When the message service entry point function has finished, MAPI retries the logon.

See also

Reference

IABLogon::Logoff
IABLogon::OpenEntry
IMAPISupport::OpenProfileSection
IMAPISupport::SetProviderUID
MSGSERVICEENTRY
IABProvider : IUnknown


IABProvider::Shutdown

 Copy code hover
[image]

IABProvider::Shutdown
See also Send feedback

Published: July 16, 2012

Cancels a connection to an active session.

C++
HRESULT Shutdown(
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[In] Reserved; must be a pointer to zero.

Return value

S_OK

The connection was successfully canceled.

Notes to Implementers

In your implementation of the Shutdown method, perform whatever tasks you consider necessary. MAPI calls your Shutdown method only after you have released all your logon objects.

See also

Reference

IABProvider : IUnknown


IAddrBook : IMAPIProp

 Copy code hover
[image]

IAddrBook : IMAPIProp
See also Send feedback

Published: July 16, 2012

Supports access to the MAPI address book and includes operations such as displaying common dialog boxes; opening containers, messaging users, and distribution lists; and performing name resolution.

Header file: | Mapix.h
Exposed by: | Address book objects
Implemented by: | MAPI
Called by: | Client applications, service providers
Interface identifier: | IID_IAddrBook
Pointer type: | LPADRBOOK
Transaction model: | Not writable

Vtable Order

OpenEntry | Opens an address book entry and returns a pointer to an interface that can be used to access the entry.
CompareEntryIDs | Compares two entry identifiers that belong to a particular address book provider to determine whether they refer to the same address book object.
Advise | Registers a client or service provider to receive notifications about changes to one or more entries in the address book.
Unadvise | Cancels a notification registration previously established for an address book entry.
CreateOneOff | Creates an entry identifier for a one-off address.
NewEntry | Adds a new recipient to an address book container or to the recipient list of an outgoing message.
ResolveName | Performs name resolution, assigning entry identifiers to recipients in a recipient list.
Address | Displays the Outlook address book dialog box.
Details | Displays a dialog box that shows details about a particular address book entry.
RecipOptions | Not supported or documented.
QueryDefaultRecipOpt | Not supported or documented.
GetPAB | Returns the entry identifier of the container that is designated as the personal address book (PAB).
SetPAB | Designates a particular container as the personal address book (PAB).
GetDefaultDir | Returns the entry identifier for the initial address book container.
SetDefaultDir | Establishes the specified container as the default address book container that is initially made available.
GetSearchPath | Returns an ordered list of entry identifiers of the containers to be included in the name resolution process initiated by the ResolveName method.
SetSearchPath | Sets a new search path in the profile that is used for the name resolution process.
PrepareRecips | Prepares a recipient list for later use by the messaging system.

See also

Concepts

MAPI Interfaces


IAddrBook::Address

 Copy code hover
[image]

IAddrBook::Address
See also Send feedback

Published: July 16, 2012

Displays the Outlook address book dialog box.

C++
HRESULT Address(
  ULONG_PTR FAR * lpulUIParam,
  LPADRPARM lpAdrParms,
  LPADRLIST FAR * lppAdrList
);

Parameters

lpulUIParam

[in, out] A pointer to a handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the ulFlags member of the lpAdrParms parameter is set to DIALOG_SDI, the window handle of the modeless dialog box is returned. See Remarks.

lpAdrParms

[in, out] A pointer to an ADRPARM structure that controls the presentation and behavior of the address dialog box.

lppAdrList

[in, out] A pointer to a pointer to an ADRLIST structure that contains recipient information. On input, this parameter can be NULL or point to a valid pointer. On output, this parameter points to a pointer to valid recipient information.

Return value

S_OK

The common address dialog box was successfully displayed.

Remarks

If the ulFlags member of the lpAdrParms parameter is set to DIALOG_SDI anticipating the return of the window handle of the modeless dialog box on output, it is ignored in Outlook; the modal version of the dialog is always shown in non-Outlook clients.

The ADRLIST structure passed back by MAPI to the caller through the lppAdrList parameter contains an array of ADRENTRY structures, one structure for each recipient. When passed to an outgoing message's IMessage::ModifyRecipients method in the lpMods parameter, the ADRLIST structure can be used to update its recipient list.

Each ADRENTRY structure in the ADRLIST structure contains zero or more SPropValue structures, one structure for every property set for the recipient. There can be zero SPropValue structures when the dialog box presented by the Address method is used to remove a recipient. When there are one or more SPropValue structures, the corresponding ADRENTRY structure is used to add or update a recipient. The recipient can be resolved, which indicates that one of the SPropValue structures describes the recipient's PR_ENTRYID (PidTagEntryId) property, or unresolved, which indicates that the PR_ENTRYID property is missing.

In addition to PR_ENTRYID, resolved recipients include the following properties:

  • PR_RECIPIENT_TYPE (PidTagRecipientType)

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_DISPLAY_TYPE (PidTagDisplayType)

The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. If MAPI must return a larger ADRLIST structure, it frees the original structure and allocates a new one. When you allocate memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately. For more information about how to allocate and free ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures

Address returns immediately if the DIALOG_SDI flag is set in the ulFlags member of the ADRPARM structure in the lpAdrParms parameter. The DIALOG_SDI flag is ignored for non-Outlook clients. If DIALOG_SDI is ignored, the modal version of the dialog will be displayed and a pointer to a handle should not be expected in lpulUIParam.

Address supports Unicode character strings in the ADRPARM structure if AB_UNICODEUI was specified in the ulFlags member of ADRPARM in the lpAdrParms parameter, and it supports Unicode character strings in ADRLIST. The Unicode strings are converted to the multibyte character string (MBCS) format before they are displayed in the Outlook address book dialog box.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIStoreFunctions.cpp | OpenOtherUsersMailboxFromGal | MFCMAPI uses the Address method to allow the user to select which mailbox to open.

See also

Reference

ADRENTRY
ADRLIST
ADRPARM
FreePadrlist
FreeProws
IMAPITable::QueryRows
IMessage::ModifyRecipients
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
SPropValue
SRowSet
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample
MFCMAPI as a Code Sample


IAddrBook::Advise

 Copy code hover
[image]

IAddrBook::Advise
See also Send feedback

Published: July 16, 2012

Registers a client or service provider to receive notifications about changes to one or more entries in the address book.

C++
HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG_PTR lpulConnection
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the address book container, messaging user, or distribution list that will generate a notification when a change occurs of the type or types described in the ulEventMask parameter.

ulEventMask

[in] One or more notification events that the caller is registering to receive. Each event is associated with a particular notification structure that contains information about the change that occurred. The following table lists the valid values for ulEventMask and their corresponding structures.

Notification event

Corresponding structure

fnevCriticalError

ERROR_NOTIFICATION

fnevObjectCreated

OBJECT_NOTIFICATION

fnevObjectDeleted

OBJECT_NOTIFICATION

fnevObjectModified

OBJECT_NOTIFICATION

fnevObjectCopied

OBJECT_NOTIFICATION

fnevObjectMoved

OBJECT_NOTIFICATION

fnevTableModified

TABLE_NOTIFICATION

lpAdviseSink

[in] A pointer to the advise sink object to be called when the event for which notification has been requested occurs.

lpulConnection

[out] A pointer to a nonzero connection number that represents the notification registration.

Return value

S_OK

The notification registration was successful.

MAPI_E_INVALID_ENTRYID

The address book provider responsible for the entry identifier passed in lpEntryID could not register a notification for the corresponding entry.

MAPI_E_NO_SUPPORT

Notification is not supported by the address book provider responsible for the object identified by the entry identifier passed in the lpEntryID parameter.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in lpEntryID cannot be handled by any of the address book providers in the profile.

Remarks

Clients and service providers call the Advise method to register for a particular type or types of notification on an address book entry. The types of notification are indicated by the event mask passed in with the ulEventMask parameter.

MAPI forwards this Advise call to the address book provider that is responsible for the entry as indicated by the entry identifier in the lpEntryID parameter. The address book provider either handles the registration itself or calls the support method, IMAPISupport::Subscribe, to prompt MAPI to register the caller. A nonzero connection number is returned to represent the successful registration.

Whenever a change occurs to the entry of the type indicated by the notification registration, the address book provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object specified in the lpAdviseSink parameter. The OnNotify method includes a NOTIFICATION structure as an input parameter that contains data to describe the event.

Depending on the address book provider, the call to OnNotify can occur immediately following the change to the registered object or at a later time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. Clients can request that these notifications occur on a particular thread by calling the HrThisThreadAdviseSink function to create the advise sink object that is passed to Advise.

Because an address book provider can release the advise sink object passed in by clients at any time after the successful completion of the Advise call and before an IAddrBook::Unadvise call to cancel the notification, clients should release their advise sink objects when Advise returns.

For more information about the notification process, see Event Notification in MAPI.

See also

Reference

HrThisThreadAdviseSink
IAddrBook::Unadvise
IMAPIAdviseSink::OnNotify
NOTIFICATION
IAddrBook : IMAPIProp


IAddrBook::CompareEntryIDs

 Copy code hover
[image]

IAddrBook::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers that belong to a particular address book provider to determine whether they refer to the same address book object.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The byte count in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The byte count in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the result of the comparison. The contents of lpulResult are set to TRUE if the two entry identifiers refer to the same object; otherwise, the contents are set to FALSE.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers passed in with the lpEntryID1 or lpEntryID2 parameters are not recognized by any address book provider.

Remarks

Client applications and service providers call the CompareEntryIDs method to compare two entry identifiers that belongs to a single address book provider to determine whether they refer to the same object. CompareEntryIDs is useful because an object can have more than one valid entry identifier. This situation can occur, for example, after a new version of an address book provider is installed.

MAPI passes this call to the address book provider that is responsible for the entry identifiers, determining the appropriate provider by matching the MAPIUID structure in the entry identifiers with the MAPIUID structure registered by the provider.

If the two entry identifiers refer to the same object, CompareEntryIDs sets the contents of the lpulResult parameter to TRUE; if they refer to different objects, CompareEntryIDs sets the contents to FALSE. In either case, CompareEntryIDs returns S_OK. If CompareEntryIDs returns an error, which can occur if no address book provider has registered a MAPIUID structure that matches the one in the entry identifiers, clients and providers should not take any action based on the result of the comparison. They should instead take the most conservative approach to the action being performed.

See also

Reference

IAddrBook : IMAPIProp


IAddrBook::CreateOneOff

 Copy code hover
[image]

IAddrBook::CreateOneOff
See also Send feedback

Published: July 16, 2012

Creates an entry identifier for a one-off address.

C++
HRESULT CreateOneOff(
  LPSTR lpszName,
  LPSTR lpszAdrType,
  LPSTR lpszAddress,
  ULONG ulFlags,
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpszName

[in] A pointer to the value of the recipient's PR_DISPLAY_NAME (PidTagDisplayName) property. The lpszName parameter can be NULL.

lpszAdrType

[in] A pointer to the address type of the recipient, such as FAX or SMTP. The lpszAdrType parameter cannot be NULL.

lpszAddress

[in] A pointer to the address of the recipient. The lpszAddress parameter cannot be NULL.

ulFlags

[in] A bitmask of flags that affects the one-off recipient. The following flags can be set:

MAPI_SEND_NO_RICH_INFO

The recipient cannot handle formatted message content. If MAPI_SEND_NO_RICH_INFO is set, MAPI sets the recipient's PR_SEND_RICH_INFO (PidTagSendRichInfo) property to FALSE. If MAPI_SEND_NO_RICH_INFO is not set, MAPI sets this property to TRUE unless the recipient's messaging address pointed to by lpszAddress is interpreted to be an Internet address. In this case, MAPI sets PR_SEND_RICH_INFO to FALSE.

MAPI_UNICODE

The display name, address type, and address are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

lpcbEntryID

[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier for the one-off recipient.

Return value

S_OK

The one-off entry identifier was created successfully.

Remarks

Clients call the CreateOneOff method to create an entry identifier for a one-off recipient — a recipient that does not belong to any of the containers from any of the currently loaded address book providers. One-off recipients can have any kind of address that is supported by one of the active address book providers for the session.

One-off recipients are typically created with a template for their particular address type. The address book provider that supports the address type supplies the template. A user of a client application enters the relevant information into the template.

MAPI supports Unicode character strings for the display name, address type, and address parameters of CreateOneOff.

The MAPI_SEND_NO_RICH_INFO flag controls whether formatted text in Rich Text Format (RTF) is sent along with each message. The Transport Neutral Encapsulation Format (TNEF) — a format that is used for transmitting formatted text — is sent by most transport providers, regardless of how the recipient sets its PR_SEND_RICH_INFO property. This is not an issue for messaging clients that work with interpersonal messages. However, because TNEF is typically used to send custom properties for custom message classes, not supporting it can be a problem for form-based clients or clients that require custom MAPI properties. For more information, see Sending Messages with TNEF.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
Mapiabfunctions.cpp | AddOneOffAddress | MFCMAPI uses the CreateOneOff method to create an entry ID for an address that is not found in any address book.

See also

Reference

IMAPISupport::CreateOneOff
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::Details

 Copy code hover
[image]

IAddrBook::Details
See also Send feedback

Published: July 16, 2012

Displays a dialog box that shows details about a particular address book entry.

C++
HRESULT Details(
  ULONG_PTR FAR * lpulUIParam,
  LPFNDISMISS lpfnDismiss,
  LPVOID lpvDismissContext,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPFNBUTTON lpfButtonCallback,
  LPVOID lpvButtonContext,
  LPSTR lpszButtonText,
  ULONG ulFlags
);

Parameters

lpulUIParam

[in] A pointer to a handle of the parent window for the dialog box.

lpfnDismiss

[in] A pointer to a function based on the DISMISSMODELESS prototype, or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client that is calling Details that the dialog box is no longer active.

lpvDismissContext

[in] A pointer to context information to pass to the DISMISSMODELESS function pointed to by the lpfnDismiss parameter. This parameter applies only to the modeless version of the dialog box, by including the DIALOG_SDI flag in the ulFlags parameter.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for the entry for which details are displayed.

lpfButtonCallback

[in] A pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] A pointer to data that was used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] A pointer to a string that contains text to be applied to the added button, if that button is extensible. The lpszButtonText parameter should be NULL if you do not need an extensible button.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flags can be set:

AB_TELL_DETAILS_CHANGE

Indicates that Details returns S_OK if changes are actually made to the address; otherwise, Details returns S_FALSE.

DIALOG_MODAL

Display the modal version of the common address dialog box, which is always shown in non-Outlook clients. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Display the modeless version of the common address dialog box. This flag is ignored for non-Outlook clients.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Return value

S_OK

The details dialog box was successfully displayed for the address book entry.

Remarks

Client applications call the Details method to display a dialog box that provides details about a particular entry in the address book. You can use the lpfButtonCallback, lpvButtonContext, and lpszButtonText parameters to add a client-defined button to the dialog box. When the button is clicked, MAPI calls the callback function pointed to by lpfButtonCallback, passing both the entry identifier of the button and the data in lpvButtonContext. If you do not need an extensible button, lpszButtonText should be NULL.

Details supports Unicode character strings; Unicode strings are converted to the multibyte character string (MBCS) format before they are displayed in the details dialog box.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
BaseDialog.cpp | CBaseDialog::OnOpenEntryID | MFCMAPI uses the Details method to display a dialog box that shows the details for an address book entry.

See also

Reference

ADRPARM
IAddrBook::Address
LPFNBUTTON
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::GetDefaultDir

 Copy code hover
[image]

IAddrBook::GetDefaultDir
See also Send feedback

Published: July 16, 2012

Returns the entry identifier for the initial address book container.

C++
HRESULT GetDefaultDir(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpcbEntryID

[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier of the default container.

Return value

S_OK

The entry identifier of the default container was successfully returned.

Remarks

Client applications and service providers call the GetDefaultDir method to retrieve the entry identifier of the default address book container. The default container is what the user sees displayed in the address book when the address book is first opened. If a default container has not been set by a call to the IAddrBook::SetDefaultDir method, MAPI assigns as the default container the first container with names that is not the personal address book (PAB). If such a container cannot be found, the PAB becomes the default container.

To set the default directory, a client or provider calls the SetDefaultDir method. Clients and providers do not have to call the IMAPIProp::SaveChanges method; because changes to the address book are not transacted, changes are immediately made permanent.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnOpenDefaultDir | MFCMAPI uses the GetDefaultDir method to get the ID for the default address book container.

See also

Reference

IAddrBook::SetDefaultDir
MAPIAllocateBuffer
MAPIFreeBuffer
PidTagContainerFlags Canonical Property
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::GetPAB

 Copy code hover
[image]

IAddrBook::GetPAB
See also Send feedback

Published: July 16, 2012

Returns the entry identifier of the container that is designated as the personal address book (PAB).

C++
HRESULT GetPAB(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpcbEntryID

[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier of the PAB. The lppEntryID parameter contains zero if no container has been designated as the PAB.

Return value

S_OK

The entry identifier of the PAB was successfully returned.

Remarks

Clients call the GetPAB method to retrieve the entry identifier of the container designated as the PAB. If a PAB has not been established in the profile, MAPI selects as the PAB the first container in the address book hierarchy that allows modifications.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnOpenPAB | MFCMAPI uses the GetPAB method to get the ID for the user's personal address book.

See also

Reference

MAPIAllocateBuffer
MAPIFreeBuffer
PidTagContainerFlags Canonical Property
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::GetSearchPath

 Copy code hover
[image]

IAddrBook::GetSearchPath
See also Send feedback

Published: July 16, 2012

Returns an ordered list of entry identifiers of the containers to be included in the name resolution process initiated by the IAddrBook::ResolveName method.

C++
HRESULT GetSearchPath(
  ULONG ulFlags,
  LPSRowSet FAR * lppSearchPath
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the strings returned in the search path. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppSearchPath

[out] A pointer to a pointer to an ordered list of container entry identifiers. GetSearchPath stores the ordered list in an SRowSet structure. If there are no containers in the address book hierarchy, zero is returned in the SRowSet structure.

Return value

S_OK

The search path was successfully retrieved.

Remarks

Clients and service providers call the GetSearchPath method to get the search path that is used to resolve names with the ResolveName method. Typically, clients call the IAddrBook::SetSearchPath method to establish a container search path in the profile before they call GetSearchPath to retrieve it. However, calling SetSearchPath is optional.

If SetSearchPath has never been called, GetSearchPath builds a path by working through the address book's hierarchy tables. The default search path established by GetSearchPath consists of the following containers in the following order:

  1. The first container with read/write permission, usually the personal address book (PAB).

  2. Every container that has its PR_DISPLAY_TYPE (PidTagDisplayType) property set to DT_GLOBAL. This setting indicates that the container holds recipients.

  3. The container designated as the default, if there are no containers that have the DT_GLOBAL flag set in their PR_DISPLAY_TYPE property and the default container differs from the first container with read/write permission.

If SetSearchPath has been called, GetSearchPath builds a path by using the address book containers that have been stored in the profile. GetSearchPath validates this path before it returns it to the caller.

After the first call to SetSearchPath, subsequent calls to SetSearchPath must be used to modify the search path returned by GetSearchPath. In other words, the calling client or provider does not receive the default search path after the first call to SetSearchPath.

See also

Reference

IAddrBook::SetSearchPath
SRowSet
IAddrBook : IMAPIProp


IAddrBook::NewEntry

 Copy code hover
[image]

IAddrBook::NewEntry
See also Send feedback

Published: July 16, 2012

Adds a new recipient to an address book container or to the recipient list of an outgoing message.

C++
HRESULT NewEntry(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG cbEIDContainer,
  LPENTRYID lpEIDContainer,
  ULONG cbEIDNewEntryTpl,
  LPENTRYID lpEIDNewEntryTpl,
  ULONG FAR * lpcbEIDNewEntry,
  LPENTRYID FAR * lppEIDNewEntry
);

Parameters

ulUIParam

[in] A handle to the parent window for the dialog box.

ulFlags

[in] A bitmask of flags that controls the type of the text that is used. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

cbEIDContainer

[in] The byte count in the entry identifier pointed to by the lpEIDContainer parameter.

lpEIDContainer

[in] A pointer to the entry identifier of the container where the new recipient is to be added. If the cbEIDContainer parameter is zero, the NewEntry method returns a recipient entry identifier and a list of templates as if the IAddrBook::CreateOneOff method was called.

cbEIDNewEntryTpl

[in] The byte count in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.

lpEIDNewEntryTpl

[in] A pointer to a one-off template that will be used to create the new recipient. If cbEIDNewEntryTpl is zero and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box with which the user can select from a list of templates for adding new entries.

lpcbEIDNewEntry

[out] A pointer to the byte count in the entry identifier pointed to by the lppEIDNewEntry parameter.

lppEIDNewEntry

[out] A pointer to a pointer to the new recipient's entry identifier.

Return value

S_OK

The new address book entry was successfully created.

Remarks

The NewEntry method creates a new address book entry, to be added directly into a container or to be used to address an outgoing message.

Notes to Callers

If you want the new entry to be added to a specific container, set lpEIDContainer to the container's entry identifier and cbEIDContainer to the byte count in the entry identifier.

If you want the new entry to be added to the recipient list of an outgoing message, set lpEIDContainer to NULL and cbEIDContainer to zero.

If you want to allow the user of a client application to select the type of entry to be created, pass zero in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. The NewEntry method displays the MAPI one-off table, a list of templates supported by MAPI and by each address book provider in the session. Each template can create a recipient entry for one or more address types.

If you want to retain the entry identifier of the new entry, pass valid pointers in the lpcbEIDNewEntry and lppEIDNewEntry parameters. You are responsible for freeing this entry identifier when you are finished with it by calling the MAPIFreeBuffer function.

To use a particular template to add a new entry to a modifiable container, use the following procedure:

  1. Call the IMAPISession::OpenEntry method to open the destination container, and set the lpEntryID parameter to the entry identifier of the container.

  2. Call the destination container's IMAPIProp::OpenProperty method, and set the ulPropTag parameter to PR_CREATE_TEMPLATES (PidTagCreateTemplates) and the lpiid parameter to IID_IMAPITable. The container will return a one-off table that lists all the templates that it supports for creating new entries.

  3. Retrieve the row that represents the template for the particular type of entry you want to create. The PR_ADDRTYPE (PidTagAddressType) column indicates the address type that is supported by the template.

  4. Call the NewEntry method, and set lpEIDNewEntryTpl to the entry identifier of the selected template. The entry identifier will be the PR_ENTRYID (PidTagEntryId) column from the template's row in the one-off table. Pass zero in cbEIDContainer and NULL in lpEIDContainer. Pass a valid pointer in the lppEIDNewEntry parameter if you want to retain the new entry's entry identifier.

See also

Reference

IAddrBook::OpenEntry
IMAPIProp::OpenProperty
PidTagCreateTemplates Canonical Property
IAddrBook : IMAPIProp


IAddrBook::OpenEntry

 Copy code hover
[image]

IAddrBook::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens an address book entry and returns a pointer to an interface that can be used to access the entry.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface to be used to access the open entry. Passing NULL returns the object's standard interface. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists, it is IDistList : IMAPIContainer and for containers, it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls how the entry is opened. The following flags can be set.

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read/write permission, the address book provider should attempt to open the entry with read/write permission. The client can retrieve the access level that was granted by calling the open entry's IMAPIProp::GetProps method and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_CACHE_ONLY

Opens an address book entry and accesses it only from the cache. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange address book provider.

MAPI_DEFERRED_ERRORS

Allows the call to succeed, potentially before the entry is fully open and available, implying that later calls to the entry might return an error.

MAPI_GAL_ONLY

Use only the GAL to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

Note Note

The ulFlags MAPI_GAL_ONLY might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following value:

#define MAPI_GAL_ONLY (0x00000080)

MAPI_MODIFY

Requests that the entry be opened with read/write permission. Because entries are opened with read-only access by default, clients should not assume that read/write permission was granted regardless of whether MAPI_MODIFY is set.

MAPI_NO_CACHE

Do not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer to the opened entry.

Return value

S_OK

The entry was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to open an entry for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The entry represented by lpEntryID does not exist.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier specified in lpEntryID is not recognized. This value is typically returned if the address book provider responsible for the corresponding entry is not open.

Remarks

Clients and service providers call the IAddrBook::OpenEntry method to open an address book entry. MAPI forwards the call to the appropriate address book provider, based on the MAPIUID structure included in the entry identifier passed in the lpEntryID parameter. The address book provider opens the entry as read-only unless the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter is set. However, these flags are suggestions. If the address book provider does not allow modification for the entry requested, it returns MAPI_E_NO_ACCESS.

The lpInterface parameter indicates which interface should be used to access the opened entry. Passing NULL in lpInterface indicates the standard MAPI interface for that type of entry should be used. Because the address book provider might return a different interface than the one suggested by the lpInterface parameter, the caller should check the value returned in the lpulObjType parameter to determine whether the object type returned is what was expected. If the object type is not of the type expected, the caller can cast the lppUnk parameter to a type that is more appropriate.

See also

Reference

IAddrBook : IMAPIProp


IAddrBook::PrepareRecips

 Copy code hover
[image]

IAddrBook::PrepareRecips
See also Send feedback

Published: July 16, 2012

Prepares a recipient list for later use by the messaging system.

C++
HRESULT PrepareRecips(
  ULONG ulFlags,
  LPSPropTagArray lpSPropTagArray,
  LPADRLIST lpRecipList
);

Parameters

ulFlags

[in] A bitmask of flags that controls how the entry is opened. The following flag can be set:

MAPI_CACHE_ONLY

Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and to access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

lpSPropTagArray

[in] A pointer to an SPropTagArray structure that contains an array of property tags that indicate the properties, if any, that require updating. The lpSPropTagArray parameter can be NULL.

lpRecipList

[in] A pointer to an ADRLIST structure that contains the list of recipients.

Return value

S_OK

The recipient list was successfully prepared.

Remarks

Clients and service providers call the PrepareRecips method to do the following:

  • Ensure that all recipients in the lpRecipList parameter have long-term entry identifiers.

  • Ensure that each recipient in the lpRecipList parameter has the properties listed in the lpSPropTagArray parameter and that these properties appear at the start of the recipient list.

MAPI converts each recipient's short-term entry identifiers to long-term entry identifiers. If necessary, recipients' long-term entry identifiers are retrieved from the appropriate address book provider and any additional properties are requested.

In an individual recipient entry, the requested properties are ordered first, followed by any properties that were already present for the entry. If one or more of the requested properties in the lpSPropTagArray parameter are not handled by the appropriate address book provider, their property types will be set to PT_ERROR. Their property values will be set to either to MAPI_E_NOT_FOUND or to another value that gives a more specific reason why the properties are not available. Each SPropValue structure included in the lpRecipList parameter must be separately allocated by using the MAPIAllocateBuffer and MAPIAllocateMore functions so that it can be freed individually.

For information about PT_ERROR, see Property Types.

See also

Reference

ADRLIST
IMAPIProp::GetProps
IMessage::ModifyRecipients
PidTagEntryId Canonical Property
SPropValue
SRowSet
IAddrBook : IMAPIProp


IAddrBook::ResolveName

 Copy code hover
[image]

IAddrBook::ResolveName
See also Send feedback

Published: July 16, 2012

Performs name resolution, assigning entry identifiers to recipients in a recipient list.

C++
HRESULT ResolveName(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPSTR lpszNewEntryTitle,
  LPADRLIST lpAdrList
);

Parameters

ulUIParam

[in] A handle to the parent window of a dialog box that is shown, if specified, to prompt the user to resolve ambiguity.

ulFlags

[in] A bitmask of flags that control various aspects of the resolution process. The following flags can be set:

AB_UNICODEUI

Indicates that lpszNewEntryTitle is a UNICODE string.

MAPI_CACHE_ONLY

Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_DIALOG

Displays a dialog box to prompt the user for additional name resolution information. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

Indicates that the properties returned in the address list should be of type PT_UNICODE instead of PT_STRING8.

lpszNewEntryTitle

[in] A pointer to text for the title of the control in the dialog box that prompts the user to enter a recipient. The title varies depending on the type of recipient. The lpszNewEntryTitle parameter can be NULL.

lpAdrList

[in-out] A pointer to an ADRLIST structure that contains the list of recipient names to be resolved. This ADRLIST structure can be created by the IAddrBook::Address method.

Return value

S_OK

The name resolution process succeeded.

MAPI_E_AMBIGUOUS_RECIP

At least one recipient in the lpAdrList parameter matched more than one entry in the address book. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.

MAPI_E_NOT_FOUND

At least one recipient in the lpAdrList parameter cannot be resolved. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.

Remarks

Clients and service providers call the ResolveName method to initiate the name resolution process. An unresolved entry is an entry that does not yet have an entry identifier or PR_ENTRYID (PidTagEntryId) property.

ResolveName goes through the following process for each unresolved entry in the address list passed in the lpAdrList parameter.

  1. If the address type of the recipient adheres to the format of an SMTP address (displayname@domain.top-level-domain), ResolveName assigns it a one-off entry identifier.

  2. For each container in the PR_AB_SEARCH_PATH (PidTagAbSearchPath) property, ResolveName calls the IABContainer::ResolveNames method. ResolveNames tries to match the display name of each unresolved recipient with a display name that belongs to one of its entries.

  3. If a container does not support ResolveNames, ResolveName restricts the container's contents table by using a PR_ANR (PidTagAnr) property restriction. This restriction causes the container to perform a "best guess" type of search to locate a matching recipient. All containers must support the PR_ANR property restriction.

  4. When a container returns a recipient that matches multiple names, ResolveName displays a dialog box if the MAPI_DIALOG flag is set, which lets the user select the correct name.

  5. If all of the containers in the PR_AB_SEARCH_PATH property have been called and no match has been found, the recipient remains unresolved.

If one or more recipients are unresolved, ResolveName returns MAPI_E_NOT_FOUND. If one or more recipients had ambiguous resolution that could not be resolved with a dialog box, or because the MAPI_DIALOG flag was not set, ResolveName returns MAPI_E_AMBIGUOUS_RECIP. When some of the recipients are ambiguous and some cannot be resolved, ResolveName can return either error value.

If a name cannot be resolved, the client can create a one-off address that has a specially formatted address and entry identifier. For more information about the format of one-off entry identifiers, see One-Off Entry Identifiers. For more information about the format of one-off addresses, see One-Off Addresses.

MAPI supports Unicode character strings for the ADRLIST and the new entry title parameters to ResolveName; if you set the MAPI_UNICODE flag, the following properties are returned as type PT_UNICODE in the ADRENTRY structures:

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_EMAIL_ADDRESS (PidTagEmailAddress)

  • PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)

However, the PR_7BIT_DISPLAY_NAME (PidTag7BitDisplayName) property is always returned as type PT_STRING8.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIABFunctions.cpp | AddOneOffAddress | MFCMAPI uses the ResolveName method to resolve a one-off address before adding it to a message.
MAPIABFunctions.cpp | AddRecipient | MFCMAPI uses the ResolveName method to look up an address book entry by display name.

See also

Reference

ADRLIST
IABContainer::ResolveNames
IAddrBook::Address
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::SetDefaultDir

 Copy code hover
[image]

IAddrBook::SetDefaultDir
See also Send feedback

Published: July 16, 2012

Establishes the specified container as the default address book container.

C++
HRESULT SetDefaultDir(
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the default address book container.

Return value

S_OK

The default address book container was successfully set.

Remarks

Clients and service providers call the SetDefaultDir method to establish a new default address book container. The default container is the container that the user sees displayed in the address book when the address book is first opened. SetDefaultDir saves the default container as an entry in the profile. The container remains as the default until either another call to SetDefaultDir is made in the same session or in another session, or the container is removed.

Note Note

The PR_AB_CHOOSE_DIRECTORY_AUTOMATICALLY property corresponds to the Choose automatically setting in the Address Book Options dialog. When this property exists in the IID_CAPONE_PROF profile section and is set to true, the Address Book dialog no longer defaults to the container specified by SetDefaultDir, but chooses an address book that Microsoft Outlook considers appropriate for the context in which the dialog was displayed. Note that this may result in a poor experience for third-party address book providers.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
Abcontdlg.cpp | CAbContDlg::OnSetDefaultDir | MFCMAPI uses the SetDefaultDir method to make the specified address book container the default one.

See also

Reference

IAddrBook::GetDefaultDir
IAddrBook::GetSearchPath
IMAPISession::Logoff
MAPILogonEx
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::SetPAB

 Copy code hover
[image]

IAddrBook::SetPAB
See also Send feedback

Published: July 16, 2012

Designates a particular container as the personal address book (PAB).

C++
HRESULT SetPAB(
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the container to be designated as the PAB. The lpEntryID parameter cannot be NULL.

Return value

S_OK

The specified container has been established as the PAB.

Remarks

Clients and service providers call the SetPAB method to designate a particular container as the PAB. The PAB is a container that consists of entries copied from other containers as well as new entries.

A call to SetPAB establishes a container as the PAB until that container is made unavailable or a new container becomes the PAB through a subsequent call to SetPAB .

Clients and providers do not have to call the IMAPIProp::SaveChanges method to make the PAB change permanent.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
AbContDlg.cpp | CAbContDlg::OnSetPAB | MFCMAPI uses the SetPAB method to make the specified container the PAB.

See also

Reference

IAddrBook::GetPAB
IAddrBook::GetSearchPath
PidTagContainerFlags Canonical Property
IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IAddrBook::SetSearchPath

 Copy code hover
[image]

IAddrBook::SetSearchPath
See also Send feedback

Published: July 16, 2012

Sets a new search path in the profile that is used for the name resolution process.

C++
HRESULT SetSearchPath(
  ULONG ulFlags,
  LPSRowSet lpSearchPath
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpSearchPath

[in] A pointer to the SRowSet structure used to hold the search path. The first property for each aRow member in SRowSet must be PR_ENTRYID (PidTagEntryId).

Return value

S_OK

The search path was successfully set.

MAPI_E_MISSING_REQUIRED_COLUMN

One of the containers described in the SRowSet structure did not include its PR_ENTRYID property.

Remarks

Clients and service providers call the SetSearchPath method to save changes that were made to the container search order that is used to resolve names with the IAddrBook::ResolveName method. The search path is saved between instances of a session.

Clients and providers do not have to call the IMAPIProp::SaveChanges method to make the search path changes permanent.

See also

Reference

IAddrBook::GetDefaultDir
IAddrBook::GetPAB
IAddrBook::GetSearchPath
PidTagContainerFlags Canonical Property
IAddrBook : IMAPIProp


IAddrBook::Unadvise

 Copy code hover
[image]

IAddrBook::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels a notification registration previously established for an address book entry.

C++
HRESULT Unadvise(
  ULONG_PTR ulConnection
);

Parameters

ulConnection

[in] A connection number that represents the registration to be canceled. The ulConnection parameter should contain a value returned by a prior call to the IAddrBook::Advise method.

Return value

S_OK

The registration was successfully canceled.

Remarks

Clients call the Unadvise method to stop receiving notifications about changes to a particular address book entry. When a notification registration is canceled, the address book provider releases its pointer to the caller's advise sink. However, the release can occur during the Unadvise call or at some later point, if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method. When a notification is in progress, the release is delayed until the OnNotify method returns.

See also

Reference

IAddrBook::Advise
IMAPIAdviseSink::OnNotify
IAddrBook : IMAPIProp


IAttach : IMAPIProp

 Copy code hover
[image]

IAttach : IMAPIProp
See also Send feedback

Published: July 16, 2012

Maintains and provides access to the properties of attachments in messages. The IAttach interface has no unique methods of its own. For more information about how to use attachments, see MAPI Attachments and Attachment Tables.

Header file: | Mapidefs.h
Exposed by: | Attachment objects
Implemented by: | Message store providers
Called by: | Client applications
Interface identifier: | IID_IAttachment
Pointer type: | LPATTACH
Transaction model: | Transacted

Vtable Order

This interface does not have any unique methods.

Required properties | Access
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_ATTACH_METHOD (PidTagAttachMethod) | Read/write
PR_RENDERING_POSITION (PidTagRenderingPosition) | Read/write

See also

Concepts

MAPI Interfaces


IAttachmentSecurity : IUnknown

 Copy code hover
[image]

IAttachmentSecurity : IUnknown
See also Send feedback

Published: July 16, 2012

Allows Microsoft Outlook 2010 and Microsoft Outlook 2013 solutions to find out if an attachment is considered unsafe and blocked for viewing and indexing.

Interface identifier:

IID_IAttachmentSecurity

Vtable Order

IAttachmentSecurity::IsAttachmentBlocked

Checks if a specified attachment is blocked by Outlook 2010 or Outlook 2013 for viewing and indexing.

Remarks

Outlook 2010 and Outlook 2013 solutions can query this interface to see if an attachment is blocked. The attachments that are blocked by Outlook 2010 or Outlook 2013 vary depending on how Outlook 2010 or Outlook 2013 has been configured and the policies that an administrator has applied.

See also

Concepts

MAPI Constants
How to: Verify an Attachment is Blocked


IAttachmentSecurity::IsAttachmentBlocked

 Copy code hover
[image]

IAttachmentSecurity::IsAttachmentBlocked
See also Send feedback

Published: July 16, 2012

Checks if a specified attachment is blocked by Microsoft Outlook 2010 or Microsoft Outlook 2013 for viewing and indexing.

C++
HRESULT IAttachmentSecurity::IsAttachmentBlocked(
    LPCWSTR pwszFileName,
    BOOL *pfBlocked
);

Parameters

pwszFileName

[in] Pointer to the filename of an attachment.

pfBlocked

[out] Pointer to a value indicating true if the specified attachment is blocked; otherwise, false.

See also

Concepts

MAPI Constants
How to: Verify an Attachment is Blocked


IContabAdmin : IUnknown

 Copy code hover
[image]

IContabAdmin : IUnknown
Send feedback

Published: July 16, 2012

Removes contact folders from the Microsoft Outlook 2010 and Microsoft Outlook 2013 address book.

Header file: | cabadmin.h
Exposed by: |
Implemented by: | IABContainer : IMAPIContainer
Called by: | CRM
Interface identifier: | IID_IContabAdmin
Pointer type: |

Vtable Order

IContabAdmin::RemoveStore

Removes the Contact Address Book (CAB) specified by the given entry ID from the address book hierarchy.


IContabAdmin::RemoveStore

 Copy code hover
[image]

IContabAdmin::RemoveStore
Send feedback

Published: July 16, 2012

Removes the Contact Address Book (CAB) specified by the given entry ID from the address book hierarchy.

Visual Basic
HRESULT RemoveStore(
ULONG cbEntryID,
LPENTRYID lpEntryID
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object to open.


IConverterSession : IUnknown

 Copy code hover
[image]

IConverterSession : IUnknown
See also Send feedback

Published: July 16, 2012

Allows conversions between MIME objects and MAPI messages. This can be useful in transporting messages across the Internet.

Provided by: | CLSID_IConverterSession
Interface identifier: | IID_IConverterSession

Vtable Order

SetAdrBook | Specifies an optional MAPI Address Book that the MAPI to MIME converter uses to resolve ambiguous addresses when converting a MAPI message to a MIME stream.
SetEncoding | Initializes the encoding to use during conversion.
Placeholder member | Not supported or documented.
MIMEToMAPI | Converts a MIME stream to a MAPI message.
MAPIToMIMEStm | Converts a MAPI message to a MIME stream.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
SetTextWrapping | Sets the text wrapping width for a MIME stream that the converter returns in MAPIToMIMEStm.
SetSaveFormat | Sets the format that the converter returns a MIME stream in MAPIToMIMEStm.
Placeholder member | Not supported or documented.
SetCharSet | Specifies an optional character set that the MAPI to MIME converter uses when converting a MAPI message to a MIME stream.

Remarks

Call SetEncoding before using MAPIToMIMEStm to perform conversion.

See also

Concepts

About the MAPI-MIME Conversion API
MAPI Constants


IConverterSession::MAPIToMIMEStm

 Copy code hover
[image]

IConverterSession::MAPIToMIMEStm
See also Send feedback

Published: July 16, 2012

Converts a MAPI message to a MIME stream.

C++
HRESULT IConverterSession::MAPIToMIMEStm(
    LPMESSAGE pmsg,
    LPSTREAM pstm,
    ULONG ulFlags
);

Parameters

pmsg

[in] Pointer to the message to convert. See mapidefs.h for the type definition of LPMESSAGE.

pstm

[out] IStream interface to output the stream.

ulFlags

[in] Flags that indicate specific actions for the converter:

CCSF_8BITHEADERS

The converter should allow 8-bit headers.

CCSF_EMBEDDED_MESSAGE

Sent/unsent information is persisted in X-Unsent.

CCSF_INCLUDE_BCC

BCC recipients of the MAPI message should be included in the MIME stream.

CCSF_NO_MSGID

Do not include Message-Id field in outgoing messages.

CCSF_NOHEADERS

The converter should ignore the headers of the outside message.

CCSF_PLAIN_TEXT_ONLY

The converter should just send plain text.

CCSF_SMTP

The converter is being passed an SMTP message. This flag must always be set.

CCSF_USE_RTF

The converter should convert from HTML to RTF format in the MIME message.

CCSF_USE_TNEF

The converter should use Transport Neutral Encapsulation Format (TNEF) format in the MIME message.

Return Values

E_INVALIDARG

Invalid flags were passed, or pmsg or pstm is NULL.

Remarks

Supported only for standard Outlook message types.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetAdrBook
IConverterSession::SetCharSet
IConverterSession::SetEncoding
IConverterSession::SetSaveFormat
IConverterSession::SetTextWrapping
PidTagMessageEditorFormat Canonical Property
PidLidUseTnef Canonical Property

Concepts

MAPI Constants


IConverterSession::MIMEToMAPI

 Copy code hover
[image]

IConverterSession::MIMEToMAPI
See also Send feedback

Published: July 16, 2012

Converts a MIME stream to a MAPI message.

C++
HRESULT IConverterSession:: MIMEToMAPI (
     LPSTREAM pstm,
     LPMESSAGE pmsg,
     LPCSTR pszSrcSrv,
     ULONG ulFlags
);

Parameters

pstm

[in] IStream interface to a MIME stream.

pmsg

[out] Pointer to the message to load. See mapidefs.h for the type definition of LPMESSAGE.

pszSrcSrv

[in] This value must be null.

ulFlags

[in] This parameter identifies any special action to be taken during the conversion. It must be zero (0) if no specific action is to be taken, or a combination of the following values:

CCSF_EMBEDDED_MESSAGE

Sent/unsent information is persisted in X-Unsent.

CCSF_SMTP

The MIME stream is for a Simple MAPI Transfer Protocol (SMTP) message.

CCSF_INCLUDE_BCC

BCC recipients of the MIME stream should be included in the MAPI message.

CCSF_USE_RTF

The HTML body of the MIME stream should be converted to Rich Text Format (RTF) in the MAPI message.

Return value

E_INVALIDARG

Indicates that pstm is null, pmsg is null, or ulFlags is invalid.

Remarks

If you have specified CCSF_USE_RTF as part of ulFlags and the destination message store supports both HTML and RTF, the MAPI message will be converted to either HTML or RTF. If the message is converted to RTF, the converted format will be compressed RTF, any HTML will be embedded in the compressed RTF string, and the string will be contained in the PidTagRtfCompressed Canonical Property.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::SetAdrBook
IConverterSession::SetCharSet
IConverterSession::SetEncoding
IConverterSession::SetSaveFormat
IConverterSession::SetTextWrapping

Concepts

MAPI Constants


IConverterSession::SetAdrBook

 Copy code hover
[image]

IConverterSession::SetAdrBook
See also Send feedback

Published: July 16, 2012

Specifies an optional MAPI Address Book that the MAPI to MIME converter uses to resolve ambiguous addresses when converting a MAPI message to a MIME stream.

HRESULT IConverterSession::SetAdrBook(
LPADRBOOK pab);

Parameters

pab

[in] Pointer to an IAddrBook : IMAPIProp interface to be used in the MAPI to MIME conversion. Set this parameter to null when you no longer need the Address Book; this releases the interface and resets the converter to not using any Address Book.

Return value

S_OK

The function call is successful.

Remarks

Converting a MAPI message to MIME stream generally does not require logging on to a MAPI profile. However, specifying a MAPI Address Book for conversion requires logging on to a profile to obtain the Address Book.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetCharSet
IConverterSession::SetEncoding
IConverterSession::SetSaveFormat
IConverterSession::SetTextWrapping


IConverterSession::SetCharSet

 Copy code hover
[image]

IConverterSession::SetCharSet
See also Send feedback

Published: July 16, 2012

Specifies an optional character set that the MAPI to MIME converter use when converting a MAPI message to a MIME stream.

C++
HRESULT SetCharset(
     BOOL fApply,
     HCHARSET hcharset,
     CSETAPPLYTYPE csetapplytype);

Parameters

fApply

[in] Indicates whether to use a specific character set for the conversion. Set this parameter to true to apply the character set in subsequent conversions. Set this parameter to false if you no longer want to apply any specific character set and return to the defaults for subsequent messages.

hcharset

[in] A handle to a character set as defined in mimeole.h of Windows Mail. Specify null to specify that you do not want to apply any specific character set. For non-null values, use a function such as MimeOleGetCodePageCharset to obtain a handle to the character set.

csetapplytype

[in] Indicates how to apply a character set to convert a message, as defined in mimeole.h of Windows Mail.

Return value

S_OK

The function call is successful.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetAdrBook
IConverterSession::SetEncoding
IConverterSession::SetSaveFormat
IConverterSession::SetTextWrapping


IConverterSession::SetEncoding

 Copy code hover
[image]

IConverterSession::SetEncoding
See also Send feedback

Published: July 16, 2012

Initializes the encoding to be used during conversion.

C++
HRESULT IConverterSession:: SetEncoding (
     ENCODINGTYPE et
);

Parameters

et

An ENCODINGTYPE value. Only the following values are supported:

  • IET_BASE64

  • IET_UUENCODE

  • IET_QP

  • IET_7BIT

  • IET_8BIT

Return value

E_INVALIDARG

The encoding type passed was invalid.

Remarks

Call SetEncoding before using IConverterSession::MAPIToMIMEStm to perform conversion.

Use SetEncoding to set the encoding for only the outermost message body of a mail item. Microsoft Outlook 2010 and Microsoft Outlook 2013 choose the encoding for any individual attachments.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetAdrBook
IConverterSession::SetCharSet
IConverterSession::SetSaveFormat
IConverterSession::SetTextWrapping

Concepts

MAPI Constants


IConverterSession::SetSaveFormat

 Copy code hover
[image]

IConverterSession::SetSaveFormat
See also Send feedback

Published: July 16, 2012

Sets the format in which the converter will return a MIME stream in IConverterSession::MAPIToMIMEStm.

C++
HRESULT IConverterSession::SetSaveFormat (
     MIMESAVETYPE mstSaveFormat
);

Parameters

mstSaveFormat

[in] The save format to be used for a MIME stream. For more information, see the enum type MIMESAVETYPE.

SAVE_RFC1521

Use MIME, which is the default.

SAVE_RFC822

Use uuencode.

Return Values

S_OK

The call was successful.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetAdrBook
IConverterSession::SetCharSet
IConverterSession::SetEncoding
IConverterSession::SetTextWrapping

Concepts

MAPI Constants


IConverterSession::SetTextWrapping

 Copy code hover
[image]

IConverterSession::SetTextWrapping
See also Send feedback

Published: July 16, 2012

Sets the text wrapping width for a MIME stream that the converter will return in IConverterSession::MAPIToMIMEStm.

HRESULT IConverterSession::SetTextWrapping (
    BOOL    fWrapText,
    ULONG   ulWrapWidth
);

Parameters

fWrapText

[in] Whether to wrap text or not.

ulWrapWidth

[in] The text wrapping width to use.

Return value

S_OK

The call was successful.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MapiMime.cpp | ImportEMLToIMessage | MFCMAPI uses MimeToMAPI to convert an EML file to a MAPI message.
MapiMime.cpp | ExportIMessageToEML | MFCMAPI uses MAPIToMIMEStm to convert a MAPI message to an EML file.

See also

Reference

IConverterSession : IUnknown
IConverterSession::MAPIToMIMEStm
IConverterSession::MIMEToMAPI
IConverterSession::SetAdrBook
IConverterSession::SetCharSet
IConverterSession::SetEncoding
IConverterSession::SetSaveFormat

Concepts

MAPI Constants


IDistList : IMAPIContainer

 Copy code hover
[image]

IDistList : IMAPIContainer
See also Send feedback

Published: July 16, 2012

Provides access to distribution lists in modifiable address book containers. IDistList can create, copy, and delete distribution lists, in addition to performing name resolution.

Header file: | Mapidefs.h
Exposed by: | Distribution list objects
Implemented by: | Address book providers
Called by: | Client applications
Interface identifier: | IID_IDistList
Pointer type: | LPDISTLIST
Transaction model: | Transacted

Vtable Order

This interface does not have any unique methods.

Required properties | Access
PR_ADDRTYPE (PidTagAddressType) | Read/write
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write
PR_ENTRYID (PidTagEntryId) | Read-only
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only

Remarks

The IDistList interface inherits from IMAPIContainer and includes the same methods as address book containers. Therefore, because the methods of the IDistList interface are identical to those of the IABContainer interface, they are not duplicated here.

A distribution list or object that implements IDistList is a collection of messaging user objects, or individual recipients. A distribution list can consist of all messaging user objects, or some messaging user and some distribution lists.

There are typically two types of distribution lists:

  • Distribution lists that are expanded by the underlying messaging system. This type of list has an address, PR_EMAIL_ADDRESS (PidTagEmailAddress), and is treated the same as if it were an individual recipient.

  • Distribution lists that exist in a local container and are expanded by the client application.

Optional distribution list properties include the following:

  • PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime)

  • PR_DISPLAY_TYPE (PidTagDisplayType)

  • PR_DETAILS_TABLE (PidTagDetailsTable)

Notice that PR_ADDRTYPE is required, but PR_EMAIL_ADDRESS (PidTagEmailAddress) is not. That is because a distribution list without an e-mail address can still receive messages, but its member list must be expanded. If the PR_ADDRTYPE property is set to MAPIPDL, MAPI performs the expansion. If PR_ADDRTYPE is a value other than MAPIPDL, the transport provider performs the expansion.

For additional information about how to use the IDistList methods, see the reference entries for the parallel methods of IABContainer.

See also

Concepts

MAPI Interfaces


IExchangeModifyTable : IUnknown

 Copy code hover
[image]

IExchangeModifyTable : IUnknown
See also Send feedback

Published: July 16, 2012

Supports access to Microsoft Exchange Server table objects, specifically system access control list (SACL) table objects and rule table objects on Microsoft Exchange Server folders. This interface resembles the IMAPITable : IUnknown interface, but it adds support for Microsoft Exchange Server-specific structures that are used to control SACLs and rules.

Exposed by: | None
Implemented by: | Server table objects
Called by: | MAPI and client applications
Interface identifier: | IID_IExchangeModifyTable
Pointer type: | LPEXCHANGEMODIFYTABLE
Transaction model: | Transacted

Vtable Order

GetLastError | Returns information about the last error that occurred in a table object.
GetTable | Returns a pointer to an interface for a MAPI table object.
ModifyTable | Updates a MAPI table object.
Properties used to modify a rules table | Access
PR_RULE_ACTIONS (PidTagRuleActions) | Read-only
PR_RULE_CONDITION (PidTagRuleCondition) | Read-only
PR_RULE_ID (PidTagRuleId) | Read-only
PR_RULE_LEVEL (PidTagRuleLevel) | Read-only
PR_RULE_NAME (PidTagRuleName) | Read-only
PR_RULE_PROVIDER (PidTagRuleProvider) | Read-only
PR_RULE_PROVIDER_DATA (PidTagRuleProviderData) | Read-only
PR_RULE_SEQUENCE (PidTagRuleSequence) | Read-only
PR_RULE_STATE (PidTagRuleState) | Read-only
PR_RULE_USER_FLAGS (PidTagRuleUserFlags) | Read-only
Properties used to modify a SACL table | Access
PR_MEMBER_ENTRYID (PidTagMemberEntryId) | Read-only
PR_MEMBER_ID (PidTagMemberId) | Read-only
PR_MEMBER_NAME (PidTagMemberName) | Read-only
PR_MEMBER_RIGHTS (PidTagMemberRights) | Read-only

Remarks

To obtain the IExchangeModifyTable interface, call the MAPI IMAPIProp::OpenProperty method on a property of type PT_OBJECT on a folder object. When you call the OpenProperty method, pass the value IID_IExchangeModifyTable in the lpiid parameter.

See also

Concepts

MAPI Interfaces


IExchangeModifyTable::GetLastError

 Copy code hover
[image]

IExchangeModifyTable::GetLastError
See also Send feedback

Published: July 16, 2012

Returns information about the last error that occurred in a table object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] The return value from the method that failed.

ulFlags

[in] Not used, set to 0 (zero).

lppMAPIError

[out] Points to a MAPI MAPIERROR structure that contains information about the last error that occurred for a table object.

See also

Reference

IExchangeModifyTable : IUnknown
MAPIERROR

Concepts

MFCMAPI as a Code Sample


IExchangeModifyTable::GetTable

 Copy code hover
[image]

IExchangeModifyTable::GetTable
See also Send feedback

Published: July 16, 2012

Returns a pointer to an interface for a MAPI table object.

C++
HRESULT GetTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Reserved; must be 0 (zero).

ACLTABLE_FREEBUSY

Sets new rights.

frightsFreeBusyDetailed

When ACLTABLE_FREEBUSY is passed, provides a detailed display of new free/busy rights.

frightsFreeBusySimple

When ACLTABLE_FREEBUSY is passed, provides a simple display of new free/busy rights.

lppTable

[out] Points to a IMAPITable : IUnknown interface containing the table object.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
RulesDlg.cpp | CRulesDlg::OnRefreshView | MFCMAPI uses the IExchangeModifyTable::GetTable method to get a table of rules.

See also

Reference

IExchangeModifyTable : IUnknown

Concepts

MFCMAPI as a Code Sample


IExchangeModifyTable::ModifyTable

 Copy code hover
[image]

IExchangeModifyTable::ModifyTable
See also Send feedback

Published: July 16, 2012

Updates a MAPI table object.

C++
HRESULT ModifyTable(
  ULONG ulFlags,
  LPROWLIST lpMods
);

Parameters

ulFlags

[in] Use one of the following values:

0 (zero)

Use the value of the ulRowFlags member of the ROWENTRY structure.

ACLTABLE_FREEBUSY

Sets new rights.

frightsFreeBusyDetailed

When ACLTABLE_FREEBUSY is passed, provides a detailed display of new free/busy rights.

frightsFreeBusySimple

When ACLTABLE_FREEBUSY is passed, provides a simple display of new free/busy rights.

ROWLIST_REPLACE

Replace all the rows in the table.

lpMods

[in] Points to a ROWLIST structure containing the properties for the table object.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
RulesDlg.cpp | CRulesDlg::OnModifySelectedItem | MFCMAPI uses the IExchangeModifyTable::ModifyTable method to write a modified rule back to the table of rules.

See also

Reference

IExchangeModifyTable : IUnknown
ROWENTRY
ROWLIST

Concepts

MFCMAPI as a Code Sample


IFolderSupport : IUnknown

 Copy code hover
[image]

IFolderSupport : IUnknown
Send feedback

Published: July 16, 2012

Provides information about a folder's support for sharing.

Provided by: | Message store provider
Interface identifier: | IID_IFolderSupport

Vtable Order

GetSupportMask

Gets information about a folder's support for sharing.

Remarks

Generally, Microsoft Office Outlook requires a MAPI store provider to implement this interface if the provider wants to share a folder. The exception is the Exchange Server store provider, which can share folders without implementing this interface.

A client can query an IMAPIFolder for IFolderSupport. If that succeeds, call IFolderSupport::GetSupportMask and check for the FS_SUPPORTS_SHARING bit to be set.


IFolderSupport::GetSupportMask

 Copy code hover
[image]

IFolderSupport::GetSupportMask
Send feedback

Published: July 16, 2012

Gets information about a folder's support for sharing.

SCR
HRESULT GetSupportMask(
    DWORD * pdwSupportMask
);

Parameters

pdwSupportMask

[out] A bitmask indicating if the folder supports sharing.

FS_NONE

Indicates that the folder does not support sharing.

FS_SUPPORTS_SHARING

Indicates that the folder supports sharing.

Return value

S_OK

The call was successful.


IMailUser : IMAPIProp

 Copy code hover
[image]

IMailUser : IMAPIProp
See also Send feedback

Published: July 16, 2012

Provides access to the many properties that are associated with messaging users. The IMailUser interface is implemented by messaging user objects. IMailUser inherits from the IMAPIProp : IUnknown interface and has no unique methods of its own.

Header file: | Mapidefs.h
Exposed by: | Messaging user objects
Implemented by: | Address book providers
Called by: | Client applications
Interface identifier: | IID_IMailUser
Pointer type: | LPMAILUSER
Transaction model: | Transacted

Vtable Order

This interface does not have any unique methods.

Required properties | Access
PR_ADDRTYPE (PidTagAddressType) | Read/write
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write
PR_DISPLAY_TYPE (PidTagDisplayType) | Read-only
PR_EMAIL_ADDRESS (PidTagEmailAddress) | Read/write
PR_ENTRYID (PidTagEntryId) | Read-only
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only
PR_SEARCH_KEY (PidTagSearchKey) | Read-only

Remarks

Five of the required properties are known as the base address properties for recipients:

  • PR_ADDRTYPE

  • PR_DISPLAY_NAME

  • PR_EMAIL_ADDRESS

  • PR_ENTRYID

  • PR_SEARCH_KEY

These properties are considered special because many other groups of similar properties are built upon this base group. The other groups are used to describe a recipient in various roles, such as a message's original or delegate sender. For more information about these properties and how to use them, see MAPI Address Types.

Messaging users can display a collection of their properties by supporting the PR_DETAILS_TABLE (PidTagDetailsTable) property. PR_DETAILS_TABLE is a display table that describes the layout of a details dialog box or a tabbed property page that displays recipient property information. MAPI creates details dialog boxes when a client calls the IAddrBook::Details method.

Messaging user objects can have other optional properties associated with them. MAPI defines many properties that provide additional addressing information about a messaging user. All of these properties are character strings. The following list shows the more commonly used properties:

  • PR_ACCOUNT (PidTagAccount)

  • PR_ASSISTANT (PidTagAssistant)

  • PR_BUSINESS_TELEPHONE_NUMBER (PidTagBusinessTelephoneNumber)

  • PR_GIVEN_NAME (PidTagGivenName)

  • PR_GOVERNMENT_ID_NUMBER (PidTagGovernmentIdNumber)

  • PR_LOCALITY (PidTagLocality)

  • PR_POSTAL_ADDRESS (PidTagPostalAddress)

For a complete list of properties, see Mapping Canonical Property Names to MAPI Names.

See also

Concepts

MAPI Interfaces


IMAPIAdviseSink : IUnknown

 Copy code hover
[image]

IMAPIAdviseSink : IUnknown
See also Send feedback

Published: July 16, 2012

Implements an advise sink object for handling notification. A pointer to an advise sink object is passed in a call to a service provider's Advise method, the mechanism used to register for notification.

Header file: | Mapidefs.h
Exposed by: | Advise sink objects
Implemented by: | Client applications and MAPI
Called by: | Service providers and MAPI
Interface identifier: | IID_IMAPIAdviseSink
Pointer type: | LPMAPIADVISESINK

Vtable Order

OnNotify

Responds to a notification by performing one or more tasks. The tasks performed depend on the type of event and the object that generates the notification.

See also

Concepts

MAPI Interfaces


IMAPIAdviseSink::OnNotify

 Copy code hover
[image]

IMAPIAdviseSink::OnNotify
See also Send feedback

Published: July 16, 2012

Responds to a notification by performing one or more tasks. The tasks performed depend on the type of event and the object that generates the notification.

C++
ULONG OnNotify(
  ULONG cNotif,
  LPNOTIFICATION lpNotifications
);

Parameters

cNotif

[in] The count of NOTIFICATION structures pointed to by the lpNotifications parameter.

lpNotifications

[in] A pointer to one or more NOTIFICATION structures that provide information about the events that have occurred.

Return value

S_OK

The notification was processed successfully.

Remarks

The notification process starts when a client or MAPI makes a call to a service provider's Advise method to register to receive a notification of a particular type for a particular object. One of the parameters to the Advise method is a pointer to an advise sink object that implements the IMAPIAdviseSink interface. When an event occurs to the target object that corresponds to the registered notification, the service provider, either directly or indirectly through MAPI, calls the advise sink's OnNotify method.

The call to OnNotify can occur either during the MAPI call that is causing the event or at some later time. On systems that support multiple threads of execution, OnNotify can be called either on the same thread that was used for registration or on a different thread. Clients can make sure that the OnNotify call is made on the same thread used to call Advise by creating the advise sink that they pass to Advise with the HrThisThreadAdviseSink function.

The lpNotifications parameter points to one or more NOTIFICATION structures that describe what has changed during the event. There is a different type of NOTIFICATION structure for each type of event.

The following table lists the values that are used to represent the possible types of events and the structures associated with each value:

Notification event type | Corresponding structure
fnevCriticalError | ERROR_NOTIFICATION
fnevNewMail | NEWMAIL_NOTIFICATION
fnevObjectCreated | OBJECT_NOTIFICATION
fnevObjectDeleted | OBJECT_NOTIFICATION
fnevObjectModified | OBJECT_NOTIFICATION
fnevObjectCopied | OBJECT_NOTIFICATION
fnevSearchComplete | OBJECT_NOTIFICATION
fnevTableModified | TABLE_NOTIFICATION
fnevStatusObjectModified | STATUS_OBJECT_NOTIFICATION
fnevExtended | EXTENDED_NOTIFICATION

For more information about how to set up and stop notifications, see the reference entries for the Advise and Unadvise methods for any of the following interfaces: IABLogon, IAddrBook, IMAPIForm, IMAPISession, IMAPITable, IMsgStore, and IMSLogon.

For general information about the notification process, see Event Notification in MAPI.

Notes to Implementers

Your OnNotify implementation will typically consist of one or more blocks of code for each type of notification you expect to receive. Within these blocks of code, perform any tasks that you consider necessary as a response to the notification. For example, suppose you register to receive fnevObjectModified notifications on a folder that is included in a dialog box display. In the block of code that you include in your OnNotify method to handle fnevObjectModified notifications, you might send a Windows message to the dialog box to request an updated display.

Do not modify or free the NOTIFICATION structure passed to OnNotify. The data in the structure is valid only until OnNotify returns.

Notes to Callers

When changes occur to multiple objects, you can notify a registered advise sink in a single call to OnNotify or in multiple calls depending on memory constraints. This is true regardless of whether the changes are the result of one method call or several. For example, a call to IMAPIFolder::CopyMessages can affect multiple messages and folders. As a message store provider, you can make one call to OnNotify with an fnevObjectModified event type for the target folder or many calls, one for each affect messages. Similarly, if a client makes repeated calls to IMAPIFolder::CreateMessage, these calls can be combined into one fnevObjectModified event for the folder or separated into individual fnevObjectCreated events for each new message.

For more information about how and when to generate notifications, see Event Notification in MAPI and Supporting Event Notification.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
AdviseSink.h and AdviseSink.cpp | CAdviseSink::OnNotifyDesc | The CAdviseSink class is implemented to handle all notifications in MFCMAPI.

See also

Reference

HrAllocAdviseSink
HrThisThreadAdviseSink
IMAPISupport::Notify
NOTIFICATION
IMAPIAdviseSink : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIClientShutdown : IUnknown

 Copy code hover
[image]

IMAPIClientShutdown : IUnknown
See also Send feedback

Published: July 16, 2012

Enables a MAPI client to carry out fast shutdown of the client process.

Header file: | Mapidefs.h
Exposed by: | IMAPISession object
Implemented by: | MAPI subsystem
Called by: | MAPI client
Interface identifier: | IID_IMAPIClientShutdown
Pointer type: | LPMAPICLIENTSHUTDOWN

Vtable Order

QueryFastShutdown | Queries the MAPI subsystem for fast shutdown support that is provided by loaded MAPI providers.
NotifyProcessShutdown | Indicates the intention of the MAPI client to proceed with shut down.
DoFastShutdown | Indicates the intention of the MAPI client to exit the client process immediately.

Remarks

The purpose of fast shutdown is to allow a MAPI client and any loaded MAPI provider with which the MAPI client has an active MAPI session to save MAPI settings and data. This enables the MAPI client to disconnect all external references and exit without causing any data loss. A MAPI client that needs to perform fast shutdown must use the IMAPIClientShutdown interface. The MAPI client can obtain a pointer to this interface by calling the IUnknown::QueryInterface method on any IMAPISession object.

A MAPI client always initiates a fast shutdown by calling the IMAPIClientShutdown::QueryFastShutdown method. The MAPI subsystem responds to the MAPI client's query by verifying whether loaded MAPI providers support the client's fast shutdown. The administrator can use Windows registry settings to help determine the level of provider support that is necessary for MAPI clients to proceed with fast shutdown. For more information, see Fast Shutdown User Options.

To proceed with fast shutdown, the client calls the IMAPIClientShutdown::NotifyProcessShutdown method to indicate to the MAPI subsystem the intention to shut down. The client then calls the IMAPIClientShutdown::DoFastShutdown method to indicate that the client process is exiting immediately.

For more information about fast shutdown, see Fast Shutdown Overview. For information about how to perform fast shutdown successfully, see Best Practices for Fast Shutdown.

See also

Concepts

MAPI Interfaces
Client Shutdown in MAPI


IMAPIClientShutdown::DoFastShutdown

 Copy code hover
[image]

IMAPIClientShutdown::DoFastShutdown
See also Send feedback

Published: July 16, 2012

Indicates the intention of the MAPI client to exit the client process immediately.

C++
HRESULT DoFastShutdown ();

Return Value

S_OK

The MAPI subsystem has indicated to loaded MAPI providers that the MAPI client is exiting immediately, and the MAPI providers are ready for the client exit.

MAPI_E_NO_SUPPORT

The MAPI subsystem does not support client fast shutdown.

Remarks

To avoid data loss from the fast shutdown of a MAPI client, MAPI clients should call the IMAPIClientShutdown::NotifyProcessShutdown and IMAPIClientShutdown::DoFastShutdown methods based on the S_OK result returned by the MAPI subsystem in the IMAPIClientShutdown::QueryFastShutdown method. For more information, see Best Practices for Fast Shutdown.

See also

Reference

IMAPIClientShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPIClientShutdown::NotifyProcessShutdown

 Copy code hover
[image]

IMAPIClientShutdown::NotifyProcessShutdown
See also Send feedback

Published: July 16, 2012

Indicates the intention of the MAPI client to proceed with shut down.

C++
HRESULT NotifyProcessShutdown ();

Return Value

S_OK

The MAPI subsystem has attempted to notify loaded MAPI providers that the MAPI client is going to do a fast shutdown.

Remarks

To avoid data loss from the fast shutdown of a MAPI client, MAPI clients should call the IMAPIClientShutdown::NotifyProcessShutdown and IMAPIClientShutdown::DoFastShutdown methods based on the S_OK result returned by the MAPI subsystem in the IMAPIClientShutdown::QueryFastShutdown method. For more information, see Best Practices for Fast Shutdown.

See also

Reference

IMAPIClientShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPIClientShutdown::QueryFastShutdown

 Copy code hover
[image]

IMAPIClientShutdown::QueryFastShutdown
See also Send feedback

Published: July 16, 2012

Queries the MAPI subsystem for fast shutdown support that is provided by loaded MAPI providers.

C++
HRESULT QueryFastShutdown ();

Return Value

S_OK

The MAPI subsystem supports the MAPI client to do fast shutdown.

MAPI_E_NO_SUPPORT

The MAPI provider does not support the MAPI client to do fast shutdown.

Remarks

Whether the MAPI subsystem supports the MAPI client to do fast shutdown depends on the user's Windows registry setting or the default behavior of the MAPI client for fast shutdown. It also depends on the ability of the loaded MAPI providers to support fast shutdown. For more information, see Fast Shutdown User Options.

See also

Reference

IMAPIClientShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPIContainer : IMAPIProp

 Copy code hover
[image]

IMAPIContainer : IMAPIProp
See also Send feedback

Published: July 16, 2012

Manages high-level operations on container objects such as address books, distribution lists, and folders. The IMAPIFolder : IMAPIContainer, IABContainer : IMAPIContainer, and IDistList : IMAPIContainer interfaces are derived from IMAPIContainer.

Header file: | Mapidefs.h
Exposed by: | Folder, address book container, and distribution list objects
Implemented by: | Message store, address book, and remote transport providers
Called by: | Client applications
Interface identifier: | IID_IMAPIContainer
Pointer type: | LPMAPICONTAINER
Transaction model: | Abstract class, never implemented

Vtable Order

GetContentsTable | Returns a pointer to the container's contents table.
GetHierarchyTable | Returns a pointer to the container's hierarchy table.
OpenEntry | Opens an object in the container, returning an interface pointer for further access.
SetSearchCriteria | Establishes search criteria for the container.
GetSearchCriteria | Obtains the search criteria for the container.
Required properties | Access
PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) | Read-only
PR_CONTAINER_CONTENTS (PidTagContainerContents) | Read-only
PR_CONTAINER_FLAGS (PidTagContainerFlags) | Read/write

See also

Concepts

MAPI Interfaces


IMAPIContainer::GetContentsTable

 Copy code hover
[image]

IMAPIContainer::GetContentsTable
See also Send feedback

Published: July 16, 2012

Returns a pointer to the container's contents table.

C++
HRESULT GetContentsTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that controls how the contents table is returned. The following flags can be set:

MAPI_ASSOCIATED

The container's associated contents table should be returned instead of the standard contents table. This flag is used only with folders. The messages that are included in the associated contents table were created with the MAPI_ASSOCIATED flag set in the call to the IMAPIFolder::CreateMessage method. Clients typically use the associated contents table to retrieve forms, views, and other hidden messages.

ACLTABLE_FREEBUSY

Enables access to the frightsFreeBusySimple and frightsFreeBusyDetailed rights in PR_MEMBER_RIGHTS.

MAPI_DEFERRED_ERRORS

GetContentsTable can return successfully, possibly before the table is made available to the caller. If the table is not available, making a subsequent table call can raise an error.

MAPI_UNICODE

Requests that the columns that contain string data be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the strings should be returned in the ANSI format.

SHOW_SOFT_DELETES

Shows items that are currently marked as soft deleted—that is, they are in the deleted item retention time phase.

lppTable

[out] A pointer to a pointer to the contents table.

Return value

S_OK

The contents table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_NO_SUPPORT

The container has no contents and cannot provide a contents table.

Remarks

The IMAPIContainer::GetContentsTable method returns a pointer to the contents table of a container. A contents table contains summary information about objects in the container.

Contents tables have lengthy column sets. For a complete list of the required and optional columns in contents tables, see Contents Tables.

It is possible for some containers to have no contents. These containers return MAPI_E_NO_SUPPORT from their implementations of GetContentsTable.

Notes to Implementers

If you support a contents table for your container, you must also do the following:

  • Support calls to the container's IMAPIProp::OpenProperty method to open the PR_CONTAINER_CONTENTS (PidTagContainerContents) property.

  • Return PR_CONTAINER_CONTENTS in response to a call to the container's

    IMAPIProp::GetProps and IMAPIProp::GetPropList methods.

A remote transport provider's implementation of this method must return a pointer to an IMAPITable : IUnknown interface in the ppTable parameter passed into the GetContentsTable method. If your transport provider has an existing contents table, it is sufficient to return a pointer to it. If not, this method must create a new IMAPITable : IUnknown object, populate the table with message headers (if any are available), and return a pointer to the new table. The ITableData::HrGetView method is useful for generating a return value and storing the table pointer in the ppTable parameter. The contents table must support at least the following property columns:

  • PR_ENTRYID (PidTagEntryID)

  • PR_SENDER_NAME (PidTagSenderName)

  • PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName)

  • PR_DISPLAY_TO (PidTagDisplayTo)

  • PR_SUBJECT (PidTagSubject)

  • PR_MESSAGE_CLASS (PidTagMessageClass)

  • PR_MESSAGE_FLAGS (PidTagMessageFlags)

  • PR_MESSAGE_SIZE (PidTagMessageSize)

  • PR_PRIORITY (PidTagPriority)

  • PR_IMPORTANCE (PidTagImportance)

  • PR_SENSITIVITY (PidTagSensitivity)

  • PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)

  • PR_MSG_STATUS (PidTagMessageStatus)

  • PR_MESSAGE_DOWNLOAD_TIME (PidTagMessageDownloadTime)

  • PR_HASATTACH (PidTagHasAttachments)

  • PR_OBJECT_TYPE (PidTagObjectType)

  • PR_INSTANCE_KEY (PidTagInstanceKey)

  • PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject)

Notes to Callers

String and binary contents table columns can be truncated. Typically, providers return 255 characters. Because you cannot know beforehand whether a table includes truncated columns, assume that a column is truncated if the length of the column is either 255 or 510 bytes. You can always retrieve the full value of a truncated column, if necessary, directly from the object by using its entry identifier to open it and then calling the IMAPIProp::GetProps method.

Depending on the provider's implementation, restrictions and sorting operations can apply to all of a string or to the truncated version of that string.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableDialog.cpp | CContentsTableDlg::CContentsTableDlg | The CContentsTableDlg class uses GetContentsTable to obtain the entries in a contents table.

See also

Reference

IMAPIProp::GetPropList
IMAPIProp::GetProps
IMAPIProp::OpenProperty
IMAPITable : IUnknown
PidTagContainerContents Canonical Property
IMAPIContainer : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIContainer::GetHierarchyTable

 Copy code hover
[image]

IMAPIContainer::GetHierarchyTable
See also Send feedback

Published: July 16, 2012

Returns a pointer to the container's hierarchy table.

C++
HRESULT GetHierarchyTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that controls how information is returned in the table. The following flags can be set:

CONVENIENT_DEPTH

Fills the hierarchy table with containers from multiple levels. If CONVENIENT_DEPTH is not set, the hierarchy table contains only the container's immediate child containers.

MAPI_DEFERRED_ERRORS

GetHierarchyTable can return successfully, possibly before the table is made available to the caller. If the table is not available, making a subsequent table call can raise an error.

MAPI_UNICODE

Requests that the columns that contain string data be returned in Unicode format. If the MAPI_UNICODE flag is not set, the strings should be returned in ANSI format.

SHOW_SOFT_DELETES

Shows items that are currently marked as soft deleted—that is, they are in the deleted item retention time phase.

lppTable

[out] A pointer to a pointer to the hierarchy table.

Return value

S_OK

The hierarchy table was successfully retrieved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_NO_SUPPORT

The container has no child containers and cannot provide a hierarchy table.

Remarks

The IMAPIContainer::GetHierarchyTable method returns a pointer to the hierarchy table of a container. A hierarchy table holds summary information about the child containers in the container. Folder hierarchy tables hold information about subfolders; address book hierarchy tables hold information about child address book containers and distribution lists.

It is possible for some containers to have no child containers. These containers return MAPI_E_NO_SUPPORT from their implementations of GetHierarchyTable.

When the CONVENIENT_DEPTH flag is set, each row in the hierarchy table also includes the PR_DEPTH (PidTagDepth) property as a column. PR_DEPTH indicates the level of each container relative to the container that implements the table. The implementing container's immediate child containers are at depth zero, child containers in the zero depth containers are at depth one, and so on. The values of PR_DEPTH increase sequentially as the hierarchy of levels deepens.

For a complete list of required and optional columns in hierarchy tables, see Hierarchy Tables.

Notes to Implementers

If you support a hierarchy table for your container, you must also do the following:

  • Support a call to the container's IMAPIProp::OpenProperty method to open the PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) property.

  • Return PR_CONTAINER_HIERARCHY from a call to the container's IMAPIProp::GetPropList or IMAPIProp::GetProps methods.

Notes to Callers

String and binary contents table columns can be truncated. Typically, providers return 255 characters. Because you cannot know beforehand whether a table includes truncated columns, assume that a column is truncated if the length of the column is either 255 or 510 bytes. You can always retrieve the full value of a truncated column, if necessary, directly from the object by using its entry identifier to open it and then calling the IMAPIProp::GetProps method.

Depending on the provider's implementation, restrictions and sorting operations can apply to the whole string or to the truncated version of that string. Moreover, store providers are not guaranteed to honor the sort order set SSortOrderSet specified for hierarchy tables.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
HierarchyTableTreeCtrl.cpp | CHierarchyTableTreeCtrl::GetHierarchyTable | The CHierarchyTableTreeCtrl class uses GetHierarchyTable to obtain hierarchy tables to display in a tree view control.

See also

Reference

IMAPIProp::GetPropList
IMAPIProp::GetProps
IMAPITable : IUnknown
PidTagContainerHierarchy Canonical Property
IMAPIContainer : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIContainer::GetSearchCriteria

 Copy code hover
[image]

IMAPIContainer::GetSearchCriteria
See also Send feedback

Published: July 16, 2012

Obtains the search criteria for the container.

C++
HRESULT GetSearchCriteria(
  ULONG ulFlags,
  LPSRestriction FAR * lppRestriction,
  LPENTRYLIST FAR * lppContainerList,
  ULONG FAR * lpulSearchState
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppRestriction

[out] A pointer to a pointer to an SRestriction structure that defines the search criteria. If a client application passes NULL in the lppRestriction parameter, GetSearchCriteria does not return an SRestriction structure.

lppContainerList

[out] A pointer to a pointer to an array of entry identifiers that represent containers to be included in the search. If a client passes NULL in the lppContainerList parameter, GetSearchCriteria does not return an array of entry identifiers.

lpulSearchState

[out] A pointer to a bitmask of flags used to indicate the current state of the search. If a client passes NULL in the lpulSearchState parameter, GetSearchCriteria returns no flags. The following flags can be set:

SEARCH_FOREGROUND

The search should run at high priority relative to other searches. If this flag is not set, the search runs at normal priority relative to other searches.

SEARCH_REBUILD

The search is in the CPU-intensive mode of its operation, trying to locate messages that match the criteria. If this flag is not set, the CPU-intensive part of the search's operation is over. This flag has meaning only if the search is active (that is, if the SEARCH_RUNNING flag is set).

SEARCH_RECURSIVE

The search is looking in specified containers and all their child containers for matching entries. If this flag is not set, only the containers explicitly included in the last call to the IMAPIContainer::SetSearchCriteria method are being searched.

SEARCH_RUNNING

The search is active and the container's contents table is being updated to reflect changes in the message store or address book. If this flag is not set, the search is inactive and the contents table is static.

Return value

S_OK

The search criteria was successfully obtained.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_NOT_INITIALIZED

Search criteria were never established for the container.

Remarks

The IMAPIContainer::GetSearchCriteria method obtains the search criteria for a container that supports searches, typically a search-results folder. You create search criteria by calling a container's IMAPIContainer::SetSearchCriteria method.

Notes to Implementers

Address book containers may need to support GetSearchCriteria only if they provide the advanced search capabilities associated with the PR_SEARCH (PidTagSearch) property. For more information about how to implement the advanced search feature for address book containers, see Implementing Advanced Searching.

Notes to Callers

When you are finished with the data structures pointed to by the lppRestriction and lppContainerList parameters, call MAPIFreeBuffer once for each structure to be released.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
HierarchyTableDlg.cpp | CHierarchyTableDlg::OnEditSearchCriteria | MFCMAPI uses the IMAPIContainer::GetSearchCriteria method to obtain search criteria from a folder to display.

See also

Reference

IMAPIContainer::SetSearchCriteria
IMAPIFolder::CreateFolder
MAPIFreeBuffer
PidTagSearch Canonical Property
IMAPIContainer : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIContainer::OpenEntry

 Copy code hover
[image]

IMAPIContainer::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens an object in the container, returning an interface pointer for further access.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object to open. If lpEntryID is set to NULL, the top-level container in the container's hierarchy is opened.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the object. Passing NULL results in the identifier for the object's standard interface being returned. For messages, the standard interface is IMAPIMessageSite : IUnknown; for folders, it is IMAPIFolder : IMAPIContainer. The standard interfaces for address book objects are IDistList : IMAPIContainer for a distribution list and IMailUser : IMAPIProp for a messaging user.

ulFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the object will be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the object should be opened with read/write permission; if the client has read-only access, the object should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully available to the calling client. If the object is not available, making a subsequent object call can raise an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write permission has been granted.

SHOW_SOFT_DELETES

Shows items that are currently marked as soft deleted—that is, they are in the deleted item retention time phase.

lpulObjType

[out] A pointer to the opened object's type.

lppUnk

[out] A pointer to a pointer to the interface implementation to use to access the open object.

Return value

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

Either the user has insufficient permissions to open the object or an attempt was made to open a read-only object with read/write permission.

MAPI_E_NOT_FOUND

The entry identifier specified by lpEntryID does not represent an object.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier in the lpEntryID parameter is not of a format recognized by the container.

Remarks

The IMAPIContainer::OpenEntry method opens an object throughout a container and returns a pointer to an interface implementation to use for further access.

Notes to Callers

Because service providers are not required to return an interface implementation of the type specified by the interface identifier in the lpInterface parameter, check the value pointed to by the lpulObjType parameter. If necessary, cast the pointer returned in lppUnk to a pointer of the appropriate type.

By default, service providers open objects with read-only access unless you set either the MAPI_MODIFY or MAPI_BEST_ACCESS flag. When one of these flags is set, service providers attempt to return a modifiable object. However, do not assume that because you requested a modifiable object that the opened object has read/write permission. Either plan for the chance of a subsequent modification to fail or retrieve the object's PR_ACCESS_LEVEL property to determine the access level granted by OpenEntry.

See also

Reference

IMAPIContainer : IMAPIProp


IMAPIContainer::SetSearchCriteria

 Copy code hover
[image]

IMAPIContainer::SetSearchCriteria
See also Send feedback

Published: July 16, 2012

Establishes search criteria for the container.

C++
HRESULT SetSearchCriteria(
  LPSRestriction lpRestriction,
  LPENTRYLIST lpContainerList,
  ULONG ulSearchFlags
);

Parameters

lpRestriction

[in] A pointer to an SRestriction structure that defines the search criteria. If NULL is passed in the lpRestriction parameter, the search criteria that were used most recently for this container are used again. NULL should not be passed in lpRestriction for the first search in a container.

lpContainerList

[in] A pointer to an array of entry identifiers that represent containers to be included in the search. If a client passes NULL in the lpContainerList parameter, the entry identifiers used most recently to search this container are used for the new search. A client should not pass NULL in lpContainerList for the first search in a container.

ulSearchFlags

[in] A bitmask of flags that control how the search is performed. The following flags can be set:

BACKGROUND_SEARCH

The search should run at normal priority relative to other searches. This flag cannot be set at the same time as the FOREGROUND_SEARCH flag.

FOREGROUND_SEARCH

The search should run at high priority relative to other searches. This flag cannot be set at the same time as the BACKGROUND_SEARCH flag.

NON_CONTENT_INDEXED_SEARCH

The search should not use content indexing to find matching entries. This flag is only valid for Exchange stores.

RECURSIVE_SEARCH

The search should include the containers specified in the lpContainerList parameter and all their child containers. This flag cannot be set at the same time as the SHALLOW_SEARCH flag.

RESTART_SEARCH

The search should be initiated if this is the first call to SetSearchCriteria, or restarted if the search is inactive. This flag cannot be set at the same time as the STOP_SEARCH flag.

SHALLOW_SEARCH

The search should look only in the containers specified in the lpContainerList parameter for matching entries. This flag cannot be set at the same time as the RECURSIVE_SEARCH flag.

STOP_SEARCH

The search should be stopped. This flag cannot be set at the same time as the RESTART_SEARCH flag.

Return value

S_OK

The search criteria was successfully set.

MAPI_E_TOO_COMPLEX

The service provider does not support the specified search criteria.

Remarks

The IMAPIContainer::SetSearchCriteria method establishes search criteria for a container that supports searches, typically a search-results folder. A search-results folder contains links to the messages that meet the search criteria; the actual messages are still stored in their original locations. The only unique data that is contained in a search-results folder is its contents table. The contents table of a search-results folder has the merged contents of the message store after the search restriction has been applied.

A search operation works only on this merged contents table; it does not search through other search-results folders. The search results return only the messages that match the search criteria; the folder hierarchy is not returned.

Control is returned to the client when the search has finished.

Notes to Implementers

Address book containers establish search criteria by applying restrictions to their contents tables. For more information about search criteria and address book containers, see Implementing Advanced Searching.

You should support open, copy, move, and delete operations on the messages within search-results folders, not on the search-results folder itself. Do not allow messages to be created within or copied into a search-results folder.

Notes to Callers

To search for message recipients, set lpRestriction to point to a subobject restriction with the ulSubObject member in the SSubRestriction structure set to PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients). To search for attachments, set the ulSubObject member to PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments). Set the lpRes member to point to a property restriction that describes the search criteria for the recipients or attachments.

For example, to look for file attachments that have the extension .mss, set ulSubObject to PR_MESSAGE_ATTACHMENTS and lpRes to a property restriction that matches PR_ATTACH_EXTENSION (PidTagAttachExtension) with .mss.

Setting the FOREGROUND_SEARCH flag in the ulSearchFlags parameter could cause a decrease in system performance.

You can use SetSearchCriteria to change the search criteria of a search already in progress. You can specify new restrictions, new lists of folders to search, and a new search priority, such as upgrading a search to a higher priority. Changes in search priority do not cause an existing search to restart, but other changes to search criteria can.

When you are through using a search-results folder, you can either delete the folder or let it remain open for later use. If you do delete the search-results folder, only message links are deleted. The actual messages remain in their parent folders.

For more information about search-results folders, see MAPI Search Folders.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
HierarchyTableDlg.cpp | CHierarchyTableDlg::OnEditSearchCriteria | MFCMAPI uses the IMAPIContainer::SetSearchCriteria method to write search criteria for a folder after a user has edited it.

See also

Reference

IMAPIContainer::GetContentsTable
IMAPIContainer::OpenEntry
IMAPIFolder::CreateFolder
IMAPIFolder : IMAPIContainer
SPropertyRestriction
SRestriction
SSubRestriction
IMAPIContainer : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIControl : IUnknown

 Copy code hover
[image]

IMAPIControl : IUnknown
See also Send feedback

Published: July 16, 2012

Enables and disables a button control, and performs tasks when a user of a client application clicks the enabled control. Service providers implement control objects to create custom buttons on dialog boxes, such as configuration property sheets, that are defined by using display tables.

For more information about how to work with display tables and control objects, see Display Tables.

Header file: | Mapidefs.h
Exposed by: | Control objects
Implemented by: | Service providers
Called by: | MAPI
Interface identifier: | IID_IMAPIControl
Pointer type: | LPMAPICONTROL

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous button control error.
Activate | Performs a task such as displaying a dialog box or starting a programmatic operation when a client application user clicks the button control.
GetState | Retrieves a value that indicates whether the button control is enabled or disabled.

See also

Concepts

MAPI Interfaces


IMAPIControl::Activate

 Copy code hover
[image]

IMAPIControl::Activate
See also Send feedback

Published: July 16, 2012

Performs a task such as displaying a dialog box or starting a programmatic operation when a client application user clicks the button control.

C++
HRESULT Activate(
  ULONG ulFlags,
  ULONG_PTR ulUIParam
);

Parameters

ulFlags

[in] Reserved; must be zero.

ulUIParam

[in] A handle to the parent window of the dialog box on which the button control appears.

Return value

S_OK

The button control was successfully activated.

Remarks

The IMAPIControl::Activate method performs tasks following a user's click of the button control. After the click occurs, as part of the processing of the display table, MAPI makes a call to Activate after first calling IMAPIControl::GetState to determine whether the button is enabled.

For more information about how to implement Activate and the other IMAPIControl : IUnknown methods, see Control Object Implementation.

See also

Reference

IMAPIControl::GetState
IMAPIControl : IUnknown


IMAPIControl::GetLastError

 Copy code hover
[image]

IMAPIControl::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous button control error.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] A handle to the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of the strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to a MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if the provider cannot supply a MAPIERROR structure with appropriate information.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

Service providers implement the IMAPIControl::GetLastError method to supply information about a prior method call that failed. MAPI can give users detailed information about the error by displaying the data from the MAPIERROR structure in a message or dialog box.

Notes to Implementers

You do not need to have information to include in the MAPIERROR structure for every error. It may not be possible to determine what the previous error was. If you have information, return S_OK and the appropriate data in the MAPIERROR structure. If no information is available, return S_OK and a pointer to NULL for the lppMAPIError parameter.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPIControl : IUnknown


IMAPIControl::GetState

 Copy code hover
[image]

IMAPIControl::GetState
See also Send feedback

Published: July 16, 2012

Retrieves a value that indicates whether the button control is enabled or disabled.

C++
HRESULT GetState(
  ULONG ulFlags,
  ULONG FAR * lpulState
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpulState

[out] A pointer to a value that indicates the state of the button control. One of the following values can be returned:

MAPI_DISABLED

The button control is disabled and cannot be clicked.

MAPI_ENABLED

The button control is enabled and can be clicked.

Return value

S_OK

The state of the button control was successfully retrieved.

Remarks

Service providers implement the IMAPIControl::GetState method to provide MAPI with the state of a button control. If the button is enabled, it can respond to a mouse click or key press. If it is disabled, the button appears dimmed and does not respond to a mouse click or key press.

For more information about how to implement GetState and the other IMAPIControl : IUnknown methods, see Control Object Implementation.

See also

Reference

IMAPIControl::Activate
IMAPIControl : IUnknown


IMAPIFolder : IMAPIContainer

 Copy code hover
[image]

IMAPIFolder : IMAPIContainer
See also Send feedback

Published: July 16, 2012

Performs operations on the messages and subfolders in a folder.

Header file: | Mapidefs.h
Exposed by: | Folder objects
Implemented by: | Message store providers
Called by: | Client applications and MAPI
Interface identifier: | IID_IMAPIFolder
Pointer type: | LPMAPIFOLDER
Transaction model: | Nontransacted

Vtable Order

CreateMessage | Creates a new message.
CopyMessages | Copies or moves one or more messages.
DeleteMessages | Deletes one or more messages.
CreateFolder | Creates a new subfolder.
CopyFolder | Copies or moves a subfolder.
DeleteFolder | Deletes a subfolder.
SetReadFlags | Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of one or more of the folder's messages, and manages the sending of read reports.
GetMessageStatus | Obtains the status associated with a message in a particular folder.
SetMessageStatus | Sets the status associated with a message.
SaveContentsSort | Sets the default sort order for a folder's contents table.
EmptyFolder | Deletes all messages and subfolders from a folder without deleting the folder itself.
Required properties | Access
PR_DISPLAY_NAME (PidTagDisplayNamePrefix) | Read/write
PR_ENTRYID (PidTagEntryId) | Read-only
PR_FOLDER_TYPE (PidTagFolderType) | Read/write
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_PARENT_ENTRYID (PidTagParentEntryId) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only
PR_STORE_ENTRYID (PidTagStoreEntryId) | Read-only
PR_STORE_RECORD_KEY (PidTagStoreRecordKey) | Read-only

See also

Concepts

MAPI Interfaces


IMAPIFolder::CopyFolder

 Copy code hover
[image]

IMAPIFolder::CopyFolder
See also Send feedback

Published: July 16, 2012

Copies or moves a subfolder.

C++
HRESULT CopyFolder(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  LPVOID lpDestFolder,
  LPSTR lpszNewFolderName,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the subfolder to copy or move.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the folder that the lpDestFolder parameter points to. Passing NULL causes the service provider to return the standard folder interface, IMAPIFolder : IMAPIContainer. Valid values for lpInterface include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, and IID_IMAPIFolder.

lpDestFolder

[in] A pointer to the open folder to receive the copied or moved subfolder.

lpszNewFolderName

[in] A pointer to the name of the copied or moved folder in its new destination. If lpszNewFolderName is set to NULL, the name of the source subfolder is used for the name of the destination folder.

ulUIParam

[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag in the ulFlags parameter is set.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls the copy or move operation. The following flags can be set:

COPY_SUBFOLDERS

All of the subfolders in the subfolder to be copied should also be copied. When COPY_SUBFOLDERS is not set for a copy operation, only the subfolder identified by lpEntryID is copied. With a move operation, the COPY_SUBFOLDERS behavior is the default regardless of whether the flag is set.

FOLDER_DIALOG

Requests the display of a progress indicator.

FOLDER_MOVE

The subfolder is to be moved instead of copied. If FOLDER_MOVE is not set, the subfolder is copied.

MAPI_DECLINE_OK

Informs the message store provider that if it implements CopyFolder by calling its support object's IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method, CopyFolder should instead immediately return MAPI_E_DECLINE_COPY.

MAPI_UNICODE

The name of the destination folder is in Unicode format. If the MAPI_UNICODE flag is not set, the folder name is in ANSI format.

Return value

S_OK

The specified folder has been successfully copied or moved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the message store provider does not support Unicode, or MAPI_UNICODE was not set and the message store provider supports only Unicode.

MAPI_E_COLLISION

The name of the folder being moved or copied is the same as that of a subfolder in the destination folder. The message store provider requires unique folder names.

MAPI_E_DECLINE_COPY

The provider implements this method by calling a support object method, and the caller has passed the MAPI_DECLINE_OK flag.

MAPI_E_FOLDER_CYCLE

The source folder directly or indirectly contains the destination folder. Significant work may have been performed before this condition was discovered, so the source and destination folder may be partially modified.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::CopyFolder method copies or moves a subfolder from one location to another. The subfolder being copied or moved is added to the destination folder as a subfolder.

Notes to Implementers

When the copy or move operation involves more than one folder, as indicated by setting the COPY_SUBFOLDERS flag, perform the operation as completely as possible for each folder. Sometimes one of the folders to be moved or copied does not exist or has already been moved or copied elsewhere. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Try to retain all message entry identifiers in the copied messages. You should also try to preserve entry identifiers, but it is not required.

Notes to Callers

Expect these return values under the following conditions.

Condition | Return value
CopyFolder has successfully copied or moved every message and subfolder. | S_OK
CopyFolder was unable to successfully copy or move every message and subfolder. | MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
CopyFolder was unable to complete. | Any error value except MAPI_E_NOT_FOUND

When CopyFolder is unable to complete, do not assume that no work was done. CopyFolder might have been able to copy or move one or more of the messages and subfolders before encountering the error.

If an entry identifier for a folder that does not exist is passed in lpEntryID, CopyFolder returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store's implementation.

Depending on the message store provider, the entry identifier of the original message may or may not be preserved in the copied message. You should preserve entry identifiers whenever possible, but it is not a requirement. You can generally depend on the following scenarios:

  • When you move a folder between two different types of message stores, the entry identifier is guaranteed to change.

  • When you move a folder between two message stores of the same type, the entry identifier almost always changes.

  • When you move a folder to another location in the same message store, the entry identifier may or may not change, depending on the message store provider.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnPasteFolder | MFCMAPI uses the IMAPIFolder::CopyFolder method to copy folders from one location to another. MFCMAPI remembers the source folder during the copy operation and actually performs the copy during the paste operation.

See also

Reference

IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IMAPIFolder::CopyMessages

 Copy code hover
[image]

IMAPIFolder::CopyMessages
See also Send feedback

Published: July 16, 2012

Copies or moves one or more messages.

C++
HRESULT CopyMessages(
  LPENTRYLIST lpMsgList,
  LPCIID lpInterface,
  LPVOID lpDestFolder,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpMsgList

[in] A pointer to an array of ENTRYLIST structures that identify the message or messages to copy or move.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the destination folder pointed to by the lpDestFolder parameter. Passing NULL results in the service provider returning the standard folder interface, IMAPIFolder : IMAPIContainer. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

lpDestFolder

[in] A pointer to the open folder to receive the copied or moved messages.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the client sets the MESSAGE_DIALOG flag in the ulFlags parameter and passes NULL in the lpProgress parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

MAPI_DECLINE_OK

Informs the message store provider to immediately return MAPI_E_DECLINE_COPY if it implements IMAPIFolder::CopyMessages by calling the support object's IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method.

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

MESSAGE_MOVE

The message or messages are to be moved instead of copied. If MESSAGE_MOVE is not set, the messages are copied.

Return value

S_OK

The message or messages have been successfully copied or moved.

MAPI_E_DECLINE_COPY

The provider implements this method by calling a support object method, and the caller has passed the MAPI_DECLINE_OK flag.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied or moved. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::CopyMessages method copies or moves messages to another folder.

Messages that are opened with read/write permission can be moved or copied.

Notes to Implementers

If you are copying messages to another message store without using the IMAPISupport::CopyMessages method, you must first call IMAPIFolder::SetReadFlags with the GENERATE_RECEIPT_ONLY flag set. The receiving message store is not responsible for generating read reports for the copied or moved messages. If you are calling IMAPISupport::CopyMessages to implement IMAPIFolder::CopyMessages, do not call SetReadFlags; MAPI will call it.

Your implementation can move or copy the messages in any order and generate read status reports in any order. That is, you can finish copying messages before generating any of the read status reports or send the reports before your implementation starts the copy operation. However, read reports should be sent for all messages to be copied, regardless of whether the copy is successful.

When the copy or move operation involves more than one message, perform the operation as completely as possible. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Try to maintain entry identifiers across move or copy operations. You should also preserve entry identifiers, although it is not required.

Send notifications when you move or copy messages so that clients are forewarned that their calls to the messages' IMAPIProp::SaveChanges methods may fail.

Do not include a message's status in the copy or move operation. Moving or copying a message status greatly affects performance.

Notes to Callers

Use IMAPIFolder::CopyMessages to populate search-results folders, where messages are often grouped by parent folder.

Expect these return values under the following conditions.

Condition | Return value
IMAPIFolder::CopyMessages has successfully copied or moved every message. | S_OK
IMAPIFolder::CopyMessages was unable to successfully copy or move every message. | MAPI_W_PARTIAL_COMPLETION
IMAPIFolder::CopyMessages was unable to complete. | Any error value

When IMAPIFolder::CopyMessages is unable to complete, do not assume that no work was done. IMAPIFolder::CopyMessages might have been able to copy or move one or more messages before encountering the error.

See also

Reference

IMAPIFolder : IMAPIContainer


IMAPIFolder::CreateFolder

 Copy code hover
[image]

IMAPIFolder::CreateFolder
See also Send feedback

Published: July 16, 2012

Creates a new subfolder.

C++
HRESULT CreateFolder(
  ULONG ulFolderType,
  LPSTR lpszFolderName,
  LPSTR lpszFolderComment,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPMAPIFOLDER FAR * lppFolder
);

Parameters

ulFolderType

[in] The type of folder to create. The following flags can be set:

FOLDER_GENERIC

A generic folder should be created.

FOLDER_SEARCH

A search-results folder should be created.

lpszFolderName

[in] A pointer to a string that contains the name for the new folder. This name is the basis for the new folder's PR_DISPLAY_NAME (PidTagDisplayName) property.

lpszFolderComment

[in] A pointer to a string that contains a comment associated with the new folder. This string becomes the value of the new folder's PR_COMMENT (PidTagComment) property. If NULL is passed, the folder has no initial comment.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the new folder. Passing NULL causes the message store provider to return the standard folder interface, IMAPIFolder : IMAPIContainer. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

ulFlags

[in] A bitmask of flags that controls how the folder is created. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows CreateFolder to return successfully, possibly before the new folder is fully available to the calling client. If the new folder is not available, making a subsequent call to it can cause an error.

MAPI_UNICODE

The name of the folder is in Unicode format. If the MAPI_UNICODE flag is not set, the folder name is in ANSI format.

OPEN_IF_EXISTS

Allows the method to succeed even if the folder named in the lpszFolderName parameter already exists by opening the existing folder that has that name. Note that message store providers that allow sibling folders to have the same name might not open an existing folder if more than one exists with the supplied name.

lppFolder

[out] A pointer to a pointer to the newly created folder.

Return value

S_OK

The new folder has been successfully created or opened, if the OPEN_IF_EXISTS flag is set.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_COLLISION

A folder that has the name given in the lpszFolderName parameter already exists. Folder names must be unique.

Remarks

The IMAPIFolder::CreateFolder method creates a subfolder in the current folder and assigns an entry identifier to the new folder.

Notes to Callers

When CreateFolder returns, be aware that the entry identifier for the new folder might not be available. Some message store providers do not make entry identifiers available until after you have called the new folder's IMAPIProp::SaveChanges method to permanently save it. This is especially true if you have set the MAPI_DEFERRED_ERRORS flag.

Be aware that some message store providers always point the lppFolder parameter to the folder's standard interface, regardless of the value that you pass in for the lpInterface parameter. Because the interface pointer that is returned might not be of the type that you expect, call the new folder's IMAPIProp::GetProps method to retrieve the PR_OBJECT_TYPE (PidTagObjectType) property. If necessary, cast the pointer to a more appropriate type before you make other calls.

Most message store providers require the name of the new folder to be unique with respect to the names of its sibling folders. Be able to handle the MAPI_E_COLLISION error value, which is returned if this rule is not followed.

To determine the entry identifier of the newly created folder, call the new folder's IMAPIProp::GetProps method to retrieve its PR_ENTRYID (PidTagEntryId) property.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnCreateSubFolder | MFCMAPI uses the CMsgStoreDlg::OnCreateSubFolder method to create new folders in MFCMAPI.

See also

Reference

IMAPIProp::GetProps
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IMAPIFolder::CreateMessage

 Copy code hover
[image]

IMAPIFolder::CreateMessage
See also Send feedback

Published: July 16, 2012

Creates a new message.

C++
HRESULT CreateMessage(
  LPCIID lpInterface,
  ULONG ulFlags,
  LPMESSAGE FAR * lppMessage
);

Parameters

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the new message. Valid interface identifiers include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, and IID_IMAPIFolder. Passing NULL causes the message store provider to return the standard message interface, IMessage : IMAPIProp.

ulFlags

[in] A bitmask of flags that controls how the message is created. The following flags can be set:

ITEMPROC_FORCE

Indicates to the personal folder store (PST) that the message is eligible for rules processing before the store notifies any listening client of the arrival of the new message. Rules processing only applies to new messages that are created on a server that is not a Exchange Server, because Exchange Server processes rules for messages on the server. Therefore, the provider or client creating the message must pass this flag in combination with saving a message with IMAPIPProp::SaveChanges using NON_EMS_XP_SAVE, which indicates that the server is not an Exchange Server.

MAPI_ASSOCIATED

The message to be created should be included in the associated contents table instead of the standard contents table. Associated messages are hidden from user interaction.

MAPI_DEFERRED_ERRORS

CreateMessage is allowed to succeed even if the create operation has not fully completed. This implies that the new message might not be immediately available to the caller.

lppMessage

[out] A pointer to a pointer to the newly created message.

Return value

S_OK

The message was successfully created.

Remarks

The IMAPIFolder::CreateMessage method creates a new message with generic or associated content and assigns an entry identifier. The entry identifier consists of a part that represents the message store provider and a part that represents the individual message.

Notes to Implementers

You can choose whether to set all of the required message properties in CreateMessage or in the message's IMAPIProp::SaveChanges method. You do not have to make these properties available until a successful save has occurred.

For more information about how to work with associated information, see Folder-Associated Information Tables and Contents Tables.

Notes to Callers

Some message store providers allow the entry identifier of the new message to be available immediately after CreateMessage returns; other message store providers delay its availability until the message is saved. Because not all message store providers generate an entry identifier for a new message until you have called the message's IMAPIProp::SaveChanges method, you may be unable to access the entry identifier when CreateMessage returns. Also, the new message may not be included in the folder's contents table until the save occurs.

Expect the entry identifier assigned to the new message to be unique not only in the current message store, but most likely across all of the message stores that are open at the same time. One exception to this rule occurs when multiple entries for a message store appear in the profile. This causes the message store to be opened multiple times and entry identifiers to be duplicated.

To create an outgoing message, call the Outbox folder's IMAPIFolder::CreateMessage method.

If you delete a folder that contains a new message before the message is saved, the results are undefined.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolder::OnNewMessage | MFCMAPI uses the IMAPIFolder::CreateMessage method to create and save a new message.

See also

Reference

IMAPIProp::SaveChanges
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IMAPIFolder::DeleteFolder

 Copy code hover
[image]

IMAPIFolder::DeleteFolder
See also Send feedback

Published: July 16, 2012

Deletes a subfolder.

C++
HRESULT DeleteFolder(
  ULONG_PTR cbEntryID,
  LPENTRYID lpEntryID,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the subfolder to delete.

ulUIParam

[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls the deletion of the subfolder. The following flags can be set:

DEL_FOLDERS

All subfolders of the subfolder pointed to by lpEntryID should be deleted.

DEL_MESSAGES

All messages in the subfolder pointed to by lpEntryID should be deleted.

FOLDER_DIALOG

A progress indicator should be displayed while the operation proceeds.

Return value

S_OK

The specified folder has been successfully deleted.

MAPI_E_HAS_FOLDERS

The subfolder being deleted contains subfolders, and the DEL_FOLDERS flag was not set. The subfolders were not deleted.

MAPI_E_HAS_MESSAGES

The subfolder being deleted contains messages, and the DEL_MESSAGES flag was not set. The subfolder was not deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the entries were successfully deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::DeleteFolder method deletes a subfolder. By default, DeleteFolder operates only on empty folders, but you can use it successfully on non-empty folders by setting two flags: DEL_FOLDERS and DEL_MESSAGES. Only empty folders or folders that set both the DEL_FOLDERS and DEL_MESSAGES flags on the DeleteFolder call can be deleted. DEL_FOLDERS enables all of the folder's subfolders to be removed; DEL_MESSAGES enables all of the folder's messages to be removed.

Notes to Implementers

When the delete operation involves more than one folder, perform the operation as completely as possible for each folder. Sometimes one of the folders to be deleted does not exist or has been moved or copied elsewhere. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Notes to Callers

Expect these return values under the following conditions.

Condition | Return value
DeleteFolder has successfully deleted every message and subfolder. | S_OK
DeleteFolder was unable to successfully delete every message and subfolder. | MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
DeleteFolder was unable to complete. | Any error value except MAPI_E_NOT_FOUND

When DeleteFolder is unable to complete, do not assume that no work was done. DeleteFolder might have been able to delete one or more of the messages and subfolders before encountering the error.

If one or more subfolders cannot be deleted, DeleteFolder returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store provider's implementation.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnDeleteSelectedItem | MFCMAPI uses the IMAPIFolder::DeleteFolder method to delete folders.

See also

Reference

IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IMAPIFolder::DeleteMessages

 Copy code hover
[image]

IMAPIFolder::DeleteMessages
See also Send feedback

Published: July 16, 2012

Deletes one or more messages.

C++
HRESULT DeleteMessages(
  LPENTRYLIST lpMsgList,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpMsgList

[in] A pointer to an ENTRYLIST structure that contains the number of messages to delete and an array of ENTRYID structures that identify the messages.

ulUIParam

[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls how the messages are deleted. The following flags can be set:

DELETE_HARD_DELETE

Permanently removes all messages, including soft-deleted ones.

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

Return value

S_OK

The specified message or messages were successfully deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the messages were successfully deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::DeleteMessages method deletes messages from a folder. Messages that do not exist, that have been moved elsewhere, that are open with read/write permission, or that are currently submitted cannot be deleted.

Notes to Implementers

When the delete operation involves more than one message, perform the operation as completely as possible for each folder, even if one or more of the messages cannot be deleted. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Notes to Callers

Expect these return values under the following conditions.

Condition | Return value
DeleteMessages has successfully deleted every message. | S_OK
DeleteMessages was unable to successfully delete every message and subfolder. | MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
DeleteMessages was unable to complete. | Any error value except MAPI_E_NOT_FOUND

When DeleteMessages is unable to complete, do not assume that no work was done. DeleteMessages might have been able to delete one or more of the messages before encountering the error.

DeleteMessages returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store's implementation.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnDeleteSelectedItem | MFCMAPI uses the IMAPIFolder::DeleteMessages method to delete the specified messages.

See also

Reference

ENTRYID
ENTRYLIST
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample
Using Macros for Error Handling


IMAPIFolder::EmptyFolder

 Copy code hover
[image]

IMAPIFolder::EmptyFolder
See also Send feedback

Published: July 16, 2012

Deletes all messages and subfolders from a folder without deleting the folder itself.

C++
HRESULT EmptyFolder(
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls how the folder is emptied. The following flags can be set:

DEL_ASSOCIATED

Deletes all subfolders, including subfolders that contain messages with associated content. The DEL_ASSOCIATED flag has meaning only for the top-level folder the call acts on.

DELETE_HARD_DELETE

Permanently removes all messages, including soft-deleted ones.

FOLDER_DIALOG

Displays a progress indicator while the operation proceeds.

Return value

S_OK

The folder was successfully emptied.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but the folder was not completely emptied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::EmptyFolder method deletes all of a folder's contents without deleting the folder itself.

During an EmptyFolder call, submitted messages are not deleted.

A folder's associated contents include messages that are used to describe views, rules, custom forms, and custom solution storage, and can also include form definitions.

Notes to Implementers

Do not call the IMsgStore::AbortSubmit method for messages in the folder that have been submitted. Submitted messages are not deleted.

Notes to Callers

Expect these return values under the following conditions.

Condition | Return value
EmptyFolder has successfully emptied the folder. | S_OK
EmptyFolder was unable to completely empty the folder. | MAPI_W_PARTIAL_COMPLETION
EmptyFolder was unable to complete. | Any error value

When EmptyFolder is unable to complete, do not assume that no work was done. EmptyFolder might have been able to delete some of the folder's contents before encountering the error.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnEmptyFolder | MFCMAPI uses the IMAPIFolder::EmptyFolder method to delete the contents of the specified folder.

See also

Reference

IMsgStore::AbortSubmit
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample
Using Macros for Error Handling


IMAPIFolder::GetMessageStatus

 Copy code hover
[image]

IMAPIFolder::GetMessageStatus
See also Send feedback

Published: July 16, 2012

Obtains the status associated with a message in a particular folder (for example, whether that message is marked for deletion).

C++
HRESULT GetMessageStatus(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  ULONG FAR * lpulMessageStatus
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for the message whose status is obtained.

ulFlags

[in] Reserved; must be zero.

lpulMessageStatus

[out] A pointer to a pointer to a bitmask of flags that indicate the message's status. Bits 0 through 15 are reserved and must be zero; bits 16 through 31 are available for implementation-specific use. The following flags can be set:

MSGSTATUS_DELMARKED

The message has been marked for deletion.

MSGSTATUS_HIDDEN

The message is not to be displayed.

MSGSTATUS_HIGHLIGHTED

The message is to be displayed highlighted.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

Return value

S_OK

The message status was successfully retrieved.

Remarks

The IMAPIFolder::GetMessageStatus method returns the status of a message. Message status is stored in the message's PR_MSG_STATUS (PidTagMessageStatus) property.

Notes to Implementers

How the message status bits are set, cleared, and used depends completely on your implementation, except that bits 0 through 15 are reserved and must be zero. If you store messages in the IPM subtree, MAPI reserves bits 16 through 31 for use by IPM clients. If you store messages in other subtrees, you can use bits 16 through 31 for your own purposes.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetNextMessage | MFCMAPI uses the IMAPIFolder::GetMessageStatus method to get the status of the next message to be displayed.
MAPIFormFunctions.cpp | OpenMessageNonModal and OpenMessageModal | MFCMAPI uses the IMAPIFolder::GetMessageStatus method to get the status of the message to be displayed to pass to the form viewer, which is either CMyMAPIFormViewer or IMAPISession::ShowForm.

See also

Reference

IMAPIFolder::SetMessageStatus
IMAPISession::ShowForm
PidTagMessageStatus Canonical Property
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample


IMAPIFolder::SaveContentsSort

 Copy code hover
[image]

IMAPIFolder::SaveContentsSort
See also Send feedback

Published: July 16, 2012

Sets the default sort order for a folder's contents table.

C++
HRESULT SaveContentsSort(
  LPSSortOrderSet lpSortCriteria,
  ULONG ulFlags
);

Parameters

lpSortCriteria

[in] A pointer to an SSortOrderSet structure that contains the default sort order.

ulFlags

[in] A bitmask of flags that controls how the default sort order is set. The following flag can be set:

RECURSIVE_SORT

The default sort order set applies to the indicated folder and to all its subfolders.

Return value

S_OK

The sort order was successfully saved.

MAPI_E_NO_SUPPORT

The message store provider does not support saving a sort order for its folder contents tables.

Remarks

The IMAPIFolder::SaveContentsSort method establishes a default sort order for a folder's contents table. That is, when a client calls the folder's IMAPIContainer::GetContentsTable method after the code calls SaveContentsSort, the rows in the returned contents table will appear in the order established by SaveContentsSort.

Not all message store providers support SaveContentsSort; it is acceptable for message store providers to return MAPI_E_NO_SUPPORT from the SaveContentsSort method.

See also

Reference

IMAPIContainer::GetContentsTable
SSortOrderSet
IMAPIFolder : IMAPIContainer


IMAPIFolder::SetMessageStatus

 Copy code hover
[image]

IMAPIFolder::SetMessageStatus
See also Send feedback

Published: July 16, 2012

Sets the status associated with a message (for example, whether that message is marked for deletion).

C++
HRESULT SetMessageStatus(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulNewStatus,
  ULONG ulNewStatusMask,
  ULONG FAR * lpulOldStatus
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for the message whose status is set.

ulNewStatus

[in] The new status to be assigned.

ulNewStatusMask

[in] A bitmask of flags that is applied to the new status and indicates the flags to be set. The following flags can be set:

MSGSTATUS_DELMARKED

The message has been marked for deletion.

MSGSTATUS_HIDDEN

The message is not to be displayed.

MSGSTATUS_HIGHLIGHTED

The message is to be displayed highlighted.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

lpulOldStatus

[out] A pointer to the previous status of the message.

Return value

S_OK

The message status was successfully set.

Remarks

The IMAPIFolder::SetMessageStatus method sets the message status to the value that is stored in its PR_MSG_STATUS (PidTagMessageStatus) property.

Notes to Implementers

How the message status bits are set, cleared, and used depends completely on your implementation, except that bits 0 through 15 are reserved and must be zero.

A remote transport provider's implementation of this method must follow the semantics described here. There are no special considerations. Clients use this method to set the MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE bits to indicate that a particular message is to be downloaded or deleted from the remote message store. A remote transport provider does not have to implement the related IMAPIFolder::GetMessageStatus method. Clients must look in the folder's contents table to determine the status of a message.

Notes to Callers

You can use the PR_MSG_STATUS property of a message to negotiate a message lockout operation with other clients. Designate a bit as the lockout bit. To determine whether the lockout bit was set, examine the previous value for message status in the lpulOldStatus parameter. Use the other bits in the ulNewStatus parameter to track message status without interfering with the lockout bit.

See also

Reference

IMAPIFolder::GetMessageStatus
PidTagMessageStatus Canonical Property
IMAPIFolder : IMAPIContainer


IMAPIFolder::SetReadFlags

 Copy code hover
[image]

IMAPIFolder::SetReadFlags
See also Send feedback

Published: July 16, 2012

Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of one or more of the folder's messages, and manages the sending of read reports.

C++
HRESULT SetReadFlags(
  LPENTRYLIST lpMsgList,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpMsgList

[in] A pointer to an array of ENTRYLIST structures that identify the message or messages that have read flags to set or clear. If lpMsgList is set to NULL, the read flags for all the folder's messages are set or cleared.

ulUIParam

[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using MAPI's implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls the setting of a message's read flag and the processing of read reports. The following flags can be set:

CLEAR_READ_FLAG

The MSGFLAG_READ flag should be cleared in PR_MESSAGE_FLAGS and a read report should not be sent.

CLEAR_NRN_PENDING

The MSGFLAG_NRN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and an unread report should not be sent.

CLEAR_RN_PENDING

The MSGFLAG_RN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and a read report should not be sent.

GENERATE_RECEIPT_ONLY

A read report should be sent if one is pending, but there should be no change in the state of the MSGFLAG_READ flag.

MAPI_DEFERRED_ERRORS

Allows SetReadFlags to return successfully, possibly before the operation has completed.

MESSAGE_DIALOG

Displays a progress indicator while the operation proceeds.

SUPPRESS_RECEIPT

A pending read report should be canceled if a read report had been requested and this call changes the state of the message from unread to read. If this call does not change the state of the message, the message store provider can ignore this flag.

Return value

S_OK

The read flag for the specified message or messages was successfully set or cleared.

MAPI_E_NO_SUPPRESS

The message store provider does not support the suppression of read reports.

MAPI_E_INVALID_PARAMETER

One of the following incompatible combinations of flags is set in the ulFlags parameter:

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

  • CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the messages were successfully processed. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::SetReadFlags method sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property of one or more of the folder's messages. Setting the MSGFLAG_READ flag marks a message as read, which does not necessarily indicate that the intended recipient has actually read the message.

SetReadFlags also manages the sending of read reports.

The read flag cannot be changed for the following:

  • Messages that do not exist.

  • Messages that have been moved elsewhere.

  • Messages that are open with read/write permission.

  • Messages that are currently submitted.

Notes to Implementers

You can decide not to support the sending of read reports and the request to suppress read reports. To avoid suppressing a read report, return MAPI_E_NO_SUPPRESS when SetReadFlags is called with SUPPRESS_RECEIPT set in the ulFlags parameter.

When the lpMsgList parameter points to more than one message, perform the operation as completely as possible for each message. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

If none of the flags are set in the ulFlags parameter, the following rules apply:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it immediately and send any pending read reports if the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set.

When the SUPPRESS_RECEIPT flag is set, the following rules apply:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it and cancel any pending read reports.

When the CLEAR_READ_FLAG flag is set, clear the MSGFLAG_READ flag in each message's PR_MESSAGE_FLAGS property and do not send any read reports.

When the GENERATE_RECEIPT_ONLY flag is set, send any pending read reports. Do not set or clear MSGFLAG_READ.

When both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, set PR_READ_RECEIPT_REQUESTED to FALSE if it is set and do not send a read report.

Notes to Callers

Expect these return values under the following conditions.

Condition | Return value
SetReadFlags has successfully processed every message. | S_OK
SetReadFlags was unable to successfully process every message. | MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND
SetReadFlags was unable to complete. | Any error value except MAPI_E_NOT_FOUND

When SetReadFlags is unable to complete, do not assume that no work was done. SetReadFlags might have been able to set or clear the MSGFLAG_READ flag for one or more of the messages before encountering the error.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnSetReadFlag | MFCMAPI uses the IMAPIFolder::SetReadFlags method to manually set the read status on the specified messages.

See also

Reference

ENTRYLIST
IMessage::SetReadFlag
PidTagMessageFlags Canonical Property
PidTagReadReceiptRequested Canonical Property
IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample
Using Macros for Error Handling


IMAPIForm : IUnknown

 Copy code hover
[image]

IMAPIForm : IUnknown
See also Send feedback

Published: July 16, 2012

Enables form viewers to work with form view contexts and form notification, to perform form verbs, and to shut down forms.

Header file: | Mapiform.h
Exposed by: | Form objects
Implemented by: | Form servers
Called by: | Form viewers
Interface identifier: | IID_IMAPIForm
Pointer type: | LPMAPIFORM

Vtable Order

SetViewContext | Establishes a view context for the form.
GetViewContext | Returns the current view context for the form.
ShutdownForm | Closes the form.
DoVerb | Requests that the form perform whatever tasks it associates with a specific verb.
Advise | Registers a form viewer for notifications about events that affect the form.
Unadvise | Cancels a registration for notifications with a form viewer previously established by calling Advise.
GetLastError | Returns a MAPIERROR structure that contains information about the previous error occurring to the form object.

See also

Concepts

MAPI Interfaces


IMAPIForm::Advise

 Copy code hover
[image]

IMAPIForm::Advise
See also Send feedback

Published: July 16, 2012

Registers a form viewer for notifications about events that affect the form.

C++
HRESULT Advise(
  LPMAPIVIEWADVISESINK pAdvise,
  ULONG FAR * pulConnection
);

Parameters

pAdvise

[in] A pointer to a view advise sink object to receive the subsequent notifications.

pulConnection

[out] A pointer to a nonzero value that represents a successful notification registration.

Return value

S_OK

The registration was successful.

E_OUTOFMEMORY

The registration was unsuccessful because of insufficient memory.

Remarks

Form viewers call a form's IMAPIForm::Advise method to register for notification when changes occur to the form.

Notes to Implementers

Keep a copy of the view advise sink pointer passed in the pAdvise parameter so that you can use it to call the appropriate IMAPIViewAdviseSink method when an event occurs. Call the view advise sink's IUnknown::AddRef method to retain the pointer until notification registration is canceled. Set the contents of the pulConnection parameter to a nonzero number.

Many forms implement a helper object to handle the registration and subsequent notification of events.

For more information about the notification process in general, see Event Notification in MAPI.

For more information about notification and forms, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIForm::Unadvise
IMAPIViewAdviseSink : IUnknown
IMAPIForm : IUnknown

Concepts

Event Notification in MAPI
Sending and Receiving Form Notifications


IMAPIForm::DoVerb

 Copy code hover
[image]

IMAPIForm::DoVerb
See also Send feedback

Published: July 16, 2012

Requests that the form perform whatever tasks it associates with a specific verb.

C++
HRESULT DoVerb(
  LONG iVerb,
  LPMAPIVIEWCONTEXT lpViewContext,
  ULONG_PTR hwndParent,
  LPCRECT lprcPosRect
);

Parameters

iVerb

[in] The number associated with one of the form's verbs.

lpViewContext

[in] A pointer to a view context object. The lpViewContext parameter can be null.

hwndParent

[in] A handle to the parent window of any dialog boxes or windows this method displays. The hwndParent parameter should be null if the dialog box or window is not modal.

lprcPosRect

[in] A pointer to a Win32 RECT structure that contains the size and position of the form's window.

Return value

S_OK

The verb was successfully invoked.

OLEOBJ_S_CANNOT_DOVERB_NOW

The verb represented by the iVerb parameter is valid, but the form cannot perform the operations currently associated with it.

Remarks

Form viewers call the IMAPIForm::DoVerb method to request that the form perform the tasks that it associates with each verb that the form supports.

Each of the supported verbs is identified by a numeric value, passed to DoVerb in the iVerb parameter. Typical implementations of DoVerb contain a switch statement that tests the values that are valid for the iVerb parameter for the form.

Notes to Implementers

If the form viewer specifies a view context in the lpViewContext parameter, use it in your DoVerb implementation instead of the view context passed in an earlier call to the IMAPIForm::SetViewContext method. Make whatever changes are necessary to your internal data structures and do not save the view context.

Perform the following tasks in your DoVerb implementation:

  • Execute whatever code is necessary for the particular verb that is associated with the iVerb parameter.

  • If necessary, restore the original view context.

  • If an unknown verb number was passed in, return MAPI_E_NO_SUPPORT. Otherwise, return a result based on the success or failure of whatever verb was executed.

  • Close the form. It is always your responsibility to close the form after a DoVerb call completes.

Some verbs, such as Print, should be modal with respect to the DoVerb call — that is, the indicated operation must be finished before the DoVerb call returns.

To obtain the RECT structure used by a form's window, call the GetWindowRect function.

Do not save the handle in the hwndParent parameter because, although it usually remains valid until the completion of DoVerb, it can be destroyed immediately upon the call's return.

Notes to Callers

You can make non-modal verbs act as modal verbs by pointing lpViewContext to a view context implementation that returns the VCSTATUS_MODAL flag from its IMAPIViewContext::GetViewStatus method.

For more information about verbs in MAPI, see Form Verbs. For more information about how verbs are handled in OLE, see OLE and Data Transfer.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::CallDoVerb | MFCMAPI uses the IMAPIForm::DoVerb method to invoke a verb on a form.

See also

Reference

IMAPIForm::SetViewContext
IMAPIViewContext::GetViewStatus
IMAPIForm : IUnknown

Concepts

MFCMAPI as a Code Sample
Form Verbs


IMAPIForm::GetLastError

 Copy code hover
[image]

IMAPIForm::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error generated by the form object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

If set, the strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. This parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IMAPIForm::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can use the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one, only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was, or it has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
IMAPIForm : IUnknown


IMAPIForm::GetViewContext

 Copy code hover
[image]

IMAPIForm::GetViewContext
See also Send feedback

Published: July 16, 2012

Returns the current view context for the form.

C++
HRESULT GetViewContext(
  LPMAPIVIEWCONTEXT FAR * ppViewContext
);

Parameters

ppViewContext

[out] A pointer to a pointer to the form's view context.

Return value

S_OK

The form's current view context was successfully returned.

S_FALSE

There is no view context for the form.

Remarks

Form viewers call GetViewContext to obtain a pointer to the view context established in a previous call to IMAPIForm::SetViewContext. If no prior call has been made to SetViewContext, GetViewContext sets ppViewContext to NULL.

Notes to Implementers

Copy your form's view context pointer into the pointer passed in by the calling form viewer in the ppViewContext parameter. If the form does not have a view context, set ppViewContext to NULL.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | OpenMessageNonModal | MFCMAPI uses the IMAPIForm::GetViewContext method to check whether a form has a view context.

See also

Reference

IMAPIViewContext : IUnknown
IMAPIForm : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIForm::SetViewContext

 Copy code hover
[image]

IMAPIForm::SetViewContext
See also Send feedback

Published: July 16, 2012

Establishes a view context for the form.

C++
HRESULT SetViewContext(
  LPMAPIVIEWCONTEXT pViewContext
);

Parameters

pViewContext

[in] A pointer to the new view context for the form.

Return value

S_OK

The view context was successfully set.

Remarks

Form viewers call the IMAPIForm::SetViewContext method to establish a particular form view context as current. A form can have only one view context at a time.

Notes to Implementers

Most form servers implement SetViewContext by using the following algorithm:

  • If a view context already exists for the form, cancel the form's registration by calling the IMAPIViewContext::SetAdviseSink method with null in the pmnvs parameter, and then call the view context's IUnknown::Release method to decrement its reference count.

  • If the new view context is not null, call IMAPIViewContext::SetAdviseSink by using the pViewContext parameter to set up a new view advise sink.

  • If the new view context is not null, call the IMAPIViewContext::GetViewStatus method to determine which status flags have been set.

  • If the new view context is not null, store it and call its IUnknown::AddRef method to increment its reference count.

  • Update any user interface elements that depend on the view context.

Depending on the status flags returned from IMAPIViewContext::GetViewStatus, SetViewContext can also perform other actions. For example, if the VCSTATUS_NEXT and VCSTATUS_PREV flags are returned, SetViewContext can enable the Next and Previous buttons for the new view context.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | CreateAndDisplayNewMailInFolder | MFCMAPI uses the IMAPIForm::SetViewContext method to set MFCMAPI's view context on the form before the form is displayed.

See also

Reference

IMAPIViewContext::GetViewStatus
IMAPIViewContext::SetAdviseSink
IMAPIForm : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIForm::ShutdownForm

 Copy code hover
[image]

IMAPIForm::ShutdownForm
See also Send feedback

Published: July 16, 2012

Closes the form.

C++
HRESULT ShutdownForm(
  ULONG ulSaveOptions
);

Parameters

ulSaveOptions

[in] A value that controls how or whether data in the form is saved before the form is closed. One of the following flags can be set:

SAVEOPTS_NOSAVE

Form data should not be saved.

SAVEOPTS_PROMPTSAVE

The user should be prompted to save any changed data in the form.

SAVEOPTS_SAVEIFDIRTY

Form data should be saved if it has changed since the last save. If no user interface is being displayed, the form can optionally switch to using the functionality for the SAVEOPTS_NOSAVE option.

Return value

S_OK

The form was closed.

E_UNEXPECTED

The form was already closed by a prior call to ShutdownForm.

Remarks

Form viewers call the IMAPIForm::ShutdownForm method to close a form.

Notes to Implementers

Perform the following tasks in your implementation of ShutdownForm:

  1. Check that a viewer has not already called ShutdownForm, and return E_UNEXPECTED if it has. Although this is unlikely, you should check.

  2. Call your form's IUnknown::AddRef method so that storage for the form and any internal data structures remain available until processing is finished.

  3. Determine whether there are any unsaved changes to the form's data. Save unsaved data according to how the ulSaveOptions parameter is set by calling your viewer's IMAPIMessageSite::SaveMessage method.

  4. Destroy your form's user interface window.

  5. Release your form's message and message site objects by calling their IUnknown::Release methods.

  6. Notify all registered viewers of the pending shutdown by calling their IMAPIViewAdviseSink::OnShutdown methods.

  7. Call the IMAPIViewContext::SetAdviseSink method to cancel your form's registration for notification by setting the advise sink pointer to null.

  8. Call the MAPIFreeBuffer function to free the memory for your form's properties.

  9. Call your form's IUnknown::Release method, matching the AddRef call made in step 2.

  10. Return S_OK.

Note Note

After these actions have been completed, the only valid methods on the form object that may be called are those from the IUnknown interface.

Notes to Callers

When ShutdownForm returns, regardless of whether it returns an error, release the form by calling its IUnknown::Release method. You can safely ignore any errors returned by ShutdownForm.

See also

Reference

IMAPIMessageSite::SaveMessage
IMAPIViewAdviseSink::OnShutdown
IMAPIViewContext::SetAdviseSink
MAPIFreeBuffer
IMAPIForm : IUnknown


IMAPIForm::Unadvise

 Copy code hover
[image]

IMAPIForm::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels a registration for notifications with a form viewer previously established by calling IMAPIForm::Advise.

C++
HRESULT Unadvise(
  ULONG ulConnection
);

Parameters

ulConnection

[in] A connection number that identifies the notification registration to be canceled.

Return value

S_OK

The registration was canceled.

E_INVALIDARG

The connection number passed in the ulConnection parameter does not represent a valid registration.

Remarks

Form viewers call the IMAPIForm::Unadvise method to cancel a registration for notification that they first established by calling the IMAPIForm::Advise method.

Notes to Implementers

Discard the pointer that you are holding to the form viewer's view advise sink by calling its IUnknown::Release method. Generally, Release is called during the Unadvise call. However, if another thread is in the process of calling one of the IMAPIViewAdviseSink methods for the view advise sink, delay the Release call until the IMAPIViewAdviseSink method returns.

See also

Reference

IMAPIForm::Advise
IMAPIViewAdviseSink : IUnknown
IMAPIForm : IUnknown


IMAPIFormAdviseSink : IUnknown

 Copy code hover
[image]

IMAPIFormAdviseSink : IUnknown
See also Send feedback

Published: July 16, 2012

Enables form servers to receive notifications from form viewers.

Header file: | Mapiform.h
Exposed by: | Form advise sink objects
Implemented by: | Form servers
Called by: | Form viewers
Interface identifier: | IID_IMAPIFormAdviseSink
Pointer type: | LPMAPIFORMADVISESINK

Vtable Order

OnChange | Indicates that a change has occurred in the status of the form viewer.
OnActivateNext | Indicates whether the form can handle the message class of the next message to display.

Remarks

Form servers use a form advise sink object to implement IMAPIFormAdviseSink instead of including it with their form object. Therefore, form viewers should expect a failed call to a form's IUnknown::QueryInterface method to obtain a pointer to this interface.

Form servers call a viewer's IMAPIViewContext::SetAdviseSink method to register for notifications. A pointer to their IMAPIFormAdviseSink implementation is included as a parameter.

See also

Concepts

MAPI Interfaces


IMAPIFormAdviseSink::OnActivateNext

 Copy code hover
[image]

IMAPIFormAdviseSink::OnActivateNext
See also Send feedback

Published: July 16, 2012

Indicates whether the form can handle the message class of the next message to display.

C++
HRESULT OnActivateNext(
  LPCSTR lpszMessageClass,
  ULONG ulMessageStatus,
  ULONG ulMessageFlags,
  LPPERSISTMESSAGE FAR * ppPersistMessage
);

Parameters

lpszMessageClass

[in] A pointer to the message class of the next message.

ulMessageStatus

[in] A bitmask of client-defined or provider-defined flags, copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the next message to display, that provides status information regarding the contents table that the message is included in.

ulMessageFlags

[in] A pointer to a bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the next message to display that indicates the current state of the message.

ppPersistMessage

[out] A pointer to a pointer to the IPersistMessage implementation for the form object used for the new form, if a new form is required. A pointer to NULL can be returned if the current form object can be used to display and save the next message.

Return value

S_OK

The notification was successful and the form can handle the next message.

S_FALSE

The form does not handle the message class of the next message.

Remarks

Form viewers call the IMAPIFormAdviseSink::OnActivateNext method to help the form determine whether it can display the next message in a folder. The next message could be a message of any class, but typically it is of the same class or a related class. This makes the process of reading multiple messages of the same class more efficient by enabling client applications to reuse form objects whenever possible.

Most form objects will use the message class pointed to by the lpszMessageClass parameter to determine whether they can handle the next message. Usually a form can handle messages that belong to classes of which the form's default class is a subclass, in addition to messages that belong to the default class. However, a form can use other factors to determine without question whether a message can be handled, such as the sent or unsent status of the next message.

Notes to Implementers

Return S_OK and NULL in the ppPersistMessage parameter if the form can handle the message class. If the form can create a new form that can handle the message that the form is unable to handle, follow these steps:

  1. Call your form's class factory to create an instance of a new form object.

  2. Store that instance in the contents of the ppPersistMessage pointer parameter.

  3. Return S_OK.

The form viewer will load the message by using the IPersistMessage::Load method that belongs to the object pointed to by ppPersistMessage.

If neither the form nor a form that you can create can handle the next message, return S_FALSE. However, in general, forms should not return this value because it causes decreased performance in the form viewer.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | CMyMAPIFormViewer::ActivateNext | MFCMAPI uses the IMAPIFormAdviseSink::OnActivateNext method to implement the IMAPIViewContext::ActivateNext method.

See also

Reference

IMAPIViewContext::ActivateNext
IPersistMessage : IUnknown
IPersistMessage::Load
PidTagMessageFlags Canonical Property
PidTagMessageStatus Canonical Property
IMAPIFormAdviseSink : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormAdviseSink::OnChange

 Copy code hover
[image]

IMAPIFormAdviseSink::OnChange
See also Send feedback

Published: July 16, 2012

Indicates that a change has occurred in the status of the form viewer.

C++
HRESULT OnChange(
  ULONG ulDir
);

Parameters

ulDir

[in] A bitmask of flags that provides information about the change that has occurred in the viewer and the expected response in the form. The following flags can be set:

VCSTATUS_CATEGORY

There is a next or previous message in another category.

VCSTATUS_INTERACTIVE

The form should display a user interface. If this flag is not set, the form should suppress displaying a user interface, even in response to a verb that usually causes a user interface to be displayed.

VCSTATUS_MODAL

The form is to be modal to the form viewer.

VCSTATUS_NEXT

There is a next message in the form viewer.

VCSTATUS_PREV

There is a previous message in the form viewer.

VCSTATUS_READONLY

Delete, submit, and move operations should be disabled.

VCSTATUS_UNREAD

There is a next or previous unread message in the form viewer.

Return value

S_OK

The notification was successful.

Remarks

Form viewers call the IMAPIFormAdviseSink::OnChange method to notify the form about a change in a viewer's status. Usually, the only change is setting or clearing the VCSTATUS_NEXT or VCSTATUS_PREVIOUS flag based on the presence or absence of a next or previous message in the viewer. Accordingly, the form object then enables or disables any next or previous actions it supports.

The settings of VCSTATUS_MODAL and VCSTATUS_INTERACTIVE cannot change in a view context after it has been created.

Notes to Implementers

The specific implementation of this method is completely dependent on the specifics of the form. Most form objects use this method to change their user interface (for example, to enable or disable menu commands or buttons to match the viewer status flags parameter).

See also

Reference

IMAPIViewContext::ActivateNext
IMAPIFormAdviseSink : IUnknown


IMAPIFormContainer : IUnknown

 Copy code hover
[image]

IMAPIFormContainer : IUnknown
See also Send feedback

Published: July 16, 2012

Manages forms in form libraries. This interface is used to create application-specific form libraries.

Header file: | Mapiform.h
Exposed by: | Form container objects
Implemented by: | Form library providers
Called by: | Client applications
Interface identifier: | IID_IMAPIFormContainer
Pointer type: | LPMAPIFORMCONTAINER

Vtable Order

InstallForm | Installs a form into a form container.
RemoveForm | Removes a particular form from a form container.
ResolveMessageClass | Resolves a message class to its form in a form container and returns a form information object for that form.
ResolveMultipleMessageClasses | Resolves a group of message classes to their forms in a form container and returns an array of form information objects for those forms.
CalcFormPropSet | Returns an array of the properties used by all forms installed in a form container.
GetDisplay | Returns the display name of a form container.
GetLastError | Returns a MAPIERROR structure containing information about the previous error occurring to the form container object.

See also

Concepts

MAPI Interfaces


IMAPIFormContainer::CalcFormPropSet

 Copy code hover
[image]

IMAPIFormContainer::CalcFormPropSet
See also Send feedback

Published: July 16, 2012

Returns an array of the properties used by all forms installed in a form container.

C++
HRESULT CalcFormPropSet(
  ULONG ulFlags,
  LPMAPIFORMPROPARRAY FAR * ppResults
);

Parameters

ulFlags

[in] A bitmask of flags that controls how the property array in the ppResults parameter is returned. The following flags can be set:

FORMPROPSET_INTERSECTION

The returned array contains the intersection of the forms' properties.

FORMPROPSET_UNION

The returned array contains the union of the forms' properties.

MAPI_UNICODE

The strings returned in the array are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppResults

[out] A pointer to a pointer to the returned SMAPIFormPropArray structure. This structure contains all properties used by the installed forms.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

Client applications call the IMAPIFormContainer::CalcFormPropSet method to obtain an array of properties used by all forms installed in a form container. IMAPIFormContainer::CalcFormPropSet works like the IMAPIFormMgr::CalcFormPropSet method, except that it operates on every form registered in a particular container.

Notes to Implementers

Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

Notes to Callers

IMAPIFormContainer::CalcFormPropSet takes either an intersection or a union of the forms' property sets, depending on the flag set in the ulFlags parameter, and it returns an SMAPIFormPropArray structure that contains the resulting group of properties.

If a client passes the MAPI_UNICODE flag in ulFlags, all returned strings are Unicode.

See also

Reference

IMAPIFormMgr::CalcFormPropSet
SMAPIFormPropArray
IMAPIFormContainer : IUnknown


IMAPIFormContainer::GetDisplay

 Copy code hover
[image]

IMAPIFormContainer::GetDisplay
See also Send feedback

Published: July 16, 2012

Returns the display name of a form container.

C++
HRESULT GetDisplay(
  ULONG ulFlags,
  LPSTR FAR * pszDisplayName
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the returned string. The following flag can be set:

MAPI_UNICODE

The returned string is in Unicode format. If the MAPI_UNICODE flag is not set, the string is in ANSI format.

pszDisplayName

[out] A pointer to a string that contains the display name of the form container.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FormContainerDlg.cpp | CFormContainerDlg::CFormContainerDlg | MFCMAPI uses the IMAPIFormContainer::GetDisplay method to get the name of the form container when it renders CFormContainerDlg.

See also

Reference

IMAPIFormContainer : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormContainer::GetLastError

 Copy code hover
[image]

IMAPIFormContainer::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error generated by the form container object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IMAPIFormContainer::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was, or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
IMAPIFormContainer : IUnknown


IMAPIFormContainer::InstallForm

 Copy code hover
[image]

IMAPIFormContainer::InstallForm
See also Send feedback

Published: July 16, 2012

Installs a form into a form library.

C++
HRESULT InstallForm(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPCSTR szCfgPathName
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays. The ulUIParam parameter is ignored unless the client application sets the MAPI_DIALOG flag in the ulFlags parameter. The ulUIParam parameter can be NULL if MAPI_DIALOG is not also passed.

ulFlags

[in] A bitmask of flags that controls the installation of the form. The following flags can be set:

MAPI_DIALOG

Displays a dialog box to provide progress information or prompt the user for more information. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPIFORM_INSTALL_OVERWRITEONCONFLICT

If another form already exists that handles the message class handled by this form, replace the existing form with this one. This flag is ignored if the MAPI_DIALOG flag is also present.

szCfgPathName

[in] The path to the form's configuration file.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_EXTENDED_ERROR

An implementation error occurred. To get the MAPIERROR structure that is associated with the error, call the IMAPIFormContainer::GetLastError method.

MAPI_E_USER_CANCEL

The user canceled the installation of the form, typically by clicking the Cancel button in a dialog box.

Notes to Implementers

Form library providers should fill in a MAPIERROR structure and return MAPI_E_EXTENDED_ERROR if any of the following conditions occur:

  • The configuration file is not found.

  • The configuration file is not readable.

  • The configuration file is invalid.

Notes to Callers

Client applications call the IMAPIFormContainer::InstallForm method to install a form into a specific form container. The szCfgPathName parameter must contain the path of a form configuration file (that is, a file with the .cfg extension that describes the form and its implementation). The flags in the ulFlags parameter specify the following:

  • If the MAPI_DIALOG flag is set, a user interface is displayed, enabling the user who is installing the form to specify installation details.

  • If the MAPIFORM_INSTALL_OVERWRITEONCONFLICT flag is set, any previous form for the same message class is replaced with the form being installed. Otherwise, the form installation is merged with the current form description, if one exists.

  • If MAPI_DIALOG is set, MAPIFORM_INSTALL_OVERWRITEONCONFLICT is ignored.

  • The absence of MAPIFORM_INSTALL_OVERWRITEONCONFLICT in the flag set means that a merge will be done. Any new platforms in the .cfg file that are not currently present in the form description will be installed and no other changes will occur.

  • If the MAPI_UNICODE flag is set, the path of the form configuration file is a Unicode string.

Clients should call IMAPIFormContainer::GetLastError if InstallForm returns MAPI_E_EXTENDED_ERROR, and they should check the returned MAPIERROR structure to determine the condition that raised the error.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FormContainerDlg.cpp | CFormContainerDlg::OnInstallForm | MFCMAPI uses the IMAPIFormContainer::InstallForm method to install a form in a form container.

See also

Reference

MAPIERROR
IMAPIFormContainer : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormContainer::RemoveForm

 Copy code hover
[image]

IMAPIFormContainer::RemoveForm
See also Send feedback

Published: July 16, 2012

Removes a particular form from a form container.

C++
HRESULT RemoveForm(
  LPCSTR szMessageClass
);

Parameters

szMessageClass

[in] A string that names the message class of the form to be removed from the form container. Message class names are always ANSI strings, never Unicode.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMessageClass parameter does not match the message class of any form in the form container.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FormContainerDlg.cpp | CFormContainerDlg::OnDeleteSelectedItem | MFCMAPI uses the IMAPIFormContainer::RemoveForm method to delete a form from a form container.

See also

Reference

IMAPIFormContainer : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormContainer::ResolveMessageClass

 Copy code hover
[image]

IMAPIFormContainer::ResolveMessageClass
See also Send feedback

Published: July 16, 2012

Resolves a message class to its form in a form container and returns a form information object for that form.

C++
HRESULT ResolveMessageClass(
  LPCSTR szMessageClass,
  ULONG ulFlags,
  LPMAPIFORMINFO FAR * ppforminfo
);

Parameters

szMessageClass

[in] A string that names the message class being resolved. Message class names are always ANSI strings, never Unicode.

ulFlags

[in] A bitmask of flags that controls how the message class is resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

ppforminfo

[out] A pointer to a pointer to the returned form information object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMessageClass parameter does not match the message class for any form in the form container.

Remarks

Client applications call the IMAPIFormContainer::ResolveMessageClass method to resolve a message class to a form within a form container. The form information object returned in the ppforminfo parameter provides further access to the properties of the form with the given message class.

Notes to Callers

To resolve a message class to a form, pass in the name of the message class to be resolved (for example, IPM.HelpDesk.Software). To force the resolution to be exact (that is, to prevent resolution to a base class of the message class), the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

The class identifier for the resolved message class is returned as part of the form information object. Do not assume that the class identifier exists in the OLE library until after you call either the IMAPIFormMgr::PrepareForm or IMAPIFormMgr::CreateForm method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FormContainerDlg.cpp | CFormContainerDlg::OnResolveMessageClass | MFCMAPI uses the IMAPIFormContainer::ResolveMessageClass method to locate a form that is associated with a message class.

See also

Reference

IMAPIFormInfo : IMAPIProp
IMAPIFormMgr::CreateForm
IMAPIFormMgr::PrepareForm
IMAPIFormContainer : IUnknown


IMAPIFormContainer::ResolveMultipleMessageClasses

 Copy code hover
[image]

IMAPIFormContainer::ResolveMultipleMessageClasses
See also Send feedback

Published: July 16, 2012

Resolves a group of message classes to their forms in a form container and returns an array of form information objects for those forms.

C++
HRESULT ResolveMultipleMessageClasses(
  LPSMESSAGECLASSARRAY pMsgClassArray,
  ULONG ulFlags,
  LPSMAPIFORMINFOARRAY FAR * ppfrminfoarray
);

Parameters

pMsgClassArray

[in] A pointer to an array that contains the names of the message classes to resolve. Message class names are always ANSI strings, never Unicode.

ulFlags

[in] A bitmask of flags that controls how the message classes are resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

ppfrminfoarray

[out] A pointer to a pointer to an array of form information objects. If a client application passes NULL in the pMsgClassArray parameter, the ppfrminfoarray parameter contains form information objects for all forms in the container.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call the IMAPIFormContainer::ResolveMultipleMessageClasses method to resolve a group of message classes to forms within a form container. The array of form information objects returned in the ppfrminfoarray parameter provides further access to each of the forms' properties.

Notes to Callers

To resolve a group of message classes to forms, pass in an array of message class names to be resolved. To force the resolution to be exact (that is, to prevent resolution to a base class of the message class), the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

If a message class cannot be resolved to a form, NULL is returned for that message class in the form information array. Therefore, even if the method returns S_OK, do not assume that all message classes have been successfully resolved. Instead, check the values in the returned array.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FormContainerDlg.cpp | CFormContainerDlg::OnResolveMultipleMessageClasses | MFCMAPI uses the IMAPIFormContainer::ResolveMultipleMessageClasses method to locate a form that is associated with a set of message classes.

See also

Reference

IMAPIFormContainer::ResolveMessageClass
IMAPIFormContainer : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormFactory : IUnknown

 Copy code hover
[image]

IMAPIFormFactory : IUnknown
See also Send feedback

Published: July 16, 2012

Supports the use of configurable run-time forms in distributed computing environments.

Header file: | Mapiform.h
Exposed by: | Form factory objects
Implemented by: | Form servers
Called by: | Form viewers
Interface identifier: | IID_IMAPIFormFactory
Pointer type: | LPMAPIFORMFACTORY

Vtable Order

CreateClassFactory | Returns a class factory object for the form.
GetLastError | Returns a MAPIERROR structure that contains information about the previous error occurring to the form factory object.
LockServer | Keeps an open form server in memory.

Remarks

The IMAPIFormFactory interface is based on the IClassFactory interface, and objects that implement IMAPIFormFactory should also inherit from IClassFactory.

IMAPIFormFactory is the interface that form viewers use to create new form objects when a form server supports more than one message class (that is, more than one type of form object).

See also

Concepts

MAPI Interfaces


IMAPIFormFactory::CreateClassFactory

 Copy code hover
[image]

IMAPIFormFactory::CreateClassFactory
See also Send feedback

Published: July 16, 2012

Returns a class factory object for the form.

C++
HRESULT CreateClassFactory(
  REFCLSID clsidForm,
  ULONG ulFlags,
  LPCLASSFACTORY FAR * lppClassFactory
);

Parameters

clsidForm

[in] A class identifier for the form to be created by the class factory.

ulFlags

[in] Reserved; must be zero.

lppClassFactory

[out] A pointer to the class factory object.

Return value

S_OK

The class factory object was returned.

Remarks

Form viewers call the IMAPIFormFactory::CreateClassFactory method to obtain a class factory for a specific form. The class factory is used to create instances of a form that handles messages of a specific class and to control the access to these instances.

The CreateClassFactory method is called by form viewers to obtain a class factory object for form servers that implement multiple message classes. This method receives a class identifier (CLSID) as a parameter. Based on that parameter, this method can determine the specific kind of class factory object to return.

Notes to Implementers

You can return from your CreateClassFactory implementation the same class factory object on multiple calls for the same class identifier. Creating a new class factory instance is not required.

You can have a single class factory implementation that creates appropriate class factory instances on demand, or multiple class factory implementations, one for each message class.

See also

Reference

IMAPIFormFactory : IUnknown


IMAPIFormFactory::GetLastError

 Copy code hover
[image]

IMAPIFormFactory::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error occurring to the form factory object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. This parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IMAPIFormFactory::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPIFormFactory : IUnknown


IMAPIFormFactory::LockServer

 Copy code hover
[image]

IMAPIFormFactory::LockServer
See also Send feedback

Published: July 16, 2012

Keeps an open form server in memory.

C++
HRESULT LockServer(
  ULONG ulFlags,
  ULONG fLockServer
);

Parameters

ulFlags

[in] Reserved; must be zero.

fLockServer

[in] true to increment the lock count; otherwise, false.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormFactory::LockServer method to keep an open form server application in memory. Keeping the form server in memory improves its performance when forms are frequently created and released.

Notes to Implementers

The IMAPIFormFactory::LockServer method is very similar to the IClassFactory::LockServer method. Essentially, the IMAPIFormFactory::LockServer method maintains a count of how many times it has been called; as long as that count is greater than 0, the method prevents the form server from being unloaded from memory. You can use the CoLockObjectExternal function to implement this.

See also

Reference

IMAPIFormFactory : IUnknown


IMAPIFormInfo : IMAPIProp

 Copy code hover
[image]

IMAPIFormInfo : IMAPIProp
See also Send feedback

Published: July 16, 2012

Gives client applications access to properties that are particular to form definition. By keeping form information in a separate object, the form library provider can describe a form to a client without activating the form.

Header file: | Mapiform.h
Exposed by: | Form information objects
Implemented by: | Form library providers
Called by: | Client applications
Interface identifier: | IID_IMAPIFormInfo
Pointer type: | LPMAPIFORMINFO
Transaction model: | Nontransacted

Vtable Order

CalcFormPropSet | Returns a pointer to the complete set of properties that a form uses.
CalcVerbSet | Returns a pointer to the complete set of verbs that a form uses.
MakeIconFromBinary | Builds an icon from an icon property of a form.
SaveForm | Saves a description of a particular form in a configuration file.
OpenFormContainer | Returns a pointer to the form container in which a particular form is installed.

Remarks

Unlike most interfaces defined in the MapiForm.h header file, IMAPIFormInfo inherits from the IMAPIProp interface, because it exports most form information through calls to the IMAPIProp::GetProps method.

See also

Concepts

MAPI Interfaces


IMAPIFormInfo::CalcFormPropSet

 Copy code hover
[image]

IMAPIFormInfo::CalcFormPropSet
See also Send feedback

Published: July 16, 2012

Returns a pointer to the complete set of properties that a form uses.

C++
HRESULT CalcFormPropSet(
  ULONG ulFlags,
  LPMAPIFORMPROPARRAY FAR * ppFormPropArray
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppFormPropArray

[out] A pointer to a pointer to the returned SMAPIFormPropArray structure.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MFCOutput.cpp | _OutputFormInfo | MFCMAPI uses the IMAPIFormInfo::CalcFormPropSet method when writing debug output for form information objects.

See also

Reference

SMAPIFormPropArray
IMAPIFormInfo : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIFormInfo::CalcVerbSet

 Copy code hover
[image]

IMAPIFormInfo::CalcVerbSet
See also Send feedback

Published: July 16, 2012

Returns a pointer to the complete set of verbs that a form uses.

C++
HRESULT CalcVerbSet(
  ULONG ulFlags,
  LPMAPIVERBARRAY FAR * ppMAPIVerbArray
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppMAPIVerbArray

[out] A pointer to a pointer to the returned SMAPIVerbArray structure that contains the form's verbs.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

Client applications call the IMAPIFormInfo::CalcVerbSet method to obtain a pointer to the set of verbs used by a form. In the SMAPIVerbArray structure returned in the ppMAPIVerbArray parameter, the verbs are returned in order of index number; each verb's index is found in its lVerb member. Client applications can use the verb array to dynamically build menus, hide or show buttons, and so on.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MFCOutput.cpp | _OutputFormInfo | MFCMAPI uses the IMAPIFormInfo::CalcVerbSet method while writing debug output for form information objects.

See also

Reference

SMAPIVerbArray
IMAPIFormInfo : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMAPIFormInfo::MakeIconFromBinary

 Copy code hover
[image]

IMAPIFormInfo::MakeIconFromBinary
See also Send feedback

Published: July 16, 2012

Builds an icon from one of the icon properties of a form.

C++
HRESULT MakeIconFromBinary(
  ULONG nPropID,
  HICON FAR * phicon
);

Parameters

nPropID

[in] A property identifier for an icon property.

phicon

[out] A pointer to the returned icon.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call the IMAPIFormInfo::MakeIconFromBinary method to build an icon from one of the icon properties of a form. In the nPropID parameter, MakeIconFromBinary takes the property identifier of one of the icon properties of a form. Using this property identifier, it builds an icon that can be displayed in table views that include property columns for icons.

See also

Reference

IMAPIFormInfo : IMAPIProp


IMAPIFormInfo::OpenFormContainer

 Copy code hover
[image]

IMAPIFormInfo::OpenFormContainer
See also Send feedback

Published: July 16, 2012

Returns a pointer to the form container in which a particular form is installed.

C++
HRESULT OpenFormContainer(
  LPMAPIFORMCONTAINER FAR * ppformcontainer
);

Parameters

ppformcontainer

[out] A pointer to a pointer to the returned form container object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPIFormInfo : IMAPIProp


IMAPIFormInfo::SaveForm

 Copy code hover
[image]

IMAPIFormInfo::SaveForm
See also Send feedback

Published: July 16, 2012

Saves a description of a particular form in a configuration file.

C++
HRESULT SaveForm(
  LPCSTR szFileName
);

Parameters

szFileName

[in] A string that names the form's description message file where its description is saved. This file name must have the .fdm extension.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_EXTENDED_ERROR

The configuration file could not be written. To get the MAPIERROR structure that is associated with the error, call the IMAPIProp::GetLastError method.

MAPI_E_NO_SUPPORT

SaveForm was probably called to save a form in the local form container. SaveForm is not supported on the local form container.

Remarks

Client applications call the IMAPIFormInfo::SaveForm method to save a description of the current form in the file that has the given file name. SaveForm creates a configuration file.

Notes to Callers

You can reinstall forms by selecting them from a list of form descriptor messages in a dialog box that form library providers display. The recommended extension for form descriptor messages is .fdm.

Call the IMAPIProp::GetLastError method if SaveForm returns MAPI_E_EXTENDED_ERROR, and check the returned MAPIERROR structure to determine the condition that caused the error.

See also

Reference

IMAPIProp::GetLastError
MAPIERROR
IMAPIFormInfo : IMAPIProp


IMAPIFormMgr : IUnknown

 Copy code hover
[image]

IMAPIFormMgr : IUnknown
See also Send feedback

Published: July 16, 2012

Enables form viewers to obtain information about and activate form servers.

Header file: | Mapiform.h
Exposed by: | Form manager objects
Implemented by: | Form library providers
Called by: | Form viewers
Interface identifier: | IID_IMAPIFormMgr
Pointer type: | LPMAPIFORMMGR

Vtable Order

LoadForm | Starts a form to open an existing message.
ResolveMessageClass | Resolves a message class to its form within a form container, and returns a form information object for that form.
ResolveMultipleMessageClasses | Resolves a group of message classes to their forms within a form container, and returns an array of form information objects for those forms.
CalcFormPropSet | Returns an array of the properties that a group of forms uses.
CreateForm | Launches a form to create a new message based on the form's message class.
SelectForm | Presents a dialog box that enables the user to select a form, and returns a form information object that describes that form.
SelectMultipleForms | Presents a dialog box that enables the user to select multiple forms, and returns an array of form information objects that describe those forms.
SelectFormContainer | Presents a dialog box that enables the user to select a form container, and returns an interface for the container object the user selected.
OpenFormContainer | Opens an IMAPIFormContainer interface for a specific form container.
PrepareForm | Downloads a form for opening.
IsInConflict | Determines whether a form can handle its own message conflicts.
GetLastError | Returns a MAPIERROR structure that contains information about the previous error occurring to the form manager object.

See also

Concepts

MAPI Interfaces


IMAPIFormMgr::CalcFormPropSet

 Copy code hover
[image]

IMAPIFormMgr::CalcFormPropSet
See also Send feedback

Published: July 16, 2012

Returns an array of the properties that a group of forms uses.

C#
HRESULT CalcFormPropSet(
  LPSMAPIFORMINFOARRAY pfrminfoarray,
  ULONG ulFlags,
  LPMAPIFORMPROPARRAY FAR * ppResults
);

Parameters

pfrminfoarray

[in] A pointer to an array of form information objects that identify the forms for which to return properties.

ulFlags

[in] A bitmask of flags that controls how the property array in the ppResults parameter is returned. The following flags can be set:

FORMPROPSET_INTERSECTION

The returned array contains the intersection of the form's properties.

FORMPROPSET_UNION

The returned array contains the union of the form's properties.

MAPI_UNICODE

The strings returned in the array are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

ppResults

[out] A pointer to a pointer to the returned SMAPIFormPropArray structure, which contains the properties that the forms use.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

Form viewers call the IMAPIFormMgr::CalcFormPropSet method to obtain an array of the properties that a group of forms uses. CalcFormPropSet takes either an intersection or a union of these forms' property sets, depending on the flag set in the ulFlags parameter, and it returns an SMAPIFormPropArray structure that contains the resulting group of properties.

Notes to Implementers

If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings should be returned as Unicode strings. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

See also

Reference

SMAPIFormPropArray
IMAPIFormMgr : IUnknown


IMAPIFormMgr::CreateForm

 Copy code hover
[image]

IMAPIFormMgr::CreateForm
See also Send feedback

Published: July 16, 2012

Opens a form to create a new message based on the form's message class.

C++
HRESULT CreateForm(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  IMAPIFormInfo pfrminfoToActivate,
  REFIID refiidToAsk,
  LPVOID FAR * ppvObj
);

Parameters

ulUIParam

[in] A handle to the parent window for the progress indicator that is displayed while the form is opened. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls how the form is opened. The following flag can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for more information. If this flag is not set, no user interface is displayed.

pfrminfoToActivate

[in] A pointer to the form information object that is used to open the form.

refiidToAsk

[in] A pointer to the interface identifier (IID) for the interface to be returned for the form object that was created. The refiidToAsk parameter must not be NULL.

ppvObj

[out] A pointer to a pointer to the returned interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The requested interface is not supported by the form object.

Remarks

Form viewers call the IMAPIFormMgr::CreateForm method to open a form to create a new message based on the form's message class. CreateForm opens the form by creating an instance of the form server for that form as described in the given form information object. If required, CreateForm calls the IMAPIFormMgr::PrepareForm method to download the form server code to the user's disk.

The pfrminfoToActivate parameter must point to a form information object that has been correctly resolved.

After the form has been opened, the calling form viewer must set up a message by using the IPersistMessage interface and can optionally set up a view context for the form. For more information, see Launching a Form Server.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | CreateAndDisplayNewMailInFolder | MFCMAPI uses the IMAPIFormMgr::CreateForm method to create a form before displaying it.

See also

Reference

IMAPIFormMgr::PrepareForm
IPersistMessage : IUnknown
IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample
Launching a Form Server


IMAPIFormMgr::GetLastError

 Copy code hover
[image]

IMAPIFormMgr::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error generated by the form manager object.

C#
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. This parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IMAPIFormMgr::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can use the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPIFormMgr : IUnknown


IMAPIFormMgr::IsInConflict

 Copy code hover
[image]

IMAPIFormMgr::IsInConflict
See also Send feedback

Published: July 16, 2012

Determines whether a form can handle its own message conflicts. A message is in conflict if it has been simultaneously edited by more than one user. This can happen to messages in public folders.

C++
HRESULT IsInConflict(
  ULONG ulMessageFlags,
  ULONG ulMessageStatus,
  LPCSTR szMessageClass LPMAPIFOLDER pFolderFocus
);

Parameters

ulMessageFlags

[in] A pointer to a bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of a message that indicates the current state of the message.

ulMessageStatus

[in] A bitmask of client-defined or provider-defined flags copied from the PR_MSG_STATUS (PidTagMessageStatus) property of a message that provides additional information about the state of the message.

szMessageClass

[in] A string that names the message's message class.

pFolderFocus

[in] A pointer to the folder that contains the message. The pFolderFocus parameter can be NULL if such a folder does not exist (for example, if the message is embedded in another message).

Return value

S_OK

The form does not handle its own message conflicts.

S_FALSE

The form handles its own message conflicts, or the message for which information was passed is not in conflict.

Remarks

Form viewers call the IMAPIFormMgr::IsInConflict method to discover whether a particular form does not handle its own message conflicts. IsInConflict checks the bitmasks in the ulMessageFlags and ulMessageStatus parameters for the presence of a conflict flag. If a conflict flag is set, IsInConflict resolves the message class passed in the szMessageClass parameter and returns S_OK if the form does not handle its own conflicts. IsInConflict returns S_FALSE if the form handles its own conflicts.

A form that does not handle its own conflicts must be opened by using the IMAPIFormMgr::LoadForm method and cannot reuse an existing form object.

Notes to Callers

Client applications typically have to deal with conflicts when the applications move from one message to the next or previous message in a folder. If a message is in conflict, but the form server for that message can handle conflicts, the client application should execute its usual code for displaying the next or previous message. If the form server cannot handle conflicts, the client application should continue as if it was unaware of the message class of the next or previous message.

See also

Reference

IMAPIFormAdviseSink::OnActivateNext
PidTagMessageFlags Canonical Property
PidTagMessageStatus Canonical Property
IMAPIFormMgr : IUnknown


IMAPIFormMgr::LoadForm

 Copy code hover
[image]

IMAPIFormMgr::LoadForm
See also Send feedback

Published: July 16, 2012

Starts a form to open an existing message.

C++
HRESULT LoadForm(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPCSTR lpszMessageClass,
  ULONG ulMessageStatus,
  ULONG ulMessageFlags,
  LPMAPIFOLDER pFolderFocus,
  LPMAPIMESSAGESITE pMessageSite,
  LPMESSAGE pmsg,
  LPMAPIVIEWCONTEXT pViewContext,
  REFIID riid,
  LPVOID FAR * ppvObj
);

Parameters

ulUIParam

[in] A handle to the parent window of the progress indicator that is displayed while the form is opened. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls how the form is opened. The following flags can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for more information. If this flag is not set, no user interface is displayed.

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

lpszMessageClass

[in] A pointer to a string that names the message class of the message to be loaded. If NULL is passed in the lpszMessageClass parameter, the message class is determined from the message pointed to by the pmsg parameter.

ulMessageStatus

[in] A bitmask of client-defined or provider-defined flags copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the message that provides information about the state of the message. The ulMessageStatus parameter must be set if lpszMessageClass is non-NULL; otherwise, ulMessageStatus is ignored.

ulMessageFlags

[in] A pointer to a bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message that indicates the current state of the message. The ulMessageFlags parameter must be set if lpszMessageClass is non-NULL; otherwise, ulMessageFlags is ignored.

pFolderFocus

[in] A pointer to the folder that directly contains the message. The pFolderFocus parameter can be NULL if such a folder does not exist (for example, if the message is embedded in another message).

pMessageSite

[in] A pointer to the message site of the message.

pmsg

[in] A pointer to the message.

pViewContext

[in] A pointer to the view context for the message. The pViewContext parameter can be NULL.

riid

[in] The interface identifier (IID) of the interface to be used for the returned form object. The riid parameter must not be NULL.

ppvObj

[out] A pointer to a pointer to the returned interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The form does not support the requested interface.

MAPI_E_NOT_FOUND

The message class passed in lpszMessageClass does not match the message class for any form in the form library.

Remarks

Form viewers call the IMAPIFormMgr::LoadForm method to open a form for an existing message. LoadForm opens the form object, loads the message into the form object, sets up the appropriate view context, if necessary, and returns the requested interface for the form object.

The pFolderFocus parameter points to the folder that contains the message. If the message is embedded in another message, pFolderFocus should be NULL.

Notes to Implementers

If NULL is passed in lpszMessageClass, the implementation obtains the message's message class, status, and flags from the message's PR_MESSAGE_CLASS (PidTagMessageClass), PR_MSG_STATUS and PR_MESSAGE_FLAGS properties. If a message class string is provided in lpszMessageClass, the implementation must use the values in ulMessageStatus and ulMessageFlags.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | OpenMessageNonModal | MFCMAPI uses the IMAPIFormMgr::LoadForm method to load a form before displaying it.

See also

Reference

PidTagMessageClass Canonical Property
PidTagMessageFlags Canonical Property
PidTagMessageStatus Canonical Property
IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormMgr::OpenFormContainer

 Copy code hover
[image]

IMAPIFormMgr::OpenFormContainer
See also Send feedback

Published: July 16, 2012

Opens an IMAPIFormContainer interface for a specific form container.

C++
HRESULT OpenFormContainer(
  HFRMREG hfrmreg,
  LPUNKNOWN lpunk,
  LPMAPIFORMCONTAINER FAR * lppfcnt
);

Parameters

hfrmreg

[in] An HFRMREG enumeration that indicates the form library to open (that is, the form container to open). An HFRMREG enumeration is an enumeration that is specific to a form library provider. Possible HFRMREG values include the following:

HFRMREG_DEFAULT

A convenient form container.

HFRMREG_FOLDER

A folder container.

HFRMREG_PERSONAL

The container for the default message store.

HFRMREG_LOCAL

A local form container.

lpunk

[in] A pointer to the object for which the interface is opened. The lpunk parameter must be null unless the value for the hfrmreg parameter requires an object pointer.

lppfcnt

[out] A pointer to a pointer to the returned form container object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_INTERFACE

The object pointed to by lpunk does not support the required interface.

Remarks

Form viewers call the IMAPIFormMgr::OpenFormContainer method to open an IMAPIFormContainer interface for a specific form container. This interface can then be used for installing forms into and removing forms from a form container.

Notes to Callers

If the value in hfrmreg is HFRMREG_FOLDER, the interface identifier used in lpunk must be non-null and must allow IUnknown::QueryInterface method calls to an IMAPIFolder interface.

To open the local form container, you must use a call to OpenFormContainer method or the MAPIOpenLocalFormContainer function; you cannot use the IMAPIFormMgr::SelectFormContainer method to enable the user to select the local form container.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnOpenFormContainer | MFCMAPI uses the IMAPIFormMgr::OpenFormContainer method to retrieve a form container so the container's contents can be rendered.
MsgStoreDlg.cpp | CMsgStoreDlg::OnOpenFormContainer | MFCMAPI uses the IMAPIFormMgr::OpenFormContainer method to retrieve a form container for a folder so the container's contents can be rendered.

See also

Reference

IMAPIFormContainer::InstallForm
IMAPIFormMgr::SelectFormContainer
MAPIOpenLocalFormContainer
IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormMgr::PrepareForm

 Copy code hover
[image]

IMAPIFormMgr::PrepareForm
See also Send feedback

Published: July 16, 2012

Downloads a form for opening.

C++
HRESULT PrepareForm(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPMAPIFORMINFO pfrmiInfo
);

Parameters

ulUIParam

[in] A handle to the parent window of the progress indicator that is displayed while the form is downloaded. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls how the form is downloaded. The following flag can be set:

MAPI_DIALOG

Displays a user interface to provide status or prompt the user for more information. If this flag is not set, no user interface is displayed.

pfrmiInfo

[in] A pointer to a form information object for the form to be downloaded.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormMgr::PrepareForm method to download a form from a form container for opening. Most form viewers do not need to call PrepareForm, because both the IMAPIFormMgr::CreateForm and IMAPIFormMgr::LoadForm methods call PrepareForm, if necessary.

You can use PrepareForm to obtain the dynamic-link libraries (DLLs) and other files associated with a form to modify them. If the modified form is loaded back into its form container, it must be reinstalled.

See also

Reference

IMAPIFormMgr::CreateForm
IMAPIFormMgr::LoadForm
IMAPIFormMgr : IUnknown


IMAPIFormMgr::ResolveMessageClass

 Copy code hover
[image]

IMAPIFormMgr::ResolveMessageClass
See also Send feedback

Published: July 16, 2012

Resolves a message class to its form within a form container, and returns a form information object for that form.

C++
HRESULT ResolveMessageClass(
  LPCSTR szMsgClass,
  ULONG ulFlags,
  LPMAPIFOLDER pFolderFocus,
  LPMAPIFORMINFO FAR * ppResult
);

Parameters

szMsgClass

[in] A string that names the message class being resolved.

ulFlags

[in] A bitmask of flags that controls how the message class is resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

pFolderFocus

[in] A pointer to the folder that contains the message being resolved. The pFolderFocus parameter can be NULL.

ppResult

[out] A pointer to a pointer to a returned form information object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message class passed in the szMsgClass parameter does not match the message class for any form in the form library.

Remarks

Form viewers call the IMAPIFormMgr::ResolveMessageClass method to resolve a message class to its form within a form container. The form information object returned in the ppResult parameter provides further access to the properties of the form that has the given message class.

Notes to Callers

To resolve a message class to a form, a form viewer passes in the name of the message class to be resolved, such as "IPM.HelpDesk.Software". To force the resolution to be exact (that is, to prevent resolution to a base class of the message class when an exactly matching form server is not available), the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter. If the pFolderFocus parameter is NULL, the message-class resolution process does not search a folder container.

The order of the containers searched depends on the implementation of the form library provider. The default form library provider searches first the local container, then the folder container for the passed-in folder, the personal form container and, finally, the organization container.

Message class names are always ANSI strings, never Unicode.

The class identifier for the resolved message class is returned as part of the form information object. A form viewer should not work on the assumption that the class identifier exists in the OLE library until after the form viewer has called either the IMAPIFormMgr::PrepareForm method or the IMAPIFormMgr::CreateForm method.

See also

Reference

IMAPIFormInfo : IMAPIProp
IMAPIFormMgr::CreateForm
IMAPIFormMgr::PrepareForm
IMAPIFormMgr : IUnknown


IMAPIFormMgr::ResolveMultipleMessageClasses

 Copy code hover
[image]

IMAPIFormMgr::ResolveMultipleMessageClasses
See also Send feedback

Published: July 16, 2012

Resolves a group of message classes to their forms within a form container, and returns an array of form information objects for those forms.

C++
HRESULT ResolveMultipleMessageClasses(
  LPSMESSAGECLASSARRAY pMsgClasses,
  ULONG ulFlags,
  LPMAPIFOLDER pFolderFocus,
  LPSMAPIFORMINFOARRAY FAR * ppfrminfoarray
);

Parameters

pMsgClasses

[in] A pointer to an array that contains the names of the message classes to resolve.

ulFlags

[in] A bitmask of flags that controls how the message classes are resolved. The following flag can be set:

MAPIFORM_EXACTMATCH

Only message class strings that are an exact match should be resolved.

MAPIFORM_LOCALONLY

Do not include cached forms.

pFolderFocus

[in] A pointer to the folder that contains the form whose message class is being resolved. The pFolderFocus parameter can be NULL.

ppfrminfoarray

[out] A pointer to a pointer to an array of form information objects. If a form viewer passes NULL in the pMsgClasses parameter, the ppfrminfoarray parameter contains form information objects for all forms in the container.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers call the IMAPIFormMgr::ResolveMultipleMessageClasses method to resolve a group of message classes to forms within a form container. The array of form information objects returned in ppfrminfoarray provides further access to each of the forms' properties.

Notes to Callers

To resolve a group of message classes to forms, a form viewer passes in an array of message class names to be resolved. To force the resolution to be exact (that is, to prevent resolution to a base class of the message class when an exactly matching form server is not available) the MAPIFORM_EXACTMATCH flag can be passed in the ulFlags parameter.

Message class names are always ANSI strings, never Unicode.

If a message class cannot be resolved to a form, NULL is returned for that message class in the form information array. Therefore, even if the method returns S_OK, form viewers should not work on the assumption that all message classes have been successfully resolved. Instead, form viewers should check the values in the returned array.

See also

Reference

IMAPIFormMgr::ResolveMessageClass
IMAPIFormMgr : IUnknown


IMAPIFormMgr::SelectForm

 Copy code hover
[image]

IMAPIFormMgr::SelectForm
See also Send feedback

Published: July 16, 2012

Presents a dialog box that enables the user to select a form, and returns a form information object that describes that form.

C++
HRESULT SelectForm(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPCSTR pszTitle,
  LPMAPIFOLDER pfld,
  LPMAPIFORMINFO FAR * ppfrminfoReturned
);

Parameters

ulUIParam

[in] A handle to the parent window of the displayed dialog box.

ulFlags

[in] A bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

pszTitle

[in] A pointer to a string that contains the caption of the dialog box. If the pszTitle parameter is NULL, the form library provider supplies a default caption.

pfld

[in] A pointer to the folder from which to select the form. If the pfld parameter is NULL, the form can be selected from the local, personal, or organization form container.

ppfrminfoReturned

[out] A pointer to a pointer to the returned form information object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the dialog box.

Remarks

Form viewers call the IMAPIFormMgr::SelectForm method to first present a dialog box that enables the user to select a form and then to retrieve a form information object that describes the selected form. The dialog box constrains the user to select a single form.

Notes to Callers

The SelectForm dialog box displays only forms that are not hidden (that is, forms that have their hidden properties clear). If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings are Unicode. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnSelectForm | MFCMAPI uses the IMAPIFormMgr::SelectForm method to select a form and send information about the form to one or more logs.

See also

Reference

IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormMgr::SelectFormContainer

 Copy code hover
[image]

IMAPIFormMgr::SelectFormContainer
See also Send feedback

Published: July 16, 2012

Presents a dialog box that enables the user to select a form container, and returns an interface for the container object the user selected.

C#
HRESULT SelectFormContainer(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPMAPIFORMCONTAINER FAR * lppfcnt
);

Parameters

ulUIParam

[in] A handle to the parent window of the displayed dialog box.

ulFlags

[in] A bitmask of flags that controls how the form library is selected (that is, how the form container is selected). The following flags can be set:

MAPIFORM_SELECT_ALL_REGISTRIES

Selection can be made from all containers. This is the default selection type.

MAPIFORM_SELECT_FOLDER_REGISTRY_ONLY

Selection can be made only from folder containers.

MAPIFORM_SELECT_NON_FOLDER_REGISTRY_ONLY

Selection can be made only from containers that are not associated with folders.

lppfcnt

[out] A pointer to a pointer to the returned interface. This interface is for the container object that is selected by the user.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form viewers typically call the IMAPIFormMgr::SelectFormContainer method to select a form container into which a form is installed. SelectFormContainer cannot be used to select the local form container, which has the value HFRMREG_LOCAL.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnSelectFormContainer | MFCMAPI uses the IMAPIFormMgr::SelectFormContainer method to select a form container before rendering its contents.

See also

Reference

IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIFormMgr::SelectMultipleForms

 Copy code hover
[image]

IMAPIFormMgr::SelectMultipleForms
See also Send feedback

Published: July 16, 2012

Presents a dialog box that enables the user to select multiple forms, and returns an array of form information objects that describe those forms.

C++
HRESULT SelectMultipleForms(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPCSTR pszTitle,
  LPMAPIFOLDER pfld,
  LPMAPIFORMINFOARRAY pfrminfoarray,
  LPMAPIFORMINFOARRAY FAR * ppfrminfoarray
);

Parameters

ulUIParam

[in] A handle to the parent window of the displayed dialog box.

ulFlags

[in] A bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

pszTitle

[in] A pointer to a string that contains the caption of the dialog box. If the pszTitle parameter is NULL, the form library provider that provides the forms supplies a default caption.

pfld

[in] A pointer to the folder from which to select the forms. If the pfld parameter is NULL, the forms are selected from the local, personal, or organization form container.

pfrminfoarray

[in] A pointer to an array of form information objects that are preselected for the user.

ppfrminfoarray

[out] A pointer to a pointer to the returned array of form information objects.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the dialog box.

Remarks

Form viewers call the IMAPIFormMgr::SelectMultipleForms method to first present a dialog box that enables the user to select multiple forms and then to retrieve an array of form information objects that describe the selected forms. The SelectMultipleForms dialog box displays all forms, whether or not they are hidden (that is, whether or not their hidden properties are clear).

Notes to Implementers

If a form viewer passes the MAPI_UNICODE flag in the ulFlags parameter, all strings are Unicode. Form library providers that do not support Unicode strings should return MAPI_E_BAD_CHARWIDTH if MAPI_UNICODE is passed.

See also

Reference

IMAPIFormMgr : IUnknown


IMAPIGetSession : IUnknown

 Copy code hover
[image]

IMAPIGetSession : IUnknown
See also Send feedback

Published: July 16, 2012

Provides access to the current MAPI session associated with the support object. MAPI Providers can query their MAPI Support Object for this interface. For more information on support objects, see Support Object Overview.

Implemented by: | MAPI
Called by: | MAPI Providers
Interface identifier: | IID_IMAPIGetSession

Vtable Order

GetMAPISession

Called to obtain a pointer to the current MAPI session.

See also

Reference

GetMAPISession
IMAPISupport

Concepts

MAPI Interfaces
Support Object Overview


IMAPIGetSession::GetMAPISession

 Copy code hover
[image]

IMAPIGetSession::GetMAPISession
See also Send feedback

Published: July 16, 2012

Returns a pointer to the MAPI session associated with the MAPI support object.

C++
HRESULT GetMAPISession(
  LPUNKNOWN *  lppSession
);

Parameters

lppSession

[out] A pointer to the current MAPI session.

See also

Reference

IMAPIGetSession : IUnknown

Concepts

Support Object Overview


IMAPIMessageSite : IUnknown

 Copy code hover
[image]

IMAPIMessageSite : IUnknown
See also Send feedback

Published: July 16, 2012

Manipulates messages and is implemented by the form viewer code (typically a client application) that responds to such manipulation.

Header file: | Mapiform.h
Exposed by: | Message site objects
Implemented by: | Form viewers
Called by: | Form objects
Interface identifier: | IID_IMAPIMessageSite
Pointer type: | LPMAPIMESSAGESITE

Vtable Order

GetSession | Returns the MAPI session in which the current message was created or opened.
GetStore | Returns the message store that contains the current message, if such a store exists.
GetFolder | Returns the folder in which the current message was created or opened, if such a folder exists.
GetMessage | Returns the current message.
GetFormManager | Returns a form manager interface, which a form server can use to open another form server.
NewMessage | Creates a new message.
CopyMessage | Copies the current message to a folder.
MoveMessage | Moves the current message to a folder.
DeleteMessage | Deletes the current message.
SaveMessage | Requests that the current message be saved.
SubmitMessage | Requests that the current message be queued for delivery.
GetSiteStatus | Returns information from a message site object about the message site's capabilities for the current message.
GetLastError | Returns a MAPIERROR structure that contains information about the previous error occurring to the message site object.

See also

Concepts

MAPI Interfaces


IMAPIMessageSite::CopyMessage

 Copy code hover
[image]

IMAPIMessageSite::CopyMessage
See also Send feedback

Published: July 16, 2012

Copies the current message to a folder.

C++
HRESULT CopyMessage(
  LPMAPIFOLDER pFolderDestination
);

Parameters

pFolderDestination

[in] A pointer to the folder where the message is to be copied.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

Form objects call the IMAPIMessageSite::CopyMessage method to copy the current message to a new folder. CopyMessage does not change the message currently being displayed to the user, and no interface for the newly created message is returned to the form.

Notes to Implementers

A typical implementation of the CopyMessage method performs the following tasks:

  1. Creates a new message for the current message to be copied to.

  2. Calls the IPersistMessage::Save method with a pointer to the new message in the pMessage parameter and FALSE in the fSameAsLoad parameter.

  3. Calls the IPersistMessage::SaveCompleted method, passing NULL in the pMessage parameter.

  4. Calls the IMAPIProp::SaveChanges method on the new message.

For a list of interfaces that are related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::CopyMessage | Not implemented.

See also

Reference

IMAPIProp::SaveChanges
IPersistMessage::Save
IPersistMessage::SaveCompleted
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::DeleteMessage

 Copy code hover
[image]

IMAPIMessageSite::DeleteMessage
See also Send feedback

Published: July 16, 2012

Deletes the current message.

C++
HRESULT DeleteMessage(
  LPMAPIVIEWCONTEXT pViewContext,
  LPCRECT prcPosRect
);

Parameters

pViewContext

[in] A pointer to a view context object.

prcPosRect

[in] A pointer to a RECT structure that contains the current form's window size and position. The next form displayed also uses this window rectangle.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

A form object calls the IMAPIMessageSite::DeleteMessage method to delete the message that the form is currently displaying.

Notes to Callers

Following the return of DeleteMessage, form objects must check for a new message and then dismiss themselves if none exists. To determine whether the message DeleteMessage acted on was deleted or moved to a Deleted Items folder, a form object can call the IMAPIMessageSite::GetSiteStatus method to determine whether the DELETE_IS_MOVE flag was returned.

Notes to Implementers

If a form viewer's implementation of the DeleteMessage method moves to the next message after it deletes a message, the implementation should call the IMAPIViewContext::ActivateNext method and pass the VCDIR_DELETE flag before performing the actual deletion. If a form viewer's implementation of DeleteMessage moves the deleted message (for example, to a Deleted Items folder), the implementation must save changes to the message if the message was modified.

A typical implementation of DeleteMessage performs the following tasks:

  1. If the implementation is moving the message, it calls the IPersistMessage::Save method, passing null in the pMessage parameter and true in the fSameAsLoad parameter.

  2. It calls the IMAPIViewContext::ActivateNext method, passing the VCDIR_DELETE flag in the ulDir parameter.

  3. If the ActivateNext call fails, it returns. If ActivateNext returns S_FALSE, it calls the IPersistMessage::HandsOffMessage method.

  4. It deletes or moves the message.

To obtain the RECT structure used by a form's window, call the Windows GetWindowRect function.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::DeleteMessage | Not implemented.

See also

Reference

IMAPIMessageSite::GetSiteStatus
IMAPIViewContext::ActivateNext
IPersistMessage::HandsOffMessage
IPersistMessage::Save
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::GetFolder

 Copy code hover
[image]

IMAPIMessageSite::GetFolder
See also Send feedback

Published: July 16, 2012

Returns the folder in which the current message was created or opened, if such a folder exists. This method returns NULL in the ppFolder parameter for embedded messages, which are not stored directly in a folder.

C++
HRESULT GetFolder(
  LPMAPIFOLDER FAR * ppFolder
);

Parameters

ppFolder

[out] A pointer to a pointer to the returned folder.

Return value

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No folder exists for the message.

Remarks

For a list of interfaces that are related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetFolder | MFCMAPI uses the IMAPIMessageSite::GetFolder method to return the currently cached pointer to the specified folder.

See also

Reference

IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::GetFormManager

 Copy code hover
[image]

IMAPIMessageSite::GetFormManager
See also Send feedback

Published: July 16, 2012

Returns a form manager interface, which a form server can use to open another form server.

C++
HRESULT GetFormManager(
  LPMAPIFORMMGR FAR * ppFormMgr
);

Parameters

ppFormMgr

[out] A pointer to a pointer to the returned form manager interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetFormManager | MFCMAPI uses the IMAPIMessageSite::GetFormManager method to call MAPIOpenFormMgr and return the results of that call.

See also

Reference

MAPIOpenFormMgr
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::GetLastError

 Copy code hover
[image]

IMAPIMessageSite::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error occurring to the message site object.

C#
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. This parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IMAPIMessageSite::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was, or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
IMAPIMessageSite : IUnknown


IMAPIMessageSite::GetMessage

 Copy code hover
[image]

IMAPIMessageSite::GetMessage
See also Send feedback

Published: July 16, 2012

Returns the current message.

C++
HRESULT GetMessage(
  LPMESSAGE FAR * ppmsg
);

Parameters

ppmsg

[out] A pointer to a pointer to the returned interface for the message.

Return value

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No message currently exists for the calling form.

Remarks

Forms call the IMAPIMessageSite::GetMessage method to obtain a message interface for the current message. The current message is the same message as was previously passed in the IPersistMessage::InitNew, IPersistMessage::Load, or IPersistMessage::SaveCompleted method.

GetMessage returns S_FALSE if no message currently exists. This state can occur after calls to the IPersistMessage::HandsOffMessage method or before the next call to IPersistMessage::Load or IPersistMessage::SaveCompleted is made.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetSession | MFCMAPI uses the IMAPIMessageSite::GetMessage method to return the currently cached message pointer, if it is available.

See also

Reference

IPersistMessage::HandsOffMessage
IPersistMessage::InitNew
IPersistMessage : IUnknown
IPersistMessage::Load
IPersistMessage::SaveCompleted
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::GetSession

 Copy code hover
[image]

IMAPIMessageSite::GetSession
See also Send feedback

Published: July 16, 2012

Returns the MAPI session in which the current message was created or opened.

C++
HRESULT GetSession(
  LPMAPISESSION FAR * ppSession
);

Parameters

ppSession

[out] A pointer to a pointer to the returned session object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

No session exists for the current message.

Remarks

For a list of interfaces that are related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetSession | MFCMAPI uses the IMAPIMessageSite::GetSession method to return the currently cached session pointer, if it is available.

See also

Reference

IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIMessageSite::GetSiteStatus

 Copy code hover
[image]

IMAPIMessageSite::GetSiteStatus
See also Send feedback

Published: July 16, 2012

Returns information from a message site object about the message site's capabilities for the current message.

C++
HRESULT GetSiteStatus(
  ULONG FAR * lpulStatus
);

Parameters

lpulStatus

[out] A pointer to a bitmask of flags that provides information about message status. The following flags can be set:

VCSTATUS_COPY

The message can be copied.

VCSTATUS_DELETE

The message can be deleted.

VCSTATUS_DELETE_IS_MOVE

When deleted, a message is moved to a Deleted Items folder in its message store instead of being immediately removed from its message store.

VCSTATUS_MOVE

The message can be moved.

VCSTATUS_NEW_MESSAGE

A new message can be created.

VCSTATUS_SAVE

The message can be saved.

VCSTATUS_SUBMIT

The message can be submitted.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::GetSiteStatus method to obtain the message site object's capabilities for the current message. The flags returned in the lpulStatus parameter provide information about the message site. Typically, a form enables or disables menu commands, depending on information the flags provide about the capabilities of the message site implementation. If a new message is loaded into a form by the IPersistMessage::SaveCompleted method or the IPersistMessage::Load method, the status flags must be checked. Some message site objects, especially read-only objects, do not allow messages to be saved or deleted.

Notes to Implementers

The IMAPIMessageSite::GetSiteStatus method may require the client application to do some calculation to determine what operations can or cannot be performed on the current message. Typically, that involves looking at the status row for the current message's message store provider, or querying the store provider to determine which actions the client application can perform by using the message store. For example, to determine whether to return the MAPI_DELETE_IS_MOVE flag, check the message store object's PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId) property to see whether there is a Deleted Items folder in the message store.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetSiteStatus | MFCMAPI uses the IMAPIMessageSite::GetSiteStatus method to get the status of the specified site. It can return VCSTATUS_NEW_MESSAGE, VCSTATUS_SAVE, or VCSTATUS_SUBMIT.

See also

Reference

IPersistMessage::Load
IPersistMessage::SaveCompleted
PidTagIpmWastebasketEntryId Canonical Property
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::GetStore

 Copy code hover
[image]

IMAPIMessageSite::GetStore
See also Send feedback

Published: July 16, 2012

Returns the message store that contains the current message, if such a store exists. This method will return NULL in the ppStore parameter for embedded messages, which are stored in another message instead of directly in a message store.

C++
HRESULT GetStore(
  LPMDB FAR * ppStore
);

Parameters

ppStore

[out] A pointer to a pointer to the message store.

Return value

S_OK

The call succeeded and has returned the expected value or values.

S_FALSE

There is no store that contains the message.

Remarks

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetStore | MFCMAPI uses the IMAPIMessageSite::GetStore method to get the currently cached pointer to the specified store, if it is available.

See also

Reference

IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::MoveMessage

 Copy code hover
[image]

IMAPIMessageSite::MoveMessage
See also Send feedback

Published: July 16, 2012

Moves the current message to a folder.

C++
HRESULT MoveMessage(
  LPFOLDER pFolderDestination,
  LPMAPIVIEWCONTEXT pViewContext,
  LPCRECT prcPosRect
);

Parameters

pFolderDestination

[in] A pointer to the folder where the message is to be moved.

pViewContext

[in] A pointer to a view context object.

prcPosRect

[in] A pointer to a RECT structure that contains the current form's window size and position. The next form displayed also uses this window rectangle.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by this message site.

Remarks

Form objects call the IMAPIMessageSite::MoveMessage method to move the current message to a new folder.

Notes to Implementers

A form viewer's implementation of MoveMessage must call the IMAPIViewContext::ActivateNext method, passing the VCDIR_MOVE flag, before actually moving the message to a new folder. To obtain the RECT structure used by a form's window, call the Windows GetWindowRect function.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

Notes to Callers

Following the return of MoveMessage, forms must check for a current message and then dismiss themselves if none exists.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::MoveMessage | Not implemented.

See also

Reference

IMAPIViewContext::ActivateNext
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::NewMessage

 Copy code hover
[image]

IMAPIMessageSite::NewMessage
See also Send feedback

Published: July 16, 2012

Creates a new message.

C++
HRESULT NewMessage(
  ULONG fComposeInFolder,
  LPMAPIFOLDER pFolderFocus,
  LPPERSISTMESSAGE pPersistMessage,
  LPMESSAGE FAR * ppMessage,
  LPMAPIMESSAGESITE FAR * ppMessageSite,
  LPMAPIVIEWCONTEXT FAR * ppViewContext
);

Parameters

fComposeInFolder

[in] Indicates in which folder the message should be composed. If the variable is FALSE, the pFolderFocus parameter is ignored and the form viewer can compose the message in any folder. If the variable is TRUE and NULL is passed in the pFolderFocus parameter, the message is composed in the current folder. If the variable is TRUE and a non-NULL value is passed in pFolderFocus, the message is composed in the folder pointed to by pFolderFocus.

pFolderFocus

[in] A pointer to the folder where the new message is created.

pPersistMessage

[in] A pointer to the form object for the new form.

ppMessage

[out] A pointer to a pointer to the new message.

ppMessageSite

[out] A pointer to a pointer to a message site object for the new message.

ppViewContext

[out] A pointer to a pointer to a view context that is appropriate for passing to a new form with the new message. If the form implements its own view context, NULL can be passed in the ppViewContext parameter.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::NewMessage method to create a new message. The form uses NewMessage to get a new message and the associated message site from its view. It can then modify the new message.

You can also obtain an associated view context by passing in a non-NULL value in the ppViewContext parameter. This view context can be used directly, or it can be aggregated and passed to the new message. If a complete implementation is required, pass NULL in ppViewContext.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::NewMessage | MFCMAPI uses the IMAPIMessageSite::NewMessage method to create a new message, instantiate a new form viewer, and call SetPersist to set the message on the form viewer. Finally, it returns the form viewer as the message site.

See also

Reference

IMAPIViewContext : IUnknown
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::SaveMessage

 Copy code hover
[image]

IMAPIMessageSite::SaveMessage
See also Send feedback

Published: July 16, 2012

Requests that the current message be saved.

C++
HRESULT SaveMessage( void );

Parameters

None.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Forms call the IMAPIMessageSite::SaveMessage method to request that a message be saved.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::SaveMessage | MFCMAPI uses the IMAPIMessageSite::SaveMessage method to save the message.

See also

Reference

IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIMessageSite::SubmitMessage

 Copy code hover
[image]

IMAPIMessageSite::SubmitMessage
See also Send feedback

Published: July 16, 2012

Requests that the current message be queued for delivery.

C++
HRESULT SubmitMessage(
  ULONG ulFlags
);

Parameters

ulFlags

[in] A bitmask of flags that controls how a message is submitted. The following flag can be set:

FORCE_SUBMIT

MAPI should submit the message even if it might not be sent immediately.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Form objects call the IMAPIMessageSite::SubmitMessage method to request that a message be queued for delivery. The message site should call the IPersistMessage::HandsOffMessage method before submitting the message. The message does not need to have been previously saved, because SubmitMessage should cause the message to be saved if the message has been modified. After the return of SubmitMessage, the form must check for a current message and then dismiss itself if none exists.

For a list of interfaces related to form servers, see MAPI Form Interfaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::SubmitMessage | MFCMAPI uses the IMAPIMessageSite::SubmitMessage method to save the message. First, it calls the IPersistMessage::HandsOffMessage method, and then it calls SubmitMessage.

See also

Reference

IPersistMessage::HandsOffMessage
IMAPIMessageSite : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Form Interfaces


IMAPIOffline : IUnknown

 Copy code hover
[image]

IMAPIOffline : IUnknown
See also Send feedback

Published: July 16, 2012

Provides information for an offline object.

Provided by: | Query on IMAPIOfflineMgr
Called by: | Client
Interface identifier: | IID_IMAPIOffline

Vtable Order

SetCurrentState | Sets the current state of an offline object to online or offline.
GetCapabilities | Gets the conditions for which callbacks are supported by an offline object.
GetCurrentState | Gets the current online or offline state of an offline object.
Placeholder member | This member is a placeholder and is not supported.

Remarks

A client uses HrOpenOfflineObj to open and obtain an offline object that supports IMAPIOfflineMgr. Because IMAPIOfflineMgr inherits from IUnknown, the client can query this interface (by using IUnknown::QueryInterface) to obtain a pointer to the interface pointer for IMAPIOffline for the offline object. The client can then get or set the current state of the object, or find out about the callback capabilities of the object (by calling IMAPIOffline::GetCapabilities) and choose to set up callbacks by using IMAPIOfflineMgr.

A member in this interface is a placeholder reserved for the internal use of Microsoft Outlook 2013 and is subject to change. Other members in this interface must be used only as documented.

See also

Reference

IMAPIOfflineMgr : IMAPIOffline

Concepts

About the Offline State API
MAPI Constants
MAPI Interfaces


IMAPIOffline::GetCapabilities

 Copy code hover
[image]

IMAPIOffline::GetCapabilities
See also Send feedback

Published: July 16, 2012

Gets the conditions for which callbacks are supported by an offline object.

C++
HRESULT GetCapabilities(
    ULONG *pulCapabilities
);

Parameters

pulCapablities

[out] A bitmask of the following capability flags:

MAPIOFFLINE_CAPABILITY_OFFLINE

The offline object is capable of providing offline notifications.

MAPIOFFLINE_CAPABILITY_ONLINE

The offline object is capable of providing online notifications.

Remarks

Upon opening an offline object using HrOpenOfflineObj, a client can query on IMAPIOfflineMgr to obtain a pointer to an IMAPIOffline interface, and call IMAPIOffline::GetCapabilities to find out the callbacks supported by the object. The client can then choose to set up callbacks by using IMAPIOfflineMgr.

Note that, depending on the mail server for an offline object, an object that supports callbacks for going online does not necessarily support callbacks for going offline.

Also note that, while an offline object may support callbacks for changes other than online/offline, the Offline State API supports only online/offline changes, and clients must check for only such capabilities.

See also

Reference

IMAPIOffline::GetCurrentState
IMAPIOffline::SetCurrentState
IMAPIOfflineMgr : IMAPIOffline

Concepts

MAPI Constants
HrOpenOfflineObj


IMAPIOffline::GetCurrentState

 Copy code hover
[image]

IMAPIOffline::GetCurrentState
See also Send feedback

Published: July 16, 2012

Gets the current online or offline state of an offline object.

C++
HRESULT GetCurrentState(
    ULONG* pulState
);

Parameters

pulState

[out] The current online or offline state of an offline object. It must be one of these two values:

MAPIOFFLINE_STATE_ONLINE

MAPIOFFLINE_STATE_OFFLINE

See also

Reference

IMAPIOffline::GetCapabilities
IMAPIOffline::SetCurrentState

Concepts

MAPI Constants


IMAPIOffline::SetCurrentState

 Copy code hover
[image]

IMAPIOffline::SetCurrentState
See also Send feedback

Published: July 16, 2012

Sets the current state of an offline object to online or offline.

C++
HRESULT SetCurrentState(
    ULONG ulFlags,
    ULONG ulMask,
    ULONG ulState,
    void* pReserved
);

Parameters

ulFlags

[in] Modifies the behavior of this call. The supported values are:

MAPIOFFLINE_FLAG_BLOCK

Setting ulFlags to this value will block the SetCurrentState call until the state change is complete. By default the transition takes place asynchronously. When the transition is occuring asynchronously, all SetCurrentState calls will return E_PENDING until the change is complete.

MAPIOFFLINE_FLAG_DEFAULT

Sets the current state without blocking.

ulMask

[in] The part of the state to change. The only supported value is MAPIOFFLINE_STATE_OFFLINE_MASK.

ulState

[in] The state to change to. It must be one of these two values:

MAPIOFFLINE_STATE_ONLINE

MAPIOFFLINE_STATE_OFFLINE

pReserved

This parameter is reserved for Outlook internal use and is not supported.

Return value

S_OK

The state of the offline object has been changed successfully.

E_PENDING

This indicates that the state of the offline object is changing asynchronously. This occurs when ulFlags is set to MAPIOFFLINE_FLAG_BLOCK in an earlier SetCurrentState call, and any subsequent SetCurrentState call will return this value until the asynchronous state change is complete.

See also

Reference

IMAPIOffline::GetCapabilities
IMAPIOffline::GetCurrentState

Concepts

MAPI Constants


IMAPIOfflineMgr : IMAPIOffline

 Copy code hover
[image]

IMAPIOfflineMgr : IMAPIOffline
See also Send feedback

Published: July 16, 2012

Supports registering for notification callbacks about connection state changes of a user account.

Exported by: | msmapi32.dll
Implemented by: | Outlook
Called by: | Client
Interface identifier: | IID_IMAPIOfflineMgr

Vtable Order

Advise | Registers for notification callbacks about connection changes.
Unadvise | Removes a given registration for notification callbacks.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.
Placeholder member | This member is a placeholder and is not supported.

Remarks

Upon opening an offline object for a user account profile using HrOpenOfflineObj, a client obtains an offline object that supports IMAPIOfflineMgr.

Because this interface inherits from IUnknown, the client can query this interface (by using IUnknown::QueryInterface) to obtain an object that supports IMAPIOffline. The client can then find out about the callback capabilities of the offline object (by calling IMAPIOffline::GetCapabilities), and choose to set up callbacks (by using IMAPIOfflineMgr::Advise).

Most of the members in this interface are placeholders reserved for the internal use of Outlook and are subject to change. Callers of this interface must use non-placeholder members only as documented.

See also

Reference

IMAPIOffline : IUnknown

Concepts

About the Offline State API
MAPI Constants
HrOpenOfflineObj
MAPI Interfaces


IMAPIOfflineMgr::Advise

 Copy code hover
[image]

IMAPIOfflineMgr::Advise
See also Send feedback

Published: July 16, 2012

Registers a client to receive callbacks on an offline object.

C++
HRESULT COfflineObj::Advise(
      ULONG ulFlags,
      MAPIOFFLINE_ADVISEINFO* pAdviseInfo,
      ULONG* pulAdviseToken
);

Parameters

ulFlags

[in] Flags that modify behavior. Only the value MAPIOFFLINE_ADVISE_DEFAULT is supported.

pAdviseInfo

[in] Information about the type of callback, when to receive a callback, a callback interface for the caller, and other details. It also contains a client token that Outlook uses in sending subsequent notification callbacks to the client caller.

pulAdviseToken

[out] An advise token returned to the client caller for subsequently canceling callback for the object.

Return value

S_OK

The call was successful.

E_INVALIDARG

An invalid parameter has been specified.

E_NOINTERFACE

The callback interface specified in pAdviseInfo is not valid.

Remarks

Upon opening an offline object using HrOpenOfflineObj, a client obtains an offline object that supports IMAPIOfflineMgr. The client can check for the kinds of callbacks supported by the object by using IMAPIOffline::GetCapabilities. The client can determine the type and other details about the callback it wants, and then call IMAPIOfflineMgr::Advise to register to receive such callbacks about the object.

See also

Reference

IMAPIOffline::GetCapabilities
IMAPIOfflineMgr::Unadvise

Concepts

MAPI Constants
HrOpenOfflineObj


IMAPIOfflineMgr::Unadvise

 Copy code hover
[image]

IMAPIOfflineMgr::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels callbacks for an offline object.

C++
HRESULT COfflineObj::Unadvise(
      ULONG ulFlags,
      ULONG ulAdviseToken
);

Parameters

ulFlags

[in] Flags for canceling callback. Only the value MAPIOFFLINE_UNADVISE_DEFAULT is supported.

ulAdviseToken

[in] An advise token that identifies the callback registration that is to be canceled.

Return value

S_OK

The call was successful. This call must return S_OK.

Remarks

Removes the registration for the callback that was associated with ulAdviseToken returned from a prior call to IMAPIOfflineMgr::Advise. Causes the IMAPIOfflineMgr object to release its reference on the IMAPIOfflineNotify object associated with ulAdviseToken.

See also

Reference

IMAPIOfflineMgr::Advise

Concepts

MAPI Constants


IMAPIOfflineNotify : IUnknown

 Copy code hover
[image]

IMAPIOfflineNotify : IUnknown
See also Send feedback

Published: July 16, 2012

Supports Microsoft Outlook 2010 and Microsoft Outlook 2013 in sending notification callbacks to a client.

Provided by: | Client
Interface identifier: | IID_IMAPIOfflineNotify

Vtable Order

Notify

Sends notifications to a client about changes in connection state.

Remarks

The client must implement this interface and pass a pointer to it as a member in MAPIOFFLINE_ADVISEINFO when setting up callbacks using IMAPIOfflineMgr::Advise. Subsequently, Outlook 2010 or Outlook 2013 will be able to use this interface to send notification callbacks to the client.

See also

Reference

IMAPIOfflineMgr::Advise

Concepts

About the Offline State API
MAPI Constants
MAPIOFFLINE_ADVISEINFO


IMAPIOfflineNotify::Notify

 Copy code hover
[image]

IMAPIOfflineNotify::Notify
See also Send feedback

Published: July 16, 2012

Sends notifications to the client about changes in connection state.

C++
void STDMETHODCALLTYPE Notify(
    const MAPIOFFLINE_NOTIFY * pNotifyInfo
);

Parameters

pNotifyInfo

[in] The notification that Outlook sends to the client. The notification indicates the part of the connection state that has changed, the old connection state, and the new connection state.

Remarks

Outlook uses this method to send notification callbacks to a client. To make this interface available to Microsoft Outlook 2010 or Microsoft Outlook 2013, the client must implement this interface and pass a pointer to it as a member in MAPIOFFLINE_ADVISEINFO when setting up callbacks using IMAPIOfflineMgr::Advise.

The client also passes to MAPIOFFLINE_ADVISEINFO a client token that Outlook 2010 or Outlook 2013 uses in IMAPIOfflineNotify::Notify to identify the client registered for the notification callback.

In general, Outlook 2010 and Outlook 2013 can notify a client of online/offline changes and other connection state changes, but the Offline State API supports only notifications for online/offline changes. The client must ignore all other notifications.

See also

Concepts

About the Offline State API
MAPIOFFLINE_NOTIFY


IMAPIProgress : IUnknown

 Copy code hover
[image]

IMAPIProgress : IUnknown
See also Send feedback

Published: July 16, 2012

Implements a progress object that provides client applications with a progress indicator. A progress indicator is a user-interface display that shows the percentage of completion of an operation, such as copying folders between message stores. MAPI and client applications implement progress objects and service providers use them.

Header file: | Mapidefs.h
Exposed by: | Progress objects
Implemented by: | MAPI and client applications
Called by: | Service providers
Interface identifier: | IID_IMAPIProgress
Pointer type: | LPMAPIPROGRESS

Vtable Order

Progress | Updates the progress indicator with a display of the progress as it is made toward completion of the operation.
GetFlags | Returns flag settings from the progress object for the level of operation on which progress information is calculated.
GetMax | Returns the maximum number of items in the operation for which progress information is displayed.
GetMin | Returns the minimum value in the SetLimits method for which progress information is displayed.
SetLimits | Sets the lower and upper limits for the number of items in the operation, and the flags that control how progress information is calculated for the operation.

Remarks

MAPI includes an lpProgress parameter in many of the methods that perform potentially lengthy operations. lpProgress points to a client implementation of a progress object. Clients that implement the IMAPIProgress interface set this parameter to point to their implementation; clients that do not implement IMAPIProgress set the parameter to NULL. To display a progress indicator during processing of the operation, service providers use the progress object supplied by the client, if available, or a MAPI implementation (indicated when lpProgress is set to NULL).

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

Files | Function | Comment
MapiProgress.h and MapiProgress.cpp | Not applicable | If the IMAPIProgress setting is enabled, MFCMAPI will pass an IMAPIProgress implementation to all functions that MFCMAPI invokes that accept an implementation.

See also

Concepts

MFCMAPI as a Code Sample
MAPI Interfaces


IMAPIProgress::GetFlags

 Copy code hover
[image]

IMAPIProgress::GetFlags
See also Send feedback

Published: July 16, 2012

Returns flag settings from the progress object for the level of operation on which progress information is calculated.

C++
HRESULT GetFlags(
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[out] A bitmask of flags that controls the level of operation on which progress information is calculated. The following flag can be returned:

MAPI_TOP_LEVEL

Progress is being calculated for the top-level object, the object that is called by the client to begin the operation. For example, the top-level object in a folder copy operation is the folder that is being copied. When MAPI_TOP_LEVEL is not set, progress is calculated for a lower level object, or subobject. In the folder copy operation, a lower level object is one of the subfolders in the folder that is being copied.

Return value

S_OK

The flags value was returned successfully.

Remarks

MAPI enables service providers to differentiate between top-level objects and subobjects with the MAPI_TOP_LEVEL flag so that all objects involved in an operation can use the same IMAPIProgress implementation to show progress. This causes the indicator display to proceed smoothly in a single positive direction. Whether the MAPI_TOP_LEVEL flag is set determines how service providers set the other parameters in subsequent calls to the progress object.

The value returned by GetFlags is set initially by the implementer and subsequently by the service provider through a call to the IMAPIProgress::SetLimits method.

Notes to Implementers

Always initialize the flag to MAPI_TOP_LEVEL and then rely on service providers to clear it when appropriate. Service providers can clear and reset the flag by calling the IMAPIProgress::SetLimits method. For more information about how to implement GetFlags and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

When you display a progress indicator, make your first call a call to IMAPIProgress::GetFlags. The returned value should be MAPI_TOP_LEVEL, because all implementations initialize the contents of the lpulFlags parameter to this value. For more information about the sequence of calls to a progress object, see How to: Display a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProgress.cpp | CMAPIProgress::GetFlags | MFCMAPI uses the IMAPIProgress::GetFlags method to determine which flags are set. Returns MAPI_TOP_LEVEL unless flags have been set by using the IMAPIProgress::SetLimits method.

See also

Reference

IMAPIProgress::SetLimits
IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample
How to: Display a Progress Indicator
Implementing a Progress Indicator


IMAPIProgress::GetMax

 Copy code hover
[image]

IMAPIProgress::GetMax
See also Send feedback

Published: July 16, 2012

Returns the maximum number of items in the operation for which progress information is displayed.

C++
HRESULT GetMax(
  ULONG FAR * lpulMax
);

Parameters

lpulMax

[out] A pointer to the maximum number of items in the operation.

Return value

S_OK

The maximum number of items in the operation has been retrieved.

Remarks

The maximum value represents the end of the operation in numeric form. The value can be a global maximum value, used to represent the scope of the entire progress display, or a local value, used to represent only a part of the display.

The value of the flag setting affects whether the progress object understands the maximum value to be local or global. When the MAPI_TOP_LEVEL flag is set, the maximum value is considered to be global and is used to calculate progress for the entire operation. When MAPI_TOP_LEVEL is not set, the maximum value is considered to be local, and providers use it internally to display progress for lower level subobjects. Progress objects save the local maximum value only to return it to a provider through a GetMax call.

For more information about how and when to make calls to a progress object, see How to: Display a Progress Indicator.

Notes to Implementers

Initialize the maximum value to 1000. Service providers can reset this value by calling the IMAPIProgress::SetLimits method. For more information about how to implement GetMax and the other IMAPIProgress methods, see Implementing a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProgress.cpp | CMAPIProgress::GetMax | MFCMAPI uses the IMAPIProgress::GetMax method to get the maximum value for the progress object. Returns 1000 unless limits have previously been set with the IMAPIProgress::SetLimits method.

See also

Reference

IMAPIProgress::GetMin
IMAPIProgress::Progress
IMAPIProgress::SetLimits
IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample
How to: Display a Progress Indicator
Implementing a Progress Indicator


IMAPIProgress::GetMin

 Copy code hover
[image]

IMAPIProgress::GetMin
See also Send feedback

Published: July 16, 2012

Returns the minimum value in the IMAPIProgress::SetLimits method for which progress information is displayed.

C++
HRESULT GetMin(
  ULONG FAR * lpulMin
);

Parameters

lpulMin

[out] A pointer to the minimum number of items in the operation.

Return value

S_OK

The minimum number of items in the operation has been retrieved.

Remarks

The minimum value represents the start of the operation in numeric form. The value can be a global maximum value, used to represent the scope of the entire progress display, or a local value, used to represent only a part of the display.

The value of the flag setting affects whether the progress object understands the minimum value to be local or global. When the MAPI_TOP_LEVEL flag is set, the minimum value is considered to be global and is used to calculate progress for the entire operation. When MAPI_TOP_LEVEL is not set, the minimum value is considered local, and providers use it internally to display progress for lower level subobjects. Progress objects save the local minimum value only to return it to a provider through a GetMin call.

Notes to Implementers

Initialize the minimum value to 1. Service providers can reset this value by calling the IMAPIProgress::SetLimits method. For more information about how to implement GetMin and the other IMAPIProgress methods, see Implementing a Progress Indicator.

For more information about how and when to make calls to a progress object, see How to: Display a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProgress.cpp | CMAPIProgress::GetMin | MFCMAPI uses the IMAPIProgress::GetMin method to get the minimum value for the progress indicator. Returns 1 unless limits have been previously set by calling the IMAPIProgress::SetLimits method.

See also

Reference

IMAPIProgress::GetMax
IMAPIProgress::Progress
IMAPIProgress::SetLimits
IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample
How to: Display a Progress Indicator
Implementing a Progress Indicator


IMAPIProgress::Progress

 Copy code hover
[image]

IMAPIProgress::Progress
See also Send feedback

Published: July 16, 2012

Updates the progress indicator with a display of the progress as it is made toward completion of the operation.

C++
HRESULT Progress(
  ULONG ulValue,
  ULONG ulCount,
  ULONG ulTotal
);

Parameters

ulValue

[in] A number that indicates the current level of progress (calculated from the ulCount and ulTotal parameters or from the lpulMin and lpulMax parameters of the IMAPIProgress::SetLimits method) between the global lower limit and the global upper limit.

ulCount

[in] A number that indicates the currently processed item relative to the total.

ulTotal

[in] The total number of items to be processed during the operation.

Return value

S_OK

The progress indicator was successfully updated.

Notes to Implementers

The ulValue parameter will be equal to the global minimum value only at the start of the operation and to the global maximum value only at the completion of the operation.

Use the ulCount and ulTotal parameters, if available, to display an optional message such as "5 items completed out of 10." If ulCount and ulTotal are set to 0, decide whether to visually change the progress indicator. Some service providers set these parameters to 0 to indicate that they are processing a subobject whose progress is monitored relative to a parent object. In this situation, it makes sense to change the display only when the parent object reports progress. Some service providers pass 0 for these parameters every time.

For more information about how to implement Progress and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

Not all three of the parameters to IMAPIProgress::Progress are required. The only parameter that is required is ulValue, a number that indicates the percentage of progress. If the MAPI_TOP_LEVEL flag is set, you can also pass an object count and an object total. Some implementations use these values to display a phrase such as "5 items completed out of 10" with the progress indicator.

If you are copying all messages in a single folder, set ulTotal to the total number of messages being copied. If you are copying a folder, set ulTotal to the number of subfolders in the folder. If the folder to be copied contains no subfolders and only messages, set ulTotal to 1.

For more information about how and when to make calls to a progress object, see How to: Display a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProgress.cpp | CMAPIProgress::Progress | MFCMAPI uses the IMAPIProgress::Progress method to update the MFCMAPI status bar with the current percentage of progress, calculated from uValue and the current maximum and minimum values.

See also

Reference

IMAPIProgress::SetLimits
IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample
How to: Display a Progress Indicator
Implementing a Progress Indicator


IMAPIProgress::SetLimits

 Copy code hover
[image]

IMAPIProgress::SetLimits
See also Send feedback

Published: July 16, 2012

Sets the lower and upper limits for the number of items in the operation, and the flags that control how progress information is calculated for the operation.

C++
HRESULT SetLimits(
  LPULONG lpulMin,
  LPULONG lpulMax,
  LPULONG lpulFlags
);

Parameters

lpulMin

[in] A pointer to a variable that contains the lower limit of items in the operation.

lpulMax

[in] A pointer to a variable that contains the upper limit of items in the operation.

lpulFlags

[in] A bitmask of flags that controls the level of operation on which progress information is calculated. The following flag can be set:

MAPI_TOP_LEVEL

Uses the values in the IMAPIProgress::Progress method's ulCount and ulTotal parameters, which indicate the currently processed item and the total items, respectively, to increment progress on the operation. When this flag is set, the values of the global lower and upper limits have to be set.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Service providers call the IMAPIProgress::SetLimits method to set or clear the MAPI_TOP_LEVEL flag and to set local and global minimum and maximum values. The value of the flag setting affects whether the progress object understands the minimum and maximum values to be local or global. When the MAPI_TOP_LEVEL flag is set, these values are considered global and are used to calculate progress for the entire operation. Progress objects initialize the global minimum value to 1 and the global maximum value to 1000.

When MAPI_TOP_LEVEL is not set, the minimum and maximum values are considered local, and providers use them internally to display progress for lower level subobjects. Progress objects save the local minimum and maximum values only so that they can be returned to providers when the IMAPIProgress::GetMin and IMAPIProgress::GetMax methods are called.

For more information about how to implement SetLimits and the other IMAPIProgress methods, see Implementing a Progress Indicator.

For more information about how and when to make calls to a progress object, see How to: Display a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProgress.cpp | CMAPIProgress::SetLimits | MFCMAPI uses the IMAPIProgress::SetLimits method to set the maximum and minimum limits and flags for the progress object.

See also

Reference

IMAPIProgress::GetMax
IMAPIProgress::GetMin
IMAPIProgress::Progress
IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample
How to: Display a Progress Indicator
Implementing a Progress Indicator


IMAPIProp : IUnknown

 Copy code hover
[image]

IMAPIProp : IUnknown
See also Send feedback

Published: July 16, 2012

Enables clients, service providers, and MAPI to work with properties. All objects that support properties implement this interface.

Header file: | Mapidefs.h
Exposed by: | No object exposes this interface directly.
Implemented by: | Service providers and MAPI
Called by: | Client applications, service providers, and MAPI
Interface identifier: | IID_IMAPIProp
Pointer type: | LPMAPIPROP
Transaction model: | Abstract class, never implemented

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous error.
SaveChanges | Makes permanent any changes that were made to an object since the last save operation.
GetProps | Retrieves the property value of one or more properties of an object.
GetPropList | Returns property tags for all properties.
OpenProperty | Returns a pointer to an interface that can be used to access a property.
SetProps | Updates one or more properties.
DeleteProps | Deletes one or more properties from an object.
CopyTo | Copies or moves all properties, except for specifically excluded properties.
CopyProps | Copies or moves selected properties.
GetNamesFromIDs | Provides the property names that correspond to one or more property identifiers.
GetIDsFromNames | Provides the property identifiers that correspond to one or more property names.

Remarks

IMAPIProp is the base interface for the following interfaces:

  • IAttach

  • IMailUser

  • IMAPIContainer

  • IMAPIFormInfo

  • IMAPIStatus

  • IMessage

  • IMsgStore

  • IProfSect

  • IPropData

See also

Concepts

MAPI Interfaces


IMAPIProp::CopyProps

 Copy code hover
[image]

IMAPIProp::CopyProps
See also Send feedback

Published: July 16, 2012

Copies or moves selected properties.

C++
HRESULT CopyProps(
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpIncludeProps

[in] A pointer to a property tag array that specifies the properties to copy or move. PR_NULL (PidTagNull) cannot be included in the array. The lpIncludeProps parameter cannot be null.

ulUIParam

[in] A handle to the parent window of the progress indicator.

lpProgress

[in] A pointer to an implementation of a progress indicator. If null is passed in the lpProgress parameter, the progress indicator is displayed by using the MAPI implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface that must be used to access the object pointed to by the lpDestObj parameter. The lpInterface parameter must not be null.

lpDestObj

[in] A pointer to the object to receive the copied or moved properties.

ulFlags

[in] A bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DECLINE_OK

If CopyProps calls the IMAPISupport::DoCopyProps method to handle the copy or move operation, it should instead return immediately with the error value MAPI_E_DECLINE_COPY. The MAPI_DECLINE_OK flag is set by MAPI to limit recursion. Clients do not set this flag.

MAPI_DIALOG

Displays a progress indicator.

MAPI_MOVE

CopyProps should perform a move operation instead of a copy operation. When this flag is not set, CopyProps performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, CopyProps overwrites existing properties.

lppProblems

[in, out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, null, indicating that there is no need for error information. If lppProblems is a valid pointer on input, CopyProps returns detailed information about errors in copying one or more properties.

Return value

S_OK

Properties have been successfully copied or moved.

MAPI_E_COLLISION

A subobject cannot be copied because a subobject with the same display name, defined by the PR_DISPLAY_NAME (PidTagDisplayName) property, already exists in the destination object.

MAPI_E_DECLINE_COPY

The service provider does not implement the copy operation.

MAPI_E_FOLDER_CYCLE

The source object performing the copy or move operation directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for CopyProps. These errors apply to a single property.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and CopyProps does not support Unicode, or MAPI_UNICODE was not set and CopyProps supports only Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPIProp::CopyProps method copies or moves selected properties from the current object to a destination object. CopyProps is used mainly for replying to and forwarding messages, where only some of the properties from the original message travel with the reply or forwarded copy.

Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety, regardless of the use of properties indicated by the SPropTagArray structure. By default, CopyProps overwrites any properties in the destination object that match properties from the source object. If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new properties, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Implementers

You can provide a full implementation of CopyProps or rely on the implementation that MAPI provides in its support object. If you want to use the MAPI implementation, call the IMAPISupport::DoCopyProps method. However, if you do delegate processing to DoCopyProps and you are passed the MAPI_DECLINE_OK flag, avoid the support call and return MAPI_E_DECLINE_COPY instead. You will be called with this flag by MAPI to avoid the possible recursion that can occur when you copy folders.

Because the copy operation can be lengthy, you should display a progress indicator. Use the IMAPIProgress implementation that is passed in the lpProgress parameter, if there is one. If lpProgress is null, call the IMAPISupport::DoProgressDialog method to use the MAPI implementation.

Notes to Callers

Do not set the MAPI_DECLINE_OK flag; it is used by MAPI in its calls to message store provider CopyProps implementations.

Because copy and move operations can take time, it is wise to request the display of a progress indicator by setting the MAPI_DIALOG flag. You can set the lpProgress parameter to your implementation of IMAPIProgress, if you have one, or to null. If lpProgress is null, CopyProps will use the default progress indicator provided by MAPI.

You can suppress the display of a progress indicator by not setting the MAPI_DIALOG flag. CopyProps will ignore the ulUIParam and lpProgress parameters and avoid displaying the indicator.

CopyProps can report global and individual errors, or errors that occur with one or more of the properties. These individual errors are put in an SPropProblemArray structure. You can suppress error reporting at the property level by passing null, instead of a valid pointer, for the property problem array structure parameter.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When CopyProps returns S_OK, check for possible errors with individual properties in the structure. When CopyProps returns an error, no information is returned in the SPropProblemArray structure. Instead, call the IMAPIProp::GetLastError method to retrieve detailed error information.

If CopyProps returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If you are copying properties that are unique to the source object type, you must make sure that the destination object is of the same type. CopyProps does not prevent you from associating properties that typically belong to one type of object with another type of object. It is up to you to copy properties that make sense for the destination object. For example, you should not copy message properties to an address book container.

To ensure that you are copying between objects of the same type, check that the source and destination object are the same type, either by comparing object pointers or calling the IUnknown::QueryInterface method. Set the interface identifier pointed to by lpInterface to the standard interface for the source object. Also, ensure that the object type or PR_OBJECT_TYPE (PidTagObjectType) property is the same for the two objects. For example, if you are copying from a message, set lpInterface to IID_IMessage and the PR_OBJECT_TYPE for both objects to MAPI_MESSAGE.

If an invalid pointer is passed in the lpDestObj parameter, the results are unpredictable.

To copy a message's recipient list, call the message's CopyProps method and include the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property in the property tag array. To copy the message's attachments, include the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property.

To copy a folder or address book container's hierarchy or contents table, include the PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) or PR_CONTAINER_CONTENTS (PidTagContainerContents) properties in the property tag array. To include a folder's associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) property in the array.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | CopyNamedProps | MFCMAPI uses the IMAPIProp::CopyProps method to copy named properties from one message to another.
SingleMAPIPropListCtrl.cpp | CSingleMAPIPropListCtrl::OnPasteProperty | MFCMAPI uses the IMAPIProp::CopyProps method to paste a property that has been copied from another object.

See also

Reference

IMAPIFolder::CopyMessages
IMAPIProgress : IUnknown
IMAPIProp::CopyTo
IMAPIProp::GetLastError
IMAPISupport::DoCopyProps
IMAPISupport::DoProgressDialog
MAPIFreeBuffer
PidTagContainerContents Canonical Property
PidTagContainerHierarchy Canonical Property
PidTagDisplayName Canonical Property
PidTagFolderAssociatedContents Canonical Property
PidTagMessageAttachments Canonical Property
PidTagMessageRecipients Canonical Property
PidTagObjectType Canonical Property
SPropProblemArray
SPropTagArray
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIProp::CopyTo

 Copy code hover
[image]

IMAPIProp::CopyTo
See also Send feedback

Published: July 16, 2012

Copies or moves all properties, except for specifically excluded properties.

C++
HRESULT CopyTo(
 ULONG ciidExclude,
 LPCIID rgiidExclude,
 LPSPropTagArray lpExcludeProps,
 ULONG_PTR ulUIParam,
 LPMAPIPROGRESS lpProgress,
 LPCIID lpInterface,
 LPVOID lpDestObj,
 ULONG ulFlags,
 LPSPropProblemArray FAR * lppProblems
);

Parameters

ciidExclude

[in] The count of interfaces to exclude when properties are copied or moved.

rgiidExclude

[in] An array of interface identifiers (IIDs) that specify interfaces that should not be used when supplemental information is copied or moved to the destination object.

lpExcludeProps

[in] A pointer to a property tag array that identifies the property tags that should be excluded from the copy or move operation. Passing null in the lpExcludeProps parameter indicates that all of the object's properties should be copied or moved. CopyTo returns MAPI_E_INVALID_PARAMETER when the cValues member of the SPropProblemArray structure pointed to by lpExcludeProps is set to 0.

ulUIParam

[in] A handle to the parent window of the progress indicator.

lpProgress

[in] A pointer to a progress indicator implementation. If null is passed in the lpProgress parameter, MAPI provides the progress implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the object pointed to by the lpDestObj parameter. The lpInterface parameter must not be null.

lpDestObj

[in] A pointer to the object to receive the copied or moved properties.

ulFlags

[in] A bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DECLINE_OK

If CopyTo calls the IMAPISupport::DoCopyTo method to handle the copy or move operation, it should instead return immediately with the error value MAPI_E_DECLINE_COPY. The MAPI_DECLINE_OK flag is set by MAPI to limit recursion. Clients do not set this flag.

MAPI_DIALOG

Displays a progress indicator.

MAPI_MOVE

CopyTo should perform a move operation instead of a copy operation. When this flag is not set, CopyTo performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, CopyTo overwrites existing properties.

lppProblems

[in, out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, null, indicating no need for error information. If lppProblems is a valid pointer on input, CopyTo returns detailed information about errors in copying one or more properties.

Return value

S_OK

The properties have been successfully copied or moved.

MAPI_E_COLLISION

A subobject cannot be copied because a subobject with the same display name — specified by the PR_DISPLAY_NAME (PidTagDisplayName) property — already exists in the destination object.

MAPI_E_DECLINE_COPY

The service provider does not implement the copy operation.

MAPI_E_FOLDER_CYCLE

The source object performing the copy or move operation directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for CopyTo. The following errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and CopyTo does not support Unicode, or MAPI_UNICODE was not set and CopyTo supports only Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

By default, the IMAPIProp::CopyTo method copies or moves all of the current object's properties to a destination object. CopyTo is used when an object should be copied or moved exactly, with all or most of its properties intact.

Any subobjects in the source object are automatically included in the operation and are copied or moved in their entirety. By default, CopyTo overwrites any properties in the destination object that match properties from the source object. If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new properties, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Implementers

You can provide a full implementation of CopyTo or rely on the implementation that MAPI provides in its support object. If you want to use the MAPI implementation, call IMAPISupport::DoCopyTo. However, if you do delegate processing to DoCopyTo and you are passed the MAPI_DECLINE_OK flag, avoid the support call and return MAPI_E_DECLINE_COPY instead. MAPI will call with this flag to avoid the possible recursion that can happen when folders are copied.

Because the copy operation can be lengthy, you should display a progress indicator. Use the IMAPIProgress implementation passed in the lpProgress parameter, if there is one. If lpProgress is null, call the IMAPISupport::DoProgressDialog method to use the MAPI implementation.

Do not attempt to set any known read-only properties in the destination object; return MAPI_E_NO_ACCESS instead.

The source and destination objects should use the same interfaces. Return MAPI_E_INVALID_PARAMETER if lpInterface is not set.

Return MAPI_E_INTERFACE_NOT_SUPPORTED if all known interfaces are excluded.

Notes to Callers

Do not set the MAPI_DECLINE_OK flag; MAPI uses it in its calls to message store provider CopyTo implementations.

Because copy and move operations can take time, you should request the display of a progress indicator by setting the MAPI_DIALOG flag. You can set the lpProgress parameter to your implementation of IMAPIProgress, if you have one, or to null. If lpProgress is null, CopyTo will use the default progress indicator that MAPI provides.

You can suppress the display of a progress indicator by not setting the MAPI_DIALOG flag. CopyTo will ignore the ulUIParam and lpProgress parameters and will not display the indicator.

CopyTo can report global and individual errors, or errors that occur with one or more properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing null, instead of a valid pointer, for the property problem array structure parameter.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When CopyTo returns S_OK, check for possible errors with individual properties in the structure. When CopyTo returns an error, no information is returned in the SPropProblemArray structure. Instead, call IMAPIProp::GetLastError to retrieve detailed error information.

If CopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If you copy properties that are unique to the source object type, you must ensure that the destination object is of the same type. CopyTo does not prevent you from associating properties that typically belong to one type of object with another type of object. It is up to you to copy properties that make sense for the destination object. For example, you should not copy message properties to an address book container.

To ensure that you copy between objects of the same type, check that the source and destination object are the same type, either by comparing object pointers or calling IUnknown::QueryInterface. Set the interface identifier pointed to by lpInterface to the standard interface for the source object. Also, be sure that the object type or PR_OBJECT_TYPE (PidTagObjectType) property is the same for the two objects. For example, if you copy from a message, set lpInterface to IID_IMessage and the PR_OBJECT_TYPE for both objects to MAPI_MESSAGE.

If an invalid pointer is passed in the lpDestObj parameter, the results are unpredictable.

Excluding properties on a CopyTo call can be useful. For example, some objects have properties that are specific to a single instance of the object, such as the date and time of message delivery. To avoid copying a message's delivery time when you copy the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) in the property tag exclude array. To exclude a message's recipient list, add the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property to the exclude array. To exclude a message's attachments, add the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property to the array.

Similarly, prevent the copying or moving of a folder or address book container's hierarchy or contents table by including PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) or PR_CONTAINER_CONTENTS (PidTagContainerContents) in the property tag exclude array.

To exclude properties from the copy or move operation, include their property tags in the lpExcludeProps parameter. If you pass the results of the PROP_TAG macro to build a property tag from a specific identifier in the property tag array, all properties with that identifier will be excluded. For example, the following entry in the property tag array causes all properties with an identifier of 0x8002 to be excluded, regardless of type:

PROP_TAG(PT_LONG, 0x8002)

The PR_NULL (PidTagNull) property tag cannot be included in the lpExcludeProps array.

The usefulness of the CopyTo feature for excluding interfaces is perhaps not as obvious as the usefulness of excluding properties. You can exclude an interface when you copy to an object that has no knowledge of a group of properties. For example, if you copy properties from a folder to an attachment, the only properties that the attachment can work with are the generic properties available with any IMAPIProp implementation. By excluding IMAPIFolder from the copy operation, the attachment will not receive any of the more specific folder properties.

When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding IMAPIContainer causes folders or address book containers to be excluded, depending on the type of provider. Do not exclude IMAPIProp or IUnknown because so many interfaces derive from them.

Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | LoadFromMSG | MFCMAPI uses the IMAPIProp::CopyTo method to copy properties from a .msg file to an IMAPIMessageSite object.
FolderDlg.cpp | CFolderDlg::HandlePaste | MFCMAPI uses the IMAPIProp::CopyTo method to copy properties from a source message to a target message during a paste operation.

See also

Reference

IMAPIFolder::CopyMessages
IMAPIProp::GetLastError
IMAPIMessageSite : IUnknown
IMAPIProgress : IUnknown
IMAPISupport::DoProgressDialog
IMAPISupport::DoCopyTo
MAPIFreeBuffer
PidTagContainerContents Canonical Property
PidTagContainerHierarchy Canonical Property
PidTagMessageAttachments Canonical Property
PidTagMessageDeliveryTime Canonical Property
PidTagMessageRecipients Canonical Property
PidTagObjectType Canonical Property
SPropProblemArray
SPropTagArray
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIProp::DeleteProps

 Copy code hover
[image]

IMAPIProp::DeleteProps
See also Send feedback

Published: July 16, 2012

Deletes one or more properties from an object.

C++
HRESULT DeleteProps(
  LPSPropTagArray lpPropTagArray,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpPropTagArray

[in] A pointer to an array of property tags that indicate the properties to delete. The cValues member of the SPropTagArray structure pointed to by lpPropTagArray must not be zero, and the lpPropTagArray parameter itself must not be NULL.

lppProblems

[in, out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, NULL, which indicates that there is no need for error information. If lppProblems is a valid pointer on input, DeleteProps returns detailed information about errors in deleting one or more properties.

Return value

S_OK

Properties were successfully deleted.

MAPI_E_NO_ACCESS

The caller has insufficient permissions to delete properties.

Remarks

The IMAPIProp::DeleteProps method removes one or more properties from the current object.

Notes to Implementers

You do not have to allow properties to be deleted from all objects. If the object is not modifiable, return MAPI_E_NO_ACCESS from the DeleteProps method.

Notes to Callers

You do not have to set the property type for each property tag in the property tag array pointed to by the lpPropTagArray parameter. Property types are ignored; only the property identifiers are used.

Be aware that some objects do not allow modification and that these objects return MAPI_E_NO_ACCESS from the DeleteProps method. Other objects allow some properties to be deleted, but not others. When there is a problem deleting only some of the properties, DeleteProps returns S_OK. If you have passed a valid pointer in the lppProblems parameter, DeleteProps will set the pointer to an SPropProblemArray structure that contains detailed information about the problems with each property. For example, if you are deleting all of the properties of a message and there is a problem with one or more of its attachments, the SPropProblemArray structure will contain an entry for the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property.

The structure pointed to by lppProblems is only valid if DeleteProps returns S_OK. If DeleteProps returns an error, do not attempt to use the SPropProblemArray structure. Instead, call the object's IMAPIProp::GetLastError method to obtain more information about the error.

Free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | DeleteProperty | MFCMAPI uses the IMAPIProp::DeleteProps method to delete a property from an object.

See also

Reference

IMAPIProp::GetLastError
IMAPIProp::GetProps
IMAPIProp::SaveChanges
MAPIFreeBuffer
SPropProblemArray
SPropTagArray
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIProp::GetIDsFromNames

 Copy code hover
[image]

IMAPIProp::GetIDsFromNames
See also Send feedback

Published: July 16, 2012

Provides the property identifiers that correspond to one or more property names.

C++
HRESULT GetIDsFromNames(
  ULONG cPropNames,
  LPMAPINAMEID FAR * lppPropNames,
  ULONG ulFlags,
  LPSPropTagArray FAR * lppPropTags
);

Parameters

cPropNames

[in] The count of property names pointed to by the lppPropNames parameter. If lppPropNames is NULL, the cPropNames parameter must be 0.

lppPropNames

[in] A pointer to an array of property names, or NULL. Passing NULL requests property identifiers for all property names in all property sets about which the object has information. The lppPropNames parameter must not be NULL if the MAPI_CREATE flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that indicates how the property identifiers should be returned. The following flag can be set:

MAPI_CREATE

Assigns a property identifier, if one has not yet been assigned, to one or more of the names included in the property name array pointed to by lppPropNames. This flag internally registers the identifier in the name-to-identifier mapping table.

lppPropTags

[out] A pointer to a pointer to an array of property tags that contains existing or newly assigned property identifiers. The property types for the property tags in this array are set to PT_UNSPECIFIED.

Return value

S_OK

The identifiers for the specified property names were successfully returned.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_E_NOT_ENOUGH_MEMORY

Insufficient memory was available to retrieve the identifiers.

MAPI_E_TOO_BIG

The operation cannot be performed because it requires too many property tags to be returned.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more property identifiers could not be returned. The corresponding property type for each unavailable property is set to PT_ERROR and its identifier to zero. When this warning is returned, handle the call as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPIProp::GetIDsFromNames method retrieves an array of property tags that hold the property identifiers for one or more named properties. IMAPIProp::GetIDsFromNames can be called to do the following:

  • Create identifiers for new names.

  • Retrieve identifiers for specific names.

  • Retrieve identifiers for all named properties that are included in the object's mapping.

Named properties are typically used by message store providers for folders and messages. Other objects, such as messaging users and profile sections, might not support the association of names to property identifiers and might return MAPI_E_NO_SUPPORT from GetIDsFromNames.

If there is an error that returns an identifier for a particular name, GetIDsFromNames returns MAPI_W_ERRORS_RETURNED and sets the property type in the property tag array entry that corresponds to the name to PT_ERROR and the identifier to zero.

Name-to-identifier mapping is represented by an object's PR_MAPPING_SIGNATURE (PidTagMappingSignature) property. PR_MAPPING_SIGNATURE contains a MAPIUID structure that indicates the service provider responsible for the object. If the PR_MAPPING_SIGNATURE property is the same for two objects, assume that these objects use the same name-to-identifier mapping.

Notes to Implementers

The identifiers that you pass back in the property tag array pointed to by the lppPropNames parameter must be in the 0x8000 to 0xFFFE range. The entries in this array must be in the same order as the names passed in the property name array pointed to by lppPropNames.

If you support named properties on a container, use the same name-to-identifier mapping for all objects in your container (that is, do not use a different mapping for each folder in your message store or each message in your folder).

Notes to Callers

Because the property types for the returned identifiers in the property tag array pointed to by lppPropTags are set to PT_UNSPECIFIED, you will have to call the IMAPIProp::SetProps method to retrieve the accurate types.

If you move or copy objects with named properties, and the source and destination objects have different mapping signatures as indicated by the values of their PR_MAPPING_SIGNATURE properties, you must preserve the names during these operations. To preserve property names, adjust the corresponding property identifiers to match the name-to-identifier mapping of the destination object.

Some objects have a limit as to the number of property identifiers they can name. If a call to GetIDsFromNames causes this limit to be exceeded, the method returns MAPI_E_TOO_BIG. In this case, query by identifier.

For more information, see MAPI Named Properties.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
SingleMAPIPropListCtrl.cpp | CSingleMAPIPropListCtrl::FindAllNamedPropsUsed | MFCMAPI uses the IMAPIProp::GetIDsFromNames method to obtain property tags for all named properties that have been mapped.

See also

Reference

IMAPIProp::GetNamesFromIDs
IMAPIProp::SetProps
MAPINAMEID
MAPIUID
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Named Properties
Using Macros for Error Handling


IMAPIProp::GetLastError

 Copy code hover
[image]

IMAPIProp::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] A handle to the error code generated in the previous method call.

ulFlags

[in] A bitmask of flags that indicates the format for the text returned in the MAPIERROR structure pointed to by lppMAPIError. The following flag can be set:

MAPI_UNICODE

The strings should be in Unicode format. If the MAPI_UNICODE flag is not set, the strings should be in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no error information to return.

Return value

S_OK

The error information was returned.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

The IMAPIProp::GetLastError method supplies information about a prior method call that failed. Clients can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

All of the implementations of GetLastError provided by MAPI are ANSI implementations, except for the IAddrBook implementation. The GetLastError method included with IAddrBook supports Unicode.

Notes to Implementers

The details of a remote transport provider's implementation of this method and what messages this method returns are up to the transport provider, because the particular error conditions that lead to various HRESULT values will be different for different transport providers.

Notes to Callers

You can use the MAPIERROR structure pointed to by the lppMAPIError parameter, if GetLastError supplies one, only if the return value is S_OK. Sometimes GetLastError cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

To release the memory for the MAPIERROR structure, call the MAPIFreeBuffer function.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

IAddrBook : IMAPIProp
MAPIERROR
MAPIFreeBuffer
IMAPIProp : IUnknown

Concepts

MAPI Extended Errors


IMAPIProp::GetNamesFromIDs

 Copy code hover
[image]

IMAPIProp::GetNamesFromIDs
See also Send feedback

Published: July 16, 2012

Provides the property names that correspond to one or more property identifiers.

C++
HRESULT GetNamesFromIDs(
  LPSPropTagArray FAR * lppPropTags,
  LPGUID lpPropSetGuid,
  ULONG ulFlags,
  ULONG FAR * lpcPropNames,
  LPMAPINAMEID FAR * FAR * lpppPropNames
);

Parameters

lppPropTags

[in, out] On input, a pointer to an SPropTagArray structure that contains an array of property tags; otherwise, NULL, indicating that all names should be returned. The cValues member for the property tag array cannot be 0. If lppPropTags is a valid pointer on input, GetNamesFromIDs returns names for each property identifier included in the array.

lpPropSetGuid

[in] A pointer to a GUID, or GUID structure, that identifies a property set. The lpPropSetGuid parameter can point to a valid property set or can be NULL.

ulFlags

[in] A bitmask of flags that indicates the type of names to be returned. The following flags can be used (if both flags are set, no names will be returned):

MAPI_NO_IDS

Requests that only names stored as Unicode strings be returned.

MAPI_NO_STRINGS

Requests that only names stored as numeric identifiers be returned.

lpcPropNames

[out] A pointer to a count of the property name pointers in the array pointed to by the lppPropNames parameter.

lpppPropNames

[out] A pointer to an array of pointers to MAPINAMEID structures that contains property names.

Return value

S_OK

The property names were successfully returned.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but names for one or more properties could not be returned. The property tags for the failing properties have a property type of PT_ERROR. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

MAPI_E_INVALID_PARAMETER

The cValues member of one or more of the entries in the property tag array pointed to by lppPropTags is set to 0.

Remarks

While access to most properties is by property identifier, some properties can be accessed by name. The IMAPIProp::GetNamesFromIDs method can be called to do the following:

  • Retrieve names for specific property identifiers in a specific property set.

  • Retrieve names for specific property identifiers in any property set.

  • Retrieve names for all named properties that are included in the object's mapping.

If lppPropTags points to a valid property tag array with one or more property identifiers, and lpPropSetGuid points to a valid property set, GetNamesFromIDs ignores the property set and the property types and returns all of the names that map to the specified identifiers.

If lppPropTags points to a valid property tag array with one or more property identifiers and lpPropSetGuid is NULL, GetNamesFromIDs returns all of the names that map to the specified identifiers.

If a specified identifier does not have a name, GetNamesFromIDs returns NULL in that identifier's place in the structure returned in lpppPropNames and also returns MAPI_W_ERRORS_RETURNED.

If both lpPropSetGuid and lppPropTags are NULL, GetNamesFromIDs allocates a new property tag array and returns all of the names for all of the named properties for the object.

When there are no names to be returned, perhaps because there are no properties in the requested property set or all of the properties are of a type excluded by the flags, GetNamesFromIDs does the following:

  • Returns S_OK.

  • Allocates a new SPropTagArray structure, setting the cValues member to 0.

  • Sets the contents of lpcPropNames to 0.

  • Sets the contents of lpppPropNames to NULL.

Notes to Implementers

If lpPropSetGuid points to a valid property set and lppPropTags is NULL, the result is undefined. You can use one of the following strategies:

  • Ignore the property set and return the names for the identifiers in the property tag array.

  • Return the names for only the identifiers in the property tag array that belong to the specified property set.

  • Fail the call, returning MAPI_E_INVALID_PARAMETER.

Notes to Callers

To retrieve all of the named properties for an object, you must first call the object's IMAPIProp::GetPropList method and then pass the returned identifiers that are above the 0x8000 range to GetNamesFromIDs.

If you pass a valid property set but not a valid property tag array, be prepared for unpredictable results. Some implementations of GetNamesFromIDs ignore the property set and return the names for the identifiers in the property tag array. Some implementations return MAPI_E_INVALID_PARAMETER. Still other implementations return names for identifiers of all properties in the property set. If the property set is PS_PUBLIC_STRINGS, GetNamesFromIDs can return all names that were ever created. Whether the service provider stores a property under the identifiers associated with the public strings is immaterial.

When you are finished with the property names, check the contents of the lpcPropNames parameter to determine whether any names were returned. If so, call the MAPIFreeBuffer function to free the memory pointed to by lppPropTags and lpppPropNames when a successful result is returned. One call to MAPIFreeBuffer is sufficient for each parameter; you do not have to traverse the array of pointers and free each MAPINAMEID structure individually.

For more information about named properties, see MAPI Named Properties.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
SingleMAPIPropListCtrl.cpp | CSingleMAPIPropListCtrl::FindAllNamedProps | MFCMAPI uses the IMAPIProp::GetNamesFromIDs method to look up named properties that have previously been mapped.

See also

Reference

GUID
IMAPIProp::GetIDsFromNames
IMAPIProp::GetPropList
MAPIFreeBuffer
MAPINAMEID
SPropTagArray
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Named Properties
Using Macros for Error Handling


IMAPIProp::GetPropList

 Copy code hover
[image]

IMAPIProp::GetPropList
See also Send feedback

Published: July 16, 2012

Returns property tags for all properties.

C++
HRESULT GetPropList(
  ULONG ulFlags,
  LPSPropTagArray FAR * lppPropTagArray
);

Parameters

ulFlags

[in] A bitmask of flags that controls the format for the strings in the returned property tags. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppPropTagArray

[out] A pointer to a pointer to the property tag array that contains tags for all of the object's properties.

Return value

S_OK

All of the property tags were returned successfully.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

The IMAPIProp::GetPropList method retrieves the property tag for each property currently supported by an object. If the object does not currently support any properties, GetPropList returns a property tag array with the cValues member set to 0.

The scope of properties returned by GetPropList varies from provider to provider. Some service providers exclude those properties for which the caller does not have access. All providers return properties of type PT_OBJECT.

If the object does not support Unicode, GetPropList returns MAPI_E_BAD_CHARWIDTH, even if there are no string properties defined for the object.

Notes to Implementers

Remote transport providers implement GetPropList exactly as specified here. There are no special concerns. Your implementation should, of course, return the same list of properties as supported by the IMAPIProp::GetProps method.

Notes to Callers

Call the MAPIFreeBuffer function to free the property tag array pointed to by lppPropTagArray .

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | GetPropsNULL | MFCMAPI uses the IMAPIProp::GetPropList method to get a property list to pass to GetProps.

See also

Reference

IMAPIProp::GetProps
MAPIFreeBuffer
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIProp::GetProps

 Copy code hover
[image]

IMAPIProp::GetProps
See also Send feedback

Published: July 16, 2012

Retrieves the property value of one or more properties of an object.

C++
HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

Parameters

lpPropTagArray

[in] A pointer to an array of property tags that identify the properties whose values are to be retrieved. The lpPropTagArray parameter must be either NULL, indicating that values for all properties of the object should be returned, or point to an SPropTagArray structure that contains one or more property tags.

ulFlags

[in] A bitmask of flags that indicates the format for properties that have the type PT_UNSPECIFIED. The following flag can be set:

MAPI_UNICODE

The string values for these properties should be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the string values should be returned in the ANSI format.

lpcValues

[out] A pointer to a count of property values pointed to by the lppPropArray parameter. If lppPropArray is NULL, the content of the lpcValues parameter is zero.

lppPropArray

[out] A pointer to a pointer to the retrieved property values.

Return value

S_OK

The property values were successfully retrieved.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed. The aulPropTag member of the property value for each unavailable property has a property type of PT_ERROR and an identifier of zero. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

MAPI_E_INVALID_PARAMETER

Zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray.

Remarks

The IMAPIProp::GetProps method obtains the property values of one or more properties of an object.

The property values are returned in the same order as they were requested (that is, the order of properties in the property tag array pointed to by lpPropTagArray matches the order in the array of property value structures pointed to by lppPropArray).

The property types specified in the aulPropTag members of the property tag array indicate the type of value that should be returned in the Value member of each property value structure. However, if the caller does not know the type of a property, the type in the aulPropTag member can be set instead to PT_UNSPECIFIED. In retrieving the value, GetProps sets the correct type in the aulPropTag member of the property value structure for the property.

If property types are specified in the SPropTagArray in lpPropTagArray, the property values in the SPropValue returned in lppPropArray have types that exactly match the requested types, unless an error value is returned instead.

String properties can have one of two property types: PT_UNICODE to represent the Unicode format and PT_STRING8 to represent the ANSI format. If the MAPI_UNICODE flag is set in the ulFlags parameter, whenever GetProps cannot determine the appropriate format for a string property, it returns its value in the Unicode format. GetProps cannot determine an exact string property type in the following situations:

  • The lpPropTagArray parameter is set to NULL to request all properties.

  • The aulPropTag member includes the value PT_UNSPECIFIED as its property type in the property tag array.

If the lpPropTagArray parameter is set to NULL to retrieve all of the properties of the object and no properties exist, GetProps does the following:

  • Returns S_OK.

  • Sets the count value in the cValues member of the property value structure to 0.

  • Sets the contents of lpcValues to 0.

  • Sets lppPropArray to NULL.

GetProps must not return multiple-value properties with cValues set to 0.

Notes to Implementers

Call the MAPIAllocateBuffer function to allocate memory initially for the SPropValue structure pointed to by lpPropTagArray; call MAPIAllocateMore to allocate any additional memory needed for the structure's members.

Return MAPI_W_ERRORS_RETURNED if you cannot retrieve the value for one or more of the requested properties. In the property value structure, set the type in the aulPropTag member to PT_ERROR and the Value member to a status code that describes the error. For example, if you have to convert a string to Unicode and do not support Unicode, set the Value member to MAPI_E_BAD_CHARWIDTH. If the property is too large, set it to MAPI_E_NOT_ENOUGH_MEMORY. If the object does not support the property, set it to MAPI_E_NOT_FOUND.

A remote transport provider's implementation of the GetProps method must return the folder's property values for properties requested by the caller. Your implementation must do the following:

  • Allocate a property value array to return to the caller and store its address in the property value pointer parameter passed in for that purpose.

  • Copy the property tags from the folder's properties into the property tags in the property value array according to the array of property tags passed to GetProps.

  • Ensure that the property type is set for all property tags passed to GetProps. The caller can pass in a property type of PT_UNSPECIFIED, in which case GetProps must set the correct property type for that property tag.

  • Set the value of each property in the property value array according to its tag. For example, if the property tag requested by the caller is PR_OBJECT_TYPE (PidTagObjectType), GetProps can set the value to MAPI_FOLDER.

  • If the caller passes in any property tags that your implementation does not handle, you can set the property tag to PT_ERROR for those properties, and set the property value to MAPI_E_NOT_FOUND.

  • Return S_OK if no errors occurred or MAPI_W_ERRORS_RETURNED if there were errors.

A remote transport provider's implementation of the GetProps method must support the following properties at a minimum:

  • PR_ACCESS (PidTagAccess)

  • PR_ACCESS_LEVEL (PidTagAccessLevel)

  • PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)

  • PR_CONTENT_COUNT (PidTagContentCount)

  • PR_CREATION_TIME (PidTagCreationTime)

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_DISPLAY_TYPE (PidTagDisplayType)

  • PR_FOLDER_TYPE (PidTagFolderType)

  • PR_OBJECT_TYPE

  • PR_SUBFOLDERS (PidTagSubfolders)

Notes to Callers

For properties of type PT_OBJECT, call the IMAPIProp::OpenProperty method instead of GetProps.

For secure properties, do not expect to retrieve them by calling GetProps with the lppPropTagArray parameter set to NULL. You must explicitly set a secure property's identifier in the aulPropTag member of its property tag array when you call GetProps. When and how a secure property is available is up to the service provider.

Free the returned SPropValue structure by calling the MAPIFreeBuffer function only if GetProps returns S_OK or MAPI_W_ERRORS_RETURNED.

If GetProps returns MAPI_W_ERRORS_RETURNED because it could not access one or more properties, check the property tags of the returned properties. The failed properties will have the following values set in their property value structure:

  • The property type in the aulPropTag member set to PT_ERROR.

  • The property value in the Value member set to a status code for the error, such as MAPI_E_NOT_FOUND.

Properties that fail because they are too large to conveniently be returned in the property value structure have their Value member set to MAPI_E_NOT_ENOUGH_MEMORY. Typically, this occurs with string or binary properties of type PT_STRING8, PT_UNICODE, or PT_BINARY when the value of the property is 4 KB or larger. Call IMAPIProp::OpenProperty to retrieve large properties.

Not all implementations of GetProps support both the Unicode and ANSI formats for character strings. When a particular property requires string format conversion and GetProps cannot support it, the Value member for the property is set to MAPI_E_BAD_CHARWIDTH.

To check if a PST is a SharePoint PST, mount the PST using IMAPISession::OpenMsgStore, then call GetProps on the message store object requesting this property. If it exists, you can assume the PST has been configured for SharePoint; if not, the PST has not been configured as a SharePoint PST.

For more information about how to use GetProps to access properties, see Retrieving MAPI Properties.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | GetPropsNULL | MFCMAPI uses the IMAPIProp::GetProps method to obtain all properties for an object by passing either NULL or the array returned by the IMAPIProp::GetPropList method in the lpPropTagArray parameter.

See also

Reference

IMAPIProp::GetPropList
IMAPIProp::OpenProperty
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
SPropTagArray
SPropValue
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample
Retrieving MAPI Properties
Using Macros for Error Handling


IMAPIProp::OpenProperty

 Copy code hover
[image]

IMAPIProp::OpenProperty
See also Send feedback

Published: July 16, 2012

Returns a pointer to an interface that can be used to access a property.

C++
HRESULT OpenProperty(
  ULONG ulPropTag,
  LPCIID lpiid,
  ULONG ulInterfaceOptions,
  ULONG ulFlags,
  LPUNKNOWN FAR * lppUnk
);

Parameters

ulPropTag

[in] The property tag for the property to be accessed. Both the identifier and the type must be included in the property tag.

lpiid

[in] A pointer to the identifier for the interface to be used to access the property. The lpiid parameter must not be null.

ulInterfaceOptions

[in] Data that relates to the interface identified by the lpiid parameter.

ulFlags

[in] A bitmask of flags that controls access to the property. The following flags can be set:

MAPI_CREATE

If the property does not exist, it should be created. If the property does exist, the current value of the property should be discarded. When a caller sets the MAPI_CREATE flag, it should also set the MAPI_MODIFY flag.

MAPI_DEFERRED_ERRORS

Allows OpenProperty to return successfully, possibly before the object is fully available to the caller. If the object is not available, making a subsequent object call can raise an error.

MAPI_MODIFY

MAPI_MODIFY is required in these situations:

  • When opening a stream property, such as IID_IStream, to modify it.

  • When opening an embedded message attachment, such as PR_ATTACH_DATA_OBJ opened with IID_IMessage, to modify it.

lppUnk

[out] A pointer to the requested interface to be used for property access.

Return value

S_OK

The requested interface pointer was successfully returned.

MAPI_E_INTERFACE_NOT_SUPPORTED

The requested interface is not supported for this property.

MAPI_E_NO_ACCESS

The caller has insufficient permissions to access the property.

MAPI_E_NO_SUPPORT

The object cannot provide access to this property through the requested interface.

MAPI_E_NOT_FOUND

The requested property does not exist and MAPI_CREATE was not set in the ulFlags parameter.

MAPI_E_INVALID_PARAMETER

The property type in the tag is set to PT_UNSPECIFIED.

Remarks

The IMAPIProp::OpenProperty method provides access to a property through a particular interface. OpenProperty is an alternative to the IMAPIProp::GetProps and IMAPIProp::SetProps methods. When either GetProps or SetProps fails because the property is too large or too complex, call OpenProperty. OpenProperty is typically used to access properties of type PT_OBJECT.

Notes to Callers

To access message attachments, open the PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property with a different interface identifier, depending on the type of attachment. The following table describes how to call OpenProperty for the different types of attachments:

Type of attachment | Interface identifier to use
Binary | IID_IStream
String | IID_IStream
Message | IID_IMessage
OLE 2.0 | IID_IStreamDocfile

IStreamDocfile is a derivative of the IStream interface that is based on an OLE 2.0 compound file. IStreamDocfile is the best choice for accessing OLE 2.0 attachments because it involves the least amount of overhead. You can use IID_IStreamDocFile for those properties that contain data stored in structured storage available through the IStorage interface.

For more information about how to use OpenProperty with attachments, see the PR_ATTACH_DATA_OBJ property and Opening an Attachment.

Do not use the IStream pointer that you receive to call either its Seek or SetSize method unless you use a zero position or size variable. Also, do not rely on the value of the plibNewPosition output parameter returned from the Seek call.

If you call OpenProperty to access a property with the IStream interface, use only that interface to make changes to it. Do not attempt to update the property with any of the other IMAPIProp : IUnknown methods, such as SetProps or IMAPIProp::DeleteProps.

Do not try to open a property with OpenProperty more than once. The results are undefined because they can vary from provider to provider.

If you need to modify the property to be opened, set the MAPI_MODIFY flag. If you are not sure whether the object supports the property but you think it should, set the MAPI_CREATE and MAPI_MODIFY flags. Whenever MAPI_CREATE is set, MAPI_MODIFY must also be set.

You are responsible for recasting the interface pointer returned in the lppUnk parameter to one that is appropriate for the interface specified in the lpiid parameter. You must also use the returned pointer to call its IUnknown::Release method when you are finished with it.

Sometimes setting the flags in the ulFlags parameter is not enough to indicate the type of access to the property that is required. You can put additional data, such as flags, in the ulInterfaceOptions parameter. This data is interface dependent. Some interfaces (such as IStream) use it, and others do not. For example, when you open a property to be modified with IStream, set the STGM_WRITE flag in the ulInterfaceOptions parameter in addition to MAPI_MODIFY. When you open a table by using the IMAPITable interface, you can set ulInterfaceOptions to MAPI_UNICODE to indicate whether the columns in the table that hold string properties should be in Unicode format.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
StreamEditor.cpp | CStreamEditor::ReadTextStreamFromProperty | MFCMAPI uses the IMAPIProp::OpenProperty method to retrieve a stream interface for large text and binary properties.

See also

Reference

HrIStorageFromStream
IMAPIProp::DeleteProps
IMAPIProp::GetProps
IMAPIProp::SetProps
IMAPISupport::IStorageFromStream
IMAPITable : IUnknown
IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample
Opening an Attachment


IMAPIProp::SaveChanges

 Copy code hover
[image]

IMAPIProp::SaveChanges
See also Send feedback

Published: July 16, 2012

Makes permanent any changes that were made to an object since the last save operation.

C++
HRESULT SaveChanges(
  ULONG ulFlags
);

Parameters

ulFlags

[in] A bitmask of flags that controls what happens to the object when the IMAPIProp::SaveChanges method is called. The following flags can be set:

NON_EMS_XP_SAVE

Indicates that the message has not been delivered from a Exchange Server. This flag should be used in combination with the IMAPIFolder::CreateMessage method and the ITEMPROC_FORCE flag to indicate to a PST store that the message is eligible for rules processing before the Personal Folders file (PST) store notifies any listening client that the message has arrived. This rules processing only applies to new messages that are created with IMAPIFolder::CreateMessage on a server that is not an Exchange Server, in which case the Exchange Server would have already processed rules on the message.

FORCE_SAVE

Changes should be written to the object, overriding any previous changes that were made to the object, and the object should be closed. Read/write permission must be set for the operation to succeed. The FORCE_SAVE flag is used after a previous call to SaveChanges returned MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

Changes should be committed and the object should be kept open for reading. No additional changes will be made.

KEEP_OPEN_READWRITE

Changes should be committed and the object should be kept open for read/write permission. This flag is usually set when the object was first opened for read/write permission. Subsequent changes to the object are allowed.

MAPI_DEFERRED_ERRORS

Allows SaveChanges to return successfully, possibly before the changes have been fully committed.

SPAMFILTER_ONSAVE

Enables spam filtering on a message that is being saved. Spam filtering support is available only if the sender's e-mail address type is Simple Mail Transfer Protocol (SMTP), and the message is being saved to a store for a Personal Folders file (PST).

Return value

S_OK

The commitment of changes was successful.

MAPI_E_NO_ACCESS

SaveChanges cannot keep the object open for read-only permission if KEEP_OPEN_READONLY is set, or read/write permission if KEEP_OPEN_READWRITE is set. No changes are committed.

MAPI_E_OBJECT_CHANGED

The object has changed since it was opened.

MAPI_E_OBJECT_DELETED

The object has been deleted since it was opened.

Remarks

The IMAPIProp::SaveChanges method makes property changes permanent for objects that support the transaction model of processing, such as messages, attachments, address book containers, and messaging user objects. Objects that do not support transactions, such as folders, message stores, and profile sections, make changes permanent immediately. No call to SaveChanges is required.

Because service providers do not have to generate an entry identifier for their objects until all properties have been saved, an object's PR_ENTRYID (PidTagEntryId) property might not be available until after its SaveChanges method has been called. Some providers wait until the KEEP_OPEN_READONLY flag is set on the SaveChanges call. KEEP_OPEN_READONLY indicates that the changes to be saved in the current call will be the last changes that will be made on the object.

Some message store implementations do not show newly created messages in a folder until a client saves the message changes by using SaveChanges and releases the message objects by using the IUnknown::Release method. In addition, some object implementations cannot generate a PR_ENTRYID property for a newly created object until after SaveChanges has been called, and some can do so only after SaveChanges has been called by using KEEP_OPEN_READONLY set in ulFlags.

Notes to Implementers

If you receive the KEEP_OPEN_READONLY flag, you have the option of leaving the object's access as read/write. However, a provider can never leave an object in a read-only state when the KEEP_OPEN_READWRITE flag is passed.

When a client saves multiple attachments to multiple messages, it calls the SaveChanges method for every attachment and every message. Often clients will set MAPI_DEFERRED_ERRORS for each of these calls except for the last one. You can return errors either with the last call or earlier calls. You can even ignore the flag.

If either KEEP_OPEN_READWRITE or KEEP_OPEN_READONLY is set together with MAPI_DEFERRED_ERRORS, you can ignore the error deferment request. If MAPI_DEFERRED_ERRORS is not set in ulFlags, one of the previously deferred errors can be returned for the SaveChanges call.

Whether a remote transport provider provides a functional implementation of this method is optional and depends on other design choices in your implementation. If you implement this method, do so according to the documentation here. Because folder objects and status objects are not transacted, at a minimum a remote transport provider's implementation of SaveChanges must return S_OK without actually doing any work.

Notes to Callers

If a client passes KEEP_OPEN_READONLY, calls the IMAPIProp::SetProps method, and then calls SaveChanges again, the same implementation might fail.

After receiving MAPI_E_NO_ACCESS from a call in which you set KEEP_OPEN_READWRITE, you will continue to have read/write permission to the object. You can call SaveChanges again, passing either the KEEP_OPEN_READONLY flag or no flags with KEEP_OPEN_SUFFIX.

Whether a provider supports the KEEP_OPEN_READWRITE flag depends on the provider's implementation.

To indicate that the only call to be made on the object after SaveChanges is IUnknown::Release, set no flags for the ulFlags parameter. An error from SaveChanges indicates that it could not make the pending changes permanent. Different providers handle the absence of flags on the SaveChanges call differently. Some providers treat this state the same as KEEP_OPEN_READONLY; other providers interpret it the same as KEEP_OPEN_READWRITE. Still other providers shut down the object when they do not receive flags on the SaveChanges call.

Some properties, typically computed properties, cannot be processed until you call SaveChanges and, in some cases, Release.

When you make bulk changes, such as saving attachments to multiple messages, defer error processing by setting the MAPI_DEFERRED_ERRORS flag in ulFlags. If you save multiple attachments to multiple messages, make one SaveChanges call to each attachment and one SaveChanges call to each message. Set the MAPI_DEFERRED_ERRORS flag for each attachment call and for all messages except for the last one.

If SaveChanges returns MAPI_E_OBJECT_CHANGED, check whether the original object has been modified. If so, warn the user, who can either request that the changes overwrite the previous changes or save the object elsewhere. If the original object has been deleted, warn the user to give them the opportunity to save the object in another location.

You cannot call SaveChanges with the FORCE_SAVE flag on an open object that has been deleted.

If SaveChanges returns an error, the object whose changes were to be saved remains open, regardless of the flags set in the ulFlags parameter.

Important note Important

The ulFlags NON_EMS_XP_SAVE and SPAMFILTER_ONSAVE might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following values:

#define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)

#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

For more information, see Saving MAPI Properties.

See also

Reference

IMAPIProp::SetProps
PidTagEntryId Canonical Property
IMAPIProp : IUnknown

Concepts

Saving MAPI Properties


IMAPIProp::SetProps

 Copy code hover
[image]

IMAPIProp::SetProps
See also Send feedback

Published: July 16, 2012

Updates one or more properties.

C++
HRESULT SetProps(
  ULONG cValues,
  LPSPropValue lpPropArray,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

cValues

[in] The count of property values pointed to by the lpPropArray parameter. The cValues parameter must not be 0.

lpPropArray

[in] A pointer to an array of SPropValue structures that contain property values to be updated.

lppProblems

[in, out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, NULL, indicating no need for error information. If lppProblems is a valid pointer on input, SetProps returns detailed information about errors in updating one or more properties.

Return value

S_OK

The properties were successfully updated.

The following values can be returned in the SPropProblemArray structure, but not as return values for SetProps:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_COMPUTED

The property cannot be updated because it is read-only, computed by the service provider that is responsible for the object.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.

MAPI_E_NOT_ENOUGH_MEMORY

The property cannot be updated because it is larger than the remote procedure call (RPC) buffer size.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the calling implementation.

Notes to Implementers

Ignore the PR_NULL (PidTagNull) property tag and all properties with a type of PT_ERROR. Do not make changes or report problems in the SPropProblemArray structure.

Return MAPI_E_INVALID_PARAMETER if a property of type PT_OBJECT is included in the property value array. Also return this error if a multiple-value property is included in the array and its cValues member is set to 0.

If the call succeeds overall but there are problems with setting some of the properties, return S_OK and put information about the problems in the appropriate entry of the SPropProblemArray structure that the lppProblems parameter points to.

Notes to Callers

Depending on the service provider, you might also be able to change the property type by passing a property tag that contains a different type than was previously used with a given property identifier.

If you include a property tag for a property that is unsupported by the object and the implementation of SetProps allows the creation of new properties, the property is added to the object. Any previous value stored with the property identifier that was used for the new property is discarded.

Note that the S_OK return value does not guarantee that all of the properties were successfully updated. Some providers cache SetProps calls until they receive a call that requires provider intervention, such as IMAPIProp::SaveChanges or IMAPIProp::GetProps. Therefore, it is possible to receive error values that relate to the SetProps call with the later calls.

If SetProps returns S_OK, check the SPropProblemArray structure pointed to by lppProblems for problems updating individual properties. If SetProps returns an error, do not check the property problem array. Instead, call the object's IMAPIProp::GetLastError method.

When updating large properties, SetProps can fail and return MAPI_E_NOT_ENOUGH_MEMORY. There is no maximum size for properties, and different objects can have different limits. If you deal with potentially large properties, be prepared to call the IMAPIProp::OpenProperty method with IID_IStream as the interface identifier if SetProps returns this error value.

Call the MAPIFreeBuffer function to free the SPropProblemArray structure.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
PropertyEditor.cpp | CPropertyEditor::WriteSPropValueToObject | MFCMAPI uses the IMAPIProp::SetProps method to write a property back to an object after the property has been edited.

See also

Reference

IMAPIProp::GetLastError
IMAPIProp::GetProps
IMAPIProp::OpenProperty
IMAPIProp::SaveChanges
MAPIFreeBuffer
SPropProblemArray
SPropValue
IMAPIProp : IUnknown


IMAPIProviderShutdown : IUnknown

 Copy code hover
[image]

IMAPIProviderShutdown : IUnknown
See also Send feedback

Published: July 16, 2012

Allows the MAPI subsystem to inform a MAPI provider of the fast shutdown of a MAPI client, so that the MAPI provider can respond to the shutdown.

Header file: | Mapidefs.h
Exposed by: | Provider objects: IXPProvider, IABProvider, or IMSProvider
Implemented by: | MAPI provider
Called by: | MAPI subsystem
Interface identifier: | IID_IMAPIProviderShutdown
Pointer type: | LPMAPIPROVIDERSHUTDOWN

Vtable Order

QueryFastShutdown | Queries the MAPI provider for fast shutdown support.
NotifyProcessShutdown | Indicates to the MAPI provider that a MAPI client is going to do a fast shutdown, so that the provider can take actions to prevent data loss.
DoFastShutdown | Indicates to the MAPI provider that the MAPI client is exiting immediately, so that the MAPI provider will persist changes to prevent data loss.

Remarks

Fast shutdown allows a MAPI client to exit its process within a short time, hopefully after the client and loaded MAPI providers have saved MAPI settings and data. The MAPI client always initiates a fast shutdown and should query the MAPI subsystem for fast shutdown support from the loaded MAPI providers. An administrator can set the Windows registry at the user level to specify the level of provider support that is necessary to allow fast shutdown of all MAPI clients. For more information about the registry settings, see Fast Shutdown User Options. However, for fast shutdown to successfully occur without data loss, MAPI providers should implement the IMAPIProviderShutdown interface.

A MAPI provider that needs to support client fast shutdown should return S_OK to the MAPI subsystem in the IMAPIProviderShutdown::QueryFastShutdown method. When the MAPI subsystem subsequently calls the IMAPIProviderShutdown::NotifyProcessShutdown and IMAPIProviderShutdown::DoFastShutdown methods, the MAPI provider should take necessary actions to save MAPI settings and data and prepare for the client's exit.

MAPI providers that do not need to support client fast shutdown should still implement the IMAPIProviderShutdown interface, and have the IMAPIProviderShutdown::QueryFastShutdown method return MAPI_E_NO_SUPPORT. For Outlook as a MAPI client, this causes Outlook to wait for all external references to be released before it exits.

Depending on the user's Windows registry setting for fast shutdown, not implementing the IMAPIProviderShutdown interface does not necessarily prevent a client fast shutdown.

For more information about the process of fast shutdown, see Fast Shutdown Overview. For information about how to carry out fast shutdown successfully, see Best Practices for Fast Shutdown.

See also

Concepts

MAPI Interfaces
Client Shutdown in MAPI


IMAPIProviderShutdown::DoFastShutdown

 Copy code hover
[image]

IMAPIProviderShutdown::DoFastShutdown
See also Send feedback

Published: July 16, 2012

Indicates to the MAPI provider that the MAPI client is exiting immediately, so that the MAPI provider will persist changes to prevent data loss.

C++
HRESULT DoFastShutdown ();

Return Value

S_OK

The MAPI provider is ready for the MAPI client to exit immediately.

See also

Reference

IMAPIProviderShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPIProviderShutdown::NotifyProcessShutdown

 Copy code hover
[image]

IMAPIProviderShutdown::NotifyProcessShutdown
See also Send feedback

Published: July 16, 2012

Indicates to the MAPI provider that a MAPI client is going to do a fast shutdown, so that the provider can take actions to prevent data loss.

C++
HRESULT NotifyProcessShutdown ();

Return Value

S_OK

The MAPI provider is taking actions to prevent data loss when the MAPI client shuts down.

See also

Reference

IMAPIProviderShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPIProviderShutdown::QueryFastShutdown

 Copy code hover
[image]

IMAPIProviderShutdown::QueryFastShutdown
See also Send feedback

Published: July 16, 2012

Queries the MAPI provider for fast shutdown support.

C++
HRESULT QueryFastShutdown ();

Return Value

S_OK

The MAPI provider supports the MAPI client to do fast shutdown.

MAPI_E_NO_SUPPORT

The MAPI provider does not support the MAPI client to do fast shutdown.

Remarks

MAPI providers that do not need to support client fast shutdown should still implement the IMAPIProviderShutdown interface, and have the IMAPIProviderShutdown::QueryFastShutdown method return MAPI_E_NO_SUPPORT. For Outlook as a MAPI client, this causes Outlook to wait for all external references to be released before it exits.

Depending on the user's Windows registry setting for fast shutdown, not implementing the IMAPIProviderShutdown interface does not necessarily prevent a client fast shutdown.

See also

Reference

IMAPIProviderShutdown : IUnknown

Concepts

Client Shutdown in MAPI


IMAPISecureMessage : IUnknown

 Copy code hover
[image]

IMAPISecureMessage : IUnknown
See also Send feedback

Published: July 16, 2012

Defines methods used to manage secure messages.

Header file: | Exchsec.h
Exposed by: | IMessage : IMAPIProp
Implemented by: | Microsoft Outlook 2010 and Microsoft Outlook 2013
Called by: | Client
Interface identifier: | IID_IMAPISECUREMESSAGE
Pointer type: | LPMAPISECUREMESSAGE

Vtable Order

Placeholder member. | Not supported or documented.
Placeholder member. | Not supported or documented.
Placeholder member. | Not supported or documented.
Placeholder member. | Not supported or documented.
IMAPISecureMessage::GetBaseMessage | Retrieves the underlying IMessage : IMAPIProp that this IMAPISecureMessage : IUnknown is encapsulating.
Placeholder member. | Not supported or documented.
Placeholder member. | Not supported or documented.
Placeholder member. | Not supported or documented.

See also

Reference

IMessage : IMAPIProp


IMAPISecureMessage::GetBaseMessage

 Copy code hover
[image]

IMAPISecureMessage::GetBaseMessage
See also Send feedback

Published: July 16, 2012

Retrieves the underlying IMessage : IMAPIProp that this IMAPISecureMessage : IUnknown is encapsulating.

C++
HRESULT GetBaseMessage(
  LPMMESSAGE FAR * ppmsg
);

Parameters

ppmsg

[out] A secure message object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPISecureMessage : IUnknown
IMessage : IMAPIProp


IMAPISession : IUnknown

 Copy code hover
[image]

IMAPISession : IUnknown
See also Send feedback

Published: July 16, 2012

Manages objects associated with a MAPI logon session.

Header file: | Mapix.h
Exposed by: | Session objects
Implemented by: | MAPI
Called by: | Client applications and MAPI
Interface identifier: | IID_IMAPISession
Pointer type: | LPMAPISESSION

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous session error.
GetMsgStoresTable | Provides access to the message store table that contains information about all the message stores in the session profile.
OpenMsgStore | Opens a message store and returns an IMsgStore pointer for further access.
OpenAddressBook | Opens the MAPI integrated address book, returning an IAddrBook pointer for further access.
OpenProfileSection | Opens a section of the current profile and returns an IProfSect pointer for further access.
GetStatusTable | Provides access to the status table, a table that contains information about all the MAPI resources in the session.
OpenEntry | Opens an object and returns an interface pointer for further access.
CompareEntryIDs | Compares two entry identifiers to determine whether they refer to the same object.
Advise | Registers to receive notification of specified events that affect the session.
Unadvise | Cancels the sending of notifications previously set up with a call to the Advise method.
MessageOptions | Not supported or documented.
QueryDefaultMessageOpt | Not supported or documented.
EnumAdrTypes | Deprecated. Returns the address types that can be handled by all of the transport providers in the session.
QueryIdentity | Returns the entry identifier of the object that provides the primary identity for the session.
Logoff | Ends a MAPI session.
SetDefaultStore | Establishes a message store as the default message store for the session.
AdminServices | Returns an IMsgServiceAdmin pointer for making changes to message services.
ShowForm | Displays a form.
PrepareForm | Creates a numeric token that the ShowForm method uses to access a message.

See also

Concepts

MAPI Interfaces


IMAPISession::AdminServices

 Copy code hover
[image]

IMAPISession::AdminServices
See also Send feedback

Published: July 16, 2012

Returns an IMsgServiceAdmin pointer for making changes to message services.

C++
HRESULT AdminServices(
  ULONG ulFlags,
  LPSERVICEADMIN FAR * lppServiceAdmin
);

Parameters

ulFlags

[in] Reserved; must be zero.

lppServiceAdmin

[out] A pointer to a pointer to a message service administration object.

Return value

S_OK

A pointer to a message service administration object was successfully returned.

Notes to Callers

The IMAPISession::AdminServices method creates a message service administration object, an object that supports the IMsgServiceAdmin interface and returns a pointer. By using this pointer, you can call IMsgServiceAdmin methods to change any of the message services in the session profile. Be aware that these changes do not take effect until the next session; the current session is unaffected.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIStoreFunctions.cpp | GetServerName | MFCMAPI uses the IMAPISession::AdminServices method to access the profile to read the server name.

See also

Reference

IMsgServiceAdmin : IUnknown
IProfAdmin::AdminServices
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::Advise

 Copy code hover
[image]

IMAPISession::Advise
See also Send feedback

Published: July 16, 2012

Registers to receive notification of specified events that affect the session.

C++
HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG_PTR lpulConnection
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the address book or message store object about which notifications should be generated, or NULL, which indicates that the client is registering to receive notifications about events that affect only the session.

ulEventMask

[in] A mask of values that indicate the types of notification events that the client is interested in and should be included in the registration. If lpEntryID is NULL, MAPI automatically registers the client for critical error events that affect only the session. When lpEntryID points to an entry identifier, the following values are valid for the ulEventMask parameter:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to a particular address book or message store provider and about session shut down.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new object.

fnevObjectCopied

Registers for notifications about an object being copied.

fnevObjectDeleted

Registers for notifications about an object being deleted.

fnevObjectModified

Registers for notifications about an object being modified.

fnevObjectMoved

Registers for notifications about an object being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

lpAdviseSink

[in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] A pointer to a nonzero number that represents the connection between the caller's advise sink object and the session.

Return value

S_OK

The registration was successful.

MAPI_E_INVALID_ENTRYID

The entry identifier pointed to by lpEntryID does not represent a valid entry identifier.

MAPI_E_NO_SUPPORT

The service provider responsible for the entry identifier pointed to by lpEntryID either does not support the type of events specified in the ulEventMask parameter or does not support notification.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier pointed to by lpEntryID cannot be handled by any of the service providers in the profile.

Remarks

The IMAPISession::Advise method establishes a connection between the caller's advise sink object, the session and, optionally, a service provider. This connection is used to send notifications to the advise sink when one or more events specified in the ulEventMask parameter occur to the object pointed to by lpEntryID. When lpEntryID is NULL, the target object is the session and notifications are sent only for critical errors and extended events.

When lpEntryID points to a valid entry identifier, MAPI calls the Advise method of the logon object that belongs to the responsible service provider. For example, if lpEntryID points to the entry identifier of a distribution list, MAPI calls the appropriate address book provider's IABLogon::Advise method.

To send a notification, either the service provider or MAPI calls the registered advise sink's IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.

Notes to Callers

On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you need assurance that notifications will occur only at a particular time on a particular thread, call the HrThisThreadAdviseSink function to generate the advise sink object that you pass to the Advise method.

To determine when a client has logged off, register for notifications in your service provider by calling Advise with lpEntryID set to NULL and cbEntryID set to 0. When the logoff occurs, you will receive an fnevExtended notification.

After a call to Advise has succeeded and before IMAPISession::Unadvise has been called to cancel the registration, release your advise sink object unless you have a specific long-term use for it.

For an overview of the notification process, see Event Notification in MAPI.

For more information about handling notifications, see Handling Notifications.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
BaseDialog.cpp | CBaseDialog::OnNotificationsOn | MFCMAPI uses the IMAPISession::Advise method to register for notifications against the session.

See also

Reference

IABLogon::Advise
HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPISession::Unadvise
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
Event Notification in MAPI


IMAPISession::CompareEntryIDs

 Copy code hover
[image]

IMAPISession::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers to determine whether they refer to the same object.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The byte count in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The byte count in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the result of the comparison. TRUE if the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to objects, possibly because these objects are currently unopened and unavailable.

Remarks

The IMAPISession::CompareEntryIDs method compares two entry identifiers that belong to a single service provider to determine whether they refer to the same object. MAPI extracts the MAPIUID portion from the entry identifiers to determine the service provider responsible for the objects and then calls its logon object's CompareEntryIDs method to perform the comparison.

Notes to Callers

The CompareEntryIDs method is useful because an object can have more than one valid entry identifier. This situation can occur, for example, after a new version of a service provider is installed.

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contain an invalid MAPIUID.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
BaseDialog.cpp | CbaseDialog::OnCompareEntryIDs | MFCMAPI uses the IMAPISession::CompareEntryIDs method to compare two entry IDs that a user enters.

See also

Reference

MAPIUID
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::EnumAdrTypes

 Copy code hover
[image]

IMAPISession::EnumAdrTypes
See also Send feedback

Published: July 16, 2012

Deprecated. Returns the address types that can be handled by all of the transport providers in the session.

C++
HRESULT EnumAdrTypes(
  ULONG ulFlags,
  ULONG FAR * lpcAdrTypes,
  LPSTR FAR * FAR * lpppszAdrTypes
);

Parameters

ulFlags

[in] A bitmask of flags that indicates the format for the returned address types. The following flag can be set:

MAPI_UNICODE

The address types are in Unicode format. If the MAPI_UNICODE flag is not set, the address types are in ANSI format.

lpcAdrTypes

[out] A pointer to a count of address types pointed to by the lpppszAdrTypes parameter.

lpppszAdrTypes

[out] A pointer to an array of pointers to address types.

Return value

S_OK

The address types were successfully retrieved.

Remarks

The IMAPISession::EnumAdrTypes method returns a list of the address types that can be handled by all of the active transport providers in the session. The address types for transport providers that are not currently loaded are not included in the list. Transport providers register to handle one or more address types when MAPI calls their IXPLogon::AddressTypes method.

Notes to Callers

Call MAPIFreeBuffer to release the string array pointed to by the lpppszAdrTypes parameter.

See also

Reference

IXPLogon::AddressTypes
MAPIFreeBuffer
IMAPISession : IUnknown


IMAPISession::GetLastError

 Copy code hover
[image]

IMAPISession::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous session error.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] A handle to the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to a MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if MAPI cannot supply appropriate information for a MAPIERROR structure.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and the session does not support Unicode.

Remarks

The IMAPISession::GetLastError method retrieves information about the last error that was returned by an IMAPISession method call. Clients can provide their users with detailed information about the error by including this information in a dialog box.

Notes to Callers

You can use the MAPIERROR structure, if MAPI supplies one, pointed to by the lppMAPIError parameter only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was, or it has nothing more to report about the error. In this situation, GetLastError returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPISession : IUnknown

Concepts

MAPI Extended Errors


IMAPISession::GetMsgStoresTable

 Copy code hover
[image]

IMAPISession::GetMsgStoresTable
See also Send feedback

Published: July 16, 2012

Provides access to the message store table that contains information about all the message stores in the session profile.

C++
HRESULT GetMsgStoresTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that determines the format for columns that are character strings. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] A pointer to a pointer to the message store table.

Return value

S_OK

The table was successfully returned.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and the session does not support Unicode.

Remarks

The IMAPISession::GetMsgStoresTable method retrieves a pointer to the message store table, a table maintained by MAPI that contains information about each open message store in the profile.

For a complete list of required and optional columns in the message store table, see Message Store Tables.

Notes to Callers

Because MAPI updates the message store table during the session whenever changes occur, call the Advise method of the message store table to register to be notified of these changes. Possible changes include the addition of new message stores, removal of existing stores, and changes to the default store.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the IMAPITable::QueryColumns and IMAPITable::QueryRows methods. This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnOpenMessageStoreTable | MFCMAPI uses the IMAPISession::GetMsgStoresTable method to obtain the message store table so that it can be rendered in the main dialog box of MFCMAPI.

See also

Reference

IMAPISession::OpenMsgStore
IMAPITable : IUnknown
IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::QuerySortOrder
IMAPITable::SetColumns
IMAPITable::SortTable
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
Message Store Tables


IMAPISession::GetStatusTable

 Copy code hover
[image]

IMAPISession::GetStatusTable
See also Send feedback

Published: July 16, 2012

Provides access to the status table, a table that contains information about all the MAPI resources in the session.

C++
HRESULT GetStatusTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that determines the format for columns that are character strings. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] A pointer to a pointer to the status table.

Return value

S_OK

The table was successfully returned.

Remarks

The IMAPISession::GetStatusTable method provides access to the status table that contains information about all of the MAPI resources in the session. There is one row in the table for information about the MAPI subsystem, one row for the MAPI spooler, one row for the integrated address book, and one row for each service provider in the profile.

For a complete list of required and optional columns in the status table, see Status Tables.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the IMAPITable::QueryColumns and IMAPITable::QueryRows methods. This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnStatusTable | MFCMAPI uses the IMAPISession::GetStatusTable method to obtain the status table to be rendered.

See also

Reference

IMAPITable : IUnknown
IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::QuerySortOrder
IMAPITable::SetColumns
IMAPITable::SortTable
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
Status Tables


IMAPISession::Logoff

 Copy code hover
[image]

IMAPISession::Logoff
See also Send feedback

Published: July 16, 2012

Ends a MAPI session.

C++
HRESULT Logoff(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG ulReserved
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows to be displayed. This parameter is ignored if the MAPI_LOGOFF_UI flag is not set.

ulFlags

[in] A bitmask of flags that control the logoff operation. The following flags can be set:

MAPI_LOGOFF_SHARED

If this session is shared, all clients that logged on by using the shared session should be notified of the logoff in progress. The clients should log off. Any client that is using the shared session can set this flag. MAPI_LOGOFF_SHARED is ignored if the current session is not shared.

MAPI_LOGOFF_UI

Logoff can display a dialog box during the operation, possibly prompting the user for confirmation.

ulReserved

[in] Reserved; must be zero.

Return value

S_OK

The logoff operation was successful.

Remarks

The IMAPISession::Logoff method ends a MAPI session. When Logoff returns, none of the methods except for IUnknown::Release can be called.

Notes to Callers

When Logoff returns, release the session object by calling its IUnknown::Release method.

For more information about ending a session, see Ending a MAPI Session.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIObjects.cpp | CMapiObjects::Logoff | MFCMAPI uses the IMAPISession::Logoff method to log off from the session before releasing it.
Note Note

Due to the fast shutdown behavior introduced in Microsoft Office Outlook 2007 Service Pack 2, Microsoft Outlook 2010, and Microsoft Outlook 2013, clients should never pass the MAPI_LOGOFF_SHARED parameter to IMAPISession::Logoff. Passing MAPI_LOGOFF_SHARED will cause all MAPI clients to begin shutdown and unexpected behavior will occur.

See also

Reference

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
Ending a MAPI Session


IMAPISession::OpenAddressBook

 Copy code hover
[image]

IMAPISession::OpenAddressBook
See also Send feedback

Published: July 16, 2012

Opens the MAPI integrated address book, returning an IAddrBook pointer for further access.

C++
HRESULT OpenAddressBook(
  ULONG_PTR ulUIParam,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPADRBOOK FAR * lppAdrBook
);

Parameters

ulUIParam

[in] A handle to the parent window of the common address dialog box and other related displays.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the address book. Passing null returns a pointer to the address book's standard interface, IAddrBook : IMAPIProp.

ulFlags

[in] A bitmask of flags that controls the opening of the address book. The following flag can be set:

AB_NO_DIALOG

Suppresses the display of dialog boxes. If the AB_NO_DIALOG flag is not set, the address book providers that contribute to the integrated address book can prompt the user for any necessary information.

lppAdrBook

[out] A pointer to a pointer to the address book.

Return value

S_OK

The address book was successfully opened.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the containers of one or more address book providers could not be opened. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISession::OpenAddressBook method opens the MAPI integrated address book, a collection of the top-level containers of all of the address book providers in the profile. The pointer that is returned in the lppAdrBook parameter provides further access to the contents of the address book. This allows the caller to perform tasks such as opening individual containers, finding messaging users, and displaying common address dialog boxes.

Notes to Callers

OpenAddressBook returns MAPI_W_ERRORS_RETURNED if it cannot load one or more of the address book providers in the profile. This value is a warning, not an error value; handle it as you would S_OK. OpenAddressBook always returns a valid pointer in the lppAdrBook parameter, regardless of how many of the address book providers failed to load. Therefore, you must always call the address book's IUnknown::Release method at some point before logging off.

When OpenAddressBook returns MAPI_W_ERRORS_RETURNED, call IMAPISession::GetLastError to obtain a MAPIERROR structure that contains information about the failing providers. A single MAPIERROR structure is returned that contains information supplied by all of the providers.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIObjects.cpp | CMapiObjects::GetAddrBook | MFCMAPI uses the IMAPISession::OpenAddressBook method to obtain the integrated address book.

See also

Reference

IAddrBook : IMAPIProp
IMAPISession::GetLastError
MAPIERROR
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::OpenEntry

 Copy code hover
[image]

IMAPISession::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens an object and returns an interface pointer for additional access.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object to open.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the opened object. Passing NULL returns the object's standard interface. For example, if the object to be opened is a message, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the object be opened by using the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the object should be opened with read/write permission; if the client has read-only permission, the object should be opened with read-only permission.

MAPI_CACHE_OK

Use all means, including offline address books, to perform name resolution.

MAPI_CACHE_ONLY

Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully available to the calling client. If the object is not available, making a subsequent object call can cause an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only permission, and clients should not work on the assumption that read/write permission is granted.

MAPI_NO_CACHE

Do not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

SHOW_SOFT_DELETES

Show items that are currently marked as soft deleted (that is, they are in the deleted item retention time phase).

lpulObjType

[out] A pointer to the type of the opened object.

lppUnk

[out] A pointer to a pointer to the opened object.

Return value

S_OK

The object was opened successfully.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or an attempt was made to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

There is not an object associated with the entry identifier passed in the lpEntryID parameter.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in the lpEntryID parameter is in an unrecognizable format. This value is typically returned if the service provider that contains the object is not open.

Remarks

The IMAPISession::OpenEntry method opens a message store or address book object, returning a pointer to an interface that can be used to access the object.

Notes to Callers

Important note Important

When opening folder entries on a public store, such as folders and messages, use IMsgStore::OpenEntry instead of IMAPISession::OpenEntry. This ensures that public folders function correctly when multiple Exchange accounts are defined in a profile.

Call IMAPISession::OpenEntry only when you do not know what kind of object that you are opening. If you know that you are opening a folder or a message, call IMsgStore::OpenEntry. If you know that you are opening an address book container, a messaging user, or a distribution list, call IAddrBook::OpenEntry. These more specific methods are faster than IMAPISession::OpenEntry.

MAPI opens all objects with read-only permission, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter. Setting one of these flags does not guarantee a particular type of access; the permissions that are granted depend on the service provider, the access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL (PidTagAccessLevel) property.

Calling IMAPISession::OpenEntry and setting lpEntryID to point to the entry identifier of a message store is the same as calling the IMAPISession::OpenMsgStore method with the MDB_NO_DIALOG flag set. The flag settings are also equivalent, except that to request read/write permission with OpenMsgStore, you must set the MDB_WRITE flag instead of MAPI_MODIFY.

Check the value returned in the lpulObjType parameter to determine whether the object type returned is what you expected. If the object type is not the type that you expected, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | CallOpenEntry | MFCMAPI uses the IMAPISession::OpenEntry method to open an object.

See also

Reference

IAddrBook::OpenEntry
IDistList : IMAPIContainer
IMailUser : IMAPIProp
IMAPIFolder : IMAPIContainer
IMAPISession::OpenMsgStore
IMessage : IMAPIProp
IMsgStore::OpenEntry
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::OpenMsgStore

 Copy code hover
[image]

IMAPISession::OpenMsgStore
See also Send feedback

Published: July 16, 2012

Opens a message store and returns an IMsgStore pointer for further access.

C++
HRESULT OpenMsgStore(
  ULONG_PTR ulUIParam,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPMDB FAR * lppMDB
);

Parameters

ulUIParam

[in] A handle to the parent window of the common address dialog box and other related displays.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the message store to be opened. The lpEntryID parameter must not be NULL.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the message store. Passing NULL causes the lppMDB parameter to return a pointer to the standard interface for a message store (IMsgStore).

ulFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the message store be opened with the maximum network permissions allowed for the user and the maximum client application permissions. For example, if the client has read/write permission, the message store should be opened with read/write permission; if the client has read-only permission, the message store should be opened with read-only permission.

MAPI_DEFERRED_ERRORS

Allows OpenMsgStore to return successfully, possibly before the message store is fully available to the calling client. If the message store is not available, making a subsequent object call can raise an error.

MDB_NO_DIALOG

Prevents the display of logon dialog boxes. If this flag is set, and OpenMsgStore has insufficient configuration information to open the message store without the user's help, it returns MAPI_E_LOGON_FAILED. If this flag is not set, the message store provider can prompt the user to correct a name or password or to perform other actions that are needed to establish a connection to the message store.

MDB_NO_MAIL

The message store should not be used for sending or receiving mail. When this flag is set, MAPI does not notify the MAPI spooler that this message store is being opened.

MDB_ONLINE

In Cached Exchange Mode, a client or service provider can call this method with MDB_ONLINE to override the connection to the local message store and open the store on the remote server. You cannot open an Exchange store in cached mode and in non-cached mode at the same time in the same MAPI session. If you have already opened the cached message store, you must either close the store before you open it with this flag, or open a new MAPI session where you can open the Exchange store on the remote server by using this flag.

MDB_TEMPORARY

Instructs MAPI that the message store is not permanent and should not be added to the message store table. This flag is used to log on to the message store so information can be retrieved programmatically from the profile section.

MDB_WRITE

Requests read/write permission to the message store.

lppMDB

[out] Pointer to a pointer of the message store.

Return value

S_OK

The message store was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a message store for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The message store indicated by lpEntryID does not exist.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To get the error information from the provider, call the IMAPISession::GetLastError method. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISession::OpenMsgStore method opens a particular message store.

Notes to Callers

The default permission level for message stores is read-only. If you set the MDB_WRITE flag, you still might not be granted read/write permission. The final level of access that MAPI assigns to the message store depends on your permission level, the message store itself, and the message store provider.

If you call OpenMsgStore to open a message store with read-only permission, the following will occur:

  • The store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property will not have its STORE_MODIFY_OK and STORE_CREATE_OK bits set.

  • Calls to open one of the message store's messages or folders by using IMAPISession::OpenEntry with the MAPI_MODIFY flag set will fail.

  • Calls to open one of the properties of the message store's messages or folders by using IMAPIProp::OpenProperty with the MAPI_MODIFY flag will fail.

  • Calls to any of the following methods will fail:

    IMAPIFolder::CreateMessage
    IMAPIFolder::DeleteMessages
    IMAPIFolder::CreateFolder
    IMAPIFolder::DeleteFolder
    IMAPIFolder::SetMessageStatus
    IMAPIProp::SetProps
    IMAPIProp::DeleteProps

  • Calls to the following methods will fail if the destination for the copied message is read-only, whether the destination is the same as the source message store or is another read-only store.

    IMAPIFolder::CopyMessages
    IMAPIFolder::CopyFolder
    IMAPIProp::CopyTo

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIStoreFunctions.cpp | CallOpenMsgStore | MFCMAPI uses the IMAPISession::OpenMsgStore method to open a message store.

See also

Reference

IMsgStore : IMAPIProp
IMAPISession::GetLastError
IMAPISession::OpenEntry
IMAPIProp::OpenProperty
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
Using Macros for Error Handling


IMAPISession::OpenProfileSection

 Copy code hover
[image]

IMAPISession::OpenProfileSection
See also Send feedback

Published: July 16, 2012

Opens a section of the current profile and returns an IProfSect pointer for further access.

C++
HRESULT OpenProfileSection(
  LPMAPIUID lpUID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPPROFSECT FAR * lppProfSect
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that identifies the profile section.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the profile section. Passing NULL causes the lppProfSect parameter to return a pointer to the profile section's standard interface, IProfSect.

ulFlags

[in] A bitmask of flags that controls access to the profile section. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully available to the calling client. If the profile section is not available, making a subsequent call to it can cause an error.

MAPI_FORCE_ACCESS

Allows access to a profile section that does not belong to the provider.

MAPI_MODIFY

Requests read/write permission. By default, profile sections are opened with read-only permission, and clients should not work on the assumption that read/write permission has been granted.

lppProfSect

[out] A pointer to a pointer to the profile section.

Return value

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a profile section for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IMAPISession::OpenProfileSection method opens a profile section or object that supports the IProfSect interface. Profile sections are used for reading information from and writing information to the session profile.

You cannot use OpenProfileSection to open profile sections that individual service providers own unless you specify MAPI_FORCE_ACCESS in the ulFlags parameter.

Notes to Callers

Multiple clients can open a profile section with read-only permission, but only one client can open a profile section with read/write permission. If another client has a profile section open that you attempt to open by calling OpenProfileSection with the MAPI_MODIFY flag set, the call will fail, returning MAPI_E_NO_ACCESS.

A read-only open operation fails if the section is open for writing.

You can create a profile section by calling OpenProfileSection with the MAPI_MODIFY flag and a nonexistent MAPIUID structure in the lpUID parameter. Be sure that you specify MAPI_MODIFY. If you set lpUID to point to a nonexistent MAPIUID and OpenProfileSection is set to use the default access mode of read-only, the call will fail with MAPI_E_NOT_FOUND.

See also

Reference

IMAPIProp : IUnknown
IProfSect : IMAPIProp
MAPIUID
IMAPISession : IUnknown


IMAPISession::PrepareForm

 Copy code hover
[image]

IMAPISession::PrepareForm
See also Send feedback

Published: July 16, 2012

Creates a numeric token that the IMAPISession::ShowForm method uses to access a message.

C++
HRESULT PrepareForm(
  LPCIID lpInterface,
  LPMESSAGE lpMessage,
  ULONG FAR * lpulMessageToken
);

Parameters

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the message. Passing null results in the standard interface, or IMessage, being used. The lpInterface parameter must be null or IID_IMessage.

lpMessage

[in] A pointer to the message to be displayed in the form.

lpulMessageToken

[out] A pointer to a message token, which is used by the IMAPISession::ShowForm method to access the message pointed to by lpMessage.

Return value

S_OK

The form preparation was successful.

Remarks

The IMAPISession::PrepareForm method creates a message token for the message pointed to by the lpMessage parameter and calls the message's IUnknown::AddRef method. This token is passed in the ulMessageToken parameter to IMAPISession::ShowForm.

Notes to Callers

If the call to PrepareForm succeeds, release the message pointed to by lpMessage by calling its IUnknown::Release method before you call ShowForm. Failure to release the message before you call ShowForm can cause memory leaks.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | OpenMessageModal | MFCMAPI uses the IMAPISession::PrepareForm method, along with IMAPISession::ShowForm, to display a message in a modal form.

See also

Reference

IMAPISession::ShowForm
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::QueryIdentity

 Copy code hover
[image]

IMAPISession::QueryIdentity
See also Send feedback

Published: July 16, 2012

Returns the entry identifier of the object that provides the primary identity for the session.

C++
HRESULT QueryIdentity(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpcbEntryID

[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier of the object that provides the primary identity.

Return value

S_OK

The primary identity was successfully returned.

MAPI_W_NO_SERVICE

The call succeeded, but there is no primary identity for the session. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISession::QueryIdentity method retrieves the primary identity for the current session and returns the value through the lppEntryID parameter. The primary identity is an object, typically a messaging user, that represents the user of a session. lppEntryID returns the primary identity for an IMailUser object, which is also stored as the PidTagEntryID property. You can use the value returned in lppEntryID to open an IMailUser object using IMAPISession::OpenEntry.

Although many service providers in multiple message services can provide the primary identity for a session, MAPI designates a single service provider. The service provider that supplies the primary identity sets the following items:

  • The STATUS_PRIMARY_IDENTITY flag in the PR_RESOURCE_FLAGS (PidTagResourceFlags) property.

  • The PR_IDENTITY_DISPLAY (PidTagIdentityDisplay) property.

  • The PR_IDENTITY_ENTRYID (PidTagIdentityEntryId) property.

  • The PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey) property.

If the service provider that supplies the primary identity belongs to a message service, the other service providers in the message service also set the PR_IDENTITY properties. These properties are published in the session's status table.

If possible, QueryIdentity returns the value for the PR_IDENTITY_ENTRYID property from the status row tagged with STATUS_PRIMARY_IDENTITY. If the PR_IDENTITY_ENTRYID property is missing from the primary identity row, QueryIdentity returns a one-off entry identifier built with other information from that row.

If the STATUS_PRIMARY_IDENTITY flag is missing from all of the PR_RESOURCE_FLAG columns in the status table, QueryIdentity returns the first entry identifier that it finds. When there is no appropriate entry identifier to return, QueryIdentity succeeds with the warning MAPI_W_NO_SERVICE and points lppEntryID to a hard-coded entry identifier.

Notes to Callers

You can call the IMsgServiceAdmin::SetPrimaryIdentity method to assign a message service the task of supplying the session's primary identity.

Another way to retrieve the primary identity is by searching the status table for the row with the PR_RESOURCE_FLAGS columns set to STATUS_PRIMARY_IDENTITY. For more information about this alternate way of retrieving identity information, see Status Table and Status Objects.

When you are finished using the entry identifier for the primary identity returned by QueryIdentity, free its memory by calling the MAPIFreeBuffer function.

For more information about identity in general, see MAPI Primary Identity.

For more information about retrieving MAPI session identity, see Retrieving Primary and Provider Identity.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnQueryIdentity | MFCMAPI uses the IMAPISession::QueryIdentity method to open the address book entry for the primary identity of the session.

See also

Reference

IMAPISession::OpenEntry
IMsgServiceAdmin::SetPrimaryIdentity
MAPIFreeBuffer
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample
MAPI Primary Identity
Retrieving Primary and Provider Identity
Using Macros for Error Handling
Status Table and Status Objects


IMAPISession::SetDefaultStore

 Copy code hover
[image]

IMAPISession::SetDefaultStore
See also Send feedback

Published: July 16, 2012

Establishes a message store as the default message store for the session.

C++
HRESULT SetDefaultStore(
  ULONG ulFlags,
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

ulFlags

[in] A bitmask of flags that controls the setting of the default message store. These flags are mutually exclusive; only one of the following flags can be set:

MAPI_DEFAULT_STORE

Establishes the message store as the session default. Updates the message store's status table row by setting the STATUS_DEFAULT_STORE flag in the PR_RESOURCE_FLAGS (PidTagResourceFlags) column.

MAPI_PRIMARY_STORE

Establishes the message store as the store to be used at logon. If the message store is not the default store, clients should make it the default. Updates the message store's status table row by setting the STATUS_PRIMARY_STORE flag in the PR_RESOURCE_FLAGS column.

MAPI_SECONDARY_STORE

Establishes the message store as the store to be used at logon if the primary message store is not available. If a client cannot open the primary store, it should open the secondary store and set it as the default. Updates the message store's status table row by setting the STATUS_SECONDARY_STORE flag in the PR_RESOURCE_FLAGS column.

MAPI_SIMPLE_STORE_PERMANENT

Sets the STATUS_SIMPLE_STORE flag in the message store's PR_RESOURCE_FLAGS property in its status table row, message store table row, and in the session profile.

MAPI_SIMPLE_STORE_TEMPORARY

Sets the STATUS_SIMPLE_STORE flag in the message store's PR_RESOURCE_FLAGS property in its status table row and message store table row. The profile is not modified.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the message store that is intended as the default. If a client passes NULL in lpEntryID, no message store is selected as the default.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The IMAPISession::SetDefaultStore method establishes a message store as one of the following:

  • The default message store for the session.

  • The primary message store for the session.

  • The secondary message store for the session.

To establish a message store as the default, the message store must have the following flags set in its PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property:

  • STORE_SUBMIT_OK

  • STORE_CREATE_OK

  • STORE_MODIFY_OK

Notes to Callers

You can determine the default message store for the session by retrieving the status table and searching for the setting of the STATUS_DEFAULT_STORE flag in the PR_RESOURCE_FLAGS column. The row that has this setting represents the message store that is designated as the session default.

When either the MAPI_DEFAULT_STORE or the MAPI_SIMPLE_STORE_PERMANENT flag is set, MAPI updates the profile, message store table, and status table.

Whenever a change is made to the message store default setting, the following notifications are generated:

  • An fnevTableModified event notification is issued for each affected row in both the message store and status table.

  • An internal notification is issued to the MAPI spooler. Operations already in progress are completed without change; new operations that involve the default message store, such as message downloading, are processed for the new default store.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnSetDefaultStore | MFCMAPI uses the IMAPISession::SetDefaultStore method to set the selected store as the default store.

See also

Reference

PidTagResourceFlags Canonical Property
PidTagStoreSupportMask Canonical Property
TABLE_NOTIFICATION
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::ShowForm

 Copy code hover
[image]

IMAPISession::ShowForm
See also Send feedback

Published: July 16, 2012

Displays a form.

C++
HRESULT ShowForm(
  ULONG_PTR ulUIParam,
  LPMDB lpMsgStore,
  LPMAPIFOLDER lpParentFolder,
  LPCIID lpInterface,
  ULONG ulMessageToken,
  LPMESSAGE lpMessageSent,
  ULONG ulFlags,
  ULONG ulMessageStatus,
  ULONG ulMessageFlags,
  ULONG ulAccess,
  LPSTR lpszMessageClass
);

Parameters

ulUIParam

[in] A handle to the parent window of the form.

lpMsgStore

[in] A pointer to the message store that contains the folder pointed to by the lpParentFolder parameter.

lpParentFolder

[in] A pointer to the folder in which the message associated with the ulMessageToken parameter was created.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the message that is displayed in the form. The lpInterface parameter must be NULL or IID_IMessage. Passing NULL results in the standard interface, IMessage, being used.

ulMessageToken

[in] The token that is associated with the message to be displayed in the form. The ulMessageToken parameter must be set to the contents of the lpulMessageToken parameter from the previous call to IMAPISession::PrepareForm.

lpMessageSent

[in] Reserved; must be NULL.

ulFlags

[in] A bitmask of flags that controls how and whether the message is saved. The following flags can be set:

MAPI_NEW_MESSAGE

The message has never been saved (that is, its IMAPIProp::SaveChanges method has never been called).

MAPI_POST_MESSAGE

The message should be saved to its parent folder. The message is not processed for sending but is posted to the folder instead. If this flag is not set, the message is copied to the Outbox and is processed for sending.

ulMessageStatus

[in] A bitmask of flags copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the message associated with the token in the ulMessageToken parameter. The flags provide information about the state of the message.

ulMessageFlags

[in] A bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message associated with the token in the ulMessageToken parameter. These flags provide further information about the state of the message.

ulAccess

[in] A flag that indicates the permission level for the message that is displayed in the form. This information is copied from the PR_ACCESS (PidTagAccess) property of the message associated with the token in the ulMessageToken parameter.

lpszMessageClass

[in] A pointer to the message class of the message being displayed in the form, copied from the PR_MESSAGE_CLASS (PidTagMessageClass) property of the message associated with the token in the ulMessageToken parameter.

Return value

S_OK

The form was successfully displayed.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IMAPISession::ShowForm method displays a message form that has been prepared by the IMAPISession::PrepareForm method.

Notes to Callers

You should have only a single reference to the message passed in the PrepareForm method's lpMessage parameter.

Be aware that form implementations can return error values other than the ones documented by MAPI. If you can use these error values to make a more accurate determination of the error condition, do so. Otherwise, handle these errors as you would handle MAPI_E_CALL_FAILED.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFormFunctions.cpp | OpenMessageModal | MFCMAPI uses the IMAPISession::ShowForm method, together with the PrepareForm method, to display a message in a modal form.

See also

Reference

IMAPIProp::SaveChanges
IMessage : IMAPIProp
IMAPISession::PrepareForm
IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPISession::Unadvise

 Copy code hover
[image]

IMAPISession::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels the sending of notifications previously set up with a call to the IMAPISession::Advise method.

C++
HRESULT Unadvise(
  ULONG_PTR ulConnection
);

Parameters

ulConnection

[in] A connection number associated with an active notification registration. The value of ulConnection must have been returned by a previous call to IMAPISession::Advise.

Return value

S_OK

The registration was successfully canceled.

Remarks

The IMAPISession::Unadvise method cancels a registration for notification. Unadvise releases its pointer to the caller's advise sink, which it received in the Advise call used for registration.

Generally, Unadvise calls the advise sink's IUnknown::Release method during the Unadvise call. However, if another thread is in the process of calling the advise sink's IMAPIAdviseSink::OnNotify method, the Release call is delayed until the OnNotify method returns.

See also

Reference

IMAPIAdviseSink::OnNotify
IMAPISession::Advise
IMAPISession : IUnknown


IMAPIStatus : IMAPIProp

 Copy code hover
[image]

IMAPIStatus : IMAPIProp
See also Send feedback

Published: July 16, 2012

Provides status information about the MAPI subsystem, the integrated address book, and the MAPI spooler. A service provider implements IMAPIStatus to supply information about its own status.

Header file: | Mapidefs.h
Exposed by: | Status objects
Implemented by: | Service providers and MAPI
Called by: | Client applications
Interface identifier: | IID_IMAPIStatus
Pointer type: | LPMAPISTATUS
Transaction model: | Nontransacted

Vtable Order

ValidateState | Confirms the external status information available for the MAPI resource or the service provider.
SettingsDialog | Displays a property sheet that enables the user to change a service provider's configuration.
ChangePassword | Modifies a service provider's password without displaying a user interface.
FlushQueues | Forces all messages waiting to be sent or received to be immediately uploaded or downloaded.
Required properties | Access
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write
PR_PROVIDER_DISPLAY (PidTagProviderDisplay) | Read/write
PR_PROVIDER_DLL_NAME (PidTagProviderDllName) | Read-only
PR_RESOURCE_FLAGS (PidTagResourceFlags) | Read-only
PR_RESOURCE_METHODS (PidTagResourceMethods) | Read-only
PR_RESOURCE_TYPE (PidTagResourceType) | Read-only
PR_STATUS_CODE (PidTagStatusCode) | Read-only

Remarks

The status objects that MAPI implements support the following methods:

Status object | Supported methods
MAPI subsystem | ValidateState only
MAPI address book | ValidateState only
MAPI spooler | ValidateState and FlushQueues

The status objects that MAPI implements are required to have a read-only version of the methods of the IMAPIProp interface and to support the ValidateState method. Transport providers should also support FlushQueues. All providers should support SettingsDialog; support for ChangePassword is optional.

Clients use status objects to perform configuration and to learn about the state of the session. They access a status object by calling the OpenStatusEntry method of a service provider logon object or the IMAPISession::GetStatusTable method to retrieve the status object.

See also

Concepts

MAPI Interfaces


IMAPIStatus::ChangePassword

 Copy code hover
[image]

IMAPIStatus::ChangePassword
See also Send feedback

Published: July 16, 2012

Modifies a service provider's password without displaying a user interface. This method is optionally supported in status objects that service providers implement.

C++
HRESULT ChangePassword(
  LPSTR lpOldPass,
  LPSTR lpNewPass,
  ULONG ulFlags
);

Parameters

lpOldPass

[in] A pointer to the old password.

lpNewPass

[in] A pointer to the new password.

ulFlags

[in] A bitmask of flags that controls the format of the passwords. The following flag can be set:

MAPI_UNICODE

The passwords are in Unicode format. If the MAPI_UNICODE flag is not set, the passwords are in ANSI format.

Return value

S_OK

The password modification was successful.

MAPI_E_NO_ACCESS

The old password pointed to by lpOldPass is invalid.

MAPI_E_NO_SUPPORT

The status object does not support this operation, as indicated by the absence of the STATUS_CHANGE_PASSWORD flag in the status object's PR_RESOURCE_METHODS (PidTagResourceMethods) property.

Remarks

Not all status objects support the IMAPIStatus::ChangePassword method. It is supported only by service providers that require clients to enter a password. None of the status objects that MAPI implements support the password change operation.

ChangePassword modifies a password programmatically, without user interaction.

Notes to Implementers

Remote transport providers implement ChangePassword as specified here. There are no special considerations.

See also

Reference

PidTagResourceMethods Canonical Property
IMAPIStatus : IMAPIProp


IMAPIStatus::FlushQueues

 Copy code hover
[image]

IMAPIStatus::FlushQueues
See also Send feedback

Published: July 16, 2012

Forces all messages waiting to be sent or received to be immediately uploaded or downloaded. The MAPI spooler status object and status objects that transport providers implement support this method.

C++
HRESULT FlushQueues(
  ULONG_PTR ulUIParam,
  ULONG cbTargetTransport,
  LPENTRYID lpTargetTransport,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

cbTargetTransport

[in] The byte count in the entry identifier pointed to by the lpTargetTransport parameter. The cbTargetTransport parameter is set only on calls to the MAPI spooler's status object. For calls to a transport provider, the cbTargetTransport parameter is set to 0.

lpTargetTransport

[in] A pointer to the entry identifier of the transport provider that is to flush its message queues. The lpTargetTransport parameter is set only on calls to the MAPI spooler's status object. For calls to a transport provider, the lpTargetTransport parameter is set to NULL.

ulFlags

[in] A bitmask of flags that controls the flush operation. The following flags can be set:

FLUSH_ASYNC_OK

The flush operation can occur asynchronously. This flag applies only to the MAPI spooler's status object.

FLUSH_DOWNLOAD

The incoming message queues should be flushed.

FLUSH_FORCE

The flush operation should occur regardless, in spite of the chance of a decrease in performance. This flag must be set when an asynchronous transport provider is targeted.

FLUSH_NO_UI

The status object should not display a progress indicator.

FLUSH_UPLOAD

The outgoing message queues should be flushed.

Return value

S_OK

The flush operation was successful.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation can be initiated.

MAPI_E_NO_SUPPORT

The status object does not support this operation, as indicated by the absence of the STATUS_FLUSH_QUEUES flag in the status object's PR_RESOURCE_METHODS (PidTagResourceMethods) property.

Remarks

The IMAPIStatus::FlushQueues method requests that the MAPI spooler or a transport provider immediately send all messages in the outgoing queue or receive all messages from the incoming queue. FlushQueues is implemented only by the MAPI spooler status object and by status objects that transport providers supply.

MAPI_E_BUSY should be returned for asynchronous requests so that clients can continue work.

By default, FlushQueues is a synchronous operation; control does not return to the caller until the flush has completed. Only the flush operation performed by the MAPI spooler can be asynchronous; clients request this behavior by setting the FLUSH_ASYNC_OK flag.

Notes to Implementers

A remote transport provider's implementation of FlushQueues sets bits in the PR_STATUS_CODE (PidTagStatusCode) property in the logon object's status row to control how queues are flushed. If a remote viewer passes in the FLUSH_UPLOAD flag, the FlushQueues method should set the STATUS_INBOUND_ENABLED and STATUS_INBOUND_ACTIVE bits. If a remote viewer passes in the FLUSH_DOWNLOAD flag, the FlushQueues method should set the STATUS_OUTBOUND_ENABLED and STATUS_OUTBOUND_ACTIVE bits. FlushQueues should then return S_OK. The MAPI spooler will then initiate the appropriate actions to upload and download messages.

Notes to Callers

A call to the MAPI spooler status object is a directive to transfer all messages either to or from the appropriate transport provider. When you call an individual transport provider's status object, only the messages for that provider are affected.

See also

Reference

PidTagResourceMethods Canonical Property
PidTagStatusCode Canonical Property
IMAPIStatus : IMAPIProp


IMAPIStatus::SettingsDialog

 Copy code hover
[image]

IMAPIStatus::SettingsDialog
See also Send feedback

Published: July 16, 2012

Displays a property sheet that enables the user to change a service provider's configuration This method is not supported in status objects that MAPI implements.

C++
HRESULT SettingsDialog(
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of the configuration property sheet.

ulFlags

[in] A bitmask of flags that controls the display of the property sheet. The following flag can be set:

UI_READONLY

Suggests that the provider should not enable users to change configuration properties. This flag is only a suggestion; it can be ignored.

Return value

S_OK

The configuration property sheet was displayed successfully.

MAPI_E_NO_SUPPORT

The status object does not support this method, as indicated by the absence of the STATUS_SETTINGS_DIALOG flag in the PR_RESOURCE_METHODS (PidTagResourceMethods) property.

Remarks

The IMAPIStatus::SettingsDialog method displays a configuration property sheet. All service providers should support the SettingsDialog method, but it is not required. Service providers can implement their own property sheets or use the implementation supplied in the support object's IMAPISupport::DoConfigPropsheet method. DoConfigPropsheet builds a read/write property sheet.

Notes to Implementers

If a remote transport provider has any settings, it should do the following:

  • Open the transport provider's profile section.

  • Get the transport provider's property settings from the profile.

  • Display the property settings in a dialog box.

  • If the dialog box allows editing of the property settings, check that the new settings are valid and store them back in the transport provider's profile section.

  • Return S_OK, or any error values returned during the preceding steps.

Notes to Callers

You can use the property sheet displayed through SettingsDialog to perform a variety of tasks, such as the following:

  • Specify a default message store.

  • Specify a transport order.

  • Specify a default address book container for browsing.

  • Specify a search order for resolving ambiguous names.

  • Specify a default personal address book.

Service providers can implement property sheets that are read/write, read-only, or a mixture of permissions, depending on the property. Service providers can implement different permissions on individual properties by setting property restrictions. The default mode for property sheets is read/write. You can request read-only property sheets by setting the UI_READONLY flag in your calls to SettingsDialog. Service providers that are able to implement read-only property sheets can do so. However, because some service providers cannot override the default mode, you must be prepared to handle property sheets of either type.

Because a user interface is always involved in this operation, only interactive clients should call SettingsDialog.

See also

Reference

IMAPISupport::DoConfigPropsheet
PidTagResourceMethods Canonical Property
IMAPIStatus : IMAPIProp


IMAPIStatus::ValidateState

 Copy code hover
[image]

IMAPIStatus::ValidateState
See also Send feedback

Published: July 16, 2012

Confirms the external status information available for the MAPI resource or the service provider. This method is supported in all status objects.

C++
HRESULT ValidateState(
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

ulFlags

[in] A bitmask of flags that controls the validation. The following flags can be set:

ABORT_XP_HEADER_OPERATION

The user canceled the operation, typically by clicking the Cancel button in the corresponding dialog box. The status object has two options:

  • Continue working on the operation.

  • Stop the operation and return MAPI_E_USER_CANCELED.

CONFIG_CHANGED

One or more of the status object's configuration properties changed. Clients can set this flag to allow the MAPI spooler to dynamically correct critical transport provider failures.

FORCE_XP_CONNECT

The status object should perform a connection. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the connection occurs without caching.

FORCE_XP_DISCONNECT

The status object should perform a disconnect operation. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the disconnection occurs without caching.

PROCESS_XP_HEADER_CACHE

Entries in the header cache table should be processed, all messages marked with the MSGSTATUS_REMOTE_DOWNLOAD flag should be downloaded, and all messages marked with the MSGSTATUS_REMOTE_DELETE flag should be deleted. Messages that have both MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE set should be moved.

REFRESH_XP_HEADER_CACHE

For a remote transport provider, a new list of message headers should be downloaded and all flags that mark message status should be cleared.

SUPPRESS_UI

Prevents the status object from displaying a user interface as part of the operation.

Return value

S_OK

The validation was successful.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation is initiated.

MAPI_E_NO_SUPPORT

The status object does not support the validation method, as indicated by the absence of the STATUS_VALIDATE_STATE flag in the PR_RESOURCE_METHODS (PidTagResourceMethods) property.

MAPI_E_USER_CANCEL

The user canceled the validation operation, typically by clicking the Cancel button in a dialog box. This value is returned only by remote transport providers.

Remarks

The IMAPIStatus::ValidateState method checks the state of a resource that is associated with a status object. ValidateState is the only method in the IMAPIStatus interface that is required for all status objects. The exact behavior of this method depends on the implementation. The following table describes the implementation of each of the different types of status objects.

Status object | ValidateState implementation
MAPI subsystem | Validates the state of all the resources that the currently active service providers and the subsystem itself own.
MAPI spooler | Performs a logon of all transport providers, regardless of whether they are already logged on.
MAPI address book | Checks the entries in its profile section.
Service provider | Implementation depends on the type of provider and the flags set in the ulFlags parameter.

Notes to Implementers

Remote client applications call the ValidateState method to start remote processing for various actions. This method exists primarily to set status bits to communicate with the MAPI spooler, instead of to actually do any work. Typically, the transport provider sets flags in its status row that indicate to the MAPI spooler what actions need to be initiated to complete the client's request. In this model of client-transport-spooler interaction, the actions requested by the client are asynchronous, in that ValidateState returns before the requested actions are complete. However, actions that do not necessarily involve the underlying messaging system, or that involve a transport-specific interface, can be synchronous. The client application passes in a bitmask of the following flags to specify which actions the remote transport provider should take.

ABORT_XP_HEADER_OPERATION

If possible, the remote transport provider should cancel any operations that involve downloading headers. To do this, the transport provider must set the following property values in the logon object's status row:

  • Clear the STATUS_INBOUND_ENABLED and STATUS_INBOUND_ACTIVE bits in the PR_STATUS_CODE (PidTagStatusCode) property to tell the MAPI spooler to halt the incoming flush process for this transport provider.

  • Set the STATUS_OFFLINE bit in the PR_STATUS_CODE property.

  • Set the PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) property to TRUE.

  • Set the PR_STATUS_STRING (PidTagStatusString) property to a string that indicates the transport provider's status to the user.

  • Return S_OK. However, if the operation in progress cannot be canceled, ValidateState should return MAPI_E_BUSY.

FORCE_XP_CONNECT

A remote transport provider should never establish a connection to a shared resource (for example, a modem or COM port) outside the context of the MAPI spooler-transport interaction involved in the IXPLogon::FlushQueues method. If ValidateState is called with this flag, your transport provider should do the following:

  • Set an internal status flag to indicate that the remote connection must be established when the IXPLogon::FlushQueues method is called.

  • Set the correct values in the status table to cause the MAPI spooler to initiate the queue flushing process.

  • When flushing of queues is complete, release the shared resource.

  • Clear the STATUS_OFFLINE bit in the PR_STATUS_CODE property.

  • Return S_OK.

FORCE_XP_DISCONNECT

The remote transport provider should release its connection to the messaging system resources. After doing this, it should set the STATUS_OFFLINE bit in the PR_STATUS_CODE property and return S_OK.

PROCESS_XP_HEADER_CACHE

The remote transport provider should process remote messages and upload any messages that have been deferred. To do this, the transport provider must set the following property values in the logon object's status row:

  • Set the PR_STATUS_STRING property to a string that indicates the transport provider's status to the user.

  • Set the STATUS_OUTBOUND_ENABLED and STATUS_OUTBOUND_ACTIVE bits in the PR_STATUS_CODE property.

  • Set the PR_REMOTE_VALIDATE_OK property in the transport provider's status row to FALSE.

  • If another operation is in progress (such as downloading headers) when ValidateState is called, ValidateState should return MAPI_E_BUSY.

  • Execute the code for processing the REFRESH_XP_HEADER_CACHE flag, as well, to satisfy requirements of the Microsoft Exchange client.

REFRESH_XP_HEADER_CACHE

The remote transport provider should retrieve any new message headers from the messaging system. To do this, the transport provider must do the following:

  • Set the PR_STATUS_STRING property to a string that indicates the transport provider's status to the user.

  • Set the STATUS_INBOUND_ENABLED and STATUS_INBOUND_ACTIVE bits in the PR_STATUS_CODE property.

  • Clear the STATUS_OFFLINE bit in the PR_STATUS_CODE property.

  • Set the STATUS_ONLINE bit in the PR_STATUS_CODE property.

  • Set the PR_REMOTE_VALIDATE_OK property in the transport provider's status row to FALSE.

SHOW_XP_SESSION_UI

If your transport provider has any pieces of user interface for processing the message headers (such as a dialog box that confirms the downloading of messages), that dialog box should be displayed. Otherwise, ValidateState can return MAPI_E_NO_SUPPORT.

If any flags other than these are passed in, ValidateState should return MAPI_E_UNKNOWN_FLAGS.

The client's call to the transport provider will often be to the IMAPIStatus::ValidateState method. During the processing of ValidateState, the transport provider should not perform any actions that allocate scarce system resources, such as a modem or COM port. This is because the MAPI spooler will sometimes need to flush queues on more than one transport provider. However, the client can call any transport provider's ValidateState method at any time. If your transport provider attempts to allocate a scarce resource during the processing of ValidateState, an error can result due to conflict with another transport provider that the MAPI spooler has instructed to flush its queues. If you allow all scarce resource allocations to occur under the direction of the MAPI spooler, you can avoid such conflicts. Your transport provider should support the PR_REMOTE_VALIDATE_OK property so client applications can detect when your transport provider is busy or waiting for the MAPI spooler to initiate an action.

Notes to Callers

Because this method can cause other potentially lengthy calls to be made, ValidateState can return MAPI_E_BUSY to inform you that this method is waiting for the completion of another operation. You should wait until the pending operation is complete before attempting another task.

You have the most control over your calls to transport provider status objects. You can pass one or more flags to ValidateState that affect the transport provider's operations. For example, the ABORT_XP_HEADER_OPERATION flag indicates that the user canceled the validation. Transport providers can decide to abort, returning MAPI_E_USER_CANCELED, or can continue.

You can set the CONFIG_CHANGED flag on a call to either the status object of a service provider or the MAPI spooler to indicate that a configuration option has been changed. You can use CONFIG_CHANGED to dynamically reconfigure a transport provider. When you set CONFIG_CHANGED on a call to a service provider's status object, the provider responds with a call to IMAPISupport::SpoolerNotify to alert the MAPI spooler of the change. When you set CONFIG_CHANGED on a call to the MAPI spooler's status object, the spooler calls IXPLogon::AddressTypes for each active transport provider. AddressTypes informs the MAPI spooler of a transport's supported address types. Some service providers also display a progress indicator if the validation is expected to take a long time. Displaying a progress indicator is helpful, but not required.

When the SUPPRESS_UI flag is set, none of the configuration property sheets or progress dialog boxes can be displayed.

See also

Reference

IMAPISupport::SpoolerNotify
IXPLogon::AddressTypes
IXPLogon::FlushQueues
PidTagRemoteValidateOk Canonical Property
PidTagResourceMethods Canonical Property
PidTagStatusCode Canonical Property
PidTagStatusString Canonical Property
IMAPIStatus : IMAPIProp


IMAPISupport : IUnknown

 Copy code hover
[image]

IMAPISupport : IUnknown
See also Send feedback

Published: July 16, 2012

Provides implementations for tasks that are typically performed by service providers and message service entry point functions. Service providers receive a pointer to their support object when MAPI calls their provider object's logon method. Message services receive their support object pointer in the call to their entry point function.

Header file: | Mapispi.h
Exposed by: | Support objects
Implemented by: | MAPI
Called by: | Service providers
Interface identifier: | IID_IMAPISup
Pointer type: | LPMAPISUP

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous support object error.
GetMemAllocRoutines | Retrieves the addresses of the MAPI memory allocation and deallocation functions (MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer).
Subscribe | Registers an advise sink to receive notifications through MAPI.
Unsubscribe | Cancels the responsibility for sending notifications that was previously established with a call to the Subscribe method.
Notify | Sends a notification of a specified event to an advise source that originally registered for the notification through the Subscribe method.
ModifyStatusRow | Modifies the status table by adding a new row or modifying an existing row.
OpenProfileSection | Opens a section of the current profile and returns an IProfSect pointer for further access
RegisterPreprocessor | Registers a transport provider's preprocessor function (a function that conforms to the PreprocessMessage prototype).
NewUID | Creates a new MAPIUID structure to be used as a unique identifier.
MakeInvalid | Marks an object as unusable.
SpoolerYield | Gives control of the CPU to the MAPI spooler so that it can perform any tasks it considers necessary.
SpoolerNotify | Notifies the MAPI spooler of a change in status or a request for service.
CreateOneOff | Creates an entry identifier for a one-off address.
SetProviderUID | Registers a MAPIUID structure that uniquely represents the service provider.
CompareEntryIDs | Compares two entry identifiers to determine whether they refer to the same object.
OpenTemplateID | Opens a recipient entry in a foreign address book provider.
OpenEntry | Opens an object and returns an interface pointer for further access.
GetOneOffTable | Returns a pointer to the MAPI one-off table (a list of templates that all address book providers support for creating new recipients).
Address | Displays the common address dialog box.
Details | Displays a dialog box that shows details about a particular address book entry.
NewEntry | Adds a new recipient directly to an address book container or to the recipient list of an outgoing message.
DoConfigPropsheet | Displays a configuration property sheet.
CopyMessages | Copies or moves messages from one folder to another folder.
CopyFolder | Copies or moves a folder from its current parent folder to another parent folder.
DoCopyTo | Copies or moves all properties of one object, except for specifically excluded properties, to another object.
DoCopyProps | Copies or moves one or more properties of an object to another object.
DoProgressDialog | Retrieves a progress object that displays a progress indicator.
ReadReceipt | Generates a read or nonread report for a message.
PrepareSubmit | Prepares a message for submission to the MAPI spooler.
ExpandRecips | Completes a message's recipient list, expanding particular distribution lists.
DoSentMail | Processes a sent message.
OpenAddressBook | Provides access to the address book.
CompleteMsg | Performs postprocessing on a message.
StoreLogoffTransports | Requests the orderly release of a message store.
StatusRecips | Generates delivery and nondelivery reports.
WrapStoreEntryID | Converts a message store's internal entry identifier to an entry identifier in the MAPI standard format.
ModifyProfile | Makes changes to a message store profile section permanent.
IStorageFromStream | Implements a storage object to access a stream.
GetSvcConfigSupportObj | Creates a message service support object.

Remarks

Address books, message stores, transport providers, and message services each have their own support objects. Service providers and message services call the methods in their support objects as part of their implementations of other interface methods. Each different support object has complete implementations of the methods that apply to its caller; the methods that are not applicable return MAPI_E_NO_SUPPORT. Address book provider support objects have implementations for the following methods:

Address | CompareEntryIDs | CreateOneOff
Details | DoConfigPropsheet | DoProgressDialog
GetLastError | GetMemAllocRoutines | GetOneOffTable
IStorageFromStream | GetSvcConfigSupportObj | MakeInvalid
ModifyStatusRow | NewEntry | NewUID
Notify | OpenAddressBook | OpenEntry
OpenProfileSection | OpenTemplateID | SetProviderUID
Subscribe | Unsubscribe | WrapStoreEntryID

Message store provider support objects have implementations for the following methods:

CompareEntryIDs | CompleteMsg | CopyFolder
CopyMessages | CreateOneOff | DoCopyProps
DoCopyTo | DoConfigPropsheet | DoProgressDialog
DoSentMail | ExpandRecips | GetLastError
GetMemAllocRoutines | GetSvcConfigSupportObj | MakeInvalid
IStorageFromStream | ModifyProfile | ModifyStatusRow
NewUID | Notify | OpenAddressBook
OpenEntry | OpenProfileSection | PrepareSubmit
ReadReceipt | SetProviderUID | SpoolerNotify
StoreLogoffTransports | Subscribe | Unsubscribe
WrapStoreEntryID

Transport provider support objects have implementations for the following methods:

DoConfigPropsheet | CompareEntryIDs | CreateOneOff
GetMemAllocRoutines | GetSvcConfigSupportObj | GetLastError
IStorageFromStream | MakeInvalid | ModifyStatusRow
OpenAddressBook | RegisterPreprocessor | NewUID
Notify | OpenProfileSection | OpenEntry
StatusRecips | SpoolerNotify | SpoolerYield
WrapStoreEntryID | Subscribe | Unsubscribe

Message service support objects have implementations for the following methods:

DoConfigPropsheet | GetLastError
GetMemAllocRoutines | GetSvcConfigSupportObj
MakeInvalid | NewUID
OpenProfileSection

See also

Concepts

MAPI Interfaces


IMAPISupport::Address

 Copy code hover
[image]

IMAPISupport::Address
See also Send feedback

Published: July 16, 2012

Displays the common address dialog box.

C++
HRESULT Address(
  ULONG_PTR FAR * lpulUIParam,
  LPADRPARM lpAdrParms,
  LPADRLIST FAR * lppAdrList
);

Parameters

lpulUIParam

[in, out] A pointer to the handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the DIALOG_SDI flag is set in the ADRPARM structure pointed to by the lpAdrParms parameter, the window handle of the modeless dialog box is returned.

lpAdrParms

[in, out] A pointer to an ADRPARM structure that controls the presentation and behavior of the address dialog box.

lppAdrList

[in, out] A pointer to a pointer to an address list. On input, this list is either the current list of recipients in a message or NULL, if no such list exists. On output, lppAdrList points to an updated list of message recipients.

Return value

S_OK

The address dialog box was successfully displayed.

Remarks

The IMAPISupport::Address method is implemented for address book provider support objects. Address book providers call Address to create or update a list of message recipients.

Each recipient is described in an ADRENTRY structure that is included in the ADRLIST structure pointed to by the lppAdrList parameter. The ADRENTRY structure contains an array of recipient property values, one of which is the recipient's type, or PR_RECIPIENT_TYPE (PidTagRecipientType) property. This ADRLIST structure can be passed to a client to use as the lpMods parameter in a call to IMessage::ModifyRecipients.

Each recipient in the ADRLIST structure can be either resolved, which indicates that one of its property values is its PR_ENTRYID (PidTagEntryId) property, or unresolved, which indicates that the PR_ENTRYID property is missing.

In addition to PR_ENTRYID, resolved recipients include the following properties:

  • PR_RECIPIENT_TYPE

  • PR_DISPLAY_NAME (PidTagDisplayName)

  • PR_ADDRTYPE (PidTagAddressType)

  • PR_DISPLAY_TYPE (PidTagDisplayType)

Unresolved recipients typically include only PR_DISPLAY_NAME and PR_RECIPIENT_TYPE.

Notes to Callers

The ADRLIST structure that the caller passes in might be a different size from the structure that MAPI returns. When you allocate memory for the ADRLIST structure, allocate the memory for each SPropValue structure separately.

Use the pointers to the MAPI memory allocation functions passed in to your ABProviderInit function to allocate memory. Allocate memory with the MAPIAllocateBuffer function for ADRLIST and each property value structure in the ADRENTRY structures in ADRLIST.

If Address must return a larger ADRLIST structure, or if you have passed NULL for lppAdrList, Address frees the original structure and allocates a new one. Address also allocates additional property value structures in the ADRLIST structure and frees old ones as appropriate. For more information about how memory is managed for ADRLIST structures, see Managing Memory for ADRLIST and SRowSet Structures.

Address returns immediately if the DIALOG_SDI flag was set in the ADRPARM structure in the lpAdrParms parameter.

See also

Reference

ABProviderInit
ADRENTRY
ADRLIST
ADRPARM
FreePadrlist
FreeProws
IMAPISupport::GetMemAllocRoutines
IMAPITable::QueryRows
IMessage::ModifyRecipients
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
PidTagAddressType Canonical Property
PidTagDisplayName Canonical Property
PidTagDisplayType Canonical Property
PidTagEntryId Canonical Property
PidTagRecipientType Canonical Property
SPropValue
SRowSet
IMAPISupport : IUnknown

Concepts

Managing Memory for ADRLIST and SRowSet Structures


IMAPISupport::CompareEntryIDs

 Copy code hover
[image]

IMAPISupport::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers to determine whether they refer to the same object.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The byte count in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The byte count in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the result of the comparison. TRUE if the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to valid objects, possibly because they are currently unopened and unavailable.

Remarks

The IMAPISupport::CompareEntryIDs method is implemented for address book and message store provider support objects. CompareEntryIDs compares two entry identifiers that belong to a single service provider to determine whether they refer to the same object. MAPI extracts the MAPIUID portion from the entry identifiers to determine the service provider responsible for the objects. MAPI then calls its logon object's CompareEntryIDs method to perform the comparison.

Notes to Callers

CompareEntryIDs is useful because an object can have more than one valid entry identifier. This situation can occur, for example, after a new version of a service provider is installed.

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contain an invalid MAPIUID structure.

See also

Reference

MAPIUID
IMAPISupport : IUnknown


IMAPISupport::CompleteMsg

 Copy code hover
[image]

IMAPISupport::CompleteMsg
See also Send feedback

Published: July 16, 2012

Performs postprocessing on a message.

C++
HRESULT CompleteMsg(
  ULONG ulFlags,
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

ulFlags

[in] Reserved; must be zero.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the message to process.

Return value

S_OK

The postprocessing was successful.

Remarks

The IMAPISupport::CompleteMsg method is implemented for message store provider support objects and is called only by message store providers that are tightly coupled with transport providers. Tightly coupled store providers call IMAPISupport::CompleteMsg to instruct the MAPI spooler to postprocess a message.

Notes to Callers

Call CompleteMsg only when you are tightly coupled with a transport provider, you can handle all of the message's recipients, and one of the following conditions exists:

  • The message was preprocessed.

  • The message requires postprocessing by the MAPI spooler.

See also

Reference

IMAPISupport : IUnknown


IMAPISupport::CopyFolder

 Copy code hover
[image]

IMAPISupport::CopyFolder
See also Send feedback

Published: July 16, 2012

Copies or moves a folder from its current parent folder to another parent folder.

C++
HRESULT CopyFolder(
  LPCIID lpSrcInterface,
  LPVOID lpSrcFolder,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  LPVOID lpDestFolder,
  LPSTR lpszNewFolderName,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpSrcInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the parent folder of the folder to be copied or moved.

lpSrcFolder

[in] A pointer to the parent folder of the folder to be copied or moved.

cbEntryID

[in] The byte count in the entry identifier pointed to by lpEntryID.

lpEntryID

[in] A pointer to the entry identifier of the folder to be copied or moved.

lpInterface

[in] Reserved; must be NULL.

lpDestFolder

[in] A pointer to the folder that is to receive the folder to be copied or moved.

lpszNewFolderName

[in] A pointer to the name of the copied or moved folder; otherwise, NULL, which indicates that the copied or moved folder should have the same name as the source folder (the folder pointed to by lpEntryID).

ulUIParam

[in] A handle of the window for the progress indicator dialog box and related windows. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

COPY_SUBFOLDERS

All of the folder's subfolders should be copied or moved. When COPY_SUBFOLDERS is not set for a copy operation, only the folder identified by lpEntryID is copied. With a move operation, the COPY_SUBFOLDERS behavior is the default regardless of whether the flag is set.

FOLDER_DIALOG

Requests the display of a progress indicator.

FOLDER_MOVE

The folder should be moved instead of copied. If FOLDER_MOVE is not set, the folder is copied.

MAPI_UNICODE

The name of the folder is in Unicode format. If the MAPI_UNICODE flag is not set, the name of the folder is in ANSI format.

Return value

S_OK

The folder has been successfully copied or moved.

MAPI_E_COLLISION

The name of the folder being moved or copied is the same as that of a subfolder in the destination folder. The message store provider requires that folder names be unique. The operation stops without completing.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISupport::CopyFolder method is implemented for message store provider support objects. Message store providers can call IMAPISupport::CopyFolder in their implementation of IMAPIFolder::CopyFolder to copy or move a single folder from one parent folder to another.

IMAPISupport::CopyFolder adds the copied or moved folder as a subfolder of the destination folder.

Notes to Callers

IMAPISupport::CopyFolder allows simultaneous renaming and moving of folders and the copying or moving of subfolders of the affected folder. To copy or move all subfolders nested in the copied or moved folder, pass the COPY_SUBFOLDERS flag in ulFlags.

Expect the following return values under the following conditions:

Condition | Return value
CopyFolder successfully copied or moved the folder and all its subfolders, if applicable. | S_OK
CopyFolder was unable to successfully copy or move all of the folders. | MAPI_W_PARTIAL_COMPLETION
CopyFolder was unable to complete. | Any error value

If CopyFolder returns an error value, do not proceed on the assumption that no work was done. One or more folders could have been copied or moved before CopyFolder experienced the failure.

See also

Reference

IMAPISupport : IUnknown


IMAPISupport::CopyMessages

 Copy code hover
[image]

IMAPISupport::CopyMessages
See also Send feedback

Published: July 16, 2012

Copies or moves messages from one folder to another folder.

C++
HRESULT CopyMessages(
  LPCIID lpSrcInterface,
  LPVOID lpSrcFolder,
  LPENTRYLIST lpMsgList,
  LPCIID lpDestInterface,
  LPVOID lpDestFolder,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpSrcInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the folder that contains the messages to be copied or moved.

lpSrcFolder

[in] A pointer to the folder that contains the messages to be copied or moved.

lpMsgList

[in] A pointer to an array of entry identifiers that identify the messages to be copied or moved.

lpDestInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the destination folder for the copied or moved messages.

lpDestFolder

[in] A pointer to the destination folder for the copied or moved messages. This folder must be open.

ulUIParam

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

lpProgress

[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls how the copy or move operation is accomplished. The following flags can be set:

MESSAGE_DIALOG

Requests the display of a progress indicator.

MESSAGE_MOVE

The messages should be moved, instead of copied. If MESSAGE_MOVE is not set, the messages are copied.

Return value

S_OK

The copy or move operation was successful.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IMAPISupport::CopyMessages method is implemented for message store provider support objects. Message store providers can call IMAPISupport::CopyMessages in their implementation of IMAPIFolder::CopyMessages to copy or move one or more messages from one folder to another. As part of the IMAPISupport::CopyMessages call, the message store provider can specify that MAPI should display a progress indicator.

See also

Reference

IMAPIFolder::CopyMessages
IMAPISupport : IUnknown


IMAPISupport::CreateOneOff

 Copy code hover
[image]

IMAPISupport::CreateOneOff
See also Send feedback

Published: July 16, 2012

Creates an entry identifier for a one-off address.

C++
HRESULT CreateOneOff(
  LPSTR lpszName,
  LPSTR lpszAdrType,
  LPSTR lpszAddress,
  ULONG ulFlags,
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Parameters

lpszName

[in] A pointer to the display name of the recipient the PR_DISPLAY_NAME (PidTagDisplayName) property. The lpszName parameter can be NULL.

lpszAdrType

[in] A pointer to the address type (such as FAX, SMTP, or X500) of the recipient. The lpszAdrType parameter cannot be NULL.

lpszAddress

[in] A pointer to the messaging address of the recipient. The lpszAddress parameter cannot be NULL.

ulFlags

[in] A bitmask of flags that affects the one-off recipient. The following flags can be set:

MAPI_SEND_NO_RICH_INFO

The recipient cannot handle formatted message content. If MAPI_SEND_NO_RICH_INFO is set, MAPI sets the recipient's PR_SEND_RICH_INFO (PidTagSendRichInfo) property to FALSE. If MAPI_SEND_NO_RICH_INFO is not set, MAPI sets this property to TRUE unless the recipient's messaging address pointed to by lpszAddress is interpreted to be an Internet address. In this case, MAPI sets PR_SEND_RICH_INFO to FALSE.

MAPI_UNICODE

The display name, address type, and address are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

lpcbEntryID

[out] A pointer to the count of bytes in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier for the one-off recipient.

Return value

S_OK

The one-off entry identifier was successfully created.

Remarks

The IMAPISupport::CreateOneOff method is implemented for all service provider support objects. Service providers call CreateOneOff to create an entry identifier for a one-off recipient (a recipient that does not belong to any of the containers from any of the currently loaded address book providers).

Notes to Callers

When you are finished using the entry identifier returned by CreateOneOff, free the memory allocated for the entry identifier by using the MAPIFreeBuffer function.

Notes to Transport Providers

Support the Transport Neutral Encapsulation Format (TNEF) and use the value of the PR_SEND_RICH_INFO property to determine whether to use TNEF when you transport a message. Not supporting TNEF or not sending a message in this format when it is requested can be a problem for form-based clients or clients that require custom MAPI properties. This is because TNEF is typically used to send custom properties for custom message classes.

See also

Reference

MAPIFreeBuffer
PidTagDisplayName Canonical Property
PidTagSendRichInfo Canonical Property
IMAPISupport : IUnknown


IMAPISupport::Details

 Copy code hover
[image]

IMAPISupport::Details
See also Send feedback

Published: July 16, 2012

Displays a dialog box that shows details about a particular address book entry.

C++
HRESULT Details(
  ULONG_PTR FAR * lpulUIParam,
  LPFNDISMISS lpfnDismiss,
  LPVOID lpvDismissContext,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPFNBUTTON lpfButtonCallback,
  LPVOID lpvButtonContext,
  LPSTR lpszButtonText,
  ULONG ulFlags
);

Parameters

lpulUIParam

[out] A pointer to the handle to the parent window of the returned dialog box.

lpfnDismiss

[in] A pointer to a function based on the DISMISSMODELESS prototype, or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client that is calling IMAPISupport::Details that the dialog box is no longer active.

lpvDismissContext

[in] A pointer to context information to pass to the DISMISSMODELESS function pointed to by the lpfnDismiss parameter. This parameter applies only to the modeless version of the dialog box, by including the DIALOG_SDI flag in the ulFlags parameter.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for which details are displayed.

lpfButtonCallback

[in] A pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] A pointer to data used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] A pointer to a string that contains text to be applied to the added button if that button is extensible. The lpszButtonText parameter should be NULL if an extensible button is not needed.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flag can be set:

DIALOG_MODAL

Display the modal version of the common address dialog box. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Display the modeless version of the common address dialog box. This flag is mutually exclusive with DIALOG_MODAL.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Return value

S_OK

The details dialog box was successfully displayed for the address book entry.

Remarks

The IMAPISupport::Details method is implemented for address book provider support objects. Address book providers call Details to display a dialog box that gives details on a particular entry in the address book. The lpfButtonCallback, lpvButtonContext, and lpszButtonText parameters can be used to add a client-defined button to the dialog box. When the button is clicked, MAPI calls the callback function pointed to by lpfButtonCallback, passing both the entry identifier of the button and the data in lpvButtonContext. If an extensible button is not needed, lpszButtonText should be NULL.

See also

Reference

ADRPARM
IMAPISupport::Address
LPFNBUTTON
IMAPISupport : IUnknown


IMAPISupport::DoConfigPropsheet

 Copy code hover
[image]

IMAPISupport::DoConfigPropsheet
See also Send feedback

Published: July 16, 2012

Displays a configuration property sheet.

C++
HRESULT DoConfigPropsheet(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPSTR lpszTitle,
  LPMAPITABLE lpDisplayTable,
  LPMAPIPROP lpConfigData,
  ULONG ulTopPage
);

Parameters

ulUIParam

[in] A handle to the parent window of the property sheet.

ulFlags

[in] Reserved; must be zero.

lpszTitle

[in] A pointer to the title of the property sheet.

lpDisplayTable

[in] A pointer to the display table that describes the controls to appear on the property sheet.

lpConfigData

[in] A pointer to the IMAPIProp implementation to be used for accessing the configuration properties to be displayed on the property sheet.

ulTopPage

[in] A zero-based index to the default top page of the property sheet.

Return value

S_OK

The configuration property sheet was displayed.

Remarks

The IMAPISupport::DoConfigPropsheet method is implemented for all support objects. DoConfigPropSheet provides a standard user interface for displaying the properties of service providers and message services. You should use this standard dialog box for all configuration property displays so that users benefit from a consistent Windows interface.

Service providers call DoConfigPropSheet as part of their implementation of the IMAPIStatus::SettingsDialog method or from a button used to display details on properties. Message services call DoConfigPropSheet from their message service entry point function.

Notes to Callers

You can create the display table pointed to by the lpDisplayTable parameter by calling the BuildDisplayTable function or with custom code.

See also

Reference

BuildDisplayTable
CreateIProp
IABProvider::Logon
IMAPIProp : IUnknown
IMAPIStatus::SettingsDialog
IMsgServiceAdmin : IUnknown
IMSProvider::Logon
IXPProvider::TransportLogon
IMAPISupport : IUnknown


IMAPISupport::DoCopyProps

 Copy code hover
[image]

IMAPISupport::DoCopyProps
See also Send feedback

Published: July 16, 2012

Copies or moves one or more properties of an object to another object.

C++
HRESULT DoCopyProps(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpSrcInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the object with the properties to be copied or moved.

lpSrcObj

[in] A pointer to the object that contains the properties to be copied or moved.

lpIncludeProps

[in] A pointer to an SPropTagArray structure that contains a counted array of property tags that indicate the properties to copy or move. The lpIncludeProps parameter cannot be NULL.

ulUIParam

[in] A handle to the parent window of the progress indicator.

lpProgress

[in] A pointer to an implementation of a progress indicator. If NULL is passed in the lpProgress parameter, the progress indicator is displayed by using the MAPI implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpDestInterface

[in] A pointer to the interface identifier that represents the interface to be used to access the object to receive the properties that are copied or moved.

lpDestObj

[in] A pointer to the object to receive the copied or moved properties.

ulFlags

[in] A bitmask of flags that controls how the copy or move operation is performed. The following flags can be set:

MAPI_DIALOG

Displays a progress indicator.

MAPI_MOVE

DoCopyProps should perform a move operation instead of a copy operation. When this flag is not set, DoCopyProps performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, DoCopyProps overwrites existing properties.

lppProblems

[in, out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, NULL, which indicates no need for error information. If lppProblems is a valid pointer on input, DoCopyProps returns detailed information about errors in copying one or more properties.

Return value

S_OK

Properties were successfully copied or moved.

MAPI_E_COLLISION

A property to be copied or moved already exists in the destination object and the MAPI_NOREPLACE flag is set.

MAPI_E_FOLDER_CYCLE

The source object directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpSrcInterface parameter is not supported by the source object, or the interface identified by the lpDestInterface parameter is not supported by the destination object.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

The following values can be returned in the SPropProblemArray structure, but not as return values for DoCopyProps. These errors apply to a single property.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and DoCopyProps does not support Unicode, or MAPI_UNICODE was not set and DoCopyProps supports only Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type that the caller expects.

Remarks

The IMAPISupport::DoCopyProps method is implemented for message store provider support objects. Message store providers can call DoCopyProps to implement the IMAPIProp::CopyProps method for their folders and messages. DoCopyProps copies or moves the properties that are identified in the property tag array pointed to by lpIncludeProps and that are present in the object pointed to by lpSrcObj.

Notes to Callers

When you copy properties between objects of the same type, such as two messages, the lpSrcInterface and lpDestInterface parameters must contain the same interface identifier, and the lpSrcObj and lpDestObj parameters must point to objects of the same type. If lpDestInterface is set to NULL, DoCopyProps returns MAPI_E_INVALID_PARAMETER. If you set lpDestInterface to an acceptable interface identifier, but set lpDestObj to an invalid pointer, the results are unpredictable. Most likely your provider will fail.

Set the MAPI_NOREPLACE flag if you do not want any of the properties in the destination object to be overwritten. Properties in the destination object that exist in the source object and are not overwritten are not deleted or modified.

To copy a message's recipient list, include the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property in the property tag array pointed to by the lpIncludeProps parameter. To copy the message's attachments, include the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property.

To copy a folder or address book container's hierarchy or contents table, include PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) or PR_CONTAINER_CONTENTS (PidTagContainerContents) in the property tag array. To include a folder's associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) property in the array.

If subfolders are copied or moved, their contents are copied or moved in their entirety, regardless of the use of properties indicated by the SPropTagArray structure.

DoCopyProps reports global errors that occur with the operation as a whole, and individual errors that occur with one or more of the properties. These individual errors are put in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL, rather than a valid pointer, for the property problem array structure parameter.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When DoCopyProps returns S_OK, check for possible errors with individual properties in the structure. When DoCopyProps returns an error, no information is returned in the SPropProblemArray structure. Instead, call the IMAPISupport::GetLastError method to retrieve detailed error information.

If DoCopyProps returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

See also

Reference

IMAPIProp::CopyProps
IMAPISupport::CopyMessages
IMAPISupport::DoCopyTo
IMAPISupport::GetLastError
PidTagContainerContents Canonical Property
PidTagContainerHierarchy Canonical Property
PidTagFolderAssociatedContents Canonical Property
PidTagMessageAttachments Canonical Property
PidTagMessageRecipients Canonical Property
SPropProblemArray
SPropTagArray
IMAPISupport : IUnknown


IMAPISupport::DoCopyTo

 Copy code hover
[image]

IMAPISupport::DoCopyTo
See also Send feedback

Published: July 16, 2012

Copies or moves all properties of one object, except for specifically excluded properties, to another object.

C++
HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpSrcInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the object that has the properties to be copied or moved.

lpSrcObj

[in] A pointer to the object that has the properties to be copied or moved.

ciidExclude

[in] The count of interfaces to exclude when you copy or move properties.

rgiidExclude

[in] An array of interface identifiers that indicates interfaces that should not be used when you copy or move supplemental information to the destination object.

lpExcludeProps

[in] A pointer to a property tag array that identifies the property tags that should be excluded from the copy or move operation. Passing NULL in the lpExcludeProps parameter indicates that all of the object's properties should be copied or moved. DoCopyTo returns MAPI_E_INVALID_PARAMETER when the cValues member of the SPropTagArray structure pointed to by lpExcludeProps is set to 0.

ulUIParam

[in] A handle to the parent window of the progress indicator.

lpProgress

[in] A pointer to a progress indicator implementation. If NULL is passed in the lpProgress parameter, MAPI provides the progress implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

lpDestInterface

[in] A pointer to the interface identifier that represents the interface to be used to access the object to receive the copied or moved properties.

lpDestObj

[in] A pointer to the object to receive the copied or moved properties.

ulFlags

[in] A bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DIALOG

Displays a progress indicator.

MAPI_MOVE

DoCopyTo should perform a move operation instead of a copy operation. When this flag is not set, DoCopyTo performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, DoCopyTo overwrites existing properties.

lppProblems

[out] On input, a pointer to a pointer to an SPropProblemArray structure; otherwise, NULL, which indicates no need for error information. If lppProblems is a valid pointer on input, DoCopyTo returns detailed information about errors in copying one or more properties.

Return value

S_OK

The properties have been successfully copied or moved.

MAPI_E_COLLISION

A property to be copied or moved already exists in the destination object and the MAPI_NOREPLACE flag is set.

MAPI_E_FOLDER_CYCLE

The source object directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

The interface identified by the lpSrcInterface parameter is not supported by the object pointed to by lpSrcObj, or the interface identified by the lpDestInterface parameter is not supported by the object pointed to by lpDestObj.

MAPI_E_NO_ACCESS

An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.

MAPI_E_INVALID_PARAMETER

The lpSrcInterface parameter is NULL.

The following values can be returned in the SPropProblemArray structure, but not as return values for DoCopyTo. These errors apply to a single property.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and DoCopyTo does not support Unicode, or MAPI_UNICODE was not set and DoCopyTo supports only Unicode.

MAPI_E_COMPUTED

The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPISupport::DoCopyTo method is implemented for message store provider support objects. Message store providers can call DoCopyTo to implement the IMAPIProp::CopyTo method for their folders and messages.

By default, DoCopyTo copies or moves all of the properties of one object to another object. Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety.

If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new properties, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.

Notes to Callers

To exclude properties from the copy or move operation, include their property tags in the lpExcludeProps parameter. If you pass the results of using the PROP_TAG macro to build a property tag from a specific identifier in the property tag array, all properties with that identifier will be excluded. For example, the following entry in the property tag array causes all properties with an identifier of 0x8002 to be excluded, regardless of type:

PROP_TAG(PT_LONG, 0x8002)

To avoid copying a message's delivery time when you copy the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) in the property tag exclude array. To exclude a message's recipient list, add the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property to the exclude array. To exclude a message's attachments, add the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property to the array.

Similarly, to prevent the copying or moving of a folder or address book container's hierarchy or contents table, include PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) or PR_CONTAINER_CONTENTS (PidTagContainerContents) in the property tag exclude array.

Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.

The interface identifier that lpSrcInterface points to is usually the same as the interface identifier that lpDestInterface points to.

If you pass an acceptable interface identifier in lpDestInterface but an invalid pointer in lpDestObj, the results are unpredictable. Most likely this will cause your provider to fail.

Conversely, if you are aware of supplemental information that should not be copied or moved, add the interface identifiers for the interfaces to be excluded in the array passed in the rgiidExclude parameter. For example, if you are copying messages, but not any of their message attachments, pass IID_IMessage in the rgiidExclude array. DoCopyTo ignores any interfaces listed in rgiidExclude that it does not recognize.

When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding the IMAPIContainer interface causes folders or address book containers to be excluded, depending on the type of provider. Do not exclude IMAPIProp or IUnknown because so many interfaces derive from them.

DoCopyTo reports global errors that apply to the operation as a whole, and individual errors that apply to individual properties. These individual errors are put in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL, rather than a valid pointer, for the property problem array structure parameter.

If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When DoCopyTo returns S_OK, check for possible errors with individual properties in the structure. When DoCopyTo returns an error, no information is returned in the SPropProblemArray structure. Instead, call the IMAPISupport::GetLastError method to retrieve detailed error information.

If DoCopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.

If a global error occurs on the DoCopyTo call, do not use or free the SPropProblemArray structure. Providers should ignore the ulIndex member in SPropProblemArray structures returned by DoCopyTo.

See also

Reference

IMAPIProp::CopyTo
IMAPISupport::CopyFolder
IMAPISupport::CopyMessages
IMAPISupport::GetLastError
PidTagContainerContents Canonical Property
PidTagContainerHierarchy Canonical Property
PidTagMessageAttachments Canonical Property
PidTagMessageDeliveryTime Canonical Property
PidTagMessageRecipients Canonical Property
SPropProblemArray
SPropTagArray
IMAPISupport : IUnknown


IMAPISupport::DoProgressDialog

 Copy code hover
[image]

IMAPISupport::DoProgressDialog
See also Send feedback

Published: July 16, 2012

Retrieves a progress object that displays a progress indicator.

C++
HRESULT DoProgressDialog(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPMAPIPROGRESS FAR * lppProgress
);

Parameters

ulUIParam

[in] A handle to the parent window of the progress indicator.

ulFlags

[in] A bitmask of flags that controls how the progress object should calculate progress. The following flag can be set:

MAPI_TOP_LEVEL

Progress is calculated for a top-level item, such as a parent folder. The progress object should use the values in the IMAPIProgress::Progress method's ulCount and ulTotal parameters — which indicate the current item and the total items in the operation, respectively — to increment the progress indicator for the operation.

lppProgress

[out] A pointer to a pointer to the progress object.

Return value

S_OK

The progress object was successfully retrieved.

Remarks

The IMAPISupport::DoProgressDialog method is implemented for address book and message store provider support objects. These providers call DoProgressDialog to access the MAPI implementation of the IMAPIProgress interface, which calculates the progress information and displays a standard dialog box.

For information about how to use a progress object and the IMAPIProgress interface, see How to: Display a Progress Indicator.

See also

Reference

IMAPIProgress : IUnknown
IMAPIProgress::Progress
IMAPISupport : IUnknown

Concepts

How to: Display a Progress Indicator


IMAPISupport::DoSentMail

 Copy code hover
[image]

IMAPISupport::DoSentMail
See also Send feedback

Published: July 16, 2012

Processes a sent message.

C++
HRESULT DoSentMail(
  ULONG ulFlags,
  LPMESSAGE lpMessage
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpMessage

[in] A pointer to the open message for which a message should be generated in the folder designated to hold sent items.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The IMAPISupport::DoSentMail method is implemented for message store provider support objects. Message store providers call DoSentMail from their implementation of the IMsgStore::FinishedMsg method, which is called by the MAPI spooler when it has finished processing a message. FinishedMsg unlocks the message, ensures that the message's reference count is 1, and calls DoSentMail.

DoSentMail performs the following tasks:

  • Checks the message for the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property to determine whether the message should be deleted after sending.

  • Determines the location of the Sent Items folder.

  • Initiates message hook processing for any hooks set on the Sent Items folder.

  • Moves the message to the Sent Items folder, Deleted Items folder, or to another folder.

  • Releases the message.

See also

Reference

IMsgStore::FinishedMsg
PidTagDeleteAfterSubmit Canonical Property
IMAPISupport : IUnknown


IMAPISupport::ExpandRecips

 Copy code hover
[image]

IMAPISupport::ExpandRecips
See also Send feedback

Published: July 16, 2012

Completes a message's recipient list, expanding particular distribution lists.

C++
HRESULT ExpandRecips(
  LPMESSAGE lpMessage,
  ULONG FAR * lpulFlags
);

Parameters

lpMessage

[in] A pointer to the message that has the recipient list to be processed.

lpulFlags

[out] A pointer to a bitmask of flags that controls the type of processing that occurs. The following flags can be set:

NEEDS_PREPROCESSING

The message needs to be preprocessed before it is sent.

NEEDS_SPOOLER

The MAPI spooler (rather than the transport provider to which the caller is tightly coupled) must send the message.

Return value

S_OK

The message's recipient list was successfully processed.

Remarks

The IMAPISupport::ExpandRecips method is implemented for message store provider support objects. Message store providers call ExpandRecips to prompt MAPI to perform the following tasks:

  • Expand certain personal distribution lists to their component recipients.

  • Replace all display names that have been changed with the original names.

  • Mark any duplicate entries.

  • Resolve all one-off addresses.

  • Check whether the message needs preprocessing and, if it does, set the flag pointed to by lpulFlags to NEEDS_PREPROCESSING.

ExpandRecips expands any distribution lists that have the messaging address type of MAPIPDL.

Notes to Callers

Always call ExpandRecips as part of your message processing. Make a call to ExpandRecips one of the first calls in your IMessage::SubmitMessage method implementation.

See also

Reference

IMessage::SubmitMessage
IMAPISupport : IUnknown


IMAPISupport::GetLastError

 Copy code hover
[image]

IMAPISupport::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous support object error.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] A handle to the error value generated in the previous method call for the support object.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if a MAPIERROR structure with appropriate error information cannot be provided.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and MAPI does not support Unicode, or MAPI_UNICODE was not set and MAPI supports only Unicode.

Remarks

The IMAPISupport::GetLastError method is implemented for all support objects. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can use the pointer to the MAPIERROR structure, if MAPI supplies one, in the lppMAPIError parameter only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or it has nothing more to report about the error. In this situation, lppMAPIError returns a pointer to NULL instead.

For more information about the GetLastError method, see MAPI Extended Errors.

To release all the memory allocated by MAPI, call the MAPIFreeBuffer function for the returned MAPIERROR structure.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPISupport : IUnknown

Concepts

MAPI Extended Errors


IMAPISupport::GetMemAllocRoutines

 Copy code hover
[image]

IMAPISupport::GetMemAllocRoutines
See also Send feedback

Published: July 16, 2012

Retrieves the addresses of the MAPI memory allocation and deallocation functions (MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer).

C++
HRESULT GetMemAllocRoutines(
  LPALLOCATEBUFFER FAR * lppAllocateBuffer,
  LPALLOCATEMORE FAR * lppAllocateMore,
  LPFREEBUFFER FAR * lppFreeBuffer
);

Parameters

lppAllocateBuffer

[out] A pointer to a pointer to the MAPIAllocateBuffer function. MAPIAllocateBuffer allocates memory.

lppAllocateMore

[out] A pointer to a pointer to the MAPIAllocateMore function. MAPIAllocateMore allocates additional memory for memory that was originally allocated by using MAPIAllocateBuffer.

lppFreeBuffer

[out] A pointer to a pointer to the MAPIFreeBuffer function. MAPIFreeBuffer frees memory.

Return value

S_OK

The function addresses were successfully returned.

Remarks

The IMAPISupport::GetMemAllocRoutines method is implemented for all support objects. Service providers call GetMemAllocRoutines to get the addresses of the three memory allocation functions that are passed to their initialization function (ABProviderInit, MSProviderInit, or XPProviderInit).

See also

Reference

MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
IMAPISupport : IUnknown


IMAPISupport::GetOneOffTable

 Copy code hover
[image]

IMAPISupport::GetOneOffTable
See also Send feedback

Published: July 16, 2012

Returns a pointer to the MAPI one-off table (a list of templates that all address book providers support for creating new recipients).

C++
HRESULT GetOneOffTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the string columns. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

lppTable

[out] A pointer to a pointer to the one-off table.

Return value

S_OK

The one-off table was successfully retrieved.

Remarks

The IMAPISupport::GetOneOffTable method is implemented for address book provider support objects. Address book providers call GetOneOffTable to retrieve the complete list of templates for creating new recipients. This table includes templates that address book providers that are active in the session support, as well as templates that MAPI supports.

The newly created recipients can be used to address a message or can be added to an address book container.

For a list of the properties that make up the required column set in one-off tables, see One-Off Tables.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the IMAPITable::QueryColumns and IMAPITable::QueryRows methods. This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

Notes to Callers

If you are registered to receive notifications of changes to this one-off table, you will also receive notifications of changes to other providers' one-off tables. Based on these notifications, you can support new address types that are added during the current session.

See also

Reference

IABContainer::CreateEntry
IMAPISupport::NewEntry
IMAPITable : IUnknown
IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::QuerySortOrder
PidTagCreateTemplates Canonical Property
IMAPISupport : IUnknown

Concepts

One-Off Tables


IMAPISupport::GetSvcConfigSupportObj

 Copy code hover
[image]

IMAPISupport::GetSvcConfigSupportObj
See also Send feedback

Published: July 16, 2012

Creates a message service support object.

C++
HRESULT GetSvcConfigSupportObj(
  ULONG ulFlags,
  LPMAPISUP FAR * lppSvcSupport
);

Parameters

ulFlags

[in] Reserved; must be zero.

lppSvcSupport

[out] A pointer to a pointer to the new message service support object.

Return value

S_OK

The configuration support object was successfully created.

Remarks

The IMAPISupport::GetSvcConfigSupportObj method is implemented for all support objects. Service providers call GetSvcConfigSupportObj to create a configuration support object to pass to a message service entry point function.

A message service entry point function is based on the MSGSERVICEENTRY prototype and is called by methods of the IMsgServiceAdmin interface. A message service entry point function allows message services to configure themselves or perform other actions when the profile is changed. Message service entry point functions can support configuration changes by displaying a property sheet or through a property value array passed to the IMsgServiceAdmin::ConfigureMsgService method.

See also

Reference

IMsgServiceAdmin : IUnknown
IMsgServiceAdmin::ConfigureMsgService
IMsgServiceAdmin::CreateMsgService
IProfAdmin : IUnknown
MSGSERVICEENTRY
IMAPISupport : IUnknown


IMAPISupport::IStorageFromStream

 Copy code hover
[image]

IMAPISupport::IStorageFromStream
See also Send feedback

Published: July 16, 2012

Implements a storage object to access a stream.

C++
HRESULT IStorageFromStream(
  LPUNKNOWN lpUnkIn,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPSTORAGE FAR * lppStorageOut
);

Parameters

lpUnkIn

[in] A pointer to a stream object.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the stream pointed to by lpUnkIn. Any of the following values are valid: IID_IStream, IID_ILockBytes, or null, which indicates that the IStream interface should be used to access the stream.

ulFlags

[in] A bitmask of flags that controls how the storage object is to be created relative to the stream object. By default, the storage is created with read-only access and the stream starts at position zero in the storage. The following flags can be set:

STGSTRM_CREATE

A new storage object should be created for the stream object.

STGSTRM_CURRENT

The storage object should start at the current position of the stream.

STGSTRM_MODIFY

The caller should have read/write permission to the returned storage object.

STGSTRM_RESET

The storage object should start at position zero.

lppStorageOut

[out] A pointer to a pointer to the storage object.

Return value

S_OK

The storage object was successfully created.

Remarks

The IMAPISupport::IStorageFromStream method is implemented for all service provider support objects. Service providers call IStorageFromStream to create a storage object to use for opening particular properties. Service providers that have their own implementation of the IStorage interface do not need to call IStorageFromStream.

The storage object created by IStorageFromStream calls the stream's IUnknown::AddRef method to increment its reference count and then decrements the count when the storage is released.

Notes to Callers

When the IMAPIProp::OpenProperty method of one of your objects is called to open a property with the IStorage interface, perform the following tasks:

  1. Open a stream object with read/write permission for the property.

  2. Internally mark the property stream as a storage object.

  3. Call IStorageFromStream to generate a storage object.

  4. Return a pointer to this storage object.

If you implement additional interfaces that use the storage object, create an object that wraps the storage object and implement a higher level IUnknown::QueryInterface method.

Do not allow a property to be opened with the IStream interface if it was created with IStorage. Conversely, do not allow a property to be opened with the IStorage interface if it was created with IStream.

With one exception, it is acceptable to use the IStreamDocfile interface to stream a storage object from one container to another, but the IID_IStreamDocfile interface identifier must be passed in the OpenProperty method's lpInterface parameter.

See also

Reference

IMAPIProp::OpenProperty
IMAPISupport : IUnknown


IMAPISupport::MakeInvalid

 Copy code hover
[image]

IMAPISupport::MakeInvalid
See also Send feedback

Published: July 16, 2012

Marks an object as unusable.

C++
HRESULT MakeInvalid(
ULONG ulFlags,
LPVOID lpObject,
ULONG ulRefCount,
ULONG cMethods
);

Parameters

ulFlags

Reserved; must be zero.

lpObject

[in] A pointer to the object to be invalidated. The object's interface must be derived from IUnknown.

ulRefCount

[in] The object's present reference count.

cMethods

[in] The count of methods in the object's vtable.

Return value

S_OK

The object was successfully marked as unusable.

Remarks

The IMAPISupport::MakeInvalid method is implemented for all support objects. The object to be invalidated must be derived from the IUnknown interface or from an interface derived from IUnknown.

MakeInvalid marks an object as unusable by replacing the object's vtable with a stub vtable of similar size in which the IUnknown::AddRef and IUnknown::Release methods perform as expected. However, any other methods fail, returning the value MAPI_E_INVALID_OBJECT.

Notes to Callers

Service providers and message services typically call MakeInvalid at shutdown time. However, MakeInvalid can be called at any time. For example, if a client releases an object without releasing some of its subobjects, you can call MakeInvalid immediately to release those subobjects.

You must own the object that you attempt to invalidate. It must be at least 16 bytes long and have at least three methods in its vtable.

You can call MakeInvalid and then perform any shutdown work, such as discarding associated data structures, that is usually done during the release of an object. Code to support the object need not be kept in memory, because MAPI frees the memory by calling MAPIFreeBuffer and then releases the object. You can release resources, call MakeInvalid, and then ignore the invalidated object.

See also

Reference

MAPIAllocateBuffer
IMAPISupport : IUnknown


IMAPISupport::ModifyProfile

 Copy code hover
[image]

IMAPISupport::ModifyProfile
See also Send feedback

Published: July 16, 2012

Makes changes to a message store profile section permanent.

C++
HRESULT ModifyProfile(
ULONG ulFlags
);

Parameters

ulFlags

[in] A bitmask of flags that indicates the type of message store. The following flag can be set:

MDB_TEMPORARY

The message store is temporary and should not be added to the message store table. When MDB_TEMPORARY is set, ModifyProfile returns S_OK immediately.

Return value

S_OK

The changes to the profile section were successful.

Remarks

The IMAPISupport::ModifyProfile method is implemented for message store provider support objects. Message store providers call ModifyProfile to prompt MAPI to modify their profile information.

ModifyProfile adds the profile section that is associated with the calling provider to the list of installed message store provider resources. This causes the message store to be listed in the message store table, which is available to clients through the IMAPISession::GetMsgStoresTable method, and to be opened without the display of a dialog box.

If the MDB_TEMPORARY flag is set, MAPI does nothing and the method returns immediately with S_OK.

See also

Reference

IMAPISession::GetMsgStoresTable
IMAPISupport : IUnknown


IMAPISupport::ModifyStatusRow

 Copy code hover
[image]

IMAPISupport::ModifyStatusRow
See also Send feedback

Published: July 16, 2012

Modifies the status table by adding a new row or modifying an existing row.

C++
HRESULT ModifyStatusRow(
ULONG cValues,
LPSPropValue lpColumnVals,
ULONG ulFlags
);

Parameters

cValues

[in] The count of properties to be included in the new or modified status table row.

lpColumnVals

[in] A pointer to an array of property values that describe the properties to be included as columns in the new or modified status table row.

ulFlags

[in] A bitmask of flags that controls how information that defines the status table row is processed. The following flag can be set:

STATUSROW_UPDATE

Directs MAPI to merge the properties included in the array pointed to by lpColumnVals with an existing status table row, rather than in a new row.

Return value

S_OK

The status table was successfully updated.

Remarks

The IMAPISupport::ModifyStatusRow method is implemented for all service provider support objects. Service providers call ModifyStatusRow at logon time to add a row to the status table and at other times during the session to update the row. ModifyStatusRow provides MAPI with the information necessary to build the status table.

Notes to Callers

Set the STATUSROW_UPDATE flag when you call ModifyStatusRow to make changes to the properties in your existing status table row. Doing so informs MAPI that only the columns being changed are passed in the lpColumnVals parameter.

Clients can use the information in the status table to access your status object.

For a complete list of columns that you should include in your status table row, see Status Tables.

See also

Reference

IMAPISupport : IUnknown


IMAPISupport::NewEntry

 Copy code hover
[image]

IMAPISupport::NewEntry
See also Send feedback

Published: July 16, 2012

Adds a new recipient directly to an address book container or to the recipient list of an outgoing message.

C++
HRESULT NewEntry(
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG cbEIDContainer,
  LPENTRYID lpEIDContainer,
  ULONG cbEIDNewEntryTpl,
  LPENTRYID lpEIDNewEntryTpl,
  ULONG FAR * lpcbEIDNewEntry,
  LPENTRYID FAR * lppEIDNewEntry
);

Parameters

ulUIParam

[in] A handle to the parent window of the dialog box.

ulFlags

[in] Reserved; must be zero.

cbEIDContainer

[in] The byte count in the entry identifier pointed to by the lpEIDContainer parameter.

lpEIDContainer

[in] A pointer to the entry identifier of the container to receive the new entry. If cbEIDContainer is 0 and lpEIDContainer is NULL, NewEntry creates a one-off entry identifier that is the same type as is generated by a call to the IMAPISupport::CreateOneOff method.

cbEIDNewEntryTpl

[in] The byte count in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.

lpEIDNewEntryTpl

[in] A pointer to the entry identifier of the template to be used to create the new entry. If cbEIDNewEntryTpl is 0 and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box that enables the user to select from a list of templates for adding new entries.

lpcbEIDNewEntry

[out] A pointer to the byte count in the entry identifier pointed to by the lppEIDNewEntry parameter.

lppEIDNewEntry

[out] A pointer to a pointer to the entry identifier of the newly created entry.

Return value

S_OK

The new entry was successfully created.

Remarks

The IMAPISupport::NewEntry method is implemented for address book provider support objects. Address book providers call NewEntry to create a new address book entry to be added directly into a container or to be used to address an outgoing message.

Notes to Callers

If you want the new entry to be added to a specific container, set lpEIDContainer to the container's entry identifier and cbEIDContainer to the byte count in the entry identifier.

If you want the new entry to be added to the recipient list of an outgoing message, set lpEIDContainer to NULL and cbEIDContainer to 0.

If you want to allow the user of a client application to select the type of entry to be created, pass 0 in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. NewEntry displays the MAPI one-off table, a list of templates that MAPI and each of the address book providers in the session support. Each template can create a recipient entry for one or more address types.

If you want to retain the entry identifier of the new entry, pass valid pointers in the lpcbEIDNewEntry and lppEIDNewEntry parameters. You are responsible for freeing this entry identifier when you are finished with it by calling the MAPIFreeBuffer function.

To use a particular template to add a new entry to a modifiable container, use the following procedure:

  1. Call the IMAPISupport::OpenEntry method to open the destination container, and set the lpEntryID parameter to the entry identifier of the container.

  2. Call the destination container's IMAPIProp::OpenProperty method, and set the ulPropTag parameter to PR_CREATE_TEMPLATES (PidTagCreateTemplates) and the lpiid parameter to IID_IMAPITable. The container will return a one-off table that lists all of the templates that it supports for creating new entries.

  3. Retrieve the row that represents the template for the particular type of entry you want to create. The PR_ADDRTYPE (PidTagAddressType) column indicates the address type that is supported by the template.

  4. Call IMAPISupport::NewEntry and set the lpEIDNewEntryTpl parameter to the entry identifier of the selected template. The entry identifier is the PR_ENTRYID (PidTagEntryId) column from the template's row in the one-off table. Pass 0 in cbEIDContainer and NULL in lpEIDContainer. Pass a valid pointer in the lppEIDNewEntry parameter if you want to retain the new entry's entry identifier.

See also

Reference

IMAPIProp::OpenProperty
IMAPISupport::OpenEntry
PidTagCreateTemplates Canonical Property
IMAPISupport : IUnknown


IMAPISupport::NewUID

 Copy code hover
[image]

IMAPISupport::NewUID
See also Send feedback

Published: July 16, 2012

Creates a new MAPIUID structure to be used as a unique identifier.

C++
HRESULT NewUID(
LPMAPIUID lpMuid
);

Parameters

lpMuid

A pointer to the new MAPIUID structure.

Return value

S_OK

The new MAPIUID structure was created.

Remarks

The IMAPISupport::NewUID method is implemented for all support objects. Service providers and message services call NewUID whenever they need to generate a long-term unique identifier. A message store provider, for example, might call NewUID to obtain a MAPIUID to put in the PR_SEARCH_KEY (PidTagSearchKey) property of a newly created message.

Notes to Callers

Do not confuse the MAPIUID structure that you register at logon time with the MAPIUID structures that the NewUID method creates. The MAPIUID structure that you register when you call the IMAPISupport::SetProviderUID method represents your address book or message store provider to MAPI and is used to distinguish entry identifiers that different providers create. This MAPIUID structure should be hard-coded and not obtained through a call to NewUID.

See also

Reference

MAPIUID
IMAPISupport : IUnknown


IMAPISupport::Notify

 Copy code hover
[image]

IMAPISupport::Notify
See also Send feedback

Published: July 16, 2012

Sends a notification of a specified event to an advise source that originally registered for the notification through the IMAPISupport::Subscribe method.

C++
HRESULT Notify(
LPNOTIFKEY lpKey,
ULONG cNotification,
LPNOTIFICATION lpNotifications,
ULONG FAR * lpulFlags
);

Parameters

lpKey

[in] A pointer to the notification key for the advise source object. The lpKey parameter cannot be NULL.

cNotification

[in] The count of notification structures pointed to by the lpNotifications parameter.

lpNotifications

[in] A pointer to an array of NOTIFICATION structures that describe pending notifications.

lpulFlags

[in, out] A bitmask of flags that controls the notification process. On input, the following flag can be set:

MAPI_UNICODE

The strings in the notification structures pointed to by lpNotifications are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

On output, MAPI can set the following flag:

NOTIFY_CANCELED

A callback function canceled a synchronous notification.

Return value

S_OK

The notifications were successfully generated.

Remarks

The IMAPISupport::Notify method is implemented for all service provider support objects. Service providers call Notify to request that MAPI generate a notification for an advise sink that has previously registered for the notification through the IMAPISupport::Subscribe method.

Notify copies the structures pointed to by the lpNotifications parameter into memory and calls the appropriate advise sink's IMAPIAdviseSink::OnNotify method. When OnNotify is finished with the notification, it releases the memory involved. The caller does not need to allocate memory; MAPI performs all necessary memory allocation.

Notes to Callers

The notification key passed in the lpKey parameter should be identical to the key passed in lpKey to the IMAPISupport::Subscribe method. Many providers use the entry identifier of the advise source as the key, but other data, such as a file path, can be used. MAPI uses this key to find all the registrations for notifications on the identified advise source.

Be sure that you set the lpEntryID member of the notification structure to a long-term entry identifier.

If you set the NOTIFY_SYNC flag on the Subscribe call for any of the pending notifications, Notify calls the IMAPIAdviseSink::OnNotify method callback functions before returning. An advise sink can be created manually or by calling HrAllocAdviseSink. The HrAllocAdviseSink function allows its caller to specify a callback function that Notify calls as part of the notification. The callback function conforms to the NOTIFCALLBACK prototype. Callback functions implemented by clients always return S_OK; callback functions implemented by service providers can return CALLBACK_DISCONTINUE.

If a callback function returns CALLBACK_DISCONTINUE, MAPI stops sending notifications and returns NOTIFY_CANCELED in the Notify method's lpulFlags parameter. You can assume that the process is inactive and stop generating notifications for that process. If Notify returns 0 in lpulFlags, the process is still active and you should continue to send notifications, as appropriate.

When you use synchronous notifications, be careful to avoid deadlock situations.

For more information about the notification process, see Event Notification in MAPI.

See also

Reference

IMAPISupport::Subscribe
IMAPISupport::Unsubscribe
NOTIFCALLBACK
NOTIFICATION
NOTIFKEY
PidTagRecordKey Canonical Property
IMAPISupport : IUnknown


IMAPISupport::OpenAddressBook

 Copy code hover
[image]

IMAPISupport::OpenAddressBook
See also Send feedback

Published: July 16, 2012

Provides access to the address book.

C++
HRESULT OpenAddressBook(
LPCIID lpInterface,
ULONG ulFlags,
LPADRBOOK FAR * lppAdrBook
);

Parameters

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the address book. Valid values are NULL, which indicates the standard address book interface IAddrBook, and IID_IAddrBook.

ulFlags

Reserved; must be zero.

lppAdrBook

[out] A pointer to a pointer to the address book.

Return value

S_OK

Access to the address book was provided.

MAPI_W_ERRORS_RETURNED

The call succeeded, but one or more address book providers could not be loaded. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISupport::OpenAddressBook method is implemented for all service provider support objects. Service providers, typically tightly coupled message store and transport providers, call OpenAddressBook to get access to the address book. The returned IAddrBook pointer can be used for a variety of address book tasks, including opening address book containers, finding messaging users, and displaying address dialog boxes.

Notes to Callers

OpenAddressBook can return MAPI_W_ERRORS_RETURNED if it cannot load one or more of the address book providers in the current profile. This value is a warning and you should treat the call as successful. Even if all of the address book providers failed to load, OpenAddressBook still succeeds, returning MAPI_W_ERRORS_RETURNED and an IAddrBook pointer in the lppAdrBook parameter. Because OpenAddressBook always returns a valid IAddrBook pointer, you must release it when you are finished using it.

If one or more address book providers failed to load, call IMAPISupport::GetLastError to obtain a MAPIERROR structure that contains information about the providers that did not load.

See also

Reference

IAddrBook : IMAPIProp
IMAPISession::OpenAddressBook
IMAPISupport : IUnknown


IMAPISupport::OpenEntry

 Copy code hover
[image]

IMAPISupport::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens an object and returns an interface pointer for further access.

C++
HRESULT OpenEntry(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
ULONG ulOpenFlags,
ULONG FAR * lpulObjType,
LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object to open.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the object. Passing NULL results in the object's standard interface being returned. For example, if the object to be opened is a message, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.

ulOpenFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the object be opened with the maximum network permissions allowed for the caller. For example, if the caller has read/write permission, the object should be opened as read/write; if the caller has read-only permission, the object should be opened as read-only.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully accessible to the caller. If the object is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened as read-only, and callers should not work on the assumption that read/write permission has been granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppUnk

[out] A pointer to a pointer to the opened object.

Return value

S_OK

The object was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object, or an attempt was made to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

There is not an object associated with the entry identifier passed in the lpEntryID parameter.

MAPI_E_UNKNOWN_ENTRYID

The entry identifier passed in the lpEntryID parameter is in an unrecognizable format. This value is typically returned if the address book provider that contains the object is not open.

Remarks

The IMAPISupport::OpenEntry method is implemented for all service provider support objects. Service providers call IMAPISupport::OpenEntry to retrieve a pointer to an interface that can be used to access a particular object.

Notes to Callers

Call IMAPISupport::OpenEntry only when you do not know what kind of object you are opening. If you know you are opening a folder or a message, call IMsgStore::OpenEntry instead. If you know you are opening an address book container, a messaging user, or a distribution list, call IAddrBook::OpenEntry. These more specific methods are faster than IMAPISupport::OpenEntry.

IMAPISupport::OpenEntry opens all objects as read-only, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter and your permissions are sufficient. Setting one of these flags does not guarantee a particular type of access; the permissions that you are granted depend on your access level, the object, and the service provider that owns the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL (PidTagAccessLevel) property.

Check the value returned in the lpulObjType parameter to determine that the object type returned is what you expected. If the object type is as expected, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.

See also

Reference

IMAPISupport : IUnknown


IMAPISupport::OpenProfileSection

 Copy code hover
[image]

IMAPISupport::OpenProfileSection
See also Send feedback

Published: July 16, 2012

Opens a section of the current profile and returns an IProfSect pointer for further access.

C++
HRESULT OpenProfileSection(
LPMAPIUID lpUid,
ULONG ulFlags,
LPPROFSECT FAR * lppProfileObj
);

Parameters

lpUid

[in] A pointer to the MAPIUID structure that identifies the profile section to be opened. Passing NULL for the lpUid parameter opens the caller's profile section.

ulFlags

[in] A bitmask of flags that controls how the profile section is opened. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the caller. If the profile section is not accessible, making a subsequent object call can result in an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened as read-only, and callers should not work on the assumption that read/write permission has been granted.

lppProfileObj

[out] A pointer to a pointer to the opened profile section.

Return value

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only profile section or to access an object for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

There is not a profile section associated with the entry identifier passed in lpEntryID.

MAPI_E_UNKNOWN_FLAGS

Reserved or unsupported flags were used and, therefore, the operation did not complete.

Remarks

The IMAPISupport::OpenProfileSection method is implemented for all support objects. Service providers and message services call OpenProfileSection to open a profile section and retrieve a pointer to its IProfSect interface implementation.

Notes to Callers

OpenProfileSection opens profile sections as read-only, unless you set the MAPI_MODIFY flag in the ulFlags parameter and your permission is sufficient. Setting this flag does not guarantee read/write permission; the permissions that you are granted depend on your access level and the object.

If OpenProfileSection attempts to open a nonexistent profile section as read-only, it returns MAPI_E_NOT_FOUND. If OpenProfileSection attempts to open a nonexistent profile section as read/write, it creates the profile section and returns the IProfSect pointer.

See also

Reference

IMAPIProp : IUnknown
IProfSect : IMAPIProp
MAPIUID
IMAPISupport : IUnknown


IMAPISupport::OpenTemplateID

 Copy code hover
[image]

IMAPISupport::OpenTemplateID
See also Send feedback

Published: July 16, 2012

Opens a recipient entry in a foreign address book provider.

C++
HRESULT OpenTemplateID(
ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
);

Parameters

cbTemplateID

[in] The byte count in the template identifier pointed to by lpTemplateID.

lpTemplateID

[in] A pointer to the template identifier PR_TEMPLATEID (PidTagTemplateid) property of the recipient entry to be opened.

ulTemplateFlags

[in] A bitmask of flags used to describe how to open the entry. The following flag can be set:

FILL_ENTRY

A new entry is being created. When the foreign provider receives the subsequent IABLogon::OpenTemplateID call from MAPI, it can control how the entry is created by modifying properties pointed to by the lpMAPIPropData parameter or by returning a specific interface implementation in lppMAPIPropNew to control how properties for the new entry are set.

lpMAPIPropData

[in] A pointer to the interface implementation that the caller uses to access the entry. This is the implementation that the foreign provider can wrap with its own implementation and return in the lppMAPIPropNew parameter. The lpMAPIPropData parameter must point to a read/write interface implementation that derives from IMAPIProp : IUnknown and supports the interface being requested in the lpInterface parameter.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the entry. The lppMAPIPropNew parameter points to an interface of the type specified by lpInterface. Passing NULL returns the standard interface for a messaging user, IID_IMailUser.

lppMAPIPropNew

[out] A pointer to the interface implementation that the foreign provider supplies for accessing the entry.

lpMAPIPropSibling

Reserved; must be NULL.

Return value

S_OK

The binding process was successful.

MAPI_E_UNKNOWN_ENTRYID

The foreign address book provider doesn't exist.

Remarks

The IMAPISupport::OpenTemplateID method is implemented only for address book provider support objects. OpenTemplateID is called only by address book providers that can act as hosts for entries that belong to other address book providers, also known as foreign providers. Host providers call OpenTemplateID to open a foreign entry, which occurs when data in the host provider is bound to code in the foreign provider.

Notes to Callers

Call OpenTemplateID only if you support the storage of entries with template identifiers from foreign address book providers. Such support places additional requirements on your IABContainer::CreateEntry and IABLogon::OpenEntry implementations. For more information, see the descriptions of these methods and Acting as a Host Address Book Provider.

If the OpenTemplateID call returns as the bound interface the same property object implementation that you passed in, you can release your reference to your property object. This is because the foreign provider has called the object's AddRef method to keep its own reference. If the foreign provider does not need to keep a reference to the property object, then OpenTemplateID will return the unbound property object.

If OpenTemplateID fails with MAPI_E_UNKNOWN_ENTRYID, try to continue by treating the entry as read-only.

See also

Reference

IABLogon::OpenTemplateID
IPropData : IMAPIProp
PidTagTemplateid Canonical Property
IMAPISupport : IUnknown


IMAPISupport::PrepareSubmit

 Copy code hover
[image]

IMAPISupport::PrepareSubmit
See also Send feedback

Published: July 16, 2012

Prepares a message for submission to the MAPI spooler.

C++
HRESULT PrepareSubmit(
LPMESSAGE lpMessage,
ULONG FAR * lpulFlags
);

Parameters

lpMessage

[in] A pointer to the message to prepare.

lpulFlags

[in, out] On input, the lpulFlags parameter is reserved and must be zero. On output, lpulFlags must be NULL.

Return value

S_OK

The message was successfully prepared.

Remarks

The IMAPISupport::PrepareSubmit method is implemented for message store provider support objects. Message store providers call PrepareSubmit in their implementation of the IMessage::SubmitMessage method to prepare a message for submission to the MAPI spooler.

PrepareSubmit is used to handle messages that have the MSGFLAG_RESEND flag set in their PR_MESSAGE_FLAGS (PidTagMessageFlags) property. MSGFLAG_RESEND is set for messages that include a request to be resent when an initial transmission fails. PrepareSubmit determines which of the recipients in the recipient list successfully received the message and which did not.

To access the recipient list, PrepareSubmit calls the message's IMessage::GetRecipientTable method. To retrieve the recipient data, PrepareSubmit calls the recipient table's IMAPITable::QueryRows method. For each row in the table, PrepareSubmit checks the PR_RECIPIENT_TYPE (PidTagRecipientType) property and takes one of the following actions:

  • If the MAPI_SUBMITTED flag is set, PrepareSubmit clears the flag and sets the PR_RESPONSIBILITY (PidTagResponsibility) property to FALSE.

  • If the MAPI_SUBMITTED flag is not set, PrepareSubmit changes PR_RECIPIENT_TYPE to MAPI_P1 and sets PR_RESPONSIBILITY to TRUE.

Notes to Callers

Before you call PrepareSubmit, be sure you have called the IMAPISupport::SpoolerNotify method and set the NOTIFY_READYTOSEND flag in the ulFlags parameter. The SpoolerNotify call must be made once per session before the call to PrepareSubmit. SpoolerNotify synchronizes the MAPI spooler and ensures that all needed transport providers are logged on and their address types are registered.

See also

Reference

IMAPIFolder::GetMessageStatus
IMessage::SubmitMessage
IMAPISupport : IUnknown


IMAPISupport::ReadReceipt

 Copy code hover
[image]

IMAPISupport::ReadReceipt
See also Send feedback

Published: July 16, 2012

Generates a read or nonread report for a message.

C++
HRESULT ReadReceipt(
ULONG ulFlags,
LPMESSAGE lpReadMessage,
LPMESSAGE FAR * lppEmptyMessage
);

Parameters

ulFlags

[in] A bitmask of flags that controls how the read or nonread report is generated. The following flag can be set:

MAPI_NON_READ

A nonread report is generated. If MAPI_NON_READ is not set, a read report is generated.

lpReadMessage

[in] A pointer to the message about which the report should be generated.

lppEmptyMessage

[in, out] On input, lppEmptyMessage points to a pointer to an empty message. On output, lppEmptyMessage points to a pointer to the report message.

Return value

S_OK

The report was successfully generated.

Remarks

The IMAPISupport::ReadReceipt method is implemented only for message store provider support objects. Message store providers call ReadReceipt to instruct MAPI to generate a read or nonread report for the message pointed to by the lpReadMessage parameter.

Notes to Callers

Call ReadReceipt when the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set and one of the following conditions is true:

  • The message has been read.

  • The message has been moved.

  • The message has been copied.

  • The message's IMessage::SetReadFlag method has been called.

Do not call ReadReceipt when a message is deleted.

A read or nonread report should be sent only once for a message. Keep track of a message's read status and do not send multiple reports for a single message.

If the lppEmptyMessage parameter points to a valid report message when MAPI returns from ReadReceipt, call the IMessage::SubmitMessage method to send the message and then release the pointer by calling its IUnknown:s:Release method.

If ReadReceipt fails, the message should be released without being submitted. If you store the message's read status, you can attempt to generate the read or nonread report at a later time.

You can either hide or display read and nonread reports generated by stores in your folders. Storing read and nonread reports in hidden folders enables you to implement tighter security.

See also

Reference

IMAPIFolder::DeleteMessages
IMessage::SubmitMessage
PidTagReadReceiptRequested Canonical Property
IMAPISupport : IUnknown


IMAPISupport::RegisterPreprocessor

 Copy code hover
[image]

IMAPISupport::RegisterPreprocessor
See also Send feedback

Published: July 16, 2012

Registers a transport provider's preprocessor function (a function that conforms to the PreprocessMessage prototype).

C++
HRESULT RegisterPreprocessor(
LPMAPIUID lpMuid,
LPSTR lpszAdrType,
LPSTR lpszDLLName,
LPSTR lpszPreprocess,
LPSTR lpszRemovePreprocessInfo,
ULONG ulFlags
);

Parameters

lpMuid

[in] A pointer to the MAPIUID structure that contains the identifier that the preprocessor function handles. The lpMuid parameter can be NULL.

lpszAdrType

[in] A pointer to the address type for the messages the function operates on, such as FAX, SMTP, or X500. The lpszAdrType parameter can be NULL.

lpszDLLName

[in] A pointer to the name of the dynamic-link library (DLL) that contains the entry point for the preprocessor function.

lpszPreprocess

[in] A pointer to the name of the preprocessor function. The lpszPreprocess parameter can be NULL.

lpszRemovePreprocessInfo

[in] A pointer to the name of the function that removes preprocessor information (a function that conforms to the RemovePreprocessInfo prototype). The lpszRemovePreprocessInfo parameter can be NULL.

ulFlags

Reserved; must be zero.

Return value

S_OK

The preprocessor function was successfully registered.

Remarks

The IMAPISupport::RegisterPreprocessor method is implemented for transport provider support objects only. Transport providers call RegisterPreprocessor to register a preprocessor function (a function that conforms to the PreprocessMessage prototype). A preprocessor function must be registered before the MAPI spooler can call it.

The lpszPreprocess, lpszRemovePreprocessInfo, and lpszDLLName parameters should all point to strings that can be used in conjunction with calls to the Win32 GetProcAddress function, allowing the preprocessor's DLL entry point to be called correctly.

Notes to Callers

Calls to preprocessors are specific to transport provider order. This means that if another transport provider ahead of your provider is able to handle a message, your preprocessor function will not be called for that message. Your preprocessor function will be called only for messages that you will handle.

You can write preprocessor functions to handle either a specific identifier stored in a MAPIUID structure or a type of address. If you specify both a MAPIUID structure in the lpMuid parameter and an address type in the lpszAdrType parameter, your function will be called for message recipients that match either the MAPIUID or the address type. If lpMuid is NULL and lpszAdrType is non-NULL, your function will be called only for recipients that have an address that matches the type pointed to by lpszAdrType. If lpMuid is non-NULL and lpszAdrType is NULL, your function will be called for recipients that match MAPIUID, regardless of their address type. If both are NULL, your function is called for all recipients of the message.

See also

Reference

MAPIUID
PreprocessMessage
RemovePreprocessInfo
IMAPISupport : IUnknown


IMAPISupport::SetProviderUID

 Copy code hover
[image]

IMAPISupport::SetProviderUID
See also Send feedback

Published: July 16, 2012

Registers a MAPIUID structure that uniquely represents the service provider.

C++
HRESULT SetProviderUID(
LPMAPIUID lpProviderID,
ULONG ulFlags
);

Parameters

lpProviderID

[in] A pointer to the MAPIUID structure that identifies the address book or message store provider.

ulFlags

Reserved; must be zero.

Return value

S_OK

The MAPIUID structure was successfully registered.

Remarks

The IMAPISupport::SetProviderUID method is implemented for address book and message store provider support objects. These providers call SetProviderUID to register a unique identifier described in the MAPIUID structure that is pointed to by lpProviderID. Providers include this identifier in all of the entry identifiers that they create.

MAPI uses the MAPIUID structure when it sends outbound messages to the MAPI spooler and to determine the appropriate provider for handling client requests. For example, when a client calls the IMAPISession::OpenEntry method, MAPI examines the MAPIUID portion of the entry identifier, maps it to the provider that passed it to SetProviderUID, and calls that provider's OpenEntry.

Notes to Callers

Call SetProviderUID at logon time to register your MAPIUID structure. MAPI allows address book and message store providers to register multiple identifiers. When you make multiple calls to SetProviderUID, it always adds the MAPIUID structure to the provider's set of MAPIUID structures, even if the MAPIUID is a duplicate. SetProviderUID cannot remove a MAPIUID.

See also

Reference

MAPIUID
IMAPISupport : IUnknown


IMAPISupport::SpoolerNotify

 Copy code hover
[image]

IMAPISupport::SpoolerNotify
See also Send feedback

Published: July 16, 2012

Notifies the MAPI spooler of a change in status or a request for service.

C++
HRESULT SpoolerNotify(
ULONG ulFlags,
LPVOID lpvData
);

Parameters

ulFlags

[in] A bitmask of flags that indicates the type of notification. Transport providers can set all of the flags except for NOTIFY_NEWMAIL_RECEIVED; only NOTIFY_NEWMAIL_RECEIVED and NOTIFY_READTOSEND are valid for message store providers. The following flags are valid for the ulFlags parameter:

NOTIFY_CONFIG_CHANGE

Registers a request to change the transport provider's configuration.

NOTIFY_CRITICAL_ERROR

An unrecoverable error has occurred to the transport provider. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter for transport provider calls, these flags are mutually exclusive.

NOTIFY_CRITSEC

Requests a critical section for the transport provider. The lpvData parameter is undefined and should be NULL.

NOTIFY_NEWMAIL

The MAPI spooler should download any newly received messages at the next available time. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_NEWMAIL_RECEIVED

A new message has been received in the message store. The lpvData parameter points to a NEWMAIL_NOTIFICATION structure that describes the message. This flag is used for message store providers that are tightly coupled with transport providers and is ignored if the store provider is logged on with the MAPI_NO_MAIL flag set.

NOTIFY_NONCRIT

Releases a critical section that was obtained with a previous call to SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_READYTOSEND

The transport or message store provider is ready to send messages. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_SENTDEFERRED

A previously deferred message should now be sent, and the transport provider should be notified when the message is ready to be delivered by using a call to the IXPLogon::SubmitMessage method. The entry identifier of the deferred message is contained in an SBinary structure pointed to by lpvData. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter, these flags are mutually exclusive.

lpvData

[in] A pointer to associated data applicable to a notification. The lpvData parameter points to valid data only when the following flags are set (lpvData is NULL when ulFlags is set to the other notification types):

ulFlags setting

lpvData value

NOTIFY_CRITICAL_ERROR

Information about the error.

NOTIFY_NEWMAIL_RECEIVED

A NEWMAIL_NOTIFICATION structure that contains information about the newly delivered message.

NOTIFY_SENTDEFERRED

An SBinary structure that contains the entry identifier of deferred message.

Return value

S_OK

The notification was successful.

Remarks

The IMAPISupport::SpoolerNotify method is implemented for message store and transport provider support objects. These providers call SpoolerNotify to notify the MAPI spooler of a change in status or a request for service. SpoolerNotify is called primarily by transport providers and may be called at any time during the session.

Notes to Transport Providers

If you have changed your transport provider configuration, call SpoolerNotify and set ulFlags to NOTIFY_CONFIG_CHANGED. SpoolerNotify responds by calling the IXPLogon::AddressTypes method to query for a change in supported address types.

If you need a critical section to ensure uninterrupted processing, call SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. Setting this flag informs the MAPI spooler that it should not call the IXPLogon::Idle and IXPLogon::Poll methods. While you have a critical section open, return MAPI_E_BUSY whenever the IMAPIStatus::ValidateState method is called. When you are finished with the critical section, make another call to SpoolerNotify with ulFlags set to NOTIFY_NONCRIT.

For example, if your remote transport provider is in the process of uploading messages, you might need to allow a user to enter a telephone number to establish the remote connection. Before you loop through the dialog box procedure, you should declare a critical section. When the user closes the dialog box, terminating the dialog box procedure, you should release the critical section.

When you set ulFlags to NOTIFY_CRITICAL_ERROR, the MAPI spooler makes no further calls to the provider except to release it. If you call SpoolerNotify with NOTIFY_CRITICAL_ERROR set from the IXPLogon::StartMessage or IXPLogon::SubmitMessage methods, return with an appropriate error value from the StartMessage or SubmitMessage call immediately after the SpoolerNotify call.

If your transport provider recovered from a condition that previously caused it to fail, call SpoolerNotify with ulFlags set to NOTIFY_READYTOSEND. This flag indicates that the provider is again ready to handle messages.

Notes to Message Store Providers

Call SpoolerNotify, passing the NOTIFY_READYTOSEND flag in ulFlags, before you make your first call to IMAPISupport::PrepareSubmit in IMessage::SubmitMessage. This call to SpoolerNotify needs to be made only once per session.

If your message store provider is tightly coupled with a transport provider and you call SpoolerNotify with ulFlags set to NOTIFY_NEWMAIL_RECEIVED, the MAPI spooler opens the new message and begins processing the new message hook function. When processing is complete, the MAPI spooler calls the IMsgStore::NotifyNewMail method to inform you of your own new message.

For more information about calling SpoolerNotify, see any of the following topics:

  • Implementing the FlushQueues Method

  • Interacting with the MAPI Spooler

  • Message Reception Model

See also

Reference

IMsgStore::NotifyNewMail
IXPLogon::StartMessage
IXPLogon::SubmitMessage
IMAPISupport : IUnknown


IMAPISupport::SpoolerYield

 Copy code hover
[image]

IMAPISupport::SpoolerYield
See also Send feedback

Published: July 16, 2012

Gives control of the CPU to the MAPI spooler so that it can perform any tasks it considers necessary.

C++
HRESULT SpoolerYield(
ULONG ulFlags
);

Parameters

ulFlags

Reserved; must be zero.

Return value

S_OK

The transport provider successfully released the CPU.

MAPI_W_CANCEL_MESSAGE

Instructs the transport provider to stop the delivery of the message to any recipients that have not yet received it.

Remarks

The IMAPISupport::SpoolerYield method is implemented for transport provider support objects. Transport providers call SpoolerYield to allow the MAPI spooler to accomplish any necessary processing.

Notes to Callers

Call SpoolerYield when you are performing lengthy operations that can be paused. This allows foreground applications to run during a long operation, such as delivery to a large recipient list across a busy network.

If SpoolerYield returns with MAPI_W_CANCEL_MESSAGE, the MAPI spooler has determined that the message should no longer be sent. Return MAPI_E_USER_CANCEL to your calling process and exit, if possible.

For more information about yielding to the MAPI spooler, see Interacting with the MAPI Spooler.

See also

Reference

IMAPISupport : IUnknown


IMAPISupport::StatusRecips

 Copy code hover
[image]

IMAPISupport::StatusRecips
See also Send feedback

Published: July 16, 2012

Generates delivery and nondelivery reports.

C++
HRESULT StatusRecips(
LPMESSAGE lpMessage,
LPADRLIST lpRecipList
);

Parameters

lpMessage

[in] A pointer to the message for which the report should be generated.

lpRecipList

[in] A pointer to an ADRLIST structure that describes the recipients of the message pointed to by lpMessage.

Return value

S_OK

The report was successfully generated.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but there are no recipient options for this type of recipient. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISupport::StatusRecips method is implemented for transport provider support objects. Transport providers call StatusRecips to request that MAPI send a delivery or nondelivery report to a set of one or more of the recipients of a message.

Notes to Callers

You can call StatusRecips multiple times during the processing of a message. However, if you call StatusRecips for an open message, do your best to collect all delivery and nondelivery information for the message recipients and call StatusRecips for that recipient list. A single point of collection is important, because multiple StatusRecips calls for one recipient can result in multiple identical reports being sent.

Store properties that relate to message delivery or nondelivery in the ADRLIST structure indicated by the lpRecipList parameter. For a complete list of required and optional properties for delivery reports and nondelivery reports, see Required Report Message Properties and Optional Report Message Properties.

Allocate memory for the ADRLIST structure in lpRecipList by using the MAPIAllocateBuffer and MAPIAllocateMore functions. MAPI releases the memory by calling the MAPIFreeBuffer function only if StatusRecips succeeds.

For an overview of delivery and nondelivery reports, see MAPI Report Messages.

See also

Reference

ADRLIST
IMAPISupport::Address
IMAPISupport::SpoolerNotify
IXPLogon::EndMessage
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
IMAPISupport : IUnknown


IMAPISupport::StoreLogoffTransports

 Copy code hover
[image]

IMAPISupport::StoreLogoffTransports
See also Send feedback

Published: July 16, 2012

Requests the orderly release of a message store.

C++
HRESULT StoreLogoffTransports(
ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[in, out] A bitmask of flags that controls how message store logoff occurs. On input, all flags for this parameter are mutually exclusive; only one of the following flags can be set per call:

LOGOFF_ABORT

Any transport provider activity for this store should be stopped before logoff. Control is returned to the client after the activity is stopped and the MAPI spooler has logged off the store. If any transport activity is taking place, the logoff does not occur and no change in the MAPI spooler or transport provider behavior occurs. If there is currently no activity, the MAPI spooler releases the store.

LOGOFF_NO_WAIT

The MAPI spooler should release the store and return control to the client immediately after all outbound mail that is ready to be sent is sent. If the message store has the default Inbox, any in-process message is received, and then further reception is disabled.

LOGOFF_ORDERLY

The MAPI spooler should release the store and return control to the client immediately after any pending messages are finished processing. No new messages should be processed.

LOGOFF_PURGE

Works the same as the LOGOFF_NO_WAIT flag. The LOGOFF_PURGE flag returns control to the caller after completion.

LOGOFF_QUIET

The logoff should not occur if any transport provider activity is taking place. The type of activity taking place is returned as a flag on output.

On output, MAPI spooler can return one or more of the following flags:

LOGOFF_COMPLETE

The logoff can complete. All resources associated with the store have been released, and the object has been invalidated. The MAPI spooler has performed or will perform all requests. Only the message store's IUnknown::Release method should be called at this point.

LOGOFF_INBOUND

A message is currently coming into the store from one or more transport providers.

LOGOFF_OUTBOUND

A message is currently being sent from the store by one or more transport providers.

LOGOFF_OUTBOUND_QUEUE

There are currently messages in the outbound queue for the store.

Return value

S_OK

The logoff procedure was successful.

Remarks

The IMAPISupport::StoreLogoffTransports method is implemented for message store provider support objects. Message store providers call StoreLogoffTransports to give client applications some control over how MAPI handles transport provider activity as a message store is closing.

If another process has the store to be logged off open for the same profile, MAPI ignores a call to StoreLogoffTransports and returns the flag LOGOFF_COMPLETE in the lpulFlags parameter.

The behavior of the store provider following the return from StoreLogoffTransports should be based on the value of lpulFlags, which indicates system status and conveys client instructions for logoff behavior.

Notes to Callers

StoreLogoffTransports is typically called from a store provider's IMsgStore::StoreLogoff method. However, it can also be called from the IUnknown::Release method of the message store. Implement the Release method of your message store so you can check whether or not a call to StoreLogoffTransports has occurred. If a call has not occurred, call StoreLogoffTransports with the LOGOFF_ABORT flag set.

The lpulFlags parameter is set to a flag that indicates how the client requires the message store to be shut down. Determine the appropriate setting for ulFlags based on the setting of the corresponding parameter in the call to StoreLogoff. That is, if a client called your StoreLogoff method with ulFlags set to LOGOFF_ORDERLY, you should call StoreLogoffTransports with ulFlags set to LOGOFF_ORDERLY.

For more information about the message store logoff process, see Shutting Down a Message Store Provider.

See also

Reference

IMsgStore::StoreLogoff
IXPLogon::FlushQueues
IMAPISupport : IUnknown


IMAPISupport::Subscribe

 Copy code hover
[image]

IMAPISupport::Subscribe
See also Send feedback

Published: July 16, 2012

Registers an advise sink to receive notifications through MAPI.

C++
HRESULT Subscribe(
LPNOTIFKEY lpKey,
ULONG ulEventMask,
ULONG ulFlags,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);

Parameters

lpKey

[in] A pointer to a notification key that represents the advise source object. The lpKey parameter cannot be NULL.

ulEventMask

[in] A mask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. The following values are valid:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to the particular address book or message store provider.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new object.

fnevObjectCopied

Registers for notifications about an object being copied.

fnevObjectDeleted

Registers for notifications about an object being deleted.

fnevObjectModified

Registers for notifications about an object being modified.

fnevObjectMoved

Registers for notifications about an object being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

ulFlags

[in] A bitmask of flags that controls how notification occurs. The following flag can be set:

NOTIFY_SYNC

When the caller calls the IMAPISupport::Notify method to generate notifications for this advise sink, Notify should make all necessary calls to advise sinks before returning. If this flag is not set, notification is asynchronous and callbacks are queued to the processes that have subscribed and started when those processes gain control of the CPU.

lpAdviseSink

[in] A pointer to an advise sink object.

lpulConnection

[out] A pointer to a nonzero connection number that represents the registration.

Return value

S_OK

The notification registration was successful.

Remarks

The IMAPISupport::Subscribe method is implemented for all service provider support objects. Service providers call Subscribe from one of their Advise methods to allow MAPI to manage the notifications.

Notes to Callers

To use the MAPI support methods for notification, create a key for the advise source the object about which notifications should be generated. The value of the key must be unique and should be easily regenerated each time the object changes.

MAPI uses the notification key to search for any callback functions registered through the HrAllocAdviseSink function for the corresponding advise source. Pass this key to IMAPISupport::Notify whenever you need to generate a notification for the corresponding advise source.

The NOTIFY_SYNC flag affects the operation of subsequent calls to Notify. When you set NOTIFY_SYNC, Notify does not return until it has finished sending all of the necessary notifications. When you do not set NOTIFY_SYNC, Notify operates asynchronously, possibly returning before all of the notifications have been sent.

See also

Reference

HrAllocAdviseSink
IMAPIAdviseSink::OnNotify
IMAPISupport::Notify
NOTIFICATION
NOTIFKEY
IMAPISupport : IUnknown


IMAPISupport::Unsubscribe

 Copy code hover
[image]

IMAPISupport::Unsubscribe
See also Send feedback

Published: July 16, 2012

Cancels the responsibility for sending notifications that was previously established with a call to the IMAPISupport::Subscribe method.

C++
HRESULT Unsubscribe(
ULONG ulConnection
);

Parameters

ulConnection

[in] The nonzero connection number that represents the notification registration previously established through IMAPISupport::Subscribe.

Return value

S_OK

The notification registration was canceled.

MAPI_E_NOT_FOUND

The connection number passed in the ulConnection parameter does not exist.

Remarks

The IMAPISupport::Unsubscribe method is implemented for all service provider support objects. Service providers call Unsubscribe to cancel a notification registration previously set up by Subscribe. Unsubscribe cancels the registration by releasing the advise sink pointer passed in the Subscribe call.

Generally, the advise sink's IUnknown::Release method is called during the Unsubscribe call. However, if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink object, the Release call is delayed until the OnNotify method returns.

See also

Reference

IMAPIAdviseSink::OnNotify
IMAPISupport::Subscribe
IMAPISupport : IUnknown


IMAPISupport::WrapStoreEntryID

 Copy code hover
[image]

IMAPISupport::WrapStoreEntryID
See also Send feedback

Published: July 16, 2012

Converts a message store's internal entry identifier to an entry identifier in the MAPI standard format.

C++
HRESULT WrapStoreEntryID(
ULONG cbOrigEntry,
LPENTRYID lpOrigEntry,
ULONG FAR * lpcbWrappedEntry,
LPENTRYID FAR * lppWrappedEntry
);

Parameters

cbOrigEntry

[in] The byte count in the entry identifier pointed to by the lpOrigEntry parameter.

lpOrigEntry

[in] A pointer to the private entry identifier for the message store.

lpcbWrappedEntry

[out] A pointer to the byte count in the entry identifier pointed to by the lppWrappedEntry parameter.

lppWrappedEntry

[out] A pointer to a pointer to the wrapped entry identifier.

Return value

S_OK

The entry identifier was successfully wrapped.

Remarks

The IMAPISupport::WrapStoreEntryID method is implemented for all service provider support objects. Service providers use WrapStoreEntryID to have MAPI generate an entry identifier for a message store that wraps the store's internal entry identifier.

Notes to Callers

When a client calls your message store's IMAPIProp::GetProps method to retrieve its PR_STORE_ENTRYID (PidTagStoreEntryId) property, and your message store uses an entry identifier in a private format, call WrapStoreEntryID and return the entry identifier pointed to by the lppWrappedEntry parameter.

Calls to the IMSProvider::Logon and IMSLogon::CompareEntryIDs methods always obtain the store's private entry identifier; the wrapped version is used only between client applications and MAPI.

Free the memory for the entry identifier pointed to by the lppWrappedEntry parameter by using the MAPIFreeBuffer function when you are finished using the entry identifier.

See also

Reference

IMAPIProp::GetProps
IMAPISupport::CompareEntryIDs
IMSLogon::CompareEntryIDs
IMSProvider::Logon
MAPIFreeBuffer
IMAPISupport : IUnknown


IMAPISync : IUnknown

 Copy code hover
[image]

IMAPISync : IUnknown
See also Send feedback

Published: July 16, 2012

Provides a mechanism for synchronizing email instead of using the Transport API. This interface is exposed on a store object. By using this interface and IMAPISyncProgressCallback : IUnknown, a transport provider can provide better progress and error messages than those that appear in the Send/Receive dialog in Microsoft Outlook.

The outbox is still in the default store. Outlook will continue to use the Transport APIs to send mail because the outgoing message cannot be in the external store.

Exposed by: | Store and transport providers
Implemented by: | Outlook
Called by: | Store and Transport providers
Interface identifier: | IID_IMAPISync

Vtable Order

SynchronizeInBackground

Implemented by message store providers. This method is called by Outlook 2010 and Outlook 2013 to start synchronization.

See also

Reference

IMAPISyncProgressCallback : IUnknown

Concepts

MAPI Interfaces


IMAPISync : SynchronizeInBackground

 Copy code hover
[image]

IMAPISync : SynchronizeInBackground
See also Send feedback

Published: July 16, 2012

Initiates a synchronization. This method is called by Microsoft Outlook 2010 and Microsoft Outlook 2013 and implemented by message store providers.

C++
HRESULT SynchronizeInBackground (
  PMAPISIB psibpb
);

Parameters

psibpb

Informs the provider of what will be synchronized and gives access to interfaces that can be used during the synchronization. It is a MAPISIB structure.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPISync : IUnknown
MAPISIB


IMAPISyncProgressCallback : IUnknown

 Copy code hover
[image]

IMAPISyncProgressCallback : IUnknown
See also Send feedback

Published: July 16, 2012

Passes the store provider as a field on the MAPISIB structure during a call to IMAPISync : SynchronizeInBackground. The store provider uses this interface to provide feedback to Microsoft Outlook about the status of the synchronization.

Header file: |
Exposed by: | Outlook
Implemented by: | Outlook
Called by: | Store providers
Interface identifier: | IID_IMAPISyncProgressCallback

Vtable Order

Progress | The store provider periodically calls this function to update the status in the Send/Receive dialog.
Error | If errors are encountered during synchronization, the store provider calls this function to provide details that are displayed in the Send/Receive dialog.
Done | The store provider calls this function to inform Outlook that synchronization has completed.

See also

Reference

IMAPISync : IUnknown

Concepts

MAPI Interfaces


IMAPISyncProgressCallback::Progress

 Copy code hover
[image]

IMAPISyncProgressCallback::Progress
See also Send feedback

Published: July 16, 2012

Updates the status in the Send/Receive dialog. The store provider periodically calls this function.

HRESULT Progress(
  const WCHAR *pwcszProgress,
  ULONG ulIndex,
  ULONG ulIndexMax
);

Parameters

pwczsProgress

A pointer to a string that displays the current progress step. It can be NULL to update progress.

ulIndex

The current position in progress.

ulIndexMax

The index indicating complete progress.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPISyncProgressCallback : IUnknown


IMAPISyncProgressCallback::Error

 Copy code hover
[image]

IMAPISyncProgressCallback::Error
See also Send feedback

Published: July 16, 2012

Provides details that are displayed in the Send/Receive dialog. If errors are encountered during synchronization, the store provider calls this function.

C++
HRESULT Error(
  HRESULT hResult,
  const WCHAR *pwcszErrorStr
);

Parameters

hResult

The HRESULT of the error or warning.

pwcszErrorStr

A pointer to the string associated with the error to be displayed.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPISyncProgressCallback : IUnknown


IMAPISyncProgressCallback::Done

 Copy code hover
[image]

IMAPISyncProgressCallback::Done
See also Send feedback

Published: July 16, 2012

Informs Microsoft Outlook that synchronization is complete.

C++
HRESULT Done(
  HANDLE hThreadDoneEvent,
  HRESULT hResult
);

Parameters

hThreadDoneEvent

An event that is passed back to allow Microsoft Outlook to close the handle. It can be NULL.

hResult

An HRESULT indicating final status of the progress.

Return value

S_OK

The call succeeded and has returned the expected value or values.

See also

Reference

IMAPISyncProgressCallback : IUnknown


IMAPITable : IUnknown

 Copy code hover
[image]

IMAPITable : IUnknown
See also Send feedback

Published: July 16, 2012

Provides a read-only view of a table. IMAPITable is used by clients and service providers to manipulate the way a table appears.

Header file: | Mapidefs.h
Exposed by: | Table objects
Implemented by: | Service providers and MAPI
Called by: | Client applications, service providers
Interface identifier: | IID_IMAPITable
Pointer type: | LPMAPITABLE

Vtable Order

GetLastError | Returns a MAPIERROR structure containing information about the previous error on the table.
Advise | Registers to receive notification of specified events affecting the table.
Unadvise | Cancels the sending of notifications previously set up with a call to the IMAPITable::Advise method.
GetStatus | Returns the table's status and type.
SetColumns | Defines the particular properties and order of properties to appear as columns in the table.
QueryColumns | Returns a list of columns for the table.
GetRowCount | Returns the total number of rows in the table.
SeekRow | Moves the cursor to a specific position in the table.
SeekRowApprox | Moves the cursor to an approximate fractional position in the table.
QueryPosition | Retrieves the current table row position of the cursor, based on a fractional value.
FindRow | Finds the next row in a table that matches specific search criteria.
Restrict | Applies a filter to a table, reducing the row set to only those rows matching the specified criteria.
CreateBookmark | Marks the table's current position.
FreeBookmark | Releases the memory associated with a bookmark.
SortTable | Orders the rows of the table based on sort criteria.
QuerySortOrder | Retrieves the current sort order for a table.
QueryRows | Returns one or more rows from a table, beginning at the current cursor position.
Abort | Stops any asynchronous operations currently in progress for the table.
ExpandRow | Expands a collapsed table category, adding the leaf rows belonging to the category to the table view.
CollapseRow | Collapses an expanded table category, removing the leaf rows belonging to the category from the table view.
WaitForCompletion | Suspends processing until one or more asynchronous operations in progress on the table have completed.
GetCollapseState | Returns the data necessary to rebuild the current collapsed or expanded state of a categorized table.
SetCollapseState | Rebuilds the current expanded or collapsed state of a categorized table using data that was saved by a prior call to the IMAPITable::GetCollapseState method.

See also

Concepts

MAPI Interfaces


IMAPITable::Abort

 Copy code hover
[image]

IMAPITable::Abort
See also Send feedback

Published: July 16, 2012

Stops any asynchronous operations currently in progress for the table.

C++
HRESULT Abort( void );

Parameters

None

Return value

S_OK

One or more asynchronous operations have been stopped.

MAPI_E_UNABLE_TO_ABORT

An asynchronous operation is in progress and cannot be stopped or it has already completed.

Remarks

The IMAPITable::Abort method stops any asynchronous operation that is currently in progress.

Notes to Callers

To find out if an asynchronous operation is in progress, call the IMAPITable::GetStatus method.

If Abort halts the processing of a call to the IMAPITable::Restrict method, the state of the table will be as it was at the time the Abort call is processed.

If Abort halts the processing of a call to the IMAPITable::SortTable method, the table's sort order is unaffected and remains as it was before the SortTable call.

See also

Reference

IMAPITable::GetStatus
IMAPITable::Restrict
IMAPITable::SortTable
IMAPITable : IUnknown


IMAPITable::Advise

 Copy code hover
[image]

IMAPITable::Advise
See also Send feedback

Published: July 16, 2012

Registers an advise sink object to receive notification of specified events affecting the table.

C++
HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

Parameters

ulEventMask

[in] Value indicating the type of event that will generate the notification. Only the following value is valid:

fnevTableModified

lpAdviseSink

[in] Pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have been already allocated.

lpulConnection

[out] Pointer to a nonzero value that represents the successful notification registration.

Return value

S_OK

The notification registration successfully completed.

MAPI_E_NO_SUPPORT

The table implementation either does not support changes to its rows and columns or does not support notification.

Remarks

Use the IMAPITable::Advise method to register a table object implemented in the provider for notification callbacks. Whenever a change occurs to the table object, the provider checks to see what event mask bit was set in the ulEventMask parameter and thus what type of change occurred. If a bit is set, then the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.

The call to OnNotify can occur during the call that changes the object, or at any following time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. For a way to turn a call to OnNotify that might happen at an inopportune time into one that is safer to handle, a provider should use the HrThisThreadAdviseSink function.

To provide notifications, the provider implementing Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, it calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMAPITable::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.

After a call to Advise has succeeded and before Unadvise has been called, clients must be prepared for the advise sink object to be released. A client should therefore release its advise sink object after Advise returns unless it has a specific long-term use for it.

Because of the asynchronous behavior of notification, implementations that change table column settings can receive notifications with information organized in a previous column order. For instance, a table row might be returned for a message that has just been deleted from the container. Such a notification is sent when the column setting change has been made and information about it sent but the notification table view has not been updated with that information yet.

For more information on the notification process, see Event Notification in MAPI. For specific information about table notification, see About Table Notifications. For information about using the IMAPISupport methods to support notification, see Supporting Event Notification.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContestTableListCtrl::NotificationOn | MFCMAPI uses the IMAPITable::Advise method to register for notifications to allow the table view to stay current.

See also

Reference

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::CollapseRow

 Copy code hover
[image]

IMAPITable::CollapseRow
See also Send feedback

Published: July 16, 2012

Collapses an expanded table category, removing any lower-level headings and leaf rows belonging to the category from the table view.

C++
HRESULT CollapseRow(
ULONG cbInstanceKey,
LPBYTE pbInstanceKey,
ULONG ulFlags,
ULONG FAR * lpulRowCount
);

Parameters

cbInstanceKey

[in] The count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.

pbInstanceKey

[in] A pointer to the PR_INSTANCE_KEY (PidTagInstanceKey) property that identifies the heading row for the category.

ulFlags

Reserved; must be zero.

lpulRowCount

[out] A pointer to the total number of rows that are being removed from the table view.

Return value

S_OK

The collapse operation has succeeded.

MAPI_E_NOT_FOUND

The row identified by the pbInstanceKey parameter does not exist.

MAPI_E_INVALID_ENTRYID

The row identified by the pbInstanceKey parameter does not exist. This error is an alternative to MAPI_E_NOT_FOUND; service providers can return either one.

Remarks

The IMAPITable::CollapseRow method collapses a table category and removes it from the table view. The rows are collapsed starting at the row identified by the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter. The number of rows that are removed from the view is returned in the contents of the lpulRowCount parameter.

Notifications are never generated for table rows that are removed from a view as the result of a collapse operation.

When a row that is defined by a bookmark is collapsed out of view, the bookmark is moved to point to the next visible row.

For more information about categorized tables, see Sorting and Categorization.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::DoExpandCollapse | MFCMAPI uses the IMAPITable::CollapseRow method to collapse a table category.

See also

Reference

IMAPITable::ExpandRow
IMAPITable::GetCollapseState
IMAPITable::QuerySortOrder
IMAPITable::SetCollapseState
IMAPITable::SortTable
SSortOrderSet
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::CreateBookmark

 Copy code hover
[image]

IMAPITable::CreateBookmark
See also Send feedback

Published: July 16, 2012

Creates a bookmark at the table's current position.

C++
HRESULT CreateBookmark(
BOOKMARK FAR * lpbkPosition
);

Parameters

lpbkPosition

[out] Pointer to the returned 32-bit bookmark value. This bookmark can later be passed in a call to the IMAPITable::SeekRow method.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNABLE_TO_COMPLETE

The requested operation could not be completed.

Remarks

The IMAPITable::CreateBookmark method marks a table position by creating a value called a bookmark. A bookmark can be used to return to the position identified by the bookmark. The bookmarked position is associated with the object at that row in the table.

Bookmarks are not supported on attachment tables, and attachment table implementations of CreateBookmark return MAPI_E_NO_SUPPORT.

Notes to Implementers

Because of the memory expense of maintaining cursor positions with bookmarks, limit the number of bookmarks that you can create. When you reach that number, return MAPI_E_UNABLE_TO_COMPLETE from all subsequent calls to CreateBookmark.

Sometimes a bookmark points to a row that is no longer in the table view. If a caller uses such a bookmark, move the cursor to the next visible row and stop there.

When the caller attempts to use a bookmark that is pointing to a nonvisible row because it has been collapsed, return MAPI_W_POSITION_CHANGED after moving the bookmark. You can reposition the bookmark to the next visible row either at this time or when the collapsing occurs in the SetCollapseState method. If you move the bookmark at the time the row is collapsed, you must retain a bit in the bookmark that indicates exactly when the bookmark was moved: since its last use or if it has never been used since its creation.

Notes to Callers

CreateBookmark allocates memory for the bookmark it creates. Release the resources for the bookmark by calling the IMAPITable::FreeBookmark method.

See also

Reference

IMAPITable::FreeBookmark
IMAPITable::SeekRow
IMAPITable : IUnknown


IMAPITable::ExpandRow

 Copy code hover
[image]

IMAPITable::ExpandRow
See also Send feedback

Published: July 16, 2012

Expands a collapsed table category, adding the leaf or lower-level heading rows belonging to the category to the table view.

C++
HRESULT ExpandRow(
ULONG cbInstanceKey,
LPBYTE pbInstanceKey,
ULONG ulRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows,
ULONG FAR * lpulMoreRows
);

Parameters

cbInstanceKey

[in] The count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.

pbInstanceKey

[in] A pointer to the PR_INSTANCE_KEY (PidTagInstanceKey) property that identifies the heading row for the category.

ulRowCount

[in] The maximum number of rows to return in the lppRows parameter.

ulFlags

Reserved; must be zero.

lppRows

[out] A pointer to an SRowSet structure receiving the first (up to ulRowCount) rows that have been inserted into the table view as a result of the expansion. These rows are inserted after the heading row identified by the pbInstanceKey parameter. The lppRows parameter can be NULL if the ulRowCount parameter is zero.

lpulMoreRows

[out] A pointer to the total number of rows that were added to the table view.

Return value

S_OK

The category was expanded successfully.

MAPI_E_NOT_FOUND

The row identified by the pbInstanceKey parameter does not exist.

Remarks

The IMAPITable::ExpandRow method expands a collapsed table category, adding the leaf or lower-level heading rows that belong to the category to the table view. A limit to the number of rows to be returned in the lppRows parameter can be specified in the ulRowCount parameter. When ulRowCount is set to a value greater than zero and one or more rows are returned in the row set pointed to by lppRows, the position of the bookmark BOOKMARK_CURRENT is moved to the row immediately following the last row in the row set.

When ulRowCount is set to zero, requesting that zero leaf or lower-level heading rows be added to the category, or zero rows are returned because there are no leaf or lower-level heading rows in the category, the position of BOOKMARK_CURRENT is set to the row following the row identified by pbInstanceKey.

Notes to Implementers

Do not generate notifications on rows that are added to a table view due to category expansion.

Notes to Callers

The number of rows in the row set pointed to by the lppRows parameter might not equal the number of rows that were actually added to the table, the entire set of leaf or lower-level heading rows for the category. Errors can occur, such as insufficient memory, or the number of rows in the category exceeding the number specified in ulRowCount parameter. In either case, BOOKMARK_CURRENT will be positioned at the last row returned. To immediately retrieve the rest of the rows in the category, call IMAPITable::QueryRows.

Do not expect to receive a table notification when a category changes its state. You can maintain a local cache of rows that can be updated with every ExpandRow or CollapseRow call.

For more information about categorized tables, see Sorting and Categorization.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::DoExpandCollapse | MFCMAPI uses the IMAPITable::ExpandRow method to expand a collapsed table category.

See also

Reference

IMAPITable::CollapseRow
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::FindRow

 Copy code hover
[image]

IMAPITable::FindRow
See also Send feedback

Published: July 16, 2012

Finds the next row in a table that matches specific search criteria and moves the cursor to that row.

C++
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);

Parameters

lpRestriction

[in] A pointer to an SRestriction structure that describes the search criteria.

BkOrigin

[in] A bookmark identifying the row where FindRow should begin its search. A bookmark can be created using the IMAPITable::CreateBookmark method, or one of the following predefined values can be passed.

BOOKMARK_BEGINNING

Searches from the beginning of the table.

BOOKMARK_CURRENT

Searches from the row in the table where the cursor is located.

BOOKMARK_END

Searches from the end of the table.

ulFlags

[in] A bitmask of flags that controls the direction of the search. The following flag can be set:

DIR_BACKWARD

Searches backward from the row identified by the bookmark.

Return value

S_OK

The find operation was successful.

MAPI_E_INVALID_BOOKMARK

The bookmark in the BkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.

MAPI_E_NOT_FOUND

No rows were found that matched the restriction.

MAPI_W_POSITION_CHANGED

The call succeeded, but the bookmark used in the operation is no longer set at the same row as when it was last used; if the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPITable::FindRow method locates the first row in the table to match a set of search criteria described in the SRestriction structure pointed to by the lpRestriction parameter.

Usually, FindRow searches forward from the specified bookmark. The caller can set the search to move backward from the bookmark by setting the DIR_BACKWARD flag in the ulFlags parameter. Searching forward starts from the current bookmark; searching backward starts from the row prior to the bookmark. The end position of the search is just before the first row found that satisfied the restriction.

If the row pointed to by the bookmark in the BkOrigin parameter no longer exists in the table and the table cannot establish a new position for the bookmark, FindRow returns MAPI_E_INVALID_BOOKMARK. If the row pointed to by BkOrigin no longer exists and the table is able to establish a new position for the bookmark, FindRow returns MAPI_W_POSITION_CHANGED.

If the bookmark passed in BkOrigin is either BOOKMARK_BEGINNING or BOOKMARK_END, FindRow returns MAPI_E_NOT_FOUND if no matching row is found. If the bookmark used in BkOrigin is BOOKMARK_CURRENT, FindRow can return MAPI_W_POSITION_CHANGED but not MAPI_E_INVALID_BOOKMARK because there is always a current cursor position.

The PR_INSTANCE_KEY (PidTagInstanceKey) property column is required for all tables, and all implementations of FindRow are required to support calls seeking a row based on PR_INSTANCE_KEY.

Notes to Implementers

The type of prefix searching performed by FindRow is only useful when the search follows the same direction as the table organization. In order to achieve the required behavior, the comparison function implied by the RELOP_GE passed in the property restriction structure should be the same comparison function on which the table sort order is based.

Notes to Callers

You can use FindRow to support scrolling based on strings typed in by the user, especially in list boxes within address dialog boxes. In this type of scrolling, users enter progressively longer prefixes of a desired string value, and you can periodically issue a FindRow call to jump to the first row that matches the prefix. Which direction the cursor jumps depends on which direction the search is set to run.

To use FindRow, a bookmark must be set. The string search can originate from any bookmark, including from the preset bookmarks indicating the current position and the beginning and end of the table. If there are a large number of rows in the table, the search operation can be slow.

Use a restriction to find a string prefix for scrolling as follows. For forward searching on a column sorted in ascending order and for backward searching on a column sorted in descending order, pass a property restriction structure in the lpRestriction parameter with the relation RELOP_GE and the appropriate property tag and prefix, using the format tagGE prefix.

For more information about using restriction structures to specify a filter, see About Restrictions.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | DwThreadFuncLoadTable | MFCMAPI uses the IMAPITable::FindRow method to find rows which match a restriction.

See also

Reference

IMAPITable::CreateBookmark
SPropertyRestriction
SRestriction
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::FreeBookmark

 Copy code hover
[image]

IMAPITable::FreeBookmark
See also Send feedback

Published: July 16, 2012

Releases the memory associated with a bookmark.

C++
HRESULT FreeBookmark(
BOOKMARK bkPosition
);

Parameters

bkPosition

[in] The bookmark to be freed, created by calling the IMAPITable::CreateBookmark method.

Return value

S_OK

The bookmark was successfully freed.

MAPI_E_INVALID_BOOKMARK

The specified bookmark does not exist.

Remarks

The IMAPITable::FreeBookmark method releases a bookmark that is no longer needed. The bookmark is no longer valid after this call. Whenever a table is released from memory, all of its associated bookmarks are also released.

Notes to Implementers

If the caller passes one of the three predefined bookmarks in the bkPosition parameter, ignore the request and return S_OK.

See also

Reference

IMAPITable::CreateBookmark
IMAPITable : IUnknown


IMAPITable::GetCollapseState

 Copy code hover
[image]

IMAPITable::GetCollapseState
See also Send feedback

Published: July 16, 2012

Returns the data that is needed to rebuild the current collapsed or expanded state of a categorized table.

C++
HRESULT GetCollapseState(
ULONG ulFlags,
ULONG cbInstanceKey,
LPBYTE lpbInstanceKey,
ULONG FAR * lpcbCollapseState,
LPBYTE FAR * lppbCollapseState
);

Parameters

ulFlags

Reserved; must be zero.

cbInstanceKey

[in] The count of bytes in the instance key pointed to by the lpbInstanceKey parameter.

lpbInstanceKey

[in] A pointer to the PR_INSTANCE_KEY (PidTagInstanceKey) property of the row at which the current collapsed or expanded state should be rebuilt. The lpbInstanceKey parameter cannot be NULL.

lpcbCollapseState

[out] A pointer to the count of structures pointed to by the lppbCollapseState parameter.

lppbCollapseState

[out] A pointer to a pointer to structures that contain data that describes the current table view.

Return value

S_OK

The state for the categorized table was successfully saved.

MAPI_E_BUSY

Another operation is in progress that prevents the operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table does not support categorization and expanded and collapsed views.

Remarks

The IMAPITable::GetCollapseState method works with the IMAPITable::SetCollapseState method to change the user's view of a categorized table. GetCollapseState saves the data that is needed for SetCollapseState to use to rebuild the appropriate views of the categories of a categorized table. Service providers determine the data to be saved. However, most service providers implementing GetCollapseState save the following:

  • The sort keys (standard columns and category columns).

  • Information about the row that the instance key represents.

  • Information to restore the collapsed and expanded categories of the table.

For more information about categorized tables, see Sorting and Categorization.

Notes to Implementers

Store the current state of all nodes of a table in the lppbCollapseState parameter.

Notes to Callers

Always call GetCollapseState before you call SetCollapseState.

See also

Reference

IMAPITable::SetCollapseState
IMAPITable : IUnknown


IMAPITable::GetLastError

 Copy code hover
[image]

IMAPITable::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure containing information about the previous error on the table.

C++
HRESULT GetLastError(
HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] HRESULT containing the error generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if a MAPIERROR structure with appropriate information cannot be provided.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

The IMAPITable::GetLastError method returns detailed information, if available, about a prior method call that failed. This information can be displayed in a message or a dialog box.

Notes to Callers

Call GetLastError whenever you need to display information about an error to the user.

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter if the table object supplies one only if GetLastError returns S_OK. Sometimes the table implementation cannot determine what the last error was or has nothing more to report about the error. In this situation, the pointer at lppMAPIError is set to NULL.

To release all the memory allocated for the MAPIERROR structure, call the MAPIFreeBuffer function.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPITable : IUnknown


IMAPITable::GetRowCount

 Copy code hover
[image]

IMAPITable::GetRowCount
See also Send feedback

Published: July 16, 2012

Returns the total number of rows in the table.

C++
HRESULT GetRowCount(
ULONG ulFlags,
ULONG FAR * lpulCount
);

Parameters

ulFlags

Reserved; must be zero.

lpulCount

[out] Pointer to the number of rows in the table.

Return value

S_OK

The row count was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the row count retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table cannot calculate the number of rows.

MAPI_W_APPROX_COUNT

The call succeeded, but an approximate row count was returned because the exact row count could not be determined possibly due to memory constraints. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

The IMAPITable::GetRowCount method retrieves the total number of rows in a table.

Notes to Implementers

If you cannot determine the table's exact row count, return MAPI_W_APPROX_COUNT and an approximate row count in the contents of the lpulCount parameter.

Notes to Callers

Use GetRowCount to find out how many rows a table holds before making a call to the IMAPITable::QueryRows method to retrieve the data. If there are less than twenty rows in the table, it is safe to call QueryPosition to retrieve the whole table. If there are more than twenty rows in the table, consider making multiple calls to QueryPosition and limit the number of rows retrieved in each call.

Some tables do not support GetRowCount and return MAPI_E_NO_SUPPORT. If GetRowCount is not supported, an alternative might be to call IMAPITable::QueryPosition. With the results from QueryPosition, you can determine the relationship between the current row and last row.

When GetRowCount returns MAPI_E_BUSY because it is temporarily unable to retrieve a row count, call the IMAPITable::WaitForCompletion method. When WaitForCompletion returns, retry the call to GetRowCount. Another way to detect whether an asynchronous operation is in progress is to call the IMAPITable::GetStatus method and check the contents of the lpulTableState parameter.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | CopyFolderContents | MFCMAPI uses the IMAPITable::GetRowCount method to determine how many rows are in the source table so memory can be allocated to perform the copy.

See also

Reference

IMAPITable::GetStatus
IMAPITable::QueryPosition
IMAPITable::QueryRows
IMAPITable::WaitForCompletion
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::GetStatus

 Copy code hover
[image]

IMAPITable::GetStatus
See also Send feedback

Published: July 16, 2012

Returns the table's status and type.

C++
HRESULT GetStatus(
ULONG FAR * lpulTableStatus,
ULONG FAR * lpulTableType
);

Parameters

lpulTableStatus

[out] Pointer to a value indicating the status of the table. One of the following values can be returned:

TBLSTAT_COMPLETE

No operations are in progress.

TBLSTAT_QCHANGED

The contents of the table have expectantly changed. This status value is not returned for changes that result from sort or restriction operations.

TBLSTAT_RESTRICT_ERROR

An error occurred during an IMAPITable::Restrict operation.

TBLSTAT_RESTRICTING

An IMAPITable::Restrict operation is in progress.

TBLSTAT_SETCOL_ERROR

An error occurred during an IMAPITable::SetColumns operation.

TBLSTAT_SETTING_COLS

An IMAPITable::SetColumns operation is in progress.

TBLSTAT_SORT_ERROR

An error occurred during an IMAPITable::SortTable operation.

TBLSTAT_SORTING

An IMAPITable::SortTable operation is in progress.

lpulTableType

[out] Pointer to a value that indicates the table's type. One of the following three table types can be returned:

TBLTYPE_DYNAMIC

The table's contents are dynamic; the rows and column values can change as the underlying data changes.

TBLTYPE_KEYSET

The rows within the table are fixed, but the values of the columns within these rows are dynamic and can change as the underlying data changes.

TBLTYPE_SNAPSHOT

The table is static, and its contents do not change when the underlying data changes.

Return value

S_OK

The table's status was successfully returned.

Remarks

The IMAPTable::GetStatus method retrieves information about a table's type and current status.

Notes to Callers

You can use GetStatus in conjunction with three other IMAPITable methods to monitor the status of those operations and determine the effect on the table. Call GetStatus after making one of the following IMAPITable calls:

  • IMAPITable::Restrict to set a restriction.

  • IMAPITable::SortTable to establish a sort order.

  • IMAPITable::SetColumns to define a column set.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::GetStatus | MFCMAPI uses the IMAPITable::GetStatus method to report the status of a table.

See also

Reference

IMAPITable::Restrict
IMAPITable::SetColumns
IMAPITable::SortTable
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::QueryColumns

 Copy code hover
[image]

IMAPITable::QueryColumns
See also Send feedback

Published: July 16, 2012

Returns a list of columns for the table.

C++
HRESULT QueryColumns(
ULONG ulFlags,
LPSPropTagArray FAR * lpPropTagArray
);

Parameters

ulFlags

[in] Bitmask of flags that indicates which column set should be returned. The following flag can be set:

TBL_ALL_COLUMNS

The table should return all available columns.

lpPropTagArray

[out] Pointer to an SPropTagArray structure containing the property tags for the column set.

Return value

S_OK

The column set was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the column set retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The IMAPITable::QueryColumns method can be called to retrieve:

  • The default column set for a table.

  • The current column set for a table, as established by a call to the IMAPITable::SetColumns method.

  • The complete column set for a table, the columns that are available, but not necessarily part of the current set.

Notes to Callers

If you do not set the TBL_ALL_COLUMNS flag, IMAPITable::QueryColumns returns either a table's default or current column set, depending on whether the table has been affected by a call to IMAPITable::SetColumns. SetColumns changes the order and selection of columns in a table's column set.

If you set the TBL_ALL_COLUMNS flag, QueryColumns returns all of the columns that are capable of being in the table's column set.

Free the memory for the property tag array pointed to by the lpPropTagArray parameter by calling the MAPIFreeBuffer function.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::DoSetColumns | MFCMAPI uses the IMAPITable::QueryColumns method to retrieve the current column set for a table so the user can edit it.

See also

Reference

IMAPITable::SetColumns
MAPIFreeBuffer
SPropTagArray
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::QueryPosition

 Copy code hover
[image]

IMAPITable::QueryPosition
See also Send feedback

Published: July 16, 2012

Retrieves the current table row position of the cursor, based on a fractional value.

C++
HRESULT QueryPosition(
ULONG FAR * lpulRow,
ULONG FAR * lpulNumerator,
ULONG FAR * lpulDenominator
);

Parameters

lpulRow

[out] Pointer to the number of the current row. The row number is zero-based; the first row in the table is zero.

lpulNumerator

[out] Pointer to the numerator for the fraction identifying the table position.

lpulDenominator

[out] Pointer to the denominator for the fraction identifying the table position. The lpulDenominator parameter cannot be zero.

Return value

S_OK

The method returned valid values in lpulRow, lpulNumerator, and lpulDenominator.

Remarks

The IMAPITable::QueryPosition method determines the current row position and returns both the number of the current row and a fractional value indicating its relative position to the end of the table. MAPI defines the current row as the next row to be read.

Notes to Implementers

You do not need to return the exact number of rows in the table for the lpulDenominator parameter; it can be an approximation.

If you cannot determine the current row, return a value of 0xFFFFFFFF in lpulRow.

Notes to Callers

You can use QueryPosition to position a scroll box in a scroll bar. For example, in a table containing 100 rows, if QueryPosition returns a value of 75 in the lpulNumerator parameter, 100 in the lpulDenominator parameter, and 75 in the lpulRow parameter, you can position the scroll box 3/4 of the way across the scroll bar.

Do not rely on the value in lpulDenominator being the number of rows in the table. QueryPosition cannot always identify the exact row that the cursor is positioned on.

A call to QueryPosition might involve large amounts of memory, particularly for large categorized tables. If the lpulRow parameter is set to 0xFFFFFFFF, too much memory was required for QueryPosition to determine the current row. Call the IMAPITable::SeekRowApprox method to position the table to the row identified by the lpulNumerator and lpulDenominator parameters. However, do not always expect SeekRowApprox to establish as the current position the same row QueryPosition would have if memory had not been a factor.

See also

Reference

IMAPITable::SeekRowApprox
IMAPITable : IUnknown


IMAPITable::QueryRows

 Copy code hover
[image]

IMAPITable::QueryRows
See also Send feedback

Published: July 16, 2012

Returns one or more rows from a table, beginning at the current cursor position.

C++
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);

Parameters

lRowCount

[in] Maximum number of rows to be returned.

ulFlags

[in] Bitmask of flags that control how rows are returned. The following flag can be set:

TBL_NOADVANCE

Prevents the cursor from advancing as a result of the row retrieval. If the TBL_NOADVANCE flag is set, the cursor points to the first row returned. If the TBL_NOADVANCE flag is not set, the cursor points to the row following the last row returned.

lppRows

[out] Pointer to a pointer to an SRowSet structure holding the table rows.

Return value

S_OK

The rows were successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_INVALID_PARAMETER

The IRowCount parameter is set to zero.

Remarks

The IMAPITable::QueryRows method gets one or more rows of data from a table. The value of the IRowCount parameter affects the starting point for the retrieval. If IRowCount is positive, rows are read in a forward direction, starting at the current position. If IRowCount is negative, QueryRows resets the starting point by moving backward the indicated number of rows. After the cursor is reset, rows are read in forward order.

The cRows member in the SRowSet structure pointed to by the lppRows parameter indicates the number of rows returned. If zero rows are returned:

  • The cursor was already positioned at the beginning of the table and the value of IRowCount is negative. -Or-

  • The cursor was already positioned at the end of the table and the value of IRowCount is positive.

The number of columns and their ordering is the same for each row. If a property does not exist for a row or there is an error reading a property, the SPropValue structure for the property in the row contains the following values:

  • PT_ERROR for the property type in the ulPropTag member.

  • MAPI_E_NOT_FOUND for the Value member.

Memory used for the SPropValue structures in the row set pointed to by the lppRows parameter must be separately allocated and freed for each row. Use MAPIFreeBuffer to free the property value structures and to free the row set. When a call to QueryRows returns zero, however, indicating the beginning or end of the table, only the SRowSet structure itself needs to be freed. For more information about how to allocate and free memory in an SRowSet structure, see Managing Memory for ADRLIST and SRowSet Structures.

The rows that are returned and the order in which they are returned depend on whether or not successful calls have been made to IMAPITable::Restrict and IMAPITable::SortTable. Restrict filters rows from the view, causing QueryRows to return only the rows that match the criteria specified in the restriction. SortTable establishes a standard or categorized sort order, affecting the sequence of rows returned by QueryRows. The returned rows are in the order specified in the SSortOrderSet structure passed to SortTable.

The columns returned for each row and the order in which they are returned depend on whether or not a successful call has been made to IMAPITable::SetColumns. SetColumns establishes a column set, specifying the properties to be included in columns in the table and the order in which they should be included. If a SetColumns call has been made, the particular columns in each row and the order of those columns match the column set specified in the call. If no SetColumns call has been made, the table returns its default column set.

If none of these calls has been made, QueryRows returns all of the rows in the table. Each row contains the default column set in default order.

When the column set established in a call to IMAPITable::SetColumns includes columns set to PR_NULL, the SPropValue array within the row set returned in lppRows will contain empty slots.

Notes to Implementers

You can allow a caller to request an unsupported column to be included in the column set. When this occurs, place PT_ERROR in the property type portion of the property tag and MAPI_E_NOT_FOUND in the property value for the unsupported column.

Treat the row count as a request rather than a requirement. You can return anywhere from zero rows, if there are no rows in the direction of the query, to the number requested.

Return only the rows that the user will see when rows are requested from a categorized table view, allowing the caller to make valid assumptions about the scope of the data and avoid extra work.

Notes to Callers

Usually you will end up with as many rows as you have specified in the lRowCount parameter. However, when memory or implementation limits are an issue or when the operation reaches the beginning or end of the table prematurely, QueryRows will return less rows than requested.

If QueryRows returns MAPI_E_BUSY, call the IMAPITable::WaitForCompletion method and retry the call to QueryRows when the asynchronous operation is complete.

When calling QueryRows, be aware that the timing of asynchronous notifications can potentially cause the row set that you get back from QueryRows not to accurately represent the underlying data. For example, a call to QueryRows to a folder's contents table following the deletion of a message but prior to the receipt of the corresponding notification will cause the deleted row to be returned in the row set. Always wait for a notification to arrive before updating the user's view of the data.

For more information about retrieving rows from tables, see Retrieving Data from Table Rows.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | DwThreadFuncLoadTable | MFCMAPI uses the IMAPITable::QueryRows method to retrieve rows in the table to load into the view.

See also

Reference

ADRENTRY
FreeProws
HrQueryAllRows
IMAPIProp::GetProps
IMAPITable::SetColumns
IMAPITable::WaitForCompletion
MAPIFreeBuffer
SRow
SRowSet
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::QuerySortOrder

 Copy code hover
[image]

IMAPITable::QuerySortOrder
See also Send feedback

Published: July 16, 2012

Retrieves the current sort order for a table.

C++
HRESULT QuerySortOrder(
LPSSortOrderSet FAR * lppSortCriteria
);

Parameters

lppSortCriteria

[out] Pointer to a pointer to the SSortOrderSet structure holding the current sort order.

Return value

S_OK

The current sort order was successfully returned.

MAPI_E_BUSY

Another operation is in progress that prevents the sort order retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The IMAPITable::QuerySortOrder method retrieves the current sort order for a table. Sort orders are described with an SSortOrderSet structure.

  • The cSorts member of the SSortOrderSet structure can be set to zero if:

  • The table is unsorted.

  • There is no information about how the table is sorted.

  • The SSortOrderSet structure is not appropriate for describing the sort order.

Notes to Implementers

If a call is made to your IMAPITable::SortTable method with an SSortOrderSet structure containing zero columns in the sort key, remove the current sort order and apply the default order, if there is one. In subsequent calls to QuerySortOrder, you can choose whether to return zero or more columns for the sort key. You can return more columns than are in the present view.

For more information about sorting, see Sorting and Categorization.

See also

Reference

IMAPITable::SortTable
MAPIFreeBuffer
SSortOrderSet
IMAPITable : IUnknown


IMAPITable::Restrict

 Copy code hover
[image]

IMAPITable::Restrict
See also Send feedback

Published: July 16, 2012

Applies a filter to a table, reducing the row set to only those rows matching the specified criteria.

C++
HRESULT Restrict(
LPSRestriction lpRestriction,
ULONG ulFlags
);

Parameters

lpRestriction

[in] Pointer to an SRestriction structure defining the conditions of the filter. Passing NULL in the lpRestriction parameter removes the current filter.

ulFlags

[in] Bitmask of flags that controls the timing of the restriction operation. The following flags can be set:

TBL_ASYNC

Starts the operation asynchronously and returns before the operation completes.

TBL_BATCH

Defers evaluation of the filter until the data in the table is required.

Return value

S_OK

The filter was successfully applied.

MAPI_E_BUSY

Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_TOO_COMPLEX

The table cannot perform the operation because the particular filter pointed to by the lpRestriction parameter is too complicated.

Remarks

The IMAPITable::Restrict method establishes a restriction, or filter, on a table. If there is a previous restriction, it is discarded and the new one applied. Applying a restriction has no affect on the underlying data of a table; it simply alters the view by limiting the rows that can be retrieved to rows containing data that satisfy the restriction.

There are several different types of restrictions, each described with a different structure. The SRestriction structure contains two members: a value that indicates the type of restriction and the specific structure applicable for that type.

Notifications for table rows that are hidden from view by calls to Restrict are never generated.

A property restriction on a multivalued property works like a restriction on a single-valued property. A multivalued property to be used in a property restriction must have the MVI_FLAG flag set. If it doesn't have this flag set, it is treated as a totally ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality. Equality is returned only if the columns compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.

For more information about restrictions, see About Restrictions.

Note Note

If you create dynamic queries to search for data on the server, use the FindRow method instead of using the Restrict method and the QueryRows method together. The Restrict method creates a cached view that is used to evaluate all messages added to or modified in the base folder. If a client application uses the Restrict method for each dynamic query, a cached view will be created for each query.

Notes to Callers

To discard the current restriction without creating a new one, pass NULL in lpRestriction.

If another asynchronous table call is in progress, causing Restrict to return MAPI_E_BUSY, you can call IMAPITable::Abort to stop the call.

Restrict operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, Restrict postpones the evaluation of the restriction unless you request the data. If the TBL_ASYNC flag is set, Restrictoperates asynchronously, potentially returning before the completion of the operation.

All bookmarks for a table are discarded when a call to Restrict is made, and BOOKMARK_CURRENT, the current cursor position, is set to the beginning of the table.

If you attempt to impose a property restriction on a property that is not in the table's column set, the results are undefined. Whenever you are unsure as to whether a property is supported in a table, combine the property restriction with an exists restriction. The exists restriction checks for the existence of the property before attempting to impose the property restriction.

Do not expect to receive a table notification on a row that has been filtered from a table due to a restriction.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::ApplyRestriction | MFCMAPI uses the IMAPITable::Restrict method to set a restriction on a table.

See also

Reference

IMAPITable::Abort
IMAPITable::FindRow
IMAPITable::GetRowCount
IMAPITable::QueryRows
SPropertyRestriction
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::SeekRow

 Copy code hover
[image]

IMAPITable::SeekRow
See also Send feedback

Published: July 16, 2012

Moves the cursor to a specific position in the table.

C++
HRESULT SeekRow(
BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
);

Parameters

bkOrigin

[in] The bookmark identifying the starting position for the seek operation. A bookmark can be created using the IMAPITable::CreateBookmark method, or one of the following predefined values can be passed.

BOOKMARK_BEGINNING

Starts the seek operation from the beginning of the table.

BOOKMARK_CURRENT

Starts the seek operation from the row in the table where the cursor is located.

BOOKMARK_END

Starts the seek operation from the end of the table.

lRowCount

[in] The signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.

lplRowsSought

[out] If lRowCount is a valid pointer on input, lplRowsSought points to the number of rows that were processed in the seek operation, the sign of which indicates the direction of search, forward or backward. If lRowCount is negative, then lplRowsSought is negative.

Return value

S_OK

The seek operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the row-seeking operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_INVALID_BOOKMARK

The bookmark specified in the bkOrigin parameter is invalid because it was removed or because it is beyond the last row requested.

MAPI_W_POSITION_CHANGED

The call succeeded, but the bookmark specified in the bkOrigin parameter is no longer set at the same row as it was when it was last used. If the bookmark has not been used, it is no longer in the same position as it was when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPITable::SeekRow method establishes a new BOOKMARK_CURRENT position for the cursor. The lRowCount parameter indicates the number of rows that the cursor moves and the direction of movement.

If the resulting position is beyond the last row of the table, the cursor is positioned after the last row. If the resulting position is before the first row of the table, the cursor is positioned at the beginning of the first row.

Notes to Implementers

If the row pointed to by bkOrigin no longer exists in the table and you cannot establish a new position for the bookmark, return MAPI_E_INVALID_BOOKMARK. If the row pointed to by bkOrigin no longer exists and you can establish a new position for the bookmark, return MAPI_W_POSITION_CHANGED.

A bookmark pointing to a row that is collapsed out of the table view can still be used. If the caller attempts to move the cursor to such a bookmark, move the cursor to the next visible row and return MAPI_W_POSITION_CHANGED.

You can move bookmarks for positions collapsed out of view, either at the time of use or at the time that the row is collapsed. If a bookmark is moved at the time that the row is collapsed, keep a bit in the bookmark that indicates whether the bookmark has moved since its last use or, if it has never been used, since its creation.

Notes to Callers

To indicate a backward move for SeekRow, pass a negative value in lRowCount. To search to the beginning of the table, pass zero in lRowCount and the value BOOKMARK_BEGINNING in bkOrigin.

If there are lots of rows in the table, the SeekRow operation can be slow. Performance can also be affected if you require a row count to be returned in the contents of the lplRowsSought parameter.

SeekRow returns the number of rows actually searched through, positive or negative, in the variable pointed to by lRowCount. In ordinary operation, it should return the same value for lplRowsSought as passed in for lRowCount, unless the search reached the beginning or end of the table.

Do not set lRowCount to a number greater than 50. To seek through a larger number of rows, use the IMAPITable::SeekRowApprox method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProcessor.cpp | CMAPIProcessor::ProcessMailboxTable | MFCMAPI uses the IMAPITable::SeekRow method to locate the beginning of the table before processing.

See also

Reference

IMAPITable::CreateBookmark
IMAPITable::FindRow
IMAPITable::QueryRows
IMAPITable::SeekRowApprox
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::SeekRowApprox

 Copy code hover
[image]

IMAPITable::SeekRowApprox
See also Send feedback

Published: July 16, 2012

Moves the cursor to an approximate fractional position in the table.

C++
HRESULT SeekRowApprox(
ULONG ulNumerator,
ULONG ulDenominator
);

Parameters

ulNumerator

[in] Pointer to the numerator of the fraction representing the table position. If the ulNumerator parameter is zero, the cursor is positioned at the beginning of the table regardless of the denominator value. If ulNumerator is equal to the ulDenominator parameter, the cursor is positioned after the last table row.

ulDenominator

[in] Pointer to the denominator of the fraction representing the table position. The ulDenominator parameter cannot be zero.

Return value

S_OK

The seek operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The cursor position in a table after a call to the IMAPITable::SeekRowApprox method is heuristically the fraction and might not be exact. For example, certain providers might implement a table on top of a binary tree, treating the table's halfway point as the top of the tree for performance reasons. If the tree is not balanced, then the halfway point used might not be exactly halfway through the table.

Notes to Callers

Call SeekRowApprox to provide the data for a scroll bar implementation. For example, if the user positions the scroll box 2/3 down the scroll bar, you can model that action by calling SeekRowApprox and passing in an equivalent fractional value using ulNumerator and ulDenominator. The SeekRowApprox search is always absolute from the beginning of the table. To move to the end of the table, the values in ulNumerator and ulDenominator must be the same.

Use whatever number scheme is appropriate. That is, to seek to a position halfway through the table, you can specify 1/2, 10/20, or 50/100.

See also

Reference

IMAPITable : IUnknown


IMAPITable::SetCollapseState

 Copy code hover
[image]

IMAPITable::SetCollapseState
See also Send feedback

Published: July 16, 2012

Rebuilds the current expanded or collapsed state of a categorized table using data that was saved by a prior call to the IMAPITable::GetCollapseState method.

C++
HRESULT SetCollapseState(
ULONG ulFlags,
ULONG cbCollapseState,
LPBYTE pbCollapseState,
BOOKMARK FAR * lpbkLocation
);

Parameters

ulFlags

Reserved; must be zero.

cbCollapseState

[in] Count of bytes in the structure pointed to by the pbCollapseState parameter.

pbCollapseState

[in] Pointer to the structures containing the data needed to rebuild the table view.

lpbkLocation

[out] Pointer to a bookmark identifying the row in the table at which the collapsed or expanded state should be rebuilt. This bookmark and the instance key passed in the lpbInstanceKey parameter in the call to IMAPITable::GetCollapseState identify the same row.

Return value

S_OK

The state of the categorized table was successfully rebuilt.

MAPI_E_BUSY

Another operation is in progress that prevents the operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_UNABLE_TO_COMPLETE

The table could not finish rebuilding the collapsed or expanded view.

Remarks

The IMAPITable::SetCollapseState method reestablishes the expanded or collapsed state of the table view. SetCollapseState and GetCollapseState work together as follows:

  1. When the state of a categorized table is about to change, IMAPITable::GetCollapseState is called to save all of the data pertaining to the state prior to the change.

  2. To restore the view of the table to its saved state, SetCollapseState is called. The data saved by GetCollapseState is passed to SetCollapseState. SetCollapseState is able to use that data to restore the state.

  3. SetCollapseState returns as an output parameter a bookmark that identifies the same row as the instance key passed as input to GetCollapseState.

For more information about categorized tables, see Sorting and Categorization.

Notes to Implementers

You are responsible for verifying that the sort order and restrictions are exactly the same as they were at the time of the GetCollapseState call. If a change has been made, SetCollapseState should not be called because the results can be unpredictable. This can happen if, for example, a client calls GetCollapseState and then SortTable to change the sort key before calling SetCollapseState. To be safe, check that the saved data is still valid before proceeding with the restoration.

Notes to Callers

To call SetCollapseState, you must have previously called GetCollapseState. The sort order establishing the categories should be the same for both methods. If the sort orders differ, the results of the SetCollapseState operation are unpredictable.

See also

Reference

IMAPITable::CreateBookmark
IMAPITable::FreeBookmark
IMAPITable::GetCollapseState
IMAPITable : IUnknown


IMAPITable::SetColumns

 Copy code hover
[image]

IMAPITable::SetColumns
See also Send feedback

Published: July 16, 2012

Defines the particular properties and order of properties to appear as columns in the table.

C++
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);

Parameters

lpPropTagArray

[in] Pointer to an array of property tags identifying properties to be included as columns in the table. The property type portion of each tag can be set to a valid type or to PR_NULL to reserve space for subsequent additions. The lpPropTagArray parameter cannot be set to NULL; every table must have at least one column.

ulFlags

[in] Bitmask of flags that controls the return of an asynchronous call to SetColumns, for example when SetColumns is used in notification. The following flags can be set:

TBL_ASYNC

Requests that the column setting operation be performed asynchronously causing SetColumns to potentially return before the operation has fully completed.

TBL_BATCH

Permits the table to postpone the column setting operation until the data is actually required.

Return value

S_OK

The column setting operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the column setting operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The column set of a table is the group of properties that make up the columns for the rows in the table. There is a default column set for each type of table. The default column set is made up of the properties that the table implementer automatically includes. Table users can alter this default set by calling the IMAPITable::SetColumns method. They can request that other columns be added to the default set if the table implementer supports them that columns be removed, or that the order of columns be changed. SetColumns specifies the columns that are returned with each row and the order of these columns within the row.

The success of the SetColumns operation is apparent only after a subsequent call has been made to retrieve the data of the table. It is then that any errors are reported.

Notes to Implementers

Some providers allow a SetColumns call to order only table columns that are part of the available columns for a table view. Other providers allow a SetColumns call to order all table columns, including those containing properties not in the original column set.

When TBL_BATCH is set for asynchronous operations, providers should return a property type of PT_ERROR and a property value of NULL for columns that are not supported.

You do not need to respond to the TBL_ASYNC flag requesting that the operation be asynchronous. If you do not support asynchronous column set definition, perform the operation synchronously. If you can support the TBL_ASYNC flag and another asynchronous operation is still in progress, return MAPI_E_BUSY. Otherwise, return S_OK regardless of whether or not you support all of the properties included in the property tag array. Errors resulting from unsupported properties should be returned from IMAPITable methods that retrieve data, such as QueryRows.

Do not generate notifications for table rows that are hidden from view by calls to Restrict.

When sending table notifications, the order of the properties in the row member of the TABLE_NOTIFICATION structure and the order specified by the most recent SetColumns call must be the same as of the time that the notification request was sent.

Another flag, TBL_BATCH, allows callers to specify that the table implementer can defer evaluating the results of the operation until a later time. Whenever possible, callers should set this flag because batched operation improves performance.

It is often convenient for callers to reserve some columns in the retrieved row set for values to be added later. Callers do this by placing PR_NULL (PidTagNull) at the desired positions in the property tag array passed to SetColumns; the table will then pass back PR_NULL at those positions in all rows retrieved with QueryRows.

Notes to Callers

When building the property tag array for the lpPropTagArray parameter, order the tags in the order that you want the columns to appear in the table view.

You can specify multivalued properties to be included in the column set by applying the multivalued instance flag, or MVI_FLAG constant, to the property tag. Set this flag by passing the property tag for the single-valued version of the property as a parameter to the MVI_PROP macro as follows:

Copy code Copy code
MVI_PROP(ulPropTag)

The MVI_PROP macro will set MVI_FLAG for the property, turning the tag into a multivalued tag. If you erroneously try to call MVI_PROP on a single-valued property, MAPI will ignore the call and leave the property tag unchanged.

You can include property tags set to PR_NULL in the property tag array to reserve space in the column set. Reserving space allows you to add to a column set without having to allocate a new property tag array.

When your call to SetColumns causes a change to the order of a table's columns and one or more of these columns represent a multivalued property, it is possible for the number of rows in the table to increase. If this occurs, all of the bookmarks for the table are discarded. For more information about how multivalued columns affect tables, see Working with Multivalued Columns.

Setting columns is by default a synchronous operation. However, you can allow the table to postpone the operation until such time as the data is needed by setting the TBL_BATCH flag. Setting this flag can improve performance. Another flag, TBL_ASYNC, makes the operation asynchronous, allowing SetColumns to return before the operation is complete. To determine when completion occurs, call IMAPITable::GetStatus.

If a call to SetColumns returns MAPI_E_BUSY, indicating that another operation is preventing your operation from starting, you can call IMAPITable::Abort to stop the operation in progress.

You can also call HrAddColumnsEx to change a column set. The difference between HrAddColumnsEx and IMAPITable::SetColumns is that HrAddColumnsEx is less flexible; it can only add columns. The additional columns are placed at the beginning of the column set; all existing columns appear following these columns.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::DoSetColumns | MFCMAPI uses the IMAPITable::SetColumns method to set the desired columns for the table.

See also

Reference

HrQueryAllRows
IMAPITable::Abort
IMAPITable::GetRowCount
IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::Restrict
IMAPITable::SortTable
SPropTagArray
SPropValue
SRowSet
TABLE_NOTIFICATION
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::SortTable

 Copy code hover
[image]

IMAPITable::SortTable
See also Send feedback

Published: July 16, 2012

The IMAPITable::SortTable method orders the rows of the table, depending on sort criteria.

C++
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);

Parameters

lpSortCriteria

[in] Pointer to an SSortOrderSet structure that contains the sort criteria to apply. Passing an SSortOrderSet structure that contains zero columns indicates that the table does not have to be sorted in any particular order.

ulFlags

[in] Bitmask of flags that controls the timing of the IMAPITable::SortTable operation. The following flags can be set:

TBL_ASYNC

Starts the operation asynchronously and returns before the operation is complete.

TBL_BATCH

Defers the completion of the sort until the data in the table is required.

Return value

S_OK

The sort operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the sort operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table does not support the type of sorting requested.

MAPI_E_TOO_COMPLEX

The table cannot perform the operation because the particular sort criteria pointed to by the lpSortCriteria parameter is too complex. SortTable can return MAPI_E_TOO_COMPLEX under the following conditions.

  • A sort operation is requested for a property column that the implementation cannot sort.

  • The implementation does not support the sort order requested in the ulOrder member of the SSortOrderSet structure.

  • The number of columns to be sorted, as specified in the cSorts member in SSortOrderSet, is larger than the implementation can handle.

  • A sort operation is requested, as indicated by a property tag in SSortOrderSet, based on a property that is not in the available or active set and the implementation does not support sorting on properties not in the available set.

  • One property is specified multiple times in a sort order set, as indicated by multiple instances of the same property tag, and the implementation cannot perform such a sort operation.

  • A sort operation based on multivalued property columns is requested using MVI_FLAG and the implementation does not support sorting on multivalued properties.

  • A property tag for a property in SSortOrderSet specifies a property or type that the implementation does not support.

  • A sort operation other than one that proceeds through the table from the PR_RENDERING_POSITION (PidTagRenderingPosition) property forward is specified only for an attachment table that supports this type of sorting.

Remarks

The IMAPITable::SortTable method orders the rows in a table view. Whereas some tables support both standard and categorized sorting on various sort key columns, other tables are more limited in their support. Address book providers ordinarily do not support table sorting. Message store providers usually support sorting to the extent that they keep the sort order of folders that results when a full table (a table without restrictions) is sorted.

Some tables allow sorting to be done on any table column. Other tables do not; columns not included in the table view are unaffected by a SortTable call. Some tables require that sort keys be built only with columns in the table's current column set.

A table can return either MAPI_E_NO_SUPPORT or MAPI_E_TOO_COMPLEX from SortTable when it cannot complete a sort operation. Moreover, store providers are not guaranteed to honor the sort order set specified for hierarchy tables.

When there are zero columns in the SSortOrderSet structure pointed to by the lpSortCriteria parameter, the table returns the current column set. The current sort order can be retrieved by calling the table's IMAPITable::QuerySortOrder method.

All bookmarks for a table are invalidated and should be deleted when a call to SortTable is made, and the BOOKMARK_CURRENT bookmark that indicates the current cursor position, should be set to the beginning of the table.

If you are sorting on a column that contains a multivalued property without the MVI_FLAG flag set, the column's values are treated as a completely ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality, and returns equality only if the columns being compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.

Notes to Callers

SortTable operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, SortTable postpones the sort operation unless you request the data. If the TBL_ASYNC flag is set, SortTable operates asynchronously, potentially returning before the completion of the operation.

Call the IMAPITable::Abort method to stop an asynchronous operation in progress if your sort must be done immediately. If SortTable cannot continue because one or more asynchronous operations on the table are in progress, it returns MAPI_E_BUSY.

For best performance, call SetColumns to customize the table's column set and Restrict to limit the number of rows in the table before you call SortTable to perform the sort.

Whenever SortTable fails, the sort order that was in effect before the failure is still in effect.

See also

Reference

IMAPITable::Abort
IMAPITable::GetRowCount
IMAPITable::QueryColumns
IMAPITable::QuerySortOrder
IMAPITable::SetColumns
SSortOrderSet
IMAPITable : IUnknown


IMAPITable::Unadvise

 Copy code hover
[image]

IMAPITable::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels the sending of notifications previously set up with a call to the IMAPITable::Advise method.

C++
HRESULT Unadvise(
ULONG_PTR ulConnection
);

Parameters

ulConnection

[in] The number of the registration connection returned by a call to IMAPITable::Advise.

Return value

S_OK

The call succeeded.

Remarks

Use the IMAPITable::Unadvise method to release the pointer to the advise sink object passed in the lpAdviseSink parameter in the previous call to IMAPITable::Advise, thereby canceling a notification registration. As part of discarding the pointer to the advise sink object, the object's IUnknown::Release method is called. Generally, Release is called during the Unadvise call, but if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink, the Release call is delayed until the OnNotify method returns.

For more information on the notification process, see Event Notification in MAPI. For specific information about table notification, see About Table Notifications. For information about using the IMAPISupport methods to support notification, see Supporting Event Notification.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::NotificationOff | MFCMAPI uses the IMAPITable::Unadvise method to cancel notifications for the table.

See also

Reference

IMAPIAdviseSink::OnNotify
IMAPITable::Advise
IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPITable::WaitForCompletion

 Copy code hover
[image]

IMAPITable::WaitForCompletion
See also Send feedback

Published: July 16, 2012

Suspends processing until one or more asynchronous operations in progress on the table have completed.

C++
HRESULT WaitForCompletion(
ULONG ulFlags,
ULONG ulTimeout,
ULONG FAR * lpulTableStatus
);

Parameters

ulFlags

Reserved; must be zero.

ulTimeout

[in] Maximum number of milliseconds to wait for the asynchronous operation or operations to complete. To wait indefinitely until completion occurs, set ulTimeout to 0xFFFFFFFF.

lpulTableStatus

[in, out] On input, either a valid pointer or NULL. On output, if lpulTableStatus is a valid pointer, it points to the most recent status of the table. If lpulTableStatus is NULL, no status information is returned. If WaitForCompletion returns an unsuccessful HRESULT value, the contents of lpulTableStatus are undefined.

Return value

S_OK

The wait operation was successful.

MAPI_E_NO_SUPPORT

The table does not support waiting for the completion of asynchronous operations.

MAPI_E_TIMEOUT

The asynchronous operation or operations did not complete in the specified time.

Remarks

The IMAPITable::WaitForCompletion method suspends processing until any asynchronous operations currently under way for the table have completed. WaitForCompletion can allow the asynchronous operations either to fully complete or to run for a certain number of milliseconds, as indicated by ulTimeout, before being interrupted. To detect asynchronous operations in progress, call the IMAPITable::GetStatus method.

See also

Reference

IMAPITable::GetRowCount
IMAPITable::GetStatus
IMAPITable::Restrict
IMAPITable::SetColumns
IMAPITable::SortTable
IMAPITable : IUnknown


IMAPIViewAdviseSink : IUnknown

 Copy code hover
[image]

IMAPIViewAdviseSink : IUnknown
See also Send feedback

Published: July 16, 2012

Receives notifications from forms.

Header file: | Mapiform.h
Exposed by: | View advise sink objects
Implemented by: | Form viewers
Called by: | Form objects
Interface identifier: | IID_IMAPIViewAdviseSink
Pointer type: | LPMAPIVIEWADVISESINK

Vtable Order

OnShutdown | Notifies the form viewer that a form is being closed.
OnNewMessage | Notifies the form viewer that either a new or an existing message has been loaded in a form.
OnPrint | Notifies the form viewer of the printing status of a form.
OnSubmitted | Notifies the form viewer that the current message has been submitted to MAPI spooler.
OnSaved | Notifies the form viewer that the current message in a form has been saved.

See also

Concepts

MAPI Interfaces


IMAPIViewAdviseSink::OnShutdown

 Copy code hover
[image]

IMAPIViewAdviseSink::OnShutdown
See also Send feedback

Published: July 16, 2012

Notifies the form viewer that a form is being closed.

C++
HRESULT OnShutdown( void );

Parameters

None

Return value

S_OK

The notification succeeded.

Remarks

For more information about form notifications, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIViewAdviseSink : IUnknown


IMAPIViewAdviseSink::OnNewMessage

 Copy code hover
[image]

IMAPIViewAdviseSink::OnNewMessage
See also Send feedback

Published: July 16, 2012

Notifies the form viewer that a new or an existing message has been loaded in a form.

C++
HRESULT OnNewMessage( void );

Parameters

None

Return value

S_OK

The notification succeeded.

Remarks

Form objects call the IMAPIViewAdviseSink::OnNewMessage method whenever a message is loaded in a form using either the IPersistMessage::InitNew or IPersistMessage::Load method.

Notes to Implementers

Release your active pointer to the form object because it no longer points to the message your viewer was formerly viewing.

For more information about form notifications, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIForm : IUnknown
IPersistMessage::InitNew
IPersistMessage::Load
IMAPIViewAdviseSink : IUnknown


IMAPIViewAdviseSink::OnPrint

 Copy code hover
[image]

IMAPIViewAdviseSink::OnPrint
See also Send feedback

Published: July 16, 2012

Notifies the form viewer of the printing status of a form.

C++
HRESULT OnPrint(
ULONG dwPageNumber,
HRESULT hrStatus
);

Parameters

dwPageNumber

[in] Number of the last page printed.

hrStatus

[in] An HRESULT value indicating the status of the print job. Possible values are:

S_FALSE

The printing job has finished successfully.

S_OK

The printing job is in progress.

FAILED

The printing job was terminated due to a failure.

Return value

S_OK

The notification succeeded.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

Form objects call the IMAPIViewAdviseSink::OnPrint method while printing to inform the viewer of printing progress.

Notes to Callers

If the printing job involves multiple pages, you can call OnPrint after each page is printed. Set dwPageNumber to the page currently being printed and hrStatus to S_OK. When the printing job is complete, call OnPrint with dwPageNumber set to the last page printed and hrStatus set to S_FALSE.

For more information about form notifications, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIViewAdviseSink : IUnknown


IMAPIViewAdviseSink::OnSaved

 Copy code hover
[image]

IMAPIViewAdviseSink::OnSaved
See also Send feedback

Published: July 16, 2012

Notifies the form viewer that the current message in a form has been saved.

C++
HRESULT OnSaved( void );

Parameters

None

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

A form object calls the IMAPIViewAdviseSink::OnSaved method after the current message in a form has been successfully saved. Doing so permits viewers to update their windows to reflect changes to the message.

For more information about form notifications, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIViewAdviseSink : IUnknown


IMAPIViewAdviseSink::OnSubmitted

 Copy code hover
[image]

IMAPIViewAdviseSink::OnSubmitted
See also Send feedback

Published: July 16, 2012

Notifies the form viewer that the current message has been submitted to the MAPI spooler.

C++
HRESULT OnSubmitted( void );

Parameters

None

Return value

S_OK

The notification succeeded.

Remarks

A form object calls the IMAPIViewAdviseSink::OnSubmitted method after a call to IMAPIMessageSite::SubmitMessage has returned successfully.

Notes to Implementers

After OnSubmitted is called, you can continue on the assumption that the message has been updated. Update your windows to reflect any changes that have occurred.

For more information about form notifications, see Sending and Receiving Form Notifications.

See also

Reference

IMAPIMessageSite::SubmitMessage
IMAPIViewAdviseSink : IUnknown


IMAPIViewContext : IUnknown

 Copy code hover
[image]

IMAPIViewContext : IUnknown
See also Send feedback

Published: July 16, 2012

Manages a form in a client application's form viewer.

Header file: | Mapiform.h
Exposed by: | View context objects
Implemented by: | Form viewers
Called by: | Form objects
Interface identifier: | IID_IMAPIViewContext
Pointer type: | LPMAPIVIEWCONTEXT

Vtable Order

SetAdviseSink | Manages a form's registration to receive notifications about changes in the viewer.
ActivateNext | Activates the next or previous message in the form viewer.
GetPrintSetup | Retrieves current printing information.
GetSaveStream | Retrieves a stream to be used for saving the current message.
GetViewStatus | Retrieves the current viewer status.
GetLastError | Returns a MAPIERROR structure that contains information about the previous error occurring in the view context object.

See also

Concepts

MAPI Interfaces


IMAPIViewContext::ActivateNext

 Copy code hover
[image]

IMAPIViewContext::ActivateNext
See also Send feedback

Published: July 16, 2012

Activates the next or previous message in the view order.

C++
HRESULT ActivateNext(
ULONG ulDir,
LPCRECT prcPosRect
);

Parameters

ulDir

[in] Status flags giving information about the message to be activated. Valid flag settings are:

VCDIR_CATEGORY

The viewer should activate a message in another category of the view. The message to be activated is:

  • The first message in the next view category if this flag is ORed with VCDIR_NEXT.

  • The last message in the previous view category if this flag is ORed with VCDIR_PREV and the previous category is expanded.

  • The first message in the previous view category if this flag is ORed with VCDIR_PREV and the previous category is not expanded. In this case the previous category undergoes automatic expansion.

VCDIR_DELETE

The viewer should activate the next or previous message because the current message has been deleted.

VCDIR_MOVE

The viewer should activate the next or previous message because the current message has been moved.

VCDIR_NEXT

The viewer should activate the next message in the view order.

VCDIR_PREV

The viewer should activate the previous message in the view order.

VCDIR_UNREAD

The viewer should activate the next or previous unread message in the view order.

prcPosRect

[in] Pointer to a Windows RECT structure containing the size and position of the window to be used to display the activated message.

Return value

S_OK

The message was activated successfully.

S_FALSE

The message was activated successfully, but a different type of form was opened in the process.

Remarks

Form objects call the IMAPIViewContext::ActivateNext method to change what message is displayed to the user. The value passed in the ulDir parameter indicates which message should be activated and, in some cases, why. The VCDIR_NEXT and VCDIR_PREVIOUS flags correspond to users choosing the Next or Previous command in a view, respectively. These operations usually correspond to moving up or down one message in the form viewer's list of messages.

The VCDIR_DELETE and VCDIR_MOVE flags are set by the IMAPIMessageSite::DeleteMessage and IMAPIMessageSite::MoveMessage methods, respectively. Implementations of these methods call ActivateNext with the appropriate direction and then perform the requested operation on the message if the ActivateNext call did not fail. Form viewers typically enable users to specify the direction to move in the message list.

Notes to Implementers

Your implementation of IMAPIViewContext::ActivateNext makes the next or previous message in the folder, depending on the value of ulDir, the current message. After ActivateNext returns, call IMAPIMessageSite::GetMessage to get a pointer to the newly activated message.

Notes to Callers

If ActivateNext returns S_FALSE, or if a current message is not present, perform your normal shutdown procedure which should include calling your form's IMAPIForm::ShutdownForm method. If a next or previous message is displayed, use the window rectangle passed in the prcPosRect parameter to display it.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::ActivateNext | MFCMAPI implements the IMAPIViewContext::ActivateNext method in this function.

See also

Reference

IMAPIViewContext::GetViewStatus
IMAPIViewContext : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIViewContext::GetLastError

 Copy code hover
[image]

IMAPIViewContext::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error occurring to the view context object.

C#
HRESULT GetLastError(
HRESULT hResult,
ULONG ulFlags,
LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] Bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. This parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError only supports Unicode.

Remarks

The IMAPIViewContext::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure pointed to by the lppMAPIError parameter if MAPI supplies one only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMAPIViewContext : IUnknown


IMAPIViewContext::GetPrintSetup

 Copy code hover
[image]

IMAPIViewContext::GetPrintSetup
See also Send feedback

Published: July 16, 2012

Retrieves current printing information.

C++
HRESULT GetPrintSetup(
ULONG ulFlags,
LPFORMPRINTSETUP FAR * lppFormPrintSetup
);

Parameters

ulFlags

[in] Bitmask of flags that controls the type of the returned strings. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppFormPrintSetup

[out] Pointer to a pointer to a structure that holds the printing information.

Return value

S_OK

The printing information was successfully retrieved.

Remarks

Form objects call the IMAPIViewContext::GetPrintSetup method to retrieve information about the printer setup before attempting to print the current message.

Notes to Implementers

Allocate the hDevMode and hDevName members of the FORMPRINTSETUP structure using the Win32 function GlobalAlloc.

Notes to Callers

If you expect the hDevMode and hDevName members of the FORMPRINTSETUP structure pointed to by the lppFormPrintSetup parameter to be Unicode strings, set ulFlags to MAPI_UNICODE. Otherwise, GetPrintSetup will return these strings in ANSI format.

Free the hDevMode and hDevName members of the FORMPRINTSETUP structure by calling the Win32 function GlobalFree. Free the entire FORMPRINTSETUP structure by calling MAPIFreeBuffer.

See also

Reference

FORMPRINTSETUP
IMAPIViewContext : IUnknown


IMAPIViewContext::GetSaveStream

 Copy code hover
[image]

IMAPIViewContext::GetSaveStream
See also Send feedback

Published: July 16, 2012

Retrieves a stream to be used for saving the current message.

C++
HRESULT GetSaveStream(
ULONG FAR * pulFlags,
ULONG FAR * pulFormat,
LPSTREAM FAR * ppstm
);

Parameters

pulFlags

[out] Pointer to a bitmask of flags that controls how the message text should be saved. The following flag can be set:

MAPI_UNICODE

The message text is saved in Unicode format. If the MAPI_UNICODE flag is not set, the text is saved in ANSI format.

pulFormat

[out] Pointer to a bitmask of flags that controls the format of the saved text. The following flags can be set:

SAVE_FORMAT_RICHTEXT

The message text is to be saved as formatted text in the Rich Text Format (RTF).

SAVE_FORMAT_TEXT

The message text is to be saved as plain text.

ppstm

[out] Pointer to a pointer to the stream that will contain the saved message.

Return value

S_OK

The stream was successfully retrieved.

Remarks

Form objects call the IMAPIViewContext::GetSaveStream method to retrieve a stream an object that implements the IStream interface to support the handling of the Save As verb in the form viewer. The IMAPIForm::DoVerb method, which is implemented in the form server and called by the form viewer to invoke a verb, should not return until the message is fully converted into the appropriate text format and placed into the appropriate stream.

Notes to Callers

Do not write to the stream pointed to by ppstm before calling GetSaveStream. When GetSaveStream returns, do not reset the position of the seek pointer. This pointer must remain at the end of the saved message text.

See also

Reference

IMAPIViewContext : IUnknown


IMAPIViewContext::GetViewStatus

 Copy code hover
[image]

IMAPIViewContext::GetViewStatus
See also Send feedback

Published: July 16, 2012

Retrieves the current viewer status.

C++
HRESULT GetViewStatus(
ULONG FAR * lpulStatus
);

Parameters

lpulStatus

[out] Pointer to a bitmask of flags providing the status of the viewer. The following flags can be set:

VCSTATUS_CATEGORY

There is a next or previous message in another category.

VCSTATUS_DELETE

The form allows messages to be removed.

VCSTATUS_INTERACTIVE

The form should display a user interface. If this flag is not set, the form should suppress displaying a user interface even in response to a verb that usually causes a user interface to be displayed.

VCSTATUS_MODAL

The form is modal to the viewer.

VCSTATUS_NEXT

There is a next message in the view.

VCSTATUS_PREV

There is a previous message in the view.

VCSTATUS_READONLY

The message is to be opened in read-only mode. Delete, submit, and move operations should be disabled.

VCSTATUS_UNREAD

There is a next or previous unread message in the view.

Return value

S_OK

The viewer's status was successfully returned.

Remarks

Form objects call the IMAPIViewContext::GetViewStatus method to determine whether there are more messages to be activated in a form view in either or both directions that is, in the direction in which a Next command activates messages, in the direction in which a Previous command activates messages, or in both directions. The value pointed to by the lpulStatus parameter is used to determine whether the VCSTATUS_NEXT and VCSTATUS_PREV flags are valid for IMAPIViewContext::ActivateNext. If the VCSTATUS_DELETE flag is set, but not the VCSTATUS_READONLY flag, then the message can be deleted using the IMAPIMessageSite::DeleteMessage method.

Typically, forms disable menu commands and buttons if they are not valid for the viewer's context. A viewer can alert a form to a change in status by calling its IMAPIFormAdviseSink::OnChange method.

The VCSTATUS_MODAL flag is set if the form must be modal to the window whose handle is passed in the earlier IMAPIForm::DoVerb call. If VCSTATUS_MODAL is set, the form can use the thread on which the DoVerb call was made until the form closes. If VCSTATUS_MODAL is not set, the form should not be modal to this window and must not use the thread.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::GetViewStatus | MFCMAPI implements the IMAPIViewContext::GetViewStatus method in this function.

See also

Reference

IMAPIMessageSite::GetSiteStatus
IMAPIViewContext : IUnknown

Concepts

MFCMAPI as a Code Sample


IMAPIViewContext::SetAdviseSink

 Copy code hover
[image]

IMAPIViewContext::SetAdviseSink
See also Send feedback

Published: July 16, 2012

Manages a form's registration to receive notifications about changes in the viewer.

C++
HRESULT SetAdviseSink(
LPMAPIFORMADVISESINK pmvns
);

Parameters

pmvns

[in] Pointer to a form advise sink object or NULL.

Return value

S_OK

The registration or cancellation for form notification succeeded.

Remarks

Form objects call the IMAPIViewContext::SetAdviseSink method to either register to learn about changes in the form viewer or cancel a prior registration. When pmvns is set to NULL, the form wants to cancel a registration. When pmvns points to a valid form advise sink, the form wants to register for future notifications.

Notes to Implementers

When SetAdviseSink includes a form advise sink pointer, keep a reference to it until another SetAdviseSink call is made to cancel notification. Send a notification when a change occurs in your viewer and when you are loading a new message.

For more information, see Sending and Receiving Form Notifications.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MyMAPIFormViewer.cpp | CMyMAPIFormViewer::SetAdviseSink | MFCMAPI implements the IMAPIViewContext::SetAdviseSink method in this function.

See also

Concepts

MFCMAPI as a Code Sample


IMessage : IMAPIProp

 Copy code hover
[image]

IMessage : IMAPIProp
Send feedback

Published: July 16, 2012

Manages messages, attachments, and recipients.

Header file: | Mapidefs.h
Exposed by: | Message object
Implemented by: | Message store providers
Called by: | Client applications
Interface identifier: | IID_IMessage
Pointer type: | LPMESSAGE
Transaction model: | Transacted

Vtable Order

GetAttachmentTable | Returns the message's attachment table.
OpenAttach | Opens an attachment.
CreateAttach | Creates a new attachment.
DeleteAttach | Deletes an attachment.
GetRecipientTable | Returns the message's recipient table.
ModifyRecipients | Adds, deletes, or modifies message recipients.
SubmitMessage | Saves all changes to the message and marks it as ready for sending.
SetReadFlag | Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message and manages the sending of read reports.

The following properties are required on messages at some point during their lifecycle. Most of the read-only properties are set by the message store provider when a client calls a message's IMAPIProp::SaveChanges method. Other read-only properties are set by the transport provider.

Required properties for messages of all classes | Access
PR_CREATION_TIME (PidTagCreationTime) | Read-only
PR_DISPLAY_BCC (PidTagDisplayBcc) | Read-only
PR_DISPLAY_CC (PidTagDisplayCc) | Read-only
PR_DISPLAY_TO (PidTagDisplayTo) | Read-only
PR_ENTRYID (PidTagEntryId) | Read-only
PR_LAST_MODIFICATION_TIME (PidTagLastModificationTime) | Read-only
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Read-only
PR_MESSAGE_CLASS (PidTagMessageClass) | Read/write
PR_MESSAGE_FLAGS (PidTagMessageFlags) | Read/write
PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) | Read-only
PR_MESSAGE_SIZE (PidTagMessageSize) | Read-only
PR_MESSAGE_CC_ME (PidTagMessageCcMe) | Read-only
PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe) | Read-only
PR_MESSAGE_TO_ME (PidTagMessageToMe) | Read-only
PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) | Read-only
PR_ORIGINATOR properties | Read-only
PR_PARENT_DISPLAY (PidTagParentDisplay) | Read-only
PR_PARENT_ENTRYID (PidTagParentEntryId) | Read-only
PR_RECEIVED_BY properties | Read-only
PR_RECIPIENT_TYPE (PidTagRecipientType) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only
PR_SEARCH_KEY (PidTagSearchKey) | Read-only
PR_SENDER properties | Read-only
PR_STORE_ENTRYID (PidTagStoreEntryId) | Read-only
PR_STORE_RECORD_KEY (PidTagStoreRecordKey) | Read-only

The following properties are all read-only to clients, with the exception of PR_BODY. Clients construct this property when they process a report.

Properties for report messages

PR_BODY (PidTagBody)

PR_CONVERSATION_INDEX (PidTagConversationIndex)

PR_CONVERSATION_TOPIC (PidTagConversationTopic)

PR_MESSAGE_CLASS

PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime)

PR_ORIGINAL_DELIVERY_TIME (PidTagOriginalDeliveryTime)

PR_ORIGINAL_DISPLAY_BCC (PidTagOriginalDisplayBcc)

PR_ORIGINAL_DISPLAY_CC (PidTagOriginalDisplayCc)

PR_ORIGINAL_DISPLAY_TO (PidTagOriginalDisplayTo)

PR_ORIGINAL_SUBJECT (PidTagOriginalSubject)

PR_ORIGINAL_SUBMIT_TIME (PidTagOriginalSubmitTime)

PR_REPORT_TAG (PidTagReportTag)

PR_REPORT_TEXT (PidTagReportText)

PR_REPORT_TIME (PidTagReportTime)

PR_SEARCH_KEY

PR_SENDER properties

PR_SUBJECT (PidTagSubject)

Properties for message recipients | Access | Required or optional
PR_ADDRTYPE (PidTagAddressType) | Read-only | Required
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write | Required
PR_DISPLAY_TYPE (PidTagDisplayType) | Read/write | Required
PR_EMAIL_ADDRESS (PidTagEmailAddress) | Read-only | Optional
PR_ENTRYID | Read-only | Required
PR_OBJECT_TYPE (PidTagObjectType) | Read-only | Required
PR_SEARCH_KEY | Read-only | Optional


IMessage::CreateAttach

 Copy code hover
[image]

IMessage::CreateAttach
See also Send feedback

Published: July 16, 2012

Creates a new attachment.

C++
HRESULT CreateAttach(
LPCIID lpInterface,
ULONG ulFlags,
ULONG FAR * lpulAttachmentNum,
LPATTACH FAR * lppAttach
);

Parameters

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message. Passing NULL results in the message's standard interface, or IMessage, being returned.

ulFlags

[in] Bitmask of flags that controls how the attachment is created. The following flag can be set:

MAPI_DEFERRED_ERRORS

Allows CreateAttach to return successfully, possibly before the attachment is fully accessible to the calling client. If the attachment is not accessible, making a subsequent call to it can result in an error.

lpulAttachmentNum

[out] Pointer to an index number identifying the newly created attachment. This number is valid only when the message is open and is the basis for the attachment's PR_ATTACH_NUM (PidTagAttachNumber) property.

lppAttach

[out] Pointer to a pointer to the open attachment object.

Return value

S_OK

The attachment was successfully created.

Remarks

The IMessage::CreateAttach method creates a new attachment on a message. The new attachment and any properties that are set for it, are not available until a client has called both the attachment's IMAPIProp::SaveChanges method and the message's IMAPIProp::SaveChanges method.

The attachment number pointed to by lpulAttachmentNum is unique and valid only within the context of the message. That is, two attachments in two different messages can have the same number while two attachments in the same message cannot.

See also

Reference

IMessage : IMAPIProp


IMessage::DeleteAttach

 Copy code hover
[image]

IMessage::DeleteAttach
See also Send feedback

Published: July 16, 2012

Deletes an attachment.

C++
HRESULT DeleteAttach(
ULONG ulAttachmentNum,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);

Parameters

ulAttachmentNum

[in] Index number of the attachment to delete. This is the value for the attachment's PR_ATTACH_NUM (PidTagAttachNumber) property.

ulUIParam

[in] Handle to the parent window of any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the ATTACH_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the ATTACH_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls the display of a user interface. The following flag can be set:

ATTACH_DIALOG

Requests the display of a progress indicator as the operation proceeds.

Return value

S_OK

The attachment was successfully deleted.

Remarks

The IMessage::DeleteAttach method deletes an attachment from within a message.

A deleted attachment is not permanently deleted until the message's IMAPIProp::SaveChanges method has been called.

Notes to Callers

Before calling DeleteAttach, call the IUnknown::Release method for the attachment and each of its streams.

Because deleting an attachment can be a lengthy process, DeleteAttach provides the mechanism that displays a progress indicator. You can request the display of a progress indicator by passing a pointer to your IMAPIProgress : IUnknown implementation or NULL if you do not have an implementation. You must also specify a window handle in the ulUIParam parameter and the ATTACH_DIALOG flag in the ulFlags parameter.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
AttachmentsDlg.cpp | CAttachmentsDlg::OnDeleteSelectedItem | MFCMAPI uses the IMessage::DeleteAttach method to delete the selected attachment.

See also

Reference

IMAPIProp::SaveChanges
IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMessage::GetAttachmentTable

 Copy code hover
[image]

IMessage::GetAttachmentTable
See also Send feedback

Published: July 16, 2012

Returns the message's attachment table.

HRESULT GetAttachmentTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Bitmask of flags that relate to the creation of the table. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the string columns are in ANSI format.

MAPI_DEFERRED_ERRORS

Allows GetAttachmentTable to return successfully, possibly before the table is fully available to the calling client. If the table is not available, making a subsequent call to it can cause an error.

lppTable

[out] Pointer to a pointer to the attachment table.

Return value

S_OK

The attachment table was successfully retrieved.

Remarks

The IMessage::GetAttachmentTable method returns a pointer to the message's attachment table, which includes information about all of the attachments in the message. Clients can get access to an attachment only through the attachment table. By retrieving an attachment's number its PR_ATTACH_NUM (PidTagAttachNumber) property a client can use several of the IMessage methods to work with the attachment.

There is one row for each attachment. For a complete list of the columns in an attachment table, see Attachment Tables.

An attachment usually does not appear in the attachment table until both the attachment and the message have been saved with a call to IMAPIProp::SaveChanges. Attachment tables are dynamic. If a client creates a new attachment, deletes an existing attachment, or changes one or more properties once the SaveChanges calls have been made on the attachment on the message, the attachment table will be updated to reflect the new information.

Some attachment tables support a wide variety of restrictions; others do not. Support for restrictions depends on the message store provider's implementation.

When initially opened, attachment tables are not necessarily sorted in any particular order.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the following calls to the attachment table:

  • IMAPITable::QueryColumns to retrieve the column set.

  • IMAPITable::QueryRows to retrieve rows.

  • IMAPITable::QuerySortOrder to retrieve the sort order.

Setting the Unicode flag requests that the information for any string columns returned from these calls be in Unicode format. However, because not all message store providers support Unicode, setting this flag is only a request.

See also

Reference

IMessage::CreateAttach
IMessage::DeleteAttach
IMessage::OpenAttach
IMessage : IMAPIProp


IMessage::GetRecipientTable

 Copy code hover
[image]

IMessage::GetRecipientTable
See also Send feedback

Published: July 16, 2012

Returns the message's recipient table.

C#
HRESULT GetRecipientTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Bitmask of flags that controls the return of the table. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows GetRecipientTable to return successfully, possibly before the table is fully available to the calling client. If the table is not available, making a subsequent call to it can cause an error.

MAPI_UNICODE

String columns should be in Unicode format. If the MAPI_UNICODE flag is not set, the string columns should be in ANSI format.

lppTable

[out] Pointer to a pointer to the recipient table.

Return value

S_OK

The recipient table was returned successfully.

Remarks

The IMessage::GetRecipientTable method returns a pointer to the message's recipient table, which includes information about all of the recipients for the message. There is one row for every recipient.

Recipient tables have a different column set depending on whether the message has been submitted. For a complete list of the columns in a recipient table, see Recipient Tables.

Some recipient tables support a wide variety of restrictions; others do not. Support for restrictions depends on the message store provider's implementation.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the following calls to the recipient table:

  • IMAPITable::QueryColumns to retrieve the column set.

  • IMAPITable::QueryRows to retrieve rows.

  • IMAPITable::QuerySortOrder to retrieve the sort order.

Setting the Unicode flag requests that the information for any string columns returned from these calls be in Unicode format. However, because not all message store providers support Unicode, setting this flag is only a request.

Notes to Callers

You can change a recipient table while it is open by calling the IMessage::ModifyRecipients method. ModifyRecipients adds recipients, deletes recipients, or modifies recipient properties.

See also

Reference

IMAPIProp::SaveChanges
IMAPITable::QueryRows
IMessage::ModifyRecipients
IMessage : IMAPIProp


IMessage::ModifyRecipients

 Copy code hover
[image]

IMessage::ModifyRecipients
See also Send feedback

Published: July 16, 2012

Adds, deletes, or modifies message recipients.

C#
HRESULT ModifyRecipients(
  ULONG ulFlags,
  LPADRLIST lpMods
);

Parameters

ulFlags

[in] Bitmask of flags that controls the recipient changes. If zero is passed for the ulFlags parameter, ModifyRecipients replaces all existing recipients with the recipient list pointed to by the lpMods parameter. The following flags can be set for ulFlags:

MODRECIP_ADD

The recipients pointed to by the lpMods parameter should be added to the recipient list.

MODRECIP_MODIFY

The recipients pointed to by the lpMods parameter should replace existing recipients. All of the existing properties are replaced by those in the corresponding ADRENTRY structure.

MODRECIP_REMOVE

Existing recipients should be removed from the recipient list using as an index the PR_ROWID (PidTagRowid) property included in the property value array of each recipient entry in the lpMods parameter.

lpMods

[in] Pointer to an ADRLIST structure that contains a list of recipients to be added, deleted, or modified in the message.

Return value

S_OK

The recipient list was successfully modified.

Remarks

The IMessage::ModifyRecipients method changes the message's recipient list. It is from this list, held in an ADRLIST structure, that the recipient table is built.

The ADRLIST structure contains one ADRENTRY structure for each recipient and each ADRENTRY structure contains an array of property values describing the recipient properties.

Recipients in the ADRLIST structure can be resolved or unresolved. The difference is in the number and type of properties that are included. An unresolved recipient contains only the PR_DISPLAY_NAME (PidTagDisplayName) and PR_RECIPIENT_TYPE (PidTagRecipientType) properties while a resolved recipient contains those two properties plus PR_ADDRTYPE (PidTagAddressType) and PR_ENTRYID (PidTagEntryId). If PR_EMAIL_ADDRESS (PidTagEmailAddress) is available, it can be included also.

By the time a message is submitted, it must include only resolved recipients in its recipient list. Unresolved recipients cause nondelivery reports to be created and sent to the original sender of the message. For more information about the name resolution process from the client perspective, see Resolving a Name. For more information from the perspective of the address book provider, see Implementing Name Resolution.

In addition to resolved and unresolved recipients, a recipient can be NULL. The cValues member of the ADRENTRY structure for the recipient is set to zero and the rgPropVals member is set to NULL.

Notes to Callers

You can create a recipient list by calling IAddrBook::Address to display the common dialog box and prompt the user to select entries. The address list pointed to by the lppAdrList parameter to Address can be passed to ModifyRecipients as the lpMods parameter.

When you specify properties for a recipient in the ADRLIST structure, include all of the recipient's properties, not only the new or changed ones. When a recipient is modified, any properties not included in the ADRLIST structure are deleted. To retrieve the current set of properties for all of a message's recipients, call GetRecipientTable and retrieve all of the rows. Because an SRowSet is identical in structure to an ADRLIST, you can use them interchangeably.

ModifyRecipients replaces all of the entries in the current recipient list with the information pointed to by lpMods when none of the flags are set in the ulFlags parameter.

Notes to Callers

When you set the MODRECIP_MODIFY flag, ModifyRecipients replaces each entire recipient row with the associated row in the ADRLIST structure passed in lpMods. Be careful to specify all of the properties that a recipient should have regardless of whether they have changed to prevent them from being unintentionally deleted.

Following are some rules for setting the properties of the recipients in the ADRLIST structure:

  • Do not use PT_NULL as a property type. ModifyRecipients returns an error when encountering this value.

  • Do not use PT_ERROR as a property type. ModifyRecipients ignores this value.

  • Include the PR_ROWID property for all recipients when you set either the MODRECIP_REMOVE or MODRECIP_MODIFY flag in ulFlags.

  • Do not include the PR_ROWID property for any of the recipients when you set the MODRECIP_ADD flag in ulFlags or when you pass zero in ulFlags.

If you include either the PR_ADDRTYPE property or PR_EMAIL_ADDRESS property for a recipient and one or both of these properties are inconsistent with the address type and address of the recipient as identified by PR_ENTRYID, the results are undefined. That is, there are three possibilities, depending on the service provider:

  • The message will be delivered to the address described by the PR_ADDRTYPE and PR_EMAIL_ADDRESS properties.

  • The message will be delivered to the recipient identified by PR_ENTRYID.

  • The message will be declared undeliverable due to the ambiguity of the address information.

Use the allocation rules outlined in Managing Memory for ADRLIST and SRowSet Structures to allocate memory for the recipient list. ModifyRecipients does not free the ADRLIST structure nor any of its substructures. The ADRLIST structure and each SPropValue structure must be separately allocated by using the MAPIAllocateBuffer function such that each can be freed individually. If the method requires additional space for any SPropValue structure, it can replace the SPropValue structure with a new one that can later be freed using MAPIFreeBuffer. The original SPropValue structure should also be freed using MAPIFreeBuffer.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIABFunctions.cpp | AddRecipient | MFCMAPI uses the IMessage::ModifyRecipients method to add a new recipient to a message.

See also

Reference

ADRENTRY
ADRLIST
IAddrBook::Address
IMAPISupport::Address
MAPIAllocateBuffer
MAPIFreeBuffer
SPropValue
IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMessage::OpenAttach

 Copy code hover
[image]

IMessage::OpenAttach
See also Send feedback

Published: July 16, 2012

Opens an attachment.

C#
HRESULT OpenAttach(
  ULONG ulAttachmentNum,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPATTACH FAR * lppAttach
);

Parameters

ulAttachmentNum

[in] Index number of the attachment to open, as stored in the attachment's PR_ATTACH_NUM (PidTagAttachNumber) property. This index number uniquely identifies the attachment in the message and is valid only in the context of the message.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the attachment. Passing NULL results in the attachment's standard interface, or IAttach, being returned.

ulFlags

[in] Bitmask of flags that controls how the attachment is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the attachment be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the attachment should be opened with read/write permission; if the client has read-only access, the attachment should be opened with read-only access.

MAPI_DEFERRED_ERRORS

Allows OpenAttach to return successfully, possibly before the attachment is fully available to the calling client. If the attachment is not available, making a subsequent call to it can cause an error.

MAPI_MODIFY

Requests read/write permission. By default, attachments are opened with read-only access, and clients should not work on the assumption that read/write permission has been granted.

lppAttach

[out] Pointer to a pointer to the open attachment.

Return value

S_OK

The attachment was successfully opened.

Remarks

The IMessage::OpenAttach method opens a message's attachment.

Notes to Callers

To open an attachment, you must have access to its attachment number or PR_ATTACH_NUM property. Call IMessage::GetAttachmentTable to retrieve the message's attachment table and locate the row that represents the attachment to be opened. See Opening an Attachment for more information.

Do not try to open one attachment multiple times; the results are undefined and dependent on the message store provider.

You can request that the attachment be opened in read/write mode, instead of the default read-only mode. However, whether the attachment will actually be opened in read/write mode is up to the message store provider. You can either attempt to modify the attachment, preparing to handle possible failure, or check the level of access that was granted by retrieving the attachment's PR_ACCESS_LEVEL (PidTagAccessLevel) property, if it is available.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
AttachmentsDlg.cpp Used to | CAttachmentsDlg::OpenItemProp | MFCMAPI uses the IMessage::OpenAttach method to open attachment objects,

See also

Reference

IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMessage::SetReadFlag

 Copy code hover
[image]

IMessage::SetReadFlag
See also Send feedback

Published: July 16, 2012

Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message and manages the sending of read reports.

C#
HRESULT SetReadFlag(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Bitmask of flags that controls the setting of a message's read flag that is, the message's MSGFLAG_READ flag in its PR_MESSAGE_FLAGS property and the processing of read reports. The following flags can be set:

CLEAR_READ_FLAG

The MSGFLAG_READ flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

CLEAR_NRN_PENDING

The MSGFLAG_NRN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and a non-read report should not be sent.

CLEAR_RN_PENDING

The MSGFLAG_RN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

GENERATE_RECEIPT_ONLY

A read report should be sent if one is pending, but there should be no change in the state of the MSGFLAG_READ flag.

MAPI_DEFERRED_ERRORS

Allows SetReadFlag to return successfully, possibly before the operation has completed.

SUPPRESS_RECEIPT

A pending read report should be canceled if a read report had been requested and this call changes the state of the message from unread to read. If this call does not change the state of the message, the message store provider can ignore this flag.

Return value

S_OK

The message's read flag has been successfully set or cleared.

MAPI_E_NO_SUPPRESS

The message store provider does not support the suppression of read reports.

MAPI_E_INVALID_PARAMETER

One of the following combinations of flags is set in the ulFlags parameter:

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG

  • SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

  • CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

Remarks

The IMessage::SetReadFlag method sets or clears the message's MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property and calls IMAPIProp::SaveChanges to save the message. Setting the MSGFLAG_READ flag marks a message as having been read, which does not necessarily indicate that the intended recipient has actually read the message.

SetReadFlags also manages the sending of read reports. A read report is sent only if the sender has requested one.

The read flag cannot be altered for:

  • Messages that do not exist.

  • Messages that have been moved elsewhere.

  • Messages that are open with read/write permission.

  • Messages that are currently submitted.

Notes to Callers

If none of the flags are set in the ulFlags parameter, the following rules apply:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it and send any pending read reports if the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set.

If both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, the PR_READ_RECEIPT_REQUESTED bit, if set, should be cleared and a read report should not be sent.

When the SUPPRESS_RECEIPT flag is set:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it and cancel any pending read reports.

When the CLEAR_READ_FLAG flag is set, clear the MSGFLAG_READ flag in each message's PR_MESSAGE_FLAGS property and do not send any read reports.

When the GENERATE_RECEIPT_ONLY flag is set, send any pending read reports. Do not set or clear MSGFLAG_READ.

When both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, set the PR_READ_RECEIPT_REQUESTED property to FALSE if it is set and do not send a read report.

You can optimize report behavior by suppressing the generation of read reports under certain conditions. However, if you do not support the suppression of reports and a client calls SetReadFlag with the SUPPRESS_RECEIPT flag set, return MAPI_E_NO_SUPPRESS.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnSetReadFlag | MFCMAPI uses theIMessage::SetReadFlag method to set read flags on selected messages.

See also

Reference

IMAPIContainer::OpenEntry
IMAPIFolder::SetReadFlags
IMAPIProp::GetProps
IMAPIProp::SaveChanges
PidTagMessageFlags Canonical Property
IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMessage::SubmitMessage

 Copy code hover
[image]

IMessage::SubmitMessage
See also Send feedback

Published: July 16, 2012

Saves all of the message's properties and marks the message as ready to be sent.

C#
HRESULT SubmitMessage(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Bitmask of flags used to control how a message is submitted. The following flag can be set:

FORCE_SUBMIT

MAPI should submit the message immediately. This flag is not currently in use.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_RECIPIENTS

The message's recipient table is empty.

Remarks

The IMessage::SubmitMessage method marks a message as ready to be transmitted. MAPI passes messages to the underlying messaging system in the order in which they are marked for sending. Because of this functionality, a message might stay in a message store for some time before the underlying messaging system can take responsibility for it. The order of receipt at the destination is in the underlying messaging system's control and does not necessarily match the order in which messages were sent.

Notes to Implementers

Call the message's IMAPIProp::SaveChanges method to save it and then check the message's PR_MESSAGE_FLAGS (PidTagMessageFlags) property. If the MSGFLAG_RESEND flag is set, call IMAPISupport::PrepareSubmit. PrepareSubmit updates the recipient type and PR_RESPONSIBILITY (PidTagResponsibility) property for all of the recipients in the resend message.

Notes to Callers

When SubmitMessage returns, all pointers to the message and its associated subobjects messages, folders, attachments, streams, tables, and so on are no longer valid. MAPI does not permit any further operations on these pointers, except for calling their IUnknown::Release methods. MAPI is designed such that after SubmitMessage is called, you should release the message and all associated subobjects. However, if SubmitMessage returns an error value indicating missing or invalid information, the message remains open and the pointers remain valid.

To cancel a send operation, get and store a pointer to the message's PR_ENTRYID (PidTagEntryId) property before the message is submitted. Because a message's entry identifier is invalidated after the message has been submitted, it is necessary to save it before calling SubmitMessage. To cancel the send, point the lpEntryId parameter to this entry identifier and call IMsgStore::AbortSubmit.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnSubmitMessage | MFCMAPI uses the IMessage::SubmitMessage method to submit the selected message.

See also

Reference

IMsgStore::AbortSubmit
IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMSCapabilities : IUnknown

 Copy code hover
[image]

IMSCapabilities : IUnknown
See also Send feedback

Published: July 16, 2012

Provides information about what a store can support.

Provided by: | Message store provider
Interface identifier: | IID_IMSCapabilities

Vtable Order

GetCapabilities

Returns capabilities of a store based on the specified selection.

Remarks

IMSCapabilities provides information about what a store can support if the store supports this interface.

See also

Concepts

MAPI Interfaces


IMSCapabilities::GetCapabilities

 Copy code hover
[image]

IMSCapabilities::GetCapabilities
Send feedback

Published: July 16, 2012

Gets information about what a store can support based on the specified selector.

C++
ULONG GetCapabilities(
MSCAP_SELECTOR mscapSelector
);

Parameters

mscapSelector

[in] Selector indicating which capabilities to return.

Return value

MSCAP_SECURE_FOLDER_HOMEPAGES

Support for folder homepages in a non-default store. This can be returned if MSCAP_SEL_FOLDER is specified in mscapSelector.

MSCAP_RES_ANNOTATION

If a restriction contains any invalid arguments such as invalid properties, the store ignores the invalid arguments and processes only the valid arguments. This can be returned if MSCAP_SEL_RESTRICTION is specified in mscapSelector.

NULL

The store does not support any capability based on the given selector.


IMsgServiceAdmin : IUnknown

 Copy code hover
[image]

IMsgServiceAdmin : IUnknown
See also Send feedback

Published: July 16, 2012

Makes changes to a message service in a profile.

Header file: | MapiX.h
Exposed by: | Message service administration objects
Implemented by: | MAPI
Called by: | Client applications
Interface identifier: | IID_IMsgServiceAdmin
Pointer type: | LPSERVICEADMIN

Vtable Order

GetLastError

Returns a MAPIERROR structure that contains information about the last error generated by a message service administration object.

GetMsgServiceTable

Provides access to the message service table, a list of the message services in the profile.

CreateMsgService

Adds a message service to the current profile.

Note Note

This method is deprecated. Use IMsgServiceAdmin2::CreateMsgServiceEx instead.

DeleteMsgService

Deletes a message service from a profile.

CopyMsgService

Copies a message service into a profile.

RenameMsgService

Deprecated. Assigns a new name to a message service.

ConfigureMsgService

Reconfigures a message service.

OpenProfileSection

Opens a section of the current profile and returns an IProfSect pointer for further access.

MsgServiceTransportOrder

Sets the order in which transport providers are called to deliver a message.

AdminProviders

Returns a pointer that provides access to a provider administration object.

SetPrimaryIdentity

Designates a message service to be the supplier of the primary identity for the profile.

GetProviderTable

Provides access to the provider table, a listing of the service providers in the profile.

Remarks

An implementation can get a pointer to an IMsgServiceAdmin interface in two ways: by calling the IMAPISession::AdminServices method or by calling the IProfAdmin::AdminServices method. For clients primarily concerned with profile configuration, IProfAdmin::AdminServices is the preferred way to get the IMsgServiceAdmin interface, because it does not log on providers to the MAPI session. If a client requires the ability to make changes to the active profile, then IMAPISession::AdminServices should be called to get the IMsgServiceAdmin pointer. Be aware that although MAPI does not allow a profile that is in use to be deleted, there are no safeguards to prevent a client from removing all the message services in the profile.

See also

Concepts

MAPI Interfaces


IMsgServiceAdmin::AdminProviders

 Copy code hover
[image]

IMsgServiceAdmin::AdminProviders
See also Send feedback

Published: July 16, 2012

Returns a pointer that provides access to a provider administration object.

C++
HRESULT AdminProviders(
  LPMAPIUID lpUID,
  ULONG ulFlags,
  LPPROVIDERADMIN FAR * lppProviderAdmin
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to be administered.

ulFlags

[in] Always NULL.

lppProviderAdmin

[out] A pointer to a pointer to a provider administration object.

Return value

S_OK

The provider administration object was successfully returned.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not exist.

Remarks

The IMsgServiceAdmin::AdminProviders method provides access to a provider administration object. A provider administration is an object that supports the IProviderAdmin interface and enables clients to do the following:

  • Add service providers to a message service.

  • Delete service providers from a message service.

  • Open profile sections.

  • Access the message service provider table.

The types of changes that can actually be made to a message service while the profile is in use depend on the message service. However, most message services do not support changes such as adding and deleting providers while the profile is in use.

Notes to Callers

To retrieve the MAPIUID structure for the message service to administer, retrieve the PR_SERVICE_UID (PidTagServiceUid) property column from the message service's row in the message service table. For more information, see the procedure outlined in the IMsgServiceAdmin::CreateMsgService method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgServiceTableDlg.cpp | CMsgServiceTableDlg::OnDisplayItem | MFCMAPI uses the IMsgServiceAdmin::AdminProviders method to open a provider administration object for a service.

See also

Reference

IProviderAdmin : IUnknown
MAPIUID
IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::ConfigureMsgService

 Copy code hover
[image]

IMsgServiceAdmin::ConfigureMsgService
See also Send feedback

Published: July 16, 2012

Reconfigures a message service.

C++
HRESULT ConfigureMsgService(
  LPMAPIUID lpUID,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG cValues,
  LPSPropValue lpProps
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to configure.

ulUIParam

[in] A handle to the parent window of the configuration property sheet.

ulFlags

[in] A bitmask of flags that controls the display of the property sheet. The following flags can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MSG_SERVICE_UI_READ_ONLY

The message service should display its configuration property sheet but not enable the user to change it. Most message services ignore this flag.

SERVICE_UI_ALLOWED

The message service should display its configuration property sheet only if the service is not completely configured.

SERVICE_UI_ALWAYS

The message service must always display its configuration property sheet. If SERVICE_UI_ALWAYS is not set, a configuration property sheet can still be displayed if SERVICE_UI_ALLOWED is set and valid configuration information is not available from the property value array in the lpProps parameter. Either SERVICE_UI_ALLOWED or SERVICE_UI_ALWAYS must be set for a property sheet to be displayed.

cValues

[in] The count of property values in the SPropValue structure pointed to by lpProps.

lpProps

[in] A pointer to an array of property values that describe the properties to display in the property sheet. The lpProps parameter should not be NULL if the message service should be configured without a user interface.

Return value

S_OK

The message service was successfully configured.

MAPI_E_EXTENDED_ERROR

An error specific to a message service. To get the MAPIERROR structure that describes the error, the client application should call the IMsgServiceAdmin::GetLastError method.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not match that of an existing message service.

MAPI_E_NOT_INITIALIZED

The message service does not have an entry point function.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in the property sheet.

Remarks

The IMsgServiceAdmin::ConfigureMsgService method enables a message service to be configured, with or without a configuration property sheet.

To allow configuration without a property sheet display, message services typically prepare a header file that includes constants for all the required and optional properties and their values.

Notes to Callers

To retrieve the MAPIUID structure for the message service to configure, retrieve the PR_SERVICE_UID (PidTagServiceUid) column from the message service's row in the message service table. For more information, see the procedure outlined in the IMsgServiceAdmin::CreateMsgService method.

You can configure a message service without displaying a property sheet to a user only if you have advance information about the property values to be set. If you are configuring a message service without displaying a property sheet, pass valid property values in the lpProps parameter and do not set the MSG_SERVICE_UI_READ_ONLY, SERVICE_UI_ALLOWED, or SERVICE_UI_ALWAYS flags.

If you receive all or some of the configuration information from the user by way of a property sheet, set SERVICE_UI_ALLOWED in ulFlags. If you use existing property information only to establish default settings and the user is able to change the settings, set SERVICE_UI_ALWAYS in ulFlags.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | HrAddServiceToProfile | MFCMAPI uses the IMsgServiceAdmin::ConfigureMsgService method to configure a service that has been added to a profile.

See also

Reference

MAPIUID
SPropValue
IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::CopyMsgService

 Copy code hover
[image]

IMsgServiceAdmin::CopyMsgService
See also Send feedback

Published: July 16, 2012

Copies a message service into a profile.

SCR
HRESULT CopyMsgService(
  LPMAPIUID lpUID,
  LPSTR lpszDisplayName,
  LPCIID lpInterfaceToCopy,
  LPCIID lpInterfaceDst,
  LPVOID lpObjectDst,
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier of the message service to copy.

lpszDisplayName

[in] This parameter has been deprecated.

lpInterfaceToCopy

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the profile section of the message service to copy. Passing NULL results in the standard profile section interface, IProfSect, being used.

lpInterfaceDst

[in] A pointer to the IID that represents the interface to be used to access the object pointed to by the lpObjectDst parameter. Passing NULL results in the session interface, IMAPISession, being used. The lpInterfaceDst parameter can also be set to IID_IMsgServiceAdmin.

lpObjectDst

[in] A pointer to a pointer to a session or message service administration object. The type of object should correspond to the interface identifier passed in lpInterfaceDst. Valid object pointers are LPMAPISESSION and LPSERVICEADMIN.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays.

ulFlags

[in] A bitmask of flags that controls how the message service is copied. The following flags can be set:

SERVICE_UI_ALWAYS

Requests that the message service always display a configuration property sheet.

Return value

S_OK

The message service was successfully copied.

MAPI_E_NO_ACCESS

The message service is already in the profile and does not allow multiple instances of itself.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpUID does not refer to an existing message service.

Remarks

The IMsgServiceAdmin::CopyMsgService method copies a message service into a profile, either the active profile or another profile. The profile that contains the message service to be copied and the destination do not have to be the same profile, but they can be.

The message service's entry point function is not called for a copy operation. The copied message service has the same configuration settings as its original. To change these settings, a client should call the IMsgServiceAdmin::ConfigureMsgService method.

See also

Reference

IMsgServiceAdmin::ConfigureMsgService
MAPIUID
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin::CreateMsgService

 Copy code hover
[image]

IMsgServiceAdmin::CreateMsgService
See also Send feedback

Published: July 16, 2012

Deprecated: The use of IMsgServiceAdmin2::CreateMsgServiceEx is recommended. Adds a message service to the current profile.

C++
HRESULT CreateMsgService(
  LPSTR lpszService,
  LPSTR lpszDisplayName,
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

lpszService

[in] A pointer to the name of the message service to add. This message service name must appear in the [Services] section of the MapiSvc.inf file.

lpszDisplayName

[in] A pointer to the display name of the message service to add. The lpszDisplayName parameter is ignored if the message service has set the PR_DISPLAY_NAME (PidTagDisplayName) property in the MapiSvc.inf file.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays.

ulFlags

[in] A bitmask of flags that controls how the message service is installed. The following flags can be set:

MAPI_UNICODE

The lpszService and the lpszDisplayName parameters should be cast to LPWSTR and interpreted as Unicode strings.

SERVICE_NO_RESTART_WARNING

When adding a new message service to the profile, the MAPI subsystem, based on various circumstances and criteria, often determines that this action requires a restart of Outlook. If the SERVICE_NO_RESTART_WARNING flag is not included and UI is allowed - based on the SERVICE_UI_ALWAYS and SERVICE_UI_ALLOWED flags - and at least one process is logged onto the current profile, this function displays the message "You must restart Outlook for these changes to take effect." Including the SERVICE_NO_RESTART_WARNING flag suppresses the display of that warning message.

SERVICE_UI_ALLOWED

The message service configuration UI is allowed if needed.

SERVICE_UI_ALWAYS

The message service displays its configuration property sheet.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message service name is not in the [Services] section of MapiSvc.inf.

Remarks

The IMsgServiceAdmin::CreateMsgService method adds a message service to the current profile. CreateMsgService calls the message service's entry point function to perform any service-specific configuration tasks. If the SERVICE_UI_ALLOWED flag is set in the ulFlags parameter, the message service being installed can display a property sheet to enable the user to configure its settings.

The MapiSvc.inf file contains the list of providers that make up a message service and the properties for each. CreateMsgService first creates a new profile section for the message service and then copies all of the information for that service from the MapiSvc.inf file into the profile, creating new sections for each provider.

After all the information has been copied from MapiSvc.inf, the message service's entry point function is called with the MSG_SERVICE_CREATE value set in the ulContext parameter. If the SERVICE_UI_ALLOWED flag is set in the CreateMsgService method's ulFlags parameter, the values in the ulUIParam and ulFlags parameters are also passed when the message service's entry point function is called. Service providers should display their configuration property sheets so users can configure the message service.

Notes to Callers

CreateMsgService does not return the MAPIUID structure for the message service that was added to the profile.

To retrieve the MAPIUID for the created message service, use the following procedure:

  1. Call the IMsgServiceAdmin::GetMsgServiceTable method to get the message service administration table.

  2. Locate the row that represents the message service by placing a restriction on the table that matches the PR_SERVICE_NAME (PidTagServiceName) property with the name of the message service.

  3. Retrieve the service's PR_SERVICE_UID (PidTagServiceUid) property.

  4. Pass the value of the PR_SERVICE_UID property in the lpUid parameter to the IMsgServiceAdmin::ConfigureMsgService method to configure the service.

Caution note Caution

The Microsoft Outlook 2010 implementation of the MAPI subsystem does not support MAPI_UNICODE and will fail if it is used.

Important note Important

The ulFlags SERVICE_NO_RESTART_WARNING might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following value:

#define SERVICE_NO_RESTART_WARNING 0x00000080

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | HrAddServiceToProfile | MFCMAPI uses the IMsgServiceAdmin::CreateMsgService method to add a service to a profile.

See also

Reference

IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::DeleteMsgService

 Copy code hover
[image]

IMsgServiceAdmin::DeleteMsgService
See also Send feedback

Published: July 16, 2012

Deletes a message service from a profile.

C++
HRESULT DeleteMsgService(
  LPMAPIUID lpuid
);

Parameters

lpuid

[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to delete.

Return value

S_OK

The message service was deleted.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by lpuid does not match an existing message service.

Remarks

The IMsgServiceAdmin::DeleteMsgService method deletes a message service from a profile. DeleteMsgService removes all profile sections related to the message service.

DeleteMsgService performs the following steps to delete the message service:

  1. Calls the message service's entry point function with the ulContext parameter set to MSG_SERVICE_DELETE before the profile sections are removed. This allows the service to perform any service-specific tasks.

  2. Deletes the message service.

  3. Deletes the message service's profile section.

The message service's entry point function is not called again after the service has been deleted.

Notes to Callers

To retrieve the MAPIUID structure for the message service to delete, retrieve the PR_SERVICE_UID (PidTagServiceUid) property column from the message service's row in the message service table. For more information, see the procedure outlined in the IMsgServiceAdmin::CreateMsgService method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgServiceTableDlg.cpp | CMsgServiceTableDlg::OnDeleteSelectedItem | MFCMAPI uses the IMsgServiceAdmin::DeleteMsgService method to delete the selected service.

See also

Reference

MAPIUID
IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::GetLastError

 Copy code hover
[image]

IMsgServiceAdmin::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the last error that occurred for a message service administration object.

C#
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated by the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

The MAPI_UNICODE flag was set and the message service administration object does not support Unicode.

Remarks

The IMsgServiceAdmin::GetLastError method retrieves information about the last error that was returned by an IMsgServiceAdmin method call. Clients can provide their users with detailed information about the error by including this information in a dialog box.

Notes to Callers

You can make use of the MAPIERROR structure, if MAPI supplies one, pointed to by the lppMAPIError parameter only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, GetLastError returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin::GetMsgServiceTable

 Copy code hover
[image]

IMsgServiceAdmin::GetMsgServiceTable
See also Send feedback

Published: July 16, 2012

Provides access to the message service table, a list of the message services in the profile.

C++
HRESULT GetMsgServiceTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Always NULL.

lppTable

[out] A pointer to a pointer to the message service table.

Return value

S_OK

The message service table was successfully returned.

Remarks

The IMsgServiceAdmin::GetMsgServiceTable method provides access to the message service table, a table that MAPI maintains that lists the message services currently installed in the session profile. For a complete list of columns in the message service table, see Message Service Table.

The message service table is static. After a client has been given access to it, subsequent message service additions or deletions will not affect it. If there are no message services in the current profile, GetMsgServiceTable returns a table with zero rows.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgServiceTableDlg.cpp | CMsgServiceTableDlg::OnRefreshView | MFCMAPI uses the IMsgServiceAdmin::GetMsgServiceTable method to load the table of services in a profile to render in the view.

See also

Reference

IMsgServiceAdmin::ConfigureMsgService
IMsgServiceAdmin::DeleteMsgService
IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::GetProviderTable

 Copy code hover
[image]

IMsgServiceAdmin::GetProviderTable
See also Send feedback

Published: July 16, 2012

Provides access to the provider table, a listing of the service providers in the profile.

C++
HRESULT GetProviderTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Always NULL.

lppTable

[out] A pointer to a pointer to the provider table.

Return value

S_OK

The provider table was successfully returned.

Remarks

The IMsgServiceAdmin::GetProviderTable method provides access to the MAPI provider table, a table that lists all the address book, message store, and transport providers currently installed in the profile.

Unlike the provider table returned through the IProviderAdmin::GetProviderTable method, the provider table returned through IMsgServiceAdmin::GetProviderTable cannot include additional rows that represent information associated with one or more service providers in the profile.

Providers that have been deleted, or are in use but have been marked for deletion, are not included in the provider table. Provider tables are static, meaning that subsequent additions to or deletions from the profile are not reflected in the table.

If the profile has no providers, GetProviderTable returns a table with zero rows and the S_OK return value.

For a complete list of the columns in the provider table, see Provider Table.

Notes to Callers

To retrieve the rows of a provider table in transport order, use the following procedure:

  1. Call the IMAPITable::Restrict method to impose a property restriction that matches the PR_RESOURCE_TYPE (PidTagResourceType) property with MAPI_TRANSPORT_PROVIDER.

  2. Call the IMAPITable::SortTable method to sort the table by the PR_PROVIDER_ORDINAL (PidTagProviderOrdinal) column.

  3. Call the IMAPITable::QueryRows method to get the rows of the table.

An alternative to these calls is to make a single call to the HrQueryAllRows function with all of the appropriate data structures passed in.

If you retrieve the PR_SERVICE_UID (PidTagServiceUid) columns in each of the rows, you can use this array of MAPIUID structures to set the transport order in a call to IMsgServiceAdmin::MsgServiceTransportOrder.

Setting the MAPI_UNICODE flag in the ulFlags parameter does the following:

  • Sets the string type to Unicode for data returned for the initial active columns of the provider table by the IMAPITable::QueryColumns method. The initial active columns for a provider table are those columns the QueryColumns method returns before the provider that contains the table calls the IMAPITable::SetColumns method.

  • Sets the string type to Unicode for data returned for the initial active rows of the provider table by QueryRows. The initial active rows for a provider table are those rows QueryRows returns before the provider that contains the table calls SetColumns.

  • Controls the property types of the sort order returned by the IMAPITable::QuerySortOrder method before the client that contains the provider table calls the IMAPITable::SortTable method.

See also

Reference

IMsgServiceAdmin::GetMsgServiceTable
IMsgServiceAdmin::MsgServiceTransportOrder
IProviderAdmin::GetProviderTable
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin::MsgServiceTransportOrder

 Copy code hover
[image]

IMsgServiceAdmin::MsgServiceTransportOrder
See also Send feedback

Published: July 16, 2012

Sets the order in which transport providers are called to deliver a message.

C++
HRESULT MsgServiceTransportOrder(
  ULONG cUID,
  LPMAPIUID lpUIDList,
  ULONG ulFlags
);

Parameters

cUID

[in] The count of unique identifiers in the lpUIDList parameter.

lpUIDList

[in] A pointer to an array of unique identifiers that represent transport providers. The array contains one identifier for each transport provider configured in the current profile.

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The transport order was set successfully.

MAPI_E_BUSY

The value in the cUID parameter differs from the number of transport providers actually in the profile.

MAPI_E_NOT_FOUND

One or more of the MAPIUID structures passed in the lpUIDList parameter do not refer to a transport provider currently in the profile.

Remarks

The IMsgServiceAdmin::MsgServiceTransportOrder method sets the delivery order of transport providers in a profile. The lpUIDList parameter must contain a sorted list of transport-provider entry identifiers obtained from the PR_PROVIDER_UID (PidTagProviderUid) property of the table returned from the IMsgServiceAdmin::GetProviderTable method. A client application must pass the complete list in lpUIDList.

SetTransportOrder overrides transport provider preferences such as the STATUS_XP_PREFER_LAST flag set in the PR_RESOURCE_FLAGS (PidTagResourceFlags) property.

See also

Reference

MAPIUID
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin::OpenProfileSection

 Copy code hover
[image]

IMsgServiceAdmin::OpenProfileSection
See also Send feedback

Published: July 16, 2012

Opens a section of the current profile and returns an IProfSect pointer for further access.

C++
HRESULT OpenProfileSection(
  LPMAPIUID lpUID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPPROFSECT FAR * lppProfSect
);

Parameters

lpUID

A pointer to the MAPIUID structure that identifies the profile section.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the profile section. Passing NULL results in a pointer to its standard interface being returned in the lppProfSect parameter. The standard interface for a profile section is IProfSect.

ulFlags

[in] A bitmask of flags that controls access to the profile section. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows OpenProfileSection to return successfully, possibly before the profile section is fully available to the calling client. If the profile section is not available, making a subsequent call to it can raise an error.

MAPI_MODIFY

Requests read/write permission. By default, profile sections are opened with read-only permission, and clients should not work on the assumption that read/write permission has been granted.

MAPI_FORCE_ACCESS

Allows access to all profile sections, even those owned by individual service providers.

lppProfSect

[out] A pointer to a pointer to the profile section.

Return value

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to access a profile section for which the caller has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IMsgServiceAdmin::OpenProfileSection method opens a profile section, an object that supports the IProfSect interface. Profile sections are used for reading information from and writing information to the session profile.

OpenProfileSection cannot be used to open profile sections owned by individual service providers unless MAPI_FORCE_ACCESS is used.

Notes to Callers

Multiple clients can open a profile section with read-only permission, but only one client can open a profile section with read/write permission. If another client has a profile section open that you attempt to open by calling OpenProfileSection with the MAPI_MODIFY flag set, the call will fail, returning MAPI_E_NO_ACCESS.

A read-only open operation fails if the section is open for writing.

You can create a profile section by calling OpenProfileSection with the MAPI_MODIFY flag and a nonexistent MAPIUID structure in the lpUID parameter. Be sure you specify MAPI_MODIFY. If you set lpUID to point to a nonexistent MAPIUID and OpenProfileSection is set to use the default access mode of read-only, the call will fail with MAPI_E_NOT_FOUND.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | OpenProfileSection | MFCMAPI uses the IMsgServiceAdmin::OpenProfileSection method to open a profile section.

See also

Reference

IMAPIProp : IUnknown
IMAPISession::OpenProfileSection
IProfSect : IMAPIProp
MAPIUID
IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IMsgServiceAdmin::RenameMsgService

 Copy code hover
[image]

IMsgServiceAdmin::RenameMsgService
See also Send feedback

Published: July 16, 2012

Deprecated. Assigns a new name to a message service.

C++
HRESULT RenameMsgService(
  LPMAPIUID lpUID,
  ULONG ulFlags,
  LPSTR lpszDisplayName
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to rename.

ulFlags

[in] Reserved; must be zero.

lpszDisplayName

[in] A pointer to the new name for the message service.

Return value

MAPI_E_NO_SUPPORT

MAPI does not support renaming this message service. RenameMsgService always returns this value.

Remarks

To assign a new name to a message service, clients should use the PR_SERVICE_NAME (PidTagServiceName) property of the message service. The names of service providers in a message service are stored in their PR_DISPLAY_NAME (PidTagDisplayName) properties.

See also

Reference

MAPIUID
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin::SetPrimaryIdentity

 Copy code hover
[image]

IMsgServiceAdmin::SetPrimaryIdentity
See also Send feedback

Published: July 16, 2012

Designates a message service to be the supplier of the primary identity for the profile.

C++
HRESULT SetPrimaryIdentity(
  LPMAPIUID lpUID,
  ULONG ulFlags
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to supply the primary identity, or NULL, which indicates that SetPrimaryIdentity should clear the current identity.

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The message service was successfully assigned the supplier of the primary identity.

MAPI_E_NO_ACCESS

SetPrimaryIdentity attempted to designate a message service that has the SERVICE_NO_PRIMARY_IDENTITY flag set in its PR_RESOURCE_FLAGS (PidTagResourceFlags) property.

Remarks

The IMsgServiceAdmin::SetPrimaryIdentity method establishes a message service as the supplier of the primary identity for the profile. The primary identity is typically the user who is logged on to the message service. It is represented by three properties:

  • PR_IDENTITY_DISPLAY (PidTagIdentityDisplay)

  • PR_IDENTITY_ENTRYID (PidTagIdentityEntryId)

  • PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey)

Every service provider in the designated message service sets these three properties to the display name, entry identifier, and search key of the messaging user that supplies the primary identity. Clients can retrieve the primary identity's entry identifier by calling the IMAPISession::QueryIdentity method.

The PR_RESOURCE_FLAGS property is set to STATUS_PRIMARY_IDENTITY for every provider that is a member of the message service that supplies the primary identity, and to SERVICE_PRIMARY_IDENTITY for the message service. When a service provider cannot supply the primary identity for its message service, it sets PR_RESOURCE_FLAGS to STATUS_NO_PRIMARY_IDENTITY. SetPrimaryIdentity sets the PR_RESOURCE_FLAGS property of each message service that is not supplying the primary identity to SERVICE_NO_PRIMARY_IDENTITY.

Each message service provider that MAPI has information about can establish an identity for each of its users when a client logs on to the service. However, because MAPI supports connections to multiple service providers for each MAPI session, there is no firm definition of a particular user's identity for the MAPI session as a whole; a user's identity depends on which service is involved. Clients can call SetPrimaryIdentity to designate one of the many identities established for a user by message services as the primary identity for that user.

See also

Reference

IMAPISession::QueryIdentity
MAPIUID
IMsgServiceAdmin : IUnknown


IMsgServiceAdmin2 : IMsgServiceAdmin

 Copy code hover
[image]

IMsgServiceAdmin2 : IMsgServiceAdmin
See also Send feedback

Published: July 16, 2012

Makes changes to a message service in a profile.

Header file: | Mapiaux.h
Exposed by: | Message service administration objects
Implemented by: | MAPI
Called by: | Client applications
Interface identifier: | IID_IMsgServiceAdmin2
Pointer type: | LPSERVICEADMIN2

Vtable Order

CreateMsgServiceEx

Adds a message service to the current profile and returns that newly added service UID.

Remarks

The IMsgServiceAdmin2 interface is exposed by the same objects that expose the IMsgServiceAdmin interface, and has been available using Outlook's implementation of the MAPI subsystem since Microsoft Outlook 2003.

See also

Concepts

MAPI Interfaces


IMsgServiceAdmin2::CreateMsgServiceEx

 Copy code hover
[image]

IMsgServiceAdmin2::CreateMsgServiceEx
See also Send feedback

Published: July 16, 2012

Adds a message service to the current profile and returns that newly added service UID.

C++
HRESULT CreateMsgServiceEx(
  LPSTR lpszService,
  LPSTR lpszDisplayName,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPMAPIUID lpuidService
);

Parameters

lpszService

[in] A pointer to the name of the message service to add. This message service name must appear in the [Services] section of the MapiSvc.inf file.

lpszDisplayName

[in] A pointer to the display name of the message service to add. The lpszDisplayName parameter is ignored if the message service has set the PR_DISPLAY_NAME (PidTagDisplayName) property in the MapiSvc.inf file.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays.

ulFlags

[in] A bitmask of flags that controls how the message service is installed. The following flags can be set:

MAPI_UNICODE

The lpszService and the lpszDisplayName parameters should be cast to LPWSTR and interpreted as Unicode strings.

SERVICE_NO_RESTART_WARNING

When adding a new message service to the profile, the MAPI subsystem, based on various circumstances and criteria, often determines that this action requires a restart of Outlook. If the SERVICE_NO_RESTART_WARNING flag is not included and UI is allowed - based on the SERVICE_UI_ALWAYS and SERVICE_UI_ALLOWED flags - and at least one process is logged onto the current profile, this function displays the message "You must restart Outlook for these changes to take effect." Including the SERVICE_NO_RESTART_WARNING flag suppresses the display of that warning message.

SERVICE_UI_ALLOWED

The message service configuration UI is allowed if needed.

SERVICE_UI_ALWAYS

The message service displays its configuration property sheet.

lpuidService

[out] The pointer to the UID of the message service added.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message service name is not in the [Services] section of MapiSvc.inf.

Remarks

The IMsgServiceAdmin2::CreateMsgServiceEx method adds a message service to the current profile. CreateMsgServiceEx calls the message service's entry point function to perform any service-specific configuration tasks. If the SERVICE_UI_ALLOWED flag is set in the ulFlags parameter, the message service being installed can display a property sheet enabling the user to configure its settings.

The MapiSvc.inf file contains the list of providers that make up a message service and the properties for each. CreateMsgServiceEx first creates a new profile section for the message service and then copies all of the information for that service from the MapiSvc.inf file into the profile, creating new sections for each provider.

After all the information has been copied from MapiSvc.inf, the message service's entry point function, MSGSERVICEENTRY, is called with the MSG_SERVICE_CREATE value set in the ulContext parameter. If the SERVICE_UI_ALLOWED flag is set in the CreateMsgServiceEx method's ulFlags parameter, the values in the ulUIParam and ulFlags parameters are also passed when the message service's entry point function is called. Service providers should display their configuration property sheets so users can configure the message service.

Notes to Callers

If the CreateMsgServiceExlpuidService argument is not NULL, the PR_SERVICE_UID (PidTagServiceUid) property of the message service that was added to the profile is returned in the GUID to which it points.

Pass the value of the PR_SERVICE_UID property in the lpuidService parameter to the IMsgServiceAdmin::ConfigureMsgService method to configure the service.

Caution note Caution

The Microsoft Outlook 2010 implementation of the MAPI subsystem does not support MAPI_UNICODE and will fail if it is used.

Important note Important

The IMsgServiceAdmin2 interface is exposed by the same object that implements the IMsgServiceAdmin interface, and has been available using Outlook's implementation of the MAPI subsystem since Outlook 2003. Its IID is defined as follows:

#if !defined(INITGUID) || defined(USES_IID_IMsgServiceAdmin2)

DEFINE_OLEGUID(IID_IMsgServiceAdmin2,0x00020387, 0, 0);

The ulFlags SERVICE_NO_RESTART_WARNING might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following value:

#define SERVICE_NO_RESTART_WARNING 0x00000080

See also

Reference

IMsgServiceAdmin2 : IMsgServiceAdmin

Concepts

MFCMAPI as a Code Sample


IMsgStore : IMAPIProp

 Copy code hover
[image]

IMsgStore : IMAPIProp
See also Send feedback

Published: July 16, 2012

Provides access to message store information and to messages and folders.

Header file: | Mapidefs.h
Exposed by: | Message store object
Implemented by: | Message store providers
Called by: | Client applications, the MAPI spooler, and MAPI
Interface identifier: | IID_IMsgStore
Pointer type: | LPMDB
Transaction model: | Nontransacted

Vtable Order

Advise | Registers to receive notification of specified events that affect the message store.
Unadvise | Cancels the sending of notifications previously set up with a call to the IMsgStore::Advise method.
CompareEntryIDs | Compares two entry identifiers to determine whether they refer to the same entry in a message store.
OpenEntry | Opens a folder or message and returns an interface pointer for further access.
SetReceiveFolder | Establishes a folder as the destination for incoming messages of a particular message class.
GetReceiveFolder | Obtains the folder that was established as the destination for incoming messages of a specified message class or as the default receive folder for the message store.
GetReceiveFolderTable | Provides access to the receive folder table, a table with information about all of the receive folders for the message store.
StoreLogoff | Enables the orderly logoff of the message store.
AbortSubmit | Attempts to remove a message from the outgoing queue.
GetOutgoingQueue | Provides access to the outgoing queue table, a table that has information about all of the messages in the message store's outgoing queue.
SetLockState | Locks or unlocks a message.
FinishedMsg | Enables the message store provider to perform processing on a sent message.
NotifyNewMail | Informs the message store that a new message has arrived.
Required properties | Access level
PR_DISPLAY_NAME (PidTagDisplayName) | Read/write
PR_ENTRYID (PidTagEntryId) | Read-only
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_RECORD_KEY (PidTagRecordKey) | Read-only
PR_STORE_ENTRYID (PidTagStoreEntryId) | Read-only
PR_STORE_RECORD_KEY (PidTagStoreRecordKey) | Read-only
PR_MDB_PROVIDER (PidTagStoreProvider) | Read-only
PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) | Read-only

The following properties are for interpersonal message (IPM) message stores:

  • PR_IPM_OUTBOX_ENTRYID (PidTagIpmOutboxEntryId)

  • PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId)

  • PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId)

  • PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId)

  • PR_MDB_PROVIDER

  • PR_STORE_SUPPORT_MASK

See also

Concepts

MAPI Properties


IMsgStore::AbortSubmit

 Copy code hover
[image]

IMsgStore::AbortSubmit
See also Send feedback

Published: July 16, 2012

Attempts to remove a message from the outgoing queue.

C++
AbortSubmit(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the message to remove from the outgoing queue.

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The message was successfully removed from the outgoing queue.

MAPI_E_NOT_IN_QUEUE

The message identified by lpEntryID is no longer in the message store's outgoing queue, typically because it has already been sent.

MAPI_E_UNABLE_TO_ABORT

The message identified by lpEntryID is locked by the MAPI spooler, and the operation cannot be aborted.

Remarks

The IMsgStore::AbortSubmit method attempts to remove a submitted message from the message store's outgoing queue.

Notes to Callers

After a message is submitted, aborting the submission by calling AbortSubmit is the only action that can be performed on the message. Do not expect AbortSubmit to always succeed. Depending on how the underlying messaging system is implemented, it might not be possible to cancel the sending of the message.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
FolderDlg.cpp | CFolderDlg::OnAbortSubmit | MFCMAPI uses the IMsgStore::AbortSubmit method to abort the submission of the selected message.

See also

Reference

IMessage::SubmitMessage
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::Advise

 Copy code hover
[image]

IMsgStore::Advise
See also Send feedback

Published: July 16, 2012

Registers to receive notification of specified events that affect the message store.

C++
HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG_PTR lpulConnection
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the folder or message about which notifications should be generated, or null. If lpEntryID is set to NULL, Advise registers for notifications on the entire message store.

ulEventMask

[in] A mask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event. The following are valid values for the ulEventMask parameter:

fnevCriticalError

Registers for notifications about severe errors, such as insufficient memory.

fnevExtended

Registers for notifications about events specific to the particular message store provider.

fnevNewMail

Registers for notifications about the arrival of new messages.

fnevObjectCreated

Registers for notifications about the creation of a new folder or message.

fnevObjectCopied

Registers for notifications about a folder or message being copied.

fnevObjectDeleted

Registers for notifications about a folder or message being deleted.

fnevObjectModified

Registers for notifications about a folder or message being modified.

fnevObjectMoved

Registers for notifications about a folder or message being moved.

fnevSearchComplete

Registers for notifications about the completion of a search operation.

lpAdviseSink

[in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] A pointer to a nonzero number that represents the connection between the caller's advise sink object and the session.

lpAdviseSink

[in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.

lpulConnection

[out] A pointer to a nonzero connection number that represents the connection between the caller's advise sink object and the message store.

Return value

S_OK

The registration was successful.

MAPI_E_NO_SUPPORT

The message store provider does not support registration for notification through the message store.

Remarks

The IMsgStore::Advise method establishes a connection between the caller's advise sink object and either the message store or an object in the message store. This connection is used to send notifications to the advise sink when one or more events, as specified in the ulEventMask parameter, occur to the advise source object. When the lpEntryID parameter points to a valid entry identifier, the advise source is the object identified by this entry identifier. When lpEntryID is NULL, the advise source is the message store.

To send a notification, either the message store provider or MAPI calls the registered advise sink's IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.

Notes to Implementers

You can support notification with or without help from MAPI. MAPI has three support object methods for helping service providers implement notification: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.

If you elect to support notification yourself, call the IUnknown::AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IMsgStore::Unadvise method is called to cancel the registration.

Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until Unadvise has been called and has completed.

Notes to Callers

On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you must be assured that notifications occur only at a particular time on a particular thread, call the HrThisThreadAdviseSink function to generate the advise sink object that you pass to Advise.

After a call to Advise has succeeded and before Unadvise has been called to cancel the registration, be prepared for the advise sink object to be released. You should release your advise sink object after Advise returns unless you have a specific long-term use for it.

For more information about the notification process, see Event Notification in MAPI.

For more information about handling notifications, see Handling Notifications.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
BaseDialog.cpp | CBaseDialog::OnNotificationsOn | MFCMAPI uses the IMsgStore::Advise method to register for notifications on the entire message store.

See also

Reference

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMsgStore::Unadvise
NOTIFICATION
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::CompareEntryIDs

 Copy code hover
[image]

IMsgStore::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers to determine whether they refer to the same entry in a message store. MAPI passes this call to a service provider only if the unique identifiers (UIDs) in both entry identifiers to be compared are handled by that provider.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The byte count in the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The byte count in the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the result of the comparison. TRUE if the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The comparison was successful.

MAPI_E_UNKNOWN_ENTRYID

One or both of the entry identifiers specified as parameters do not refer to objects, possibly because the corresponding objects are unopened and unavailable at present.

Remarks

The IMsgStore::CompareEntryIDs method compares two entry identifiers that belong to the message store to determine whether they refer to the same object.

Notes to Callers

CompareEntryIDs is useful because an object can have more than one valid entry identifier (for example, after a new version of a message store provider is installed).

If CompareEntryIDs returns an error, do not take any action based on the result of the comparison. Instead, take the most conservative approach possible. CompareEntryIDs might fail if, for example, one or both of the entry identifiers contains an invalid MAPIUID.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
BaseDialog.cpp | CBaseDialog::OnCompareEntryIDs | MFCMAPI uses the IMsgStore::CompareEntryIDs method to compare entry IDs.

See also

Reference

MAPIUID
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::FinishedMsg

 Copy code hover
[image]

IMsgStore::FinishedMsg
See also Send feedback

Published: July 16, 2012

Enables the message store provider to perform processing on a sent message. This method is called only by the MAPI spooler.

C++
HRESULT FinishedMsg(
  ULONG ulFlags,
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

ulFlags

[in] Reserved; must be zero.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the message to be processed.

Return value

S_OK

Processing on the sent message was successful.

MAPI_E_NO_SUPPORT

The message store provider does not support sent message processing. This error value is returned if the caller is not the MAPI spooler.

Remarks

The IMsgStore::FinishedMsg method performs processing on a sent message. This processing can involve deleting the message, moving it to a different folder, or both actions. The type of processing depends on whether the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) and PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) properties are set.

Notes to Implementers

In your implementation of FinishedMsg, unlock the message identified by lpEntryID and perform the appropriate processing. The target message will always be locked; the MAPI spooler never passes the entry identifier for an unlocked message to FinishedMsg.

It is possible that neither PR_DELETE_AFTER_SUBMIT or PR_SENTMAIL_ENTRYID is set, both are set, or one or the other is set. The following table describes the action you should take based on the settings:

If neither property is set: | Leave the message in the folder from which it was sent (typically the Outbox).
If both properties are set: | Move the message to the indicated folder, if desired, and then delete it.
If PR_SENTMAIL_ENTRYID is set: | Move the message to the indicated folder.
If PR_DELETE_AFTER_SUBMIT is set: | Delete the message.

After you have taken whatever action is appropriate, call the IMAPISupport::DoSentMail method.

See also

Reference

IMAPISupport::DoSentMail
IMsgStore : IMAPIProp


IMsgStore::GetOutgoingQueue

 Copy code hover
[image]

IMsgStore::GetOutgoingQueue
See also Send feedback

Published: July 16, 2012

Provides access to the outgoing queue table, a table that has information about all of the messages in the message store's outgoing queue. This method is called only by the MAPI spooler.

C++
HRESULT GetOutgoingQueue(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Reserved; must be zero.

lppTable

[out] A pointer to a pointer to the outgoing queue table.

Return value

S_OK

The outgoing queue table was successfully returned.

Remarks

The IMsgStore::GetOutgoingQueue method provides the MAPI spooler with access to the table that shows the message store's queue of outgoing messages. Typically, messages are placed in the outgoing queue table after their IMessage::SubmitMessage method is called. However, because the order of submission affects the order of preprocessing and submission to the transport provider, some messages that have been marked for sending might not appear in the outgoing queue table immediately.

Notes to Implementers

For a list of the properties that must be included as columns in your outgoing queue table, see Outgoing Queue Tables.

Because the MAPI spooler is designed to accept messages from a message store in ascending order of submission time, either allow the MAPI spooler to sort the outgoing queue table to match this order or establish it as the default sort order.

You must support notifications for the outgoing message queue table, ensuring that the MAPI spooler is notified when the contents of the queue change.

See also

Reference

IMessage::SubmitMessage
IMsgStore : IMAPIProp


IMsgStore::GetReceiveFolder

 Copy code hover
[image]

IMsgStore::GetReceiveFolder
See also Send feedback

Published: July 16, 2012

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

C++
HRESULT GetReceiveFolder(
  LPSTR lpszMessageClass,
  ULONG ulFlags,
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID,
  LPSTR FAR * lppszExplicitClass
);

Parameters

lpszMessageClass

[in] A pointer to a message class that is associated with a receive folder. If the lpszMessageClass parameter is set to NULL or an empty string, GetReceiveFolder returns the default receive folder for the message store.

ulFlags

[in] A bitmask of flags that controls the type of the passed-in and returned strings. The following flag can be set:

MAPI_UNICODE

The message class string is in Unicode format. If the MAPI_UNICODE flag is not set, the message class string is in ANSI format.

lpcbEntryID

[out] A pointer to the byte count in the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[out] A pointer to a pointer to the entry identifier for the requested receive folder.

lppszExplicitClass

[out] A pointer to a pointer to the message class that explicitly sets as its receive folder the folder pointed to by lppEntryID. This message class should either be the same as the class in the lpszMessageClass parameter, or a base class of that class. Passing NULL indicates that the folder pointed to by lppEntryID is the default receive folder for the message store.

Return value

S_OK

The receive folder was successfully returned.

Remarks

The IMsgStore::GetReceiveFolder method obtains the entry identifier of a receive folder, a folder designated to receive incoming messages of a particular message class. Callers can specify a message class or NULL in the lpszMessageClass parameter. If lpszMessageClass is NULL, GetReceiveFolder returns the following values:

  • In lppszExplicitClass, the name of the first base class of the message class pointed to by lpszMessageClass that does explicitly set a receive folder.

  • In lppEntryID, the entry identifier of the receive folder for the base class pointed to by the lppszExplicitClass parameter.

For example, suppose the receive folder of the message class IPM.Note has been set to the entry identifier of the Inbox and GetReceiveFolder is called with the contents of lpszMessageClass set to IPM.Note.Phone. If IPM.Note.Phone does not have an explicit receive folder set, GetReceiveFolder returns the entry identifier of the Inbox in lppEntryID and IPM.Note in lppszExplicitClass.

If the client calls GetReceiveFolder for a message class and has not set a receive folder for that message class, lppszExplicitClass is either a zero-length string, a string in Unicode format, or a string in ANSI format depending on whether the client set the MAPI_UNICODE flag in the ulFlags parameter.

A default receive folder, obtained by passing NULL in the lpszMessageClass parameter, always exists for every message store.

A client should call the MAPIFreeBuffer function when it is done with the entry identifier returned in lppEntryID to free the memory that holds that entry identifier. It should also call MAPIFreeBuffer when it is done with the message class string returned in lppszExplicitClass to free the memory that holds that string.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | GetInbox | MFCMAPI uses the IMsgStore::GetReceiveFolder method to locate the Inbox folder.

See also

Reference

MAPIFreeBuffer
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::GetReceiveFolderTable

 Copy code hover
[image]

IMsgStore::GetReceiveFolderTable
See also Send feedback

Published: July 16, 2012

Provides access to the receive folder table, a table that includes information about all of the receive folders for the message store.

C++
HRESULT GetReceiveFolderTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable );

Parameters

ulFlags

[in] A bitmask of flags that controls table access. The following flags can be set:

MAPI_DEFERRED_ERRORS

Allows GetReceiveFolderTable to return successfully, possibly before the table is fully available to the caller. If the table is not fully available, making a subsequent table call can raise an error.

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppTable

[out] A pointer to a pointer to the receive folder table.

Return value

S_OK

The receive folder table was successfully returned.

Remarks

The IMsgStore::GetReceiveFolderTable method provides access to a table that shows the property settings for all of the message store's receive folders.

Notes to Implementers

For a list of required columns in a receive folder table, see Receive Folder Tables.

Implement your receive folder tables to support setting property restrictions on the PR_RECORD_KEY (PidTagRecordKey) property. This enables easy access to particular receive folders.

Notes to Callers

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the IMAPITable::QueryColumns and IMAPITable::QueryRows methods. This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnDisplayReceiveFolderTable | MFCMAPI uses the IMsgStore::GetReceiveFolderTable method to get the receive folder table to display.

See also

Reference

IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::QuerySortOrder
IMAPITable::SetColumns
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::NotifyNewMail

 Copy code hover
[image]

IMsgStore::NotifyNewMail
See also Send feedback

Published: July 16, 2012

Informs the message store that a new message has arrived. This method is called only by the MAPI spooler.

C++
HRESULT NotifyNewMail(
  LPNOTIFICATION lpNotification
);

Parameters

lpNotification

[in] A pointer to a NOTIFICATION structure that describes the new message notification.

Return value

S_OK

The message store was successfully notified.

Remarks

The IMsgStore::NotifyNewMail method is called by the MAPI spooler to inform the message store that a message is ready for delivery.

Notes to Implementers

When NotifyNewMail is called, send a new mail notification to all registered clients. You can send the notification by calling IMAPISupport::Notify, if you elect to use the support object methods, or by using your own implementation. A registered client is one that has called IMsgStore::Advise and set the lpEntryID parameter to NULL and the ulEventMask parameter to fnevNewMail.

Do not modify or free the memory for the NOTIFICATION structure that describes the new mail notification. Copy the NOTIFICATION structure by calling the utility function ScCopyNotifications to make use of the information in its members.

See also

Reference

IMAPISupport::Subscribe
IMAPISupport::Unsubscribe
NOTIFICATION
ScCopyNotifications
IMsgStore : IMAPIProp


IMsgStore::OpenEntry

 Copy code hover
[image]

IMsgStore::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens a folder or message and returns an interface pointer for further access.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object to open, or NULL. If lpEntryID is set to NULL, OpenEntry opens the root folder for the message store.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the opened object. Passing NULL results in the object's standard interface (IMAPIFolder for folders and IMessage for messages) being returned.

ulFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be used:

MAPI_BEST_ACCESS

Requests that the object be opened by using the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write permission, the object should be opened by using read/write permission; if the client has read-only permission, the object should be opened by using read-only permission.

MAPI_DEFERRED_ERRORS

Allows OpenEntry to return successfully, possibly before the object is fully available to the calling client. If the object is not available, making a subsequent object call can raise an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only permission, and clients should not work on the assumption that read/write permission is granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppUnk

[out] A pointer to a pointer to the opened object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.

MAPI_NO_CACHE

When a store is opened in cached mode, a client or service provider can call IMsgStore::OpenEntry, setting the MAPI_NO_CACHE flag to open an item or a folder on the remote store. If you open the message store with the MDB_ONLINE flag on the remote server, you do not have to use the MAPI_NO_CACHE flag.

Remarks

The IMsgStore::OpenEntry method opens a folder or message and returns a pointer to an interface that can be used for further access.

Important note Important

When opening folder entries on a public store, such as folders and messages, use IMsgStore::OpenEntry instead of IMAPISession::OpenEntry. This ensures that public folders function correctly when multiple Exchange accounts are defined in a profile.

Notes to Callers

Folders and messages are automatically opened with read-only permission, unless you set the MAPI_MODIFY or MAPI_BEST_ACCESS flag in the ulFlags parameter. Setting one of these flags does not guarantee a particular type of permission; the permissions that you are granted depend on the message store provider, your access level, and the object. To determine the access level of the opened object, retrieve its PR_ACCESS_LEVEL (PidTagAccessLevel) property.

Although IMsgStore::OpenEntry can be used to open any folder or message, it is usually faster to use the IMAPIContainer::OpenEntry method if you have access to the parent folder of the folder or message to be opened.

Check the value returned in the lpulObjType parameter to determine whether the returned object type is what you expected. If the object type is not the expected type, cast the pointer from the lppUnk parameter to a pointer of the appropriate type. For example, if you are opening a folder, cast lppUnk to a pointer of type LPMAPIFOLDER.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | CallOpenEntry | MFCMAPI uses the IMsgStore::OpenEntry method to open the object associated with an entry ID.

See also

Reference

IMAPIContainer::OpenEntry
IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::SetLockState

 Copy code hover
[image]

IMsgStore::SetLockState
See also Send feedback

Published: July 16, 2012

Locks or unlocks a message. This method is called only by the MAPI spooler.

C++
HRESULT SetLockState(
  LPMESSAGE lpMessage,
  ULONG ulLockState
);

Parameters

lpMessage

[in] A pointer to the message to lock or unlock.

ulLockState

[in] A value that indicates whether the message should be locked or unlocked. One of the following values is valid:

MSG_LOCKED

The message should be locked.

MSG_UNLOCKED

The message should be unlocked.

Return value

S_OK

The lock state of the message was successfully set.

Remarks

The IMsgStore::SetLockState method locks or unlocks a message. SetLockState can be called only by the MAPI spooler while it is sending the message.

Usually, when the MAPI spooler calls SetLockState to lock a message, it locks only the oldest message (that is, the next message queued for the MAPI spooler to send). If the oldest message in the queue is waiting for a temporarily unavailable transport provider, and the next message in the queue uses a different transport provider, the MAPI spooler can begin processing the later message. It begins processing by locking that message by using SetLockState.

Notes to Implementers

After the MAPI spooler has called SetLockState with the ulLockState parameter set to MSG_LOCKED, calls to the IMsgStore::AbortSubmit method to cancel the message's transmission must fail.

Call the message's IMAPIProp::SaveChanges method in your SetLockState implementation so that any changes that were made to the message before the SetLockState call was received are saved.

See also

Reference

IMsgStore::AbortSubmit
IMsgStore::FinishedMsg
IMsgStore : IMAPIProp


IMsgStore::SetReceiveFolder

 Copy code hover
[image]

IMsgStore::SetReceiveFolder
See also Send feedback

Published: July 16, 2012

Establishes a folder as the destination for incoming messages of a particular message class.

C++
HRESULT SetReceiveFolder(
  LPSTR lpszMessageClass,
  ULONG ulFlags,
  ULONG cbEntryID,
  LPENTRYID lpEntryID
);

Parameters

lpszMessageClass

[in] A pointer to the message class that is to be associated with the new receive folder. If the lpszMessageClass parameter is set to NULL or an empty string, SetReceiveFolder sets the default receive folder for the message store.

ulFlags

[in] A bitmask of flags that controls the type of the text in the passed-in strings. The following flag can be set:

MAPI_UNICODE

The message class string is in Unicode format. If the MAPI_UNICODE flag is not set, the message class string is in ANSI format.

cbEntryID

[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the folder to establish as the receive folder. If the lpEntryID parameter is set to NULL, SetReceiveFolder replaces the current receive folder with the message store's default.

Return value

S_OK

A receive folder was successfully established.

Remarks

The IMsgStore::SetReceiveFolder method sets or changes the receive folder for a particular message class. With SetReceiveFolder, a client can, by using successive calls, specify a different receive folder for each defined message class or specify that incoming messages for multiple message classes all go to the same folder. For example, a client can have its own class of messages arrive in its own folder. A fax application can designate one folder in which the store provider puts incoming faxes and another folder in which the provider puts outgoing faxes.

If an error occurs during the call to SetReceiveFolder, the receive folder setting remains unchanged.

If SetReceiveFolder changes the receive folder setting with lpEntryID set to NULL, indicating that the default receive folder should be set, SetReceiveFolder returns S_OK even if there was no existing setting for the indicated message class.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgStoreDlg.cpp | CMsgStoreDlg::OnSetReceiveFolder | MFCMAPI uses the IMsgStore::SetReceiveFolder method to set a folder as the receive folder for a particular message class.

See also

Reference

IMsgStore : IMAPIProp

Concepts

MFCMAPI as a Code Sample


IMsgStore::StoreLogoff

 Copy code hover
[image]

IMsgStore::StoreLogoff
See also Send feedback

Published: July 16, 2012

Enables the orderly logoff of the message store.

C++
HRESULT StoreLogoff(
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[in, out] A bitmask of flags that controls logoff from the message store. On input, all flags set for this parameter are mutually exclusive; a caller must specify only one flag per call. The following flags are valid on input:

LOGOFF_ABORT

Any transport provider activity for this message store should be stopped before logoff. Control is returned to the caller after activity is stopped. If any transport provider activity is taking place, the logoff does not occur and no change in the behavior of the MAPI spooler or transport providers occurs. If transport provider activity is idle, the MAPI spooler releases the store.

LOGOFF_NO_WAIT

The message store should not wait for messages from transport providers before closing. Outbound messages that are ready to be sent are sent. If this store contains the default Inbox, any in-process messages are received, and then further reception is disabled. When all activity is complete, the MAPI spooler releases the store, and control is immediately returned to the caller.

LOGOFF_ORDERLY

The message store should not wait for information from transport providers before closing. Messages that are currently being processed are completed, but no new messages are processed. When all activity is complete, the MAPI spooler releases the store, and control is immediately returned to the store provider.

LOGOFF_PURGE

The logoff should work the same as if the LOGOFF_NO_WAIT flag is set, but either the IXPLogon::FlushQueues or IMAPIStatus::FlushQueues method for the appropriate transport providers should be called. The LOGOFF_PURGE flag returns control to the caller after completion.

LOGOFF_QUIET

If any transport provider activity is taking place, the logoff should not occur.

The following flags are valid on output:

LOGOFF_INBOUND

Inbound messages are currently arriving.

LOGOFF_OUTBOUND

Outbound messages are in the process of being sent.

LOGOFF_OUTBOUND_QUEUE

Outbound messages are pending (that is, they are in the Outbox).

Return value

S_OK

The logoff completed successfully.

Remarks

The IMsgStore::StoreLogoff method exerts control over the interaction of the message store and transport providers during the logoff process. Calling StoreLogoff is valid only for message stores that are being used only by the caller. For example, when two clients are using the same message store and one of them calls StoreLogoff, the message store is immediately released and control is returned to the calling client.

Notes to Implementers

Save the flags that are passed to StoreLogoff and pass them when you call the IMAPISupport::StoreLogoffTransports method. Do not call StoreLogoffTransports until the message store's reference count drops to zero. Multiple calls to StoreLogoffTransports simply overwrite the saved flags.

If no call has been made to StoreLogoff before the message store's reference count reaches zero, set the LOGOFF_ABORT flag in the ulFlags parameter that you pass to StoreLogoffTransports.

See also

Reference

IMAPIStatus::FlushQueues
IMAPISupport::StoreLogoffTransports
IXPLogon::FlushQueues
IMsgStore : IMAPIProp


IMsgStore::Unadvise

 Copy code hover
[image]

IMsgStore::Unadvise
See also Send feedback

Published: July 16, 2012

Cancels the sending of notifications previously set up with a call to the IMsgStore::Advise method.

C++
HRESULT Unadvise(
  ULONG_PTR ulConnection
);

Parameters

ulConnection

[in] The connection number associated with an active notification registration. The value of ulConnection must have been returned by a previous call to the IMsgStore::Advise method.

Return value

S_OK

The registration was successfully canceled.

Remarks

The IMsgStore::Unadvise method cancels a registration for notification. Unadvise releases its pointer to the caller's advise sink, which it received in the Advise call used for registration.

Generally, Unadvise calls the advise sink's IUnknown::Release method during the Unadvise call. However, if another thread is in the process of calling the advise sink's IMAPIAdviseSink::OnNotify method, the Release call is delayed until the OnNotify method returns.

See also

Reference

IMAPIAdviseSink::OnNotify
IMsgStore::Advise
IMsgStore : IMAPIProp


IMSLogon : IUnknown

 Copy code hover
[image]

IMSLogon : IUnknown
See also Send feedback

Published: July 16, 2012

Accesses resources in a message store logon object.

Header file: | Mapispi.h
Exposed by: | Message store logon objects
Implemented by: | Message store providers
Called by: | MAPI
Interface identifier: | IID_IMSLogon
Pointer type: | LPMSLOGON

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the last error that occurred for the message store object.
Logoff | Logs off a message store provider.
OpenEntry | Opens a folder or message object and returns a pointer to the object to provide further access.
CompareEntryIDs | Compares two entry identifiers to determine whether they refer to the same object.
Advise | Registers an object with a message store provider for notifications about changes in the message store.
Unadvise | Removes an object's registration for notification of message store changes previously established by using a call to the IMSLogon::Advise method.
OpenStatusEntry | Opens a status object.

Remarks

The message store logon object is the part of an open message store provider that MAPI calls directly. There is a one-to-one correspondence between the message store logon object that MAPI calls and the message store object that client applications call; you can think of the logon and store objects as one object that exposes two interfaces. The two objects are created together and freed together.

See also

Concepts

MAPI Interfaces


IMSLogon::Advise

 Copy code hover
[image]

IMSLogon::Advise
See also Send feedback

Published: July 16, 2012

Registers an object with a message store provider for notifications about changes in the message store. The message store will then send notifications about changes to the registered object.

C++
HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG FAR * lpulConnection
);

Parameters

cbEntryID

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier of the object about which notifications should be generated. This object can be a folder, a message, or any other object in the message store. Alternatively, if MAPI sets the cbEntryID parameter to 0 and passes null for lpEntryID, the advise sink provides notifications about changes to the entire message store.

ulEventMask

[in] An event mask of the types of notification events occurring for the object about which MAPI will generate notifications. The mask filters specific cases. Each event type has a structure associated with it that contains additional information about the event. The following table lists the possible event types along with their corresponding structures.

Notification event type

Corresponding structure

fnevCriticalError

ERROR_NOTIFICATION

fnevNewMail

NEWMAIL_NOTIFICATION

fnevObjectCreated

OBJECT_NOTIFICATION

fnevObjectDeleted

OBJECT_NOTIFICATION

fnevObjectModified

OBJECT_NOTIFICATION

fnevObjectCopied

OBJECT_NOTIFICATION

fnevObjectMoved

OBJECT_NOTIFICATION

fnevSearchComplete

OBJECT_NOTIFICATION

fnevStatusObjectModified

STATUS_OBJECT_NOTIFICATION

lpAdviseSink

[in] A pointer to an advise sink object to be called when an event occurs for the session object about which notification has been requested. This advise sink object must already exist.

lpulConnection

[out] A pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_SUPPORT

The operation is not supported by MAPI or by one or more service providers.

Remarks

Message store providers implement the IMSLogon::Advise method to register an object for notification callbacks. Whenever a change occurs to the indicated object, the provider checks to see what event mask bit was set in the ulEventMask parameter and, therefore, what type of change occurred. If a bit is set, the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.

The call to OnNotify can occur during the call that changes the object, or at any later time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. To safely handle a call to OnNotify that might happen at an inopportune time, a client application should use the HrThisThreadAdviseSink function.

To provide notifications, the message store provider that implements Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, the provider calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMSLogon::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.

After a call to Advise has succeeded and before Unadvise has been called, providers must be prepared for the advise sink object to be released. Therefore, a provider should release its advise sink object after Advise returns, unless it has a specific long-term use for it.

For more information about the notification process, see Event Notification in MAPI.

See also

Reference

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMSLogon::Unadvise
NOTIFICATION
IMSLogon : IUnknown


IMSLogon::CompareEntryIDs

 Copy code hover
[image]

IMSLogon::CompareEntryIDs
See also Send feedback

Published: July 16, 2012

Compares two entry identifiers to determine whether they refer to the same object. MAPI refers this call to a service provider only if the unique identifiers (UIDs) in both entry identifiers to be compared are handled by that provider.

C++
HRESULT CompareEntryIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the returned result of the comparison. TRUE if the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::CompareEntryIDs method to compare two entry identifiers for a given entry in a message store to determine whether they refer to the same object. If the two entry identifiers refer to the same object, CompareEntryIDs sets the lpulResult parameter to TRUE; if they refer to different objects, CompareEntryIDs sets lpulResult to FALSE.

CompareEntryIDs is useful because an object can have more than one valid entry identifier. This can occur, for example, after a new version of a message store provider is installed.

See also

Reference

IMSLogon : IUnknown


IMSLogon::GetLastError

 Copy code hover
[image]

IMSLogon::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the last error that occurred for the message store object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call for the message store object.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

Use the IMSLogon::GetLastError method to retrieve information to display in a message to the user regarding the last error returned from a method call for the message store object.

To release all the memory allocated by MAPI for the returned MAPIERROR structure, client applications need to call only the MAPIFreeBuffer function.

The return value from GetLastError must be S_OK for an application to use the MAPIERROR. Even if the return value is S_OK, a MAPIERROR might not be returned. If the implementation cannot determine what the last error was, or if a MAPIERROR is not available for that error, GetLastError returns a pointer to NULL in lppMAPIError instead.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IMSLogon : IUnknown


IMSLogon::Logoff

 Copy code hover
[image]

IMSLogon::Logoff
See also Send feedback

Published: July 16, 2012

Logs off a message store provider.

C++
HRESULT Logoff(
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[in] Reserved; must be a pointer to zero.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::Logoff method to forcibly shut down a message store provider. IMSLogon::Logoff is called in the following situations:

  • While MAPI is logging off a client after a call to the IMAPISession::Logoff method.

  • While MAPI is logging off a message store provider. In this case, IMSLogon::Logoff is called as part of MAPI processing the IUnknown::Release method of the support object that the message store provider creates while it is processing an IMsgStore::StoreLogoff or IUnknown::Release method call on a message store object.

See also

Reference

IMAPISession::Logoff
IMAPISupport : IUnknown
IMsgStore::StoreLogoff
IMSProvider::Logon
MAPIFreeBuffer
IMSLogon : IUnknown


IMSLogon::OpenEntry

 Copy code hover
[image]

IMSLogon::OpenEntry
See also Send feedback

Published: July 16, 2012

Opens a folder or message object and returns a pointer to the object to provide further access.

C++
HRESULT OpenEntry(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulOpenFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

cbEntryID

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the address of the entry identifier of the folder or message object to open.

lpInterface

[in] A pointer to the interface identifier (IID) for the object. Passing NULL indicates that the object is cast to the standard interface for such an object. The lpInterface parameter can also be set to an identifier for an appropriate interface for the object.

ulOpenFlags

[in] A bitmask of flags that controls how the object is opened. The following flags can be set:

MAPI_BEST_ACCESS

The object should be opened with the maximum permissions allowed for the user and the maximum client application permissions. For example, if the client has read/write permission, the object is opened with read/write permission; if the client has read-only permission, the object is opened with read-only permission. The client can retrieve the permission level by getting the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not available to the calling application. If the object is not available, a subsequent call to the object might return an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are created with read-only permission, and clients should not work on the assumption that read/write permission has been granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppUnk

[out] A pointer to the pointer to the opened object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the IMSLogon::OpenEntry method to open a folder or a message in a message store. MAPI passes in the entry identifier of the object to open. The message store provider should return a pointer that enables further access to the object specified in the lppUnk parameter.

Before MAPI calls IMSLogon::OpenEntry, it first determines that the given message or folder entry identifier matches one registered by this message store provider. For more information about how store providers register entry identifiers, see IMAPISupport::SetProviderUID.

IMSLogon::OpenEntry is identical to the IMsgStore::OpenEntry method of the message store object, except that the client does not call IMSLogon::OpenEntry; MAPI calls IMSLogon::OpenEntry when it processes an IMAPISession::OpenEntry method. Objects opened by using IMSLogon::OpenEntry should be treated exactly the same as objects opened by using the message store object; in particular, objects opened by using this call should be invalidated when the message store object is released.

See also

Reference

IMAPISupport::SetProviderUID
IMsgStore::OpenEntry
IMSLogon : IUnknown


IMSLogon::OpenStatusEntry

 Copy code hover
[image]

IMSLogon::OpenStatusEntry
See also Send feedback

Published: July 16, 2012

Opens a status object.

C++
HRESULT OpenStatusEntry(
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPVOID FAR * lppEntry
);

Parameters

lpInterface

[in] A pointer to the interface identifier (IID) for the status object to open. Passing NULL indicates the standard interface for the object is returned (in this case, the IMAPIStatus interface). The lpInterface parameter can also be set to an identifier for an appropriate interface for the object.

ulFlags

[in] A bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write permission. By default, objects are created with read-only permission, and client applications should not work on the assumption that read/write permission has been granted.

lpulObjType

[out] A pointer to the type of the opened object.

lppEntry

[out] A pointer to the pointer to the opened object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::OpenStatusEntry method to open a status object. This status object is then used to enable clients to call IMAPIStatus methods. For example, clients can use the IMAPIStatus::SettingsDialog method to reconfigure the message store logon session or the IMAPIStatus::ValidateState method to validate the state of the message store logon session.

See also

Reference

IMAPIStatus : IMAPIProp
IMAPIStatus::SettingsDialog
IMAPIStatus::ValidateState
IMSLogon : IUnknown


IMSLogon::Unadvise

 Copy code hover
[image]

IMSLogon::Unadvise
See also Send feedback

Published: July 16, 2012

Removes an object's registration for notification of message store changes previously established by using a call to the IMSLogon::Advise method.

C++
HRESULT Unadvise(
  ULONG ulConnection
);

Parameters

ulConnection

[in] The number of the registration connection returned by a call to IMSLogon::Advise.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers implement the IMSLogon::Unadvise method to release the pointer to the advise sink object passed in the lpAdviseSink parameter in the previous call to IMSLogon::Advise, thereby canceling a notification registration. As part of discarding the pointer to the advise sink object, the object's IUnknown::Release method is called. Generally, Release is called during the Unadvise call. However, if another thread is in the process of calling the IMAPIAdviseSink::OnNotify method for the advise sink object, the Release call is delayed until the OnNotify method returns.

See also

Reference

IMAPIAdviseSink::OnNotify
IMSLogon::Advise
IMSLogon : IUnknown


IMSProvider : IUnknown

 Copy code hover
[image]

IMSProvider : IUnknown
See also Send feedback

Published: July 16, 2012

Provides access to a message store provider through a message store provider object. This message store provider object is returned at provider logon by the message store provider's MSProviderInit entry point function. The message store provider object is primarily used by client applications and the MAPI spooler to open message stores.

Header file: | Mapispi.h
Exposed by: | Message store provider objects
Implemented by: | Message store providers
Called by: | MAPI and the MAPI spooler
Interface identifier: | IID_IMSProvider
Pointer type: | LPMSPROVIDER

Vtable Order

Shutdown | Closes a message store provider in an orderly fashion.
Logon | Logs MAPI on to one instance of a message store provider.
SpoolerLogon | Logs the MAPI spooler on to a message store.
CompareStoreIDs | Compares two message store entry identifiers to determine whether they refer to the same store object.

Remarks

MAPI uses one message store provider object per session, no matter how many message stores are opened by the store provider. If a second MAPI session logs on to any open stores, MAPI calls MSProviderInit a second time to create a new message store provider object for that session to use.

A message store provider object must contain the following to operate correctly:

  • An lpMalloc memory-allocation routine pointer for use by all stores opened by using this provider object.

  • The lpfAllocateBuffer, lpfAllocateMore , and lpfFreeBuffer routine pointers to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer memory allocation functions.

  • A linked list of all the stores opened by using this provider object and not yet closed.

See also

Concepts

MAPI Interfaces


IMSProvider::CompareStoreIDs

 Copy code hover
[image]

IMSProvider::CompareStoreIDs
See also Send feedback

Published: July 16, 2012

Compares two message store entry identifiers to determine whether they refer to the same store object.

C++
HRESULT CompareStoreIDs(
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG FAR * lpulResult
);

Parameters

cbEntryID1

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier to be compared.

cbEntryID2

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier to be compared.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the returned result of the comparison. TRUE if the two entry identifiers refer to the same object; otherwise, FALSE.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

MAPI calls the IMSProvider::CompareStoreIDs method when it processes a call to the IMAPISession::OpenMsgStore method. CompareStoreIDs is called at this point to determine which profile section, if any, is associated with the message store being opened. A CompareStoreIDs call can be made when no message stores are open for a particular store provider. In addition, MAPI also calls CompareStoreIDs when it processes a store provider call to the IMAPISupport::OpenProfileSection method.

The entry identifiers compared by CompareStoreIDs are both for the current store provider's dynamic-link library (DLL) and are both unwrapped store entry identifiers. For more information about wrapping store entry identifiers, see IMAPISupport::WrapStoreEntryID.

Comparing entry identifiers is useful because an object can have more than one valid entry identifier. This can occur, for example, after a new version of a message store provider is installed.

See also

Reference

IMAPISession::OpenMsgStore
IMAPISupport::OpenProfileSection
IMAPISupport::WrapStoreEntryID
IMSProvider : IUnknown


IMSProvider::Logon

 Copy code hover
[image]

IMSProvider::Logon
See also Send feedback

Published: July 16, 2012

Logs MAPI on to one instance of a message store provider.

C++
HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG FAR * lpcbSpoolSecurity,
  LPBYTE FAR * lppbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

Parameters

lpMAPISup

[in] A pointer to the current MAPI support object for the message store.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays.

lpszProfileName

[in] A pointer to a string that contains the name of the profile being used for store provider logon. This string can be displayed in dialog boxes, written out to a log file, or simply ignored. It must be in Unicode format if the MAPI_UNICODE flag is set in the ulFlags parameter.

cbEntryID

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for the message store. Passing null in lpEntryID indicates that a message store has not yet been selected and that dialog boxes that enable the user to select a message store can be presented.

ulFlags

[in] A bitmask of flags that controls how the logon is performed. The following flags can be set:

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not available to the calling implementation. If the object is not available, a subsequent call to the object might raise an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

MDB_NO_DIALOG

Prevents the display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if the logon is unsuccessful. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions that are necessary to establish connection to the store.

MDB_NO_MAIL

The message store should not be used for sending or receiving mail. The flag signals MAPI not to notify the MAPI spooler that this message store is being opened. If this flag is set and the message store is tightly coupled with a transport provider, the provider does not need to call the IMAPISupport::SpoolerNotify method.

MDB_TEMPORARY

Logs on the store so that information can be retrieved programmatically from the profile section, without use of dialog boxes. This flag instructs MAPI that the store is not to be added to the message store table and that the store cannot be made permanent. If this flag is set, message store providers do not need to call the IMAPISupport::ModifyProfile method.

MDB_WRITE

Requests read/write permission.

lpInterface

[in] A pointer to the interface identifier (IID) for the message store to log on to. Passing null indicates the MAPI interface for the message store (IMsgStore) is returned. The lpInterface parameter can also be set to an identifier for an appropriate interface for the message store (for example, IID_IUnknown or IID_IMAPIProp).

lpcbSpoolSecurity

[out] A pointer to the variable in which the store provider returns the size, in bytes, of the validation data in the lppbSpoolSecurity parameter.

lppbSpoolSecurity

[out] A pointer to the pointer to the returned validation data. This validation data is provided so the IMSProvider::SpoolerLogon method can log the MAPI spooler on to the same store as the message store provider.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure, if any, that contains version, component, and context information for an error. The lppMAPIError parameter can be set to null if there is no MAPIERROR structure to return.

lppMSLogon

[out] A pointer to the pointer to the message store logon object for MAPI to log on to.

lppMDB

[out] A pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_LOGON_FAILED

A logon session could not be established.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. When this value is returned, MAPI calls the message store provider's message-service entry point function.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling. To get the error information from the provider, call the IMAPISession::GetLastError method.

Remarks

MAPI calls the IMSProvider::Logon method to do the majority of processing necessary to obtain access to a message store. Message store providers validate any user credentials necessary to access a particular store and return a message store object in the lppMDB parameter that the MAPI spooler and client applications can log on to.

In addition to the returned message store object for client and MAPI spooler use, the provider also returns a message store logon object for MAPI to use in controlling the opened store. The message store logon object and the message store object should be tightly linked inside the message store provider so each can affect the other. The use of the store object and the logon object should be identical; there should be a one-to-one correspondence between the logon object and the store object such that the objects act as if they are one object that exposes two interfaces. The two objects should also be created together and freed together.

The MAPI support object, created by MAPI and passed to the provider in the lpMAPISup parameter, provides access to functions in MAPI that the provider requires. These include functions that save and retrieve profile information, access address books, and so on. The lpMAPISup pointer can be different for each store that is opened. While processing calls for a message store after logon, the store provider should use the lpMAPISup variable that is specific to that store. For any Logon call that opens a message store and succeeds in creating a message store logon object, the provider must save a pointer to the MAPI support object in the store logon object and must call the IUnknown::AddRef method to add a reference for the support object.

The ulUIParam parameter should be used if the provider presents dialog boxes during the Logon call. However, dialog boxes should not be presented if ulFlags contains the MDB_NO_DIALOG flag. If a user interface needs to be called but ulFlags does not allow it, or if for some other reason a user interface cannot be displayed, the provider should return MAPI_E_LOGON_FAILED. If Logon displays a dialog box and the user cancels the logon, typically by clicking the dialog box's Cancel button, the provider should return MAPI_E_USER_CANCEL.

The lpEntryID parameter can either be null or point to an unwrapped store entry identifier that this message store previously created. If lpEntryID points to an unwrapped entry identifier, that entry identifier can come from one of several places:

  • It can be an entry identifier that the store provider previously wrapped and wrote to the profile section as a PR_ENTRYID (PidTagEntryId) property.

  • It can be an entry identifier that the provider previously wrapped and returned to a calling client as a PR_STORE_ENTRYID (PidTagStoreEntryId) property.

  • It can be an entry identifier that the provider previously wrapped and returned to a calling client as the PR_ENTRYID property of a message store object.

In any of these cases, it is possible that the entry identifier was created on a different computer than the one currently being used.

When lpEntryID is not null, it should contain all of the information needed to identify and locate the message store. This information can include network volume names, phone numbers, user account names, and so on. If the connection to the store cannot be made by using the data in the entry identifier, the store provider should display a dialog box that enables the user to select the store to be opened. A dialog box might be required, for example, if a server has been renamed, an account name has changed, or portions of the network are not available.

When lpEntryID is null, the message store to use has not yet been selected. The provider can still access a store without displaying a dialog box if it supports further methods to specify the store. For example, the provider can check its initialization file, or it can look for additional properties that were placed in its or its message service's profile section at configuration.

If a provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED. MAPI will then call the provider's message service entry point function to enable the user to select a store, or even to create one, and to enter an account name and password, as needed. MAPI automatically creates a new profile section for a new store; this new profile section can be temporary or permanent, depending on how it has been added. If the store provider calls the IMAPISupport::ModifyProfile method, the new profile section becomes permanent and the store is added to the list of message stores returned by the IMAPISession::GetMsgStoresTable method.

The lpInterface parameter specifies the IID of the interface required for the newly opened store object. Passing null in lpInterface specifies that the MAPI message store interface, IMsgStore, is required. Passing the message store object, IID_IMsgStore, also specifies that IMsgStore is required. If IID_IUnknown is passed in lpInterface, the provider should open the store by using whatever interface derived from IUnknown is best for the provider (again, this is typically IMsgStore). When IID_IUnknown is passed, the calling implementation uses the IUnknown::QueryInterface method to select an interface after the store open operation succeeds.

The IMSProvider::Logon call should return sufficient information, such as a path to the store and credentials for accessing the store, to allow the MAPI spooler to log on to the same store that the store provider does without presenting a dialog box. The lpcbSpoolSecurity and lppbSpoolSecurity parameters are used to return this information. The provider allocates the memory for this data by passing a pointer to a buffer in the MSProviderInit function's lpfAllocateBuffer parameter; the provider places the size of this buffer in lpcbSpoolSecurity.

MAPI frees this buffer when appropriate. If the MAPI spooler's logon to the store can be accomplished from the information in the profile section alone, the provider can return null in lppbSpoolSecurity and 0 for the information's size in lpcbSpoolSecurity. The MAPI spooler logon occurs as part of a different process than the store logon; because the buffer that contains the passed information gets copied between processes, it might not be in memory at the same location for the MAPI spooler process as for the store provider process. Therefore, a provider shouldn't put addresses into this buffer. For more information about MAPI spooler logon, see the IMSProvider::SpoolerLogon method.

Most store providers use the IMAPISession::OpenProfileSection method of the support object passed in the lpMAPISup parameter for saving and retrieving user credentials and options. OpenProfileSection enables a store provider to save additional arbitrary information in a profile section and associate it with a particular resource. For example, a store provider can save the user account name and password associated with a resource and any paths or other information needed to access that resource.

Properties with property identifiers 0x6600 through 0x67FF are secure properties available to the provider for its own use to store private data in profile sections. For more information about the uses of properties in profile section objects, see the IProfSect : IMAPIProp method.

In addition to any private data in properties with identifiers 0x6600 through 0x67FF, the store provider should provide information for the PR_DISPLAY_NAME (PidTagDisplayName) property in its profile section. It should put in PR_DISPLAY_NAME the display name of the provider itself — an identifying string (for example, "Microsoft Personal Information Store") that is displayed to users so they can distinguish this message store from others they might have access to. PR_DISPLAY_NAME commonly contains a server name, user account name, or path.

Some profile section properties are visible in the message store table; others are visible during setup, installation, and configuration of the MAPI subsystem. The provider typically provides information for these visible properties both for a new profile section, which does not yet include saved credentials or private information, and when it finds that property information has changed. For more information about profile sections, see IMAPISupport::OpenProfileSection.

After successfully logging on a user, and before returning to MAPI, the store provider should create the array of properties for the status row for the resource and call the IMAPISupport::ModifyStatusRow method.

Logon calls that open message stores that are already open for the current MAPI session skip much of the processing previously described. These calls do not create status rows, return message store logon objects, call AddRef for the MAPI support object, or return data for MAPI spooler logon. These calls do return S_OK and return a message store object with the requested interface.

To detect such calls, the provider should maintain a list in the message store provider object of stores already open for this provider object. When processing a Logon call, the provider should scan this list of open stores and determine whether the store to be logged on to is already open. If it is, user credentials do not need to be checked and the display of a dialog box should be avoided, if possible. If dialog boxes must be displayed, the provider should check returned information to see whether a store has been opened a second time. In addition, the provider should check for duplicate openings by using lpEntryID at the beginning of Logon call processing.

Standard processing for a Logon call that accesses an open store is as follows:

  1. The store provider calls AddRef for the existing store object if the new interface being requested is the same as the interface for the existing store. Otherwise, it calls QueryInterface to get the new interface. If the store does not support the new interface, the provider should return the error value MAPI_E_INTERFACE_NOT_SUPPORTED.

  2. The provider returns a pointer to the required interface of the existing store object in lppMDB.

  3. The provider returns null in lppMSLogon.

  4. The provider should not open the profile for the support object passed in the call. In addition, it should not register a provider unique identifier, register a status row, or return MAPI spooler logon data.

  5. The provider should not call AddRef for the support object, because it does not require a pointer to the object.

Whenever possible, providers should return appropriate error and warning strings for Logon calls, because doing so greatly eases the burden of users in determining why something did not work. To return these strings, a provider sets the members in the MAPIERROR structure. MAPI looks for, uses, and releases the MAPIERROR structure if it is returned by a provider.

Memory for this MAPIERROR structure should be allocated by using the buffer passed in lpfAllocateBuffer on the MSProviderInit call. Any error strings contained in the returned structure should be in Unicode format if MAPI_UNICODE is set in the LogonulFlags; otherwise, they should be in the ANSI character set.

For most error values returned from Logon, MAPI disables the message services to which the failing provider belongs. MAPI will not call any providers that belong to those services for the life of the MAPI session. In contrast, when Logon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. Logon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the entire service for the life of the session. For example, a provider might return this error when it does not allow the display of a user interface and a required password is unavailable.

If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider's message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so the user can enter configuration information.

See also

Reference

IMAPISession::GetMsgStoresTable
IMAPISession::OpenMsgStore
IMAPISession::OpenProfileSection
IMAPISupport::ModifyProfile
IMAPISupport::ModifyStatusRow
IMsgStore : IMAPIProp
IMSProvider::SpoolerLogon
IProfSect : IMAPIProp
MAPIERROR
MSProviderInit
IMSProvider : IUnknown


IMSProvider::Shutdown

 Copy code hover
[image]

IMSProvider::Shutdown
See also Send feedback

Published: July 16, 2012

Closes a message store provider in an orderly fashion.

C++
HRESULT Shutdown(
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[in] Reserved; must be a pointer to zero.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

MAPI calls the IMSProvider::Shutdown method just before releasing the message store provider object. MAPI releases all logon objects for a provider before calling Shutdown for that provider.

See also

Reference

IMSProvider : IUnknown


IMSProvider::SpoolerLogon

 Copy code hover
[image]

IMSProvider::SpoolerLogon
See also Send feedback

Published: July 16, 2012

Logs the MAPI spooler on to a message store.

C++
HRESULT SpoolerLogon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG cbSpoolSecurity,
  LPBYTE lpbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

Parameters

lpMAPISup

[in] A pointer to the MAPI support object for the message store.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays.

lpszProfileName

[in] A pointer to a string that contains the name of the profile being used for the MAPI spooler logon. This string can be displayed in dialog boxes, written out to a log file, or simply ignored. It must be in Unicode format if the MAPI_UNICODE flag is set in the ulFlags parameter.

cbEntryID

[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier for the message store. Passing NULL in the lpEntryID parameter indicates that a message store has not yet been selected and that dialog boxes that enable the user to select a message store can be presented.

ulFlags

[in] A bitmask of flags that controls how the logon is performed. The following flags can be set:

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not available to the calling implementation. If the object is not available, a subsequent call to the object might raise an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

MDB_NO_DIALOG

Prevents the display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if the logon is unsuccessful. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions necessary to establish connection to the store.

MDB_WRITE

Requests read/write permission.

lpInterface

[in] A pointer to the interface identifier (IID) for the message store to log on to. Passing NULL indicates the MAPI interface for the message store (IMsgStore) is returned. The lpInterface parameter can also be set to an identifier for an appropriate interface for the message store (for example IID_IUnknown or IID_IMAPIProp).

cbSpoolSecurity

[in] A pointer to the size, in bytes, of validation data in the lppbSpoolSecurity parameter.

lpbSpoolSecurity

[in] A pointer to a pointer to validation data. The SpoolerLogon method uses this data to log the MAPI spooler on to the same store as the message store provider previously logged on to by using the IMSProvider::Logon method.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure, if any, that contains version, component, and context information for an error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppMSLogon

[out] A pointer to the pointer to the message store logon object for MAPI to log on to.

lppMDB

[out] A pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. When this value is returned, MAPI calls the message store provider's message service entry point function.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling. To get the error information from the provider, call the IMAPISession::GetLastError method.

Remarks

The MAPI spooler calls the IMSProvider::SpoolerLogon method to log on to a message store. The MAPI spooler should use the message store object returned by the message store provider in the lppMDB parameter during and after logon.

For consistency with the IMSProvider::Logon method, the provider also returns a message store logon object in the lppMSLogon parameter. The use of the store object and the logon object are identical for usual store logon; there should be a one-to-one correspondence between the logon object and the store object such that the objects act as if they are one object that exposes two interfaces. The two objects are created together and freed together.

The store provider should internally mark the returned message store object to indicate that the store is being used by the MAPI spooler. Some of the methods for this store object behave differently than for the message store object provided to client applications. Keeping this internal mark is the most common way of triggering the behavior specific to the MAPI spooler.

See also

Reference

IMSProvider::Logon
MAPIERROR
IMSProvider : IUnknown


IOSTX : IUnknown

 Copy code hover
[image]

IOSTX : IUnknown
See also Send feedback

Published: July 16, 2012

Provides synchronization methods. This interface retrieves the necessary information to replicate local changes to the server and server changes to the local store.

Provided by: | IPSTX::GetSyncObject
Interface identifier: | IID_IOSTX

Vtable Order

GetLastError | Gets extended information about the last error.
InitSync | Informs the local store that synchronization is about to start.
SyncBeg | Prepares the local store for synchronization in a particular state and retrieves the necessary information to replicate.
SyncEnd | Ends synchronization in the current state and exits that state.
SyncHdrBeg | Starts synchronization for a message header.
SyncHdrEnd | Ends synchronization for a message header.
SetSyncResult | Sets the result of the synchronization.
Placeholder member | Not supported or documented.

Remarks

When a client uploads or synchronizes folders and folder contents on a local store, it moves the local store from one state to another as depicted in the state transition diagram in About the Replication State Machine. The following is the order of events for the client to move the local store from one state to another:

  1. The client calls IOSTX::InitSync to inform the local store that replication is about to start.

  2. Depending on the direction of replication and the objects to replicate, the client calls IOSTX::SyncBeg to begin replication in the appropriate state. Outlook provides the client the necessary information, and the client performs the replication.

  3. The client calls IOSTX::SetSyncResult to return the result of the replication.

  4. The client calls IOSTX::SyncEnd to end the replication, providing Outlook the necessary information for subsequent replication.

In particular, when downloading message items, the client uses IOSTX::SyncHdrBeg and IOSTX::SyncHdrEnd to update a full message item with the message header on the local store:

  1. Upon IOSTX::SyncHdrBeg, the local store transitions into the download message header state. Outlook initially provides the client with the current message header on the local store.

  2. The client downloads a full message item together with the message header.

  3. Outlook updates the item on the local store with the full message item.

See also

Concepts

About the Replication API
MAPI Constants


IOSTX::GetLastError

 Copy code hover
[image]

IOSTX::GetLastError
See also Send feedback

Published: July 16, 2012

Gets extended information about the last error.

C++
HRESULT GetLastError(
    HRESULT hResult,
    ULONG ulFlags,
    LPMAPIERROR *lppMAPIError
);

Parameters

hResult

[in] Error code.

ulFlags

[in] Flags to modify behavior. This must be 0.

lppMAPIError

[out] Pointer to the MAPIERROR structure that contains the extended information for the error. See mapidefs.h for the type definition of LPMAPIERROR.

See also

Reference

IOSTX::InitSync
IOSTX::SetSyncResult
IOSTX::SyncBeg
IOSTX::SyncEnd
IOSTX::SyncHdrBeg
IOSTX::SyncHdrEnd
IOSTX : IUnknown

Concepts

MAPI Constants


IOSTX::InitSync

 Copy code hover
[image]

IOSTX::InitSync
See also Send feedback

Published: July 16, 2012

Informs the local message store that synchronization is about to start.

C++
HRESULT InitSync(
    ULONG ulFlags
);

Parameters

ulFlags

[in] Flags to determine appropriate behavior during synchronization. Outlook uses these flags in each state of the replication state machine to determine the information that it should provide for the client. For example, if the client passes SYNC_ONLY_ASSOCIATED, Outlook will only return information related to associated (or hidden) items.

See also

Reference

IOSTX::GetLastError
IOSTX::SetSyncResult
IOSTX::SyncBeg
IOSTX::SyncEnd
IOSTX::SyncHdrBeg
IOSTX::SyncHdrEnd
IOSTX : IUnknown

Concepts

MAPI Constants


IOSTX::SetSyncResult

 Copy code hover
[image]

IOSTX::SetSyncResult
See also Send feedback

Published: July 16, 2012

Sets the result of the synchronization.

C++
HRESULT SetSyncResult(
    HRESULT hrSync
);

Parameters

hrSync

[in] The result of the synchronization.

Remarks

Call IOSTX::SetSyncResult before calling IOSTX::SyncEnd to inform the local store of the result of synchronization.

See also

Reference

IOSTX::GetLastError
IOSTX::InitSync
IOSTX::SyncBeg
IOSTX::SyncEnd
IOSTX::SyncHdrBeg
IOSTX::SyncHdrEnd

Concepts

MAPI Constants


IOSTX::SyncBeg

 Copy code hover
[image]

IOSTX::SyncBeg
See also Send feedback

Published: July 16, 2012

Prepares the local store for synchronization in a particular state and retrieves the necessary information to replicate.

C++
HRESULT SyncBeg(
    UINT uiSync,
    LPVOID *ppv
);

Parameters

uiSync

[in] The state that the local store will enter. The following is a list of state identifers:

LR_SYNC_IDLE

LR_SYNC

LR_SYNC_UPLOAD_HIERARCHY

LR_SYNC_UPLOAD_FOLDER

LR_SYNC_CONTENTS

LR_SYNC_UPLOAD_TABLE

LR_SYNC_UPLOAD_MESSAGE

LR_SYNC_UPLOAD_MESSAGE_READ

LR_SYNC_UPLOAD_MESSAGE_DEL

LR_SYNC_DOWNLOAD_HIERARCHY

LR_SYNC_DOWNLOAD_TABLE

ppv

[in]/[out] Pointer to the data structure corresponding to the state to enter.

DNHIER

DNTBL

DNTBL

SYNC

SYNCCONT

UPDEL

UPDELE

UPFLD

UPHIER

UPMOV

UPMSG

UPREAD

UPREADE

UPTBL

UPTBLE

Remarks

The client calls IOSTX::SetSyncResult to set the result of the synchronization, and then calls IOSTX::SyncEnd to end that state. The client must call IOSTX::SyncEnd for each call to IOSTX::SyncBeg in order to determine whether the state has been successfully replicated. Once this has been determined, Outlook can begin to clean up its internal state.

Most of these structures contain [out]/[in] information, allowing Outlook to pass information to the client, and the client to pass information to Outlook. When the client calls IOSTX::SyncBeg, Outlook allocates the data structure for a given state and initializes it with information for that state. This is the [out] information. While in a state, the client updates the corresponding data structure for that state. This is the [in] information.

See also

Reference

IOSTX::GetLastError
IOSTX::InitSync
IOSTX::SetSyncResult
IOSTX::SyncEnd
IOSTX::SyncHdrBeg
IOSTX::SyncHdrEnd
IOSTX : IUnknown

Concepts

MAPI Constants


IOSTX::SyncEnd

 Copy code hover
[image]

IOSTX::SyncEnd
See also Send feedback

Published: July 16, 2012

Ends synchronization in the current state and exits that state.

C++
HRESULT SyncEnd();

Remarks

The client must call IOSTX::SyncEnd for each call to IOSTX::SyncBeg. The corresponding data structure holds information to indicate whether the client has successfully completed the current state so that Outlook can clean up its internal state.

See also

Reference

IOSTX::GetLastError
IOSTX::InitSync
IOSTX::SetSyncResult
IOSTX::SyncBeg
IOSTX::SyncHdrBeg
IOSTX::SyncHdrEnd
IOSTX : IUnknown

Concepts

MAPI Constants


IOSTX::SyncHdrBeg

 Copy code hover
[image]

IOSTX::SyncHdrBeg
See also Send feedback

Published: July 16, 2012

Starts synchronization for a message header.

C++
HRESULT SyncHdrBeg(
    ULONG cbeid,
    LPENTRYID lpeid,
    LPVOID *ppv
);

Parameters

cbeid

[in] The number of bytes in the entry ID for the message.

lpeid

[in] The entry ID for the message.

ppv

[in]/[out] Pointer to the HDRSYNC structure for the message header.

Remarks

Upon IOSTX::SyncHdrBeg, the local store transitions to the download message header state. Outlook initializes for the client the HDRSYNC structure with the current representation of the message header in the store and the parent folder. The client must then download a full message item (as pmsgFull in HDRSYNC). If this was successful, the client also sets ulFlags in HDRSYNC as HSF_OK. Upon IOSTX::SyncHdrEnd, Outlook checks the result in HDRSYNC and uses the information in HDRSYNC to update the local message header.

See also

Reference

IOSTX::GetLastError
IOSTX::InitSync
IOSTX::SetSyncResult
IOSTX::SyncBeg
IOSTX::SyncEnd
IOSTX::SyncHdrEnd
IOSTX : IUnknown

Concepts

MAPI Constants


IOSTX::SyncHdrEnd

 Copy code hover
[image]

IOSTX::SyncHdrEnd
See also Send feedback

Published: July 16, 2012

Ends synchronization for a message header.

C++
HRESULT SyncHdrEnd(
    LPMAPIPROGRESS pprog
);

Parameters

pprog

[in] IMAPIProgress interface for synchronization of moved or copied messages. See mapidefs.h for the type definition of LPMAPIPROGRESS.

Remarks

Upon IOSTX::SyncBeg, the local store enters the download message header state. The client downloads a full message item (as pmsgFull in HDRSYNC). If this is successful, the client also sets ulFlags in HDRSYNC as HSF_OK. Upon IOSTX::SyncHdrEnd, Outlook checks the result in HDRSYNC and uses pprog and the information in HDRSYNC to update the local message header.

The local store returns to the state it was in before the preceding IOSTX::SyncHdrBeg.

See also

Reference

IOSTX::GetLastError
IOSTX::InitSync
IOSTX::SetSyncResult
IOSTX::SyncBeg
IOSTX::SyncEnd
IOSTX::SyncHdrBeg
IOSTX : IUnknown

Concepts

MAPI Constants


IPSTOVERRIDE1 : IUnknown

 Copy code hover
[image]

IPSTOVERRIDE1 : IUnknown
See also Send feedback

Published: July 16, 2012

Allows a Personal Folders file (PST) store provider to override the PSTDisableGrow policy.

Inherits from: | IUnknown
Implemented by: | PST store provider
Called by: | Client
Interface identifier: | IID_IPSTOVERRIDE1

Vtable Order

IPSTOVERRIDE1::GetPersistedRegistrations | Retrieves the list of registrations for the Personal Folders (.pst) file.
IPSTOVERRIDE1::SetPersistedRegistrations | Registers Personal Folders files for automatic unlocking, avoiding further calls to HrTrustedPSTOverrideHandlerCallback.
IPSTOVERRIDE1::OverridePSTDisableGrow | Unlocks a Personal Folders file for growth.

Remarks

The PST Override Handler Interface Identifiers might not be defined in the downloadable header file you currently have, in which case you will find them in the MAPI Constants topic, and can copy and add them to your code. Use the DEFINE_GUID macro defined in the Microsoft Windows Software Development Kit (SDK) header file guiddef.h to associate globally unique identifier (GUID) symbolic names with their values.

For more information see How to implement a PST override handler to bypass the PSTDisableGrow policy in Outlook 2007.

See also

Reference

IPSTOVERRIDEREQ : IUnknown


IPSTOVERRIDE1::GetPersistedRegistrations

 Copy code hover
[image]

IPSTOVERRIDE1::GetPersistedRegistrations
See also Send feedback

Published: July 16, 2012

Retrieves the list of registrations for the Personal Folders (.pst) file.

C++
HRESULT GetPersistedRegistration(SPropValue **ppmval);

Parameters

ppmval

[in] A pointer to a pointer to an SPropValue structure. The ulPropTag member of this structure is of the type PT_MV_UNICODE, and the MVszW value member will be an array of null-terminated Unicode strings. These strings are paths to DLLs for which registration has been persisted.

Note Note

.pst support for ANSI is not implemented.

Return value

S_OK

The function call was successful.

See also

Reference

IPSTOVERRIDE1 : IUnknown
IPSTOVERRIDEREQ : IUnknown


IPSTOVERRIDE1::OverridePSTDisableGrow

 Copy code hover
[image]

IPSTOVERRIDE1::OverridePSTDisableGrow
See also Send feedback

Published: July 16, 2012

Unlocks a Personal Folders (.pst) file for a session, overriding the PSTDisableGrow policy.

C++
HRESULT OverridePSTDisableGrow();

Return value

S_OK

The function call was successful.

See also

Reference

IPSTOVERRIDE1 : IUnknown
IPSTOVERRIDEREQ : IUnknown


IPSTOVERRIDE1::SetPersistedRegistrations

 Copy code hover
[image]

IPSTOVERRIDE1::SetPersistedRegistrations
See also Send feedback

Published: July 16, 2012

Registers Personal Folders (.pst) files for automatic unlocking, avoiding further calls to the HrTrustedPSTOverrideHandlerCallback.

C++
HRESULT SetPersistedRegistrations(
  SPropValue *pmval
);

Parameters

pmval

[in] An SPropValue structure that contains a pointer to the path of the dynamic-link library (DLL) to register. The structure has the following characteristics:

  • A ulPropTag of PROP_TAG(PT_MV_UNICODE, PROP_ID_NULL).

  • An MVszW value property that is set to an array of null-terminated Unicode character strings. For more information see the SWStringArray topic.

Note Note

The SPropValue is stored in a MAPI property in the PST's internal range. This property is inaccessible to ordinary MAPI applications.

Return value

S_OK

The function call was successful.

Remarks

Persisted registrations may adversely affect the performance of applications, such as Outlook and Windows Desktop Search, that open PSTs. Consider the performance effect when using or expanding the usage of persisted registrations.

Important note Important

This method is implemented for Unicode only. Further, it will preemptively fail if any of the paths in the array do not have a file name extension of .dll.

See also

Reference

IPSTOVERRIDE1 : IUnknown
IPSTOVERRIDEREQ : IUnknown


IPSTOVERRIDEREQ : IUnknown

 Copy code hover
[image]

IPSTOVERRIDEREQ : IUnknown
See also Send feedback

Published: July 16, 2012

Accesses resources of a Personal Folders file (PST) store provider.

Inherits from: | IUnknown
Implemented by: | PST store provider
Called by: | Client applications
Interface identifier: | IID_IPSTOVERRIDEREQ

Vtable Order

IPSTOVERRIDEREQ::RegisterTrustedPSTOverrideHandler

Initiates the unlocking procedure for a Personal Folders (.pst) file.

Remarks

The PST Override Handler Interface Identifiers might not be defined in the downloadable header file you currently have, in which case you will find them in the MAPI Constants topic, and can copy and add them to your code. Use the DEFINE_GUID macro defined in the Microsoft Windows Software Development Kit (SDK) header file guiddef.h to associate globally unique identifier (GUID) symbolic names with their values.

For more information see How to implement a PST override handler to bypass the PSTDisableGrow policy in Outlook 2007.

See also

Reference

IPSTOVERRIDE1 : IUnknown


IPSTOVERRIDEREQ::RegisterTrustedPSTOverrideHandler

 Copy code hover
[image]

IPSTOVERRIDEREQ::RegisterTrustedPSTOverrideHandler
See also Send feedback

Published: July 16, 2012

Initiates the unlocking procedure for a Personal Folders (.pst) file.

C++
HRESULT RegisterTrustedPSTOverrideHandler (
  LPCWSTR pwzDllPath,
  LPVOID pvClientData
);

Parameters

pwzDllPath

[in] A pointer to the path of a third-party dynamic-link library (DLL).

pvClientData

[in] A pointer to client data, which will be passed by the PST provider into subsequent calls to the DLL's HrTrustedPSTOverrideHandlerCallback function. This client data may be used by the DLL to assist in verifying whether the PST should be unlocked.

Return value

S_OK

The function call was successful.

Remarks

The DLL specified by the wzDllPath parameter must be signed using a digital certificate. The DLL must also export a function with the following signature.

Copy code Copy code
extern "C" HRESULT __cdecl HrTrustedPSTOverrideHandlerCallback(IMsgStore *pmstore, IUnknown *pOverride, LPVOID pvClientData)

This function will be called with a pointer to the IMsgStore object for the PST, a pointer to an IUnknown object that implements the IPSTOVERRIDE1 interface, and a pointer to the data originally supplied through pvClientData.

For more information see How to implement a PST override handler to bypass the PSTDisableGrow policy in Outlook 2007.

See also

Reference

IPSTOVERRIDE1 : IUnknown
IPSTOVERRIDEREQ : IUnknown


IPSTX : IUnknown

 Copy code hover
[image]

IPSTX : IUnknown
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX

Vtable Order

GetLastError | Gets extended information about the last error.
GetSyncObject | Gets the associated IOSTX interface.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
EmulateSpooler | Sets a local store to emulate the Outlook Protocol Manager to spool outgoing messages to a server.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX::EmulateSpooler

 Copy code hover
[image]

IPSTX::EmulateSpooler
See also Send feedback

Published: July 16, 2012

Sets a local store to emulate the Outlook Protocol Manager to spool outgoing messages to a server.

C++
HRESULT EmulateSpooler(
    BOOL fEmulate
);
fEmulate

[in] Set this parameter to True if the local store should emulate the spooler; set it to False if not.

Remarks

A local store calls IPSTX::EmulateSpooler to act as an Outlook Protocol Manager, spooling messages in the outgoing queue to the back-end server (for example, MSN server or AOL server) for processing. Emulating a spooler during synchronization, the store then calls these two methods:

  1. IMsgStore::GetOutgoingQueue to get the outgoing queue of messages in the store. This method succeeds only if the store is emulating the Outlook Protocol Manager.

  2. IMsgStore::SetLockState to secure sole access to a message in the outgoing queue just before sending it to the server. This method succeeds only if the store is emulating the Outlook Protocol Manager. After sending the message, the store calls this method again to release sole access to it.

Note Note

Since Outlook 2002, the Outlook Protocol Manager replaced the MAPI spooler and became responsible for spooling outgoing messages to back-end servers.

See also

Reference

IPSTX::GetLastError
IPSTX::GetSyncObject


IPSTX::GetLastError

 Copy code hover
[image]

IPSTX::GetLastError
See also Send feedback

Published: July 16, 2012

Gets extended information about the last error.

HRESULT GetLastError(
    HRESULT hResult,
    ULONG ulFlags,
    LPMAPIERROR *lppMAPIError
);

Parameters

hResult

[in] Error code.

ulFlags

[in] Flags to modify behavior. This must be 0.

lppMAPIError

[out] Pointer to the MAPIERROR structure that contains the extended information for the error. See mapidefs.h for the type definition of LPMAPIERROR.

See also

Reference

IPSTX::EmulateSpooler
IPSTX::GetSyncObject


IPSTX::GetSyncObject

 Copy code hover
[image]

IPSTX::GetSyncObject
See also Send feedback

Published: July 16, 2012

Starts a synchronization session and gets the associated IOSTX interface.

C++
HRESULT GetSyncObject(
   IOSTX **ppostx
);

Parameters

ppostx

[out] Pointer to the IOSTX interface to get.

Remarks

The caller must ensure that the same folder is not synchronized at the same time on more than one thread.

See also

Reference

IPSTX::EmulateSpooler
IPSTX::GetLastError


IPSTX2 : IPSTX

 Copy code hover
[image]

IPSTX2 : IPSTX
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX2

Vtable Order

Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
SetSpoolSuspendState | Sets the suspended state on the spooler.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX2::SetSpoolSuspendState

 Copy code hover
[image]

IPSTX2::SetSpoolSuspendState
See also Send feedback

Published: July 16, 2012

Sets the suspended state on the spooler.

C++
void SetSpoolSuspendState(
    ULONG ulState
);

Parameters

ulState

[in] The state to set the spooler to. It must be one of the following values:

SS_ACTIVE

SS_SUSPENDED

See also

Concepts

MAPI Constants


IPSTX3 : IPSTX2

 Copy code hover
[image]

IPSTX3 : IPSTX2
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX3

Vtable Order

Placeholder member

Not supported or documented.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX4 : IPSTX3

 Copy code hover
[image]

IPSTX4 : IPSTX3
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX4

Vtable Order

Placeholder member

Not supported or documented.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX5 : IPSTX4

 Copy code hover
[image]

IPSTX5 : IPSTX4
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX5

Vtable Order

Placeholder member

Not supported or documented.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX6 : IPSTX5

 Copy code hover
[image]

IPSTX6 : IPSTX5
See also Send feedback

Published: July 16, 2012

This interface provides helper functionality when performing replication through the IOSTX interface.

Provided by | Query on IMsgStore
Interface identifier: | IID_IPSTX6

Vtable Order

Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.
DisconnectStore | Disconnects the local store.
Placeholder member | Not supported or documented.
Placeholder member | Not supported or documented.

See also

Concepts

About the Replication API
MAPI Constants


IPSTX6::DisconnectStore

 Copy code hover
[image]

IPSTX6::DisconnectStore
See also Send feedback

Published: July 16, 2012

Disconnects the local store.

C++
HRESULT DisconnectStore(
    ULONG ulFlags
);

Parameters

ulFlags

[in] Flags to modify behavior. This parameter must always be set to 0.

See also

Concepts

About the Replication API
MAPI Constants


IPersistMessage : IUnknown

 Copy code hover
[image]

IPersistMessage : IUnknown
See also Send feedback

Published: July 16, 2012

Enables form viewers to handle the storage of a form and to transition between the various states.

Header file: | Mapiform.h
Exposed by: | Persist message objects
Implemented by: | Form objects
Called by: | Form viewers
Interface identifier: | IID_IPersistMessage
Pointer type: | LPPERSISTMESSAGE

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous error in the form object.
GetClassID | Returns an identifier that represents the form server that can manage the form.
IsDirty | Checks the form for changes that were made since the last save.
InitNew | Initializes a new message.
Load | Loads the form for a specified message.
Save | Saves a revised form back to the message from which it was loaded or created.
SaveCompleted | Notifies the form that a save operation has been completed.
HandsOffMessage | Causes the form to release its current message.

Remarks

All forms are required to implement the IPersistMessage interface.

IPersistMessage works similarly to the OLE IPersistStorage interface. For more information, see the IPersistStorage methods.

See also

Concepts

MAPI Interfaces


IPersistMessage::GetClassID

 Copy code hover
[image]

IPersistMessage::GetClassID
See also Send feedback

Published: July 16, 2012

Returns an identifier that represents the form server that can manage the form.

C++
HRESULT GetClassID(
  LPCLSID lpClassID
);

Parameters

lpClassID

[in, out] A pointer to the class identifier (CLSID) of the form.

Return value

S_OK

The class identifier was successfully returned.

Remarks

The IPersistMessge::GetClassID method sets the contents of the lpClassID parameter to the form server's class identifier and returns S_OK. When a form viewer calls GetClassID and it returns successfully, the form is placed in the Uninitialized state.

For more information about how class identifiers are used with structured storage objects, see the documentation for the IPersist::GetClassID method.

See also

Reference

IPersistMessage : IUnknown


IPersistMessage::GetLastError

 Copy code hover
[image]

IPersistMessage::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error in the form object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to a MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if the form cannot supply appropriate information for a MAPIERROR structure.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the address book provider does not support Unicode, or MAPI_UNICODE was not set and the address book provider supports only Unicode.

Remarks

Form objects implement the IPersistMessage::GetLastError method to supply information about a prior method call that failed. Form viewers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

A call to GetLastError does not affect the state of the form. When GetLastError returns, the form remains in the state that it was in before the call was made.

Notes to Callers

You can use the MAPIERROR structure, if the form supplies one, that is pointed to by the lppMAPIError parameter only if GetLastError returns S_OK. Sometimes the form cannot determine what the last error was or has nothing more to report about the error. In this situation, the form returns a pointer to NULL in lppMAPIError instead.

For more information about the GetLastError method, see MAPI Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IPersistMessage : IUnknown


IPersistMessage::HandsOffMessage

 Copy code hover
[image]

IPersistMessage::HandsOffMessage
See also Send feedback

Published: July 16, 2012

Causes the form to release its current message.

C++
HRESULT HandsOffMessage( void );

Parameters

None

Return value

S_OK

The message was successfully released.

Remarks

Forms transition into two HandsOff states:

  • HandsOffAfterSave

  • HandsOffFromNormal

When a form is in either of these states, it is in the process of being stored permanently.

Notes to Implementers

When a form viewer calls the IPersistMessage::HandsOffMessage method while your form is in the Normal or NoScribble state, recursively call HandsOffMessage on each message embedded in the current message and the IPersistStorage::HandsOffStorage method on each OLE object embedded in the current message. Then release the current message and all embedded messages and OLE objects. If your form was in the Normal state, transition to the HandsOffFromNormal state. If your form was in the NoScribble state, transition to the HandsOffAfterSave state. After a successful transition, call the message's IUnknown::Release method and return S_OK.

When a form viewer calls HandsOffMessage while your form is in either of the HandsOff states, return E_UNEXPECTED.

For more information about the different states of a form, see Form States. For more information about how to work with the HandsOff state of storage objects, see the IPersistStorage::HandsOffStorage method.

See also

Reference

IPersistMessage : IUnknown

Concepts

Form States


IPersistMessage::InitNew

 Copy code hover
[image]

IPersistMessage::InitNew
See also Send feedback

Published: July 16, 2012

Initializes a new message.

C++
HRESULT InitNew(
  LPMAPIMESSAGESITE pMessageSite,
  LPMESSAGE pMessage
);

Parameters

pMessageSite

[in] A pointer to the message site that the form will use to work with the message in the viewer.

pMessage

[in] A pointer to the new message.

Return value

S_OK

The new message was successfully initialized.

Remarks

Form viewers call the IPersistMessage::InitNew method when the user writes a new message that belongs to a message class that the form handles. If the form object has a valid user interface pointer, the user interface for the message object should be displayed.

InitNew should not be called when your form is in any state except the Uninitialized state. If the form is in one of the other states when InitNew is called, return E_UNEXPECTED.

Notes to Implementers

Typically, messages that have unsaved properties are marked as modified so that the client can display a dialog box that prompts the user whether these properties should be saved. If the user indicates that a message should be saved, save the data, mark the message as clean, and exit normally.

However, if processing for your newly initialized messages includes setting one or more computed properties, and it is important for those properties to be saved, do not mark the messages as modified. Because computed properties should be invisible to users, no dialog box should be displayed.

If your form has a reference to an active message site other than the one that is passed into InitNew, release the original site because it will no longer be used. Store the pointers to the message site and message from the pMessageSite and pMessage parameters and call both objects' IUnknown::AddRef methods to increment their reference counts.

Set the PR_MESSAGE_FLAGS (PidTagMessageFlags) and PR_MSG_STATUS (PidTagMessageStatus) properties for the new message to something appropriate for your message class. Many message classes, for example, set PR_MESSAGE_FLAGS to MSGFLAG_UNSENT for new messages.

Before returning, transition the form to the Normal state if no errors have occurred. Send a new message notification to all registered viewers by calling their IMAPIViewAdviseSink::OnNewMessage methods and return S_OK.

Notes to Callers

After you have made a successful call to InitNew, you can assume that the following required properties, and no others, have been set for the form:

PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit)

PR_IMPORTANCE (PidTagImportance)

PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested)

PR_PRIORITY (PidTagPriority)

PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested)

PR_SENSITIVITY (PidTagSensitivity)

PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId)

For more information about the states of forms, see Form States. For more information about how storage objects are initialized, see the IPersistStorage::InitNew method.

See also

Reference

IPersistMessage : IUnknown


IPersistMessage::IsDirty

 Copy code hover
[image]

IPersistMessage::IsDirty
See also Send feedback

Published: July 16, 2012

Checks the form for changes that were made since the last save.

C++
HRESULT IsDirty( void );

Parameters

None

Return value

S_OK

The form has changes that were made since it was last saved.

S_FALSE

The form does not have changes that were made since it was last saved.

Remarks

Form viewers call the IPersistMessage::IsDirty method to determine whether the message has unsaved data.

See also

Reference

IPersistMessage : IUnknown


IPersistMessage::Load

 Copy code hover
[image]

IPersistMessage::Load
See also Send feedback

Published: July 16, 2012

Loads the form for a specified message.

C++
HRESULT Load(
  LPMESSAGESITE pMessageSite,
  LPMESSAGE pMessage,
  ULONG ulMessageStatus,
  ULONG ulMessageFlags
);

Parameters

pMessageSite

[in] A pointer to the message site for the form to be loaded.

pMessage

[in] A pointer to the message for which the form should be loaded.

ulMessageStatus

[in] A bitmask of client-defined or provider-defined flags, copied from the message's PR_MSG_STATUS (PidTagMessageStatus) property, that provide information about the state of the message.

ulMessageFlags

[in] A bitmask of flags, copied from the message's PR_MESSAGE_FLAGS (PidTagMessageFlags) property, that provide further information about the state of the message.

Return value

S_OK

The form was successfully loaded.

Remarks

Form viewers call the IPersistMessage::Load method to load a form for an existing message.

Notes to Implementers

Load is called only when a form is in one of the following states:

  • Uninitialized

  • HandsOffAfterSave

  • HandsOffFromNormal

If a form viewer calls Load while the form is in any other state, the method returns E_UNEXPECTED.

If your form has a reference to an active message site other than the one that is passed into Load, release the original site because it will no longer be used. Store the pointers to the message site and message from the pMessageSite and pMessage parameters and call both objects' IUnknown::AddRef methods to increment their reference counts.

After AddRef has completed, store the properties from the ulMessageStatus and ulMessageFlags parameters into the form. Transition the form to its Normal state before displaying it, and notify registered viewers by calling their IMAPIViewAdviseSink::OnNewMessage methods.

If no errors occur, return S_OK.

See also

Reference

PidTagMessageFlags Canonical Property
PidTagMessageStatus Canonical Property
IPersistMessage : IUnknown

Concepts

Uninitialized State
HandsOffAfterSave State
HandsOffFromNormal State
Form States

Other resources

IPersistStorage::Load
IPersistStream::Load
IPersistFile::Load


IPersistMessage::Save

 Copy code hover
[image]

IPersistMessage::Save
See also Send feedback

Published: July 16, 2012

Saves a revised form back to the message from which it was loaded or created.

C++
HRESULT Save(
  LPMESSAGE pMessage,
  ULONG fSameAsLoad
);

Parameters

pMessage

[in] A pointer to the message.

fSameAsLoad

[in] TRUE to indicate that the message pointed to by pMessage is the message from which the form was loaded or created; otherwise, FALSE.

Return value

S_OK

The form was successfully saved.

Remarks

Form viewers call the IPersistMessage::Save method to save a revised form back to the message from which it was loaded or created.

Save should only be called when the form is in its Normal state.

Notes to Implementers

Do not commit the saved changes; it is up to the caller to commit the changes. Never make changes to the properties that belong to the form's message except during the Save call.

If fSameAsLoad is set to TRUE, you can save the changes to the form's existing message. If fSameAsLoad is set to FALSE, you must copy all of the properties from the original message into the message pointed to by pMessage before performing the save. Use the original message's IMAPIProp::CopyTo method to copy the properties.

When all of the properties have been copied, enter the NoScribble state. If no errors occur, return S_OK. Otherwise, return the error from the failed action.

If Save is called when the form is in any state other than Normal, return E_UNEXPECTED.

For more information about saving storage objects, see the documentation on the IPersistStorage methods.

See also

Reference

IPersistMessage : IUnknown

Concepts

Form States


IPersistMessage::SaveCompleted

 Copy code hover
[image]

IPersistMessage::SaveCompleted
See also Send feedback

Published: July 16, 2012

Notifies the form that a save operation has been completed.

C++
HRESULT SaveCompleted(
  LPMESSAGE pMessage
);

Parameters

pMessage

[in] A pointer to the newly saved message.

Return value

S_OK

The notification was successful.

E_INVALIDARG

The pMessage parameter is NULL and the form is either in the HandsOffFromNormal or HandsOffAfterSave state.

E_UNEXPECTED

The form is not in one of the following states:

  • HandsOffFromNormal

  • HandsOffAfterSave

  • NoScribble

Remarks

The IPersistMessage::SaveCompleted method is called by a form viewer to notify the form that all pending changes have been saved. SaveCompleted should be called only when the form is in one of the following states:

  • HandsOffFromNormal

  • HandsOffAfterSave

  • NoScribble

Notes to Implementers

There are several possible actions that the SaveCompleted method can perform, depending on what the message pointer parameter contains, and what state the message is in. However, when an action is successful, always save the current state of the message that the pMessage parameter points to and transition the form to its Normal state.

The following table describes the conditions that affect the actions you should take in your implementation of SaveCompleted.

Condition | Action
The pMessage parameter is NULL and the fSameAsLoad parameter of the IPersistMessage::Save method is set to TRUE. | Call the IMAPIViewAdviseSink::OnSaved method of all registered viewers, mark the form as clean, and return S_OK.
The pMessage parameter is NULL and the fSameAsLoad parameter of the IPersistMessage::Save method is set to FALSE. | Return S_OK.
The form is in the HandsOffFromNormal state. | Release the current message and replace it with the message pointed to by the pMessage parameter. Call the replacement message's IUnknown::AddRef method and return S_OK.
The form is in the HandsOffAfterSave state. | Call the IMAPIViewAdviseSink::OnSaved method of all registered viewers, mark the form as clean, and return S_OK.
The form is in the NoScribble state. | Release the current message and replace it with the message pointed to by pMessage. Call the replacement message's IUnknown::AddRef method. Call the IMAPIViewAdviseSink::OnSaved method of all registered viewers, mark the form as clean, and return S_OK.
The form is in one of the HandsOff states and the pMessage parameter is set to NULL. | Return E_INVALIDARG.
The form is in a state other than one of the HandsOff states or the NoScribble state. | Return E_UNEXPECTED.

For more information about saving storage objects, see the documentation for the IPersistStorage::SaveCompleted or IPersistFile::SaveCompleted methods.

See also

Reference

IPersistMessage : IUnknown

Concepts

Form States

Other resources

IPersistStorage::SaveCompleted
IPersistFile::SaveCompleted


IProfAdmin : IUnknown

 Copy code hover
[image]

IProfAdmin : IUnknown
See also Send feedback

Published: July 16, 2012

Supports the administration of profiles.

Header file: | Mapix.h
Exposed by: | Profile administration object
Implemented by: | MAPI
Called by: | Client applications
Interface identifier: | IID_IProfAdmin
Pointer type: | LPPROFADMIN

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous error that occurred to a profile administration object.
GetProfileTable | Provides access to the profile table, a table that contains information about all of the available profiles.
CreateProfile | Creates a new profile.
DeleteProfile | Deletes a profile.
ChangeProfilePassword | Deprecated. Changes the password for a profile.
CopyProfile | Copies a profile.
RenameProfile | Assigns a new name to a profile.
SetDefaultProfile | Sets or clears a client's default profile.
AdminServices | Provides access to a message service administration object for making changes to the message services in a profile.

See also

Concepts

MAPI Interfaces


IProfAdmin::AdminServices

 Copy code hover
[image]

IProfAdmin::AdminServices
See also Send feedback

Published: July 16, 2012

Provides access to a message service administration object for making changes to the message services in a profile.

C++
HRESULT AdminServices(
  LPSTR lpszProfileName,
  LPSTR lpszPassword,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  LPSERVICEADMIN FAR * lppServiceAdmin
);

Parameters

lpszProfileName

[in] A pointer to the name of the profile to be modified. The lpszProfileName parameter must not be NULL.

lpszPassword

[in] Always NULL.

ulUIParam

[in] A handle of the parent window for any dialog boxes or windows that this method displays.

ulFlags

[in] A bitmask of flags that controls the retrieval of the message service administration object. The following flags can be set:

MAPI_DIALOG

Enables the display of a user interface.

MAPI_UNICODE

The profile name is in Unicode format. If the MAPI_UNICODE flag is not set, the name is in ANSI format.

lppServiceAdmin

[out] A pointer to a pointer to a message service administration object.

Return value

S_OK

The message service administration object was successfully returned.

MAPI_E_LOGON_FAILED

The specified profile does not exist, or the password was wrong and a dialog box could not be displayed to the user to request the correct password because MAPI_DIALOG was not set in ulFlags.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::AdminServices method provides access to a message service administration object for making configuration changes to the message services in a profile.

The lpszPassword parameter must be NULL or a pointer to a zero-length string.

Notes to Callers

Although you can retrieve an IMsgServiceAdmin pointer by calling either this method or IMAPISession::AdminServices, call IProfAdmin::AdminServices if you have strictly a configuration client and offer no messaging features. IProfAdmin::AdminServices does not create a session object and does not load any service providers, which enhances performance.

You cannot use IProfAdmin::AdminServices to create a profile. Therefore, you must specify an existing valid profile in lpszProfileName. If the specified profile does not exist, IProfAdmin::AdminServices returns MAPI_E_LOGON_FAILED.

The name of the profile can be up to 64 characters in length and can include the following characters:

  • All alphanumeric characters, including accent characters and the underscore character.

  • Embedded spaces, but not leading or trailing spaces.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | HrAddServiceToProfile | MFCMAPI uses the IProfAdmin::AdminServices method to open a message service administration object for the selected profile to add services.

See also

Reference

IMAPISession::AdminServices
IProfAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IProfAdmin::ChangeProfilePassword

 Copy code hover
[image]

IProfAdmin::ChangeProfilePassword
See also Send feedback

Published: July 16, 2012

Deprecated. Changes the password for a profile.

C++
HRESULT ChangeProfilePassword(
  LPSTR lpszProfileName,
  LPSTR lpszOldPassword,
  LPSTR lpszNewPassword,
  ULONG ulFlags
);

Parameters

lpszProfileName

[in] A pointer to the name of the profile associated with the password to be changed.

lpszOldPassword

[in] A pointer to the current password.

lpszNewPassword

[in] A pointer to the new password.

ulFlags

[in] A bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The profile name and passwords are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

Return value

S_OK

If this method is called, it will return S_OK. However, no action will be taken.

Remarks

Do not use this method. MAPI does not support passwords for profiles.

See also

Reference

IProfAdmin : IUnknown


IProfAdmin::CopyProfile

 Copy code hover
[image]

IProfAdmin::CopyProfile
See also Send feedback

Published: July 16, 2012

Copies a profile.

C++
HRESULTCopyProfile(
  LPSTR lpszOldProfileName,
  LPSTR lpszOldPassword,
  LPSTR lpszNewProfileName,
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

lpszOldProfileName

[in] A pointer to the name of the profile to copy.

lpszOldPassword

[in] A pointer to the password of the profile to copy.

lpszNewProfileName

[in] A pointer to the new name of the copied profile.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

ulFlags

[in] A bitmask of flags that controls how the profile is copied. The following flags can be set:

MAPI_DIALOG

Displays a dialog box that prompts the user for the correct password of the profile to copy. If this flag is not set, no dialog box is displayed.

Return value

S_OK

The profile was successfully copied.

MAPI_E_ACCESS_DENIED

The new profile name is the same as that of an existing profile.

MAPI_E_LOGON_FAILED

The password for the profile to copy is incorrect, and a dialog box could not be displayed to the user to request the correct password because MAPI_DIALOG was not set in the ulFlags parameter.

MAPI_E_NOT_FOUND

The specified profile does not exist.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::CopyProfile method makes a copy of the profile pointed to by lpszOldProfileName, giving it the name pointed to by lpszNewProfileName. Copying a profile leaves the copy with the same password as the original.

The name of the original profile, its password, and the copy can be up to 64 characters in length and can include the following characters:

  • All alphanumeric characters, including accent characters and the underscore character.

  • Embedded spaces, but not leading or trailing spaces.

Profile passwords are not supported on all operating systems. On operating systems that do not support profile passwords, lpszOldPassword can be NULL or a pointer to a zero-length string.

If lpszOldPassword is set to NULL, the profile to be copied requires a password, and the MAPI_DIALOG flag is set; a dialog box that prompts the user to provide the password is displayed. If a password is required, but lpszOldPassword is set to NULL and the MAPI_DIALOG flag is not set, CopyProfile returns MAPI_E_LOGON_FAILED.

See also

Reference

IProfAdmin : IUnknown


IProfAdmin::CreateProfile

 Copy code hover
[image]

IProfAdmin::CreateProfile
See also Send feedback

Published: July 16, 2012

Creates a new profile.

C++
HRESULT CreateProfile(
  LPSTR lpszProfileName,
  LPSTR lpszPassword,
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

lpszProfileName

[in] A pointer to the name of the new profile.

lpszPassword

[in] A pointer to the password of the new profile.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

ulFlags

[in] A bitmask of flags that controls how the profile is created. The following flags can be set:

MAPI_DEFAULT_SERVICES

MAPI should populate the new profile with the message services that are included in the [Default Services] section of the Mapisvc.inf file.

MAPI_DIALOG

The configuration property sheets of each of the providers in the message services to be added can be displayed.

Return value

S_OK

The new profile was created.

MAPI_E_NO_ACCESS

The specified new profile already exists.

Remarks

The IProfAdmin::CreateProfile method creates a new profile.

Notes to Callers

You can call CreateProfile at application installation time or at any time during a session. When this method is called at installation time, many of the configuration settings come from the Mapisvc.inf configuration file. When this method is called during an active session, the settings come from the user who is prompted through a series of property sheets.

If the MAPI_DEFAULT_SERVICES flag is set in the ulFlags parameter, CreateProfile calls the message service entry point function for each message service in the [Default Services] section in the Mapisvc.inf file. Each message service entry point function is called with the ulContext parameter set to MSG_SERVICE_CREATE.

If both the MAPI_DIALOG and MAPI_DEFAULT_SERVICES flags are set, the values in the ulUIParam and ulFlags parameters are also passed to the message service entry point function. The message service entry point functions are called only after all available information from the Mapisvc.inf file has been added to the profile.

The name of the new profile and its password can be up to 64 characters in length and can include the following characters:

  • All alphanumeric characters, including accent characters and the underscore character.

  • Embedded spaces, but not leading or trailing spaces.

The lpszPassword parameter must be NULL or a pointer to a zero-length string.

See also

Reference

IMsgServiceAdmin::ConfigureMsgService
IMsgServiceAdmin::CreateMsgService
MSGSERVICEENTRY
IProfAdmin : IUnknown


IProfAdmin::DeleteProfile

 Copy code hover
[image]

IProfAdmin::DeleteProfile
See also Send feedback

Published: July 16, 2012

Deletes a profile.

C++
HRESULT DeleteProfile(
  LPSTR lpszProfileName,
  ULONG ulFlags
);

Parameters

lpszProfileName

[in] A pointer to the name of the profile to be deleted.

ulFlags

[in] Always NULL.

Return value

S_OK

The profile was successfully deleted.

MAPI_E_NOT_FOUND

The specified profile does not exist.

Remarks

The IProfAdmin::DeleteProfile method deletes a profile. If the profile to delete is in use when DeleteProfile is called, DeleteProfile returns S_OK but does not delete the profile immediately. Instead, DeleteProfile marks the profile for deletion and deletes it after it is no longer being used, when all of its active sessions have ended.

The entry point function for each message service in the profile is called with the MSG_SERVICE_DELETE value set in the ulContext parameter. First, the function deletes the service, and then it deletes the service's profile section. The message service entry point function is not called again after the service has been deleted.

No password is required to delete a profile.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | HrRemoveProfile | MFCMAPI uses the IProfAdmin::DeleteProfile method to delete the selected profile.

See also

Reference

IMsgServiceAdmin::DeleteMsgService
MSGSERVICEENTRY
IProfAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IProfAdmin::GetLastError

 Copy code hover
[image]

IProfAdmin::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error that occurred to a profile administration object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR structure returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

Remarks

The IProfAdmin::GetLastError method retrieves information about the last error returned from a method call for the profile administration object.

Notes to Callers

You can use the MAPIERROR structure, if MAPI supplies one, pointed to by the lppMAPIError parameter only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError.

To release all the memory allocated by MAPI for the MAPIERROR structure, call the MAPIFreeBuffer function.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IProfAdmin : IUnknown


IProfAdmin::GetProfileTable

 Copy code hover
[image]

IProfAdmin::GetProfileTable
See also Send feedback

Published: July 16, 2012

Provides access to the profile table, a table that contains information about all of the available profiles.

C++
HRESULT GetProfileTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] Always NULL.

lppTable

[out] A pointer to a pointer to the profile table.

Return value

S_OK

The profile table was successfully retrieved.

Remarks

The IProfAdmin::GetProfileTable method provides access to the profile table, which contains one row for every available profile. There are only two columns in each row: the profile's display name, and a flag that indicates whether the profile is the default.

Profiles that have been deleted, or that are in use but have been marked for deletion, are not included in the profile table. The profile table is static; subsequent additions and deletions of profiles are not reflected in the table.

If no profiles exist, GetProfileTable returns a table with zero rows.

For more information about the profile table, see Profile Tables.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnShowProfiles | MFCMAPI uses the IProfAdmin::GetProfileTable method to get the profile table to display in a new dialog box.

See also

Reference

IMAPITable : IUnknown
MAPILogonEx
IProfAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IProfAdmin::RenameProfile

 Copy code hover
[image]

IProfAdmin::RenameProfile
See also Send feedback

Published: July 16, 2012

Assigns a new name to a profile.

C++
HRESULT RenameProfile(
  LPSTR lpszOldProfileName,
  LPSTR lpszOldPassword,
  LPSTR lpszNewProfileName,
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

lpszOldProfileName

[in] A pointer to the current name of the profile to rename.

lpszOldPassword

[in] Always NULL.

lpszNewProfileName

[in] A pointer to the new name of the profile to rename.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

ulFlags

[in] Always NULL.

Return value

S_OK

The profile was successfully renamed.

MAPI_E_LOGON_FAILED

The profile password is incorrect.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::RenameProfile method assigns a new name to a profile, if it has one. If the profile to rename is in use by a client when RenameProfile is called, RenameProfile marks the profile and returns S_OK instead of attempting the rename operation while the profile is in use. When the profile is no longer being used, RenameProfile assigns it the new name.

The old and new names of the profile can be up to 64 characters in length and can include the following characters:

  • All alphanumeric characters, including accent characters and the underscore character.

  • Embedded spaces, but not leading or trailing spaces.

The lpszPassword should always be NULL or a pointer to a zero-length string.

See also

Reference

IProfAdmin : IUnknown


IProfAdmin::SetDefaultProfile

 Copy code hover
[image]

IProfAdmin::SetDefaultProfile
See also Send feedback

Published: July 16, 2012

Sets or clears a client's default profile.

C++
HRESULT SetDefaultProfile(
  LPSTR lpszProfileName,
  ULONG ulFlags
);

Parameters

lpszProfileName

[in] A pointer to the name of the profile that will become the default, or NULL. Setting lpszProfileName to NULL indicates that SetDefaultProfile should remove the existing default profile, leaving the client without a default.

ulFlags

[in] A bitmask of flags that controls the type of the string pointed to by lpszProfileName. The following flag can be set:

MAPI_UNICODE

The profile name is in Unicode format. If the MAPI_UNICODE flag is not set, the profile name is in ANSI format.

Return value

S_OK

A default profile was successfully established or removed.

MAPI_E_NOT_FOUND

The specified profile does not exist.

Remarks

The IProfAdmin::SetDefaultProfile method either establishes a particular profile as the client's default profile or clears the current default profile. The default profile is the profile that is automatically used whenever the client begins a MAPI session. SetDefaultProfile also sets the new default profile's PR_DEFAULT_PROFILE (PidTagDefaultProfile) property to TRUE.

Notes to Callers

To start a session with the default profile, pass the MAPI_USE_DEFAULT flag to the MAPILogonEx function.

See also

Reference

IProfAdmin::GetProfileTable
MAPILogonEx
PidTagDefaultProfile Canonical Property
IProfAdmin : IUnknown


IProfSect : IMAPIProp

 Copy code hover
[image]

IProfSect : IMAPIProp
See also Send feedback

Published: July 16, 2012

Works with the properties of profile section objects.

Header file: | Mapix.h
Exposed by: | Profile section objects
Implemented by: | MAPI
Called by: | Client applications and service providers
Interface identifier: | IID_IProfSect
Pointer type: | LPPROFSECT
Transaction model: | Nontransacted

Vtable Order

This interface does not have any unique methods.

Required properties | Access
PR_OBJECT_TYPE (PidTagObjectType) | Read-only
PR_PROFILE_NAME (PidTagProfileName) | Read-only

Notes to Callers

The IProfSect interface does not have any unique methods of its own, but you can call the profile section's IMAPIProp methods. There are some differences between the IProfSect implementation and other implementations of IMAPIProp:

  • IProfSect does not support a transaction model.

  • IProfSect does not support named properties.

  • IProfSect reserves the identifier range 0x67F0 to 0x67ff for secure properties.

Not supporting a transaction model means that all changes that were made to a profile section following calls to the IMAPIProp::CopyProps and IMAPIProp::CopyTo methods occur immediately. Calls to the IMAPIProp::SaveChanges method succeed but do not actually save any changes.

To be protected from changes that occur prematurely, service providers need to make copies of their profile sections that are displayed to users through property sheets. The property sheets should work with the copy, instead of the real profile section. When the user clicks the OK button to verify that the changes are accurate, the changes can be saved to the real profile section.

To implement a property sheet by using a copied profile section, use the following procedure:

  1. Open the profile section by calling the IMAPISupport::OpenProfileSection or IProviderAdmin::OpenProfileSection method.

  2. Call the CreateIProp function to retrieve a property data object — an object that supports the IPropData interface.

  3. Call the profile section's IMAPIProp::CopyTo method to copy the properties that will appear on the property sheet from the profile section to the property data object.

  4. Call the IMAPISupport::DoConfigPropSheet method to request that the service provider display a property sheet, and pass a pointer to the property data object in the lpConfigData parameter.

  5. When the user saves changes to configuration properties in the property sheet, call the IMAPIProp::CopyTo method to copy the properties from the property data object back to the profile section.

Profile sections, unlike other objects, do not support named properties. The IMAPIProp::GetIDsFromNames and IMAPIProp::GetNamesFromIDs methods return MAPI_E_NO_SUPPORT if they are called on a profile section object. If you use the IMAPIProp::SetProps method to set property identifiers in the range above 0x8000, the PT_ERROR property type will be returned.

Profile sections reserve the identifier range 0x67F0 to 0x67FF for secure properties. Service providers can use this range to store passwords and other provider-specific credentials. Properties in this range are not returned in the complete list of properties when NULL is passed in the lpPropTag parameter of the IMAPIProp::GetProps method, nor are they returned in the lppPropTagArray parameter of the IMAPIProp::GetPropList method. Secure properties must be requested specifically by their identifiers.

MAPI furnishes a profile section with the hard-coded constant MUID_PROFILE_INSTANCE as its identifier and PR_SEARCH_KEY (PidTagSearchKey) as its single property. MAPI ensures that the PR_SEARCH_KEY property value will be unique among all created profiles. Use PR_SEARCH_KEY instead of PR_PROFILE_NAME when uniqueness is important, because it is possible for a deleted profile to be followed by another profile with the same name.

For more information about how to use profile sections, see Administering Profiles and Message Services.

See also

Concepts

MAPI Interfaces


IPropData : IMAPIProp

 Copy code hover
[image]

IPropData : IMAPIProp
See also Send feedback

Published: July 16, 2012

Provides the ability to retrieve and change the access for an object's properties.

Header file: | Mapiutil.h
Exposed by: | Property data object
Implemented by: | MAPI
Called by: | Service providers and client applications
Interface identifier: | IID_IMAPIPropData
Pointer type: | LPPROPDATA
Transaction model: | Nontransacted

Vtable Order

HrSetObjAccess | Sets the access level for the object.
HrSetPropAccess | Sets the access level and status for one or more of the object's properties.
HrGetPropAccess | Retrieves the access level and status for one or more of the object's properties.
HrAddObjProps | Adds one or more properties of type PT_OBJECT to the object.

Remarks

The IPropData::IMAPIProp interface is implemented by MAPI and used primarily by service providers that access this implementation by calling the CreateIProp function.

For more information about access levels on objects and properties, see Permissions for Objects and Properties.

See also

Concepts

MAPI Interfaces


IPropData::HrAddObjProps

 Copy code hover
[image]

IPropData::HrAddObjProps
See also Send feedback

Published: July 16, 2012

Adds one or more properties of type PT_OBJECT to the object.

C++
HRESULT HrAddObjProps(
  LPSPropTagArray lpPropTagArray,
  LPSPropProblemArray FAR * lppProblems
);

Parameters

lpPropTagArray

[in] A pointer to an array of property tags that indicate the properties to add.

lppProblems

[in, out] On input, a valid pointer to an SPropProblemArray structure, or NULL. On output, a pointer to a pointer to a structure that contains information about properties that could not be added, or NULL. A pointer to a property problem array structure is returned only if a valid pointer is passed in.

Return value

S_OK

The properties were successfully added.

MAPI_E_INVALID_TYPE

A property type other than PT_OBJECT was passed in the array that the lpPropTagArray parameter points to.

MAPI_E_NO_ACCESS

The object has been set not to allow read/write permission.

MAPI_W_PARTIAL_COMPLETION

Some, but not all, of the properties were added.

Remarks

The IPropData::HrAddObjProps method adds one or more properties of type PT_OBJECT to the object. HrAddObjProps provides an alternative to the IMAPIProp::SetProps method for object properties, because object properties cannot be created by calling SetProps. Adding an object property results in the property tag being included in the list of property tags that the IMAPIProp::GetPropList method returns.

Notes to Callers

If HrAddObjProps returns MAPI_W_PARTIAL_COMPLETION and you have set lppProblems to a valid pointer, check the returned SPropProblemArray structure to find out which properties were not added. Typically, the only problem that occurs is lack of memory. Free the SPropProblemArray structure by calling the MAPIFreeBuffer function when you are finished with it.

To add a property, the target object must have read/write permission. If HrAddObjProps returns MAPI_E_NO_ACCESS, you cannot add properties to the object because it does not permit modification. To obtain read/write permission to an object prior to calling HrAddObjProps, call IPropData::HrSetObjAccess and set the ulAccess parameter to IPROP_READWRITE.

See also

Reference

MAPIFreeBuffer
SPropProblemArray
SPropTagArray
IPropData : IMAPIProp


IPropData::HrGetPropAccess

 Copy code hover
[image]

IPropData::HrGetPropAccess
See also Send feedback

Published: July 16, 2012

Retrieves the access level and status for one or more of the object's properties.

C++
HRESULT HrGetPropAccess(
  LPSPropTagArray FAR * lppPropTagArray,
  ULONG FAR * FAR * lprgulAccess
);

Parameters

lppPropTagArray

[in, out] On input, an array of property tags that indicate the properties for which to retrieve access levels and status; otherwise, a pointer to NULL, which indicates that HrGetPropAccess should retrieve access levels and status for all properties. On output, an array of property tags for which access and status flags were retrieved. The flags are stored in the array pointed to by the lprgulAccess parameter.

lprgulAccess

[out] A pointer to an array of flag bitmasks. Each bitmask indicates the access levels or status, or both, for each of the properties identified in the array pointed to by the lpPropTagArray parameter. The two arrays are positional in that the first bitmask that lprgulAccess points to describes the first property that lpPropTagArray points to, and so on. For each property tag, the following flags can be set:

Access-level flag

Status flag

IPROP_READONLY, which indicates that the property cannot be modified.

IPROP_CLEAN, which indicates that the property has not been modified.

IPROP_READWRITE, which indicates that the property can be modified.

IPROP_DIRTY, which indicates that the property has been modified.

Return value

S_OK

The access level and status flags for the properties were successfully returned.

Remarks

The IPropData::HrGetPropAccess method retrieves a set of flags that indicates the access level and status for one or more properties.

Notes to Callers:

You can use HrGetPropAccess for the following purposes:

  • To determine whether a client changed or deleted a writable property.

  • To prevent a client from changing or deleting a property by using the IMAPIProp methods.

If one of the properties in the property tag array pointed to by lppPropTagArray has been deleted, HrGetPropAccess sets the array entry to 0 on output. If you set lppPropTagArray to NULL and one of the object's properties has been deleted, the deleted property is returned in the array.

If a property has been modified, its IPROP_DIRTY flag is set in the corresponding entry in the array that lprgulAccess points to. Neither IPROP_READONLY nor IPROP_READWRITE will be set.

If a property has not been modified or deleted, only the IPROP_READONLY or IPROP_READWRITE flag will be set.

See also

Reference

SPropTagArray
IPropData : IMAPIProp


IPropData::HrSetObjAccess

 Copy code hover
[image]

IPropData::HrSetObjAccess
See also Send feedback

Published: July 16, 2012

Sets the access level for the object.

C++
HRESULT HrSetObjAccess(
  ULONG ulAccess
);

Parameters

ulAccess

[in] A bitmask of flags that specifies the object's access level. One of the following flags can be set:

IPROP_READONLY

Sets the object's access level to read-only.

IPROP_READWRITE

Sets the object's access level to read/write.

Return value

S_OK

The object's access level was successfully set.

Remarks

The IPropData::HrSetObjAccess method sets the access level for an entire object, rather than for individual properties. HrSetObjAccess can be used to change the access level established when the object was created.

Notes to Callers

To set an access level on a property, first call HrSetObjAccess with the IPROP_READWRITE flag set in the ulAccess parameter to make the object modifiable. Then call the IPropData::HrSetPropAccess method, specifying the target property in the array pointed to by the lpPropTagArray parameter.

To create an object with properties that will be read-only to clients, create a read/write object, add the necessary properties, and then call HrSetObjAccess to change the object's access to read-only.

You can also use HrSetObjAccess to prevent clients from creating new properties.

See also

Reference

IPropData::HrGetPropAccess
IPropData::HrSetPropAccess
IPropData : IMAPIProp


IPropData::HrSetPropAccess

 Copy code hover
[image]

IPropData::HrSetPropAccess
See also Send feedback

Published: July 16, 2012

Sets the access level or status for one or more of the object's properties.

C++
HRESULT HrSetPropAccess(
  LPSPropTagArray lpPropTagArray,
  ULONG FAR * rgulAccess
);

Parameters

lpPropTagArray

[in] A pointer to an array of property tags that indicate the properties to be modified.

rgulAccess

[in] An array of flag bitmasks. Each bitmask indicates the access levels or status, or both, for each of the properties identified in the array that the lpPropTagArray parameter points to. The two arrays are positional in that the first bitmask in rgulAccess describes the first property that lpPropTagArray points to, and so on. For each property tag, one access-level flag and one status flag can be set. The following table shows the possible flags.

Access-level flag

Status flag

IPROP_READONLY, which indicates that the property cannot be modified

IPROP_CLEAN, which indicates that the property has not been modified.

IPROP_READWRITE, which indicates that the property can be modified.

IPROP_DIRTY, which indicates that the property has been modified.

Return value

S_OK

The access-level and status flags have been successfully set.

MAPI_E_NO_ACCESS

An attempt was made to set a property on a read-only object or an object for which the caller has insufficient permissions.

MAPI_E_INVALID_PARAMETER

The rgulAccess parameter contains an invalid combination of flags, such as IPROP_READONLY and IPROP_READWRITE.

Remarks

The IPropData::HrSetPropAccess method changes the access level and status for the properties that are identified by the property tags in the SPropTagArray structure pointed to by the lpPropTagArray parameter. For each property, there is a corresponding entry in the rgulAccess array. The entry can be set to one flag that indicates the property's access level and another flag that indicates its status.

Notes to Callers

Use HrSetPropAccess to determine when a particular property value changes and to change the access level for one or more of an object's properties.

See also

Reference

SPropTagArray
IPropData : IMAPIProp


IProviderAdmin : IUnknown

 Copy code hover
[image]

IProviderAdmin : IUnknown
See also Send feedback

Published: July 16, 2012

Works with service providers in a message service.

Header file: | Mapidefs.h
Exposed by: | Provider administration objects
Implemented by: | MAPI
Called by: | Client applications and service providers
Interface identifier: | IID_IProviderAdmin
Pointer type: | LPPROVIDERADMIN

Vtable Order

GetLastError | Returns a MAPIERROR structure that contains information about the previous error that occurred to the provider administration object.
GetProviderTable | Provides access to the message service's provider table, a list of the service providers in the message service.
CreateProvider | Adds a service provider to the message service.
DeleteProvider | Deletes a service provider from the message service.
OpenProfileSection | Opens a profile section from the current profile and returns an IProfSect pointer for further access.

Remarks

Clients can get a pointer to an IProviderAdmin interface by calling the IMsgServiceAdmin::AdminProviders method; service providers are passed an IProviderAdmin pointer when their message service's entry point function is called.

See also

Concepts

MAPI Interfaces


IProviderAdmin::CreateProvider

 Copy code hover
[image]

IProviderAdmin::CreateProvider
See also Send feedback

Published: July 16, 2012

Adds a service provider to the message service.

C++
HRESULT CreateProvider(
  LPSTR lpszProvider,
  ULONG cValues,
  LPSPropValue lpProps,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  MAPIUID FAR * lpUID
);

Parameters

lpszProvider

[in] A pointer to the name of the provider to add.

cValues

[in] The count of property values pointed to by the lpProps parameter.

lpProps

[in] A pointer to a property value array that describes the properties of the provider to add.

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows this method displays. The ulUIParam parameter is used if the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] A bitmask of flags that controls the provider addition. The following flags can be set:

MAPI_DIALOG

Displays a dialog box to prompt for configuration information.

MAPI_UNICODE

The provider name and string properties are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

lpUID

[out] A pointer to the MAPIUID structure that contains the unique identifier that represents the provider to add.

Return value

S_OK

The provider was successfully added to the message service.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProviderAdmin::CreateProvider method adds a service provider to the message service. The lpszProvider parameter must point to the name of a provider that belongs to the message service. CreateProvider does not verify whether the name matches the name of a provider in the service; if the passed name does not match a service name, the call succeeds, but the results are unpredictable. Most message services do not allow providers to be added or deleted while the profile is in use.

After all of the available information about the service provider has been added to the profile from the Mapisvc.inf file, CreateProvider calls the message service's entry point function with the ulContext parameter set to MSG_SERVICE_PROVIDER_CREATE. If MAPI_DIALOG is set in the CreateProvider method's ulFlags parameter, the values in the ulUIParam and ulFlags parameters are also passed to the entry point function. These additional parameters enable the service provider to display its property sheet so the user can enter configuration settings.

See also

Reference

MAPIUID
MSGSERVICEENTRY
SPropValue
IProviderAdmin : IUnknown


IProviderAdmin::DeleteProvider

 Copy code hover
[image]

IProviderAdmin::DeleteProvider
See also Send feedback

Published: July 16, 2012

Deletes a service provider from the message service.

C++
HRESULT DeleteProvider(
  LPMAPIUID lpUID
);

Parameters

lpUID

[in, out] A pointer to the MAPIUID structure that contains the unique identifier that represents the provider to delete.

Return value

S_OK

The provider was successfully deleted from the message service.

MAPI_E_NOT_FOUND

The MAPIUID pointed to by the lpUID parameter was not recognized.

Remarks

The IProviderAdmin::DeleteProvider method deletes a service provider from the message service. DeleteProvider determines the service provider to delete by matching the MAPIUID structure pointed to by lpUID with the set of identifiers registered by the active service providers.

Most message services do not allow providers to be deleted while the profile is in use. If the provider to delete is in use, DeleteProvider marks it for deletion instead of removing it immediately and returns S_OK. When the provider is no longer being used, it is deleted.

DeleteProvider calls the message service's entry point function before the provider is removed from the service. The ulContext parameter is set to MSG_SERVICE_PROVIDER_DELETE. The message service entry point function performs the following tasks:

  • Deletes the service provider.

  • Deletes the service provider's profile section.

The message service entry point function is not called again after the provider has been deleted.

See also

Reference

MAPIUID
MSGSERVICEENTRY
IProviderAdmin : IUnknown


IProviderAdmin::GetLastError

 Copy code hover
[image]

IProviderAdmin::GetLastError
See also Send feedback

Published: July 16, 2012

Returns a MAPIERROR structure that contains information about the previous error that occurred to the provider administration object.

C++
HRESULT GetLastError(
  HRESULT hResult,
  ULONG ulFlags,
  LPMAPIERROR FAR * lppMAPIError
);

Parameters

hResult

[in] An HRESULT data type that contains the error value generated in the previous method call.

ulFlags

[in] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The strings in the MAPIERROR returned in the lppMAPIError parameter are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] A pointer to a pointer to the returned MAPIERROR structure that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR to return.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and GetLastError does not support Unicode, or MAPI_UNICODE was not set and GetLastError supports only Unicode.

Remarks

The IProviderAdmin::GetLastError method supplies information about a prior method call that failed. Callers can provide their users with detailed information about the error by including the data from the MAPIERROR structure in a dialog box.

Notes to Callers

You can use the MAPIERROR structure, if MAPI supplies one, that the lppMAPIError parameter points to only if GetLastError returns S_OK. Sometimes MAPI cannot determine what the last error was or has nothing more to report about the error. In this situation, a pointer to NULL is returned in lppMAPIError instead.

For more information about the GetLastError method, see Using Extended Errors.

See also

Reference

MAPIERROR
MAPIFreeBuffer
IProviderAdmin : IUnknown


IProviderAdmin::GetProviderTable

 Copy code hover
[image]

IProviderAdmin::GetProviderTable
See also Send feedback

Published: July 16, 2012

Provides access to the message service's provider table, a list of the service providers in the message service.

C++
HRESULT GetProviderTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parameters

ulFlags

[in] A bitmask of flags that controls the type of the strings returned in the provider table's columns. The following flag can be set:

MAPI_UNICODE

The string columns are in Unicode format. If the MAPI_UNICODE flag is not set, the columns are in ANSI format.

lppTable

[out] A pointer to a pointer to the provider table.

Return value

S_OK

The provider table was successfully returned.

Remarks

The IProviderAdmin::GetProviderTable method retrieves a pointer to the message service's provider table, a table that MAPI maintains that contains information about each service provider in the message service.

Unlike the provider table returned by the IMsgServiceAdmin::GetProviderTable method, the provider table returned by IProviderAdmin::GetProviderTable may include additional rows that represent information associated with one or more of the service providers in the message service. This extra information is added to the profile with the "Sections" keyword of the Mapisvc.inf file. When a provider has extra profile sections, it stores the MAPIUID structures for these sections in the PR_SERVICE_EXTRA_UIDS (PidTagServiceExtraUids) property. PR_SERVICE_EXTRA_UIDS is saved in the message service profile section.

Providers that have been deleted, or are in use but have been marked for deletion, are not included in the provider table. Provider tables are static, meaning that subsequent additions to or deletions from the message service are not reflected in the table.

If the message service has no providers, IProviderAdmin::GetProviderTable returns a table with zero rows and the S_OK return value.

Setting the MAPI_UNICODE flag in the ulFlags parameter affects the format of the columns returned from the IMAPITable::QueryColumns and IMAPITable::QueryRows methods.

This flag also controls the property types in the sort order returned by the IMAPITable::QuerySortOrder method.

For a complete list of the columns in the provider table, see Provider Table.

Notes to Callers

To retrieve the rows of a provider table in transport order, sort the table by the PR_PROVIDER_ORDINAL (PidTagProviderOrdinal) column.

To retrieve only those rows that represent service providers (without including any extra rows), limit your retrieval to the rows that have a value of PT_ERROR in their PR_RESOURCE_TYPE (PidTagResourceType) column.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MsgServiceTableDlg.cpp | CMsgServiceTableDlg::OnDisplayItem | MFCMAPI uses the IProviderAdmin::GetProviderTable method to get the table of providers to render in a new dialog box.

See also

Reference

IMAPITable::QueryColumns
IMAPITable::QueryRows
IMAPITable::QuerySortOrder
IMAPITable::SetColumns
IMsgServiceAdmin::GetProviderTable
IProviderAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IProviderAdmin::OpenProfileSection

 Copy code hover
[image]

IProviderAdmin::OpenProfileSection
See also Send feedback

Published: July 16, 2012

Opens a profile section from the current profile and returns an IProfSect pointer for further access.

C++
HRESULT OpenProfileSection(
  LPMAPIUID lpUID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPPROFSECT FAR * lppProfSect
);

Parameters

lpUID

[in] A pointer to the MAPIUID structure that contains the unique identifier for the profile section to be opened. Clients must not pass NULL for the lpUID parameter. Service providers can pass NULL to retrieve the MAPIUID when they call from their message service entry point functions.

lpInterface

[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the profile section. Passing NULL results in the profile section's standard interface (IProfSect) being returned.

ulFlags

[in] A bitmask of flags that controls how the profile section is opened. The following flags can be set:

MAPI_DEFERRED_ERRORS

Enables OpenProfileSection to return successfully, possibly before the profile section is fully available to the caller. If the profile section is not available, making a subsequent call to it can raise an error.

MAPI_MODIFY

Requests read/write permission. By default, objects are opened with read-only permission, and callers should not work on the assumption that read/write permission has been granted. Clients are not allowed read/write permission to provider sections of the profile.

MAPI_FORCE_ACCESS

Allows access to all profile sections, even those owned by individual service providers.

lppProfSect

[out] A pointer to a pointer to the profile section.

Return value

S_OK

The profile section was successfully opened.

MAPI_E_NO_ACCESS

An attempt was made to modify a read-only profile section or to access an object for which the user has insufficient permissions.

MAPI_E_NOT_FOUND

The requested profile section does not exist.

Remarks

The IProviderAdmin::OpenProfileSection method opens a profile section, enabling the caller to read information from and possibly write information to the active profile.

Clients cannot open profile sections that belong to providers by using the OpenProfileSection method.

Multiple clients or service providers can simultaneously open a profile section with read-only permission. However, when a profile section is open with read/write permission, no other calls can be made to open the section, regardless of the type of access. If a profile section is open with read-only permission, a subsequent call to request read/write permission will fail with MAPI_E_NO_ACCESS. Likewise, if a section is open with read/write permission, a subsequent call to request read-only permission will also fail.

Notes to Callers

If you request that OpenProfileSection open a nonexistent profile section by passing MAPI_MODIFY in ulFlags and an unknown MAPIUID in lpUID, the profile section will be created.

If you request that OpenProfileSection open a nonexistent section with read-only permission, it returns MAPI_E_NOT_FOUND.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIProfileFunctions.cpp | OpenProfileSection | MFCMAPI uses the IProviderAdmin::OpenProfileSection method to open a profile section from the current profile.

See also

Reference

IMAPIProp : IUnknown
IProfSect : IMAPIProp
MAPIUID
IProviderAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample


IProxyStoreObject

 Copy code hover
[image]

IProxyStoreObject
Send feedback

Published: July 16, 2012

Provides an Internet Message Access Protocol (IMAP) store object that has been unwrapped and that allows access to items in the Personal Folders file (PST) without invoking synchronization and downloading the items.

Quick Info

Inherited from: | IUnknown
Provided By: | Message store provider
Interface identifier: | IID_IProxyStoreObject

Vtable Order

Placeholder member | Not supported or documented.
IProxyStoreObject::UnwrapNoRef | Gets a pointer to an unwrapped IMAP store.
Placeholder member | Not supported or documented.

Remarks

Call IUnknown::QueryInterface on the source message store to obtain the IProxyStoreObject interface. Then call IProxyStoreObject::UnwrapNoRef to obtain the unwrapped store object. If QueryInterface returns the error MAPI_E_INTERFACE_NOT_SUPPORTED, then the store has not been wrapped.

Because UnwrapNoRef does not increment the reference count for this new pointer to the unwrapped store object, after successfully calling UnwrapNoRef, you should call IUnknown::AddRef to maintain the reference count.


IProxyStoreObject::UnwrapNoRef

 Copy code hover
[image]

IProxyStoreObject::UnwrapNoRef
See also Send feedback

Published: July 16, 2012

Gets a pointer to an unwrapped Internet Message Access Protocol (IMAP) store object that provides access to the underlying Personal Folders file (PST) without invoking synchronization and downloading the items.

C++
HRESULT IProxyStoreObject::UnwrapNoRef (     LPVOID *ppvObject );

Parameters

ppvObject

[out] Pointer to an IMsgStore : IMAPIProp store object that is unwrapped.

Return Values

S_OK

  • The call was successful and a pointer to an unwrapped interface has been returned in ppvObject.

Remarks

Without first unwrapping an IMAP store, accessing a message in the store can force a synchronization that attempts to download the entire message. Using the unwrapped store allows access to the message in its current state without triggering a download.

Because UnwrapNoRef does not increment the reference count for this new pointer to the unwrapped store object, after successfully calling UnwrapNoRef, you should call IUnknown::AddRef to maintain the reference count.

See also

Reference

IProxyStoreObject


ITableData : IUnknown

 Copy code hover
[image]

ITableData : IUnknown
See also Send feedback

Published: July 16, 2012

Provides utility methods for working with tables. MAPI provides table data objects or objects that implement ITableData to help service providers perform table maintenance. To obtain a table data object, service providers call the CreateTable function.

Header file: | Mapiutil.h
Exposed by: | Table data objects
Implemented by: | MAPI
Called by: | Service providers
Interface identifier: | IID_IMAPITableData
Pointer type: | LPTABLEDATA

Vtable Order

HrGetView | Creates a table view, returning a pointer to an IMAPITable implementation.
HrModifyRow | Inserts a new table row, possibly replacing an existing row.
HrDeleteRow | Deletes a table row.
HrQueryRow | Retrieves a table row.
HrEnumRow | Retrieves a row based on its position in the table.
HrNotify | Sends a notification for a table row.
HrInsertRow | Inserts a table row.
HrModifyRows | Inserts multiple table rows, possibly replacing existing rows.
HrDeleteRows | Deletes multiple table rows.

Remarks

The MAPI implementation of ITableData works with tables by holding all of the data and any associated restrictions in memory, making it unsuitable for use with very large tables. Large restrictions and complex operations such as categorization are not supported.

Table data objects identify rows by using an index column, a property that is guaranteed to have a unique value for each row. Most service providers use the PR_INSTANCE_KEY (PidTagInstanceKey) property as the index column. Properties that have multiple values cannot be used as an index column.

Table data objects generate a single notification regardless of the number of rows affected by a change or deletion. If a target row in an operation does not exist, a row is added.

See also

Concepts

MAPI Interfaces


ITableData::HrDeleteRow

 Copy code hover
[image]

ITableData::HrDeleteRow
See also Send feedback

Published: July 16, 2012

Deletes a table row.

C++
HRESULT HrDeleteRow(
  LPSPropValue lpSPropValue
);

Parameters

lpSPropValue

[in] A pointer to a property value structure that describes the index column for the row to be deleted. The ulPropTag member of the property value structure should contain the same property tag as the ulPropTagIndexColumn parameter from the call to the CreateTable function.

Return value

S_OK

The row was successfully deleted.

MAPI_E_NOT_FOUND

The property pointed to by the lpSPropValue parameter does not identify a row in the table.

Remarks

The ITableData::HrDeleteRow method removes the table row that contains the column that matches the property pointed to by the lpSPropValue parameter. The data for the row is deleted and the row is removed from all open views.

After the row is deleted, notifications are sent to all clients or service providers that have a view of the table and that have called the table's IMAPITable::Advise method to register for notifications.

Deleting a row does not reduce the column set that is available to existing views or subsequently opened views, even if the deleted row is the last row that has a value for a specific column.

See also

Reference

CreateTable
ITableData::HrDeleteRows
ITableData::HrModifyRow
SPropValue
TABLE_NOTIFICATION
ITableData : IUnknown


ITableData::HrDeleteRows

 Copy code hover
[image]

ITableData::HrDeleteRows
See also Send feedback

Published: July 16, 2012

Deletes multiple table rows.

C++
HRESULT HrDeleteRows(
  ULONG ulFlags,
  LPSRowSet lprowsetToDelete,
  ULONG FAR * cRowsDeleted
);

Parameters

ulFlags

[in] A bitmask of flags that controls the deletion. The following flag can be set:

TAD_ALL_ROWS

Deletes all rows from the table and all corresponding views, sending a single TABLE_RELOAD notification.

lprowsetToDelete

[in] A pointer to a row set that describes the rows to be deleted. The lprowsetToDelete parameter can be NULL if the TAD_ALL_ROWS flag is set in the ulFlags parameter.

cRowsDeleted

[out] The count of the deleted rows.

Return value

S_OK

The table rows were successfully deleted.

Remarks

The ITableData::HrDeleteRows method locates and removes the table rows that contain the columns that match the property pointed to by the lpProps member of each aRow entry in the row set. An index column is used to identify each row; this column must have the same property tag as the property tag passed in the ulPropTagIndexColumn parameter in the call to the CreateTable function.

The number of rows that were actually deleted is returned in cRowsDeleted. No error is returned if one or more rows could not be found.

After the rows are deleted, notifications are sent to all clients or service providers that have a view of the table and that have called the table's IMAPITable::Advise method to register for notifications.

Deleting rows does not reduce the columns available to existing table views or subsequently opened table views, even if the deleted rows are the last that have values for a specific column.

See also

Reference

CreateTable
ITableData::HrDeleteRow
ITableData::HrModifyRows
SRowSet
TABLE_NOTIFICATION
ITableData : IUnknown


ITableData::HrEnumRow

 Copy code hover
[image]

ITableData::HrEnumRow
See also Send feedback

Published: July 16, 2012

Retrieves a row based on its position in the table.

C++
HRESULT HrEnumRow(
  ULONG ulRowNumber,
  LPSRow FAR * lppSRow
);

Parameters

ulRowNumber

[in] The number of the row for which to return properties. The value in the ulRowNumber parameter can be any value from 0, which indicates the first row in the table, through n - 1, which indicates the last row in the table.

lppSRow

[out] A pointer to a pointer to an SRow structure that describes the target row.

Return value

S_OK

The row was retrieved successfully, or a row for the row number specified by the ulRowNumber parameter does not exist.

Remarks

The ITableData::HrEnumRow method retrieves a row based on a sequential number. This number represents the order of insertion (0 indicates the first row, and the number of rows minus 1 indicates the last row). MAPI maintains this chronological order of row insertion for the lifetime of the table data object.

If the number specified in ulRowNumber does not correspond to a row in the table, HrEnumRow returns S_OK and sets the lppSRow parameter to NULL.

MAPI allocates memory for the returned SRow structure by using the MAPIAllocateBuffer function when the table data object is created. The caller must release this memory by calling the MAPIFreeBuffer function.

To retrieve rows from a table in the order that they were inserted, table data object users call the HrEnumRow method.

See also

Reference

MAPIAllocateBuffer
MAPIFreeBuffer
SRow
ITableData : IUnknown


ITableData::HrGetView

 Copy code hover
[image]

ITableData::HrGetView
See also Send feedback

Published: July 16, 2012

Creates a table view, returning a pointer to an IMAPITable implementation.

C++
HRESULT HrGetView(
  LPSSortOrderSet lpSSortOrderSet,
  CALLERRELEASE FAR * lpfCallerRelease,
  ULONG_PTR ulCallerData,
  LPMAPITABLE FAR * lppMAPITable
);

Parameters

lpSSortOrderSet

[in] A pointer to a sort order structure that describes the sort order for the table view. If NULL is passed in the lpSSortOrderSet parameter, the view is not sorted.

lpfCallerRelease

[in] A pointer to a callback function based on the CALLERRELEASE prototype that MAPI calls when it releases the view. If NULL is passed in the lpfCallerRelease parameter, no function is called on release of the view.

ulCallerData

[in] The data that must be saved with the new view and passed to the callback function pointed to by lpfCallerRelease.

lppMAPITable

[out] A pointer to a pointer to the newly created view.

Return value

S_OK

The view was successfully created.

Remarks

The ITableData::HrGetView method creates a read-only view of the data in the table, sorted in the order pointed to by the lpSSortOrderSet parameter. The cursor is placed at the beginning of the first row in the view. An IMAPITable interface implementation for accessing the view is returned.

Service providers call HrGetView when they need to give a client access to a table. HrGetView creates the view and returns the IMAPITable pointer. Service providers in turn pass the pointer on to the client. When the client is finished using the table and calls its IUnknown::Release method, HrGetView calls the callback function pointed to by the lpfCallerRelease parameter.

If a service provider needs to return to a client a view that has a customized column set or a restriction, the provider can call the view's IMAPITable::SetColumns and IMAPITable::Restrict methods before allowing the client access.

See also

Reference

CALLERRELEASE
IMAPITable : IUnknown
SSortOrderSet
ITableData : IUnknown


ITableData::HrInsertRow

 Copy code hover
[image]

ITableData::HrInsertRow
See also Send feedback

Published: July 16, 2012

Inserts a table row.

C++
HRESULT HrInsertRow(
  ULONG uliRow,
  LPSRow lpSRow
);

Parameters

uliRow

[in] A sequential row number that represents a specific row. The new row will be placed after the row that the number indicates. The uliRow parameter can contains row numbers from 0 through n, where n is the total number of rows in the table. Passing n in uliRow appends the row to the end of the table.

lpSRow

[in] A pointer to an SRow structure that describes the row to be inserted.

Return value

S_OK

The row was successfully inserted.

MAPI_E_INVALID_PARAMETER

A row that has the same value for its index column as the row to be inserted already exists in the table.

Remarks

The ITableData::HrInsertRow method inserts a row into a table at a particular position. The new row is inserted after the row that is in the position specified by the uliRow parameter.

If uliRow is set to the number of rows in the table, the new row is appended to the end of the table.

The property that acts as the index column for the table must be included in the lpProps member of the SRow structure pointed to by the lpSRow parameter. This index property, typically PR_INSTANCE_KEY (PidTagInstanceKey), is used to uniquely identify the row for future maintenance tasks.

The property columns in the SRow structure do not have to be in the same order as the property columns in the table.

After the row is inserted, notifications are sent to all clients or service providers that have a view of the table and that have called the table's IMAPITable::Advise method to register for notifications. No notification is sent if the inserted row is not included in the view due to a restriction.

See also

Reference

SRow
TABLE_NOTIFICATION
ITableData : IUnknown


ITableData::HrModifyRow

 Copy code hover
[image]

ITableData::HrModifyRow
See also Send feedback

Published: July 16, 2012

Inserts a new table row, possibly replacing an existing row.

C++
HRESULT HrModifyRow(
  LPSRow lpSRow
);

Parameters

lpSRow

[in] A pointer to an SRow structure that describes the row to be added or to replace an existing row. One of the property value structures pointed to by the lpProps member of the SRow structure should contain the index column, the same value that was specified in the ulPropTagIndexColumn parameter in the call to the CreateTable function.

Return value

S_OK

The row was successfully inserted or modified.

MAPI_E_INVALID_PARAMETER

The passed-in row does not have an index column.

Remarks

The ITableData::HrModifyRow method inserts the row described by the SRow structure pointed to by the lpSRow parameter. If a row that has the same value for its index column as the row that lpSRow points to already exists in the table, the existing row is replaced. If no row exists that matches the one included in the SRow structure, HrModifyRow adds the row to the end of the table.

All views of the table are modified to include the row pointed to by lpSRow. However, if a view has a restriction in place that excludes the row, it may not be visible to the user.

The columns in the row pointed to by lpSRow do not have to be in the same order as the columns in the table. The caller can also include as columns properties that are not currently in the table. For existing views, HrModifyRow makes these new columns available but does not include them in the current column set. For future views, HrModifyRow includes the new columns in the column set.

After HrModifyRow adds the row, notifications are sent to all clients or service providers that have a view of the table and that have called the table's IMAPITable::Advise method to register for notifications.

See also

Reference

SRow
TABLE_NOTIFICATION
ITableData : IUnknown


ITableData::HrModifyRows

 Copy code hover
[image]

ITableData::HrModifyRows
See also Send feedback

Published: July 16, 2012

Inserts multiple table rows, possibly replacing existing rows.

C++
HRESULT HrModifyRows(
  ULONG ulFlags,
  LPSRowSet lpSRowSet
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpSRowSet

[in] A pointer to an SRowSet structure that contains the set of rows to be added, replacing existing rows if necessary. One of the property value structures pointed to by the lpProps member of each SRow structure in the row set should contain the index column, the same value that was specified in the ulPropTagIndexColumn parameter in the call to the CreateTable function.

Return value

S_OK

The rows were successfully inserted or modified.

MAPI_E_INVALID_PARAMETER

One or more of the passed-in rows does not have an index column. If this error is returned, no rows are changed.

Remarks

The ITableData::HrModifyRows method inserts the rows described by the SRowSet structure pointed to by the lpSRowSet parameter. If the index column value of a row in the row set matches the value for an existing row in the table, the existing row is replaced. If no row exists that matches the one included in the SRowSet structure, HrModifyRows adds the row to the end of the table.

All views of the table are modified to include the rows pointed to by lpSRowSet. However, if a view has a restriction in place that excludes a row, it may not be visible to the user.

The columns in the rows pointed to by lpSRowSet do not have to be in the same order as the columns in the table. The caller can also include as columns properties that are not currently in the table. For existing views, HrModifyRows makes these new columns available but does not include them in the current column set. For future views, HrModifyRows includes the new columns in the column set.

After HrModifyRows has added the rows, notifications are sent to all clients or service providers that have a view of the table and that have called the table's IMAPITable::Advise method to register for notifications. MAPI sends TABLE_ROW_ADDED or TABLE_ROW_MODIFIED notifications for each row, up to eight rows. If more than eight rows are affected by the HrModifyRows call, MAPI sends a single TABLE_CHANGED notification instead.

See also

Reference

SRowSet
ITableData : IUnknown


ITableData::HrNotify

 Copy code hover
[image]

ITableData::HrNotify
See also Send feedback

Published: July 16, 2012

Sends a notification for a table row.

C++
HRESULT HrNotify(
  ULONG ulFlags,
  ULONG cValues,
  LPSPropValue lpSPropValue
);

Parameters

ulFlags

[in] Reserved; must be zero.

cValues

[in] The count of property values in the SPropValue structure pointed to by the lpSPropValue parameter.

lpSPropValue

[in] A pointer to an SPropValue structure that describes the values of the columns in the target row.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The ITableData::HrNotify method sends a TABLE_ROW_MODIFIED notification for the row that matches the row described by the properties pointed to by the lpSPropValue parameter. HrNotify sends the notification regardless of whether changes have occurred to the row. All clients and service providers that have views of the table and have called IMAPITable::Advise to register for notifications on their views receive this notification.

See also

Reference

SPropValue
TABLE_NOTIFICATION
ITableData : IUnknown


ITableData::HrQueryRow

 Copy code hover
[image]

ITableData::HrQueryRow
See also Send feedback

Published: July 16, 2012

Retrieves a table row.

C++
HRESULT HrQueryRow(
  LPSPropValue lpSPropValue,
  LPSRow FAR * lppSRow,
  ULONG FAR * lpuliRow
);

Parameters

lpSPropValue

[in] A pointer to a property value structure that describes the index column for the row to be retrieved. The ulPropTag member of the property value structure should contain the same property tag as the ulPropTagIndexColumn parameter from the call to the CreateTable function, which accesses the ITableData implementation.

lppSRow

[out] A pointer to a pointer to the retrieved row.

lpuliRow

[in, out] On input, a valid pointer or NULL, which indicates that no information needs to be returned. On output, a valid pointer that points to the row's row number, a sequential number that identifies the row's position in the table.

Return value

S_OK

The row was successfully retrieved.

MAPI_E_INVALID_PARAMETER

The SPropValue structure that lpSPropValue points to does not contain the index column property.

Remarks

The ITableData::HrQueryRow method retrieves all of the properties for the row that has an index column that matches the value of the index column included in the property structure pointed to by lpSPropValue. HrQueryRow also returns the row number, if the caller requests it, that identifies the row's position in the table.

Because HrQueryRow does not modify the SPropValue structure pointed to by lpSPropValue, callers must free the structure when HrQueryRow returns. Callers must also free the SRow structure that contains the retrieved row.

See also

Reference

MAPIAllocateBuffer
MAPIFreeBuffer
SPropValue
SRow
ITableData : IUnknown


ITnef : IUnknown

 Copy code hover
[image]

ITnef : IUnknown
See also Send feedback

Published: July 16, 2012

Provides methods for encapsulating MAPI properties that are not supported by a messaging system into binary streams that can be attached to messages. The format used for this encapsulation is the Transport-Neutral Encapsulation Format (TNEF). The target transport provider or MAPI-based client application can then, on receiving a message that includes a TNEF attachment, recover the properties from the attachment.

Header file: | Tnef.h
Exposed by: | TNEF objects
Implemented by: | MAPI
Called by: | Transport providers, message store providers, and gateways
Interface identifier: | IID_ITNEF
Pointer type: | LPTNEF

Vtable Order

AddProps | Enables the calling service provider or gateway to add properties to the encapsulation of a message or an attachment.
ExtractProps | Extracts the properties from a TNEF encapsulation.
Finish | Finishes processing for all TNEF operations that are queued and waiting.
OpenTaggedBody | Opens a stream interface on the text of an encapsulated message.
SetProps | Sets the value of one or more properties for an encapsulated message or attachment without modifying the original message or attachment.
EncodeRecips | Encodes a view for a message's recipient table in the TNEF data stream for the message.
FinishComponent | Processes individual components from a message one at a time into a TNEF stream.

See also

Concepts

MAPI Interfaces


ITnef::AddProps

 Copy code hover
[image]

ITnef::AddProps
See also Send feedback

Published: July 16, 2012

Enables the calling service provider or gateway to add properties to the encapsulation of a message or an attachment.

C++
HRESULT AddProps(
  ULONG ulFlags,
  ULONG ulElemID,
  LPVOID lpvData,
  LPSPropTagArray lpPropList
);

Parameters

ulFlags

[in] A bitmask of flags that controls how properties are included in or excluded from encapsulation. The following flags can be set:

TNEF_PROP_ATTACHMENTS_ONLY

Encodes only the properties in the lpPropList parameter that are part of attachments in the message.

TNEF_PROP_CONTAINED

Encodes only properties from the attachment specified by the ulElemID parameter. If the lpvData parameter is not NULL, the data pointed to is written into the attachment's encapsulation in the file indicated by the PR_ATTACH_TRANSPORT_NAME (PidTagAttachTransportName) property.

TNEF_PROP_CONTAINED_TNEF

Encodes only properties from the message or attachment specified by the ulElemID parameter. If this flag is set, the value in lpvData must be an IStream pointer.

TNEF_PROP_EXCLUDE

Encodes all properties not specified in the lpPropList parameter.

TNEF_PROP_INCLUDE

Encodes all properties specified in lpPropList.

TNEF_PROP_MESSAGE_ONLY

Encodes only those properties specified in lpPropList that are part of the message itself.

ulElemID

[in] An attachment's PR_ATTACH_NUM (PidTagAttachNumber) property, which contains a number that uniquely identifies the attachment in its parent message. The ulElemID parameter is used when special handling is requested for an attachment. The ulElemID parameter should be 0 unless the TNEF_PROP_CONTAINED or TNEF_PROP_CONTAINED_TNEF flag is set in the ulFlags parameter.

lpvData

[in] A pointer to attachment data used to replace the data of the attachment specified in ulElemID. The lpvData parameter should be NULL unless TNEF_PROP_CONTAINED or TNEF_PROP_CONTAINED_TNEF is set in ulFlags.

lpPropList

[in] A pointer to the list of properties to include in or exclude from encapsulation.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::AddProps method to list properties to be included in or excluded from the Transport-Neutral Encapsulation Format (TNEF) processing of a message or an attachment. By using successive calls, the provider or gateway can specify a list of properties to add and encode or to exclude from being encoded. Providers and gateways can also use AddProps to provide information about any special handling attachments should be given.

AddProps is supported only for TNEF objects that are opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function.

Note that no actual TNEF encoding happens for AddProps until the ITnef::Finish method is called. This functionality means that pointers passed into AddProps must remain valid until after the call to Finish is made. At that point, all objects and data passed in with AddProps calls can be released or freed.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | SaveToTNEF | MFCMAPI uses the ITnef::AddProps method to copy properties from a message to a TNEF stream.

See also

Reference

ITnef::Finish
OpenTnefStream
OpenTnefStreamEx
PidTagAttachTransportName Canonical Property
ITnef : IUnknown

Concepts

MFCMAPI as a Code Sample


ITnef::EncodeRecips

 Copy code hover
[image]

ITnef::EncodeRecips
See also Send feedback

Published: July 16, 2012

Encodes a view for a message's recipient table in the Transport-Neutral Encapsulation Format (TNEF) data stream for the message.

C++
HRESULT EncodeRecips(
  ULONG ulFlags,
  LPMAPITABLE lpRecipientTable
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpRecipientTable

[in] A pointer to the recipient table for which the view is encoded. The lpRecipientTable parameter can be NULL.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::EncodeRecips method to perform TNEF encoding for a particular recipient table view. TNEF encoding is useful, for example, if a provider or gateway requires a particular column set, sort order, or restriction for the recipient table.

A provider or gateway passes the table view to be encoded in the lpRecipientTable parameter. The TNEF implementation encodes the recipient table with the given view, using the given column set, sort order, restriction, and position. If a provider or gateway passes NULL in lpRecipientTable, TNEF gets the recipient table from the message being encoded by using the IMessage::GetRecipientTable method, and processes every row of the table into the TNEF stream by using the table's current settings.

Calling EncodeRecips with NULL in lpRecipientTable thus encodes all message recipients and is equivalent to calling the ITnef::AddProps method with the TNEF_PROP_INCLUDE flag in its ulFlags parameter and the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property in its lpPropList parameter.

Note that it is rarely necessary to call EncodeRecips unless there is a requirement to encode a particular recipient table view. Foreign messaging systems almost always have facilities for handling recipient lists that are powerful enough to handle the common needs of encoding recipient lists; therefore, these systems almost never require TNEF for this purpose.

See also

Reference

IMessage::GetRecipientTable
ITnef::AddProps
PidTagMessageRecipients Canonical Property
ITnef : IUnknown


ITnef::ExtractProps

 Copy code hover
[image]

ITnef::ExtractProps
See also Send feedback

Published: July 16, 2012

Extracts the properties from a TNEF encapsulation.

C++
HRESULT ExtractProps(
  ULONG ulFlags,
  LPSPropTagArray lpPropList,
  LPSTnefProblemArray FAR * lpProblems
);

Parameters

ulFlags

[in] A bitmask of flags that controls how properties are decoded. The following flags can be set:

TNEF_PROP_EXCLUDE

Decodes all properties not specified in the lpPropList parameter.

TNEF_PROP_INCLUDE

Decodes all properties specified in lpPropList.

lpPropList

[in] A pointer to the list of properties to include in or exclude from the decoding operation.

lpProblems

[out] A pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties, if any, were not encoded properly. If NULL is passed in the lpProblems parameter, no property problem array is returned.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_CORRUPT_DATA

Data being decoded into a stream is corrupted.

Remarks

Transport providers, message store providers, and gateways call the ITnef::ExtractProps method to extract (that is, decode) properties from the encapsulation of a message or an attachment that was passed to the OpenTnefStream function. The calling provider or gateway can specify a list of properties to decode. Providers and gateways can also use ExtractProps to provide information about any special handling for attachments.

ExtractProps populates the original message passed into OpenTnefStream with the decoded properties. Subsequent ExtractProps calls go back to the message and extract the new list of properties.

Unlike the ITnef::AddProps method, which queues requested actions until the ITnef::Finish method is called, the ExtractProps method decodes the encapsulated properties immediately when it is called. For that reason, the target message for encapsulation decoding should be relatively empty. Existing properties in the target message are overwritten by encapsulated properties.

ExtractProps is supported only for objects that are opened with the TNEF_DECODE flag for the OpenTnefStream or OpenTnefStreamEx function.

The TNEF implementation reports TNEF stream encoding problems without stopping the ExtractProps process. The STnefProblemArray structure returned in lpProblems indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the one of the STnefProblem structures contained in STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which ExtractProps does not return a problem report were processed successfully.

Note Note

If a property in the MAPI encapsulation block cannot be processed and leaves the stream unreliable during the decoding of a TNEF stream, decoding of the encapsulation block is stopped and a problem is reported. The problem array for this type of problem contains 0L for the ulPropTag member, attMAPIProps or attAttachment for the ulAttribute member, and MAPI_E_UNABLE_TO_COMPLETE for the scode member. Note that the decoding of the stream is not halted, just the decoding of the MAPI encapsulation block. The stream decoding continues with the next attribute block.

If a provider or gateway does not work with problem arrays, it can pass NULL in lppProblems; in this case, no problem array is returned.

The value returned in lpProblems is valid only if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray structure by calling the MAPIFreeBuffer function.

See also

Reference

ITnef::AddProps
ITnef::Finish
ITnef::SetProps
MAPIFreeBuffer
OpenTnefStream
OpenTnefStreamEx
STnefProblemArray
ITnef : IUnknown


ITnef::Finish

 Copy code hover
[image]

ITnef::Finish
See also Send feedback

Published: July 16, 2012

Finishes processing for all Transport-Neutral Encapsulation Format (TNEF) operations that are queued and waiting.

C++
HRESULT Finish(
  ULONG ulFlags,
  WORD FAR * lpKey,
  LPSTnefProblemArray FAR * lpProblem
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpKey

[out] A pointer to the PR_ATTACH_NUM (PidTagAttachNumber) key property of an attachment. The TNEF encapsulation object uses this key to match an attachment to its attachment placement tag in a message. This key should be unique to each attachment.

lpProblem

[out] A pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties, if any, were not encoded properly. If NULL is passed in the lpProblem parameter, no property problem array is returned.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::Finish method to perform the encoding of all properties for which encoding was requested in calls to the ITnef::AddProps and ITnef::SetProps methods. If the TNEF object was opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function, the Finish method encodes the requested properties into the encapsulation stream passed to that object. If the TNEF object was opened with the TNEF_DECODE flag, the Finish method decodes the properties from the TNEF stream and writes them back to the message they belong to.

After the Finish call, the pointer to the encapsulation stream points to the end of the TNEF data. If the provider or gateway needs to use the TNEF stream data after the Finish call, it must reset the stream pointer to the beginning of the TNEF stream data.

The TNEF implementation reports TNEF stream encoding problems without stopping the Finish process. The STnefProblemArray structure returned in the lpProblem parameter indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the one of the STnefProblem structures contained in STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which Finish does not return a problem report were processed successfully.

If a provider or gateway does not work with problem arrays, it can pass NULL in lpProblem; in this case, no problem array is returned.

The value returned in lpProblem is valid only if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, the STnefProblemArray structure is not filled in and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray by calling the MAPIFreeBuffer function.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | SaveToTNEF | MFCMAPI uses the ITnef::Finish method to finish processing of the new TNEF stream.

See also

Reference

ITnef::AddProps
MAPIFreeBuffer
OpenTnefStream
OpenTnefStreamEx
PidTagAttachNumber Canonical Property
STnefProblemArray
ITnef : IUnknown

Concepts

MFCMAPI as a Code Sample


ITnef::FinishComponent

 Copy code hover
[image]

ITnef::FinishComponent
See also Send feedback

Published: July 16, 2012

Processes individual components from a message one at a time into a Transport-Neutral Encapsulation Format (TNEF) stream.

C++
HRESULT FinishComponent(
  ULONG ulFlags,
  ULONG ulComponentID,
  LPSPropTagArray lpCustomPropList,
  LPSPropValue lpCustomProps,
  LPSPropTagArray lpPropList,
  LPSTnefProblemArray FAR * lppProblems
);

Parameters

ulFlags

[in] A bitmask of flags that controls which component will be finished. One or the other of the following flags must be set:

TNEF_COMPONENT_ATTACHMENT

Processing will be finished for an attachment object; the ulComponentID parameter contains the PR_ATTACH_NUM (PidTagAttachNumber) property of the attachment.

TNEF_COMPONENT_MESSAGE

Processing will be finished for a message object.

ulComponentID

[in] 0 to indicate processing for a message, or the PR_ATTACH_NUM property of an attachment to be processed. If the TNEF_COMPONENT_MESSAGE flag is set in the ulFlags parameter, ulComponentID must be 0.

lpCustomPropList

[in] A pointer to an SPropTagArray structure that contains property tags that identify the properties passed in the lpCustomProps parameter. There must be a one-to-one correspondence between each property value in lpCustomProps and a property tag in the lpCustomPropList parameter.

lpCustomProps

[in] A pointer to an SPropValue structure that contains property values for the properties to encode.

lpPropList

[in] A pointer to an SPropTagArray structure that contains property tags for the properties to encode.

lppProblems

[out] A pointer to a pointer to a returned STnefProblemArray structure. The STnefProblemArray structure indicates which properties, if any, were not encoded properly. If NULL is passed in the lppProblems parameter, no property problem array is returned.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::FinishComponent method to perform TNEF processing for one component, either a message or an attachment, as indicated by the flag set in the ulFlags parameter.

For component processing to be enabled, the calling provider or gateway pass the TNEF_COMPONENT_ENCODING flag in ulFlags for the OpenTnefStream or OpenTnefStreamEx function that opened the object to receive encoding.

Passing values in the lpCustomPropList and lpCustomProps parameters performs component encoding equivalent to that done by the ITnef::SetProps method. Passing a value in the lpPropList parameter performs component encoding equivalent to that done by the ITnef::AddProps method with the TNEF_PROP_INCLUDE flag set in ulFlags. Passing these values enables you to perform encodings with a single call instead of multiple calls.

The TNEF implementation reports TNEF stream encoding problems without stopping the FinishComponent process. The STnefProblemArray structure returned in lppProblems indicates which TNEF attributes or MAPI properties, if any, could not be processed. The value returned in the scode member of the one of the STnefProblem structures contained in STnefProblemArray indicates the specific problem. The provider or gateway can work on the assumption that all properties or attributes for which FinishComponent does not return a problem report were processed successfully.

If a provider or gateway does not work with problem arrays, it can pass NULL in lppProblems; in this case, no problem array is returned.

The value returned in lppProblems is valid only if the call returns S_OK. When S_OK is returned, the provider or gateway should check the values returned in the STnefProblemArray structure. If an error occurs on the call, the STnefProblemArray structure is not filled in, and the calling provider or gateway should not use or free the structure. If no error occurs on the call, the calling provider or gateway must release the memory for the STnefProblemArray by calling the MAPIFreeBuffer function.

See also

Reference

ITnef::AddProps
ITnef::SetProps
MAPIFreeBuffer
OpenTnefStream
OpenTnefStreamEx
SPropTagArray
STnefProblemArray
ITnef : IUnknown


ITnef::OpenTaggedBody

 Copy code hover
[image]

ITnef::OpenTaggedBody
See also Send feedback

Published: July 16, 2012

Opens a stream interface on the text of an encapsulated message.

C++
HRESULT OpenTaggedBody(
  LPMESSAGE lpMessage,
  ULONG ulFlags,
  LPSTREAM FAR * lppStream
);

Parameters

lpMessage

[in] A pointer to the message with which the stream is associated. This message is not required to be the same message that is passed in the call to the OpenTnefStream or OpenTnefStreamEx function.

ulFlags

[in] A bitmask of flags that controls how the stream interface is opened. The following flags can be set:

MAPI_CREATE

If a property does not exist in the current message, it should be created. If the property does exist, the current data in the property should be replaced with the data from the Transport-Neutral Encapsulation Format (TNEF) stream. When an implementation sets the MAPI_CREATE flag, it should also set the MAPI_MODIFY flag.

MAPI_MODIFY

Requests read/write permission. The default interface is read-only. MAPI_MODIFY must be set whenever MAPI_CREATE is set.

lppStream

[out] A pointer to a pointer to a stream object that contains the text from the PR_BODY (PidTagBody) property of the passed-in encapsulated message and that supports the IStream interface.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::OpenTaggedBody method to open a stream interface on the text of an encapsulated message (that is, on a TNEF object).

As part of its processing, OpenTaggedBody either inserts or parses attachment tags that indicate the position of any attachments or OLE objects in the message text. The attachment tags are in the following format:

[[ attachment name : n in attachment container name ]]

attachment name describes the attachment object; n is a number that identifies the attachment that is part of a sequence, incrementing from the value passed in the lpKey parameter of the OpenTnefStream or OpenTnefStreamEx function; and attachment container name describes the physical component where the attachment object resides.

OpenTaggedBody reads out message text and inserts an attachment tag wherever an attachment object originally appeared in the text. The original message text is not changed.

When a message that has tags is passed to a stream, the tags are stripped out and the attachment objects are relocated in the position of the tags in the stream.

See also

Reference

OpenTnefStream
OpenTnefStreamEx
PidTagBody Canonical Property
ITnef : IUnknown


ITnef::SetProps

 Copy code hover
[image]

ITnef::SetProps
See also Send feedback

Published: July 16, 2012

Sets the value of one or more properties for an encapsulated message or attachment without modifying the original message or attachment.

C++
HRESULT SetProps(
  ULONG ulFlags,
  ULONG ulElemID,
  ULONG cValues,
  LPSPropValue lpProps
);

Parameters

ulFlags

[in] A bitmask of flags that controls how property values are set. The following flag can be set:

TNEF_PROP_CONTAINED

Encodes only properties from the message or attachment specified by the ulElemID parameter.

ulElemID

[in] An attachment's PR_ATTACH_NUM (PidTagAttachNumber) property, which contains a number that uniquely identifies the attachment in its parent message.

cValues

[in] The number of property values in the SPropValue structure pointed to by the lpProps parameter.

lpProps

[in] A pointer to an SPropValue structure that contains the property values of the properties to set.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

Transport providers, message store providers, and gateways call the ITnef::SetProps method to set properties to include in the encapsulation of a message or an attachment without modifying the original message or attachment. Any properties set with this call override existing properties in the encapsulated message.

SetProps is supported only for TNEF objects that are opened with the TNEF_ENCODE flag for the OpenTnefStream or OpenTnefStreamEx function. Any number of properties can be set with this call.

Note Note

No actual TNEF encoding for SetProps happens until after the ITnef::Finish method is called. This functionality means that pointers passed into SetProps must remain valid until after the call to Finish is made. At that point, all objects and data passed into SetProps calls can be released or freed.

See also

Reference

ITnef::Finish
OpenTnefStream
OpenTnefStreamEx
PidTagAttachNumber Canonical Property
SPropValue
ITnef : IUnknown


IXPLogon : IUnknown

 Copy code hover
[image]

IXPLogon : IUnknown
See also Send feedback

Published: July 16, 2012

Gives the MAPI spooler access to a transport provider.

Header file: | Mapispi.h
Exposed by: | Transport logon objects
Implemented by: | Transport providers
Called by: | The MAPI spooler
Interface identifier: | IID_IXPLogon
Pointer type: | LXPLOGON

Vtable Order

AddressTypes | Returns the types of recipients that the transport provider handles.
RegisterOptions | Not supported or documented.
TransportNotify | Signals the occurrence of an event about which the transport provider requested notification.
Idle | Indicates that the system is idle, enabling the transport provider to perform low-priority operations.
TransportLogoff | Initiates the logoff process.
SubmitMessage | Indicates that the MAPI spooler has a message for the transport provider to deliver.
EndMessage | Informs the transport provider that the MAPI spooler completed its processing on an outbound message.
Poll | Indicates whether the transport provider has received one or more inbound messages.
StartMessage | Initiates the transfer of an inbound message from the transport provider to the MAPI spooler.
OpenStatusEntry | Opens the transport provider's status object.
ValidateState | Checks the transport provider's external status.
FlushQueues | Requests that the transport provider immediately deliver all pending inbound or outbound messages.

See also

Concepts

MAPI Interfaces


IXPLogon::AddressTypes

 Copy code hover
[image]

IXPLogon::AddressTypes
See also Send feedback

Published: July 16, 2012

Returns the types of recipients that the transport provider handles.

C++
HRESULT AddressTypes(
  ULONG FAR * lpulFlags,
  ULONG FAR * lpcAdrType,
  LPSTR FAR * FAR * lpppszAdrTypeArray,
  ULONG FAR * lpcMAPIUID,
  LPUID FAR * FAR * lpppUIDArray
);

Parameters

lpulFlags

[out] A bitmask of flags that controls the type of strings returned. The following flag can be set:

MAPI_UNICODE

The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpcAdrType

[out] A pointer to the count of entries in the array pointed to by the lpppszAdrTypeArray parameter.

lpppszAdrTypeArray

[out] A pointer to a pointer to an array of strings that identify recipient types.

lpcMAPIUID

[out] A pointer to the count of entries in the array pointed to by the lpppUIDArray parameter.

lpppUIDArray

[out] A pointer to a pointer to an array of pointers to MAPIUID structures that identify recipient types.

Return value

S_OK

The transport provider successfully indicated the types of recipients that it can handle.

Notes to Implementers

The MAPI spooler calls the IXPLogon::AddressTypes method immediately after a transport provider returns from a call to the IXPProvider::TransportLogon method so the transport provider can indicate what types of recipients it handles. To indicate this, the transport provider should pass back in the lpppszAdrTypeArray parameter a pointer to an array of pointers to strings, or pass back in the lpppUIDArray parameter a pointer to an array of pointers to MAPIUID structures, or pass values in both parameters.

These two arrays are used for different identification processes. MAPI and the MAPI spooler use the MAPIUID structures in the lpppUIDArray array to identify those recipient entry identifiers that are directly handled by the transport provider or by the messaging system to which the transport provider connects. Neither MAPI nor the MAPI spooler expands addresses by using entry identifiers contained in any of these MAPIUID structures; these structures are used only for recipient type identification.

The MAPI spooler uses each of the strings in the lpppszAdrTypeArray parameter for a comparison test when it decides which transport provider should handle which recipients for an outbound message. If a message recipient's PR_ADDRTYPE (PidTagAddressType) property exactly matches a string that identifies one of the messaging address types that the transport provider supplies, the provider can deliver the message to that recipient.

If multiple transport providers can handle the same type of recipient, MAPI selects a transport provider based on the transport priority order indicated in the client application's profile. To determine which transport provider to use, the MAPI spooler scans all provider-specified MAPIUID structures in priority order, and then all provider-specified address type values in priority order. The first transport provider to match a particular recipient in this scan gets the first opportunity to handle this recipient. If that provider does not handle the recipient, the MAPI spooler continues the scan to find a transport provider for any recipient not yet handled. The scan continues until no further matches are found, at which point a nondelivery report is generated for any recipient that was not handled.

If the provider always supports a particular set of recipient types, the address type and MAPIUID arrays that the transport provider passed can be static. If the transport provider dynamically constructs these arrays, it can allocate memory by using the support object that was previously passed in the call to TransportLogon, although this is not necessary.

The memory used for the address type and MAPIUID arrays should remain allocated until the final call to the IXPLogon::TransportLogoff method, at which time the transport provider can free the memory, if necessary. The transport provider should not alter the contents of these arrays after it returns from the TransportLogoff call.

A transport provider that can handle any type of recipient can return NULL in the lpppszAdrTypeArray parameter. Transport providers for LAN-based messaging systems that use a central server to deliver outgoing messages to various foreign message systems commonly do this. This type of transport provider should be installed last in the MAPI and MAPI spooler priority order of transport providers in the profile.

A transport provider that does not support outbound messages that are dispatched to it based on address type should return a single zero-length string in lpppszAdrTypeArray. If a transport provider supports no recipient types, it should pass NULL for the MAPIUID structure and an empty string for the address type. Transport providers of this type are most commonly used to install a message preprocessor.

See also

Reference

IXPLogon::TransportLogoff
IXPProvider::TransportLogon
MAPIUID
IXPLogon : IUnknown


IXPLogon::EndMessage

 Copy code hover
[image]

IXPLogon::EndMessage
See also Send feedback

Published: July 16, 2012

Informs the transport provider that the MAPI spooler completed its processing on an outbound message.

C++
HRESULT EndMessage(
  ULONG ulMsgRef,
  ULONG FAR * lpulFlags
);

Parameters

ulMsgRef

[in] A message-specific reference value that was obtained in an earlier call to the IXPLogon::SubmitMessage method.

lpulFlags

[out] A bitmask of flags that indicates to the MAPI spooler what it should do with the message. If no flags are set, the message has been sent. The following flags can be set:

END_DONT_RESEND

The transport provider has all the information it needs about this message for now. When the transport provider requires more information or when it has sent the message, it notifies the MAPI spooler by calling the IMAPISupport::SpoolerNotify method with the NOTIFY_SENTDEFERRED flag and by passing the message's entry identifier.

END_RESEND_LATER

The transport provider is not sending the message at the current time for reasons that are not error conditions. The transport provider should be called again later to send the message.

END_RESEND_NOW

The transport provider needs to restart the message passed to it in an IMessage::SubmitMessage method call.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::EndMessage method after it completes the processing involved in providing extended delivery or nondelivery information.

Once this call returns, the value in the ulMsgRef parameter is no longer valid for this message. The transport provider can reuse the same value on a future message.

All objects that the transport provider opens during the transfer of a message should be released before the EndMessage call returns, with the exception of the message object that the MAPI spooler passes to the transport provider. The message object passed by the MAPI spooler is invalid after the EndMessage call.

See also

Reference

IMAPISupport::SpoolerNotify
IMessage::SubmitMessage
IXPLogon::SubmitMessage
IXPLogon : IUnknown


IXPLogon::FlushQueues

 Copy code hover
[image]

IXPLogon::FlushQueues
See also Send feedback

Published: July 16, 2012

Requests that the transport provider immediately deliver all pending inbound or outbound messages.

C++
HRESULT FlushQueues(
  ULONG_PTR ulUIParam,
  ULONG cbTargetTransport,
  LPENTRYID lpTargetTransport,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

cbTargetTransport

[in] Reserved; must be zero.

lpTargetTransport

[in] Reserved; must be NULL.

ulFlags

[in] A bitmask of flags that controls how message queue flushing is accomplished. The following flags can be set:

FLUSH_DOWNLOAD

The inbound message queue or queues should be flushed.

FLUSH_FORCE

The transport provider should process this request, if possible, even if doing so is time consuming.

FLUSH_NO_UI

The transport provider should not display a user interface.

FLUSH_UPLOAD

The outbound message queue or queues should be flushed.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::FlushQueues method to advise the transport provider that the MAPI spooler is about to begin processing messages. The transport provider should call the IMAPISupport::ModifyStatusRow method to set an appropriate bit for its state in the PR_STATUS_CODE (PidTagStatusCode) property of its status row. After updating its status row, the transport provider should return S_OK for the FlushQueues call. The MAPI spooler then starts sending messages, with the operation being synchronous to the MAPI spooler.

To support its implementation of the IMAPIStatus::FlushQueues method, the MAPI spooler calls IXPLogon::FlushQueues for all logon objects for active transport providers that are running in a profile session. When a transport provider's FlushQueues method is called as a result of a client application call to IMAPIStatus::FlushQueues, the message processing occurs asynchronously to the client.

See also

Reference

IMAPIStatus::FlushQueues
IXPLogon : IUnknown


IXPLogon::Idle

 Copy code hover
[image]

IXPLogon::Idle
See also Send feedback

Published: July 16, 2012

Indicates that the system is idle, enabling the transport provider to perform low-priority operations.

C++
HRESULT Idle(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The MAPI spooler periodically calls the IXPLogon::Idle method, if requested, during times when the system is idle by passing the XP_LOGON_SP flag in the call to the IXPProvider::TransportLogon method that opened the current session. At times when the system is idle, the transport provider can perform background operations that are not appropriate during other calls, or that need to occur on a regular basis.

See also

Reference

IXPProvider::TransportLogon
IXPLogon : IUnknown


IXPLogon::OpenStatusEntry

 Copy code hover
[image]

IXPLogon::OpenStatusEntry
See also Send feedback

Published: July 16, 2012

Opens the transport provider's status object.

C++
HRESULT OpenStatusEntry(
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPMAPISTATUS FAR * lppEntry
);

Parameters

lpInterface

[in] A pointer to an interface identifier (IID) for the transport logon object. Passing NULL returns the IMAPIStatus interface. The lpInterface parameter can also be set to an identifier for an interface for the object.

ulFlags

[in] A bitmask of flags that controls how the status object is opened. The following flag can be set:

MAPI_MODIFY

Requests read/write permission. The default interface is read-only.

lpulObjType

[out] A pointer to the type of the opened object.

lppEntry

[out] A pointer to the pointer to the opened status object.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::OpenStatusEntry method when a client application calls an OpenEntry method for the entry identifier in the transport provider's status table row. OpenStatusEntry opens an object with the IMAPIStatus interface associated with this particular transport provider logon. This object is then used to enable client applications to call IMAPIStatus methods (for example, to reconfigure the logon session by using the IMAPIStatus::SettingsDialog method, or to validate the state of the logon session by using the IMAPIStatus::ValidateState method).

See also

Reference

IMAPIStatus : IMAPIProp
IXPLogon : IUnknown


IXPLogon::Poll

 Copy code hover
[image]

IXPLogon::Poll
See also Send feedback

Published: July 16, 2012

Indicates whether the transport provider has received one or more inbound messages.

C++
HRESULT Poll(
  ULONG FAR * lpulIncoming
);

Parameters

lpulIncoming

[out] A value that indicates the existence of inbound messages. A nonzero value indicates that there are inbound messages.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler periodically calls the IXPLogon::Poll method if the transport provider indicates it must be polled for new messages, which the provider does by passing the LOGON_SP_POLL flag to the call to the IXPProvider::TransportLogon method at the beginning of a session. If the transport provider indicates in response to the Poll call that there are one or more inbound messages available for it to process, the MAPI spooler calls the IXPLogon::StartMessage method to allow the provider to process the first inbound message. The transport provider indicates inbound messages by setting the value in the lpulIncoming parameter to a nonzero value.

See also

Reference

IXPLogon::StartMessage
IXPProvider::TransportLogon
IXPLogon : IUnknown


IXPLogon::StartMessage

 Copy code hover
[image]

IXPLogon::StartMessage
See also Send feedback

Published: July 16, 2012

Initiates the transfer of an inbound message from the transport provider to the MAPI spooler.

C++
HRESULT StartMessage(
  ULONG ulFlags,
  LPMESSAGE lpMessage,
  ULONG FAR * lpulMsgRef
);

Parameters

ulFlags

[in] Reserved; must be zero.

lpMessage

[in] A pointer to a message object (representing the inbound message) that has read/write permission, which is used by the transport provider to access and manipulate that message. This object remains valid until after the transport provider returns from the call to IXPLogon::StartMessage.

lpulMsgRef

[out] A pointer to a reference value assigned to the message. The MAPI spooler initializes this value to 1 before it returns the pointer to the transport provider.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::StartMessage method to initiate the transfer of an inbound message from the transport provider to the MAPI spooler. Before the transport provider starts to use the message pointed to by lpMessage, it should store a message reference in the lpulMsgRef parameter for potential use by a call to the IXPLogon::TransportNotify method.

During a StartMessage call, the MAPI spooler processes methods for objects opened during the transfer of the message, and it also processes any attachments. This processing can take a long time. Transport providers can call the IMAPISupport::SpoolerYield callback function for the MAPI spooler frequently during this processing to release CPU time for other system tasks.

All recipients in the recipient table that the transport provider creates for the message must contain all required addressing properties. If necessary, the provider can construct a custom recipient to represent a particular recipient. However, if the provider can produce a recipient entry that includes more information, it should do so. For example, if a transport provider has enough information about an address book provider's recipient format that it can build a valid entry identifier for a recipient for that format, it should build the entry identifier.

If any nontransmittable properties are received, the transport provider should not store them in the new message. However, the transport provider should store all transmittable properties it receives in the new message.

If the incoming message is a delivery report or a nondelivery report and the transport provider is unable to use the IMAPISupport::StatusRecips method to generate the report from the original message, the provider should itself populate the message with the appropriate properties. However, the transport provider cannot set the message's PR_ENTRYID (PidTagEntryId) property.

To save the incoming message in the appropriate MAPI message store after processing, the transport provider calls the IMAPIProp::SaveChanges method. If the transport provider does not have any messages to pass to the MAPI spooler, it can stop the incoming message by returning from the StartMessage call without calling SaveChanges.

All objects that the transport provider opens during a StartMessage call should be released before returning. However, the provider should not release the message object that the MAPI spooler originally passed in the lpMessage parameter.

If StartMessage returns an error, the message in process is released without having changes saved and is lost. In this case, the transport provider should pass the NOTIFY_CRITICAL_ERROR flag with a call to the IMAPISupport::SpoolerNotify method and call the IXPLogon::Poll method to notify the MAPI spooler that it is in a severe error condition.

For more information, see Interacting with the MAPI Spooler.

See also

Reference

IMAPIProp::SaveChanges
IMAPISupport::SpoolerNotify
IMAPISupport::SpoolerYield
IMAPISupport::StatusRecips
IMessage::GetRecipientTable
IXPLogon::Poll
IXPLogon::TransportNotify
IXPLogon : IUnknown


IXPLogon::SubmitMessage

 Copy code hover
[image]

IXPLogon::SubmitMessage
See also Send feedback

Published: July 16, 2012

Indicates that the MAPI spooler has a message for the transport provider to deliver.

C++
HRESULT SubmitMessage(
  ULONG ulFlags,
  LPMESSAGE lpMessage,
  ULONG FAR * lpulMsgRef,
  ULONG FAR * lpulReturnParm
);

Parameters

ulFlags

[in] A bitmask of flags that controls how the message is submitted. The following flag can be set:

BEGIN_DEFERRED

The MAPI spooler is calling a transport provider with a message that was previously deferred. The entry identifier of the message is the same as when it was deferred. The message was deferred by passing its entry identifier back to the MAPI spooler by using the IMAPISupport::SpoolerNotify method with the NOTIFY_SENTDEFERRED flag.

lpMessage

[in] A pointer to a message object (representing the message to deliver) that has read/write permission, which the transport provider uses to access and manipulate that message. This object remains valid until after the transport provider returns from a subsequent call to the IXPLogon::EndMessage method.

lpulMsgRef

[out] A pointer to a variable in which the transport provider returns the reference value it assigned to this message. The MAPI spooler passes this reference value in subsequent calls for this message. The MAPI spooler initializes the value to 0 before returning it to the transport provider.

lpulReturnParm

[out] A pointer to a variable that corresponds to the MAPI_E_WAIT or MAPI_E_NETWORK_ERROR error value returned by SubmitMessage.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BUSY

The transport provider cannot handle the message, because it is performing another operation. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage. The MAPI spooler will try the SubmitMessage call again later.

MAPI_E_CANCEL

Although the transport provider requested that the MAPI spooler resubmit the message on a previous SpoolerNotify call, conditions have since changed, and the message should not be resent. The MAPI spooler will go on to handle something else.

MAPI_E_NETWORK_ERROR

A network error prevented successful completion of the operation. The lpulReturnParm parameter should be set to the number of seconds that will elapse before the MAPI spooler resubmits the message.

MAPI_E_NOT_ME

The transport provider cannot handle this message. The MAPI spooler should try to find another transport provider for it. A provider should use this return value to indicate that no processing occurred and that the MAPI spooler should not call EndMessage.

MAPI_E_WAIT

A temporary problem prevents the transport provider from handling the message. The lpulReturnParm parameter should be set to the number of seconds that will elapse before the MAPI spooler resubmits the message.

Remarks

The MAPI spooler calls the IXPLogon::SubmitMessage method when it has a message for the transport provider to deliver. The message is passed to the transport provider by using the lpMessage parameter.

If the provider is ready to accept the message, it should return a reference value by using the lpulMsgRef parameter, process the passed object, and return the appropriate value (usually S_OK). If the provider is not prepared to handle the transfer, it should return an error value and, optionally, another MAPI return value in lpulReturnParm to indicate how long the MAPI spooler should wait before resubmitting the message.

A transport provider's implementation of this method can do the following:

  • Put the message into an internal queue to wait for transmission, possibly copying the message to local storage, and return.

  • Attempt to perform the actual transmission and return when the transmission completes, either successfully or unsuccessfully.

  • Determine whether to send the message after checking the resource involved. In this case, if the resource is free, the provider can lock the resource, prepare the message, and submit it. If the resource is busy, the provider can prepare the message and defer sending to a later time.

The preferred technique for message transmission depends on the transport provider and the expected number of processes competing for system resources.

During a SubmitMessage call, the transport provider controls the transfer of message data from the message object. However, the transport provider should assign a reference value to the message, to which it returns a pointer in lpulMsgRef, before transferring data. It does so because at any point during the process, the MAPI spooler can call the IXPLogon::TransportNotify method with the NOTIFY_CANCEL_MESSAGE flag set to signal the provider that it should release any open objects and stop message transfer.

The transport provider should not send any nontransmittable properties of the message. When it finds such a property, it should go on to process the next property. The provider should make every effort not to display MAPI_P1 recipient information as part of the transmitted message content; the provider should use this recipient information only for addressing purposes. MAPI_P1 recipients are internally generated recipients that are used for resending messages; they should not be transmitted. Instead, use the other recipients for transmitting recipient information. The purpose of this arrangement is to permit resend recipients to see the exact same recipient table as the original recipients.

During a SubmitMessage call, the MAPI spooler processes methods for objects that are opened during the transfer of the message, and it processes any attachments. This processing can take a long time. Transport providers can call the IMAPISupport::SpoolerYield method for the MAPI spooler frequently during this processing to release CPU time for other system tasks.

All message recipients are visible in the recipient table of the message that the MAPI spooler originally passed. The transport provider should process only those recipients that it can handle — based on entry identifier, address type, or both — and that do not already have their PR_RESPONSIBILITY (PidTagResponsibility) property set to TRUE. If PR_RESPONSIBILITY is already set to TRUE, another transport provider has handled that recipient. When the provider completes sufficient processing of a recipient to determine whether it can handle messages for that recipient, it should set that recipient's PR_RESPONSIBILITY property to TRUE in the passed message. Usually, the provider makes this determination after message delivery is complete.

Typically, the transport provider does not return from a SubmitMessage call until it completes the transfer of message data. If no error is returned, the next call from the MAPI spooler to the provider is a call to the IXPLogon::EndMessage method.

If SubmitMessage returns an error, the MAPI spooler releases the message in process without saving changes. If the transport provider requires message changes to be saved, it must call the IMAPIProp::SaveChanges method on the message before returning.

In case of errors that occur because of transport problems, the MAPI spooler retains the message, but it delays resubmitting the message to the transport provider based on the value returned in lpulReturnParm. The transport provider must fill in that value if its return value from SubmitMessage is MAPI_E_WAIT or MAPI_E_NETWORK_ERROR. If a severe error condition occurs, the transport provider must call the IMAPISupport::SpoolerNotify method with the NOTIFY_CRITICAL_ERROR flag.

See also

Reference

IMAPIProp::SaveChanges
IMAPISupport::SpoolerNotify
IMAPISupport::SpoolerYield
IXPLogon::EndMessage
IXPLogon::TransportNotify
IXPLogon : IUnknown


IXPLogon::TransportLogoff

 Copy code hover
[image]

IXPLogon::TransportLogoff
See also Send feedback

Published: July 16, 2012

Initiates the logoff process.

C++
HRESULT TransportLogoff(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The call succeeded and returned the expected value or values. If anything other than S_OK is returned, the provider is logged off.

Remarks

The MAPI spooler calls the IXPLogon::TransportLogoff method to terminate a transport provider session for a particular user. Before calling TransportLogoff, the MAPI spooler discards any data about supported messaging address types for this session passed in the IXPLogon::AddressTypes method.

Notes to Implementers

The transport provider should be prepared to accept a call to TransportLogoff at any time. If a message is in process, the provider should stop the sending process.

The transport provider should release all resources allocated for its current session. If it has allocated any memory for this session with the MAPIAllocateBuffer function, it should free the memory by using the MAPIFreeBuffer function. Any memory allocated by the transport provider to satisfy calls to the IXPLogon::AddressTypes method can be safely released at this time.

Usually, on completing a TransportLogoff call, a provider should first invalidate its logon object by calling the IMAPISupport::MakeInvalid method and then release its support object. The provider's implementation of TransportLogoff should release the support object last, because when the support object is released, the MAPI spooler can also release the provider object itself.

See also

Reference

IMAPISupport::MakeInvalid
IMAPISupport::SpoolerYield
IXPLogon::AddressTypes
MAPIAllocateBuffer
MAPIFreeBuffer
IXPLogon : IUnknown


IXPLogon::TransportNotify

 Copy code hover
[image]

IXPLogon::TransportNotify
See also Send feedback

Published: July 16, 2012

Signals the occurrence of an event about which the transport provider requested notification.

C++
HRESULT TransportNotify(
  ULONG FAR * lpulFlags,
  LPVOID FAR * lppvData
);

Parameters

lpulFlags

[in, out] A bitmask of flags that signals notification events. The following flags can be set by the MAPI spooler on input and must be returned unchanged on output:

NOTIFY_ABORT_DEFERRED

Notifies the transport provider that a message for which it accepted responsibility is being deferred. Only transport providers that support deferral must support this flag. The lppvData parameter points to the entry identifier of the canceled message. Messages that the MAPI spooler has not processed can still be deferred by calling the IMsgStore::AbortSubmit method.

NOTIFY_BEGIN_INBOUND

The MAPI spooler can now accept inbound messages for this transport provider session. The MAPI spooler regularly calls the IXPLogon::Poll method if the transport provider set the LOGON_SP_POLL flag with the IXPProvider::TransportLogon call at logon. Once the NOTIFY_BEGIN_INBOUND flag is set, the MAPI spooler honors the NOTIFY_NEWMAIL flag passed in the call to the IMAPISupport::SpoolerNotify method. The status table row for the transport provider session should be updated before returning by calling the IMAPISupport::ModifyStatusRow method. The NOTIFY_BEGIN_INBOUND and NOTIFY_END_INBOUND flags are mutually exclusive.

NOTIFY_BEGIN_INBOUND_FLUSH

Signals the transport provider to cycle through inbound messages as quickly as possible. To comply with this notification, the transport provider should set the STATUS_INBOUND_FLUSH flag in the PR_STATUS_CODE (PidTagStatusCode) property of its status table row as soon as it can, by using ModifyStatusRow. An inbound messaging cycle is complete when the provider determines it has downloaded all it can, or when it has received a TransportNotify method call with the NOTIFY_END_INBOUND_FLUSH flag set. Until the end of the inbound messaging cycle, the provider should not call the IMAPISupport::SpoolerYield method or otherwise relinquish cycles to the operating system to speed delivery of incoming messages. This is acceptable because the MAPI spooler typically uses NOTIFY_BEGIN_INBOUND_FLUSH only in response to a user's request, via a client application, to deliver all messages now. At the end of the inbound flush operation, the provider should use SpoolerNotify to clear the STATUS_INBOUND_FLUSH flag in the PR_STATUS_CODE property of its status row.

NOTIFY_BEGIN_OUTBOUND

Outbound operations can now occur for this transport provider session. If there are any messages to be sent for this provider, a call to the IXPLogon::SubmitMessage method follows. The status table row for this session should be updated before returning. The NOTIFY_BEGIN_OUTBOUND and NOTIFY_END_OUTBOUND flags are mutually exclusive.

NOTIFY_BEGIN_OUTBOUND_FLUSH

Works similarly to the NOTIFY_BEGIN_INBOUND_FLUSH flag, but refers to outbound messages. The appropriate status flag is STATUS_OUTBOUND_FLUSH.

NOTIFY_CANCEL_MESSAGE

The MAPI spooler must cancel transfer of the message for which the lppvData parameter points to the 32-bit value from the IXPLogon::SubmitMessage method call. The NOTIFY_CANCEL_MESSAGE flag can be set without the transport provider having returned from the SubmitMessage, IXPLogon::StartMessage, or IXPLogon::EndMessage method call that is associated with the message. The transport provider must return as soon as possible from the entry point that is handling the canceled message. For an inbound message that is currently being processed, the transport provider should save the incoming message wherever it is presently stored and deliver it again at the next convenient time. The message object data already stored for the incoming message is discarded. If the transport provider did not update this 32-bit value at the StartMessage or SubmitMessage time, the value is 0 for outbound messages and 1 for inbound messages.

NOTIFY_END_INBOUND

Inbound operations must cease for this transport provider session. The MAPI spooler ceases to use the Poll method and ignores NOTIFY_NEWMAIL for this session. In-process messages should be completed. The status table row for the transport session should be updated by calling ModifyStatusRow before returning. The NOTIFY_END_INBOUND and NOTIFY_BEGIN_INBOUND flags are mutually exclusive.

NOTIFY_END_INBOUND_FLUSH

Notifies the transport provider to come out of inbound flush mode. The transport provider should not stop downloading, but downloading should be done in the background. The status table row for the transport session should be updated by calling ModifyStatusRow when the transport provider can comply with this notification.

NOTIFY_END_OUTBOUND

Outbound operations must cease for this transport provider session. The MAPI spooler ceases to call SubmitMessage and ignores the SpoolerNotify NOTIFY_READYTOSEND flag. If there is an outbound message currently being sent, it should not be stopped; to stop delivery of a message, use the NOTIFY_CANCEL_MESSAGE flag. The status table row for this session should be updated by calling ModifyStatusRow before returning. The NOTIFY_END_INBOUND and NOTIFY_BEGIN_OUTBOUND flags are mutually exclusive.

NOTIFY_END_OUTBOUND_FLUSH

Works similarly to NOTIFY_END_INBOUND_FLUSH, but refers to outbound messages. The appropriate status flag is STATUS_OUTBOUND_FLUSH.

lppvData

[out] A pointer to a pointer to event-specific data. For more information about what lppvData specifies, see the description for the lpulFlags parameter.

Return value

S_OK

The call succeeded and returned the expected value or values.

Remarks

The MAPI spooler calls the IXPLogon::TransportNotify method to signal the transport provider about events for which notification has been requested. These events include a MAPI spooler request to cancel a message transfer, the beginning or ending of inbound or outbound transport operations, and the beginning or ending of an operation to clear an inbound or outbound message queue.

When the user tries to cancel a message that the transport provider has previously deferred, the MAPI spooler calls TransportNotify, passing in both the NOTIFY_ABORT_DEFERRED and NOTIFY_CANCEL_MESSAGE flags in ulFlags. If the MAPI spooler is logging off and still has messages in the queue, it passes only NOTIFY_ABORT_DEFERRED in ulFlags when it calls TransportNotify.

Notes to Implementers

The provider must synchronize access to its data on this call, because the MAPI spooler can invoke this method from another thread of execution or from a procedure for a different window. This will most likely occur when the MAPI spooler signals the cancellation of a message that the transport provider has started sending.

See also

Reference

IMAPISupport::SpoolerNotify
IMAPISupport::SpoolerYield
IMsgStore::AbortSubmit
IXPLogon::EndMessage
IXPLogon::Poll
IXPLogon::StartMessage
IXPLogon::SubmitMessage
IXPLogon::TransportNotify
IXPProvider::TransportLogon
IXPLogon : IUnknown


IXPLogon::ValidateState

 Copy code hover
[image]

IXPLogon::ValidateState
See also Send feedback

Published: July 16, 2012

Checks the transport provider's external status.

C++
HRESULT ValidateState(
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] A handle to the parent window of any dialog boxes or windows that this method displays.

ulFlags

[in] A bitmask of flags that controls how the status check is performed and the results of the status check. The following flags can be set:

ABORT_XP_HEADER_OPERATION

The user canceled the operation, typically by clicking the Cancel button in a dialog box. The transport provider has the option to continue working on the operation, or it can abort the operation and return MAPI_E_USER_CANCELED.

CONFIG_CHANGED

Validates the state of currently loaded transport providers by causing the MAPI spooler to call their IXPLogon::AddressTypes method. This flag also provides the MAPI spooler an opportunity to correct critical transport-provider failures without forcing client applications to log off and then log on again.

FORCE_XP_CONNECT

The user selected a connect operation. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the connect action occurs without caching.

FORCE_XP_DISCONNECT

The user selected a disconnect operation. When this flag is used with REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE, the disconnect action occurs without caching.

PROCESS_XP_HEADER_CACHE

Entries in the header cache table should be processed, all messages marked with the MSGSTATUS_REMOTE_DOWNLOAD flag should be downloaded, and all messages marked with the MSGSTATUS_REMOTE_DELETE flag should be deleted. Messages that have both MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE set should be moved.

REFRESH_XP_HEADER_CACHE

A new list of message headers should be downloaded, and all message status marking flags should be cleared.

SUPPRESS_UI

Prevents the transport provider from displaying a user interface.

Return value

S_OK

The call succeeded and returned the expected value or values.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped before this operation is attempted.

MAPI_E_NO_SUPPORT

The remote transport provider involved does not support a user interface, and the client application itself should display the dialog box.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The MAPI spooler calls the IXPLogon::ValidateState method to support calls to the IMAPIStatus::ValidateState method for the status object. The transport provider should respond to the IXPLogon::ValidateState call exactly as if the MAPI spooler had opened a status object for the current logon session and then called IMAPIStatus::ValidateState on that object.

To support its implementation of IMAPIStatus::ValidateState, the MAPI spooler calls IXPLogon::ValidateState on all logon objects for all active transport providers that are running in a profile session.

See also

Reference

IMAPIStatus::ValidateState
IXPLogon::AddressTypes
IXPLogon : IUnknown


IXPProvider : IUnknown

 Copy code hover
[image]

IXPProvider : IUnknown
Send feedback

Published: July 16, 2012

Initializes a transport provider object and shuts down the object when it is no longer needed.

Header file: | Mapispi.h
Exposed by: | Transport provider objects
Implemented by: | Transport providers
Called by: | The MAPI spooler
Interface identifier: | IID_IXPProvider
Pointer type: | LPXPROVIDER

Vtable Order

Shutdown | Closes down a transport provider in an orderly fashion.
TransportLogon | Establishes a session in which a client application logs on to a transport provider.


IXPProvider::Shutdown

 Copy code hover
[image]

IXPProvider::Shutdown
See also Send feedback

Published: July 16, 2012

Closes down a transport provider in an orderly fashion.

C++
HRESULT Shutdown (
  ULONG FAR * lpulFlags
);

Parameters

lpulFlags

[in] Reserved; must be zero.

Return value

S_OK

The call succeeded in shutting down the transport provider.

Remarks

The MAPI spooler calls the IXPProvider::Shutdown method just prior to releasing a transport provider object. Before calling Shutdown, MAPI releases all logon objects for a provider.

See also

Reference

XPProviderInit
IXPProvider : IUnknown


IXPProvider::TransportLogon

 Copy code hover
[image]

IXPProvider::TransportLogon
See also Send feedback

Published: July 16, 2012

Establishes a session in which a client application logs on to a transport provider.

C++
HRESULT TransportLogon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG FAR * lpulFlags,
  LPMAPIERROR FAR * lppMAPIError,
  LPXPLOGON FAR * lppXPLogon
);

Parameters

lpMAPISup

[in] Pointer to the transport provider's support object for callback functions within MAPI for this session. This object remains valid until the transport provider releases it.

ulUIParam

[in] Handle to the parent window of any dialog boxes or windows this method displays. The ulUIParam parameter can be non-null, for example when the LOGON_SETUP flag is set in the lpulFlags parameter.

lpszProfileName

[in] Pointer to the profile name of the user. The lpszProfileName parameter is primarily used when a dialog box must be presented.

lpulFlags

[in, out] Bitmask of flags that controls how the logon session is established. The following flags can be set on input by the MAPI spooler:

LOGON_NO_CONNECT

The user account is logging on to this transport provider for purposes other than transmission and reception of messages. The transport provider should not attempt to make any connections to other messaging systems.

LOGON_NO_DIALOG

No dialog box should be displayed even if the currently saved user credentials are invalid or insufficient for logon.

LOGON_NO_INBOUND

The transport provider does not have to initialize for reception of messages and should not accept incoming messages. The MAPI spooler can use the IXPLogon::TransportNotify method later to signal the transport provider to enable incoming message processing.

LOGON_NO_OUTBOUND

The transport provider does not have to initialize for sending messages, as the MAPI spooler does not provide any. If a client application requires a connection to a remote provider during the composition of a message so that it can make IXPLogon::AddressTypes method calls, the transport provider should make the connection. The MAPI spooler can use TransportNotify to signal the transport provider when outgoing operations can begin.

MAPI_UNICODE

The passed-in string for the profile name is in Unicode format. If the MAPI_UNICODE flag is not set, the string is in ANSI format.

The following flags can be set on output by the transport provider:

LOGON_SP_IDLE

Requests that the MAPI spooler frequently call the transport provider's IXPLogon::Idle method for idle-time processing.

LOGON_SP_POLL

Requests that the MAPI spooler frequently call the IXPLogon::Poll method on the returned logon object to check for new messages. If this flag is not set, the MAPI spooler only checks for new messages when the transport provider uses the IMAPISupport::SpoolerNotify method to notify the spooler that there are new messages to process. A transport provider effectively becomes send-only by not setting this flag and by not notifying the MAPI spooler of message receipt.

LOGON_SP_RESOLVE

Requests that the MAPI spooler resolve to full addresses all message addresses for recipients not supported by this transport provider. Therefore that the transport provider can construct a reply path for all recipients.

MAPI_UNICODE

The returned strings in the MAPIERROR structure, if any, are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, that contains version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppXPLogon

[out] Pointer to the pointer to the returned transport provider logon object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to be completed. MAPI calls the provider's message service entry point function.

MAPI_E_UNKNOWN_CPID

The provider cannot support the client's code page.

MAPI_E_UNKNOWN_LCID

The provider cannot support the client's locale information.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The MAPI spooler calls the IXPProvider::TransportLogon method to establish a logon session for a user.

Most transport providers use the IMAPISupport::OpenProfileSection method provided with the support object pointed to by the lpMAPISup parameter for saving and retrieving user identity information, server addresses, and credentials. By using OpenProfileSection, a transport provider can save arbitrary information and associate it with a logon to a particular resource. For example, a provider can use OpenProfileSection to save the account name and password associated with a particular session and any server names or other necessary information that are required to access resources for that session. MAPI hides information associated with a resource from outside access. The profile section made available through lpMAPISup is managed by the MAPI spooler so data related to this user context is separated from data for other contexts.

The transport provider must call the IUnknown::AddRef method on the support object and keep a copy of the pointer to this object as part of the provider logon object.

The profile display name in lpszProfileName is provided so the transport provider can use it in error messages or logon dialog boxes. If the provider retains this name, it must be copied to storage allocated by the provider.

Transport providers that are tightly coupled with other service providers may have to do additional work at logon to establish the good credentials required for operations between companion providers.

Usually, transport providers are opened when the user first logs on to a profile. Because the first logon to a profile therefore generally comes before logon to any message store, the MAPI spooler usually calls TransportLogon with both the LOGON_NO_INBOUND and LOGON_NO_OUTBOUND flags set in lpulFlags. Later, when the appropriate message stores are available in the profile session, the MAPI spooler calls TransportNotify to initiate incoming and outgoing operations for the transport provider.

Passing the LOGON_NO_CONNECT flag in lpulFlags signals offline operation of the transport provider. This flag indicates no external connections should be made; if the transport provider cannot establish a session without an external connection, it should return an error value for the logon.

A transport provider should set the LOGON_SP_IDLE flag in lpulFlags at initialization time if it is designed to use time that the system otherwise spends idle. Such time is often used to handle automatic operations, such as automatic message downloading, timed message downloading, or timed message submission. If this flag is set, the MAPI spooler calls Idle when system idle time occurs to initiate such operations. The MAPI spooler does not call Idle at set intervals; rather, it is called only during true idle time. Therefore, providers should not work on any assumption about how frequently their Idle methods will be called. Providers that support idle-time operations should supply a configuration user interface for it in their provider property sheet.

If the transport provider logon succeeds, the provider should return in the lppXPLogon parameter a pointer to a logon object. The MAPI spooler will use this object for additional provider access. If TransportLogon displays a logon dialog box and the user cancels logon typically by clicking the Cancel button in the dialog box the provider should return MAPI_E_USER_CANCEL.

For most error values returned from TransportLogon, MAPI disables the message services to which the provider belongs. MAPI will not call any providers that belong to that service for the rest of the MAPI session. In contrast, when TransportLogon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. TransportLogon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the service for the rest of the session.

If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider's message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context, to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so that the user can enter configuration information.

If the provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED so that MAPI calls the provider's message service entry point function.

See also

Reference

IXPProvider : IUnknown
IMAPISupport::OpenProfileSection
IMAPISupport::SpoolerNotify
IXPLogon::AddressTypes
IXPLogon::Idle
IXPLogon::Poll
IXPLogon::TransportNotify
MAPIERROR


MAPI Functions, Callbacks, and Macros

 Copy code hover
[image]

MAPI Functions, Callbacks, and Macros
Send feedback

Published: July 16, 2012

The following alphabetic entries contain documentation for the MAPI functions, callbacks, and macros.

ABProviderInit | ACCELERATEABSDI
BuildDisplayTable | CALLERRELEASE
ChangeIdleRoutine | CheckParameters
CheckParms | CloseIMsgSession
CreateIProp | CreateTable
DeinitMapiUtil | DeregisterIdleRoutine
DISMISSMODELESS | EnableIdleRoutine
FBadColumnSet | FBadEntryList
FBadProp | FBadPropTag
FBadRestriction | FBadRglpNameID
FBadRglpszW | FBadRow
FBadRowSet | FBadSortOrderSet
FBinFromHex | FEqualNames
FGetComponentPath | FixMAPI
FNIDLE | FPropCompareProp
FPropContainsProp | FPropExists
FreePadrlist | FreeProws
FtAdcFt | FtAddFt
FtgRegisterIdleRoutine | FtMulDw
FtMulDwDw | FtNegFt
FtSubFt | GetAttribIMsgOnIStg
GetDefCachedMode | GetDefCachedModeDownloadPubFoldFavs
GetInstance | GetTnefStreamCodepage
HexFromBin | HrAddColumns
HrAddColumnsEx | HrAllocAdviseSink
HrCompareABEntryIDsWithExchangeContext | HrComposeEID
HrComposeMsgID | HrCreateOfflineObj
HrDecomposeEID | HrDecomposeMsgID
HrDispatchNotifications | HrDoABDetailsWithExchangeContext
HrDoABDetailsWithProviderUID | HrEntryIDFromSz
HrGetAutoDiscoverXML | HrGetGALFromEmsmdbUID
HrGetOneProp | HrIStorageFromStream
HrOpenABEntryUsingDefaultContext | HrOpenABEntryWithExchangeContext
HrOpenABEntryWithProviderUID | HrOpenABEntryWithProviderUIDSupport
HrOpenABEntryWithResolvedRow | HrOpenABEntryWithSupport
HrOpenOfflineObj | HrQueryAllRows
HrSetOneProp | HrSzFromEntryID
HrThisThreadAdviseSink | HrValidateIPMSubtree
IsBadBoundedStringPtr | LAUNCHWIZARDENTRY
LPFNBUTTON | LPropCompareProp
LpValFindProp | MAPIAdminProfiles
MAPIAllocateBuffer | MAPIAllocateMore
MAPICrashRecovery | MAPIDeInitIdle
MAPIFreeBuffer | MAPIGetDefaultMalloc
MAPIInitialize | MAPIInitIdle
MAPILogonEx | MAPIOFFLINE_AGGREGATEINFO
MAPIOFFLINE_CREATEINFO | MAPIOpenFormMgr
MAPIOpenLocalFormContainer | MAPIReallocateBuffer
MAPIUninitialize | MapStorageSCode
MNLS_CompareStringW | MNLS_IsBadStringPtrW
MNLS_lstrcmpW | MNLS_lstrcpyW
MNLS_lstrlenW | MNLS_MultiByteToWideChar
MNLS_WideCharToMultiByte | MSGCALLRELEASE
MSGSERVICEENTRY | MSProviderInit
NOTIFCALLBACK | NSTServiceEntry
OpenIMsgOnIStg | OpenIMsgSession
OpenStreamOnFile | OpenStreamOnFileW
OpenTnefStream | OpenTnefStreamEx
PpropFindProp | PreprocessMessage
PropCopyMore | RemovePreprocessInfo
RTFSync | ScBinFromHexBounded
ScCopyNotifications | ScCopyProps
ScCountNotifications | ScCountProps
ScCreateConversationIndex | ScDupPropset
ScInitMapiUtil | ScLocalPathFromUNC
ScRelocNotifications | ScRelocProps
ScUNCFromLocalPath | SERVICEWIZARDDLGPROC
SetAttribIMsgOnIStg | SzFindCh
SzFindLastCh | SzFindSz
UFromSz | UlAddRef
UlFromSzHex | UlPropSize
UlRelease | UlValidateParameters
UlValidateParms | ValidateParameters
ValidateParms | WIZARDENTRY
WrapCompressedRTFStream | WrapCompressedRTFStreamEx
WrapStoreEntryID | XPProviderInit


ABProviderInit

 Copy code hover
[image]

ABProviderInit
See also Send feedback

Published: July 16, 2012

Initializes an address book provider for operation.

Header file: | Mapispi.h
Implemented by: | Address book providers
Called by: | MAPI
C++
HRESULT ABProviderInit(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  ULONG ulMAPIVer,
  ULONG FAR * lpulProviderVer,
  LPABPROVIDER FAR * lppABProvider
);

Parameters

hInstance

[in] The instance of the address book provider's dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The address book provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI.DLL uses. For the current version number, see the MAPISPI.H header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this address book provider uses.

lppABProvider

[out] Pointer to a pointer to the initialized address book provider object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function ABProviderInit to initialize an address book provider following a client logon.

Notes to Implementers

An address book provider must implement ABProviderInit as an entry point function in the provider's DLL. The implementation must be based on the ABPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines ABPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes ABProviderInit to follow the CDECL calling convention.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. Because the provider object contains context, ABProviderInit must return a different provider object in lppABProvider for each initialization, even for multiple initializations in the same process.

The address book provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information on writing ABProviderInit, see Implementing an Address Book Provider Entry Point Function. For more information on entry point functions, see Implementing a Service Provider Entry Point Function.

See also

Reference

IABProvider : IUnknown
MSProviderInit
XPProviderInit


ACCELERATEABSDI

 Copy code hover
[image]

ACCELERATEABSDI
Send feedback

Published: July 16, 2012

Defines a callback function to process accelerator keys in a modeless address book dialog box.

Header file: | Mapidefs.h
Defined function implemented by: | MAPI
Defined function called by: | Client applications
C++
BOOL (STDMETHODCALLTYPE ACCELERATEABSDI)(
  ULONG_PTR ulUIParam,
  LPVOID lpvmsg
);

Parameters

ulUIParam

[in] An implementation-specific value used for passing user interface information to a function. In applications running on Microsoft Windows, ulUIParam is the parent window handle for a dialog box and is of type HWND, cast to a ULONG_PTR. A value of zero indicates there is no parent window.

lpvmsg

[in] Pointer to a Windows message.

Return value

A function with the ACCELERATEABSDI prototype returns TRUE if it handles the message.

Remarks

A function based on the ACCELERATEABSDI prototype is used only with a modeless dialog, that is, only if the client application has set the DIALOG_SDI flag in the ulFlags member of the ADRPARM structure.

A modeless dialog shares the client application's Windows message loop, instead of having its own loop. The application, which controls the message loop, does not know what accelerator keys the dialog uses, so it calls an ACCELERATEABSDI based function to test for and act upon accelerator keys such as CTRL+P for printing.

A client's message loop calls the ACCELERATEABSDI based function when the client invokes a modeless address book dialog box with the IAddrBook::Address method. This call is terminated when MAPI calls a function based on the DISMISSMODELESS function prototype.


BuildDisplayTable

 Copy code hover
[image]

BuildDisplayTable
Send feedback

Published: July 16, 2012

Creates a display table from the property page data contained in one or more DTPAGE structures.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Service providers
C++
STDAPI BuildDisplayTable(
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  LPMALLOC lpMalloc,
  HINSTANCE hInstance,
  UINT cPages,
  LPDTPAGE lpPage,
  ULONG ulFlags,
  LPMAPITABLE * lppTable,
  LPTABLEDATA * lppTblData
);

Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpMalloc

Unused; should be set to NULL.

hInstance

[in] An instance of a MAPI object from which BuildDisplayTable retrieves resources.

cPages

[in] Count of DTPAGE structures in the array pointed to by the lpPage parameter.

lpPage

[in] Pointer to an array of DTPAGE structures that contain information about the display table pages to be built.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppTable

[out] Pointer to a pointer to the display table, which exposes the IMAPITable interface.

lppTblData

[in, out] Pointer to a pointer to a table data object exposing the ITableData interface on the table returned in the lppTable parameter. If no table data object is desired, lppTblData should be set to NULL instead of a pointer value.

Return value

None

Remarks

MAPI uses the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

Everything possible is read from the dialog resource, including:

  • The page title that is, the ulbLpszLabel member of the DTBLPAGE structure read from the dialog title in the resource.

  • All control titles that is, the ulbLpszLabel members of other control structures read from the control text in the resource.

BuildDisplayTable overwrites anything passed in the input control structures with information from the dialog resource, which means the caller of BuildDisplayTable cannot dynamically specify page or control titles. Callers who need to do that can have BuildDisplayTable return the table data object in lppTableData and change rows in it; or they can build the display table by hand in a table data object instead.

If lppTableData is not set to NULL, the provider is responsible for freeing the table data object when it is finished with the display table.


CALLERRELEASE

 Copy code hover
[image]

CALLERRELEASE
Send feedback

Published: July 16, 2012

Defines a callback function that can release a table data object when a table view is being released.

Header file: | Mapiutil.h
Defined function implemented by: | Client applications and service providers
Defined function called by: | MAPI
C++
void CALLERRELEASE(
  ULONG_PTR ulCallerData,
  LPTABLEDATA lpTblData,
  LPMAPITABLE lpVue
);

Parameters

ulCallerData

[in] Caller data saved by MAPI with the table view and passed to the CALLERRELEASE based callback function. The data provides context about the table view being released.

lpTblData

[in] Pointer to the ITableData : IUnknown interface for the table data object underlying the table view being released.

lpVue

[in] Pointer to the IMAPITable : IUnknown interface for the table view being released. This is an interface for the table object returned in the lppMAPITable parameter of the ITableData::HrGetView method that created the object to release.

Return value

None

Remarks

A client application or service provider that has populated a table data object can call ITableData::HrGetView to create a read-only, sorted view of the table. The call to HrGetView passes a pointer to a CALLERRELEASE based callback function and also a context to be saved with the table view. When the reference count of the table view returns to zero and the view is being released, the IMAPITable implementation calls the callback function, passing the context in the ulCallerData parameter.

A common use of a CALLERRELEASE based callback function is to release the underlying table data object and not have to keep track of it during subsequent processing.


ChangeIdleRoutine

 Copy code hover
[image]

ChangeIdleRoutine
Send feedback

Published: July 16, 2012

Changes some or all of the characteristics of a FNIDLE based idle routine.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
VOID ChangeIdleRoutine(
  FTG ftg,
  PFNIDLE pfnIdle,
  LPVOID pvIdleParam,
  short priIdle,
  ULONG csecIdle,
  USHORT iroIdle,
  USHORT ircIdle
);

Parameters

ftg

[in] Function tag that identifies the idle routine.

pfnIdle

[in] Pointer to the idle routine.

pvIdleParam

[in] Pointer to a new block of memory that the calling implementation allocates for the idle routine.

priIdle

[in] Value representing a new priority for the idle routine. Possible priorities for implementation-defined routines are greater than or less than zero, but not zero. A value of zero is reserved for a user event such as a mouse click or a WM_PAINT message. Values greater than zero represent priorities for background tasks that have a higher priority than user events and are dispatched as part of the standard Windows message pump loop. Values less than zero represent priorities for idle tasks that only run during message-pump idle time. Examples of priorities are: 1 for foreground submission, 1 for power-edit character insertion, and 3 for downloading new messages.

csecIdle

[in] A new time, in hundredths of a second, to apply to the idle routine. The meaning of the initial time value varies, depending on what is passed in the iroIdle parameter. It can be:

  • The minimum period of user inaction that must elapse before the MAPI idle engine calls the idle routine for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle routine as often as necessary.

  • The minimum interval between calls to the idle routine, if the FIROINTERVAL flag is set in iroIdle.

iroIdle

[in] Bitmask of flags indicating new options for calling the idle routine. Exactly one of the following flags must be set:

FIROINTERVAL

The time specified by the csecIdle parameter is the minimum interval between successive calls to the idle routine.

FIROONCEONLY

Obsolete. Do not use.

FIROPERBLOCK

Obsolete. Do not use.

FIROWAIT

The time specified by the csecIdle parameter is the minimum period of user inaction that must elapse before the MAPI idle engine calls the idle routine for the first time. After this time passes, the idle engine can call the idle routine as often as necessary.

ircIdle

[in] Bitmask of flags used to indicate the changes to be made to the idle routine. The following flags can be set in any combination:

FIRCCSEC

A change to the time associated with the idle routine, that is, a change indicated by the value passed in the csecIdle parameter.

FIRCIRO

A change to the options for the idle routine, that is, a change indicated by the value passed in the iroIdle parameter.

FIRCPFN

A change to the idle routine pointer, that is, a change indicated by the value passed in the pfnIdle parameter.

FIRCPRI

A change to the priority of the idle routine, that is, a change indicated by the value passed in the priIdle parameter.

FIRCPV

A change to the memory block of the idle routine, that is, a change indicated by the value passed in the pvIdleParam parameter.

Return value

None.

Remarks

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.


CheckParameters

 Copy code hover
[image]

CheckParameters
Send feedback

Published: July 16, 2012

Calls an internal function to validate debugging parameters on service provider methods called by MAPI.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT CheckParameters(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

The call succeeded.

Remarks

The CheckParameters macro has been superseded by the CheckParms macro. CheckParms is recommended on all platforms.


CheckParms

 Copy code hover
[image]

CheckParms
Send feedback

Published: July 16, 2012

Calls an internal function to validate debugging parameters on service provider methods called by MAPI.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT CheckParms(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

The call succeeded.

Remarks

In contrast to the ValidateParms and UlValidateParms macros, the CheckParms macro does not perform a full parameter validation. Parameters passed between MAPI and service providers are assumed to be correct, so CheckParms performs a debug validation only.


CloseIMsgSession

 Copy code hover
[image]

CloseIMsgSession
Send feedback

Published: July 16, 2012

Closes a message session and all the messages created within that session.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
VOID CloseIMsgSession(
  LPMSGSESS lpMsgSess
);

Parameters

lpMsgSess

[in] Pointer to the message session object obtained using the OpenIMsgSession function at the start of the message session.

Return value

None.

Remarks

A message session is used by client applications and service providers that want to deal with several related MAPI IMessage objects built on top of underlying OLE IStorage objects. The client or provider uses the OpenIMsgSession and CloseIMsgSession functions to wrap the creation of such messages inside a message session. Once the message session is opened, the client or provider passes a pointer to it in a call to OpenIMsgOnIStg to create a new IMessage-on-IStorage object.

A message session keeps track of all IMessage-on-IStorage objects opened during the duration of the session, in addition to all the attachments and other properties of the messages. When a client or provider calls CloseIMsgSession, it closes all these objects. Calling CloseIMsgSession is the only way to close IMessage-on-IStorage objects.


CreateIProp

 Copy code hover
[image]

CreateIProp
Send feedback

Published: July 16, 2012

Creates a property data object, that is, an IPropData object.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE CreateIProp(
  LPCIID lpInterface,
  ALLOCATEBUFFER FAR * lpAllocateBuffer,
  ALLOCATEMORE FAR * lpAllocateMore,
  FREEBUFFER FAR * lpFreeBuffer,
  LPVOID lpvReserved,
  LPPROPDATA FAR * lppPropData
);

Parameters

lpInterface

[in] Pointer to an interface identifier (IID) for the property data object. The valid interface identifier is IID_IMAPIPropData. Passing NULL in the lpInterface parameter also causes the property data object returned in the lppPropData parameter to be cast to the standard interface for a property data object.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpvReserved

[in] Reserved; must be zero.

lppPropData

[out] Pointer to a pointer to the returned property data object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_INTERFACE_NOT_SUPPORTED

The requested interface is not supported for this object.

Remarks

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, respectively. A client application calling CreateIProp passes in pointers to the MAPI functions just named; a service provider passes the pointers to these functions it received in its initialization call or retrieved with a call to the IMAPISupport::GetMemAllocRoutines method.


CreateTable

 Copy code hover
[image]

CreateTable
See also Send feedback

Published: July 16, 2012

Creates structures and an object handle for an ITableData object which can be used to create table contents.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE CreateTable(
  LPCIID lpInterface,
  ALLOCATEBUFFER FAR * lpAllocateBuffer,
  ALLOCATEMORE FAR * lpAllocateMore,
  FREEBUFFER FAR * lpFreeBuffer,
  LPVOID lpvReserved,
  ULONG ulTableType,
  ULONG ulPropTagIndexColumn,
  LPSPropTagArray lpSPropTagArrayColumns,
  LPTABLEDATA FAR * lppTableData
);

Parameters

lpInterface

[in] Pointer to an interface identifier (IID) for the table data object. The valid interface identifier is IID_IMAPITableData. Passing NULL in the lpInterface parameter also causes the table data object returned in the lppTableData parameter to be cast to the standard interface for a table data object.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpvReserved

[in] Reserved; must be zero.

ulTableType

[in] A table type that is available to a client application or service provider as part of the IMAPITable::GetStatus return data on its table views. Possible values are:

TBLTYPE_DYNAMIC

The table's contents are dynamic and can change as the underlying data changes.

TBLTYPE_KEYSET

The rows in the table are fixed, but the values in these rows are dynamic and can change as the underlying data changes.

TBLTYPE_SNAPSHOT

The table is static and the contents do not change when the underlying data changes.

ulPropTagIndexColumn

[in] Index number of the column for use when changing table data.

lpSPropTagArrayColumns

[in] Pointer to an SPropTagArray structure that contains an array of property tags indicating the properties required in the table for which the object holds data.

lppTableData

[out] Pointer to a pointer to the returned table data object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer functions, respectively. A client application calling CreateTable passes in pointers to the MAPI functions just named; a service provider passes the pointers to these functions that it received in its initialization call or retrieved with a call to the IMAPISupport::GetMemAllocRoutines method.

See also

Reference

IMAPITable : IUnknown


DeinitMapiUtil

 Copy code hover
[image]

DeinitMapiUtil
Send feedback

Published: July 16, 2012

Releases utility functions called explicitly by the ScInitMapiUtil function or implicitly by the MAPIInitialize function.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
VOID DeinitMapiUtil( void );

Parameters

None

Return value

None

Remarks

The DeinitMapiUtil function release functions initialized with ScInitMapiUtil or MAPIInitialize.

When use of the functions called by ScInitMapiUtil is complete, DeinitMapiUtil must be explicitly called to release them. In contrast, MAPIUninitialize implicitly calls DeinitMapiUtil.


DeregisterIdleRoutine

 Copy code hover
[image]

DeregisterIdleRoutine
Send feedback

Published: July 16, 2012

Removes a FNIDLE based idle routine from the MAPI system.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
VOID DeregisterIdleRoutine(
  FTG ftg
);

Parameters

ftg

[in] Function tag that identifies the idle routine to be removed.

Return value

None.

Remarks

Any task in a client application or service provider can deregister any idle routine for which it has a valid ftg parameter. In particular, an idle routine can deregister itself.

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.

After the idle routine is deregistered, the idle engine does not call it again. Any implementation that calls DeregisterIdleRoutine must deallocate any memory blocks to which it passed pointers for the idle engine to use in its original call to the FtgRegisterIdleRoutine function.


DISMISSMODELESS

 Copy code hover
[image]

DISMISSMODELESS
See also Send feedback

Published: July 16, 2012

Defines a callback function that MAPI calls when it has dismissed a modeless address book dialog box.

Header file: | Mapidefs.h
Defined function implemented by: | Client applications
Defined function called by: | MAPI
C++
void (STDMETHODCALLTYPE DISMISSMODELESS)(
  ULONG_PTR ulUIParam,
  LPVOID lpvContext
);

Parameters

ulUIParam

[in] An implementation-specific value typically used for passing user interface information to a function. For example, in Microsoft Windows this parameter is the parent window handle for the dialog box and is of type HWND, cast to a ULONG_PTR. A value of zero indicates there is no parent window.

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application. Typically, for C++ code, lpvContext is a pointer to the address of a C++ object instance.

Return value

None

Remarks

When the client application invokes a modeless address book dialog box, it includes in its Windows message loop a call to a function based on the ACCELERATEABSDI prototype, which checks for and processes accelerator keys. When the dialog box is closed, MAPI calls the DISMISSMODELESS based function so that the client application will stop calling the ACCELERATEABSDI based function.

See also

Reference

ADRPARM


EnableIdleRoutine

 Copy code hover
[image]

EnableIdleRoutine
Send feedback

Published: July 16, 2012

Enables or disables a FNIDLE based idle routine.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
VOID EnableIdleRoutine(
  FTG ftg,
  BOOL fEnable
);

Parameters

ftg

[in] Function tag that identifies the idle routine to be enabled or disabled.

fEnable

[in] Contains TRUE if the idle engine should enable the idle routine, or FALSE if it should disable it.

Return value

None.

Remarks

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.


FBadColumnSet

 Copy code hover
[image]

FBadColumnSet
Send feedback

Published: July 16, 2012

Tests the validity of a table column set for use by a service provider in a subsequent call to the IMAPITable::SetColumns method.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadColumnSet(
  LPSPropTagArray lpptaCols
);

Parameters

lpptaCols

[in] Pointer to an SPropTagArray structure that contains an array of property tags defining the table columns to validate.

Return value

TRUE

The specified column set is invalid.

FALSE

The specified column set is valid.

Remarks

The FBadColumnSet function treats columns of type PT_ERROR as invalid and columns of type PT_NULL as valid.


FBadEntryList

 Copy code hover
[image]

FBadEntryList
Send feedback

Published: July 16, 2012

Validates a list of MAPI entry identifiers.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
BOOL FBadEntryList(
  LPENTRYLIST lpEntryList
);

Parameters

lpEntryList

[in] Pointer to an ENTRYLIST structure that contains an array of entry identifiers to be validated.

Return value

TRUE

One or more of the listed entry identifiers are invalid.

FALSE

All of the listed entry identifiers are valid.

Remarks

The FBadEntryList function determines if the entry identifier list has been correctly generated. An example of an invalid identifier is one for which memory has been incorrectly allocated or an identifier of an incorrect size.


FBadProp

 Copy code hover
[image]

FBadProp
See also Send feedback

Published: July 16, 2012

Validates a specified property.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadProp(
  LPSPropValue lpprop
);

Parameters

lpprop

[in] An SPropValue structure defining the property to be validated.

Return value

TRUE

The specified property is invalid.

FALSE

The specified property is valid.

Remarks

A service provider can call the FBadProp function for several reasons, for example to prepare for a call to the IMAPIProp::SetProps method setting a property. FBadProp validates the specified property depending on the property type. For example, if the property is Boolean, FBadProp make sures that its value is either TRUE or FALSE. If the property is binary, FBadProp checks its pointer and size and makes sure that it is allocated correctly.

See also

Reference

FBadPropTag


FBadPropTag

 Copy code hover
[image]

FBadPropTag
See also Send feedback

Published: July 16, 2012

Validates a specified property tag.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadPropTag(
  ULONG ulPropTag
);

Parameters

ulPropTag

[in] The property tag to be validated.

Return value

TRUE

The specified property tag is not a valid MAPI property tag.

FALSE

The specified property tag is a valid MAPI property tag.

Remarks

The FBadPropTag function validates the specified property tag based on MAPI definitions. It make sures that the property type is one of the types defined by MAPI and that the property identifier is defined to be of that type.

See also

Reference

FBadProp


FBadRestriction

 Copy code hover
[image]

FBadRestriction
Send feedback

Published: July 16, 2012

Validates a restriction used to limit a table view.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadRestriction(
  LPSRestriction lpres
);

Parameters

lpres

[in] An SRestriction structure defining the restriction to be validated.

Return value

TRUE

The specified restriction, or one or more of its subrestrictions, is invalid.

FALSE

The specified restriction and all its subrestrictions are valid.

Remarks

Once a restriction is validated, it can be passed in calls to the IMAPITable::Restrict method to restrict the table to certain rows, to the IMAPITable::FindRow method to locate a table row, and to methods of the IMAPIContainer interface to perform a restriction on a container object.


FBadRglpNameID

 Copy code hover
[image]

FBadRglpNameID
Send feedback

Published: July 16, 2012

Validates an array of structures that describe named properties and verifies their allocation.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
BOOL FBadRglpNameID(
  LPMAPINAMEID FAR * lppNameId,
  ULONG cNames
);

Parameters

lppNameId

[in] Pointer to an array of MAPINAMEID structures describing the named properties.

cNames

[in] Count of named property structures in the array pointed to by the lppNameId parameter.

Return value

TRUE

One or more of the specified property name structures is invalid.

FALSE

The specified property name structures are all valid.

Remarks

The FBadRglpNameID function can be used when setting up for a call to IMAPIProp::GetIDsFromNames or IMAPIProp::GetNamesFromIDs.


FBadRglpszW

 Copy code hover
[image]

FBadRglpszW
Send feedback

Published: July 16, 2012

Validates all strings in an array of Unicode strings.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
BOOL FBadRglpszW(
  LPWSTR FAR * lppszW,
  ULONG cStrings
);

Parameters

lppszW

[in] Pointer to an array of null-terminated Unicode strings.

cStrings

[in] Count of strings in the array pointed to by the lppszW parameter.

Return value

TRUE

One or more of the strings in the specified array are invalid.

FALSE

The strings in the specified array are valid.


FBadRow

 Copy code hover
[image]

FBadRow
See also Send feedback

Published: July 16, 2012

Validates a row in a table.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadRow(
  LPSRow lprow
);

Parameters

lprow

[in] Pointer to an SRow structure identifying the row to be validated.

Return value

TRUE

The specified row is invalid.

FALSE

The specified row is valid.

See also

Reference

FBadRowSet


FBadRowSet

 Copy code hover
[image]

FBadRowSet
See also Send feedback

Published: July 16, 2012

Validates all table rows included in a set of table rows.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
BOOL FBadRowSet(
  LPSRowSet lpRowSet
);

Parameters

lpRowSet

[in] Pointer to an SRowSet structure identifying the row set to be validated. If the pointer is NULL, the structure is invalid.

Return value

TRUE

A row of the specified row set is invalid, or the row set itself is invalid.

FALSE

The rows of the specified row set and the row set itself are all valid.

See also

Reference

FBadRow


FBadSortOrderSet

 Copy code hover
[image]

FBadSortOrderSet
Send feedback

Published: July 16, 2012

Validates a sort order set by verifying its memory allocation.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
ULONG FBadSortOrderSet(
  LPSSortOrderSet lpsos
);

Parameters

lpsos

[in] Pointer to an SSortOrderSet structure identifying the sort order set to be validated.

Return value

TRUE

The specified sort order set is invalid.

FALSE

The specified sort order set is valid.

Remarks

The FBadSortOrderSet function can be used to prepare for a call to a sort method such as the IMAPITable::SortTable method.


FBinFromHex

 Copy code hover
[image]

FBinFromHex
See also Send feedback

Published: July 16, 2012

Converts a string representation of a hexadecimal number to binary data.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
BOOL FBinFromHex(
  LPSTR sz,
  LPBYTE pb
);

Parameters

sz

[in] Pointer to the null-terminated ASCII string to be converted. It is not a Unicode string. Valid characters include the hexadecimal characters zero through nine and both uppercase and lowercase characters A through F.

pb

[out] Pointer to the returned binary number.

Return value

TRUE

The string was successfully converted into a binary number.

FALSE

The input string contains invalid ASCII hexadecimal characters.

See also

Reference

ScBinFromHexBounded


FEqualNames

 Copy code hover
[image]

FEqualNames
Send feedback

Published: July 16, 2012

Determines whether two MAPI named properties are the same.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
BOOL FEqualNames(
  LPMAPINAMEID lpName1,
  LPMAPINAMEID lpName2
);

Parameters

lpName1

[in] Pointer to a MAPINAMEID structure describing the first named property.

lpName2

[in] Pointer to a MAPINAMEID structure describing the second named property.

Return value

TRUE

The two property names are equal.

FALSE

The two property names are not equal.

Remarks

The FEqualNames function is useful because the MAPINAMEID structure contains a GUID and can represent the property name itself in more than one way. This means the two structures cannot be compared by simple binary methods.

The testing process is case-sensitive for the property name strings.


FGetComponentPath

 Copy code hover
[image]

FGetComponentPath
See also Send feedback

Published: July 16, 2012

Returns the path to the private Mapi32.dll.

C++
BOOL FGetComponentPath(
  LPCSTR szComponent,
  LPSTR szQualifier,
  LPSTR szDllPath,
  DWORD cchBufferSize,
  BOOL fInstall
);

Parameters

szComponent

[in] The MSIComponentID reg key described in Mapi32.dll Stub Registry Settings.

szQualifier

[in] The MSIApplicationLCID or MSIOfficeLCID subkey described in How to: Choose a Specific Version of MAPI to Load. Callers can pass null if there is no qualifier.

szDllPath

[in] The path to the private Mapi32.dll, which has full MAPI functionality (the same exports as the Mapi32.dll).

cchBufferSize

[in] The size of szDllPath, in characters.

fInstall

[in] Tells MAPI to install the private Mapi32.dll component if it is absent.

Return value

true

The path was found.

false

The path was not found.

Remarks

Use the FGetComponentPath function when you need to get the path to the private Mapi32.dll.

See also

Concepts

How to: Choose a Specific Version of MAPI to Load

Other resources

Mapi32.dll Stub Registry Settings


FixMAPI

 Copy code hover
[image]

FixMAPI
See also Send feedback

Published: July 16, 2012

Makes a backup copy of the current copy of mapi32.dll on the client computer, and restores mapi32.dll with the MAPI stub library, mapistub.dll.

Quick Info

Exported by: | mapistub.dll
Called by: | Client
Implemented by: | Windows
Copy code Copy code
DWORD STDAPICALLTYPE FixMAPI(void);

Return Values

If the function succeeds, the return value is a non-zero value.

If the function fails, the return value is zero. To get extended error information, call the Microsoft Windows Software Development Kit (SDK) function, GetLastError.

Remarks

FixMAPI does not replace the current mapi32.dll file if the file is marked as read-only.

FixMAPI does not replace the current mapi32.dll if Microsoft Exchange Server is installed on the computer.

When FixMAPI makes a backup copy of the current copy of mapi32.dll on the computer, it assigns the backup copy a name different from "mapi32.dll". It then directs subsequent calls intended for that assembly to the backup copy.

See also

Other resources

KB 256946: You receive a program conflict error message when you start Outlook 2000
KB 228457: Description of the Fixmapi.exe Tool Included with Internet Explorer 5


FNIDLE

 Copy code hover
[image]

FNIDLE
Send feedback

Published: July 16, 2012

Defines an idle routine that the MAPI idle engine calls periodically according to priority.

Header file: | Mapiutil.h
Defined function implemented by: | Client applications and service providers
Defined function called by: | MAPI
Corresponding pointer type: | PFNIDLE
C++
BOOL (STDAPICALLTYPE FNIDLE)(
  LPVOID lpvContext
);

Parameters

lpvContext

[in] Pointer to a block of memory that MAPI passes to the idle routine each time it calls it. This pointer is passed to the MAPI idle engine in the pvIdleParam parameter by FtgRegisterIdleRoutine. The data in the memory block can provide context for the call to the idle routine, such as which object to operate on, or the current state of a lengthy operation.

Return value

FALSE

An idle routine with the FNIDLE prototype should always return FALSE.

Remarks

The specific functionality of the idle routine is determined by the implementing client application or service provider.

The client or provider must limit the execution time of each state of an idle routine. Every state should perform a minimum amount of processing, update the current state in the context data pointed to by lpvContext, and return to the MAPI idle engine.

The client or provider must call the MAPI function MAPIInitIdle before it can register its own idle routine with a call to the FtgRegisterIdleRoutine function.

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.


FPropCompareProp

 Copy code hover
[image]

FPropCompareProp
Send feedback

Published: July 16, 2012

Compares two property values using a specified relational operator.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
BOOL FPropCompareProp(
  LPSPropValue lpSPropValue1,
  ULONG ulRelOp,
  LPSPropValue lpSPropValue2
);

Parameters

lpSPropValue1

[in] Pointer to an SPropValue structure defining the first property value for comparison.

ulRelOp

[in] The relational operator to use in the comparison. For allowable values, see the SComparePropsRestriction structure.

lpSPropValue2

[in] Pointer to an SPropValue structure defining the second property value for comparison.

Return value

TRUE

The property values satisfy the specified relation.

FALSE

The property values do not satisfy the specified relation.

Remarks

The comparison method depends on the property types specified in the SPropValue property definitions. The FPropCompareProp and FPropContainsProp functions can be used to prepare restrictions for generating a table.

The order of comparison is lpSPropValue1, ulRelOp, lpSPropValue2. If the property types of the property values to be compared do not match, the FPropCompareProp function returns FALSE.


FPropContainsProp

 Copy code hover
[image]

FPropContainsProp
Send feedback

Published: July 16, 2012

Compares two property values, generally strings or binary arrays, to see if one contains the other.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
BOOL FPropContainsProp(
  LPSPropValue lpSPropValueDst,
  LPSPropValue lpSPropValueSrc,
  ULONG ulFuzzyLevel
);

Parameters

lpSPropValueDst

[in] Pointer to an SPropValue structure defining the property value that might contain the search string pointed to by the lpSPropValueSrc parameter.

lpSPropValueSrc

[in] Pointer to an SPropValue structure defining the search string that FPropContainsProp is seeking in the property value pointed to by the lpSPropValueDst parameter.

ulFuzzyLevel

[in] Option settings defining the level of preciseness to use in the comparison. The lower 16 bits apply to properties of type PT_BINARY and PT_STRING8. They must be set to exactly one of the following values:

- FL_FULLSTRING

The lpSPropValueSrc search string must be equal to the property value identified by lpSPropValueDst.

- FL_PREFIX

The lpSPropValueSrc search string must appear at the beginning of the property value identified by lpSPropValueDst. The two values should be compared only up to the length of the search string indicated by lpSPropValueSrc.

- FL_SUBSTRING

The lpSPropValueSrc search string must be contained anywhere in the property value identified by lpSPropValueDst.

The upper 16 bits apply only to properties of type PT_STRING8. They can be set to the following values in any combination:

- FL_IGNORECASE

The comparison should be made without considering case sensitivity.

- FL_IGNORENONSPACE

The comparison should ignore Unicode-defined nonspacing characters such as diacritical marks.

- FL_LOOSE

The comparison should indicate a match whenever possible, ignoring case sensitivity and nonspacing characters.

Return value

TRUE

The parameters are all valid and the lpSPropValueSrc search string is contained as specified in the lpSPropValueDst property value.

FALSE

The property values being compared are not of type PT_STRING8 or PT_BINARY, the property values are of different types, or the lpSPropValueSrc search string is not contained as specified in the lpSPropValueDst property value.

Remarks

The comparison method depends on the property types specified in the SPropValue property definitions and the fuzzy level heuristic provided in the ulFuzzyLevel parameter. The FPropCompareProp and FPropContainsProp functions can be used to prepare restrictions for generating a table.

The upper 16 bits of ulFuzzyLevel are ignored for property type PT_BINARY. If the settings in ulFuzzyLevel are missing or invalid, a full-string exact match is performed. For more information about property containment, see the SContentRestriction structure.


FPropExists

 Copy code hover
[image]

FPropExists
Send feedback

Published: July 16, 2012

Searches for a given property tag in an IMAPIProp interface or an interface derived from IMAPIProp, such as IMessage or IMAPIFolder.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
BOOL FPropExists(
  LPMAPIPROP pobj,
  ULONG ulPropTag
);

Parameters

pobj

[in] Pointer to the IMAPIProp interface or interface derived from IMAPIProp within which to search for the property tag.

ulPropTag

[in] Property tag for which to search.

Return value

TRUE

A match for the given property tag was found.

FALSE

A match for the given property tag was not found.

Remarks

If the property tag in the ulPropTag parameter has type PT_UNSPECIFIED, the FPropExists function looks for a match based only on the property identifier. Otherwise, the match is for the entire property tag, including the type.


FreePadrlist

 Copy code hover
[image]

FreePadrlist
See also Send feedback

Published: July 16, 2012

Destroys an ADRLIST structure and frees associated memory, including memory allocated for all member arrays and structures.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
void FreePadrlist(
  LPADRLIST padrlist
);

Parameters

padrlist

[in] Pointer to the ADRLIST structure to be destroyed.

Return value

None.

Notes to Callers

As part of its implementation of FreePadrlist, MAPI calls the MAPIFreeBuffer function to free every entry in the ADRLIST structure before freeing the complete structure. Therefore all such entries must have followed the allocation rules for the ADRLIST structure, using an individual MAPIAllocateBuffer call for each member array and structure.

For more information about allocating memory for ADRLIST and SRowSet structures, see Managing Memory for ADRLIST and SRowSet Structures.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIABFunctions.cpp | AddOneOffAddress | MFCMAPI uses the FreePadrlist method to free an ADRLIST structure that was built to add a one-off address to a message.

See also

Concepts

MFCMAPI as a Code Sample


FreeProws

 Copy code hover
[image]

FreeProws
See also Send feedback

Published: July 16, 2012

Destroys an SRowSet structure and frees associated memory, including memory allocated for all member arrays and structures.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
void FreeProws(
  LPSRowSet prows
);

Parameters

prows

[in] Pointer to the SRowSet structure to be destroyed.

Return value

None.

Notes to Callers

As part of its implementation of FreeProws, MAPI calls the MAPIFreeBuffer function to free every entry in the SRowSet structure before freeing the complete structure. Therefore all such entries must have followed the allocation rules for the SRowSet structure, using an individual MAPIAllocateBuffer call for each member array and structure.

For more information about allocating memory for ADRLIST and SRowSet structures, see Managing Memory for ADRLIST and SRowSet Structures.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | DwThreadFuncLoadTable | MFCMAPI uses the FreeProws method to free an SRowSet structure containing rows of the table being processed.

See also

Concepts

MFCMAPI as a Code Sample


FtAdcFt

 Copy code hover
[image]

FtAdcFt
See also Send feedback

Published: July 16, 2012

Adds one unsigned 64-bit integer to another, optionally using a carry flag.

Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtAdcFt(
  FILETIME ft1,
  FILETIME ft2,
  WORD FAR *pwCarry
);

Parameters

ft1

[in] A FILETIME structure that contains the first unsigned 64-bit integer to be added.

ft2

[in] A FILETIME structure that contains the second unsigned 64-bit integer to be added.

pwCarry

[in, out, optional] On input, a pointer to the incoming carry flag. On output, a pointer to the carry result for the addition. This parameter can be NULL if the carry result is not required.

Return value

The FtAdcFt function returns a FILETIME structure that contains the sum of the two integers. The two input parameters remain unchanged. If pwCarry is non-NULL, it contains the carry result for the sum, either 0 or 1.

Remarks

The FtAdcFt function is identical to FtAddFt when pwCarry is NULL. If pwCarry is not NULL and points to 0, FtAdcFt returns the same FILETIME value that FtAddFt returns.

See also

Reference

FtAddFt


FtAddFt

 Copy code hover
[image]

FtAddFt
Send feedback

Published: July 16, 2012

Adds one unsigned 64-bit integer to another.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtAddFt(
  FILETIME Addend1,
  FILETIME Addend2
);

Parameters

Addend1

[in] A FILETIME structure that contains the first unsigned 64-bit integer to be added.

Addend2

[in] A FILETIME structure that contains the second unsigned 64-bit integer to be added.

Return value

The FtAddFt function returns a FILETIME structure that contains the sum of the two integers. The two input parameters remain unchanged.


FtgRegisterIdleRoutine

 Copy code hover
[image]

FtgRegisterIdleRoutine
Send feedback

Published: July 16, 2012

Adds a FNIDLE function-based idle routine to the MAPI system.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FTG FtgRegisterIdleRoutine(
  PFNIDLE pfnIdle,
  LPVOID pvIdleParam,
  short priIdle,
  ULONG csecIdle,
  USHORT iroIdle
);

Parameters

pfnIdle

[in] A pointer to the idle routine.

pvIdleParam

[in] A pointer to a block of memory that the idle engine should pass as a parameter to the idle routine when it calls it.

priIdle

[in] The initial priority for the idle routine. Possible priorities for implementation-defined routines are greater than or less than zero, but not zero. The zero priority is reserved for a user event such as a mouse click or a WM_PAINT message. Priorities greater than zero represent background tasks that have a higher priority than user events and are dispatched as part of the standard Windows message pump loop. Priorities less than zero represent idle tasks that only run during message pump idle time. Examples of priorities are as follows: 1 for foreground submission, 2 for power-edit character insertion, and 3 for downloading new messages.

csecIdle

[in] The initial time value, in hundredths of a second, to be used in specifying idle routine parameters. The meaning of the initial time value varies, depending on what is passed in the iroIdle parameter. The meaning can be one of the following:

  • The minimum period of user inaction that must elapse before the MAPI idle engine calls the idle routine for the first time, if the FIROWAIT flag is set in iroIdle. After this time passes, the idle engine can call the idle routine as often as necessary.

  • The minimum interval between calls to the idle routine, if the FIROINTERVAL flag is set in iroIdle.

iroIdle

[in] The bitmask of flags used to set initial options for the idle routine. The following flags can be set:

FIRONOADJUSTMENT

Use this flag to specify that the idle routine timer should not be adjusted for sleep or resume. The default behavior without this flag is that sleep time is excluded when calculating the elapsed time. If FIRONOADJUSTMENT is passed then the sleep time is included when calculating elapsed time.

FIRODISABLED

The idle routine should be disabled when registered. The default action is to enable the idle routine when FtgRegisterIdleRoutine registers it.

FIROINTERVAL

The time specified by the csecIdle parameter is the minimum interval between successive calls to the idle routine.

FIROONCEONLY

Obsolete. Do not use.

FIROPERBLOCK

Obsolete. Do not use.

FIROWAIT

The time specified by the csecIdle parameter is the minimum period of user inaction that must elapse before the MAPI idle engine calls the idle routine for the first time. After this time passes, the idle engine can call the idle routine as often as necessary.

Return value

The FtgRegisterIdleRoutine function returns a function tag identifying the idle routine that was added to the MAPI system. If FtgRegisterIdleRoutine cannot register the idle routine for the client application or service provider, for example because of memory problems, it returns NULL.

Remarks

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype.

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

ChangeIdleRoutine, DeregisterIdleRoutine, and EnableIdleRoutine take as an input parameter the function tag returned by FtgRegisterIdleRoutine.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.

The following is an example of using the FIRONOADJUSTMENT flag in the iroIdle parameter.

  1. Register an idle routine with a 5 minute delay.

  2. Hibernate/Sleep the computer after 1 minute (4 minutes left on the timer).

  3. Resume the computer 10 minutes later.

The default behavior, without FIRONOADJUSTMENT, is that you still have to wait 4 more minutes for your routine to run. That is, your timer was adjusted to allow for how long the computer was asleep. However, if you pass FIRONOADJUSTMENT your idle routine will run immediately because more than 5 minutes of real time have elapsed.


FtMulDw

 Copy code hover
[image]

FtMulDw
Send feedback

Published: July 16, 2012

Multiplies an unsigned 64-bit integer by an unsigned 32-bit integer.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtMulDw(
  DWORD Multiplier,
  FILETIME Multiplicand
);

Parameters

Multiplier

[in] A double word that contains the unsigned 32-bit integer multiplier.

Multiplicand

[in] A FILETIME structure that contains the unsigned 64-bit integer to be multiplied by the value in the Multiplier parameter.

Return value

The FtMulDw function returns a FILETIME structure that contains the product of the two integers. The two input parameters remain unchanged.


FtMulDwDw

 Copy code hover
[image]

FtMulDwDw
Send feedback

Published: July 16, 2012

Multiplies one unsigned 32-bit integer by another.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtMulDwDw(
  DWORD Multiplicand,
  DWORD Multiplier
);

Parameters

Multiplicand

[in] A double word that contains the unsigned 32-bit integer to be multiplied by the value in the Multiplier parameter.

Multiplier

[in] A double word that contains the unsigned 32-bit integer multiplier.

Return value

The FtMulDwDw function returns a FILETIME structure that contains the product of the two integers. The two input parameters remain unchanged.


FtNegFt

 Copy code hover
[image]

FtNegFt
Send feedback

Published: July 16, 2012

Computes the two's complement of an unsigned 64-bit integer.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtNegFt(
  FILETIME ft
);

Parameters

ft

[in] A FILETIME structure that contains the unsigned 64-bit integer for which to compute the two's complement.

Return value

The FtNegFt function returns a FILETIME structure that contains the two's complement of the integer. The input parameter remains unchanged.


FtSubFt

 Copy code hover
[image]

FtSubFt
Send feedback

Published: July 16, 2012

Subtracts one unsigned 64-bit integer from another.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
FILETIME FtSubFt(
  FILETIME Minuend,
  FILETIME Subtrahend
);

Parameters

Minuend

[in] A FILETIME structure that contains the unsigned 64-bit integer from which the value in the Subtrahend parameter is to be subtracted.

Subtrahend

[in] A FILETIME structure that contains the unsigned 64-bit integer that is subtracted from the value indicated by the Minuend parameter.

Return value

The FtSubFt function returns a FILETIME structure that contains the result of the subtraction. The two input parameters remain unchanged.


GetAttribIMsgOnIStg

 Copy code hover
[image]

GetAttribIMsgOnIStg
Send feedback

Published: July 16, 2012

Retrieves attributes of properties on an IMessage object supplied by the OpenIMsgOnIStg function.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and message store providers
C++
HRESULT GetAttribIMsgOnIStg(
  LPVOID lpObject,
  LPSPropTagArray lpPropTagArray,
  LPSPropAttrArray FAR * lppPropAttrArray
);

Parameters

lpObject

[in] Pointer to an IMessage object obtained from the OpenIMsgOnIStg function.

lpPropTagArray

[in] Pointer to an SPropTagArray structure that contains an array of property tags indicating the properties for which attributes are to be retrieved.

lppPropAttrArray

[out] Pointer to a pointer to the returned SPropAttrArray structure that contains the retrieved property attributes.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed and were returned with a property type of PT_ERROR.

Remarks

Property attributes can only be accessed on property objects, that is, objects implementing the IMAPIProp : IUnknown interface. To make MAPI properties available on an OLE structured storage object, OpenIMsgOnIStg builds an IMessage : IMAPIProp object on top of the OLE IStorage object. The property attributes on such objects can be set or altered with SetAttribIMsgOnIStg and retrieved with GetAttribIMsgOnIStg.

Note Note

GetAttribIMsgOnIStg and SetAttribIMsgOnIStg do not operate on all IMessage objects. They are only valid for IMessage-on-IStorage objects returned by OpenIMsgOnIStg.

The number and positions of the attributes in the lppPropAttrArray parameter correspond to the number and positions of the property tags in the lpPropTagArray parameter.


GetDefCachedMode

 Copy code hover
[image]

GetDefCachedMode
See also Send feedback

Published: July 16, 2012

Indicates whether Cached Exchange Mode for the private Exchange store is enabled, and whether this is enforced by policy.

Quick Info

Exported by: | msmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
BOOL GetDefCachedMode(BOOL *pfPolicy);

Parameters

pfPolicy

[out] true if the return value is enforced by policy, false if it is not.

Return Values

true

  • Caching is enabled.

false

  • Caching is disabled.

See also

Concepts

GetDefCachedModeDownloadPubFoldFavs


GetDefCachedModeDownloadPubFoldFavs

 Copy code hover
[image]

GetDefCachedModeDownloadPubFoldFavs
See also Send feedback

Published: July 16, 2012

Indicates whether Cached Exchange Mode for the Public Folder Favorites folder is enabled, and whether this is enforced by policy.

Quick Info

Exported by: | msmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
BOOL GetDefCachedModeDownloadPubFoldFavs(BOOL *pfPolicy);

Parameters

pfPolicy

[out] true if the return value is enforced by policy, false if it is not.

Return Values

true

  • Caching is enabled.

false

  • Caching is disabled.

See also

Concepts

GetDefCachedMode


GetInstance

 Copy code hover
[image]

GetInstance
Send feedback

Published: July 16, 2012

Copies one value within a multivalued property to a single-valued property of the same type.

Header file: | MAPIUTIL.H
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
VOID GetInstance(
  LPSPropValue pvalMv,
  LPSPropValue pvalSv,
  ULONG uliInst
);

Parameters

pvalMv

[in] Pointer to an SPropValue structure defining a multivalued property.

pvalSv

[in] Pointer to a single-valued property to receive data.

uliInst

[in] The instance number, that is, the array element, of the value being copied from the structure indicated by the pvalMv parameter.

Return value

None.

Remarks

If the value copied is too large for the allocated memory, the GetInstance function only copies pointers instead of allocating new memory.


GetTnefStreamCodepage

 Copy code hover
[image]

GetTnefStreamCodepage
See also Send feedback

Published: July 16, 2012

Determines the code page for a Transport-Neutral Encapsulation Format (TNEF) stream.

Header file: | tnef.h
Implemented by: | MAPI
Called by: | Client applications and service providers.
C++
HRESULT GetTnefStreamCodepage(
  LPSTREAM lpStream,
  ULONG FAR * lpulCodepage,
  ULONG FAR * lpulSubCodepage
);

Parameters

lpStream

[in] Pointer to a storage stream object OLE IStream interface providing a source for a TNEF stream message.

lpulCodepage

[out] Pointer to the code page of the stream.

lpulSubCodepage

[out] Pointer to the subcode page of the stream.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_ENOUGH_DISK

There was an error reading an attribute in the TNEF stream.

MAPI_E_CORRUPT_DATA

Either the stream was not a TNEF stream or there was an error reading the attOemCodepage attribute.

Remarks

Use the GetTnefStreamCodepage function to read the attOemCodepage attribute of the TNEF stream to determine the code page and subcode page. If attOemCodepage is not found, GetTnefStreamCodepage returns a code page of 437 and a subcode page of 0.

See also

Other resources

attOemCodepage


HexFromBin

 Copy code hover
[image]

HexFromBin
Send feedback

Published: July 16, 2012

Converts a binary number into a string representation of a hexadecimal number.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
void HexFromBin(
  LPBYTE pb,
  int cb,
  LPSTR sz
);

Parameters

pb

[in] Pointer to the binary data to be converted.

cb

[in] Size, in bytes, of the binary data pointed to by the pb parameter.

sz

[out] Pointer to a null-terminated ASCII string representing the binary data in hexadecimal digits.

Return value

None.

Remarks

The HexFromBin function takes a pointer to a unit of binary data whose size is indicated by the cb parameter. It returns in the sz string, within (2*cb)+1 bytes of memory, a representation of this binary information in hexadecimal numbers. If the byte value is decimal 10, for example, the hexadecimal string will be 0A, so one byte converts to two bytes in the string.


HrAddColumns

 Copy code hover
[image]

HrAddColumns
See also Send feedback

Published: July 16, 2012

Adds or moves columns to the beginning of an existing table.

Header file: | mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers.
C++
HRESULT HrAddColumns(
  LPMAPITABLE lptbl,
  LPSPropTagArray lpproptagColumnsNew,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPFREEBUFFER lpFreeBuffer
);

Parameters

lptbl

[in] Pointer to the MAPI table affected.

lpproptagColumnsNew

[in] Pointer to an SPropTagArray structure that contains an array of property tags for the properties to be added or moved to the beginning of the table.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function. Used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function. Used to free memory.

Return value

S_OK

The call succeeded and the specified columns were moved or added.

Remarks

The HrAddColumns function is equivalent to using HrAddColumnsEx with lpfnFilterColumns set to NULL.

See also

Reference

HrAddColumnsEx
MAPIAllocateBuffer
MAPIFreeBuffer
SPropTagArray


HrAddColumnsEx

 Copy code hover
[image]

HrAddColumnsEx
See also Send feedback

Published: July 16, 2012

Adds or moves columns to the beginning of an existing table.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrAddColumnsEx(
  LPMAPITABLE lptbl,
  LPSPropTagArray lpproptagColumnsNew,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPFREEBUFFER lpFreeBuffer,
  void (FAR * lpfnFilterColumns)(
  LPSPropTagArray ptaga)
);

Parameters

lptbl

[in] Pointer to the MAPI table affected.

lpproptagColumnsNew

[in] Pointer to an SPropTagArray structure that contains an array of property tags for the properties to be added or moved to the beginning of the table.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpfnFilterColumns

[in] Pointer to a callback function furnished by the caller. If the lpfnFilterColumns parameter is set to NULL, no callback is made.

ptaga

[in] Pointer to an SPropTagArray structure that contains the array of property tags already existing in the table before properties are added or moved to the beginning. HrAddColumnsEx passes this pointer as the parameter to the callback function pointed to by lpfnFilterColumns.

Return value

S_OK

The call succeeded and the specified columns were moved or added.

Remarks

The properties passed to HrAddColumnsEx using the lpproptagColumnsNew parameter become the first properties exposed on subsequent calls to the IMAPITable::QueryRows method. Any properties previously in the table that were not specified in the lpproptagColumnsNew parameter are exposed after all the added and moved properties.

If any table properties are undefined when QueryRows is called, they are returned with property type PT_NULL and property identifier PROP_ID_NULL.

Notes to Callers

The HrAddColumnsEx function allows the caller to furnish a callback function to filter the columns that were already in the table, for example to convert strings from property type PT_UNICODE to PT_STRING8. HrAddColumnsEx passes a pointer to the previously existing column set as the parameter to the callback function. The callback function can change data in the property tag array but cannot add new tags.

HrAddColumnsEx first calls the callback function if one is furnished, then adds or moves the specified columns, and finally calls IMAPITable::SetColumns.

The lpAllocateBuffer and lpFreeBuffer input parameters point to the MAPIAllocateBuffer and MAPIFreeBuffer functions, respectively. The exact values of the pointers passed to HrAddColumnsEx depend on whether the caller is a client application or a service provider. A client passes pointers to the MAPI functions with the specified names. A service provider passes the pointers it received in its initialization call or retrieved by calling the IMAPISupport::GetMemAllocRoutines method.

See also

Reference

IMAPITable::QueryColumns


HrAllocAdviseSink

 Copy code hover
[image]

HrAllocAdviseSink
Send feedback

Published: July 16, 2012

Creates an advise sink object, given a context specified by the calling implementation and a callback function to be triggered by an event notification.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
STDAPI HrAllocAdviseSink(
  LPNOTIFCALLBACK lpfnCallback,
  LPVOID lpvContext,
  LPMAPIADVISESINK FAR * lppAdviseSink
);

Parameters

lpfnCallback

[in] Pointer to a callback function based on the NOTIFCALLBACK prototype that MAPI is to call when a notification event occurs for the newly created advise sink.

lpvContext

[in] Pointer to caller data passed to the callback function when MAPI calls it. The caller data can represent an address of significance to the client or provider. Typically, for C++ code, the lpvContext parameter represents a pointer to the address of an object.

lppAdviseSink

[out] Pointer to a pointer to an advise sink object.

Return value

None.

Remarks

To use the HrAllocAdviseSink function, a client application or service provider creates an object to receive notifications, creates a notification callback function based on the NOTIFCALLBACK function prototype that goes with that object, and passes a pointer to the object in the HrAllocAdviseSink function as the lpvContext value. Doing so performs a notification; and as part of the notification process, MAPI calls the callback function with the object pointer as the context.

MAPI implements its notification engine asynchronously. In C++, the notification callback can be an object method. If the object generating the notification is not present, the client or provider requesting notification must keep a separate reference count for that object for the object's advise sink.

Caution note Caution

HrAllocAdviseSink should be used sparingly; it is safer for clients to create their own advise sinks.


HrCompareABEntryIDsWithExchangeContext

 Copy code hover
[image]

HrCompareABEntryIDsWithExchangeContext
Send feedback

Published: July 16, 2012

Compares two address book entryIDs safely in a Multiple Exchange profile. This function is a replacement function for IAddrBook::CompareEntryIDs.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrCompareABEntryIDsWithExchangeContext(
  LPMAPISESSION pmsess,
  const MAPIUID *pEmsmdbUID,
  LPADRBOOK pAddrBook,
  ULONG cbEntryID1,
  LPENTRYID lpEntryID1,
  ULONG cbEntryID2,
  LPENTRYID lpEntryID2,
  ULONG ulFlags,
  ULONG * lpulResult
);

Parameters

pmsess

[in] The logged on IMAPISession. It cannot be NULL.

pEmsmdbUID

[in] A pointer to an emsmdbUID that identifies the Exchange Service that contains the Exchange Address Book Provider that this function should use to display details on the entry identifier. If the incoming entry identifier is not an Exchange Address Book Provider entry identifier, this parameter is ignored and the function call behaves like IAddrBook::Details. If this parameter is NULL or a zero MAPIUID, this function behaves like IAddrBook::Details.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

cbEntryID1

[in] The byte count of the first entry identifier specified by the lpEntryID1 parameter.

lpEntryID1

[in] A pointer to the first entry identifier that represents the address book entry to compare.

cbEntryID2

[in] The byte count of the second entry identifier specified by the lpEntryID2 parameter.

lpEntryID2

[in] A pointer to the second entry identifier used in the comparison that represents the address book entry to compare.

ulFlags

[in] Reserved; must be zero.

lpulResult

[out] A pointer to the location that contains the results of the comparison.


HrComposeEID

 Copy code hover
[image]

HrComposeEID
See also Send feedback

Published: July 16, 2012

Creates a compound entry identifier for an object, usually a message in a message store.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrComposeEID(
  LPMAPISESSION psession,
  ULONG cbStoreRecordKey,
  LPBYTE pStoreRecordKey,
  ULONG cbMsgEID,
  LPENTRYID pMsgEID,
  ULONG FAR * pcbEID,
  LPENTRYID FAR * ppEID
);

Parameters

psession

[in] Pointer to the session in use by the client application.

cbStoreRecordKey

[in] Size, in bytes, of the record key of the message store holding the message or other object. If zero is passed in the cbStoreRecordKey parameter, the ppEID parameter points to a copy of the object's entry identifier.

pStoreRecordKey

[in] Pointer to the record key of the message store that contains the message or other object.

cbMsgEID

[in] Size, in bytes, of the entry identifier of the message or other object.

pMsgEID

[in] Pointer to the entry identifier of the object.

pcbEID

[out] Pointer to the size, in bytes, of the returned identifier.

ppEID

[out] Pointer to a pointer to the returned entry identifier. If the value of the cbStoreRecordKey parameter is greater than zero, the ppEID parameter points to a pointer to the compound entry identifier that is created. If cbStoreRecordKey is zero, ppEID points to a pointer to a copy of the object's entry identifier.

Return value

None.

Remarks

If the message or other object for which the compound entry identifier is being created resides in a message store, the identifier is created from the object's entry identifier and the store's record key. If the object is not in a store, that is, if the byte count for the store record key passed in cbStoreRecordKey is zero, the object's entry identifier is simply copied.

The HrComposeEID function enables applications to work with objects in multiple stores through the use of compound entry identifiers. An application can call the HrDecomposeEID function to split the compound entry identifier into its original constituents.

See also

Reference

HrComposeMsgID
HrDecomposeMsgID


HrComposeMsgID

 Copy code hover
[image]

HrComposeMsgID
Send feedback

Published: July 16, 2012

Creates an ASCII string representing a compound entry identifier for an object, usually a message in a message store.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrComposeMsgID(
  LPMAPISESSION psession,
  ULONG cbStoreRecordKey,
  LPBYTE pStoreRecordKey,
  ULONG cbMsgEID,
  LPENTRYID pMsgEID,
  LPSTR FAR * pszMsgID
);

Parameters

psession

[in] Pointer to the session in use by the client application.

cbStoreRecordKey

[in] Size, in bytes, of the record key of the message store that contains the message or other object. If zero is passed in the cbStoreRecordKey parameter, the pszMsgID parameter points to a copy of the entry identifier converted to text.

pStoreRecordKey

[in] Pointer to the record key of the message store that contains the message or other object.

cbMsgEID

[in] Size, in bytes, of the entry identifier of the message or other object.

pMsgEID

[in] Pointer to the entry identifier of the object.

pszMsgID

[out] Pointer to the returned ASCII string. If the cbStoreRecordKey parameter is greater than zero, the pszMsgID parameter points to a compound entry identifier converted to text. If cbStoreRecordKey is zero, pszMsgID points to a noncompound entry identifier converted to text.

Return value

None.

Remarks

If the message or other object for which the compound entry identifier is being created resides in a message store, the identifier string is created from the object's entry identifier and the store's record key. If the object is not in a store, that is, if the byte count for the store record key passed in the cbStoreRecordKey parameter is zero, the object's entry identifier is simply copied and converted into a string.

Calling the HrComposeMsgID function is equivalent to calling the HrComposeEID function and then the HrSzFromEntryID function.

HrComposeMsgID enables client applications to work with objects in multiple stores through the use of compound entry identifiers. An application can call the HrDecomposeMsgID function to split the compound entry identifier into its original constituents.


HrCreateOfflineObj

 Copy code hover
[image]

HrCreateOfflineObj
Example See also Send feedback

Published: July 16, 2012

Creates a MAPI offline object that is used by the provider and store in order to notify MAPI when the object goes online and offline,

Exported by: | Msmapi32.dll
Implemented by: | Outlook
Called by: | Client
C++
STDAPI HrCreateOfflineObj(
ULONG ulFlags,
MAPIOFFLINE_CREATEINFO* pCreateInfo,
IMAPIOfflineMgr** ppOffline
);

Parameters

ulFlags

[in] It must be 0.

pCreateInfo

[in] A pointer to a MAPIOFFLINE_CREATEINFO structure that contains the information needed to create the offline object.

ppOffline

[out] A pointer to the IMAPIOfflineMgr interface.

Return value

None.

HrOpenOfflineObj

Example

Copy code Copy code
// create/get global offline object to use as parent.
 ZeroMemory(&OfflineCreateInfo, sizeof(OfflineCreateInfo));
  OfflineCreateInfo.ulSize = sizeof(OfflineCreateInfo);
  OfflineCreateInfo.ulCreateFlags = 0;
  OfflineCreateInfo.pwszProfileName = pszProfileName;
  OfflineCreateInfo.ulCapabilities = ulCapabilities;
  OfflineCreateInfo.pGUID = &GUID_GlobalState;
  OfflineCreateInfo.pInstance = NULL;
  OfflineCreateInfo.pParent = NULL;
  OfflineCreateInfo.pMAPISupport = NULL;
  OfflineCreateInfo.pAggregateInfo = NULL;
  OfflineCreateInfo.pConnectInfo = NULL;

// Create an offline object for the provider with global as parent.
  ZeroMemory(&OfflineCreateInfo, sizeof(OfflineCreateInfo));
  OfflineCreateInfo.ulSize = sizeof(OfflineCreateInfo);
  OfflineCreateInfo.ulCreateFlags = 0;
  OfflineCreateInfo.pwszProfileName = pszProfileName;
  OfflineCreateInfo.ulCapabilities = ulCapabilities;
  OfflineCreateInfo.pGUID = pGuid;
  OfflineCreateInfo.pInstance = pInstance;
  OfflineCreateInfo.pParent = pGlobalOfflineMgr;
  OfflineCreateInfo.pMAPISupport = NULL;
  OfflineCreateInfo.pAggregateInfo = NULL;
  OfflineCreateInfo.pConnectInfo = NULL;

  // create store offline object which aggregates with the store object and has provider offline object as parent.
  ZeroMemory(&OfflineCreateInfo, sizeof(OfflineCreateInfo));
  OfflineCreateInfo.ulSize = sizeof(OfflineCreateInfo);
  OfflineCreateInfo.ulCreateFlags = 0;
  OfflineCreateInfo.pwszProfileName = pszProfileName;
  OfflineCreateInfo.ulCapabilities = ulCapabilities;
  OfflineCreateInfo.pGUID = NULL;
  OfflineCreateInfo.pInstance = NULL;
  OfflineCreateInfo.pParent = m_pProviderOfflineMgr;
  OfflineCreateInfo.pMAPISupport = pMAPISup;
  OfflineCreateInfo.pAggregateInfo = &AggregateInfo;
  OfflineCreateInfo.pConnectInfo = NULL;

  ZeroMemory(&AggregateInfo, sizeof(AggregateInfo));
  AggregateInfo.ulSize = sizeof(AggregateInfo);
  AggregateInfo.pOuterObj = (IMsgStore *)this;
  AggregateInfo.pRefTrackRoot = NULL;

See also

Reference

MAPIOFFLINE_AGGREGATEINFO
MAPIOFFLINE_CREATEINFO


HrDecomposeEID

 Copy code hover
[image]

HrDecomposeEID
Send feedback

Published: July 16, 2012

Separates the compound entry identifier of an object, usually a message in a message store, into the entry identifier of that object in the store and the store's entry identifier.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrDecomposeEID(
  LPMAPISESSION psession,
  ULONG cbEID,
  LPENTRYID pEID,
  ULONG FAR * pcbStoreEID,
  LPENTRYID FAR * ppStoreEID,
  ULONG FAR * pcbMsgEID,
  LPENTRYID FAR * ppMsgEID
);

Parameters

psession

[in] Pointer to the session in use by the client application.

cbEID

[in] Size, in bytes, of the compound entry identifier to be separated.

pEID

[in] Pointer to the compound entry identifier to be separated.

pcbStoreEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the message store that contains the object. If the pEID parameter points to a noncompound entry identifier, then the pcbStoreEID parameter points to a value of zero.

ppStoreEID

[out] Pointer to a pointer to the returned entry identifier of the message store that contains the object. If the pEID parameter points to a noncompound entry identifier, NULL is returned in the ppStoreEID parameter.

pcbMsgEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the object. If the pEID parameter points to a noncompound entry identifier, then the pcbMsgEID parameter is equal to the value of the cbEID parameter.

ppMsgEID

[out] Pointer to a pointer to the returned entry identifier of the object. If the pEID parameter points to a noncompound entry identifier, ppMsgEID points to a pointer to a copy of the noncompound entry identifier.

Return value

None.

Remarks

If the identifier specified by the pEID parameter is compound, it is split into the entry identifier of the object within its message store and the store's entry identifier. Noncompound entry identifier strings are simply copied. The compound identifier to be separated is usually one created by the HrComposeEID function.

Notes to Callers

The memory that holds the pEID parameter is released upon successful completion of this function. The calling implementation is responsible for freeing memory for the output parameters.


HrDecomposeMsgID

 Copy code hover
[image]

HrDecomposeMsgID
Send feedback

Published: July 16, 2012

Separates the ASCII representation of the compound entry identifier of an object, usually a message in a message store, into the entry identifier of that object in the store and the store's entry identifier.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrDecomposeMsgID(
  LPMAPISESSION psession,
  LPSTR szMsgID,
  ULONG FAR * pcbStoreEID,
  LPENTRYID FAR * ppStoreEID,
  ULONG FAR * pcbMsgEID,
  LPENTRYID FAR * ppMsgEID
);

Parameters

psession

[in] Pointer to the session in use by the client application.

szMsgID

[in] The string representing the entry identifier of the object.

pcbStoreEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the message store that contains the object. If the szMsgID parameter points to a noncompound entry identifier string, then the pcbStoreEID parameter points to zero.

ppStoreEID

[out] Pointer to a pointer to the returned entry identifier of the message store that contains the object. If the szMsgID parameter points to a noncompound entry identifier, NULL is returned in the ppStoreEID parameter.

pcbMsgEID

[out] Pointer to the returned size, in bytes, of the entry identifier of the object within its store. If the szMsgID parameter points to a noncompound entry identifier string, then the pcbMsgEID parameter is equal to the value of the cbEID parameter.

ppMsgEID

[out] Pointer to a pointer to the returned entry identifier string of the object within its store. If the szMsgID parameter points to a noncompound entry identifier, ppMsgEID points to a pointer to a converted copy of the noncompound entry identifier.

Return value

None.

Remarks

If the identifier specified by the szMsgID parameter is compound, it is converted from ASCII and split into the entry identifier of the object within its message store and the store's entry identifier. Noncompound entry identifier strings are simply converted and copied. The compound identifier string to be separated is usually one created by the HrComposeMsgID function.

Calling the HrDecomposeMsgID function is equivalent to calling the HrEntryIDFromSz function and then the HrDecomposeEID function.


HrDispatchNotifications

 Copy code hover
[image]

HrDispatchNotifications
Send feedback

Published: July 16, 2012

Forces dispatching of all queued notifications.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrDispatchNotifications(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

All queued notifications have been dispatched.

MAPI_E_USER_CANCEL

WM_QUIT, WM_QUERYENDSESSION, or WM_ENDSESSION was received.

MAPI_E_NOT_INITIALIZED

MAPI was not initialized.

Remarks

The HrDispatchNotifications function causes MAPI to dispatch all notifications that are currently queued in the MAPI notification engine without waiting for a message dispatch. This can have a beneficial effect on memory utilization. For more information, see Forcing a Notification.

Notes to Callers

Some applications wait for a notification message in a timeout loop using the Windows PeekMessage and DispatchMessage functions. On all but the fastest platforms, such applications might experience poor performance or even blockage of notifications. Using HrDispatchNotifications not only reduces code but improves performance.


HrDoABDetailsWithExchangeContext

 Copy code hover
[image]

HrDoABDetailsWithExchangeContext
Send feedback

Published: July 16, 2012

Ensures that the OpenEntry method is opened by the expected Exchange address book provider. This function works similarly to IAddrBook::Details, but opens the entryID using the Exchange address book identified by the pEmsmdbUID parameter.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryWithExchangeContext(
  LPMAPISESSION   pmsess,
  const MAPIUID  *pEmsmdbUID,
  LPADRBOOK pAddrBook,
  ULONG_PTR FAR * lpulUIParam,
  LPFNDISMISS lpfnDismiss,
  LPVOID lpvDismissContext,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPENTRYID lpEntryID,
  LPFNBUTTON lpfButtonCallback,
  LPVOID lpvButtonContext,
  LPSTR lpszButtonText,
  ULONG ulFlags,
);

Parameters

pmsess

The logged on IMAPISession. It cannot be NULL.

pEmsmdbUID

A pointer to an emsmdbUID that identifies the Exchange Service that contains the Exchange address book provider that is used by the function to open the entry identifier. If the incoming entry identifier is not an Exchange address book provider entry identifier, this parameter is ignored and the function behaves like IAddrBook::OpenEntry. If this parameter is NULL or a zero MAPIUID, this function also acts exactly like IAddrBook::OpenEntry.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

lpulUIParam

[out] A handle to the parent window for the dialog box.

lpfnDismiss

[in] A pointer to a function based on the DISMISSMODELESS prototype, or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client that is calling Details that the dialog box is no longer active.

lpvDismissContext

[in] A pointer to context information to pass to the DISMISSMODELESS function pointed to by the lpfnDismiss parameter. This parameter applies only to the modeless version of the dialog box by including the DIALOG_SDI flag in the ulFlags parameter.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpfButtonCallback

[in] A pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] A pointer to data that was used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] A pointer to a string that contains text to be applied to the added button, if that button is extensible. The lpszButtonText parameter should be NULL when an extensible button is not needed.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flags can be set:

AB_TELL_DETAILS_CHANGE

Indicates that Details returns TRUE if changes are actually made to the address; otherwise, Details returns FALSE.

DIALOG_MODAL

Displays the modal version of the common address dialog box. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Displays the modeless version of the common address dialog box. This flag is mutually exclusive with DIALOG_MODAL.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.


HrDoABDetailsWithProviderUID

 Copy code hover
[image]

HrDoABDetailsWithProviderUID
Send feedback

Published: July 16, 2012

Ensures that the OpenEntry method is opened by the expected Exchange address book provider. This function works similarly to IAddrBook::Details but opens entryID using the Exchange address book identified by pEmsabpUID.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrDoABDetailsWithProviderUID(
  const MAPIUID   *pEmsabpUID,
  LPADRBOOK        pAddrBook,
  ULONG_PTR FAR *  lpulUIParam,
  LPFNDISMISS      lpfnDismiss,
  LPVOID           lpvDismissContext,
  ULONG            cbEntryID,
  LPENTRYID        lpEntryID,
  LPFNBUTTON       lpfButtonCallback,
  LPVOID           lpvButtonContext,
  LPSTR           lpszButtonText,
  ULONG            ulFlags
);

Parameters

pEmsabpUID

[in] A pointer to an emsabpUID that identifies the Exchange address book provider this function should use to display details on the entry identifier. If the incoming entry identifier is not an Exchange address book provider entry identifier, this parameter is ignored and the function call acts exactly like IAddrBook::Details. If this parameter is NULL or a zero MAPIUID, this function also acts exactly like IAddrBook::Details.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

lpulUIParam

[out] A handle to the parent window for the dialog box.

lpfnDismiss

[in] A pointer to a function based on the DISMISSMODELESS prototype, or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client that is calling Details that the dialog box is no longer active.

lpvDismissContext

[in] A pointer to context information to pass to the DISMISSMODELESS function pointed to by the lpfnDismiss parameter. This parameter applies only to the modeless version of the dialog box by including the DIALOG_SDI flag in the ulFlags parameter.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpfButtonCallback

[in] A pointer to a function based on the LPFNBUTTON function prototype. An LPFNBUTTON function adds a button to the details dialog box.

lpvButtonContext

[in] A pointer to data that was used as a parameter for the function specified by the lpfButtonCallback parameter.

lpszButtonText

[in] A pointer to a string that contains text to be applied to the added button, if that button is extensible. The lpszButtonText parameter should be NULL when an extensible button is not needed.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flags can be set:

AB_TELL_DETAILS_CHANGE

Indicates that Details returns TRUE if changes are actually made to the address; otherwise, Details returns FALSE.

DIALOG_MODAL

Displays the modal version of the common address dialog box. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Displays the modeless version of the common address dialog box. This flag is mutually exclusive with DIALOG_MODAL.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.


HrEntryIDFromSz

 Copy code hover
[image]

HrEntryIDFromSz
Send feedback

Published: July 16, 2012

Recreates an entry identifier from its ASCII encoding.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HRESULT HrEntryIDFromSz(
  LPSTR sz,
  ULONG FAR * pcb,
  LPENTRYID FAR * ppentry
);

Parameters

sz

[in] Pointer to the ASCII string from which to create an entry identifier.

pcb

[out] Pointer to the size, in bytes, of the entry identifier pointed to by the ppentry parameter.

ppentry

[out] Pointer to a pointer to the returned ENTRYID structure that contains the new entry identifier.

Return value

S_OK

The recreation was successful.

MAPI_E_INVALID_ENTRYID

The entry ID was invalid.

Remarks

The HrEntryIDFromSz and HrSzFromEntryID functions provide conversion between the string and binary formats of entry identifiers.

Notes to Callers

The HrEntryIDFromSz function allocates memory for the ASCII string using the MAPIAllocateBuffer function.


HrGetAutoDiscoverXML

 Copy code hover
[image]

HrGetAutoDiscoverXML
Send feedback

Published: July 16, 2012

Returns an Extensible Markup Language (XML) stream that represents information retrieved from the auto-discovery service of a Microsoft Exchange 2007 server.

Quick Info

Exported by: | olmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
HRESULT HrGetAutoDiscoverXML(
    __in_z const WCHAR *pwzAddress,
    __in_opt_z const WCHAR *pwzPassword,
    __in_opt HANDLE hCancelEvent,
    __in_opt ULONG ulFlags,
    __out IStream** ppXmlStream);

Parameters

pwzAddress

[in] A null-terminated Simple Mail Transfer Protocol (SMTP) e-mail address of the account for which you want to retrieve the auto-discovery information.

pwzPassword

[in] An optional password for the account specified by pwzAddress. Note that passing any password has no effect if the account specified by pwzAddress does not require a password.

hCancelEvent

[in] An unset Win32 event handle that is optional and can be used to cancel the operation. To cancel the operation, set the event and pass the event handle as hCancelEvent; pass null if you do not want to cancel the operation. Note that passing a value that does not represent an event handle has no effect and is ignored by the function.

ulFlags

[in] This parameter is not used. It must be 0.

ppXmlStream

[out] A pointer to an IStream object that contains the autodiscovery XML. Returns null if the autodiscovery operation fails. You must release the IStream object when you are finished with it.

Return Values

S_OK

  • The function call is successful.

E_INVALIDARG

  • pwzAddress is null or is not a valid SMTP address, or ppXmlStream is a null pointer to an IStream object.

MAPI_E_NOT_FOUND

  • Client computer is not connected to the network, client computer is not connected to a Microsoft Exchange 2007 server, pwzAddress is not an account on an Exchange 2007 server, or pwzAddress is an account that does not support Exchange auto-discovery service.

MAPI_E_USER_CANCEL

  • An event handle has been passed to hCancelEvent to cancel the operation.

STRSAFE_E_INSUFFICIENT_BUFFER

  • The value passed to pwzAddress or pwzPassword is too long, such that it overflows the internal buffer of size 256 bytes.


HrGetGALFromEmsmdbUID

 Copy code hover
[image]

HrGetGALFromEmsmdbUID
Send feedback

Published: July 16, 2012

Returns the entry identifier of the global address book for the Exchange service identified by pEmsmdbUID. The returned entry identifier should be freed using MAPIFreeBuffer.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrGetGALFromEmsmdbUID(
  LPMAPISESSION pSess,
  LPADRBOOK lpAdrBook,
  const MAPIUID * pEmsmdbUID,
  ULONG * lpcbeid,
  LPENTRYID * lppeid
);

Parameters

pSess

[in] The logged on IMAPISession. It cannot be NULL.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

pEmsmdbUID

[in] A pointer to an emsmdbUID that identifies the GAL of the Exchange Service to be retrieved. If pEmsmdbUID is NULL or the zero UID, this function gets the legacy GAL of the Exchange Service.

lpcbeid

[out] A pointer to the byte count of the entry identifier of the global address list.

lppeid

[out] A pointer to the entry identifier of the global address list. This should be freed using MAPIFreeBuffer.


HrGetOneProp

 Copy code hover
[image]

HrGetOneProp
See also Send feedback

Published: July 16, 2012

Retrieves the value of a single property from a property interface, that is, an interface derived from IMAPIProp.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HrGetOneProp(
  LPMAPIPROP pmp,
  ULONG ulPropTag,
  LPSPropValue FAR * ppprop
);

Parameters

pmp

[in] Pointer to the IMAPIProp interface from which the property value is to be retrieved.

ulPropTag

[in] Property tag of the property to be retrieved.

ppprop

[out] Pointer to a pointer to the returned SPropValue structure defining the retrieved property value.

Return value

MAPI_E_NOT_FOUND

The requested property is not available from the specified interface.

Remarks

Unlike the IMAPIProp::GetProps method, the HrGetOneProp function never returns any warning. Because it retrieves only one property, it simply either succeeds or fails. For retrieving multiple properties, GetProps is faster.

You can set or change a single property with the HrSetOneProp function.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIFunctions.cpp | GetMAPIObjectType | MFCMAPI uses the HrGetOneProp method to retrieve the type of an object.

See also

Concepts

MFCMAPI as a Code Sample


HrIStorageFromStream

 Copy code hover
[image]

HrIStorageFromStream
Send feedback

Published: July 16, 2012

Layers an IStorage interface onto an IStream object.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrIStorageFromStream(
  LPUNKNOWN lpUnkIn,
  PIID lpInterface,
  ULONG ulFlags,
  LPSTORAGE FAR * lppStorageOut
);

Parameters

lpUnkIn

[in] Pointer to the IUnknown object implementing IStream.

lpInterface

[in] Pointer to the interface identifier (IID) for the stream object. Any of the following values can be passed in the lpInterface parameter: NULL, IID_IStream, or IID_ILockBytes. Passing NULL in lpInterface is the same as passing IID_IStream.

ulFlags

[in] Bitmask of flags that controls how the storage object is to be created relative to the stream. The default setting is STGSTRM_RESET, which gives the storage object read-only access and starts it at position zero of the stream. The following flags can be set in any combination, except as noted:

STGSTRM_CREATE

Creates a new storage object for the stream object. This flag cannot be set if the STGSTRM_RESET flag is set.

STGSTRM_CURRENT

Starts storage at the current position of the stream. This flag cannot be set if the STGSTRM_RESET flag is set.

STGSTRM_MODIFY

Allows the calling service provider to write to the returned storage. This flag cannot be set if the STGSTRM_RESET flag is set.

STGSTRM_RESET

Starts storage at position zero. This flag cannot be set if any other flag is set.

lppStorageOut

[out] Pointer to a pointer to the returned IStorage object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Message store providers support the HrIStorageFromStream function using the IStorage interface for attachments. Store providers must implement the IStream interface. HrIStorageFromStream provides the IStorage interface for the IStream object. It is possible to pass either an ILockBytes or an IStream interface in lpUnkIn.


HrOpenABEntryUsingDefaultContext

 Copy code hover
[image]

HrOpenABEntryUsingDefaultContext
Send feedback

Published: July 16, 2012

Performs the same function as HrOpenABEntryWithExchangeContext except that it uses the legacy emsmdbUID as the pEmsmdbUID parameter. Do not use this function unless you cannot obtain the correct emsmdbUID for the call to HrOpenABEntryWithExchangeContext.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryUsingDefaultContext(
  LPMAPISESSION pmsess,
  LPADRBOOK pAddrBook,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

pmsess

[in] The logged on IMAPISession. It cannot be NULL.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface that is used to access the open entry. Passing NULL returns the standard interface of the object. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists it is IDistList : IMAPIContainer, and for containers it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls how the entry is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read and write permission, the address book provider attempts to open the entry with read and write permission. The client can retrieve the access level that was granted by calling the IMAPIProp::GetProps method of the open entry and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_CACHE_ONLY

Uses only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange address book provider.

MAPI_DEFERRED_ERRORS

Allows the call to succeed, potentially before the entry is fully open and available, implying that subsequent calls to the entry might return an error.

MAPI_GAL_ONLY

Uses only the GAL to perform name resolution. This flag is supported only by the Exchange address book provider.

MAPI_MODIFY

Requests that the entry be opened with read and write permission. Because entries are opened with read-only access by default, clients should not assume that read and write permission was granted regardless of whether MAPI_MODIFY is set.

MAPI_NO_CACHE

Does not use the offline address book to perform name resolution. This flag is supported only by the Exchange address book provider.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer of the opened entry.


HrOpenABEntryWithExchangeContext

 Copy code hover
[image]

HrOpenABEntryWithExchangeContext
Send feedback

Published: July 16, 2012

Opens the entryID using the Exchange Address Book identified by pEmsmdbUID. This function works similarly to IAddrBook::Details except that using this function ensures that the IAddrBook::OpenEntry is opened by using the expected Exchange Address Book Provider.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrDoABDetailsWithExchangeContext(
  LPMAPISESSION pmsess,
  const MAPIUID *pEmsmdbUID,
  LPADRBOOK pAddrBook,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags
);

Parameters

pmsess

[in] The logged on IMAPISession. It cannot be NULL.

pEmsmdbUID

[in] A pointer to an emsmdbUID that identifies the Exchange Service that contains the Exchange Address Book Provider that this function should use to display details on the entry identifier. If the incoming entry identifier is not an Exchange Address Book Provider entry identifier, this parameter is ignored and the function call behaves like IAddrBook::Details. If this parameter is NULL or a zero MAPIUID, this function behaves like IAddrBook::Details.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

ulFlags

[in] A bitmask of flags that controls how the entry is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read and write permission, the address book provider attempts to open the entry with read and write permission. The client can retrieve the access level that was granted by calling the IMAPIProp::GetProps method of the open entry and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_CACHE_ONLY

Uses only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_DEFERRED_ERRORS

Allows the call to succeed, potentially before the entry is fully open and available, implying that subsequent calls to the entry might return an error.

MAPI_GAL_ONLY

Uses only the GAL to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

MAPI_MODIFY

Requests that the entry be opened with read and write permission. Because entries are opened with read-only access by default, clients should not assume that read and write permission was granted regardless of whether MAPI_MODIFY is set.

MAPI_NO_CACHE

Does not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.


HrOpenABEntryWithProviderUID

 Copy code hover
[image]

HrOpenABEntryWithProviderUID
Send feedback

Published: July 16, 2012

Opens the entryID using the Exchange Address Book identified by pEmsabpUID. This function works similarly to IAddrBook::OpenEntry except that using this function ensures that IAddrBook::OpenEntry is opened by using the expected Exchange Address Book provider.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryWithProviderUID(
  const MAPIUID *pEmsabpUID,
  LPADRBOOK pAddrBook,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

pEmsmdbUID

[in] A pointer to an emsmdbUID that identifies the Exchange Service that contains the Exchange Address Book Provider that this function should use to display details on the entry identifier. If the incoming entry identifier is not an Exchange Address Book Provider entry identifier, this parameter is ignored and the function call behaves like IAddrBook::Details. If this parameter is NULL or a zero MAPIUID, this function behaves like IAddrBook::Details.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface that is used to access the open entry. Passing NULL returns the standard interface of the object. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists, it is IDistList : IMAPIContainerand for containers, it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls the how the entry is opened, The following flags can be set:

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read and write permission, the address book provider attempts to open the entry with read and write permission. The client can retrieve the access level that was granted by calling the IMAPIProp::GetProps method of the open entry and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_CACHE_ONLY

Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_DEFERRED_ERRORS

Allows the call to succeed, potentially before the entry is fully open and available, implying that subsequent calls to the entry might return an error.

MAPI_GAL_ONLY

Use only the GAL to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

MAPI_MODIFY

Requests that the entry be opened with read and write permission. Because entries are opened with read-only access by default, clients should not assume that read and write permission was granted regardless of whether MAPI_MODIFY is set.

MAPI_NO_CACHE

Do not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer of the opened entry.


HrOpenABEntryWithProviderUIDSupport

 Copy code hover
[image]

HrOpenABEntryWithProviderUIDSupport
Send feedback

Published: July 16, 2012

Performs the same function as the HrOpenABEntryWithProviderUID function except that the HrOpenABEntryWithProviderUIDSupport function opens the entry using the given support object instead of using the session and the address book.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryWithProviderUIDSupport(
  const MAPIUID *pEmsabpUID,
  LPMAPISUP lpSup,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

pEmsabpUID

[in] A pointer to an emsabpUID parameter that identifies the Exchange address book provider that this function should use to display details on the entry identifier. If the incoming entry identifier is not an Exchange address book provider entry identifier, this parameter is ignored and the function call acts exactly like IAddrBook::Details. If this parameter is NULL or a zero MAPIUID, this function also acts exactly like IAddrBook::Details.

lpSup

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface to be used to access the open entry. Passing NULL returns the standard interface of the object. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists it is IDistList : IMAPIContainer, and for containers it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flags can be set:

AB_TELL_DETAILS_CHANGE

Indicates that Details returns TRUE if changes are actually made to the address; otherwise, Details returns FALSE.

DIALOG_MODAL

Displays the modal version of the common address dialog box. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Displays the modeless version of the common address dialog box. This flag is mutually exclusive with DIALOG_MODAL.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer of the opened entry.


HrOpenABEntryWithResolvedRow

 Copy code hover
[image]

HrOpenABEntryWithResolvedRow
Send feedback

Published: July 16, 2012

Performs the same function as HrOpenABEntryWithExchangeContext except that it automatically gets the emsabpUID from the resolved row and opens the entryID.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryWithResolvedRow(
  LPSRow prwResolved,
  LPADRBOOK pAddrBook,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID lpInterface,
  ULONG ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

prwResolved

[in] A pointer to the resolved row that is used to get the emsabpUID and open the entryID.

pAddrBook

[in] The address book used to open the entry identifier. It cannot be NULL.

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface that is used to access the open entry. Passing NULL returns the standard interface of the object. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists, it is IDistList : IMAPIContainerand for containers, it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls how the entry is opened. The following flags can be set:

MAPI_BEST_ACCESS

Requests that the entry be opened with the maximum allowed network and client permissions. For example, if the client has read and write permission, the address book provider attempts to open the entry with read and write permission. The client can retrieve the access level that was granted by calling the IMAPIProp::GetProps method of the open entry and retrieving the PR_ACCESS_LEVEL (PidTagAccessLevel) property.

MAPI_CACHE_ONLY

Uses only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

MAPI_DEFERRED_ERRORS

Allows the call to succeed, potentially before the entry is fully open and available, implying that subsequent calls to the entry might return an error.

MAPI_GAL_ONLY

Uses only the GAL to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

MAPI_MODIFY

Requests that the entry be opened with read and write permission. Because entries are opened with read-only access by default, clients should not assume that read and write permission was granted regardless of whether MAPI_MODIFY is set.

MAPI_NO_CACHE

Does not use the offline address book to perform name resolution. This flag is supported only by the Exchange Address Book Provider.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer of the opened entry.


HrOpenABEntryWithSupport

 Copy code hover
[image]

HrOpenABEntryWithSupport
Send feedback

Published: July 16, 2012

Do not use this function.

Header file: | abhelp.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrOpenABEntryWithSupport(
  LPMAPISUP lpSup,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  LPCIID  lpInterface,
  ULONG  ulFlags,
  ULONG FAR * lpulObjType,
  LPUNKNOWN FAR * lppUnk
);

Parameters

lpSup

cbEntryID

[in] The byte count of the entry identifier specified by the lpEntryID parameter.

lpEntryID

[in] A pointer to the entry identifier that represents the address book entry to open.

lpInterface

[in] A pointer to the interface identifier (IID) of the interface to be used to access the open entry. Passing NULL returns the standard interface of the object. For messaging users, the standard interface is IMailUser : IMAPIProp. For distribution lists, it is IDistList : IMAPIContainer, and for containers, it is IABContainer : IMAPIContainer. Callers can set lpInterface to the appropriate standard interface or an interface in the inheritance hierarchy.

ulFlags

[in] A bitmask of flags that controls the type of the text for the lpszButtonText parameter. The following flags can be set:

AB_TELL_DETAILS_CHANGE

Indicates that Details returns TRUE if changes are actually made to the address; otherwise, Details returns FALSE.

DIALOG_MODAL

Displays the modal version of the common address dialog box. This flag is mutually exclusive with DIALOG_SDI.

DIALOG_SDI

Displays the modeless version of the common address dialog box. This flag is mutually exclusive with DIALOG_MODAL.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpulObjType

[out] A pointer to the type of the opened entry.

lppUnk

[out] A pointer to a pointer of the opened entry.


HrOpenOfflineObj

 Copy code hover
[image]

HrOpenOfflineObj
See also Send feedback

Published: July 16, 2012

Opens an offline object based on a given profile.

Quick Info

Exported by: | msmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
typedef HRESULT (STDMETHODCALLTYPE HROPENOFFLINEOBJ)(
      ULONG ulReserved,
      LPCWSTR pwszProfileNameIn,
      const GUID* pGUID,
      const GUID* pReserved,
      IMAPIOfflineMgr** ppOfflineObj);

Parameters

ulReserved

[in] This parameter is not used. It must be 0.

pwszProfileNameIn

[in] The name of the profile that the offline object is for. It must be expressed in Unicode.

pGUID

[in] Pointer to a GUID which can be used to uniquely identify this object from other offline objects. It must be GUID_GlobalState.

pReserved

[in] This parameter is not used. It must be null.

ppOfflineObj

[out] A pointer to the requested offline object. The caller can use this pointer to access the IMAPIOfflineMgr : IMAPIOffline interface to find the callbacks that this object supports and to set up callbacks for it.

Return Values

S_OK

  • The function call is successful.

MAPI_E_NOT_FOUND

  • The function call failed.

Remarks

This is the first call that a client makes when the client wants to be notified of any connection state changes for a given profile. Upon calling HrOpenOfflineObj, the client obtains an offline object that supports IMAPIOfflineMgr. The client can check for the kinds of callbacks supported by the object (by using IMAPIOffline::GetCapabilities), and then set up callbacks for it (by using IMAPIOfflineMgr::Advise).

When using GetProcAddress to look for the address of this function in msmapi32.dll, specify HrOpenOfflineObj@20 as the procedure name.

HrOpenOfflineObj only works for clients that are MAPI providers, COM Add-Ins, and Exchange Client Extensions running inside the Outlook process. Otherwise, HrOpenOfflineObj returns MAPI_E_NOT_FOUND.

See also

Reference

IMAPIOffline : IUnknown
IMAPIOfflineMgr : IMAPIOffline

Concepts

About the Offline State API
MAPI Constants


HrQueryAllRows

 Copy code hover
[image]

HrQueryAllRows
Send feedback

Published: July 16, 2012

Retrieves all rows of a table.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT HrQueryAllRows(
  LPMAPITABLE ptable,
  LPSPropTagArray ptaga,
  LPSRestriction pres,
  LPSSortOrderSet psos,
  LONG crowsMax,
  LPSRowSet FAR * pprows
);

Parameters

ptable

[in] Pointer to the MAPI table from which rows are retrieved.

ptaga

[in] Pointer to an SPropTagArray structure that contains an array of property tags indicating table columns. These tags are used to select the specific columns to be retrieved. If the ptaga parameter is NULL, HrQueryAllRows retrieves the entire column set of the current table view passed in the ptable parameter.

pres

[in] Pointer to an SRestriction structure that contains retrieval restrictions. If the pres parameter is NULL, HrQueryAllRows makes no restrictions.

psos

[in] Pointer to an SSortOrderSet structure identifying the sort order of the columns to be retrieved. If the psos parameter is NULL, the default sort order for the table is used.

crowsMax

[in] Maximum number of rows to be retrieved. If the value of the crowsMax parameter is zero, no limit on the number of rows retrieved is set.

pprows

[out] Pointer to a pointer to the returned SRowSet structure that contains an array of pointers to the retrieved table rows.

Return value

S_OK

The call retrieved the expected rows of a table.

MAPI_E_TABLE_TOO_BIG

The number of rows in the table is larger than the number passed for the crowsMax parameter.

Remarks

A client application or service provider has no control over the number of rows HrQueryAllRows attempts to retrieve, other than by imposing a restriction pointed to by the pres parameter. The crowsMax parameter does not limit the retrieval to a certain number of table rows, but rather defines a maximum amount of memory available to hold all retrieved rows. The only protection against massive memory overflow is the stopgap feature provided by setting crowsMax. The error return MAPI_E_TABLE_TOO_BIG means the table contains too many rows to be held all at once in memory.

Tables that are typically small, such as a message store table or a provider table, usually can be safely retrieved with HrQueryAllRows. Tables at risk of being very large, such as a contents table or even a recipients table, should be traversed in subsections using the IMAPITable::QueryRows method.

If any table properties are undefined when HrQueryAllRows is called, they are returned with property type PT_NULL and property identifier PROP_ID_NULL


HrSetOneProp

 Copy code hover
[image]

HrSetOneProp
Send feedback

Published: July 16, 2012

Sets or changes the value of a single property on a property interface, that is, an interface derived from IMAPIProp.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HrSetOneProp(
  LPMAPIPROP pmp,
  LPSPropValue pprop
);

Parameters

pmp

[in] Pointer to an IMAPIProp interface on which the property value is to be set or changed.

pprop

[in] Pointer to the SPropValue structure defining the value to be set on the pmp property.

Return value

None.

Remarks

Unlike the IMAPIProp::SetProps method, the HrSetOneProp function never returns any warnings. Because it sets only one property, it simply either succeeds or fails. For setting or changing multiple properties, SetProps is faster.

You can retrieve a single property with the HrGetOneProp function.


HrSzFromEntryID

 Copy code hover
[image]

HrSzFromEntryID
Send feedback

Published: July 16, 2012

Encodes an entry identifier into an ASCII string.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrSzFromEntryID(
  ULONG cb,
  LPENTRYID pentry,
  LPSTR FAR * psz
);

Parameters

cb

[in] Size, in bytes, of the entry identifier pointed to by the pentry parameter.

pentry

[in] Pointer to an ENTRYID structure that contains the entry identifier to be encoded.

psz

[out] Pointer to the returned ASCII string.

Return value

None.

Remarks

The HrEntryIDFromSz and HrSzFromEntryID functions provide conversion between the string and binary formats of entry identifiers. With MAPI, you should use structures with binary data.

Notes to Callers

The HrSzFromEntryID function allocates memory for the ASCII string using the MAPIAllocateBuffer function.


HrThisThreadAdviseSink

 Copy code hover
[image]

HrThisThreadAdviseSink
Send feedback

Published: July 16, 2012

Creates an advise sink that wraps an existing advise sink for thread safety.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrThisThreadAdviseSink(
  LPMAPIADVISESINK lpAdviseSink,
  LPMAPIADVISESINK FAR * lppAdviseSink
);

Parameters

lpAdviseSink

[in] Pointer to the advise sink to be wrapped.

lppAdviseSink

[out] Pointer to a pointer to a new advise sink that wraps the advise sink pointed to by the lpAdviseSink parameter.

Return value

None.

Remarks

The purpose of the wrapper is to make sure that notification is called on the same thread that called the HrThisThreadAdviseSink function. This function is used to protect notification callbacks that must run on a particular thread.

Client applications should use HrThisThreadAdviseSink to restrict when notifications are generated, that is, when calls are made to the IMAPIAdviseSink::OnNotify method of the advise sink object passed by the client in a previous Advise call. If notifications are allowed to be generated arbitrarily, a notification implementation might force a client into multithreaded operation when that would not be appropriate. For example, a client might use a library, such as one of the Microsoft Foundation Class Libraries, that does not support multithreaded calls. Notification on a different thread would make such a client difficult to test and prone to error.

HrThisThreadAdviseSink makes sure that OnNotify calls occur only at these appropriate times:

  • During processing of a call to any MAPI method.

  • During processing of Windows messages.

When HrThisThreadAdviseSink is implemented, any calls to the new advise sink's OnNotify method on any thread cause the original notification method to be executed on the thread on which HrThisThreadAdviseSink was called.

For more information about notification and advise sinks, see Event Notification in MAPI and Implementing an Advise Sink Object.


HrValidateIPMSubtree

 Copy code hover
[image]

HrValidateIPMSubtree
See also Send feedback

Published: July 16, 2012

Adds standard interpersonal message (IPM) folders to a message store.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
HrValidateIPMSubtree(
  LPMDB lpMDB,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppProps,
  LPMAPIERROR FAR * lppMapiError
);

Parameters

lpMDB

[in] Pointer to the message store object to which to add the folders.

ulFlags

[in] Bitmask of flags used to control how the folders are created. The following flags can be set:

MAPI_FORCE_CREATE

The folders should be verified before creation, even if message store properties indicate that they are valid. A client application typically sets this flag when an error indicates that the structure of an existing folder has been damaged.

MAPI_FULL_IPM_TREE

The full set of IPM folders should be created in the message store's root folder. The folder titles in the hierarchy are:

  • Folder Views

  • Common Views

  • Search Root*

  • IPM Subtree*

  • Inbox

  • Outbox

  • Deleted Items*

  • Sent Items

where the three folders marked with * are the minimum set created even when the MAPI_FULL_IPM_TREE flag has not been set. A client application typically sets this flag when the message store in which the folders are to be created is the default store.

lpcValues

[in, out] Pointer to the number of SPropValue structures in the array returned in the lppProps parameter. The value of the lpcValues parameter can be zero if lppProps is NULL.

lppProps

[in, out] Pointer to a pointer to an array of SPropValue structures that contains property values for the PR_VALID_FOLDER_MASK (PidTagValidFolderMask) property and for the appropriate folder entry identifier properties. If HrValidateIPMSubtree creates an Inbox in the message store, the SPropValue array includes an Inbox entry identifier with a special property tag coded as PROP_TAG(PT_BINARY, PROP_ID_NULL). The lppProps parameter can be NULL, indicating that the calling implementation does not require that an SPropValue array be returned.

lppMapiError

[out] Pointer to a pointer to a MAPIERROR structure that contains version, component, and context information for an error. The lppMAPIError parameter is set to NULL if no MAPIERROR structure is returned.

Return value

None.

Remarks

MAPI uses the HrValidateIPMSubtree function internally to construct the standard IPM subtree in a message store when the store is first opened, or when a store is made the default store. This function can also be used by client applications to validate or repair standard message folders.

HrValidateIPMSubtree always creates the Search Root and IPM Subtree folders in the store's root folder and the Deleted Items folder in the IPM Subtree folder. The IPM Subtree folder is the root of the IPM hierarchy in that message store. The Search Root folder can be used as the root of a subtree for search-results folders.

IPM clients should display their folder view starting at the IPM subtree root folder and showing child folders beneath it. Information in the root folder of a message store should not appear in a client's user interface. This functionality means that if a client must hide information, the information can be put in the IPM subtree root directory, where it is not visible to the user. In contrast, non-IPM applications that require messages and folders to be invisible to the user, for example in a server-based message store, can put them outside the IPM hierarchy.

HrValidateIPMSubtree sets the PR_VALID_FOLDER_MASK property to indicate whether each IPM folder it creates has a valid entry identifier. The following entry identifier properties of the message store are set to the entry identifiers of the corresponding folders and returned in the lppProps parameter along with PR_VALID_FOLDER_MASK:

PR_COMMON_VIEWS_ENTRYID (PidTagCommonViewsEntryId)
PR_FINDER_ENTRYID (PidTagFinderEntryId)
PR_IPM_OUTBOX_ENTRYID (PidTagIpmOutboxEntryId)
PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId)
PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId)
PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId)
PR_VIEWS_ENTRYID (PidTagViewsEntryId)

A placeholder PROP_TAG for the IPM Inbox (PT_BINARY, PROP_ID_NULL).

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MstStoreDlg.cpp | CMsgStoreDlg::OnValidateIPMSubtree | MFCMAPI uses the HrValidateIPMSubtree method to add standard folders to a message store.

See also

Reference

IMAPISession::OpenMsgStore

Concepts

MFCMAPI as a Code Sample


IsBadBoundedStringPtr

 Copy code hover
[image]

IsBadBoundedStringPtr
See also Send feedback

Published: July 16, 2012

Verifies that the calling process has read access to the specified range of memory.

Header file: | mapiwin.h
Implemented by: | MAPI
Called by: | Client applications and service providers.
C++
BOOL IsBadBoundedStringPtr(
  const void FAR* lpsz,
  UINT cchMax
);

Parameters

lpsz

[in] Pointer to a null-terminated ASCII string.

cchMax

[in] The maximum size of the string, in CHARs. The function checks for read access in all characters up to the terminating null character of the string, or up to the number of characters specified by this parameter, whichever is smaller. If this parameter is zero, the return value is zero.

Return value

The return value is zero when the calling process has read access to all characters up to the terminating null character of the string, or read access up to the number of characters specified by cchMax.

The return value is non-zero when the calling process does not have read access to all characters up to the terminating null character of the string, or read access up to the number of characters specified by cchMax.

Remarks

The IsBadBoundedStringPtr function is equivalent to using IsBadStringPtr.

See also

Other resources

IsBadStringPtr


LAUNCHWIZARDENTRY

 Copy code hover
[image]

LAUNCHWIZARDENTRY
Send feedback

Published: July 16, 2012

Defines a function that starts the Profile Wizard application for the purpose of adding one or more message services to a profile.

Header file: | Mapiwz.h
Defined function implemented by: | MAPI
Defined function called by: | Client applications
C++
HRESULT LAUNCHWIZARDENTRY(
  HWND hParentWnd,
  ULONG ulFlags,
  LPCSTR FAR * lppszServiceNameToAdd,
  ULONG cbBufferMax,
  LPSTR lpszNewProfileName
);

Parameters

hParentWnd

[in] A handle to the caller's parent window. If the caller does not have a parent window, the hParentWnd parameter should be NULL.

ulFlags

[in] Bitmask of flags indicating options for the Profile Wizard. The following flags can be set:

MAPI_PW_ADD_SERVICE_ONLY

The Profile Wizard is to add only the message services listed through the lppszServiceNameToAdd parameter, and not display its page for selecting message services.

MAPI_PW_FIRST_PROFILE

The profile to be created is the first one for this workstation.

MAPI_PW_HIDE_SERVICES_LIST

The Profile Wizard's page for selecting message services should not be displayed.

MAPI_PW_LAUNCHED_BY_CONFIG

The Profile Wizard was launched by the Control Panel configuration application.

MAPI_PW_PROVIDER_UI_ONLY

Only the service providers's configuration dialog boxes should be displayed and the Profile Wizard's pages should not appear. This flag can only be set if the MAPI_PW_ADD_SERVICE_ONLY flag is set.

lppszServiceNameToAdd

[in] Pointer to an array of strings that contains the names of the message services to be added to the profile. The array must terminate with a NULL value.

cbBufferMax

[in] Size of the buffer pointed to by the lpszNewProfileName parameter.

lpszNewProfileName

[out] Pointer to a string buffer where the function based on LAUNCHWIZARDENTRY returns the name of the created profile.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing. Possibilities include failure to initialize the MAPI subsystem for the Profile Wizard, inability to access the default profile, and an error return from the dialog box.

Remarks

The MAPI implementation of the LAUNCHWIZARDENTRY function prototype is the entry point into the MAPI Profile Wizard application. MAPI names this entry point LaunchWizard.

When the MAPI_PW_ADD_SERVICE_ONLY flag is set in the ulFlags parameter, the following rules apply:

  • The MAPI_PW_LAUNCHED_BY_CONFIG flag inhibits the welcome page from being displayed.

  • The MAPI_PW_HIDE_SERVICES_LIST and MAPI_PW_PROVIDER_UI_ONLY flags are useful only when there is no default profile. In this case these flags determine which Profile Wizard page is to be displayed.

  • If a default profile exists, none of the Profile Wizard pages are to be displayed.

  • If a default profile exists, only one message service is listed through the lppszServiceNameToAdd parameter, and that message service is already in the default profile, the Profile Wizard returns S_OK without adding anything to the profile.

For every message service to be added to the profile, the Profile Wizard calls the service's entry point function based on the MSGSERVICEENTRY prototype. For each service provider selected from a message service to be added to the profile, the Profile Wizard calls the provider's entry point function based on the WIZARDENTRY prototype. During interactive configuration, every user event in the property pages causes the Profile Wizard to call the provider's callback function based on the SERVICEWIZARDDLGPROC prototype.

If a service provider being added to the profile supports the Profile Wizard pages, it must allow programmatic configuration of the profile.


LPFNBUTTON

 Copy code hover
[image]

LPFNBUTTON
See also Send feedback

Published: July 16, 2012

Defines a callback function that MAPI calls to activate an optional button control in an address book dialog box. This button is typically a Details button.

Header file: | Mapidefs.h
Defined function implemented by: | Service providers
Defined function called by: | MAPI
C++
SCODE (STDMETHODCALLTYPE FAR * LPFNBUTTON)(
  ULONG_PTR ulUIParam,
  LPVOID lpvContext,
  ULONG cbEntryID,
  LPENTRYID lpSelection,
  ULONG ulFlags
);

Parameters

ulUIParam

[in] Handle of the parent windows for any dialog boxes or windows this function displays.

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application. Typically, for C++ code, lpvContext represents a pointer to a C++ object.

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpSelection parameter.

lpSelection

[in] Pointer to the entry identifier defining the selection in the dialog box.

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Client applications call a callback function based on the LPFNBUTTON prototype to define a button in a details dialog box. The client passes a pointer to the callback function in calls to the IAddrBook::Details method.

Service providers call a hook function based on the LPFNBUTTON prototype to define a button in a details dialog box. The provider passes a pointer to this hook function in calls to the IMAPISupport::Details method.

In both cases, when the dialog box is displayed and the user chooses the defined button, MAPI calls LPFNBUTTON.

See also

Reference

BuildDisplayTable


LPropCompareProp

 Copy code hover
[image]

LPropCompareProp
Send feedback

Published: July 16, 2012

Compares two property values to determine whether they are equal.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LONG LPropCompareProp(
  LPSPropValue lpSPropValueA,
  LPSPropValue lpSPropValueB
);

Parameters

lpSPropValueA

[in] Pointer to an SPropValue structure defining the first property value to be compared.

lpSPropValueB

[in] Pointer to an SPropValue structure defining the second property value to be compared.

Return value

LPropCompareProp returns one of the following values for most property types:

  • Less than zero if the value indicated by the lpSPropValueA parameter is less than that indicated by the lpSPropValueB parameter.

  • Greater than zero if the value indicated by lpSPropValueA is greater than that indicated by lpSPropValueB.

  • Zero if the value indicated by lpSPropValueA equals the value indicated by lpSPropValueB.

For property types that have no intrinsic ordering, such as Boolean or error types, the LPropCompareProp function returns an undefined value if the two property values are not equal. This undefined value is nonzero and consistent across calls.

Remarks

Use the LPropCompareProp function only if the types of the two properties to be compared are the same.

Before calling LPropCompareProp, a client application or service provider must first retrieve the properties for comparison with a call to the IMAPIProp::GetProps method. When a client or provider calls LPropCompareProp, the function first examines the property tags to make sure that the comparison of property values is valid. The function then compares the property values, returning an appropriate value.

If the property values are unequal, LPropCompareProp determines which one is the greater. The properties that LPropCompareProp compares do not have to belong to the same object.


LpValFindProp

 Copy code hover
[image]

LpValFindProp
See also Send feedback

Published: July 16, 2012

Searches for a specified property in a property set.

Header file: | mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers.
C++
LPSPropValue LpValFindProp(
  ULONG ulPropTag,
  ULONG cValues,
  LPSPropValue lpPropArray
);

Parameters

ulPropTag

[in] Tag for the property to search for in the property set, indicated by the lpPropArray parameter.

cValues

[in] Count of properties in the property set, indicated by the lpPropArray parameter.

lpPropArray

[in] Array of SPropValue structures that defines the properties to be searched.

Return value

The LpValFindProp function returns an SPropValue structure that defines the property that matches the input property tag, or NULL if there is no match.

Remarks

The LpValFindProp function is identical to PpropFindProp.

See also

Reference

PpropFindProp
SPropValue


MAPIAdminProfiles

 Copy code hover
[image]

MAPIAdminProfiles
See also Send feedback

Published: July 16, 2012

Creates a profile administration object.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications
C++
HRESULT MAPIAdminProfiles(
  ULONG ulFlags,
  LPPROFADMIN FAR * lppProfAdmin
);

Parameters

ulFlags

[in] Bitmask of flags indicating options for the service entry function.

lppProfAdmin

[out] Pointer to a pointer to the new profile administration object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIObjects.cpp | CMapiObjects::GetProfAdmin | MFCMAPI uses the MAPIAdminProfiles method to get the profile administration object.

See also

Reference

IProfAdmin::CreateProfile

Concepts

MFCMAPI as a Code Sample


MAPIAllocateBuffer

 Copy code hover
[image]

MAPIAllocateBuffer
See also Send feedback

Published: July 16, 2012

Allocates a memory buffer.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE MAPIAllocateBuffer(
  ULONG cbSize,
  LPVOID FAR * lppBuffer
);

Parameters

cbSize

[in] Size, in bytes, of the buffer to be allocated.

lppBuffer

[out] Pointer to the returned allocated buffer.

Return value

S_OK

The call succeeded and has returned the requested memory buffer.

Remarks

During MAPIAllocateBuffer call processing, the calling implementation acquires a block of memory from the operating system. The memory buffer is allocated on an even-numbered byte address. On platforms where long integer access is more efficient, the operating system allocates the buffer on an address whose size in bytes is a multiple of four.

Calling the MAPIFreeBuffer function releases the memory buffer allocated by MAPIAllocateBuffer, by calling the MAPIAllocateMore function and any buffers linked to it, when the memory is no longer needed.

See also

Reference

MAPIReallocateBuffer


MAPIAllocateMore

 Copy code hover
[image]

MAPIAllocateMore
Send feedback

Published: July 16, 2012

Allocates a memory buffer that is linked to another buffer previously allocated with the MAPIAllocateBuffer function.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE MAPIAllocateMore(
  ULONG cbSize,
  LPVOID lpObject,
  LPVOID FAR * lppBuffer
);

Parameters

cbSize

[in] Size, in bytes, of the new buffer to be allocated.

lpObject

[in] Pointer to an existing MAPI buffer allocated using MAPIAllocateBuffer.

lppBuffer

[out] Pointer to the returned, newly allocated buffer.

Return value

S_OK

The call succeeded and has returned a pointer to the requested memory.

Remarks

During MAPIAllocateMore call processing, the calling implementation acquires a block of memory from the operating system. The memory buffer is allocated on an even-numbered byte address. On platforms where long integer access is more efficient, the operating system allocates the buffer on an address whose size in bytes is a multiple of four.

The only way to release a buffer allocated with MAPIAllocateMore is to pass the buffer pointer specified in the lpObject parameter to the MAPIFreeBuffer function. The link between the memory buffers allocated with MAPIAllocateBuffer and MAPIAllocateMore enables MAPIFreeBuffer to release both buffers with a single call.


MAPICrashRecovery

 Copy code hover
[image]

MAPICrashRecovery
See also Send feedback

Published: July 16, 2012

The MAPICrashRecovery function checks the state of the Personal Folders file (PST) or Offline Folders file (OST) shared memory. If the memory is in a consistent state, the MAPICrashRecovery function moves the data to disk and prevents further read or write access until the process is terminated.

Quick Info

Exported by: | olmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
void MAPICrashRecovery(ULONG ulFlags);

Parameters

ulFlags

[in] Flags used to control how the MAPI crash recovery is performed. The following flags can be set:

  • MAPICRASH_RECOVER

    • If the PSTs or OSTs are in a consistent state, move the data to disk and lock the PSTs or OSTs to prevent read or write access.

  • MAPICRASH_CONTINUE

    • Unlock the PSTs or OSTs for debugging. After a successful call to MAPICrashRecovery with the MAPICRASH_RECOVER flag, call MAPICrashRecovery with the MAPICRASH_CONTINUE flag to allow debugging to continue.

  • MAPICRASH_SYSTEM_SHUTDOWN

    • If the PSTs or OSTs are in a consistent state, move the data to disk and lock the PSTs or OSTs to prevent read or write access. The PSTs or OSTs cannot be unlocked using MAPICRASH_CONTINUE. Must be used in combination with MAPICRASH_RECOVER.

Remarks

The upper byte (0xFF000000) is reserved for provider specific crash recovery flags.

Call MAPICrashRecovery with the MAPICRASH_RECOVER and MAPICRASH_SYSTEM_SHUTDOWN flags in response to the WM_ENDSESSION message.

See also

Concepts

About the MAPI Crash Recovery API
How to: Use the MAPI Crash Recovery API


MAPIDeInitIdle

 Copy code hover
[image]

MAPIDeInitIdle
Send feedback

Published: July 16, 2012

Shuts down the MAPI idle engine for the calling application.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
void MAPIDeInitIdle( void );

Parameters

None.

Return value

None.

Remarks

A client application or service provider should call MAPIDeInitIdle when it no longer needs the idle engine, for example, when it is about to stop processing.

Every call to MAPIInitIdle must be matched by a subsequent call to MAPIDeInitIdle, or the idle engine is left running for the calling application.

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.


MAPIFreeBuffer

 Copy code hover
[image]

MAPIFreeBuffer
See also Send feedback

Published: July 16, 2012

Frees a memory buffer allocated with a call to the MAPIAllocateBuffer function or the MAPIAllocateMore function.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
ULONG MAPIFreeBuffer(
  LPVOID lpBuffer
);

Parameters

lpBuffer

[in] Pointer to a previously allocated memory buffer. If NULL is passed in the lpBuffer parameter, MAPIFreeBuffer does nothing.

Return value

S_OK

The call succeeded and freed the memory requested. MAPIFreeBuffer can also return S_OK on already freed locations or if memory block is not allocated with MAPIAllocateBuffer and MAPIAllocateMore.

Remarks

Usually, when a client application or service provider calls MAPIAllocateBuffer or MAPIAllocateMore, the operating system constructs in one contiguous memory buffer one or more complex structures with multiple levels of pointers. When a MAPI function or method creates a buffer with such contents, a client can later free all the structures contained in the buffer by passing to MAPIFreeBuffer the pointer to the buffer returned by the MAPI function that created the buffer. For a service provider to free a memory buffer using MAPIFreeBuffer, it must pass the pointer to that buffer returned with the provider's support object.

The call to MAPIFreeBuffer to free a particular buffer must be made as soon as a client or provider is finished using this buffer. Simply calling the IMAPISession::Logoff method at the end of a MAPI session does not automatically release memory buffers.

A client or service provider should operate on the assumption that the pointer passed in lpBuffer is invalid after a successful return from MAPIFreeBuffer. If the pointer indicates either a memory block not allocated by the messaging system through MAPIAllocateBuffer or MAPIAllocateMore or a free memory block, the behavior of MAPIFreeBuffer is undefined.

Note Note

Passing a null pointer to MAPIFreeBuffer makes application cleanup code simpler and smaller because MAPIFreeBuffer can initialize pointers to NULL and then free them in the cleanup code without having to test them first.

See also

Reference

IMAPISupport::GetMemAllocRoutines


MAPIGetDefaultMalloc

 Copy code hover
[image]

MAPIGetDefaultMalloc
Send feedback

Published: July 16, 2012

Retrieves the address of the default MAPI memory allocation function.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LPMALLOC MAPIGetDefaultMalloc( );

Parameters

None.

Return value

The MAPIGetDefaultMalloc function returns a pointer to the default MAPI memory allocation function.


MAPIInitialize

 Copy code hover
[image]

MAPIInitialize
See also Send feedback

Published: July 16, 2012

Increments the MAPI subsystem reference count and initializes global data for the MAPI DLL.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications
C++
HRESULT MAPIInitialize(
  LPVOID lpMapiInit
);

Parameters

lpMapiInit

[in] Pointer to a MAPIINIT_0 structure. The lpMapiInit parameter can be set to NULL.

Return value

S_OK

The MAPI subsystem was initialized successfully.

Remarks

The MAPIInitialize function increments the MAPI reference count for the MAPI subsystem, and the MAPIUninitialize function decrements the internal reference count. Thus, the number of calls to one function must equal the number of calls to the other. MAPIInitialize returns S_OK if MAPI has not been previously initialized.

A client or service provider must call MAPIInitialize before making any other MAPI call. Failure to do so causes client or service provider calls to return the MAPI_E_NOT_INITIALIZED value.

When calling MAPIInitialize from a multithreaded application, set the lpMapiInit parameter to a MAPIINIT_0 structure that is declared as follows:

MAPIINIT_0 MAPIINIT= { 0, MAPI_MULTITHREAD_NOTIFICATIONS}

and call:

MAPIInitialize (&MAPIINIT);

When this structure is declared, MAPI creates a separate thread to handle the notification window, which continues until the initialize reference count falls to zero. A Windows service must set the ulflags member of the MAPIINIT_0 structure pointed to by lpMapiInit to MAPI_NT_SERVICE.

Note Note

You cannot call MAPIInitialize or MAPIUninitialize from within a Win32 DllMain function or any other function that creates or terminates threads. For more information, see Using Thread-Safe Objects.

MAPIInitialize does not return any extended error information. Unlike most other MAPI calls, the meanings of its return values are strictly defined to correspond to the particular step of the initialization that failed:

  1. Checks parameters and flags.

    MAPI_E_INVALID_PARAMETER or MAPI_E_UNKNOWN_FLAGS. Caller passed invalid parameter or flag.

  2. Initializes registry keys required by MAPI and confirms the type of operating system. This step only happens if the client process is running as a service under Windows and sets the MAPI_NT SERVICE flag in the MAPIINIT_0 structure.

    MAPI_E_TOO_COMPLEX. The calling process is a Windows service and registry keys required by MAPI could not be initialized.

    Additional information may be available in the application event log.

  3. Check for the compatibility of MAPI with OLE, then initialize OLE.

    1. Checks for compatibility between the current versions of OLE and MAPI.

      MAPI_E_VERSION. The version of OLE installed on the workstation is not compatible with this version of MAPI.

    2. Initializes OLE.

      During this step only, this function can return an error code not listed here. Any error not listed here should be assumed to come from the OLE function CoInitialize.

  4. Initializes per-process global variables.

    MAPI_E_SESSION_LIMIT. MAPI sets up context specific to the current process. Failures may occur on Win16 if the number of processes exceeds a certain number, or on any system if available memory is exhausted.

  5. Initializes shared global variables of all processes.

    MAPI_E_NOT_ENOUGH_RESOURCES. Not enough system resources were available to complete the operation.

  6. Initializes the notification engine, creates its window and its thread if requested by the MAPI_MULTITHREAD_NOTIFICATIONS flag.

    MAPI_E_INVALID_OBJECT. May fail if system resources are exhausted.

  7. Loads and initializes the profile provider. Verifies that MAPIInitialize can access the registry key where profile data are stored.

    MAPI_E_NOT_INITIALIZED. The profile provider has encountered an error.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp |  | MFCMAPI uses the MAPIInitialize method to initialize MAPI on a background thread to do some table processing.

See also

Concepts

MFCMAPI as a Code Sample


MAPIInitIdle

 Copy code hover
[image]

MAPIInitIdle
Send feedback

Published: July 16, 2012

Initializes the MAPI idle engine for the calling application.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LONG MAPIInitIdle(
  LPVOID lpvReserved
);

Parameters

lpvReserved

[in] Reserved; must be zero.

Return value

The MAPIInitIdle function returns zero if initialization is successful, and 1 otherwise. If MAPIInitIdle is called multiple times, all additional calls succeed but are ignored except to increment the reference count.

Remarks

A client application or service provider must call MAPIInitIdle before calling any other idle engine function.

Every call to MAPIInitIdle must be matched by a subsequent call to MAPIDeInitIdle, or the idle engine is left running for the calling application.

The following functions deal with the MAPI idle engine and with idle routines based on the FNIDLE function prototype:

Idle routine function | Usage
ChangeIdleRoutine | Changes the characteristics of a registered idle routine.
DeregisterIdleRoutine | Removes a registered idle routine from the MAPI system.
EnableIdleRoutine | Disables or re-enables a registered idle routine without removing it from the MAPI system.
FtgRegisterIdleRoutine | Adds an idle routine to the MAPI system, with or without enabling it.
MAPIDeInitIdle | Shuts down the MAPI idle engine for the calling application.
MAPIInitIdle | Initializes the MAPI idle engine for the calling application.

When all foreground tasks for the platform become idle, the MAPI idle engine calls the highest priority idle routine that is ready to execute. There is no guarantee of calling order among idle routines of the same priority.


MAPILogonEx

 Copy code hover
[image]

MAPILogonEx
See also Send feedback

Published: July 16, 2012

Logs a client application on to a session with the messaging system.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications
C++
HRESULT MAPILogonEx(
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  LPSTR lpszPassword,
  FLAGS flFlags,
  LPMAPISESSION FAR * lppSession
);

Parameters

ulUIParam

[in] Handle to the window to which the logon dialog box is modal. If no dialog box appears during the call, the ulUIParam parameter is ignored. This parameter can be zero.

lpszProfileName

[in] Pointer to a string that contains the name of the profile to use when the user logs on. This string is limited to 64 characters.

lpszPassword

[in] Pointer to a string that contains the password of the profile. The lpszPassword parameter must be NULL.

flFlags

[in] Bitmask of flags used to control how logon is performed. The following flags can be set:

MAPI_ALLOW_OTHERS

The shared session should be returned, which allows later clients to obtain the session without providing any user credentials.

MAPI_BG_SESSION

Log on to a session and run any operations in the background. In general, if a client intends to do processing on a background thread or in a separate process in a manner that is unobtrusive to the foreground thread, it should call with the MAPI_BG_SESSION flag. A client application such as an indexing engine or opening a Personal Folders File (PST) for background type access are some examples of where to use MAPI_BG_SESSION.MAPILogonEx.

MAPI_EXPLICIT_PROFILE

The default profile should not be used and the user should be required to supply a profile.

MAPI_EXTENDED

Log on with extended capabilities. This flag should always be set.

MAPI_FORCE_DOWNLOAD

An attempt should be made to download all of the user's messages before returning. If the MAPI_FORCE_DOWNLOAD flag is not set, messages can be downloaded in the background after the call to MAPILogonEx returns.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user for logon information if required. When the MAPI_LOGON_UI flag is not set, the calling client does not display a logon dialog box and returns an error value if the user is not logged on.

MAPI_NEW_SESSION

An attempt should be made to create a new MAPI session instead of acquiring the shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogonEx uses an existing shared session even if the lpszprofileName parameter is not NULL.

MAPI_NO_MAIL

MAPI should not inform the MAPI spooler of the session's existence. The result is that no messages can be sent or received in the session except through a tightly coupled store and transport pair. A calling client sets this flag if it is acting as an agent, if configuration work must be done, or if the client is browsing the available message stores.

MAPI_NT_SERVICE

The caller is running as a Windows service. Callers that are not running as a Windows service should not set this flag; callers that are running as a service must set this flag.

MAPI_SERVICE_UI_ALWAYS

MAPILogonEx should display a configuration dialog box for each message service in the profile. The dialog boxes are displayed after the profile has been chosen but before any message service is logged on. The MAPI common dialog box for logon also contains a check box that requests the same operation.

MAPI_TIMEOUT_SHORT

The logon should fail if blocked for more than a few seconds.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPI_USE_DEFAULT

The messaging subsystem should substitute the profile name of the default profile for the lpszProfileName parameter. The MAPI_EXPLICIT_PROFILE flag is ignored unless lpszProfileName is NULL or empty.

lppSession

[out] Pointer to a pointer to the MAPI session interface.

Return value

S_OK

The logon succeeded.

MAPI_E_LOGON_FAILED

The logon was unsuccessful, either because one or more of the parameters to MAPILogonEx were invalid or because there were too many sessions open already.

MAPI_E_TIMEOUT

MAPI serializes all logons through a mutex. This is returned if the MAPI_TIMEOUT_SHORT flag was set and another thread held the mutex.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

MAPI client applications call the MAPILogonEx function to log on to a session with the messaging system. All strings that are passed in and returned to and from MAPI calls are null-terminated and must be specified in the current character set or code page of the calling client or provider's operating system.

The lpszProfileName parameter is ignored if there is an existing previous session that called MapiLogonEx with the MAPI_ALLOW_OTHERS flag set and if the flag MAPI_NEW_SESSION is not set. If the lpszProfileName parameter is NULL or points to an empty string, and the flFlags parameter includes the MAPI_LOGON_UI flag, the MAPILogonEx function generates a logon dialog box that has an empty field for the profile name.

When logging on to a specific profile, a client should pass the MAPI_NEW_SESSION flag into MAPILogonEx in addition to the profile name. Otherwise, if another client has established a shared session by logging on with MAPI_ALLOW_OTHERS, the client will be logged on to the shared session instead of to the profile requested.

The MAPI_EXPLICIT_PROFILE flag does not cause the default profile name to be used when lpszProfileName is NULL or empty unless the MAPI_USE_DEFAULT flag is also present.

The MAPI_NO_MAIL flag has several effects that cause the following when not using the MAPI spooler:

  • No messages can be sent or delivered by the MAPI spooler during this session. Only tightly coupled store and transport providers can send and deliver messages.

  • Server based stores might still send or deliver messages.

  • Messages sent or delivered by server based stores are not processed by any hook providers.

  • Per-message and per-recipient options for transports are not available.

  • The status table does not contain entries for transport providers, and any transport functionality dependent on status objects (such as configuration) is not available.

  • The message spooler row in the status table contains the STATUS_FAILURE value.

  • Piggybacked logons are allowed, but those logons do not cause the previous logon to receive status object updates.

A service should always log on using the MAPI_NO_MAIL flag.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MAPIObjects.cpp | CMapiObjects::MAPILogonEx | MFCMAPI uses the MAPILogonEx method to log on to MAPI.

See also

Reference

IMAPISession::GetMsgStoresTable
IMAPISession::OpenMsgStore

Concepts

MFCMAPI as a Code Sample


MAPIOFFLINE_AGGREGATEINFO

 Copy code hover
[image]

MAPIOFFLINE_AGGREGATEINFO
See also Send feedback

Published: July 16, 2012

The structure is used with HrCreateOfflineObj.

C++
typedef struct
{
  ULONG            ulSize;
  IUnknown*          pOuterObj;
  IUnknown*          pRefTrackRoot;
} MAPIOFFLINE_AGGREGATEINFO;

Members

ulSize

The size of the structure.

pOuterObj

A pointer to the IUnknown object onto which this object is being aggregated. This allows any QueryInterface calls to pass through to the created object.

pRefTrackRoot

Must be NULL.

See also

Reference

HrCreateOfflineObj
MAPIOFFLINE_CREATEINFO


MAPIOFFLINE_CREATEINFO

 Copy code hover
[image]

MAPIOFFLINE_CREATEINFO
See also Send feedback

Published: July 16, 2012

This structure is used with HrCreateOfflineObj.

C++
typedef struct
{
  ULONG      ulSize;
  ULONG      ulCreateFlags;
  LPCWSTR      pwszProfileName;
  ULONG      ulCapabilities;
  const GUID*      pGUID;
  const GUID*      pInstance;
  IMAPIOfflineMgr*    pParent;
  IUnknown*      pMAPISupport;
  MAPIOFFLINE_AGGREGATEINFO*  pAggregateInfo;
  MAPIOFFLINE_CONNECTINFO*  pConnectInfo;
} MAPIOFFLINE_CREATEINFO;

Members

ulSize

The size of structure.

ulCreateFlags

It must be 0.

pwszProfileName

The name of the profile.

ulCapabilities

A bit mask of the following capability flags.

MAPIOFFLINE_CAPABILITY_OFFLINE

The offline object is capable of going offline.

MAPIOFFLINE_CAPABILITY_ONLINE

The offline object is capable of going online.

pGUID

Pointer to a GUID that is used to uniquely identify this type of offline object from other offline objects. GUID_GlobalState refers to the global offline object that objects can use as a parent object.

pInstance

Pointer to GUID that uniquely identifies this offline object. It is used to disambiguate this offline objects from other objects.

pParent

Pointer to offline object that is the parent of this offline object and whose changes this offline object will inherit.

pMAPISupport

Identifies the MAPI support object that that will use this offline object. For example, if this offline object is used to keep track of a store's offline and online state, then this is the stores support object. However, if this is an offline object for an object with no support object then it can be NULL.

pAggregateInfo

A pointer to a MAPIOFFLINE_AGGREGATEINFO structure. For more information, see MAPIOFFLINE_AGGREGATEINFO.

pConnectInfo

Must be null.

See also

Reference

HrCreateOfflineObj
MAPIOFFLINE_AGGREGATEINFO


MAPIOpenFormMgr

 Copy code hover
[image]

MAPIOpenFormMgr
See also Send feedback

Published: July 16, 2012

Opens an IMAPIFormMgr interface on a form library provider object in the context of an existing session.

Header file: | Mapiform.h
Implemented by: | MAPI
Called by: | Client applications
C++
MAPIOpenFormMgr(
  LPMAPISESSION pSession,
  LPMAPIFORMMGR FAR * ppmgr
);

Parameters

pSession

[in] Pointer to the session in use by the client application.

ppmgr

[out] Pointer to the returned IMAPIFormMgr interface.

Return value

None.

Remarks

After a client application makes a call to the MAPIOpenFormMgr function, most subsequent forms-related interactions take place through the form library provider or an interface returned by the form library provider. The IMAPIFormMgr interface allows the client to work with message handlers and perform resolutions between message classes and form libraries.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp opens the form manager so a form can be selected. | CMainDlg::OnSelectForm | MFCMAPI uses the MAPIOpenFormMgr method to open the form manager so a form can be selected.

See also

Concepts

MFCMAPI as a Code Sample


MAPIOpenLocalFormContainer

 Copy code hover
[image]

MAPIOpenLocalFormContainer
See also Send feedback

Published: July 16, 2012

Returns an interface pointer to the local form library.

Header file: | Mapiform.h
Implemented by: | MAPI
Called by: | Client applications
C++
MAPIOpenLocalFormContainer(
  LPMAPIFORMCONTAINER FAR * ppfcnt
);

Parameters

ppfcnt

[out] Pointer to a pointer to the local form library interface.

Return value

None.

Remarks

The interface to which a pointer is returned can be used by third-party installation programs to install application-specific forms into the library without the program first having to log on to MAPI.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
MainDlg.cpp | CMainDlg::OnMAPIOpenLocalFormContainer | MFCMAPI uses the MAPIOpenLocalFormContainer method to open the local form container to render in a new window.

See also

Concepts

MFCMAPI as a Code Sample


MAPIReallocateBuffer

 Copy code hover
[image]

MAPIReallocateBuffer
See also Send feedback

Published: July 16, 2012

Reallocates a memory buffer. It is used with the MAPIAllocateBuffer function.

Header file: | omapix.h
Called by: | Client applications and service providers
C++
STDMETHODIMP_(SCODE) MAPIReallocateBuffer
(
LPVOID lpv,
ULONG ulSize,
LPVOID * lppv
);

Parameters

lpv

A pointer to the memory to be reallocated.

ulSize

The size, in bytes, of the buffer to be allocated.

lppv

A pointer to the returned allocated buffer.

Remarks

MAPIReallocateBuffer allocates a new block of memory of the requested size and copies the contents of the buffer that is passed into this new block of memory. If the block of memory that is passed contains internal pointers, the pointers do not change to match the new location.

See also

Reference

MAPIAllocateBuffer


MAPIUninitialize

 Copy code hover
[image]

MAPIUninitialize
Send feedback

Published: July 16, 2012

Decrements the reference count, cleans up, and deletes per-instance global data for the MAPI DLL.

Header file: | Mapix.h
Implemented by: | MAPI
Called by: | Client applications
C++
void MAPIUninitialize ( void );

Parameters

None

Return value

None.

Remarks

A client application calls the MAPIUninitialize function to end its interaction with MAPI, begun with a call to the MAPIInitialize function. After MAPIUninitialize is called, no other MAPI calls can be made by the client.

MAPIUninitialize decrements the reference count, and the corresponding MAPIInitialize function increments the reference count. Thus, the number of calls to one function must equal the number of calls to the other.

Note Note

You cannot call MAPIInitialize or MAPIUninitialize from within a Win32 DllMain function or any other function that creates or terminates threads. For more information, see Using Thread-Safe Objects.


MapStorageSCode

 Copy code hover
[image]

MapStorageSCode
Send feedback

Published: July 16, 2012

Maps an SCODE return value from an OLE storage object to an HRESULT type.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE MapStorageSCode(
  SCODE StgSCode
);

Parameters

StgSCode

[in] MAPI SCODE return value from an OLE storage object to be mapped to a HRESULT value.

Return value

S_OK

The call succeeded and returned the expected value.

MAPI_E_CALL_FAILED

The function cannot find a matching value.

Remarks

MAPI provides the MapStorageSCode function for the internal use of MAPI components that base their message implementations on the message DLL. Because these components open OLE storage themselves, they must be able to map error values returned for problems with OLE storage to an HRESULT value.

For more information, see Structured Storage.


MNLS_CompareStringW

 Copy code hover
[image]

MNLS_CompareStringW
See also Send feedback

Published: July 16, 2012

Compares two Unicode strings.

C++
int MNLS_CompareStringW (
  LCID lcid,
  DWORD dwFlags,
  LPCWSTR pstr1,
  int cch1,
  LPCWSTR pstr2,
  int cch2);

Parameters

lcid

[in] Locale identifier. For detailed definitions, see the Locale parameter of CompareString.

dwFlags

[in] Flags to ignore case and diacritics. For detailed definitions, see the dwCmpFlags parameter of CompareStringEx.

pstr1

[in] Pointer to the first Unicode string to compare.

cch1

[in] Length in characters of the first Unicode string, excluding the terminating null character. The application can supply a negative value if the string is null-terminated. In this case, the MNLS_CompareStringW function determines the length automatically.

pstr2

[in] Pointer to the second Unicode string to compare.

cch2

[in] Length in characters of the second Unicode string, excluding the terminating null character. The application can supply a negative value if the string is null-terminated. In this case, the function determines the length automatically.

Return value

Returns the values described for CompareStringEx.

Remarks

This function wraps CompareStringW. MNLS_CompareStringW takes the same parameters and has the same behavior as CompareStringW.

See also

Other resources

CompareStringW
CompareStringEx


MNLS_IsBadStringPtrW

 Copy code hover
[image]

MNLS_IsBadStringPtrW
Send feedback

Published: July 16, 2012

Verifies that a pointer to a wide string is valid.

C++
BOOL MNLS_IsBadStringPtrW(
  LPCWSTR lpsz,
  UINT ucchMax);

Parameters

lpsz

[in] A pointer to the wide character string.

ucchMax

[in] The maximum length of the string in characters including terminator.

Return value

Returns a Boolean that is true if the string is bad.

Remarks

This function wraps IsBadStringPtr. For more information, see IsBadStringPtr.


MNLS_lstrcmpW

 Copy code hover
[image]

MNLS_lstrcmpW
See also Send feedback

Published: July 16, 2012

Compares two Unicode strings.

C++
int MNLS_lstrcmpW(
  LPCWSTR lpString1,
  LPCWSTR lpString2);

Parameters

lpString1

[in] Pointer to the first Unicode string to compare.

lpString2

[in] Pointer to the second Unicode string to compare.

Return value

Returns the values described for an equivalent call to MNLS_CompareStringW except for CSTR_EQUAL.

Remarks

MNLS_lstrcmpW performs a comparison by calling MNLS_CompareStringW with a locale of GetUserDefaultLCID, 0 for flags, and -1 for cch1 and cch2.

See also

Other resources

GetUserDefaultLCID


MNLS_lstrcpyW

 Copy code hover
[image]

MNLS_lstrcpyW
See also Send feedback

Published: July 16, 2012

Copies a string to a buffer.

Caution note Caution

Do not use. Consider using StringCchCopy instead.

C++
LPWSTR MNLS_lstrcpyW(
 LPWSTR lpString1,
LPCWSTR lpString2);

Parameters

lpString1

[out] A buffer to receive the contents of the string pointed to by the lpString2 parameter.

lpString2

[in] The null-terminated string to be copied.

Return value

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL and lpString1 may not be null-terminated.

Remarks

This function wraps the lstrcpy function. For more information, see lstrcpy.

See also

Other resources

lstrcpy


MNLS_lstrlenW

 Copy code hover
[image]

MNLS_lstrlenW
See also Send feedback

Published: July 16, 2012

Determines the length of the specified Unicode string, excluding the terminating null character.

Tip Tip

Consider using StringCchLength instead.

C++
int MNLS_lstrlen(
  LPCWSTR lpsz);

Parameters

lpsz

[in] The null-terminated Unicode string to be checked.

Return value

The function returns an integer with the length of the string. It is a count of characters in the string, excluding the terminating null character. If lpsz is NULL, the function returns zero.

Remarks

This function wraps the lstrlen function. For more information, see lstrlen.

See also

Other resources

lstrlen
StringCchLength


MNLS_MultiByteToWideChar

 Copy code hover
[image]

MNLS_MultiByteToWideChar
Send feedback

Published: July 16, 2012

Similar to MultiByteToWideChar, which maps a character string to a UTF-16 (wide character) string. The character string is not necessarily from a multibyte character set.

C++
int MNLS_MultiByteToWideChar(
  UINT uCodePage,
  DWORD dwFlags,
  LPCSTR lpMultiByteStr,
  int cchMultiByte,
  LPWSTR lpWideCharStr,
  int cchWideChar);

Parameters

uCodePage

[in] Code page to use in performing the conversion.

dwFlags

[in] Flags indicating the conversion type.

lpMultiByteStr

[in] Pointer to the character string to convert.

cchMultiByte

[in] Size, in bytes, of the string indicated by the lpMultiByteStr parameter.

lpWideCharStr

[out] Optional. Pointer to a buffer that receives the converted string.

cchWideChar

[in] Size, in characters, of the buffer indicated by lpWideCharStr.

Return value

Returns the number of characters written to the buffer indicated by lpWideCharStr if successful.

Remarks

This function wraps the MultiByteToWideChar function. For more information, see MultiByteToWideChar.


MNLS_WideCharToMultiByte

 Copy code hover
[image]

MNLS_WideCharToMultiByte
See also Send feedback

Published: July 16, 2012

This function is similar to WideCharToMultiByte, which maps a UTF-16 (wide character) string to a new character string. The new character string is not necessarily from a multibyte character set.

C++
int MNLS_WideCharToMultiByte(
  UINT uCodePage,
  DWORD dwFlags,
  LPCWSTR lpWideCharStr,
  int cchWideChar,
  LPSTR lpMultiByteStr,
  int cchMultiByte,
  LPCSTR lpDefaultChar,
  BOOL FAR *lpfUsedDefaultChar);

Parameters

uCodePage

[in] Code page to use in performing the conversion.

dwFlags

[in] Flags indicating the conversion type.

lpWideCharStr

[in] Pointer to the Unicode string to convert.

cchWideChar

[in] Flags indicating the conversion type.

lpMultiByteStr

[out] Optional. Pointer to a buffer that receives the converted string.

cchMultiByte

[in] Size, in bytes, of the buffer indicated by lpMultiByteStr.

lpDefaultChar

[in] Optional. Pointer to the character to use if a character cannot be represented in the specified code page.

lpfUsedDefaultChar

[out] Optional. Pointer to a flag that indicates if the function has used a default character in the conversion.

Return value

Returns the number of bytes written to the buffer pointed to by lpMultiByteStr if successful.

Remarks

This function wraps the WideCharToMultiByte function. For more information, see WideCharToMultiByte.

See also

Other resources

WideCharToMultiByte


MSGCALLRELEASE

 Copy code hover
[image]

MSGCALLRELEASE
Send feedback

Published: July 16, 2012

Defines a callback function that can free an IStorage interface after the final release of an IMessage object built on top of it with the OpenIMsgOnIStg function.

Header file: | Imessage.h
Defined function implemented by: | Client applications and service providers
Defined function called by: | MAPI
C++
typedef void (STDAPICALLTYPE MSGCALLRELEASE)(
  ULONG  ulCallerData,
  LPMESSAGE  lpMessage );

Parameters

ulCallerData

[in] Contains calling application information about the IMessage interface.

lpMessage

[in] Pointer to the top-level message and attachments that have been released.

Return value

None.


MSGSERVICEENTRY

 Copy code hover
[image]

MSGSERVICEENTRY
Send feedback

Published: July 16, 2012

Defines a prototype for a message service entry point function to support message service configuration.

Header file: | Mapispi.h
Defined function implemented by: | Message services
Defined function called by: | MAPI
C++
HRESULT MSGSERVICEENTRY(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG ulContext,
  ULONG cValues,
  LPSPropValue lpProps,
  LPPROVIDERADMIN lpProviderAdmin,
  LPMAPIERROR FAR * lppMapiError
);

Parameters

hInstance

[in] Handle of the instance of the service providerDLL. The handle is typically used to retrieve resources.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message service may need to use this allocation method when working with certain interfaces such as IStream.

lpMAPISup

[in] Pointer to an IMAPISupport : IUnknown interface implementation.

ulUIParam

[in] An implementation-specific value used for passing user interface information to a function or zero. The ulUIParam parameter is the parent window handle for the configuration dialog box and is of type HWND (cast to a ULONG_PTR). A value of zero indicates that there is no parent window.

ulFlags

[in] Bitmask of flags indicating options for the service entry function. The following flags can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MSG_SERVICE_UI_READ_ONLY

The service's configuration user interface should display the current configuration but not allow the user to change it.

SERVICE_UI_ALLOWED

Permits a configuration dialog box to be displayed if necessary. When the SERVICE_UI_ALLOWED flag is set, the dialog box should be displayed only if the lpProps property value array is empty or does not contain a valid configuration. If SERVICE_UI_ALLOWED is not set, a dialog box might still be displayed if the SERVICE_UI_ALWAYS flag is set.

UI_CURRENT_PROVIDER_FIRST

Requests that the configuration dialog box for the active provider be displayed on top of other dialog boxes.

SERVICE_UI_ALWAYS

Requires the message service to display a configuration dialog box. If the SERVICE_UI_ALWAYS flag is not set, a configuration dialog box might still be displayed if the SERVICE_UI_ALLOWED flag is set and valid configuration information is not available from the lpProps property value array. Either SERVICE_UI_ALLOWED or SERVICE_UI_ALWAYS must be set to allow a user interface to be displayed.

ulContext

[in] The configuration operation that MAPI is currently performing. The ulContext parameter will contain one of the following values:

MSG_SERVICE_CONFIGURE

Changes to the service's configuration should be made in the profile. If the SERVICE_UI_ALWAYS flag is set, the service should display its configuration dialog box. The dialog box should also be displayed if the SERVICE_UI_ALLOWED flag is set and the lpProps parameter is empty or does not contain valid configuration data. If lpProps contains valid data, no dialog box should be displayed and the service should use this data for making the configuration change.

MSG_SERVICE_CREATE

The service is being added to a profile. If either the SERVICE_UI_ALWAYS or SERVICE_UI_ALLOWED flag is set, the service should display its configuration dialog box. If neither flag is set, the service should fail.

MSG_SERVICE_DELETE

The service is being removed from a profile. After receiving this event, the service should return S_OK.

MSG_SERVICE_INSTALL

The service has been installed to the user's workstation from a network, floppy disk, or other external medium. After receiving this event, the service usually returns S_OK.

MSG_SERVICE_PROVIDER_CREATE

Requests that the service create an additional instance of a provider. If the service supports this operation, it should call IProviderAdmin::CreateProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.

MSG_SERVICE_PROVIDER_DELETE

Requests that the service delete a provider instance. If the service supports this operation, it should call IProviderAdmin::DeleteProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.

MSG_SERVICE_UNINSTALL

The service is being removed. After receiving this event, the service can perform any cleanup tasks that should be done before the service ends and then return with a success value. If the user cancels the removal, the service should return MAPI_E_USER_CANCEL.

cValues

[in] Count of property values in the array pointed to by the lpProps parameter. The value of the cValues parameter is zero if MAPI is passing no property values.

lpProps

[in] Pointer to an optional array of SPropValue structures indicating values for provider-supported properties that the function will use in configuring the message service. The function only uses this parameter if the ulContext parameter is set to MSG_SERVICE_CONFIGURE. This parameter is commonly used to pass the path to a file for a file-based service, such as a personal address book service. If the MSG_SERVICE_CONFIGURE flag is not passed in the ulFlags parameter, the lpProps parameter must be zero.

lpProviderAdmin

[in] Pointer to an IProviderAdmin:IUnknown interface that the function can use to locate profile sections for a specific provider in the current message service.

lppMapiError

[out] Pointer to a MAPIERROR structure. The structure is allocated with the MAPIAllocateBuffer function. All members are optional, although most structures will contain a valid error message string in the lpszError member. If the lpszComponent or lpszError members of the structure are present, their memory must eventually be freed by a single call to MAPIFreeBuffer on the base structure.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNCONFIGURED

The service provider has not been configured.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

MAPI_E_NO_SUPPORT

The provider either does not support changes to its objects or does not support notification of changes.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

A function defined using the MSGSERVICEENTRY function prototype enables message services to configure themselves or to perform other service-specific actions. The function primarily furnishes a dialog box in which the user can change settings specific to the message service. It can also support programmatic configuration by using the property value array passed in the lpProps parameter. Programmatic configuration is optional unless the service supports the Profile Wizard, for which it is required.

MAPI calls this entry point from the Control Panel application or in response to a client application calling IMsgServiceAdmin::CreateMsgService or IMsgServiceAdmin::ConfigureMsgService.

MAPI places no restriction on the function name that a message service uses for the MSGSERVICEENTRY prototype but prefers the name ServiceEntry. There is no restriction on the ordinal for the function, and a single provider DLL can contain more than one function. However, only one of the functions can be named ServiceEntry.

A message service can use the BuildDisplayTable function and the IMAPISupport::DoConfigPropsheet method to simplify configuration dialog box implementation.

It is possible for a user to cancel a MSG_SERVICE_UNINSTALL operation. In this case, the ServiceEntry function should check with the user to verify that the service should not be removed and return MAPI_E_USER_CANCEL if the service remains installed.

A function based on the MSGSERVICEENTRY prototype returns one of the HRESULT values listed. MAPI forwards this value when responding to a client's call to IMsgServiceAdmin::ConfigureMsgService.

Message services that export a service entry function must include the PR_SERVICE_DLL_NAME (PidTagServiceDllName) and PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) properties in the message service section of MAPISVC.INF.


MSProviderInit

 Copy code hover
[image]

MSProviderInit
See also Send feedback

Published: July 16, 2012

Initializes a message store provider for operation.

Header file: | Mapispi.h
Implemented by: | Message store providers
Called by: | MAPI
C++
HRESULT MSProviderInit(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  ULONG ulMAPIVer,
  ULONG FAR * lpulProviderVer,
  LPMSPROVIDER FAR * lppMSProvider
);

Parameters

hInstance

[in] The instance of the message store provider's dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message store provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI uses. For the current version number, see the Mapispi.h header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this message store provider uses.

lppMSProvider

[out] Pointer to a pointer to the initialized message store provider object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function MSProviderInit to initialize a message store provider following a client logon.

Notes to Implementers

A message store provider must implement MSProviderInit as an entry point function in the provider's DLL. The implementation must be based on the MSPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines MSPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes MSProviderInit to follow the CDECL calling convention. An advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. Because the provider object contains context, MSProviderInit must return a different provider object in lppMSProvider for each initialization, even for multiple initializations in the same process.

The provider DLL should not be linked with Mapix.dll. Instead, it should use these pointers for memory allocation or deallocation.

The message store provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information about writing MSProviderInit, see Loading Message Store Providers. For more information about entry point functions, see Implementing a Service Provider Entry Point Function.

See also

Reference

ABProviderInit
IMSProvider : IUnknown
XPProviderInit


NOTIFCALLBACK

 Copy code hover
[image]

NOTIFCALLBACK
See also Send feedback

Published: July 16, 2012

Defines a callback function that MAPI calls to send an event notification. This callback function can only be used when wrapped in an advise sink object created by calling the HrAllocAdviseSink function.

Header file: | Mapidefs.h
Defined function implemented by: | Client applications and service providers
Defined function called by: | MAPI
C++
ULONG (STDAPICALLTYPE NOTIFCALLBACK)(
  LPVOID lpvContext,
  ULONG cNotification,
  LPNOTIFICATION lpNotifications
);

Parameters

lpvContext

[in] Pointer to an arbitrary value passed to the callback function when MAPI calls it. This value can represent an address of significance to the client application or service provider. Typically, for C++ code, the lpvContext parameter represents a pointer to a C++ object.

cNotification

[in] Count of event notifications in the array indicated by the lpNotifications parameter.

lpNotifications

[out] Pointer to the location where this function writes an array of NOTIFICATION structures that contains the event notifications.

Return value

The set of valid return values for the NOTIFCALLBACK function prototype depends on whether the function is implemented by a client application or a service provider. Clients should always return S_OK. Providers can return either S_OK or CALLBACK_DISCONTINUE.

Remarks

CALLBACK_DISCONTINUE is a valid return value for synchronous callback functions only; it requests that MAPI immediately stop processing the callbacks for this notification. When CALLBACK_DISCONTINUE is returned, MAPI sets the lpUlFlags parameter to NOTIFY_CANCELED when it returns from IMAPISupport::Notify.

The following are limitations on what a synchronous callback function can do:

  • It cannot cause another synchronous notification to be generated.

  • It cannot display a user interface.

See also

Reference

IMAPIAdviseSink::OnNotify


NSTServiceEntry

 Copy code hover
[image]

NSTServiceEntry
See also Send feedback

Published: July 16, 2012

Message service entry point function for a MAPI store provider to wrap a PST-based local store as an NST store.

Quick Info

Implemented by: | MAPI provider
Called by: | MAPI
Copy code Copy code
HRESULT NSTServiceEntry(
    HINSTANCE hInstance,
    LPMALLOC lpMalloc,
    LPMAPISUP lpMAPISup,
    ULONG ulUIParam,
    ULONG ulFlags,
    ULONG ulContext,
    ULONG cValues,
    LPSPropValue lpProps,
    LPPROVIDERADMIN lpProviderAdmin,
    LPMAPIERROR FAR * lppMapiError
);

Parameters

NSTServiceEntry uses the MSGSERVICEENTRY function prototype. For information on its parameters, see MSGSERVICEENTRY.

Return Values

For information on return values, see MSGSERVICEENTRY.

Remarks

When using GetProcAddress to look for the address of this function in msmapi32.dll, specify "NSTServiceEntry" as the procedure name.

To use the Replication API, a MAPI store provider must first open and wrap a PST-based local store by calling NSTServiceEntry. The provider can then use the major interfaces of the API, IOSTX and IPSTX, to carry out replication.

The following remarks apply to an NST store:

  • Do not store any information in the global profile section when implementing a MAPI provider that uses NSTServiceEntry. The global profile section is shared by many providers and data stored in this profile can be overwritten.

  • Only items with existing modification time stamps get their stamps updated when they are saved.

  • Conflict-checking does not occur automatically when items are saved.

  • Duplicate detection does not occur when items are saved.

  • The file representing the cached version of the server is appended with .NST.

  • To obtain a pointer to the global profile section, a message service calls IMAPISupport::OpenProfileSection in the support object using pbNSTGlobalProfileSectionGuid as defined below:

    Copy code Copy code
    #define  pbNSTGlobalProfileSectionGuid "\x85\xED\x14\x23\x9D\xF7\x42\x66\x8B\xF2\xFB\xD4\xA5\x21\x29\x41"

  • In this case, the support object of the message service should ensure that IMAPISupport::OpenProfileSection returns the profile section that is identified by the PR_SERVICE_UID property in the default profile section. To get this profile section, the support object can open the default profile section, retrieve PR_SERVICE_UID, and pass the result to IMAPISupport::OpenProfileSection to retrieve the correct global profile section. The support object in turn returns a pointer to this global profile section to the message service.

See also

Concepts

About the Replication API


OpenIMsgOnIStg

 Copy code hover
[image]

OpenIMsgOnIStg
See also Send feedback

Published: July 16, 2012

Builds a new IMessage object on top of an existing OLE IStorage object, to be used within a message session.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE OpenIMsgOnIStg(
  LPMSGSESS lpMsgSess,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  LPMALLOC lpmalloc,
  LPVOID lpMapiSup,
  LPSTORAGE lpStg,
  MSGCALLRELEASE FAR * lpfMsgCallRelease,
  ULONG ulCallerData,
  ULONG ulFlags,
  LPMESSAGE FAR * lppMsg
);

Parameters

lpMsgSess

[in] Pointer to a message session object within which the new IMessage-on-IStorage object is to be created.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The IMessage interface needs to use this allocation method when working with interfaces such as IStorage and IStream.

lpMapiSup

[in] Optional pointer to a MAPI support object that a service provider can use to call the methods of the IMAPISupport : IUnknown interface.

lpStg

[in, out] Pointer to an OLE IStorage object that is open and has read-only or read/write permission. Because IMessage does not support write-only access, OpenIMsgOnIStg does not accept a storage object opened in write-only mode.

lpfMsgCallRelease

[in] Optional pointer to a callback function based on the MSGCALLRELEASE prototype that MAPI is to call following the last release on the IMessage-on-IStorage object.

ulCallerData

[in] Caller data saved by MAPI with the IMessage-on-IStorage object and passed to the MSGCALLRELEASE based callback function. The data provides context about the IMessage object being released and the IStorage object on top of which it was built.

ulFlags

[in] Bitmask of flags used to control whether the OLE IStorage::Commit method is called when the client application or service provider calls the IMessage::SaveChanges method. The following flags can be set:

IMSG_NO_ISTG_COMMIT

The OLE method IStorage::Commit is not to be called when the client or provider calls SaveChanges.

MAPI_UNICODE

Enables creation of Unicode .msg files. The resulting IMessage file shows STORE_UNICODE_OK in its PR_STORE_SUPPORT_MASK and supports Unicode properties.

Note Note

The MAPI_UNICODE flag is only supported in this function on Outlook 2003 or higher.

lppMsg

[out] Pointer to a pointer to the opened IMessage object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

Property attributes can only be accessed on property objects, that is, objects implementing the IMAPIProp : IUnknown interface. To make MAPI properties available on an OLE structured storage object, OpenIMsgOnIStg builds an IMessage : IMAPIProp object on top of the OLE IStorage object. The property attributes on such objects can be set or altered with SetAttribIMsgOnIStg and retrieved with GetAttribIMsgOnIStg.

Notes to Callers

A message session should be opened with OpenIMsgSession before OpenIMsgOnIStg is called. Supplying a valid lpMsgSess parameter make sures that the new message is created within a message session so that it is closed when the session is closed. If lpMsgSess is NULL, the message is created independently of any message session. If the client application or service provider that created the message does not release it, as well as all its attachments and open tables, memory is leaked and may cause the application to terminate.

MAPI uses the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer pointers are optional when the OpenIMsgOnIStg function is called with a valid lpMapiSup parameter.

Because it is dealing with an underlying OLE object, MAPI also needs to use OLE memory allocation. For more information about OLE structured storage objects and OLE memory allocation, see the OLE Programmer's Reference.

If a valid value is supplied for lpMapiSup, IMessage supports the MAPI_DIALOG and ATTACH_DIALOG flags by calling the IMAPISupport::DoProgressDialog method to supply a progress user interface for the IMAPIProp::CopyTo and IMessage::DeleteAttach methods. Also, the IMessage::ModifyRecipients method attempts to convert short-term entry identifiers to long-term entry identifiers by calling the IMAPISupport::OpenAddressBook method and making calls on the resulting address book object. If NULL is passed for lpMapiSup, IMessage ignores MAPI_DIALOG and ATTACH_DIALOG and stores short-term entry identifiers without conversion.

The IStorage object pointed to by the lpStg parameter must be opened in either the STGM_READ or STGM_READWRITE mode. If the STGM_READWRITE mode is used, the STGM_TRANSACTED mode must also be set.

The callback function pointed to by the lpfMsgCallRelease parameter is optional; if provided, it should be based on the MSGCALLRELEASE function prototype. The IMessage interface calls it when the reference count of the IMessage-on-IStorage object is set to zero by the last call to its Release method. The callback function is commonly used to free the underlying IStorage interface. IMessage will not attempt to access the IStorage object pointed to by the lpStg parameter after making the callback.

Some clients or providers might write additional data to the IStorage object beyond what IMessage itself writes when its SaveChanges method is called. The client or provider can use the IMSG_NO_ISTG_COMMIT flag to prevent IMessage from calling the OLE IStorage::Commit method while processing a SaveChanges call; in this case the client or provider must itself commit the IStorage object when the additional data is written. To aid in this, the IMessage implementation guarantees to name all substorages it creates in the IStorage object starting with the string "__", that is, with two underscores. The client or provider can avoid name collisions by keeping its substorage names out of this namespace.

MAPI does not define the behavior of multiple open operations performed on a subobject of a message, such as an attachment, a stream, or an embedded message. MAPI currently allows a subobject that is already open to be opened once more, but MAPI performs the open operation by incrementing the reference count for the existing open object and returning it to the client or provider that called the IMessage::OpenAttach or IMAPIProp::OpenProperty method. This means the access requested for the first open operation on a subobject is the access provided for all subsequent open operations, regardless of the access requested by the operations.

The correct procedure for placing a message into an attachment is to call the IMAPIProp::OpenProperty method with an interface identifier of IID_IMessage. OpenProperty currently also supports creation of message attachments available directly on the OLE IStorage interface, that is, using the IID_IStorage interface identifier. IStorage access is supported to allow an easy way to put a Microsoft Word document into an attachment without converting it to or from the OLE IStream interface. However, IMessage may not behave predictably if OpenIMsgOnIStg is passed an IStorage pointer to the attachment data and then the objects are released in the wrong order.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | LoadMSGToMessage | MFCMAPI uses the OpenIMsgOnIStg method to open an IMessage interface on top of the .MSG file so that the file may be manipulated with MAPI.

See also

Concepts

MFCMAPI as a Code Sample


OpenIMsgSession

 Copy code hover
[image]

OpenIMsgSession
Send feedback

Published: July 16, 2012

Creates and opens a message session that groups the messages created within it.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE OpenIMsgSession(
  LPMALLOC lpMalloc,
  ULONG ulFlags,
  LPMSGSESS FAR * lppMsgSess
);

Parameters

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. MAPI needs to use this allocation method when working with the OLE IStorage interface.

ulFlags

[in] Reserved; must be zero.

lppMsgSess

[out] Pointer to a pointer to the returned message session object.

Return value

S_OK

The session was opened.

MAPI_E_INVALID_PARAMETER

lpMalloc or lppMsgSess is NULL.

MAPI_E_INVALID_FLAGS

Invalid flags were passed.

MAPI_UNICODE

When calling this function, a client or service provider sets the MAPI_UNICODE flag to create Unicode .msg files. The resulting Imessage file shows STORE_UNICODE_OK in its PR_STORE_SUPPORT_MASK and supports Unicode properties.

Remarks

A message session is used by client applications and service providers that want to deal with several related MAPI IMessage : IMAPIProp objects built on top of underlying OLE IStorage objects. The client or provider uses the OpenIMsgSession and CloseIMsgSession functions to wrap the creation of such messages inside a message session. Once the message session is opened, the client or provider passes a pointer to it in a call to OpenIMsgOnIStg to create a new IMessage-on-IStorage object.

A message session keeps track of all IMessage-on-IStorage objects created during the duration of the session, in addition to all the attachments and other properties of the messages. When a client or provider calls CloseIMsgSession, it closes all these objects. Calling CloseIMsgSession is the only way to close IMessage-on-IStorage objects.

OpenIMsgSession is used by clients and providers that require the ability to handle several related messages as OLE IStorage objects. If only one such message is to be open at a time, there is no need to track multiple messages and no reason to create a message session with OpenIMsgSession.

Because it is dealing with an underlying OLE object, MAPI needs to use OLE memory allocation. For more information about OLE structured storage objects and OLE memory allocation, see OLE and Data Transfer.


OpenStreamOnFile

 Copy code hover
[image]

OpenStreamOnFile
See also Send feedback

Published: July 16, 2012

Allocates and initializes an OLE IStream object to access the contents of a file. This function takes an ANSI string as the file name including the path and the file extension, therefore, use of the Unicode version of this function, OpenStreamOnFileW, is recommended.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
HRESULT STDMETHODCALLTYPE OpenStreamOnFile(
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  LPSTR lpszFileName,
  LPSTR lpszPrefix,
  LPSTREAM FAR * lppStream
);

Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

ulFlags

[in] Bitmask of flags used to control the creation or opening of the file to be accessed through the OLE IStream object. The following flags can be set:

SOF_UNIQUEFILENAME

A temporary file is to be created for the IStream object. If this flag is set, the STGM_CREATE and STGM_READWRITE flags should also be set.

STGM_CREATE

The file is to be created even if one already exists. If the lpszFileName parameter is not set, both this flag and STGM_DELETEONRELEASE must be set. If STGM_CREATE is set, the STGM_READWRITE flag must also be set.

STGM_DELETEONRELEASE

The file is to be deleted when the IStream object is released. If the lpszFileName parameter is not set, both this flag and STGM_CREATE must be set.

STGM_READ

The file is to be created or opened with read-only access.

STGM_READWRITE

The file is to be created or opened with read/write permission. If this flag is not set, the STGM_CREATE flag must not be set either.

lpszFileName

[in] The filename, including path and extension, of the file for which OpenStreamOnFile initializes the IStream object. If the SOF_UNIQUEFILENAME flag is set, lpszFileName contains the path to the directory in which to create a temporary file. If lpszFileName is NULL, OpenStreamOnFile obtains an appropriate path from the system, and both the STGM_CREATE and STGM_DELETEONRELEASE flags must be set.

lpszPrefix

[in] The prefix for the filename on which OpenStreamOnFile initializes the IStream object. If set, the prefix must contain not more than three characters. If lpszPrefix is NULL, a prefix of "SOF" is used.

lppStream

[out] Pointer to a pointer to an object exposing the IStream interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

The file could not be accessed due to insufficient user permissions or because read-only files cannot be modified.

MAPI_E_NOT_FOUND

The designated file does not exist.

Remarks

The OpenStreamOnFile function has two important uses, distinguished by the setting of the SOF_UNIQUEFILENAME flag. When this flag is not set, OpenStreamOnFile opens an IStream object on an existing file, for example to copy its contents to the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property of an attachment using the IStream::CopyTo method. In this case the lpszFileName parameter specifies the path and filename of the file.

When SOF_UNIQUEFILENAME is set, OpenStreamOnFile creates a temporary file to hold data for an IStream object. For this usage, the lpszFileName parameter can optionally designate the path to the directory where the file is to be created, and the lpszPrefix parameter can optionally specify a prefix for the filename.

When the calling client application or service provider is finished with the IStream object, it should free it by calling the OLE IStream::Release method.

MAPI uses the functions pointed to by lpAllocateBuffer and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

The SOF_UNIQUEFILENAME flag is used to create a temporary file with a name unique to the messaging system. If this flag is set, the lpszFileName parameter specifes the path for the temporary file, and the lpszPrefix parameter contains the prefix characters of the filename. The constructed filename is <prefix>HHHH.TMP, where HHHH is a hexadecimal number. If lpszFileName is NULL, the file will be created in the temporary file directory that is returned from the Windows function GetTempPath, or the current directory if no temporary file directory has been designated.

If the SOF_UNIQUEFILENAME flag is not set, lpszPrefix is ignored, and lpszFileName should contain the fully qualified path and filename of the file to be opened or created. The file will be opened or created based on the other flags that are set in ulFlags.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | WriteAttachStreamToFile | MFCMAPI uses the OpenStreamOnFile method to open a stream on a file so an attachment can be written out to it.

See also

Concepts

MFCMAPI as a Code Sample


OpenStreamOnFileW

 Copy code hover
[image]

OpenStreamOnFileW
See also Send feedback

Published: July 16, 2012

Allocates and initializes an OLE IStream object to access the contents of a file. This function takes UNICODE strings as arguments, unlike the ANSI version of this function OpenStreamOnFile, and thus allows for arbitrary characters in the file name including the path and file extension.

Exported by: | olmapi32.dll
Implemented by: | Outlook
Called by: | Client applications and service providers
C++
HRESULT STDMETHODCALLTYPE OpenStreamOnFileW(
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  LPWSTR lpszFileName,
  LPWSTR lpszPrefix,
  LPSTREAM FAR * lppStream
);

Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

ulFlags

[in] Bitmask of flags used to control the creation or opening of the file to be accessed through the OLE IStream object. The following flags can be set:

SOF_UNIQUEFILENAME

A temporary file is to be created for the IStream object. If this flag is set, the STGM_CREATE and STGM_READWRITE flags should also be set.

STGM_CREATE

The file is to be created even if one already exists. If the lpszFileName parameter is not set, both this flag and STGM_DELETEONRELEASE must be set. If STGM_CREATE is set, the STGM_READWRITE flag must also be set.

STGM_DELETEONRELEASE

The file is to be deleted when the IStream object is released. If the lpszFileName parameter is not set, both this flag and STGM_CREATE must be set.

STGM_READ

The file is to be created or opened with read-only access.

STGM_READWRITE

The file is to be created or opened with read/write permission. If this flag is not set, the STGM_CREATE flag must not be set either.

lpszFileName

[in] The filename, including path and extension, of the Unicode named file for which OpenStreamOnFileW initializes the IStream object. If the SOF_UNIQUEFILENAME flag is set, lpszFileName contains the path to the directory in which to create a temporary file. If lpszFileName is NULL, OpenStreamOnFileW obtains an appropriate path from the system, and both the STGM_CREATE and STGM_DELETEONRELEASE flags must be set.

lpszPrefix

[in] The prefix for the Unicode filename on which OpenStreamOnFileW initializes the IStream object. If set, the prefix must contain not more than three characters. If lpszPrefix is NULL, a prefix of "SOF" is used.

lppStream

[out] Pointer to a pointer to an object exposing the IStream interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

The file could not be accessed due to insufficient user permissions or because read-only files cannot be modified.

MAPI_E_NOT_FOUND

The designated file does not exist.

Remarks

The OpenStreamOnFileW function has two important uses in addition to handling a file with a Unicode name, distinguished by the setting of the SOF_UNIQUEFILENAME flag. When this flag is not set, OpenStreamOnFileW opens an IStream object on an existing file, for example to copy its contents to the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property of an attachment using the IStream::CopyTo method. In this case the lpszFileName parameter specifies the path and filename of the file.

When SOF_UNIQUEFILENAME is set, OpenStreamOnFileW creates a temporary file to hold data for an IStream object. For this usage, the lpszFileName parameter can optionally designate the path to the directory where the file is to be created, and the lpszPrefix parameter can optionally specify a prefix for the filename.

When the calling client application or service provider is finished with the IStream object, it should free it by calling the OLE IStream::Release method.

MAPI uses the functions pointed to by lpAllocateBuffer and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

The SOF_UNIQUEFILENAME flag is used to create a temporary file with a name unique to the messaging system. If this flag is set, the lpszFileName parameter specifes the path for the temporary file, and the lpszPrefix parameter contains the prefix characters of the filename. The constructed filename is <prefix>HHHH.TMP, where HHHH is a hexadecimal number. If lpszFileName is NULL, the file will be created in the temporary file directory that is returned from the Windows function GetTempPath, or the current directory if no temporary file directory has been designated.

If the SOF_UNIQUEFILENAME flag is not set, lpszPrefix is ignored, and lpszFileName should contain the fully qualified path and filename of the file to be opened or created. The file will be opened or created based on the other flags that are set in ulFlags.

See also

Reference

OpenStreamOnFile


OpenTnefStream

 Copy code hover
[image]

OpenTnefStream
See also Send feedback

Published: July 16, 2012

Called by a transport provider to initiate a MAPI Transport Neutral Encapsulation Format (TNEF) session.

Header file: | Tnef.h
Implemented by: | MAPI
Called by: | Transport providers
C++
HRESULT OpenTnefStream(
  LPVOID lpvSupport,
  LPSTREAM lpStream,
  LPSTR lpszStreamName,
  ULONG ulFlags,
  LPMESSAGE lpMessage,
  WORD wKey,
  LPITNEF FAR * lppTNEF
);

Parameters

lpvSupport

[in] Passes a support object, or passes in NULL.

lpStream

[in] Pointer to a storage stream object OLE IStream interface providing a source or destination for a TNEF stream message.

lpszStreamName

[in] Pointer to the name of the data stream that the TNEF object uses. If the caller has set the TNEF_ENCODE flag (ulFlags parameter) in its call to OpenTnefStream, the lpszName parameter must specify a non-null pointer to a non-null string consisting of any characters considered valid for naming a file. MAPI does not allow string names including the characters "[", "]", or ":", even if the file system permits their use. The size of the string passed for lpszName must not exceed the value of MAX_PATH, the maximum length of a string that contains a path name.

ulFlags

[in] Bitmask of flags used to indicate the mode of the function. The following flags can be set:

TNEF_BEST_DATA

All possible properties are mapped into their down-level attributes, but when there is a possible data loss due to the conversion to a down-level attribute, the property is also encoded in the encapsulations. Note that this will cause the duplication of information in the TNEF stream. TNEF_BEST_DATA is the default if no other modes are specified.

TNEF_COMPATIBILITY

Provides backward compatibility with the older client applications. TNEF streams encoded with this flag will map all possible properties into their corresponding down-level attribute. This mode also causes the defaulting of some properties that are required by down-level clients.

Caution note Caution

This flag is obsolete and should not be used.

TNEF_DECODE

The TNEF object on the indicated stream is opened with read-only access. The transport provider must set this flag if it wants the function to initialize the object for subsequent decoding.

TNEF_ENCODE

The TNEF object on the indicated stream is opened for read/write permission. The transport provider must set this flag if it wants the function to initialize the object for subsequent encoding.

TNEF_PURE

Encodes all properties into the MAPI encapsulation blocks. Therefore, a "pure" TNEF file will consist of, at most, attMAPIProps, attAttachment, attRenddata, and attRecipTable. This mode is ideal for use when no backward compatibility is required.

lpMessage

[in] Pointer to a message object as a destination for a decoded message with attachments or a source for an encoded message with attachments. Any properties of a destination message might be overwritten by the properties of an encoded message.

wKey

[in] A search key that the TNEF object uses to match attachments to the text tags inserted in the message text. This value should be relatively unique across messages.

lppTNEF

[out] Pointer to the new TNEF object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

A TNEF object created by the OpenTnefStream function later calls the OLE method IUnknown::AddRef to add references for the support object, the stream object, and the message object. The transport provider can release the references for all three objects with a single call to the OLE method IUnknown::Release on the TNEF object.

OpenTnefStream allocates and initializes a TNEF object ITnef interface for the provider to use in encoding a MAPI message IMessage interface into a TNEF stream message. Alternatively, the function can set up the object for the provider to use in subsequent calls to ITnef::ExtractProps to decode a TNEF stream message into a MAPI message. To free the TNEF object and close the session, the transport provider must call the inherited IUnknown::Release method on the object.

This function is the original entry point for TNEF access and has been replaced by OpenTnefStreamEx but is still used for compatibility for those already using TNEF.

See also

Reference

IMAPISupport : IUnknown
IXPProvider::TransportLogon


OpenTnefStreamEx

 Copy code hover
[image]

OpenTnefStreamEx
See also Send feedback

Published: July 16, 2012

Creates a Transport-Neutral Encapsulation Format (TNEF) object that can be used to encode or decode a message object into a TNEF data stream for use by transports or gateways and message stores. This is the entry point for TNEF access.

Header file: | Tnef.h
Implemented by: | MAPI
Called by: | Transport providers
C++
HRESULT OpenTnefStreamEx(
  LPVOID lpvSupport,
  LPSTREAM lpStream,
  LPSTR lpszStreamName,
  ULONG ulFlags,
  LPMESSAGE lpMessage,
  WORD wKeyVal,
  LPADDRESSBOOK lpAddressBook,
  LPITNEF FAR * lppTNEF
);

Parameters

lpvSupport

[in] Passes a support object, or passes in NULL. If NULL, the lpAddressBook parameter should be non-null.

lpStream

[in] Pointer to a storage stream object, such as an OLE IStream interface, providing a source or destination for a TNEF stream message.

lpszStreamName

[in] Pointer to the name of the data stream that the TNEF object uses. If the caller has set the TNEF_ENCODE flag (ulFlags parameter) in its call to OpenTnefStream, the lpszName parameter must specify a non-null pointer to a non-null string consisting of any characters considered valid for naming a file. MAPI does not allow string names including the characters "[", "]", or ":", even if the file system permits their use. The size of the string passed for the lpszName parameter must not exceed the value of MAX_PATH, the maximum length of a string that contains a path name.

ulFlags

[in] Bitmask of flags used to indicate the mode of the function. The following flags can be set:

TNEF_BEST_DATA

All possible properties are mapped into their down-level attributes, but when there is a possible data loss due to the conversion to a down-level attribute, the property is also encoded in the encapsulations. Note that this will cause the duplication of information in the TNEF stream. TNEF_BEST_DATA is the default if no other modes are specified.

TNEF_COMPATIBILITY

Provides backward compatibility with older client applications. TNEF streams encoded with this flag will map all possible properties into their corresponding down-level attribute. This mode also causes the defaulting of some properties that are required by down-level clients.

Caution note Caution

This flag is obsolete and should not be used.

TNEF_DECODE

The TNEF object on the indicated stream is opened with read-only access. The transport provider must set this flag if the function is to initialize the object for subsequent decoding.

TNEF_ENCODE

The TNEF object on the indicated stream is opened for read/write permission. The transport provider must set this flag if the function is to initialize the object for subsequent encoding.

TNEF_PURE

Encodes all properties into the MAPI encapsulation blocks. Therefore, a "pure" TNEF file will consist of, at most, the attributes attMAPIProps, attAttachment, attRenddata, and attRecipTable. This mode is ideal for use when no backward compatibility is required.

lpMessage

[in] Pointer to a message object as a destination for a decoded message with attachments or a source for an encoded message with attachments. Any properties of a destination message can be overwritten by the properties of an encoded message.

wKeyVal

[in] A search key that the TNEF object uses to match attachments to the text tags inserted in the message text. This value should be relatively unique across messages.

lpAddressBook

[in] Pointer to an address book object used to get addressing information for entry identifiers.

lppTNEF

[out] Pointer to the new TNEF object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The OpenTnefStreamEx function is the recommended replacement for OpenTnefStream, the original entry point for TNEF access.

A TNEF object created by the OpenTnefStreamEx function later calls the OLE method IUnknown::AddRef to add references for the support object, the stream object, and the message object. The transport provider can release the references for all three objects with a single call to the OLE method IUnknown::Release on the TNEF object.

OpenTnefStreamEx allocates and initializes a TNEF object for the provider to use in encoding a MAPI message into a TNEF stream message. Alternatively, this function can set up the object for the provider to use in subsequent calls to ITnef::ExtractProps to decode a TNEF stream message into a MAPI message. To free the TNEF object and close the session, the transport provider must call the inherited IUnknown::Release method on the object.

The base value for the wKeyVal parameter must not be zero and should not be the same for every call to OpenTnefStreamEx. Instead, use random numbers based on the system time from the run-time library's random number generator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
File.cpp | LoadFromTNEF | MFCMAPI uses the OpenTnefStreamEx method to open a stream on the TNEF file so properties may be extracted.

See also

Reference

IMAPISupport : IUnknown
IXPProvider::TransportLogon

Concepts

MFCMAPI as a Code Sample


PpropFindProp

 Copy code hover
[image]

PpropFindProp
See also Send feedback

Published: July 16, 2012

Searches for a specified property in a property set.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LPSPropValue PpropFindProp(
  LPSPropValue rgprop,
  ULONG cprop,
  ULONG ulPropTag
);

Parameters

rgprop

[in] Array of SPropValue structures that define the properties to be searched.

cprop

[in] Count of properties in the property set indicated by the rgprop parameter.

ulPropTag

[in] Property tag for the property to search for in the property set indicated by the rgprop parameter.

Return value

PpropFindProp returns an SPropValue structure defining the property that matches the input property tag, or NULL if there is no match.

Remarks

If the given property tag indicates a property of type PT_UNSPECIFIED, the PpropFindProp function finds a match only for the property identifier in the tag. Otherwise, it finds a match for the entire property tag, including the property type, and returns the property identified.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ContentsTableListCtrl.cpp | CContentsTableListCtrl::BuildDataItem | MFCMAPI uses the PpropFindProp method to find properties in a property set being added to the list.

See also

Concepts

MFCMAPI as a Code Sample


PreprocessMessage

 Copy code hover
[image]

PreprocessMessage
See also Send feedback

Published: July 16, 2012

Defines a function that preprocesses message contents or the format of a message.

Header file: | Mapispi.h
Defined function implemented by: | Transport providers
Defined function called by: | MAPI spooler
C++
HRESULT PreprocessMessage(
  LPVOID lpvSession,
  LPMESSAGE lpMessage,
  LPADRBOOK lpAdrBook,
  LPMAPIFOLDER lpFolder,
  LPALLOCATEBUFFER AllocateBuffer,
  LPALLOCATEMORE AllocateMore,
  LPFREEBUFFER FreeBuffer,
  ULONG FAR * lpcOutbound,
  LPMESSAGE FAR * FAR * lpppMessage,
  LPADRLIST FAR * lppRecipList
);

Parameters

lpvSession

[in] Pointer to the session to be used.

lpMessage

[in] Pointer to the message to be preprocessed.

lpAdrBook

[in] Pointer to the address book from which the user should select recipients for the message.

lpFolder

[in, out] Pointer to a folder. On input, the lpFolder parameter points to the folder that contains messages to be preprocessed. On output, lpFolder points to the folder where preprocessed messages have been placed.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpcOutbound

[out] Pointer to the number of messages in the array pointed to by the lpppMessage parameter.

lpppMessage

[out] Pointer to a pointer to an array of pointers to preprocessed or otherwise generated messages.

lppRecipList

[out] Pointer to an optional returned ADRLIST structure, listing preprocessor-detected recipients for which the message is undeliverable. For more information about the contents of this list, see the IMAPISupport::StatusRecips method.

Return value

S_OK

Message contents were successfully preprocessed.

Remarks

A transport-provider message preprocessor can present a progress indicator during message preprocessing. However, it should never present a dialog box requiring user interaction during message preprocessing.

When a preprocessor adds large amounts of data to an outbound message, certain procedures should be followed. This type of message can be stored in a server-based message store, causing the preprocessor to access a remote store, a time-consuming procedure. To avoid having to do so, the preprocessor should have an option that enables it to store data that takes a large amount of space in a local message store and to provide a reference to that local store in the message.

The preprocessor should not release any of the objects originally passed to the PreprocessMessage based function.

Before the MAPI spooler can call a PreprocessMessage function, the transport provider must have registered the function in a call to the IMAPISupport::RegisterPreprocessor method. After calling a PreprocessMessage function, the spooler cannot continue submitting a message until the function returns.

The MAPI spooler owns the task of submitting messages. This means the original message is never placed in an array of message pointers and that a call to the SubmitMessage methods is never required.

See also

Reference

IAddrBook : IMAPIProp
IMAPIFolder : IMAPIContainer
IMAPISupport : IUnknown


PropCopyMore

 Copy code hover
[image]

PropCopyMore
Send feedback

Published: July 16, 2012

Copies a single property value from a source location to a destination location.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE PropCopyMore(
  LPSPropValue lpSPropValueDest,
  LPSPropValue lpSPropValueSrc,
  ALLOCATEMORE * lpfAllocMore,
  LPVOID lpvObject
);

Parameters

lpSPropValueDest

[out] Pointer to the location to which this function writes an SPropValue structure defining the copied property value.

lpSPropValueSrc

[in] Pointer to the SPropValue structure that contains the property value to be copied.

lpfAllocMore

[in] Pointer to the MAPIAllocateMore function to be used to allocate additional memory if the destination location is not large enough to hold the property to be copied.

lpvObject

[in] Pointer to an object for which MAPIAllocateMore will allocate space if necessary.

Return value

S_OK

The single property value was copied successfully.

MAPI_E_NO_SUPPORT

An unknown property type was encountered.

Remarks

A client application or service provider can use the PropCopyMore function to copy a property out of a table that is about to be freed in order to use it elsewhere.

PropCopyMore does not need to allocate memory unless the property value copied is of a type, such as PT_STRING8, that does not fit in an SPropValue structure. For these large properties, the function allocates memory using the MAPIAllocateMore function to which a pointer is passed in the lpfAllocMore parameter.

Injudicious use of PropCopyMore fragments memory; consider using the ScCopyProps function instead.


RemovePreprocessInfo

 Copy code hover
[image]

RemovePreprocessInfo
Send feedback

Published: July 16, 2012

Removes preprocessed information written by a PreprocessMessage based function from a message.

Header file: | Mapispi.h
Defined function implemented by: | Transport providers
Defined function called by: | MAPI spooler
C++
HRESULT RemovePreprocessInfo(
  LPMESSAGE lpMessage
);

Parameters

lpMessage

[in] Pointer to the preprocessed message from which information is to be removed.

Return value

S_OK

Preprocessed information was removed successfully.

Remarks

The MAPI spooler calls a function based on RemovePreprocessInfo. A transport provider registers the RemovePreprocessInfo based function at the same time it registers the parallel PreprocessMessage based function in a call to the IMAPISupport::RegisterPreprocessor method.

An image rendering suitable for fax transmission is an example of preprocessed information written by a function defined by the PreprocessMessagefunction prototype. The MAPI spooler usually calls a RemovePreprocessInfo function after sending a message that contains preprocessed information.


RTFSync

 Copy code hover
[image]

RTFSync
See also Send feedback

Published: July 16, 2012

Makes sure that the Rich Text Format (RTF) message text matches the plain text version. It is necessary to call this function before reading the RTF version and after modifying the RTF version.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | RTF-aware client applications and message store providers
C++
HRESULT RTFSync(
  LPMESSAGE lpMessage,
  ULONG ulFlags,
  BOOL FAR * lpfMessageUpdated
);

Parameters

lpMessage

[in] Pointer to the message to be updated.

ulFlags

[in] Bitmask of flags used to indicate the RTF or plain text version of the message has changed. The following flags can be set:

RTF_SYNC_BODY_CHANGED

The plain text version of the message has changed.

RTF_SYNC_RTF_CHANGED

The RTF version of the message has changed.

All other bits in the ulFlags parameter are reserved for future use.

lpfMessageUpdated

[out] Pointer to a variable indicating whether there is an updated message. TRUE if there is an updated message, FALSE otherwise.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

If the PR_RTF_IN_SYNC (PidTagRtfInSync) property is missing or is FALSE, before reading the PR_RTF_COMPRESSED (PidTagRtfCompressed) property the RTFSync function should be called with the RTF_SYNC_BODY_CHANGED flag set.

If the STORE_RTF_OK flag is not set in the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property, this function should be called with the RTF_SYNC_RTF_CHANGED flag set after modifying PR_RTF_COMPRESSED.

If both PR_BODY (PidTagBody) and PR_RTF_COMPRESSED have been changed, the RTFSync function should be called with both flags set.

If the value of the lpfMessageUpdated parameter is set to TRUE, then the IMAPIProp::SaveChanges method should be called for the message. If SaveChanges is not called, the modifications will not be saved in the message.

Message store providers can use RTFSync to keep the PR_BODY and PR_RTF_COMPRESSED properties synchronized.

For more information, see Supporting RTF Text for Message Store Providers.

See also

Reference

WrapCompressedRTFStream


ScBinFromHexBounded

 Copy code hover
[image]

ScBinFromHexBounded
See also Send feedback

Published: July 16, 2012

Converts the specified portion of a string representation of a hexadecimal number into a binary number.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScBinFromHexBounded(
  LPSTR sz,
  LPBYTE pb,
  ULONG cb
);

Parameters

sz

[in] Pointer to the null-terminated string to be converted. Valid characters include the hexadecimal characters 0 through 9 and both uppercase and lowercase characters a through f.

pb

[out] Pointer to the returned binary number.

cb

[in] Size, in bytes, of the pb parameter.

Return value

S_OK

Conversion was successful.

MAPI_E_CALL_FAILED

Invalid characters were encountered.

See also

Reference

FBinFromHex


ScCopyNotifications

 Copy code hover
[image]

ScCopyNotifications
Send feedback

Published: July 16, 2012

Copies a group of event notifications to a single block of memory.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScCopyNotifications(
  int cntf,
  LPNOTIFICATION rgntf,
  LPVOID pvDst,
  ULONG FAR * pcb
);

Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to an array of NOTIFICATION structures defining the event notifications to be copied.

pvDst

[out] Pointer to the returned notifications.

pcb

[out] Optional pointer to a variable where the size, in bytes, of the array pointed to by the rgntf parameter is stored. If not NULL, the pcb parameter is set to the number of bytes stored in the pvDst parameter.

Return value

S_OK

Event notifications were copied successfully.

E_INVALIDARG

An invalid notification was encountered.

Remarks

If NULL is passed in the pcb parameter, no copying is performed; if a non-null value is passed in pcb, the ScCopyNotifications function copies the size of the array and the array itself to a single block of memory. If pcb is not NULL, it is set to the number of bytes stored in the pvDst parameter. The pvDst parameter must be large enough to contain the entire array.


ScCopyProps

 Copy code hover
[image]

ScCopyProps
See also Send feedback

Published: July 16, 2012

Copies the properties defined by an array of SPropValue structures to a new destination.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScCopyProps(
  int cprop,
  LPSPropValue rgprop,
  LPVOID pvDst,
  ULONG FAR * pcb
);

Parameters

cprop

[in] Count of properties to be copied.

rgprop

[in] Pointer to an array of SPropValue structures that define the properties to be copied. The rgprop parameter does not have to point to the beginning of the array, but it must point to the beginning of one of the SPropValue structures in the array.

pvDst

[in] Pointer to the initial position in memory to which this function copies the properties.

pcb

[out] Optional pointer to the size, in bytes, of the block of memory pointed to by the pvDst parameter.

Return value

S_OK

Properties were copied successfully.

MAPI_E_INVALID_PARAMETER

An unknown property type was encountered.

Remarks

The new array and its data reside in a buffer created with a single allocation, and the ScRelocProps function can be used to adjust the pointers in the individual SPropValue structures. Prior to this adjustment, the pointers are valid.

ScCopyProps maintains the original property order for the copied property array.

The pcb parameter is optional; if it is not NULL, it is set to the number of bytes stored in the pvDst parameter.

See also

Reference

ScDupPropset


ScCountNotifications

 Copy code hover
[image]

ScCountNotifications
Send feedback

Published: July 16, 2012

Determines the size, in bytes, of an array of event notifications, and validates the memory associated with the array.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScCountNotifications(
  int cntf,
  LPNOTIFICATION rgntf,
  ULONG FAR * pcb
);

Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to the array of NOTIFICATION structures whose size is to be determined.

pcb

[out] Optional pointer to the size, in bytes, of the array pointed to by the rgntf parameter. If NULL, ScCountNotifications validates the array of notifications.

Return value

S_OK

Count was determined successfully.

MAPI_E_INVALID_PARAMETER

An invalid notification was encountered.

Remarks

If NULL is passed in the pcb parameter, the ScCountNotifications function only validates the array of notifications but no counting is done; if a non-null value is passed in pcb, ScCountNotifications determines the size of the array and stores the cause pcb. The pcb parameter must be large enough to contain the entire array.


ScCountProps

 Copy code hover
[image]

ScCountProps
See also Send feedback

Published: July 16, 2012

Determines the size, in bytes, of a property value array and validates the memory associated with the array.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScCountProps(
  int cprop,
  LPSPropValue rgprop,
  ULONG FAR * pcb
);

Parameters

cprop

[in] Count of properties in the array indicated by the rgprop parameter.

rgprop

[in] Pointer to a range in an array of SPropValue structures that defines the properties whose size is to be determined. This range does not necessarily start at the beginning of the array.

pcb

[out] Optional pointer to the size, in bytes, of the property array.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_INVALID_PARAMETER

At least one property in the property value array has an identifier of PROP_ID_NULL or PROP_ID_INVALID, or the property array contains a multivalued property with no property values.

Remarks

If NULL is passed in the pcb parameter, the ScCountProps function validates the array of notifications but no counting is done. If a non-null value is passed in pcb, the ScCountNotifications function determines the size of the array and stores the cause pcb. The pcb parameter must be large enough to contain the entire array.

As it is counting, ScCountProps validates the memory associated with the array. ScCountProps only works with properties about which MAPI has information.

See also

Reference

PropCopyMore


ScCreateConversationIndex

 Copy code hover
[image]

ScCreateConversationIndex
Send feedback

Published: July 16, 2012

Indicates where in a message thread a message belongs.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScCreateConversationIndex(
  ULONG cbParent,
  LPBYTE lpbParent,
  ULONG FAR* lpcbIndex,
  LPBYTE FAR * lppbIndex
);

Parameters

cbParent

[in] Count of bytes in the parent conversation index.

lpbParent

[in] Pointer to bytes in the parent conversation index. This may be NULL if cbParent is zero.

lpcbIndex

[out] Pointer to the count of bytes in the new conversation index returned by the call.

lppbIndex

[out] Pointer to a pointer to the new conversation index returned by the call.

Return value

S_OK

The call succeeded and has returned the expected value or values.


ScDupPropset

 Copy code hover
[image]

ScDupPropset
Send feedback

Published: July 16, 2012

Duplicates a property value array in a single block of MAPI memory combining the operations of the ScCopyProps and ScCountProps functions.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScDupPropset(
  int cprop,
  LPSPropValue rgprop,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPSPropValue FAR * prgprop
);

Parameters

cprop

[in] Count of property values in the array indicated by the rgprop parameter.

rgprop

[in] Pointer to an array of SPropValue structures defining the property values to be duplicated.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory for the duplicated array.

prgprop

[out] Pointer to the initial position in memory where the returned duplicated array of SPropValue structures is stored.

Return value

S_OK

The call succeeded and has returned the expected value or values.


ScInitMapiUtil

 Copy code hover
[image]

ScInitMapiUtil
See also Send feedback

Published: July 16, 2012

Replaces MAPIInitialize when only select utility functions are being used.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications
C++
SCODE ScInitMapiUtil(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Reserved; must be zero.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

The ScInitMapiUtil and DeinitMapiUtil functions cooperate to call and release select utility functions, as opposed to MAPIInitialize, which calls core as well as utility functions. When ScInitMapiUtil calls utility functions, it also initializes the necessary memory.

When use of the functions that ScInitMapiUtil has called is complete, DeinitMapiUtil must be explicitly called to release them. In contrast, MAPIInitialize implicitly calls DeinitMapiUtil.

See also

Reference

MAPIUninitialize


ScLocalPathFromUNC

 Copy code hover
[image]

ScLocalPathFromUNC
See also Send feedback

Published: July 16, 2012

Locates a local path counterpart to the given universal naming convention (UNC) path.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScLocalPathFromUNC(
  LPSTR szUNC,
  LPSTR szLocal,
  UINT cchLocal
);

Parameters

szUNC

[in] A path in the format \\[server]\[share]\[path] of a file or directory.

szLocal

[out] A path in the format [drive:]\[path] of the same file or directory as for the szUNC parameter.

cchLocal

[in] Size of the buffer for the output string.

Return value

S_OK

A local path was successfully located.

MAPI_E_TOO_BIG

szLocal was not large enough to hold the result.

S_FALSE

The UNC string was already a local path.

MAPI_E_NOT_FOUND

A local path was not found.

See also

Reference

ScUNCFromLocalPath


ScRelocNotifications

 Copy code hover
[image]

ScRelocNotifications
See also Send feedback

Published: July 16, 2012

Adjusts a pointer within a specified event notification array.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScRelocNotifications(
  int cntf,
  LPNOTIFICATION rgntf,
  LPVOID pvBaseOld,
  LPVOID pvBaseNew,
  ULONG FAR * pcb
);

Parameters

cntf

[in] Count of NOTIFICATION structures in the array indicated by the rgntf parameter.

rgntf

[in] Pointer to the array of NOTIFICATION structures defining event notifications within which a pointer is to be adjusted.

pvBaseOld

[in] Pointer to the original base address of the array indicated by the rgntf parameter.

pvBaseNew

[in] The location to which ScRelocNotifications writes the new base address of the array indicated by the rgntf parameter.

pcb

[out] Pointer to the size, in bytes, of the array indicated by the pvBaseNew parameter.

Return value

S_OK

A pointer was adjusted successfully.

MAPI_E_INVALID_PARAMETER

An invalid notification was encountered.

Remarks

The pcb parameter to the ScRelocNotifications function is optional.

See also

Reference

ScRelocProps


ScRelocProps

 Copy code hover
[image]

ScRelocProps
See also Send feedback

Published: July 16, 2012

Adjusts the pointers in an SPropValue array after the array and its data have been copied or moved to a new location.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScRelocProps(
  int cprop,
  LPSPropValue rgprop,
  LPVOID pvBaseOld,
  LPVOID pvBaseNew,
  ULONG FAR * pcb
);

Parameters

cprop

[in] Count of properties in the array pointed to by the rgprop parameter.

rgprop

[in] Pointer to an array of SPropValue structures for which pointers are to be adjusted.

pvBaseOld

[in] Pointer to the original base address of the array pointed to by the rgprop parameter.

pvBaseNew

[in] Pointer to the new base address of the array pointed to by the rgprop parameter.

pcb

[in, out] Optional pointer to the size, in bytes, of the array indicated by the pvBaseNew parameter. If not NULL, the pcb parameter is set to the number of bytes stored in the pvD parameter.

Return value

S_OK

Pointers were adjusted successfully.

MAPI_E_INVALID_PARAMETER

One or both parameters were invalid, or an unknown property type was encountered.

Remarks

The ScRelocProps function operates on the assumption that the property value array for which pointers are adjusted was originally allocated in a single call similar to a call to the ScCopyProps function. If a client application or service provider is working with a property value that is built from disjointed blocks of memory, it should use ScCopyProps to copy properties instead.

ScRelocProps is used to maintain the validity of pointers in an SPropValue array. To maintain pointers' validity when writing such an array to and reading it from a disk, perform the following operations:

  1. Before writing the array and data to a disk, call ScRelocProps on the array with the pvBaseNew parameter pointing to some standard value zero, for instance.

  2. After reading the array and data from a disk, call ScRelocProps on the array with the pvBaseOld parameter equal to the same standard value used in Step 1. The array and data must be read into a buffer created with a single allocation.

  3. The pcb parameter to ScRelocProps is optional.

See also

Reference

MAPIAllocateBuffer
ScCountProps
ScDupPropset
ScRelocNotifications


ScUNCFromLocalPath

 Copy code hover
[image]

ScUNCFromLocalPath
See also Send feedback

Published: July 16, 2012

Locates a universal naming convention (UNC) path counterpart to the given local path.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
SCODE ScUNCFromLocalPath(
  LPSTR szLocal,
  LPSTR szUNC,
  UINT cchUNC
);

Parameters

szLocal

[in] A path in the format [drive:]\[path] of a file or directory.

szUNC

[out] A path in the format \\[server]\[share]\[path] of the same file or directory as for the szLocal parameter.

cchUNC

[in] Size of the buffer for the output string.

Return value

S_OK

The UNC path counterpart was successfully located.

MAPI_E_INVALID_PARAMETER

One or more parameters are invalid.

MAPI_E_TOO_BIG

szUNC was not large enough to hold the result.

S_FALSE

The local path was already a UNC string.

See also

Reference

ScLocalPathFromUNC


SERVICEWIZARDDLGPROC

 Copy code hover
[image]

SERVICEWIZARDDLGPROC
Send feedback

Published: July 16, 2012

Defines a callback function invoked by the Profile Wizard to allow a service provider to react to user events when the provider's property sheets or pages are being shown.

Header file: | Mapiwz.h
Defined function implemented by: | Service providers
Defined function called by: | MAPI Profile Wizard
C++
BOOL SERVICEWIZARDDLGPROC(
  HWND hDlg,
  UINT wMsgID,
  WPARAM wParam,
  LPARAM lParam
);

Parameters

hDlg

[in] Window handle to the Profile Wizard dialog box.

wMsgID

[in] The window message to be processed. In addition to the regular window messages expected by a modal dialog box, the following messages can be received:

WM_CLOSE

The Profile Wizard has completed. The service provider should do all required cleanup such as deallocating any dynamically allocated memory.

WM_COMMAND

One of the provider's controls has been selected, or the Next or Back button has been clicked. The value in the wParam parameter indicates which of these user events has occurred.

WM_INITDIALOG

The user has moved to another property page, for which the dialog box must be initialized. The provider should initialize the controls that the Profile Wizard has added to the dialog box.

WIZ_QUERYNUMPAGES

The Profile Wizard is prompting for the number of pages that the provider needs to display. The provider should return the number of pages instead of TRUE or FALSE. For example, use the following return statement to indicate that three pages should to be displayed:

Copy code Copy code
return (BOOL)3;
wParam

[in] A 32-bit parameter associated with window messages. Possible values depend on the message specified in the wMsgID parameter. In addition to the values expected with the regular window messages for a modal dialog box, the following values can be received:

WIZ_NEXT

When wMsgID contains WM_COMMAND, the user has clicked the Next button.

WIZ_PREV

When wMsgID contains WM_COMMAND, the user has clicked the Back button.

lParam

[in] A 32-bit parameter associated with window messages. Possible values depend on the message specified in the wMsgID parameter.

Return value

The value returned by a SERVICEWIZARDDLGPROC based function is dependent on the window message received. Note in particular the exceptional return value for the WIZ_QUERYNUMPAGES message. The normal return values are:

TRUE

The service provider has processed the received window message.

FALSE

The service provider has not processed the received window message.

Remarks

When the user moves from one property page to another, the provider is responsible for hiding the old page's controls and showing the controls for the next or previous page. When the user clicks the Next button, the SERVICEWIZARDDLGPROC based function is called with the WM_COMMAND message and WIZ_NEXT in the wParam parameter. The following steps describe what occurs between the time the user clicks Next and the time the first provider's configuration pages are rendered.

  1. The Profile Wizard hides any controls that are on the window.

  2. The Profile Wizard adds the provider's hidden controls to the page.

  3. The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_INITDIALOG message, so that the provider can initialize the controls.

  4. The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WIZ_QUERYNUMPAGES message. The provider returns the number of pages that are to be shown.

  5. The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_COMMAND message with the wParam parameter set to either WIZ_NEXT or WIZ_PREV. At this point, the provider either returns FALSE {error} or reveals its controls and returns TRUE {success}. If the Profile Wizard passes in ID_NEXT, the provider's first page is displayed. If ID_PREV is passed in, the last page is displayed.

  6. The Profile Wizard calls the provider's SERVICEWIZARDDLGPROC function, sending the WM_COMMAND message with the wParam parameter set to either WIZ_NEXT or WIZ_PREV (depending on which button the user clicked). The provider is responsible for showing or hiding its controls and writing its data to the IMAPIProp passed to the Profile Wizard to step through its sequence of pages. The provider should return TRUE if the next or previous page was successfully shown, and FALSE if neither the next nor previous page could be shown. The provider needs to be aware of when it is stepping outside of its sequence of pages, and respond appropriately by hiding its controls and writing its data to the profile.

  7. If the user steps outside the provider's range of pages, the Profile Wizard deletes the provider's hidden controls from the dialog box and calls the next provider or displays its next page if that was the last provider.


SetAttribIMsgOnIStg

 Copy code hover
[image]

SetAttribIMsgOnIStg
Send feedback

Published: July 16, 2012

Sets or alters attributes of properties on an IMessage object supplied by the OpenIMsgOnIStg function.

Header file: | Imessage.h
Implemented by: | MAPI
Called by: | Client applications and message store providers
C++
HRESULT SetAttribIMsgOnIStg(
  LPVOID lpObject,
  LPSPropTagArray lpPropTags,
  LPSPropAttrArray lpPropAttrs,
  LPSPropProblemArray FAR * lppPropProblems
);

Parameters

lpObject

[in] Pointer to the object for which property attributes are being set.

lpPropTags

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating the properties for which property attributes are being set.

lpPropAttrs

[in] Pointer to an SPropAttrArray structure listing the property attributes to set.

lppPropProblems

[out] Pointer to the returned SPropProblemArray structure containing a set of property problems. This structure identifies problems encountered if SetAttribIMsgOnIStg has been able to set some properties, but not all. If a pointer to NULL is passed in the lppPropProblems parameter, no property problem array is returned even if some properties were not set.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but one or more properties could not be accessed and were returned with a property type of PT_ERROR.

Remarks

Property attributes can only be accessed on property objects, that is, objects implementing the IMAPIProp : IUnknown interface. To make MAPI properties available on an OLE structured storage object, OpenIMsgOnIStg builds an IMessage : IMAPIProp object on top of the OLE IStorage object. The property attributes on such objects can be set or altered with SetAttribIMsgOnIStg and retrieved with GetAttribIMsgOnIStg.

Note GetAttribIMsgOnIStg and SetAttribIMsgOnIStg do not operate on all IMessage objects. They are only valid for IMessage-on-IStorage objects returned by OpenIMsgOnIStg.

In the lpPropAttrs parameter, the number and position of the attributes must match the number and position of the property tags passed in the lpPropTags parameter.

The SetAttribIMsgOnIStg function is used to make message properties read-only when required by the IMessage schema. The sample message store provider uses it for this purpose. For more information, see Messages.


SzFindCh

 Copy code hover
[image]

SzFindCh
Send feedback

Published: July 16, 2012

Searches for the first occurrence of a character in a null-terminated string.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LPSTR SzFindCh(
  LPCSTR lpsz,
  USHORT ch
);

Parameters

lpsz

[in] Pointer to the null-terminated string to be searched.

ch

[in] The character to be searched for.

Return value

SzFindCh returns a pointer to the first occurrence of the character in the string. If the character does not occur anywhere in the string, or if the lpsz parameter is NULL, a value of NULL is returned.

Remarks

The SzFindCh function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in the Unicode and DBCS formats are supported.


SzFindLastCh

 Copy code hover
[image]

SzFindLastCh
Send feedback

Published: July 16, 2012

Searches for the last occurrence of a character in a null-terminated string.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LPSTR SzFindLastCh(
  LPCSTR lpsz,
  USHORT ch
);

Parameters

lpsz

[in] Pointer to the null-terminated string to be searched.

ch

[in] The character to be searched for.

Return value

SzFindLastCh returns a pointer to the last occurrence of the character in the string. If the character does not occur anywhere in the string, or if the lpsz parameter is NULL, a value of NULL is returned.

Remarks

The SzFindLastCh function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in the Unicode and DBCS formats are supported.


SzFindSz

 Copy code hover
[image]

SzFindSz
Send feedback

Published: July 16, 2012

Locates the first occurrence of a null-terminated substring in a null-terminated string.

Header file: | Mapiutil.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
LPSTR SzFindCh(
  LPCSTR lpsz,
  LPCSTR lpszKey
);

Parameters

lpsz

[in] Pointer to the null-terminated string to be searched. The lpsz parameter must not exceed 65536 characters.

lpszKey

[in] Pointer to the null-terminated substring to be searched for. The lpszKey parameter must not exceed 65536 characters.

Return value

SzFindSz returns a pointer to the first character of the first occurrence of the substring in the string. If the substring does not occur anywhere in the string, if lpszKey is larger than lpsz, or if either parameter is NULL, a value of NULL is returned.

Remarks

The SzFindSz function searches for an exact match only; it is sensitive to case and diacritical differences. Searches in Unicode and DBCS formats are supported. The length limit on both parameters is in characters, not necessarily bytes.


UFromSz

 Copy code hover
[image]

UFromSz
Send feedback

Published: July 16, 2012

Converts a null-terminated string of decimal digits into an unsigned integer.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
UINT UFromSz(
  LPCSTR lpsz
);

Parameters

lpsz

[in] Pointer to the null-terminated string to be converted. The lpsz parameter must not exceed 65536 characters.

Return value

UFromSz returns an unsigned integer. If the string does not begin with at least one decimal digit, zero is returned.

Remarks

The UFromSz function stops converting when it reaches the first character in the string that is not a decimal digit. For example, given the string "55", UFromSz returns the integer value 55. Given the string "5a5b", the function returns the integer value 5. Given the string "a5b5", UFromSz returns zero.

UFromSz is sensitive to diacritical differences. Strings in the Unicode and DBCS formats are supported. The length limit on lpsz is in characters, not necessarily bytes.


UlAddRef

 Copy code hover
[image]

UlAddRef
Send feedback

Published: July 16, 2012

Provides an alternative way to invoke the OLE method IUnknown::AddRef.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
ULONG UlAddRef(
  LPVOID punk
);

Parameters

punk

[in] Pointer to an interface derived from the IUnknown interface, in other words any MAPI interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

UlAddRef returns the value returned by the IUnknown::AddRef method, which is the new value of the reference count for the interface. The value is nonzero.

For more information about IUnknown::AddRef, see Implementing the IUnknown Interface.


UlFromSzHex

 Copy code hover
[image]

UlFromSzHex
Send feedback

Published: July 16, 2012

Converts a null-terminated string of hexadecimal digits into an unsigned long integer.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
ULONG UlFromSzHex(
LPCSTR lpsz
);

Parameters

lpsz

[in] Pointer to the null-terminated string to be converted. The lpsz parameter must not exceed 65536 characters.

Return value

UlFromSzHex returns an unsigned long integer. If the string does not begin with at least one hexadecimal digit, zero is returned.

Remarks

The UlFromSzHex function stops converting when it reaches the first character in the string that is not a hexadecimal digit. For example, given the string "5a", UlFromSzHex returns the integer value 90. Given the string "5g5h", the function returns the integer value 5. Given the string "g5h5", UlFromSzHex returns zero.

UlFromSzHex is sensitive to diacritical differences but allows both 'a' through 'f' and 'A' through 'F' for hexadecimal digits. Strings in the Unicode and DBCS formats are supported. The length limit on lpsz is in characters, not necessarily bytes.


UlPropSize

 Copy code hover
[image]

UlPropSize
Send feedback

Published: July 16, 2012

Returns the size of a single property value.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
ULONG UlPropSize(
  LPSPropValue lpSPropValue
);

Parameters

lpSPropValue

[in] Pointer to an SPropValue structure defining the property to be measured.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The UlPropSize function returns the size, in bytes, of the property value for the specified property. It disregards the size of the remainder of the SPropValue structure.


UlRelease

 Copy code hover
[image]

UlRelease
Send feedback

Published: July 16, 2012

Provides an alternative way to invoke the OLE method IUnknown::Release.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
ULONG UlRelease(
  LPVOID punk
);

Parameters

punk

[in] Pointer to an interface derived from the IUnknown interface, in other words any MAPI interface.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The reference count is the number of existing pointers to the object to be released.

If the punk parameter is NULL, the function returns immediately without calling IUnknown::Release

UlRelease returns the value returned by the IUnknown::Release method, which can be equal to the reference count for the object to be released.

For more information about IUnknown::Release, see Implementing the IUnknown Interface.


UlValidateParameters

 Copy code hover
[image]

UlValidateParameters
Send feedback

Published: July 16, 2012

Calls an internal function to check the parameters client applications have passed to service providers and MAPI.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT UlValidateParameters(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The UlValidateParameters macro has been superseded by the UlValidateParms macro. UlValidateParameters does not work correctly on RISC platforms and is now prevented from compiling on them. It still compiles and works correctly on Intel platforms, but UlValidateParms is recommended on all platforms.


UlValidateParms

 Copy code hover
[image]

UlValidateParms
Send feedback

Published: July 16, 2012

Calls an internal function to check the parameters client applications have passed to service providers and MAPI.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT UlValidateParms(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_CALL_FAILED

An error prevented the operation from completing.

Remarks

Parameters passed between MAPI and service providers are assumed to be correct and undergo only debug validation with the CheckParms macro. Providers should check all parameters passed in by client applications, but clients should assume that MAPI and provider parameters are correct. Use the HR_FAILED macro to test return values.

The UlValidateParms macro is called differently depending on whether the calling code is C or C++. This macro is used to validate parameters for the few IUnknown and MAPI methods that return ULONG instead of HRESULT values; the ValidateParms macro works for all others.


ValidateParameters

 Copy code hover
[image]

ValidateParameters
Send feedback

Published: July 16, 2012

Calls an internal function to check the parameters client applications have passed to service providers.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT ValidateParameters(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

All of the parameters are valid.

MAPI_E_CALL_FAILED

One or more of the parameters are not valid.

Remarks

The ValidateParameters macro has been superseded by the ValidateParms macro. ValidateParameters does not work correctly on RISC platforms and is now prevented from compiling on them. It still compiles and works correctly on Intel platforms, but ValidateParms is recommended on all platforms.


ValidateParms

 Copy code hover
[image]

ValidateParms
See also Send feedback

Published: July 16, 2012

Calls an internal function to check the parameters client applications have passed to service providers.

Header file: | Mapival.h
Implemented by: | MAPI
Called by: | Service providers
C++
HRESULT ValidateParms(
  METHODS eMethod,
  LPVOID First
);

Parameters

eMethod

[in] Specifies, by enumeration, the method to validate.

First

[in] Pointer to the first argument on the stack.

Return value

S_OK

All of the parameters are valid.

MAPI_E_CALL_FAILED

One or more of the parameters are not valid.

Remarks

Parameters passed between MAPI and service providers are assumed to be correct and undergo only debug validation with the CheckParms macro. Providers should check all parameters passed in by client applications, but clients should assume that MAPI and provider parameters are correct. Use the HR_FAILED macro to test return values.

ValidateParms is called differently depending on whether the calling code is C or C++. C++ passes an implicit parameter known as this to each method call, which becomes explicit in C and is the address of the object. The first parameter, eMethod, is an enumerator made from the interface and method being validated and tells what parameters to expect to find on the stack. The second parameter is different for C and C++. In C++ it is called First, and it is the first parameter to the method being validated. The second parameter for the C language, ppThis, is the address of the first parameter to the method which is always an object pointer. In both cases, the second parameter gives the address of the beginning of the method's parameter list, and based on eMethod, moves down the stack and validates the parameters.

Providers implementing common interfaces such as IMAPITable and IMAPIProp should always check parameters using the ValidateParms function in order to make sure consistency across all providers. Additional parameter validation functions have been defined for some complex parameter types to be used instead as appropriate. See the reference topics for the following functions:

  • FBadColumnSet

  • FBadEntryList

  • FBadProp

  • FBadProp

  • FBadRestriction

  • FBadRestriction

  • FBadRglpszW

  • FBadRow

  • FBadRowSet

  • FBadSortOrderSet

Inherited methods use the same parameter validation as the interface from which they inherit. For example, the parameter checking for IMessage and IMAPIProp should be the same.

See also

Reference

UlValidateParms


WIZARDENTRY

 Copy code hover
[image]

WIZARDENTRY
Send feedback

Published: July 16, 2012

Defines a service provider entry point function which the Profile Wizard calls to retrieve enough information to display the provider's configuration property sheets.

Header file: | Mapiwz.h
Defined function implemented by: | Service providers
Defined function called by: | MAPI Profile Wizard
C++
ULONG WIZARDENTRY(
  HINSTANCE hProviderDLLInstance,
  LPSTR FAR * lpcsResourceName,
  DLGPROC FAR * lppDlgProc,
  LPMAPIPROP lpMAPIProp,
  LPMAPISUPPORTOBJECT lpMapiSupportObject
);

Parameters

hProviderDLLInstance

[in] Instance handle of the service provider's DLL.

lpcsResourceName

[out] Pointer to a string that contains the full name of the dialog resource that should be displayed by the Profile Wizard during configuration. The maximum size of the string, including the NULL terminator, is 32 characters.

lppDlgProc

[out] Pointer to a standard Windows dialog box procedure that will be called by the Profile Wizard to notify the provider of various events.

lpMAPIProp

[in] Pointer to a property interface implementation that provides access to the configuration properties.

lpMapiSupportObject

[in] Pointer to the MAPI support object applicable to this session.

Return value

S_OK

The service provider's WIZARDENTRY function was called successfully.

MAPI_E_CALL_FAILED

An error of unexpected or unknown origin prevented the operation from completing.

Remarks

The Profile Wizard calls the WIZARDENTRY based function when it is ready to display the service provider's configuration user interface. When the Profile Wizard is finished configuring all providers, it writes the configuration properties to the profile by calling IMsgServiceAdmin::ConfigureMsgService.

Notes to Implementers

The name of the WIZARDENTRY based function must be placed in the WIZARD_ENTRY_NAME entry in MAPISVC.INF.

The resource name is that of the dialog resource that will be rendered in the pane of the Profile Wizard. The resource that is passed back needs to contain all the pages in a single dialog resource. When the Profile Wizard receives this resource, it ignores the dialog style, but not the control styles, and creates all the controls as children of the Profile Wizard page. All controls are initially hidden. Providers should make sure that the coordinates for their controls are zero or zero-based, and that they do not exceed a maximum width of 200 dialog units and a maximum height of 150 dialog units. Control identifiers below 400 are reserved for the Profile Wizard. The Profile Wizard displays the provider's title in bold text above the provider's user interface.

The property interface pointer supplied in the lpMAPIProp parameter should be retained by the provider for future reference. The Profile Wizard deals with only the most basic set of properties, and the provider can use the property interface implementation to include additional properties. During configuration, providers should add their configuration properties to the object implementing the property interface. After all providers have been configured, the Profile Wizard adds these properties to the profile.

For more information about how to use this function, see Supporting Message Service Configuration.


WrapCompressedRTFStream

 Copy code hover
[image]

WrapCompressedRTFStream
See also Send feedback

Published: July 16, 2012

Creates a text stream in uncompressed Rich Text Format (RTF) from the compressed format used in the PR_RTF_COMPRESSED (PidTagRtfCompressed) property.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications
C++
HRESULT WrapCompressedRTFStream(
  LPSTREAM lpCompressedRTFStream,
  ULONG ulflags,
  LPSTREAM FAR * lpUncompressedRTFStream
);

Parameters

lpCompressedRTFStream

[in] Pointer to a stream opened on the PR_RTF_COMPRESSED property of a message.

ulFlags

[in] Bitmask of option flags for the function. The following flags can be set:

MAPI_MODIFY

Whether the client intends to read or write the wrapped stream interface that is returned.

STORE_UNCOMPRESSED_RTF

Uncompressed RTF should be written to the stream pointed to by lpCompressedRTFStream

lpUncompressedRTFStream

[out] Pointer to the location where WrapCompressedRTFStream returns a stream for the uncompressed RTF.

Return value

S_OK

The call succeeded and has returned the expected value or values.

Remarks

If the MAPI_MODIFY flag is passed in the ulFlags parameter, the lpCompressedRTFStream parameter must already be open for reading and writing. New, uncompressed RTF text should be written into the stream interface returned in lpUncompressedRTFStream. Because it is not possible to append the existing stream, the entire message text must be written.

If zero is passed in the ulFlags parameter, then lpCompressedRTFStream may be opened read-only. Only the entire message text can be read out of the stream interface returned in lpUncompressedRTFStream. It is not possible to search starting the middle of the stream.

WrapCompressedRTFStream assumes that the compressed stream's pointer is set to the beginning of the stream. Certain OLE IStream methods are not supported by the returned uncompressed stream. These include IStream::Clone, IStream::LockRegion, IStream::Revert, IStream::Seek, IStream::SetSize, IStream::Stat, and IStream::UnlockRegion. In order to copy to the entire stream, a read/write loop is needed.

Because the client writes new RTF in uncompressed format, it should use WrapCompressedRTFStream, instead of directly writing to the stream. RTF-aware clients should search for the STORE_UNCOMPRESSED_RTF flag in the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property and pass it to WrapCompressed RTFStream if it is set.

See also

Reference

RTFSync


WrapCompressedRTFStreamEx

 Copy code hover
[image]

WrapCompressedRTFStreamEx
See also Send feedback

Published: July 16, 2012

Decompresses the the body of an e-mail message that is in compressed Rich Text Format (RTF), indicates the format of the decompressed stream, optionally converts the decompressed stream to its native format, and returns either the decompressed stream or the converted native stream.

Quick Info

Exported by: | msmapi32.dll
Called by: | Client
Implemented by: | Outlook
Copy code Copy code
HRESULT __stdcall WrapCompressedRTFStreamEx(
    LPSTREAM            lpCompressedRTFStream,
    CONST RTF_WCSINFO   *pWCSInfo,
    LPSTREAM            *lppUncompressedRTFStream,
    RTF_WCSRETINFO      *pRetInfo);

Parameters

lpCompressedRTFStream

[in] This is a pointer to a stream that is opened on the PidTagRtfCompressed Canonical Property of a message.

pWCSInfo

[in] This is a pointer to a

RTF_WCSINFO structure that contains options for the function.

lppUncompressedRTFStream

[out] This is a pointer to the location where a stream for the decompressed RTF is returned.

pRetInfo

[out] This is a pointer to a RTF_WCSRETINFO structure that contains information about the format of the returned decompressed stream.

Return Values

S_OK

  • The function call is successful.

MAPI_E_INVALID_PARAMETER

  • This is returned if the MAPI_NATIVE_BODY flag is combined with the MAPI_MODIFY flag in the ulFlags field of the RTF_WCSINFO structure pointed at by pWCSInfo.

Remarks

WrapCompressedRTFStreamEx allows you to access the body of an e-mail message encapsulated in compressed RTF by decompressing the stream, returns the decompressed stream and its format, and optionally the native body stream. The native body stream can be in RTF, plain text, or HTML.

The Microsoft Office Outlook object model provides a Body property for MailItem objects and a MailItem.BodyFormat Property (Outlook) that indicates the format of the body text. By design, a solution that is not trusted by Outlook invokes security dialog boxes generated by the Outlook Security Guard. Using the exported MAPI function WrapCompressedRTFStreamEx allows a solution to use MAPI instead of the Outlook object model and avoid these security dialog boxes.

Because the MAPI_NATIVE_BODY flag cannot be combined with the MAPI_MODIFY flag in the ulFlags field of the RTF_WCSINFO structure pointed at by pWCSInfo, you can only access the native body stream in read-only mode. To access the native body stream in read/write mode, you should use the WrapCompressedRTFStream function.

See also

Concepts

How to: Retrieve the Body of a Message in Compressed RTF and Convert It to Its Native Format


WrapStoreEntryID

 Copy code hover
[image]

WrapStoreEntryID
Send feedback

Published: July 16, 2012

Converts a message store's internal entry identifier to an entry identifier more usable by the messaging system.

Header file: | Mapidefs.h
Implemented by: | MAPI
Called by: | Client applications and service providers
C++
WrapStoreEntryID(
  ULONG ulFlags,
  LPSTR szDLLName,
  ULONG cbOrigEntry,
  LPENTRYID lpOrigEntry,
  ULONG * lpcbWrappedEntry,
  LPENTRYID * lppWrappedEntry
);

Parameters

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_UNICODE

The strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

szDLLName

[in] The name of the message store provider DLL.

cbOrigEntry

[in] Size, in bytes, of the original entry identifier for the message store.

lpOrigEntry

[in] Pointer to an ENTRYID structure that contains the original entry identifier.

lpcbWrappedEntry

[out] Pointer to the size, in bytes, of the new entry identifier.

lppWrappedEntry

[out] Pointer to a pointer to an ENTRYID structure that contains the new entry identifier.

Return value

None.

Remarks

A message store object retains an internal entry identifier which is meaningful only to service providers coresident with that message store. For other messaging components, MAPI supplies a wrapped version of the internal entry identifier that makes it recognizable as that belong to the message store. Coresident service providers should always be given the original unwrapped message store entry identifier; client applications should always be given the wrapped version, which is then usable anywhere in the messaging domain and in other domains.

A service provider can wrap a message store entry identifier using either the WrapStoreEntryID function or the IMAPISupport::WrapStoreEntryID method, which calls the WrapStoreEntryID function. The provider must wrap the entry identifier when exposing the message store's PR_ENTRYID (PidTagEntryId) property or writing it into a profile section, and when exposing the PR_STORE_ENTRYID (PidTagStoreEntryId) property. MAPI wraps a message store entry identifier when responding to an IMAPISession::OpenMsgStore call.

When a client application passes a wrapped message store entry identifier to MAPI, for example in an IMAPISession::OpenEntry call, MAPI unwraps the entry identifier before using it to call a provider method such as IMSProvider::Logon or IMSProvider::CompareStoreIDs.


XPProviderInit

 Copy code hover
[image]

XPProviderInit
See also Send feedback

Published: July 16, 2012

Initializes a transport provider for operation.

Header file: | Mapispi.h
Implemented by: | Transport providers
Called by: | MAPI
C++
HRESULT XPProviderInit(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  ULONG ulFlags,
  ULONG ulMAPIVer,
  ULONG FAR * lpulProviderVer,
  LPXPPROVIDER FAR * lppXPProvider
);

Parameters

hInstance

[in] The instance of the transport provider's dynamic-link library (DLL) that MAPI used when it loaded the DLL.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The transport provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that Mapi.dll uses. For the current version number, see the Mapispi.h header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this transport provider uses.

lppXPProvider

[out] Pointer to a pointer to the initialized transport provider object.

Return value

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function XPProviderInit to initialize a transport provider following a client logon. XPProviderInit is called once for each transport provider specified in the client's profile.

Notes to Implementers

A transport provider must implement XPProviderInit as an entry point function in the provider's DLL. The implementation must be based on the XPPROVIDERINIT function prototype, also specified in Mapispi.h. MAPI defines XPPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes XPProviderInit to follow the CDECL calling convention. An advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. Because the provider object contains context, XPProviderInit must return a different provider object in lppXPProvider for each initialization, even for multiple initializations in the same process.

The transport provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information about writing XPProviderInit, see Initializing the Transport Provider. For more information about entry point functions, see Implementing a Service Provider Entry Point Function.

See also

Reference

ABProviderInit
IXPProvider : IUnknown
MSProviderInit


MAPI Properties

 Copy code hover
[image]

MAPI Properties
See also Send feedback

Published: July 16, 2012

This section contains canonical properties that are supported by Microsoft Outlook Messaging API (MAPI). Each canonical property corresponds to one or multiple related MAPI properties. For more information on canonical properties, see MAPI Canonical Properties. For a general explanation of how MAPI works with properties and a list of the properties available for each object, see MAPI Property Overview. For information about the property-related macros, see the reference page for the SPropValue structure. For a comprehensive list of MAPI properties and their mappings to canonical property names, see Mapping MAPI Names to Canonical Property Names and Mapping Canonical Property Names to MAPI Names.

Note: Unlike members of OLE variant arrays, every member in a MAPI multivalued property array is of the same type.

See also

Other resources

MAPI Reference


ArchiveSourceSupportMask

 Copy code hover
[image]

ArchiveSourceSupportMask
Send feedback

Published: July 16, 2012

Specifies whether Microsoft Office Outlook should scan folders in a store and archive them automatically.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_LONG
Access type: | Read-only or read/write depending on the store provider

Remarks

To provide any of the store functionality, the store provider must implement IMAPIProp : IUnknown and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PSETID_Common
ulKind: | MNID_STRING
Kind.lpwstrName: | L"ArchiveSourceSupportMask"

This property allows store providers to specify whether Outlook should scan folders in a store and archive them automatically.

By default, this property is not exposed on a store, which means Outlook can scan folders on the store. If the property is exposed, the following are the possible values:

Copy code Copy code
enum {
 ASM_DEFAULT              = 0,
 ASM_DO_NOT_ARCHIVE         = 1 << 0x0,
 ASM_CLIENT_DO_NOT_CHANGE = 1 << 0xF
};

ASM_DEFAULT

  • Outlook can scan folders on the store.

ASM_DO_NOT_ARCHIVE

  • Outlook should not scan folders on the store.

ASM_CLIENT_DO_NOT_CHANGE

  • Do not allow clients to change this property on the store. Note that the constant ASM_CLIENT_DO_NOT_CHANGE is for future reference and is not currently implemented. For now, a store can prevent clients from changing this flag by hardcoding the value that the store returns for this property.


CrawlSourceSupportMask

 Copy code hover
[image]

CrawlSourceSupportMask
Send feedback

Published: July 16, 2012

Specifies whether Microsoft Office Outlook should scan folders in a store, including Contacts, Calendar, and Tasks folders, on startup to populate the Navigation Pane.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_LONG
Access type: | Read-only or read/write depending on the store provider

Remarks

To provide any of the store functionality, the store provider must implement IMAPIProp : IUnknown and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PSETID_Common
ulKind: | MNID_STRING
Kind.lpwstrName: | L"CrawlSourceSupportMask"

This property provides a way for store providers to specify whether Outlook should scan various folders in a store. It is used on startup when Outlook scans existing folders on each opened store to populate the Navigation pane; Outlook checks for the presence and value of this property on a store before initiating the scan.

By default, this property is not exposed on a store, which means Outlook can scan folders on the store. If the property is exposed, the following are the possible values:

Copy code Copy code
enum {
 CSM_DEFAULT              = 0,
 CSM_DO_NOT_CRAWL         = 1 << 0x0,
 CSM_CLIENT_DO_NOT_CHANGE = 1 << 0xF
};

CSM_DEFAULT

  • Outlook can scan folders on the store.

CSM_DO_NOT_CRAWL

  • Outlook should not scan folders on the store.

CSM_CLIENT_DO_NOT_CHANGE

  • Do not allow clients to change this property on the store. Note that the constant CSM_CLIENT_DO_NOT_CHANGE is for future reference and is not currently implemented. For now, a store can prevent clients from changing this flag by hardcoding the value that the store returns for this property.


Display Server Folder Sizes Property

 Copy code hover
[image]

Display Server Folder Sizes Property
Send feedback

Published: July 16, 2012

Displays the sizes of specified folders on the server in the Outlook Folder Size dialog box.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_BOOLEAN
Access type: | Read/write

Remarks

To provide any of the store functionality, the store provider must implement IMAPIProp : IUnknown and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PS_PUBLIC_STRINGS
ulKind: | MNID_STRING
Kind.lpwstrName: | L"urn:schemas-microsoft-com:office:outlook#serverfoldersizes"

This property is supported in Microsoft Outlook 2003 Service Pack (SP) 1. If the version of Outlook is earlier than Outlook 2003 SP 1, or if its value is false, Outlook will display only the sizes of folders on the local store. If this property is set on a store that uses Outlook 2003 SP 1, Outlook will query for the size of each specified folder on the server and the local drive.

To query for the folder size on the server, Outlook opens a folder on the store with IMsgStore::OpenEntry, passing the flag MAPI_NO_CACHE, and then it queries for PR_MESSAGE_SIZE_EXTENDED. The store provider should then return the folder size on the server.

To query for the size of a folder on the local drive, Outlook opens the folder without the MAPI_NO_CACHE flag. It then queries for PR_MESSAGE_SIZE_EXTENDED; the store provider should return the size of the specified folder on the local drive.

With this property set, store providers that synchronize store contents to a server can display folder size data on the server in the Outlook Folder Size dialog box. Users can then compare their current server storage usage with server quotas.


Hide Meeting Update Option Property

 Copy code hover
[image]

Hide Meeting Update Option Property
Send feedback

Published: July 16, 2012

Hides the option to send meeting updates to only added or deleted attendees.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_BOOLEAN
Access type: | Read/write

Remarks

To provide any of the store functionality, the store provider must implement IMAPIProp : IUnknown and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PS_PUBLIC_STRINGS
ulKind: | MNID_STRING
Kind.lpwstrName: | L"urn:schemas-microsoft-com:office:outlook#allornonemtgupdatedlg"

A store provider that uses a server to send meeting updates can modify the Send Update to Attendees dialog box. This functionality is useful because when the server sends a meeting update, the server does not know which attendees have been added or deleted by the user since the initial meeting request. When this property is true, the Send update only to added or deleted attendees option is not displayed in the Send Update to Attendees dialog box.

This property is ignored if the version of Outlook is earlier than Microsoft Office Outlook 2003 Service Pack 1, or if its value is false.


Make Store Type Private Property

 Copy code hover
[image]

Make Store Type Private Property
Send feedback

Published: July 16, 2012

Treats a secondary store as private.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_BOOLEAN
Access type: | Read/write

Remarks

To provide any of the store functionality, the store provider must implement IMsgStore : IMAPIProp and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PS_PUBLIC_STRINGS
ulKind: | MNID_STRING
Kind.lpwstrName: | L"urn:schemas-microsoft-com:office:outlook#storetypeprivate"

A store provider can use this property to have Outlook treat it as private when it is a secondary store for a user.

By default, Outlook treats a secondary store the same way as a delegate store, and items in the secondary store are private only if the user marks them specifically as private. When this property is true, items deleted from a secondary store are moved to the Deleted Items folder in the primary store. Items marked private are not displayed. Drafts are stored in the Drafts folder in the primary store.

This property is ignored if the version of Outlook is earlier than Microsoft Office Outlook 2003 Service Pack 1, or if its value is false.


NoFolderScan

 Copy code hover
[image]

NoFolderScan
Send feedback

Published: July 16, 2012

Specifies whether Microsoft Office Outlook should scan Contacts folders on a store.

Quick Info

Exposed on: | IMsgStore : IMAPIProp object
Created by: | Store provider
Accessed by: | Outlook and other clients
Property type: | PT_LONG
Access type: | Read-only or read/write depending on the store provider

Remarks

To provide any of the store functionality, the store provider must implement IMAPIProp : IUnknown and return a valid property tag for any of these properties passed to an IMAPIProp::GetIDsFromNames call. When the property tag for any of these properties is passed to IMAPIProp::GetProps, the store provider must also return the correct property value. Store providers can call HrGetOneProp and HrSetOneProp to get or set these properties.

To retrieve the value of this property, the client should first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PSETID_Common
ulKind: | MNID_STRING
Kind.lpwstrName: | L"NoFolderScan"

This property provides a way for store providers to specify to Outlook not to scan Contacts folders in the store to avoid performance degradation. It is used in mail merge operations during which Outlook checks for the presence and value of this property before initiating the scan.

By default, this property is not exposed on a store, which means Outlook can scan the Contacts folder on the store. If the property is exposed, the following are the possible values:

  • Zero (0): Outlook can carry out the scan.

  • Non-zero value: Outlook should not scan Contacts folders on the store.


PidLidAddressBookProviderArrayType Canonical Property

 Copy code hover
[image]

PidLidAddressBookProviderArrayType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the state of the contact's electronic addresses and represents a set of bit flags.

Associated properties: | dispidABPArrayType
Property set: | PSETID_Address
Long ID (LID): | 0x00008029
Data type: | PT_LONG
Area: | Contact

Remarks

The value of the dispidABPArrayType property must be a combination of flags that specify the state of the contact object. Individual flags are specified in the following table. If this property is set, the dispidABPEmailList (PidLidAddressBookProviderEmailList) property must be set, as well. These two properties must be kept synchronized with each other. For example, if dispidABPArrayType has the bit "0x00000001 set", one of the values of dispidABPEmailList must be "0x00000000".

Bit | Description
0x00000001 | Email1 is defined for the contact.
0x00000002 | Email2 is defined for the contact.
0x00000004 | Email3 is defined for the contact.
0x00000008 | Business fax is defined for the contact.
0x00000010 | Home fax is defined for the contact.
0x00000020 | Primary fax is defined for the contact.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAddressBookProviderEmailList Canonical Property

 Copy code hover
[image]

PidLidAddressBookProviderEmailList Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies which electronic address properties are set on the contact.

Associated properties: | dispidABPEmailList
Property set: | PSETID_Address
Long ID (LID): | 0x00008028
Data type: | PT_MV_LONG
Area: | Contact

Remarks

Each PT_LONG value in this property must be unique in the property and must be set to one of the values in the following table. If this property is set, the dispidABPArrayType (PidLidAddressBookProviderArrayType) property must also be set. These two properties must be kept synchronized with each other. For example, if one of the values in dispidABPEmailList is "0x00000000", then dispidABPArrayType must have the bit "0x00000001" set.

Value | Description
0x00000000 | Email1 is defined for the contact.
0x00000001 | Email2 is defined for the contact.
0x00000002 | Email3 is defined for the contact.
0x00000003 | Business fax is defined for the contact.
0x00000004 | Home fax is defined for the contact.
0x00000005 | Primary fax is defined for the contact.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAddressCountryCode Canonical Property

 Copy code hover
[image]

PidLidAddressCountryCode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the country code of the contact's mailing address.

Associated properties: | dispidAddressCountryCode
Property set: | PSETID_Address
Long ID (LID): | 0x000080DD
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAgingDontAgeMe Canonical Property

 Copy code hover
[image]

PidLidAgingDontAgeMe Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a value of TRUE if the item will not be automatically archived.

Associated properties: | dispidAgingDontAgeMe
Property set: | PSETID_Common
Long ID (LID): | 0x0000850E
Data type: | PT_BOOLEAN
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointments and meetings.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAllAttendeesString Canonical Property

 Copy code hover
[image]

PidLidAllAttendeesString Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a list of all the attendees except for the organizer, including resources and unsendable attendees.

Associated properties: | dispidAllAttendeesString
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008238
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the attendee's display name. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAnniversaryEventEntryId Canonical Property

 Copy code hover
[image]

PidLidAnniversaryEventEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the entry identifier of the appointment that represents the contact's anniversary.

Associated properties: | dispidAnniversaryEventEID
Property set: | PSETID_Address
Long ID (LID): | 0x0000804E
Data type: | PT_BINARY
Area: | Contact

Remarks

The appointment specified by the dispidAnniversaryEventEID property must be linked to this contact by using the dispidContactLinkEntry (PidLidContactLinkEntry), dispidContactLinkSearchKey (PidLidContactLinkSearchKey), and dispidContactLinkName (PidLidContactLinkName) properties, as detailed in [MS-OXCMSG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentAuxiliaryFlags Canonical Property

 Copy code hover
[image]

PidLidAppointmentAuxiliaryFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a bit field that describes the auxiliary state of the object.

Associated properties: | dispidApptAuxFlags
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008207
Data type: | PT_LONG
Area: | Meetings

Remarks

This property is not required. Below are the individual flags that can be set.

C (auxApptFlagCopied, 0x00000001)

This flag indicates that the calendar object was copied from another calendar folder.

R (auxApptFlagForceMtgResponse, 0x00000002)

This flag on a meeting request indicates that the client or server should send a meeting response back to the organizer when a response is chosen.

F (auxApptFlagForwarded, 0x00000004)

This flag on a meeting request indicates that it was forwarded (including being forwarded by the organizer), rather than being an invitation from the organizer.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentColor Canonical Property

 Copy code hover
[image]

PidLidAppointmentColor Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the color to use when displaying the calendar.

Associated properties: | dispidApptColor
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008214
Data type: | PT_LONG
Area: | Calendar

Remarks

This property specifies the color to use when displaying the calendar. A client or server should set this value for backward compatibility with older clients. It may instead display the calendar based on the value of the Keywords (PidNameKeywords) property as specified in [MS-OXCMSG]. When set, the value must be one of the following.

Value | Color
0x00000000 | None
0x00000001 | Red
0x00000002 | Blue
0x00000003 | Green
0x00000004 | Grey
0x00000005 | Orange
0x00000006 | Cyan
0x00000007 | Olive
0x00000008 | Purple
0x00000009 | Teal
0x0000000A | Yellow

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentCounterProposal Canonical Property

 Copy code hover
[image]

PidLidAppointmentCounterProposal Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that this meeting response is a counter proposal.

Associated properties: | dispidApptCounterProposal
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008257
Data type: | PT_BOOLEAN
Area: | Meetings

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentDuration Canonical Property

 Copy code hover
[image]

PidLidAppointmentDuration Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the length of time, in minutes, when an appointment is scheduled.

Associated properties: | dispidApptDuration
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008213
Data type: | PT_LONG
Area: | Calendar

Remarks

The value must be the number of minutes between the value of the dispidApptStartWhole (PidLidAppointmentStartWhole) and the dispidApptEndWhole (PidLidAppointmentEndWhole) properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentEndWhole Canonical Property

 Copy code hover
[image]

PidLidAppointmentEndWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the date and time that an appointment ends.

Associated properties: | dispidApptEndWhole
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000820E
Data type: | PT_SYSTIME
Area: | Calendar

Remarks

This property corresponds to the dispidApptEndWhole property of the appointment in the Microsoft Office Outlook object model.

This specifies the end date and time for the event; it must be in Coordinated Universal Time (UTC) and must be greater than the value of the dispidApptStartWhole (PidLidAppointmentStartWhole) property. For a recurring series, the dispidApptEndWhole property is the end date and time of the first instance according to the recurrence pattern.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentLastSequence Canonical Property

 Copy code hover
[image]

PidLidAppointmentLastSequence Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates to the organizer the last sequence number that was sent to any attendee.

Associated properties: | dispidApptLastSequence
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008203
Data type: | PT_LONG
Area: | Meetings

Remarks

This property has no meaning for an attendee.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentMessageClass Canonical Property

 Copy code hover
[image]

PidLidAppointmentMessageClass Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the PR_MESSAGE_CLASS (PidTagMessageClass) property of the meeting that is to be generated from the meeting request.

Associated properties: | dispidApptMessageClass
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000024
Data type: | PT_TSTRING
Area: | Meetings

Remarks

The value of this property must either be "IPM.Appointment" or be prefixed with "IPM.Appointment.". This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentNotAllowPropose Canonical Property

 Copy code hover
[image]

PidLidAppointmentNotAllowPropose Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether attendees are not allowed to propose a new date/time for the meeting.

Associated properties: | dispidApptNotAllowPropose
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000825A
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of FALSE, or the absence of this property indicates that the attendees are allowed to propose a new date/time.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentProposalNumber Canonical Property

 Copy code hover
[image]

PidLidAppointmentProposalNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of attendees who have sent counter proposals that have not been accepted or rejected by the organizer.

Associated properties: | dispidApptProposalNum
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008259
Data type: | PT_LONG
Area: | Meetings

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentProposedDuration Canonical Property

 Copy code hover
[image]

PidLidAppointmentProposedDuration Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the proposed value for the dispidApptDuration (PidLidAppointmentDuration) property for a counter proposal.

Associated properties: | dispidApptProposedDuration
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008256
Data type: | PT_LONG
Area: | Meetings

Remarks

If set, it must be equal to the number of minutes between the dispidApptProposedStartWhole (PidLidAppointmentProposedStartWhole) and dispidApptProposedEndWhole (PidLidAppointmentProposedEndWhole) properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentProposedEndWhole Canonical Property

 Copy code hover
[image]

PidLidAppointmentProposedEndWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the proposed value for the dispidApptEndWhole (PidLidAppointmentEndWhole) property for a counter proposal.

Associated properties: | dispidApptProposedEndWhole
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008251
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

This value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentProposedStartWhole Canonical Property

 Copy code hover
[image]

PidLidAppointmentProposedStartWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the proposed value for dispidApptStartWhole (PidLidAppointmentStartWhole) for a counter proposal.

Associated properties: | dispidApptProposedStartWhole
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008250
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

This value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentRecur Canonical Property

 Copy code hover
[image]

PidLidAppointmentRecur Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the dates and times when a recurring series occurs by using one of the recurrence patterns and ranges that are specified in [MS-OXOCAL].

Associated properties: | dispidApptRecur
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008216
Data type: | PT_BINARY
Area: | Calendar

Remarks

This property specifies the dates and times when a recurring series occurs by using one of the recurrence patterns and ranges detailed in [MS-OXOCAL]. The value of this property also contains information about both modified and deleted exceptions; information such as dates, subject, location, and several other properties of exceptions. The binary data in this property for recurring calendar items is stored as the AppointmentRecurrencePattern structure. This property must not exist on single instance calendar items.

There are some limitations to recurrences:

  • Multiple instances must not start on the same day.

  • Occurrences must not overlap. Specifically, an exception that modifies the start date of an instance in the recurring series must occur on a date that is after the end of the prior instance and the start of the next instance in the recurring series. The same is true if the prior or next instances in the recurring series are exceptions.

The schedule of a recurring series is determined by its recurrence pattern and range.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentReplyName Canonical Property

 Copy code hover
[image]

PidLidAppointmentReplyName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user who last replied to the meeting request or meeting update object.

Associated properties: | dispidApptReplyName
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008230
Data type: | PT_UNICODE
Area: | Meetings

Remarks

This property is only set for a delegator when a delegate responded. The value is equal to the PR_MAILBOX_OWNER_NAME (PidTagMailboxOwnerName) property for the delegate's store. This property has no meaning for the organizer. For details on PR_MAILBOX_OWNER_NAME, see store object protocol specified in [MS-OXCSTOR].

Related Resources

Protocol Specifications

[MS-OXCDATA]

Provides data type definitions.

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentReplyTime Canonical Property

 Copy code hover
[image]

PidLidAppointmentReplyTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time when the attendee responded to a received meeting request or meeting update.

Associated properties: | dispidApptReplyTime
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008220
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

The value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentSequence Canonical Property

 Copy code hover
[image]

PidLidAppointmentSequence Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the sequence number of a Meeting object.

Associated properties: | dispidApptSequence
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008201
Data type: | PT_LONG
Area: | Meetings

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentSequenceTime Canonical Property

 Copy code hover
[image]

PidLidAppointmentSequenceTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time at which this property was last modified.

Associated properties: | dispidApptSeqTime
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008202
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

The value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentStartWhole Canonical Property

 Copy code hover
[image]

PidLidAppointmentStartWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the date and time when an appointment begins.

Associated properties: | dispidApptStartWhole
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000820D
Data type: | PT_SYSTIME
Area: | Calendar

Remarks

This property specifies the start date and time of the event. This property must be in Coordinated Universal Time (UTC) and must be less than the value of the dispidApptEndWhole (PidLidAppointmentEndWhole) property. For a recurring series, this property is the start date and time of the first instance according to the recurrence pattern.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentStateFlags Canonical Property

 Copy code hover
[image]

PidLidAppointmentStateFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a bit field that describes the state of the object.

Associated properties: | dispidApptStateFlags
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008217
Data type: | PT_LONG
Area: | Meetings

Remarks

This property is not required. Below are the individual flags that can be set.

M (asfMeeting, 0x00000001)

This flag indicates that the object is a meeting object or a meeting-related object.

R (asfReceived, 0x00000002)

This flag indicates that the represented object was received from someone else.

C (asfCanceled, 0x00000004)

This flag indicates that the meeting object represented by the object has been canceled.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentSubType Canonical Property

 Copy code hover
[image]

PidLidAppointmentSubType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether or not the event is all day.

Associated properties: | dispidApptSubType
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008215
Data type: | PT_BOOLEAN
Area: | Calendar

Remarks

This property specifies whether or not the event is an all-day event, as specified by the user. A value of TRUE indicates that the event is an all-day event, in which case the start time and end time must be midnight so that the duration is a multiple of 24 hours and is at least 24 hours. A value of FALSE or the absence of this property indicates the event is not an all-day event. The client or server must not infer the value as TRUE when a user happens to create an event that is 24 hours, even if the event starts and ends at midnight.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentTimeZoneDefinitionEndDisplay Canonical Property

 Copy code hover
[image]

PidLidAppointmentTimeZoneDefinitionEndDisplay Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a stream that maps to the persisted format of a TZDEFINITION structure, which stores the description for the time zone that is used when the end time of a single-instance appointment or meeting request is selected.

Associated properties: | dispidApptTZDefEndDisplay
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000825F
Data type: | PT_BINARY
Area: | Calendar

Remarks

Microsoft Office Outlook 2003 or earlier, and solutions that are based on Collaboration Data Objects (CDO) 1.2.1 and that have not run the calendar update tool for Outlook or Microsoft Exchange Server, store the start time and end time of single-instance appointments and meeting requests in Coordinated Universal Time (UTC). These clients do not store any information for the time zone where the appointment or meeting request is created.

Versions of Microsoft Outlook since Microsoft Office Outlook 2007, and solutions based on CDO 1.2.1 that have run the Outlook or Exchange Server calendar update tool use dispidApptTZDefEndDisplay to store the time zone for the end time. dispidApptTZDefEndDisplay shows the appointment or meeting in the original time zone that it was scheduled, and determines whether the end time should be adjusted if the rules of the time zone change. If this property is missing, the time zone specified by the dispidApptTZDefStartDisplay (PidLidAppointmentTimeZoneDefinitionStartDisplay) property is used. If dispidApptTZDefStartDisplay is missing or invalid, the current local time zone is assumed. dispidApptTZDefEndDisplay is used for display purposes only and is not used in recurrence expansion.

A parser must be careful when it reads a stream obtained from dispidApptTZDefEndDisplay, or when it persists TZDEFINITION to a stream for commitment to a binary property such as dispidApptTZDefEndDisplay. For more information, see About persisting TZDEFINITION to a stream to commit to a binary property.

dispidApptTZDefEndDisplay specifies time zone information for the dispidApptEndWhole (PidLidAppointmentEndWhole) property. The format, constraints, and computation of dispidApptTZDefEndDisplay are the same as specified in the dispidApptTZDefStartDisplay property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentTimeZoneDefinitionRecur Canonical Property

 Copy code hover
[image]

PidLidAppointmentTimeZoneDefinitionRecur Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a stream that maps to the persisted format of a TZDEFINITION structure, which stores the description for the time zone that is used when a recurring appointment or meeting request is created.

Associated properties: | dispidApptTZDefRecur
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008260
Data type: | PT_BINARY
Area: | Calendar

Remarks

Versions of Microsoft Outlook since Microsoft Office Outlook 2007, and solutions based on Collaboration Data Objects (CDO) 1.2.1 that have run the Outlook or Exchange Server calendar update tool use the dispidApptTZDefRecur and dispidTimeZoneStruct (PidLidTimeZoneStruct) properties to determine whether the recurring meeting should be adjusted if the rules of the time zone change. These properties must be synchronized, because older clients may still manipulate the dispidTimeZoneStruct property. To detect whether the two properties are synchronized, the wFlags member for the rule that matches dispidTimeZoneStruct should have the TZRULE_FLAG_RECUR_CURRENT_TZREG flag set. If this flag is not set, or it is set and the rule in the dispidTimeZoneStruct property does not match the marked rule, the dispidApptTZDefRecur property should be discarded and dispidTimeZoneStruct should be used instead.

When you write both the dispidApptTZDefRecur and dispidTimeZoneStruct properties to a new recurring meeting, or, when you make an arbitrary choice to use the dispidTimeZoneStruct property, the current definition for the time zone (according to the Windows registry) should be used.

A parser must be careful when it reads a stream that is obtained from dispidApptTZDefRecur, or when it persists TZDEFINITION to a stream for commitment to a binary property such as dispidApptTZDefRecur. For more information, see About persisting TZDEFINITION to a stream to commit to a binary property.

dispidApptTZDefRecur specifies time zone information that describes how to convert the meeting date and time on a recurring series to and from Coordinated Universal Time (UTC). If this property is set but it has data that is inconsistent with the data represented by dispidTimeZoneStruct, the client must use dispidTimeZoneStruct instead of dispidApptTZDefRecur. If dispidApptTZDefRecur is not set, the PidLidTimeZoneStruct property will be used instead. The fields in this BLOB are encoded in little-endian byte order.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentTimeZoneDefinitionStartDisplay Canonical Property

 Copy code hover
[image]

PidLidAppointmentTimeZoneDefinitionStartDisplay Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a stream that maps to the persisted format of a TZDEFINITION structure, which stores the description for the time zone that is used when the start time of a single-instance appointment or meeting request is selected.

Associated properties: | dispidApptTZDefStartDisplay
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000825E
Data type: | PT_BINARY
Area: | Calendar

Remarks

Microsoft Office Outlook 2003 or earlier, and solutions that are based on Collaboration Data Objects (CDO) 1.2.1 and that have not run the calendar update tool for Outlook or Microsoft Exchange Server, store the start time and end time of single-instance appointments and meeting requests in Coordinated Universal Time (UTC). These clients do not store any information for the time zone in which the appointment or meeting request is created.

Versions of Outlook since Microsoft Office Outlook 2007, and solutions based on CDO 1.2.1 that have run the Outlook or Exchange Server calendar update tool use this property to store the time zone for the start time. The dispidApptTZDefStartDisplay property shows the appointment or meeting in the original time zone that it was scheduled. It determines whether the start time should be adjusted if the rules of the time zone change. If this property is missing, the current local time zone is assumed. This property is used for display purposes only and is not used in recurrence expansion.

A parser must be careful when it reads a stream obtained from this property, or when it persists TZDEFINITION to a stream for commitment to a binary property such as dispidApptTZDefStartDisplay. For more information, see About persisting TZDEFINITION to a stream to commit to a binary property.

This property specifies time zone information for the dispidApptStartWhole (PidLidAppointmentStartWhole) property. The value of dispidApptTZDefStartDisplay is used to convert the start date and time from UTC to the local time zone for display purposes. For each TZRULE specified by this property, the TZRULE_FLAG_RECUR_CURRENT_TZREG flag must not be set. For example, if the TZRULE is the effective rule, the value of the field, TZRULE must be "0x0002"; otherwise, it must be "0x0000".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications..

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAppointmentUnsendableRecipients Canonical Property

 Copy code hover
[image]

PidLidAppointmentUnsendableRecipients Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of unsendable attendees.

Associated properties: | dispidApptUnsendableRecips
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000823D
Data type: | PT_BINARY
Area: | Meetings

Remarks

This property is not required but should be set. Its format is detailed in [MS-OXOCAL].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAttendeeCriticalChange Canonical Property

 Copy code hover
[image]

PidLidAttendeeCriticalChange Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time when the meeting-related object was sent.

Associated properties: | LID_ATTENDEE_CRITICAL_CHANGE
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000001
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

The value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAutoFillLocation Canonical Property

 Copy code hover
[image]

PidLidAutoFillLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that the value of the dispidLocation (PidLidLocation) property is set to the PR_DISPLAY_NAME (PidTagDisplayName) property from the RecipientRow that represents a resource.

Associated properties: | dispidAutoFillLocation
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000823A
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

For more details on RecipientRow, see the Message and Attachment Object protocol as specified in [MS-OXCMSG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAutoLog Canonical Property

 Copy code hover
[image]

PidLidAutoLog Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether to create a journal for each action associated with this contact.

Associated properties: | dispidAutoLog
Property set: | PSETID_Address
Long ID (LID): | 0x00008025
Data type: | PT_BOOLEAN
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution list.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidAutoProcessState Canonical Property

 Copy code hover
[image]

PidLidAutoProcessState Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the options that are used in automatic processing of e-mail messages.

Associated properties: | dispidSniffState
Property set: | PSETID_Common
Long ID (LID): | 0x0000851A
Data type: | PT_LONG
Area: | General messaging

Remarks

The property may be absent, in which case the default value of "0x00000000" is used. If set, this property must be set to one of the values in the following table.

Value | Description
0x00000000 | Do not automatically process the message.
0x00000001 | Process the message automatically or when the message is opened.
0x00000002 | Process the message only when the message is opened.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidBilling Canonical Property

 Copy code hover
[image]

PidLidBilling Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the billing information associated with an item.

Associated properties: | dispidBilling
Property set: | PSETID_Common
Long ID (LID): | 0x00008535
Data type: | PT_UNICODE
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidBirthdayEventEntryId Canonical Property

 Copy code hover
[image]

PidLidBirthdayEventEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryId of an optional appointment that represents the contact's birthday.

Associated properties: | dispidBirthdayEventEID
Property set: | PSETID_Address
Long ID (LID): | 0x0000804D
Data type: | PT_BINARY
Area: | Contact

Remarks

The appointment this is specified by this property must be linked to this contact by using the dispidApptStateFlags (PidLidContactLinkEntry), dispidContactLinkSearchKey (PidLidContactLinkSearchKey), and dispidContactLinkName (PidLidContactLinkName) properties, as specified in [MS-OXCMSG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidBusinessCardCardPicture Canonical Property

 Copy code hover
[image]

PidLidBusinessCardCardPicture Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the image to use on a business card.

Associated properties: | dispidBCCardPicture
Property set: | PSETID_Address
Long ID (LID): | 0x00008041
Data type: | PT_BINARY
Area: | Contact

Remarks

The value of this property must be either a portable network graphics (PNG) or JPEG stream. This property should be used in conjunction with the dispidBCDisplayDefinition (PidLidBusinessCardDisplayDefinition) property as follows: dispidBCCardPicture should not be present on a contact if dispidBCDisplayDefinition is not present. This property also should not be present if the data in dispidBCCardPicture does not require a card image.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidBusinessCardDisplayDefinition Canonical Property

 Copy code hover
[image]

PidLidBusinessCardDisplayDefinition Canonical Property
See also Send feedback

Published: July 16, 2012

Contains user-customization details for displaying a contact as a business card.

Associated properties: | dispidBCDisplayDefinition
Property set: | PSETID_Address
Long ID (LID): | 0x00008040
Data type: | PT_BINARY
Area: | Contact

Remarks

The layout of a business card can be represented as an image and a number of text fields. The image can be either a contact photo, or a card picture. Text fields consist of a value from another property set on the contact and an optional customized label string provided by the user. Note that multi-byte values are stored in little-endian format in the buffer.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidBusyStatus Canonical Property

 Copy code hover
[image]

PidLidBusyStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the user's availability for an appointment.

Associated properties: | dispidBusyStatus
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008205
Data type: | PT_LONG
Area: | Calendar

Remarks

This property specifies the availability of a user for the event described by the object and must be one of the values specified below.

Value | Description
0x00000000 | The user is available.
0x00000001 | The user has a tentative event scheduled.
0x00000002 | The user is busy.
0x00000003 | The user is out of office.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCalendarType Canonical Property

 Copy code hover
[image]

PidLidCalendarType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the value of the CalendarType field from the dispidApptRecur (PidLidAppointmentRecur) property.

Associated properties: | LID_CALENDAR_TYPE
Property set: | PSETID_Meeting
Long ID (LID): | 0x0000001C
Data type: | PT_LONG
Area: | Meetings

Remarks

When the meeting request represents a recurring series or an exception, this is the value of the CalendarType field from the dispidApptRecur property. Otherwise, this property is not set and assumed to be 0.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCategories Canonical Property

 Copy code hover
[image]

PidLidCategories Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a list of categories for an item.

Associated properties: | dispidCategories
Property set: | PS_PUBLIC_STRINGS
Long ID (LID): | 0x00002328
Data type: | PT_MV_UNICODE
Area: | Common

Remarks

To generate a keywords header field, clients must set the value of this property to the desired values. This property has multiple strings; each category should be mapped to a single keyword.

Multipurpose Internet Mail Extensions (MIME) writers should copy each sub-value of this property to a separate keyword in the Keywords header field, with a comma (U+002C) and space (U+0020) separating each keyword. MIME writers may drop this property instead of copying it to the keywords header field, in order to avoid conflict among different sets of categories in different organizations.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCcAttendeesString Canonical Property

 Copy code hover
[image]

PidLidCcAttendeesString Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of all the sendable attendees who are also optional attendees.

Associated properties: | dispidCCAttendeesString
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000823C
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the PR_DISPLAY_NAME (PidTagDisplayName) property of the attendee's address book. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidChangeHighlight Canonical Property

 Copy code hover
[image]

PidLidChangeHighlight Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a bit field that indicates how the meeting object changed.

Associated properties: | dispidChangeHighlight
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008204
Data type: | PT_LONG
Area: | Meetings

Remarks

This property is not required. The individual flags that can be set are detailed in [MS-OXOCAL].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClassification Canonical Property

 Copy code hover
[image]

PidLidClassification Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the name of the message classification.

Associated properties: | dispidClassification
Property set: | PSETID_Common
Long ID (LID): | 0x000085B6
Data type: | PT_UNICODE
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClassificationDescription Canonical Property

 Copy code hover
[image]

PidLidClassificationDescription Canonical Property
See also Send feedback

Published: July 16, 2012

Describes what the message classification intends to achieve.

Associated properties: | dispidClassDesc
Property set: | PSETID_Common
Long ID (LID): | 0x000085B7
Data type: | PT_UNICODE
Area: | General messaging

Remarks

For additional information, see How to Deploy Message Classification for Outlook 2007

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClassificationGuid Canonical Property

 Copy code hover
[image]

PidLidClassificationGuid Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a globally unique identifier (GUID) of an existing message classification.

Associated properties: | dispidClassGuid
Property set: | PSETID_Common
Long ID (LID): | 0x000085B8
Data type: | PT_UNICODE
Area: | General messaging

Remarks

For additional information, see How to Deploy Message Classification for Outlook 2007

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClassificationKeep Canonical Property

 Copy code hover
[image]

PidLidClassificationKeep Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the message classification should persist with the message if the message is forwarded or replied.

Associated properties: | dispidClassKeep
Property set: | PSETID_Common
Long ID (LID): | 0x000085BA
Data type: | PT_BOOLEAN
Area: | General messaging

Remarks

For additional information, see How to Deploy Message Classification for Outlook 2007.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClassified Canonical Property

 Copy code hover
[image]

PidLidClassified Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that a message is classified.

Associated properties: | dispidClassified
Property set: | PSETID_Common
Long ID (LID): | 0x000085B5
Data type: | PT_BOOLEAN
Area: | General messaging

Remarks

For additional information, see How to Deploy Message Classification for Outlook 2007

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCleanGlobalObjectId Canonical Property

 Copy code hover
[image]

PidLidCleanGlobalObjectId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the clean global ObjectID.

Associated properties: | dispidCleanGlobalObjId
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000023
Data type: | PT_BINARY
Area: | Meetings

Remarks

The format of this property is the same as that of LID_GLOBAL_OBJID (PidLidGlobalObjectId). The value of this property must be equal to the value of LID_GLOBAL_OBJID, except the YH, YL, M, and D fields must be zero. All objects that refer to an Instance of a recurring series (including an orphan instance), as well as the recurring series itself, will have the same value for this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClipEnd Canonical Property

 Copy code hover
[image]

PidLidClipEnd Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the end date and time of the event in Coordinated Universal Time (UTC) for single instance calendar objects.

Associated properties: | dispidClipEnd
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008236
Data type: | PT_SYSTIME
Area: | Calendar

Remarks

For single instance calendar objects, it specifies the end date and time of the event in UTC. For a recurring series, this property specifies midnight on the date of the last instance of the recurring series in UTC, unless the recurring series has no end, in which case the value must be 31 August 4500, 11:59 p.m.

The value of this property must be set to the value of the dispidApptEndWhole (PidLidAppointmentEndWhole).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidClipStart Canonical Property

 Copy code hover
[image]

PidLidClipStart Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the start date and time of the event in Coordinated Universal Times (UTC) for single instance calendar objects, and specifies midnight on the date of the first instance in UTC for a recurring series.

Associated properties: | dispidClipStart
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008235
Data type: | PT_SYSTIME
Area: | Calendar

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCommonEnd Canonical Property

 Copy code hover
[image]

PidLidCommonEnd Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the end date and time of a message.

Associated properties: | dispidCommonEnd
Property set: | PSETID_Common
Long ID (LID): | 0x00008517
Data type: | PT_SYSTIME
Area: | General messaging

Remarks

This property indicates the end time for an item. It must be greater than or equal to the value of the dispidCommonStart (PidLidCommonStart) property.

This value must be the Coordinated Universal Time (UTC) equivalent of the dispidTaskDueDate (PidLidTaskDueDate) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCommonStart Canonical Property

 Copy code hover
[image]

PidLidCommonStart Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the start date and time of a message.

Associated properties: | dispidCommonStart
Property set: | PSETID_Common
Long ID (LID): | 0x00008516
Data type: | PT_SYSTIME
Area: | General messaging

Remarks

This property indicates the start time for an item. It must be less than or equal to the value of the dispidCommonEnd (PidLidCommonEnd) property.

The value of this property must be the Coordinated Universal Time (UTC) equivalent of the dispidTaskStartDate (PidLidTaskStartDate) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCompanies Canonical Property

 Copy code hover
[image]

PidLidCompanies Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the names of the companies that are associated with an item.

Associated properties: | dispidCompanies
Property set: | PSETID_Common
Long ID (LID): | 0x00008539
Data type: | PT_MV_UNICODE
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactCharacterSet Canonical Property

 Copy code hover
[image]

PidLidContactCharacterSet Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the character set used for this contact.

Associated properties: | dispidContactCharSet
Property set: | PSETID_Address
Long ID (LID): | 0x00008023
Data type: | PT_LONG
Area: | Contact

Remarks

Applications can use this property to aid in generating a character-set dependent list of choices for the dispidFileUnder (PidLidFileUnder) , dispidFileUnderList (PidLidFileUnderList) , and dispidFileUnderId (PidLidFileUnderId) properties. If the value of the property is "0x00000000" or "0x00000001", applications should treat the property as not being set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactItemData Canonical Property

 Copy code hover
[image]

PidLidContactItemData Canonical Property
See also Send feedback

Published: July 16, 2012

Used to display the contact information.

Associated properties: | dispidContactItemData
Property set: | PSETID_Address
Long ID (LID): | 0x00008007
Data type: | PT_MV_LONG
Area: | Contact

Remarks

If present, the property must have six entries, each corresponding to a visible field in the application's user interface.

One-based index into the multi-valued property | The value must be one of the following | Description
1 | 0x00000001 | The application should display the contact's home address.
1 | 0x00000002 or 0x00000000 | The application should display the contact's work.
1 | 0x00000003 | The application should display the contact's other address.
2 | 0x00008080 | The application should display Email1.
2 | 0x00008090 | The application should display Email2.
2 | 0x000080A0 | The application should display Email3.
3,4,5,6 | PropertyID of any of the telephone properties or any of the fax numbers that are specified in [MS-OXOCNTC]. | The application should display the corresponding property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactLinkEntry Canonical Property

 Copy code hover
[image]

PidLidContactLinkEntry Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the list of Address Book EntryIDs linked to by this message object.

Associated properties: | dispidContactLinkEntry
Property set: | PSETID_Common
Long ID (LID): | 0x00008585
Data type: | PT_BINARY
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactLinkName Canonical Property

 Copy code hover
[image]

PidLidContactLinkName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the elements of the dispidContacts (PidLidContacts) property.

Associated properties: | dispidContactLinkName
Property set: | PSETID_Common
Long ID (LID): | 0x00008586
Data type: | PT_UNICODE
Area: | Contact

Remarks

The elements in the dispidContactLinkName property are separated by a semicolon and a space ("; ").

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactLinkSearchKey Canonical Property

 Copy code hover
[image]

PidLidContactLinkSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the list of SearchKeys for the contact linked to by this message object.

Associated properties: | dispidContactLinkSearchKey
Property set: | PSETID_Common
Long ID (LID): | 0x00008584
Data type: | PT_BINARY
Area: | Contact

Remarks

Length in bytes | Description | Notes
2 | ContactEntryCount | None
variable | SearchKey data | Repeats ContactEntryCount times

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContacts Canonical Property

 Copy code hover
[image]

PidLidContacts Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the names of contacts associated with the item.

Associated properties: | dispidContacts
Property set: | PSETID_Common
Long ID (LID): | 0x0000853A
Data type: | PT_MV_UNICODE
Area: | General messaging

Remarks

This property contains the PR_DISPLAY_NAME (PidTagDisplayName) property of each Address Book EntryID that is referenced in the value of dispidContactLinkEntry (PidLidContactLinkEntry) property. It may include names not referenced in dispidContactLinkEntry.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactUserField1 Canonical Property

 Copy code hover
[image]

PidLidContactUserField1 Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the first field on the contact that is intended for miscellaneous use for the contact.

Associated properties: | dispidContactUserField1
Property set: | PSETID_Address
Long ID (LID): | 0x0000804F
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property contains text that is unrelated to any other contact-specific property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactUserField2 Canonical Property

 Copy code hover
[image]

PidLidContactUserField2 Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the second field on the contact that is intended for miscellaneous use for the contact.

Associated properties: | dispidContactUserField2
Property set: | PSETID_Address
Long ID (LID): | 0x00008050
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property contains text that is unrelated to any other contact-specific property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactUserField3 Canonical Property

 Copy code hover
[image]

PidLidContactUserField3 Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the third field on the contact that is intended for miscellaneous use for the contact.

Associated properties: | dispidContactUserField3
Property set: | PSETID_Address
Long ID (LID): | 0x00008051
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property contains text that is unrelated to any other contact-specific property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidContactUserField4 Canonical Property

 Copy code hover
[image]

PidLidContactUserField4 Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the fourth field on the contact that is intended for miscellaneous use for the contact.

Associated properties: | dispidContactUserField4
Property set: | PSETID_Address
Long ID (LID): | 0x00008052
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property contains text that is unrelated to any other contact-specific property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCurrentVersion Canonical Property

 Copy code hover
[image]

PidLidCurrentVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a long that represents the build number of the Outlook application for an item.

Associated properties: | dispidCurrentVersion
Property set: | PSETID_Common
Long ID (LID): | 0x00008552
Data type: | PT_LONG
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCurrentVersionName Canonical Property

 Copy code hover
[image]

PidLidCurrentVersionName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a String that indicates the major and minor version number of the Outlook application for an item.

Associated properties: | dispidCurrentVersionName
Property set: | PSETID_Common
Long ID (LID): | 0x00008554
Data type: | TBD
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidCustomFlag Canonical Property

 Copy code hover
[image]

PidLidCustomFlag Canonical Property
See also Send feedback

Published: July 16, 2012

A bitmask that specifies how a message is customized, for example, saved with custom properties.

Associated properties: | dispidCustomFlag
Long ID (LID): | 0x00008251
Data type: | PT_LONG

Remarks

To retrieve the value of this property, first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value.

Possible Flags are as follows:

Constant | Value
INSP_ONEOFFFLAGS | 0x0D000000
INSP_PROPDEFINITION | 0x02000000

When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed to by the input parameter lppPropNames.

Member | Value
lpGuid: | PSETID_Common
ulKind: | MNID_ID
Kind.lID: | dispidCustomFlag

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidDistributionListChecksum Canonical Property

 Copy code hover
[image]

PidLidDistributionListChecksum Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the 32-bit cyclic redundancy check (CRC-32) polynomial checksum for a personal distribution list.

Associated properties: | dispidDLChecksum
Property set: | PSETID_Address
Long ID (LID): | 0x0000804C
Data type: | PT_LONG
Area: | Contact

Remarks

The value of this property can be used to detect when the dispidDLMembers (PidLidDistributionListMembers) property was updated without updating the other personal distribution list member properties by computing the CRC-32 on the existing value of dispidDLMembers and comparing it with the value of the dispidDLChecksum property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidDistributionListMembers Canonical Property

 Copy code hover
[image]

PidLidDistributionListMembers Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the list of EntryIds of the objects that correspond to the members of the personal distribution list.

Associated properties: | dispidDLMembers
Property set: | PSETID_Address
Long ID (LID): | 0x00008055
Data type: | PT_MV_BINARY
Area: | Contact

Remarks

Members of the personal distribution list can be other personal distribution lists, electronic addresses contained in a contact, Global Address List users or distribution lists, or one-off e-mail addresses. The format of each EntryId must be either a one-off EntryId, as specified in [MS-OXCDATA], or a wrapped EntryId.

When setting this property, the client or the server must ensure its total size is less than 15,000 bytes.

This property specifies the list of one-off EntryIds that correspond to the members of the personal distribution list. These one-off EntryIds encapsulate display names and e-mail addresses of the personal distribution list members.

If the client or the server set this property, it must be synchronized with this property dispidDLMembers for each entry in the dispidDLOneOffMembers (PidLidDistributionListOneOffMembers) property, there must be an entry in the same position in the dispidDLOneOffMembers.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidDistributionListName Canonical Property

 Copy code hover
[image]

PidLidDistributionListName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the name of the personal distribution list.

Associated properties: | dispidDLName
Property set: | PSETID_Address
Long ID (LID): | 0x00008053
Data type: | PT_UNICODE
Area: | Contact

Remarks

The value of this property should be the same as the value of the PR_DISPLAY_NAME (PidTagDisplayName) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidDistributionListOneOffMembers Canonical Property

 Copy code hover
[image]

PidLidDistributionListOneOffMembers Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the list of one-off EntryIds that correspond to the members of the personal distribution list.

Associated properties: | dispidDLOneOffMembers
Property set: | PSETID_Address
Long ID (LID): | 0x00008054
Data type: | PT_MV_BINARY
Area: | Contact

Remarks

These one-off EntryIds encapsulate display names and e-mail addresses of the personal distribution list members.

If the client or the server set this property, it must be synchronized with the dispidDLMembers (PidLidDistributionListMembers) property: for each entry in the dispidDLOneOffMembers property, there must be an entry in the same position in the dispidDLMembers property.

When setting dispidDLOneOffMembers, the client or the server must ensure that its total size is less than 15,000 bytes in size.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail1AddressType Canonical Property

 Copy code hover
[image]

PidLidEmail1AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type of the first e-mail address.

Associated properties: | dispidEmail1AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x00008082
Data type: | PT_UNICODE
Area: | Contact

Remarks

If present, this property value must be a valid address type.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail1DisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail1DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-readable display name for the first e-mail address.

Associated properties: | dispidEmail1DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x00008080
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail1EmailAddress Canonical Property

 Copy code hover
[image]

PidLidEmail1EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the first e-mail address of the contact.

Associated properties: | dispidEmail1EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x00008083
Data type: | PT_UNICODE
Area: | Contact

Remarks

The value of this property must be appropriate for the address type specified for this e-mail address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail1OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail1OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the first display name that corresponds to the e-mail address that is specified for the contact.

Associated properties: | dispidEmail1OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x00008084
Data type: | PT_UNICODE
Area: | Contact

Remarks

If the value of the dispidEmail1AddrType (PidLidEmail1AddressType) property is "SMTP", the value of the respective dispidEmail1OriginalDisplayName property should equal the value of the respective dispidEmail1EmailAddress (PidLidEmail1EmailAddress) property. This property displays an alternative user-friendly address that is equivalent to the one in the dispidEmail1EmailAddress property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail1OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidEmail1OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryId of the object that corresponds to the first e-mail address.

Associated properties: | dispidEmail1OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x00008085
Data type: | PT_BINARY
Area: | Contact

Remarks

The value of this property must be either a one-off EntryId for this electronic address or a valid Address Book object EntryId.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail2AddressType Canonical Property

 Copy code hover
[image]

PidLidEmail2AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type of the second e-mail address.

Associated properties: | dispidEmail2AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x00008092
Data type: | PT_UNICODE
Area: | Contact

Remarks

If present, this property value must be a valid address type.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail2DisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail2DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-readable display name for the second e-mail address.

Associated properties: | dispidEmail2DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x00008090
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail2EmailAddress Canonical Property

 Copy code hover
[image]

PidLidEmail2EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the second e-mail address of the contact.

Associated properties: | dispidEmail2EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x00008093
Data type: | PT_UNICODE
Area: | Contact

Remarks

The value of this property must be appropriate for the address type specified for this e-mail address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail2OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail2OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the second display name that corresponds to the e-mail address specified for the contact.

Associated properties: | dispidEmail2OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x00008094
Data type: | PT_UNICODE
Area: | Contact

Remarks

If the value of the dispidEmail2AddrType (PidLidEmail2AddressType) property is "SMTP", the value of the respective PidLidEmail2OriginalDisplayName property should equal the value of the respective dispidEmail2EmailAddress (PidLidEmail2EmailAddress) property. The purpose of this property is to display an alternative user-friendly address that is equivalent to the one in the dispidEmail2EmailAddress.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail2OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidEmail2OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryId of the object that corresponds to the second e-mail address.

Associated properties: | dispidEmail2OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x00008095
Data type: | PT_BINARY
Area: | Contact

Remarks

The value of this property must be either a one-off EntryId for this electronic address or a valid Address Book object EntryId.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail3AddressType Canonical Property

 Copy code hover
[image]

PidLidEmail3AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type of the third e-mail address.

Associated properties: | dispidEmail3AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x000080A2
Data type: | PT_UNICODE
Area: | Contact

Remarks

If present, this property value must be a valid address type.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail3DisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail3DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-readable display name for the third e-mail address.

Associated properties: | dispidEmail3DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080A0
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail3EmailAddress Canonical Property

 Copy code hover
[image]

PidLidEmail3EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the third e-mail address of the contact.

Associated properties: | dispidEmail3EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x000080A3
Data type: | PT_UNICODE
Area: | Contact

Remarks

The value of this property must be appropriate for the address type specified for this e-mail address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail3OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidEmail3OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the third display name that corresponds to the e-mail address that is specified for the contact.

Associated properties: | dispidEmail3OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080A4
Data type: | PT_UNICODE
Area: | Contact

Remarks

If the value of the dispidEmail3AddrType (PidLidEmail3AddressType) property is "SMTP", the value of the respective dispidEmail3OriginalDisplayName property should equal the value of the respective dispidEmail3EmailAddress (PidLidEmail3EmailAddress). The purpose of this property is to display an alternative user-friendly address that is equivalent to the one in the dispidEmail3EmailAddress.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidEmail3OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidEmail3OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryId of the object that corresponds to the third e-mail address.

Associated properties: | dispidEmail3OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080A5
Data type: | PT_BINARY
Area: | Contact

Remarks

The value of this property must be either a one-off EntryId for this electronic address or a valid Address Book object EntryId.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidExceptionReplaceTime Canonical Property

 Copy code hover
[image]

PidLidExceptionReplaceTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time within the recurrence pattern that the exception will replace.

Associated properties: | dispidExceptionReplaceTime
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008228
Data type: | PT_SYSTIME
Area: | Calendar

Remarks

The value must be specified in Coordinated Universal Time (UTC). This property allows the exception attachment object to be found for a particular instance.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1AddressType Canonical Property

 Copy code hover
[image]

PidLidFax1AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type for the business fax address for a contact.

Associated properties: | dispidFax1AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x000080B2
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to "FAX".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1DisplayName Canonical Property

 Copy code hover
[image]

PidLidFax1DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the display name of the business fax address for a contact.

Associated properties: | dispidFax1DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080B0
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1EmailAddress Canonical Property

 Copy code hover
[image]

PidLidFax1EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail address of the contact's business fax.

Associated properties: | dispidFax1EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x000080B3
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, should contain a user-readable display name, followed by the "@" character, followed by a fax number.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1EmailType Canonical Property

 Copy code hover
[image]

PidLidFax1EmailType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail type of the contact's business fax address.

Associated properties: | dispidFax1EmailType
Property set: | PSETID_Address
Long ID (LID): | 0x000080B7
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1EntryId Canonical Property

 Copy code hover
[image]

PidLidFax1EntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryID of the contact's business fax address.

Associated properties: | dispidFax1EntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080B1
Data type: | PT_BINARY
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidFax1OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original display name of the contact's business fax address.

Associated properties: | dispidFax1OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080B4
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to the same value as the PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidFax1OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original EntryID of the contact's business fax address.

Associated properties: | dispidFax1OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080B5
Data type: | PT_BINARY
Area: | Contact

Remarks

This property, if present, must specify the one-off EntryId that corresponds to this fax address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax1RichTextFormat Canonical Property

 Copy code hover
[image]

PidLidFax1RichTextFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the rich text format of the contact's business fax address.

Associated properties: | dispidFax1RTF
Property set: | PSETID_Address
Long ID (LID): | 0x000080B6
Data type: | PT_BOOLEAN
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2AddressType Canonical Property

 Copy code hover
[image]

PidLidFax2AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type for the contact's home fax address.

Associated properties: | dispidFax2AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x000080C2
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to "FAX".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2DisplayName Canonical Property

 Copy code hover
[image]

PidLidFax2DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the display name of the contact's home fax address.

Associated properties: | dispidFax2DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080C0
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2EmailAddress Canonical Property

 Copy code hover
[image]

PidLidFax2EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail address of the contact's home fax address.

Associated properties: | dispidFax2EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x000080C3
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, should contain a user-readable display name, followed by the "@" character, followed by a fax number.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2EmailType Canonical Property

 Copy code hover
[image]

PidLidFax2EmailType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail type of the contact's home fax address.

Associated properties: | dispidFax2EmailType
Property set: | PSETID_Address
Long ID (LID): | 0x000080C7
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2EntryId Canonical Property

 Copy code hover
[image]

PidLidFax2EntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryID of the contact's home fax address.

Associated properties: | dispidFax2EntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080C1
Data type: | PT_BINARY
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidFax2OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original display name of the contact's home fax address.

Associated properties: | dispidFax2OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080C4
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to the same value as the PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidFax2OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original EntryID of the contact's home fax address.

Associated properties: | dispidFax2OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080C5
Data type: | PT_BINARY
Area: | Contact

Remarks

This property, if present, must specify the one-off EntryId that corresponds to this fax address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax2RichTextFormat Canonical Property

 Copy code hover
[image]

PidLidFax2RichTextFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the rich text format of the home contact's fax address.

Associated properties: | dispidFax2RTF
Property set: | PSETID_Address
Long ID (LID): | 0x000080C6
Data type: | PT_BOOLEAN
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3AddressType Canonical Property

 Copy code hover
[image]

PidLidFax3AddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the address type for the other contact's fax address.

Associated properties: | dispidFax3AddrType
Property set: | PSETID_Address
Long ID (LID): | 0x000080D2
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to "FAX".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3DisplayName Canonical Property

 Copy code hover
[image]

PidLidFax3DisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the display name of the contact's other fax address.

Associated properties: | dispidFax3DisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080D0
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3EmailAddress Canonical Property

 Copy code hover
[image]

PidLidFax3EmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the email address of the contact's other fax address.

Associated properties: | dispidFax3EmailAddress
Property set: | PSETID_Address
Long ID (LID): | 0x000080D3
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, should contain a user-readable display name, followed by the "@" character, followed by a fax number.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3EmailType Canonical Property

 Copy code hover
[image]

PidLidFax3EmailType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail type of the contact's other fax address.

Associated properties: | dispidFax3EmailType
Property set: | PSETID_Address
Long ID (LID): | 0x000080D7
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3EntryId Canonical Property

 Copy code hover
[image]

PidLidFax3EntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the EntryID of the contact's other fax address.

Associated properties: | dispidFax3EntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080D1
Data type: | PT_BINARY
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3OriginalDisplayName Canonical Property

 Copy code hover
[image]

PidLidFax3OriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original display name of the contact's other fax address.

Associated properties: | dispidFax3OriginalDisplayName
Property set: | PSETID_Address
Long ID (LID): | 0x000080D4
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property, if present, must be set to the same value as the PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3OriginalEntryId Canonical Property

 Copy code hover
[image]

PidLidFax3OriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the original EntryID of the contact's other fax address.

Associated properties: | dispidFax3OriginalEntryID
Property set: | PSETID_Address
Long ID (LID): | 0x000080D5
Data type: | PT_BINARY
Area: | Contact

Remarks

This property, if present, must specify the one-off EntryId that corresponds to this fax address.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFax3RichTextFormat Canonical Property

 Copy code hover
[image]

PidLidFax3RichTextFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the rich text format of the contact's other fax address.

Associated properties: | dispidFax3RTF
Property set: | PSETID_Address
Long ID (LID): | 0x000080D6
Data type: | PT_BOOLEAN
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFExceptionalAttendees Canonical Property

 Copy code hover
[image]

PidLidFExceptionalAttendees Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether this property is a recurring calendar object with one or more exceptions, and at least one of the exception embedded messages has at least one RecipientRow.

Associated properties: | dispidFExceptionalAttendees
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000822B
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of FALSE, or the absence of this property, indicates that the calendar object either has no exceptions, or none of the exception embedded messages has RecipientRows.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFExceptionalBody Canonical Property

 Copy code hover
[image]

PidLidFExceptionalBody Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that the exception embedded message object has a body that differs from the recurring calendar object.

Associated properties: | dispidFExceptionalBody
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008206
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

If the value of this property is TRUE, then the exception embedded message object must have a body. If the value of this property is FALSE, or if the property does not exist, then a client or server must obtain the body from the recurring calendar object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFileUnder Canonical Property

 Copy code hover
[image]

PidLidFileUnder Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the name under which the contact is filed when displaying a list of contacts.

Associated properties: | dispidFileUnder
Property set: | PSETID_Address
Long ID (LID): | 0x00008005
Data type: | PT_UNICODE
Area: | Contact

Remarks

The application should treat this property as an empty PT_UNICODE if it is missing from the contact.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFileUnderId Canonical Property

 Copy code hover
[image]

PidLidFileUnderId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies how to generate and recompute the value of the dispidFileUnder (PidLidFileUnder) property when other contact name properties change.

Associated properties: | dispidFileUnderId
Property set: | PSETID_Address
Long ID (LID): | 0x00008006
Data type: | PT_LONG
Area: | Contact

Remarks

If this property is missing or set to a value not detailed in the table below or in [MS-OXOCNTC], the application can choose its own logic to recompute the value of the dispidFileUnder as other contact name properties change.

In the following table, the notation <PropertyName> is used to specify "the value of PropertyName". For example, if the value of the PR_SURNAME (PidTagSurname) property is "Smith", and the value of the PR_GIVEN_NAME (PidTagGivenName) property is "Ben", then "<PidTagGivenName> <PidTagSurname>" specifies the string "Ben Smith". In the table, "\r" specifies a carriage return character, "\n" specifies a line-feed character, and <space> represents a space character.

Value of the dispidFileUnderId property | Description of the dispidFileUnder property
0x00000000 | Empty PT_UNICODE.
0x00003001 | "<PidTagDisplayName>"
0x00003A06 | "<PidTagGivenName>"
0x00003A11 | "<PidTagSurname>"
0x00003A16 | "<PidTagCompanyName>"
0x00008017 | "<PidTagSurname>,<space><PidTagGivenName><space><PidTagMiddleName>"
0x00008018 | "<PidTagCompanyName>\r\n<PidTagSurname>,<space><PidTagGivenName><space><PidTagMiddleName>"
0x00008019 | "<PidTagSurname>,<space><PidTagGivenName><space><PidTagMiddleName>\r\n<PidTagCompanyName>"
0x00008030 | "<PidTagSurname><PidTagGivenName><space><PidTagMiddleName>"
0x00008031 | "<PidTagSurname><space><PidTagGivenName><space><PidTagMiddleName>"
0x00008032 | "<PidTagCompanyName>\r\n<PidTagSurname><PidTagGivenName><space><PidTagMiddleName>"
0x00008033 | "<PidTagCompanyName>\r\n<PidTagSurname><space><PidTagGivenName><space><PidTagMiddleName>"
0x00008034 | "<PidTagSurname><PidTagGivenName><space><PidTagMiddleName>\r\n<PidTagCompanyName>"
0x00008035 | "<PidTagSurname><space><PidTagGivenName><space><PidTagMiddleName>\r\n<PidTagCompanyName>"
0x00008036 | "<PidTagSurname><space><PidTagGivenName><space><PidTagMiddleName><space><PidTagGeneration>"
0x00008037 | "<PidTagGivenName><space><PidTagMiddleName><space><PidTagSurname><space><PidTagGeneration>"
0x00008038 | "<PidTagSurname><PidTagGivenName><space><PidTagMiddleName><space><PidTagGeneration>"
0xfffffffd | Specifies that, when displaying the contact, the application should attempt to use the current value of dispidFileUnder and other contact properties to find a "best match" for dispidFileUnderId to one of the previous values in this table.
0xfffffffe | Specifies that, when displaying the contact, the application should choose the appropriate default values (according to the language locale) for dispidFileUnderId and update dispidFileUnder to match the choice.
0xffffffff | dispidFileUnder is a user-provided PT_UNICODE, and should not be changed when another contact name property changes.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFileUnderList Canonical Property

 Copy code hover
[image]

PidLidFileUnderList Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a list of possible values for the dispidFileUnderId (PidLidFileUnderId) property.

Associated properties: | dispidFileUnderList
Property set: | PSETID_Address
Long ID (LID): | 0x00008026
Data type: | PT_MV_LONG
Area: | Contact

Remarks

Each value in the multi-value property must be one of the allowed values for dispidFileUnderId specified in [MS-OXOCNTC].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFInvited Canonical Property

 Copy code hover
[image]

PidLidFInvited Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether or not invitations have been sent for the meeting that this meeting represents.

Associated properties: | dispidFInvited
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008229
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of FALSE, or the absence of this property, indicates that a meeting request has never been sent. A value of TRUE indicates that a meeting request has been sent. Once this value is set to TRUE on a meeting, it must not be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFlagRequest Canonical Property

 Copy code hover
[image]

PidLidFlagRequest Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the status of a meeting request.

Associated properties: | dispidRequest
Property set: | PSETID_Common
Long ID (LID): | 0x00008530
Data type: | PT_UNICODE
Area: | Flagging

Remarks

In Microsoft Office Outlook, a meeting request is an appointment item.

This property contains user-specifiable text to be associated with the flag and should be set if the message object is flagged or completed, but should not exist for a meeting-related object. Clients may choose not to support this property, and always write "Follow up" (translated to the user's language if appropriate) as the value of the string when this property should be set. This property should be conditionally ignored based on the values of the dispidFlagStringEnum (PidLidFlagString) and dispidValidFlagStringProof (PidLidValidFlagStringProof) properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFlagString Canonical Property

 Copy code hover
[image]

PidLidFlagString Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an index that identifies one of a set of pre-defined text strings associated with the flag.

Associated properties: | dispidFlagStringEnum
Property set: | PSETID_Common
Long ID (LID): | 0x000085C0
Data type: | PT_LONG
Area: | Task

Remarks

If this property is set, clients should use the corresponding string value in the tables below (for example, to substitute a string that is translated into the current user's language), and should ignore the value set in dispidFlagRequest (PidLidFlagRequest) and dispidValidFlagStringProof (PidLidValidFlagStringProof).

Defaults suggested to the user for contact objects are as follows:

Value | English string
0x00000000 or not present | Follow the guidance related to displaying dispidFlagRequest.
0x0000006E | "Follow up"
0x0000006F | "Call"
0x00000070 | "Arrange Meeting"
0x00000071 | "Send E-mail"
0x00000072 | "Send Letter"

Defaults suggested to the user for all other message objects are as follows:

Value | English string
0x00000000 or not present | Follow the guidance related to displaying dispidFlagRequest.
0x00000001 | "Call"
0x00000002 | "Do not Forward"
0x00000003 | "Follow up"
0x00000004 | "For Your Information"
0x00000005 | "Forward"
0x00000006 | "No Response Necessary"
0x00000007 | "Read"
0x00000008 | "Reply"
0x00000009 | "Reply to All"
0x0000000A | "Review"

All strings specified above can be translated to the user's language, if appropriate.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFormPropStream Canonical Property

 Copy code hover
[image]

PidLidFormPropStream Canonical Property
See also Send feedback

Published: July 16, 2012

Represents data in custom properties that are saved with the message.

Associated properties: | dispidFormPropStream
Property set: | PSETID_Common
Long ID (LID): | 0x0000851B
Data type: | PT_BINARY
Area: | Run-time configuration

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFormStorage Canonical Property

 Copy code hover
[image]

PidLidFormStorage Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the properties of the form that is associated with the message.

Associated properties: | dispidFormStorage
Property set: | PSETID_Common
Long ID (LID): | 0x0000850F
Data type: | PT_BINARY
Area: | Run-time configuration

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidForwardInstance Canonical Property

 Copy code hover
[image]

PidLidForwardInstance Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that the meeting request represents an exception to a recurring series, and it was forwarded (even when forwarded by the organizer) rather than being an invitation sent by the organizer.

Associated properties: | dispidFwrdInstance
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000820A
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of FALSE for this property indicates that the meeting request is not a forwarded instance. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFreeBusyLocation Canonical Property

 Copy code hover
[image]

PidLidFreeBusyLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a URL path from which a client can retrieve free/busy information for the contact as an iCal file, as specified in [MS-OXCICAL].

Associated properties: | dispidFreeBusyLocation
Property set: | PSETID_Address
Long ID (LID): | 0x000080D8
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidFShouldTNEF Canonical Property

 Copy code hover
[image]

PidLidFShouldTNEF Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether to encode an item with Transport Neutral Encapsulation Format (TNEF).

Associated properties: | dispidFShouldTNEF
Property set: | PSETID_Common
Long ID (LID): | 0x000085A5
Data type: | PT_BOOLEAN
Area: | Run-time configuration

Remarks

This property is set when Microsoft Word is set as the e-mail editor, and it sends an OLE object that is embedded in a Rich Text Format (RTF) stream.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidGlobalObjectId Canonical Property

 Copy code hover
[image]

PidLidGlobalObjectId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the unique identifier of the calendar object.

Associated properties: | LID_GLOBAL_OBJID
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000003
Data type: | PT_BINARY
Area: | Meetings

Remarks

Once set for a calendar object, the value of this property must not change. A detailed description of the format can be found in [MS-OXOCAL].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidHasPicture Canonical Property

 Copy code hover
[image]

PidLidHasPicture Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether a photo attachment exists for a contact.

Associated properties: | dispidHasPicture
Property set: | PSETID_Address
Long ID (LID): | 0x00008015
Data type: | PT_BOOLEAN
Area: | Contact

Remarks

If this property exists and is set to TRUE, the contact's attachment table contains an attachment with the PR_ATTACHMENT_CONTACTPHOTO (PidTagAttachmentContactPhoto) property set to TRUE.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidHeaderItem Canonical Property

 Copy code hover
[image]

PidLidHeaderItem Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether Microsoft Outlook has downloaded to the client computer only the header of a message, or both the header and body of the message, when Outlook is configured in Cached Exchange Mode.

Associated properties: | dispidHeaderItem
Property set: | PSETID_Common
Long ID (LID): | 0x00008578
Data type: | PT_LONG
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidHomeAddress Canonical Property

 Copy code hover
[image]

PidLidHomeAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the complete address of the contact's home address.

Associated properties: | dispidHomeAddress
Property set: | PSETID_Address
Long ID (LID): | 0x0000801A
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property should be a combination of other physical address properties, and is based on client locale.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidHomeAddressCountryCode Canonical Property

 Copy code hover
[image]

PidLidHomeAddressCountryCode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the country code portion of the contact's home address.

Associated properties: | dispidHomeAddressCountryCode
Property set: | PSETID_Address
Long ID (LID): | 0x000080DA
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacst and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidHtml Canonical Property

 Copy code hover
[image]

PidLidHtml Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the contact's business Web page URL.

Associated properties: | dispidHTML
Property set: | PSETID_Address
Long ID (LID): | 0x0000802B
Data type: | PT_UNICODE
Area: | Contact

Remarks

The value of this property, if present, should be the same as the value of the PR_BUSINESS_HOME_PAGE (PidTagBusinessHomePage) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidImageAttachmentsCompressionLevel Canonical Property

 Copy code hover
[image]

PidLidImageAttachmentsCompressionLevel Canonical Property
See also Send feedback

Published: July 16, 2012

Defines a compression level to apply on image attachments.

Associated properties: | dispidImgAttchmtsCompressLevel
Property set: | PSETID_Common
Long ID (LID): | 0x00008593
Data type: | PT_LONG
Area: | Run-time configuration

Remarks

The following are valid compression levels:

C++ Copy code Copy code
enum PictureCompressLevel
{
 pclOriginal = 0,
 pclEmail = 1,
 pclWeb = 2,
 pclDocuments = 3,
};

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidImapDeleted Canonical Property

 Copy code hover
[image]

PidLidImapDeleted Canonical Property
See also Send feedback

Published: July 16, 2012

Denotes Internet Mail Access Protocol (IMAP) items that are marked for deletion.

Associated properties: | dispidImapDeleted
Property set: | PSETID_Common
Long ID (LID): | 0x00008570
Data type: | PT_LONG
Area: | IMAP

Remarks

If set to a nonzero value, the item has been marked for deletion.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidInstantMessagingAddress Canonical Property

 Copy code hover
[image]

PidLidInstantMessagingAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the contact's instant messaging address.

Associated properties: | dispidInstMsg
Property set: | PSETID_Address
Long ID (LID): | 0x00008062
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidIntendedBusyStatus Canonical Property

 Copy code hover
[image]

PidLidIntendedBusyStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the value of the dispidBusyStatus (PidLidBusyStatus) property on the meeting in the organizer's calendar when the meeting request or meeting update was sent.

Associated properties: | dispidIntendedBusyStatus
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008224
Data type: | PT_LONG
Area: | Meetings

Remarks

The allowable values of this property are the same as those for the property dispidBusyStatus.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidInternetAccountName Canonical Property

 Copy code hover
[image]

PidLidInternetAccountName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-visible e-mail account name through which the e-mail message is sent.

Associated properties: | dispidInetAcctName
Property set: | PSETID_Common
Long ID (LID): | 0x00008580
Data type: | PT_UNICODE
Area: | General messaging

Remarks

The format of this string is implementation dependent. This property can be used by the client to determine which server to direct the mail to, but is optional and the value has no meaning to the server.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidInternetAccountStamp Canonical Property

 Copy code hover
[image]

PidLidInternetAccountStamp Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the e-mail account ID through which the e-mail message is sent.

Associated properties: | dispidInetAcctStamp
Property set: | PSETID_Common
Long ID (LID): | 0x00008581
Data type: | PT_UNICODE
Area: | General messaging

Remarks

The format of this string is implementation dependent. This property can be used by the client to determine which server to direct the mail to, but is optional and the value has no meaning to the server.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidIsException Canonical Property

 Copy code hover
[image]

PidLidIsException Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that the object that represents an exception (including an orphan instance).

Associated properties: | LID_IS_EXCEPTION
Property set: | PSETID_Meeting
Long ID (LID): | 0x0000000A
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of FALSE indicates that the object that represents a recurring series or a single instance. The absence of this property for any object indicates a value of FALSE except for the exception embedded message, which assumes a value of TRUE.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidIsInterpersonalFax Canonical Property

 Copy code hover
[image]

PidLidIsInterpersonalFax Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the item is an internet fax item.

Associated properties: | dispidIsIPFax
Property set: | PSETID_Common
Long ID (LID): | 0x0000859B
Data type: | PT_BOOLEAN
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidIsRecurring Canonical Property

 Copy code hover
[image]

PidLidIsRecurring Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether or not the object is associated with a recurring series.

Associated properties: | LID_IS_RECURRING
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000005
Data type: | PT_BOOLEAN
Area: | Meetings

Remarks

A value of TRUE indicates that the object represents either a recurring series or an exception (including an orphan instance). A value of FALSE, or the absence of this property, indicates that the object represents a single instance. Note the difference between this property and the PR_RECURRING (PidLidRecurring) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidIsSilent Canonical Property

 Copy code hover
[image]

PidLidIsSilent Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that the user did not include any text in the body of the meeting response.

Associated properties: | LID_IS_SILENT
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000004
Data type: | PT_BOOLEAN
Area: | Meetings

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLinkedTaskItems Canonical Property

 Copy code hover
[image]

PidLidLinkedTaskItems Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a list of the PR_ENTRYID (PidTagEntryId) property of tasks that are related to the calendar.

Associated properties: | dispidLinkedTaskItems
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000820C
Data type: | PT_MV_BINARY
Area: | Task

Remarks

This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidTagEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLocation Canonical Property

 Copy code hover
[image]

PidLidLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the location of an appointment.

Associated properties: | dispidLocation
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008208
Data type: | PT_UNICODE
Area: | Calendar

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogDocumentPosted Canonical Property

 Copy code hover
[image]

PidLidLogDocumentPosted Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the document was sent by e-mail or posted to a server folder during journaling.

Associated properties: | dispidLogDocPosted
Property set: | PSETID_Log
Long ID (LID): | 0x00008711
Data type: | PT_BOOLEAN
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogDocumentPrinted Canonical Property

 Copy code hover
[image]

PidLidLogDocumentPrinted Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the document was printed during journaling.

Associated properties: | dispidLogDocPrinted
Property set: | PSETID_Log
Long ID (LID): | 0x0000870E
Data type: | PT_BOOLEAN
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogDocumentRouted Canonical Property

 Copy code hover
[image]

PidLidLogDocumentRouted Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the document was sent to a routing recipient during journaling.

Associated properties: | dispidLogDocRouted
Property set: | PSETID_Log
Long ID (LID): | 0x00008710
Data type: | PT_BOOLEAN
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogDocumentSaved Canonical Property

 Copy code hover
[image]

PidLidLogDocumentSaved Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the document was saved during journaling.

Associated properties: | dispidLogDocSaved
Property set: | PSETID_Log
Long ID (LID): | 0x0000870F
Data type: | PT_BOOLEAN
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogDuration Canonical Property

 Copy code hover
[image]

PidLidLogDuration Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the duration, in minutes, of a journal message.

Associated properties: | dispidLogDuration
Property set: | PSETID_Log
Long ID (LID): | 0x00008707
Data type: | PT_LONG
Area: | Journal

Remarks

The duration, in minutes, of the activity that must be the difference between the dispidLogEnd (PidLidLogEnd) and dispidLogStart (PidLidLogStart) properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogEnd Canonical Property

 Copy code hover
[image]

PidLidLogEnd Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the end date and time for the journal message.

Associated properties: | dispidLogEnd
Property set: | PSETID_Log
Long ID (LID): | 0x00008708
Data type: | PT_SYSTIME
Area: | Journal

Remarks

The time when the activity ended in Coordinated Universal Time The (UTC), which must be equal to the dispidCommonEnd (PidLidCommonEnd) property and greater than or equal to dispidLogStart (PidLidLogStart) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogFlags Canonical Property

 Copy code hover
[image]

PidLidLogFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains metadata about the journal.

Associated properties: | dispidLogFlags
Property set: | PSETID_Log
Long ID (LID): | 0x0000870C
Data type: | PT_LONG
Area: | Journal

Remarks

The bit field that contains metadata about the journal must be either zero or "0x40000000".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogStart Canonical Property

 Copy code hover
[image]

PidLidLogStart Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the start date and time for the journal message.

Associated properties: | dispidLogStart
Property set: | PSETID_Log
Long ID (LID): | 0x00008706
Data type: | PT_SYSTIME
Area: | Journal

Remarks

The time in Coordinated Universal Time (UTC) when the activity began must be equal to the dispidCommonStart (PidLidCommonStart) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogType Canonical Property

 Copy code hover
[image]

PidLidLogType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the journaling application (for example, "MSWord"), and is typically a free-form attribute of a journal message, usually a string.

Associated properties: | dispidLogType
Property set: | PSETID_Log
Long ID (LID): | 0x00008700
Data type: | PT_UNICODE
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidLogTypeDesc Canonical Property

 Copy code hover
[image]

PidLidLogTypeDesc Canonical Property
See also Send feedback

Published: July 16, 2012

Describes the activity that is being recorded.

Associated properties: | dispidLogTypeDesc
Property set: | PSETID_Log
Long ID (LID): | 0x00008712
Data type: | PT_UNICODE
Area: | Journal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journals.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidMeetingType Canonical Property

 Copy code hover
[image]

PidLidMeetingType Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the type of meeting request or meeting update.

Associated properties: | dispidMeetingType
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000026
Data type: | PT_LONG
Area: | Meetings

Remarks

The value of this property must be set to one of the following:

Property | Value | Description
mtgEmpty | 0x00000000 | Unspecified.
mtgRequest | 0x00000001 | Initial meeting request.
mtgFull | 0x00010000 | Full update.
mtgInfo | 0x00020000 | Informational update.
mtgOutOfDate | 0x00080000 | A newer meeting request or meeting update was received after this one.
mtgDelegatorCopy | 0x00100000 | This is set on the delegator's copy when a delegate handles meeting-related objects.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidMeetingWorkspaceUrl Canonical Property

 Copy code hover
[image]

PidLidMeetingWorkspaceUrl Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the URL of the meeting workspace that is associated with a calendar object.

Associated properties: | dispidMWSURL
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008209
Data type: | PT_UNICODE
Area: | Meetings

Remarks

This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidMileage Canonical Property

 Copy code hover
[image]

PidLidMileage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the mileage information that is associated with an item.

Associated properties: | dispidMileage
Property set: | PSETID_Common
Long ID (LID): | 0x00008534
Data type: | PT_UNICODE
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendableBcc Canonical Property

 Copy code hover
[image]

PidLidNonSendableBcc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of all the unsendable attendees who are resources.

Associated properties: | dispidNonSendableBCC
Property set: | PSETID_Common
Long ID (LID): | 0x00008538
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the PR_DISPLAY_NAME (PidTagDisplayName) property of the attendee's Address Book. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendableCc Canonical Property

 Copy code hover
[image]

PidLidNonSendableCc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of all the unsendable attendees who are also optional attendees.

Associated properties: | dispidNonSendableCC
Property set: | PSETID_Common
Long ID (LID): | 0x00008537
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the PR_DISPLAY_NAME (PidTagDisplayName) property of the attendee's Address Book. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendableTo Canonical Property

 Copy code hover
[image]

PidLidNonSendableTo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of all the unsendable attendees who are also required attendees.

Associated properties: | dispidNonSendableTo
Property set: | PSETID_Common
Long ID (LID): | 0x00008536
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the PR_DISPLAY_NAME (PidTagDisplayName) property of the attendee's Address Book. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendableBccTrackStatus Canonical Property

 Copy code hover
[image]

PidLidNonSendableBccTrackStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value for each attendee that is listed in the dispidNonSendableBCC (PidLidNonSendableBcc) property.

Associated properties: | dispidNonSendBccTrackStatus
Property set: | PSETID_Common
Long ID (LID): | 0x00008545
Data type: | PT_MV_LONG
Area: | General messaging

Remarks

This property is required only when the dispidNonSendableBCC property is set. The number of values in this property must equal the number of values in the dispidNonSendableBCC. Each value in this property corresponds to the attendee in the dispidNonSendableBCC property at the same index.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendCcTrackStatus Canonical Property

 Copy code hover
[image]

PidLidNonSendCcTrackStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value for each attendee listed in the dispidNonSendableCC (PidLidNonSendableCc) property.

Associated properties: | dispidNonSendCcTrackStatus
Property set: | PSETID_Common
Long ID (LID): | 0x00008544
Data type: | PT_MV_LONG
Area: | General messaging

Remarks

This property is required only when the dispidNonSendableCC property is set. The number of values in this property must equal the number of values in dispidNonSendableCC. Each PT_LONG value in this property corresponds to the attendee in the dispidNonSendableCC property at the same index.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNonSendToTrackStatus Canonical Property

 Copy code hover
[image]

PidLidNonSendToTrackStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value for each attendee listed in the dispidNonSendableTo (PidLidNonSendableTo) property.

Associated properties: | dispidNonSendToTrackStatus
Property set: | PSETID_Common
Long ID (LID): | 0x00008543
Data type: | PT_MV_LONG
Area: | General messaging

Remarks

This property is required only when the dispidNonSendableTo property is set. The number of values in this property must equal the number of values in dispidNonSendableTo. Each PT_LONG value in this property corresponds to the attendee in the dispidNonSendableTo property at the same index.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNoteColor Canonical Property

 Copy code hover
[image]

PidLidNoteColor Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the suggested background color of the note.

Associated properties: | dispidNoteColor
Property set: | PSETID_Note
Long ID (LID): | 0x00008B00
Data type: | PT_LONG
Area: | Sticky Notes

Remarks

This property must be one of the entries in the following table:

Value | Color
0x00000000 | Blue
0x00000001 | Green
0x00000002 | Pink
0x00000003 | Yellow
0x00000004 | White

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXONOTE]

Specifies the properties and operations that are permissible on notes.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNoteHeight Canonical Property

 Copy code hover
[image]

PidLidNoteHeight Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the height of the visible message window in pixels.

Associated properties: | dispidNoteHeight
Property set: | PSETID_Note
Long ID (LID): | 0x00008B03
Data type: | PT_LONG
Area: | Sticky Note

Remarks

This value must be greater than zero.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXONOTE]

Specifies the properties and operations that are permissible on notes.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNoteWidth Canonical Property

 Copy code hover
[image]

PidLidNoteWidth Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the width of the visible message window in pixels.

Associated properties: | dispidNoteWidth
Property set: | PSETID_Note
Long ID (LID): | 0x00008B02
Data type: | PT_LONG
Area: | Sticky Note

Remarks

This value must be greater than zero.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXONOTE]

Specifies the properties and operations that are permissible on notes.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNoteX Canonical Property

 Copy code hover
[image]

PidLidNoteX Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the distance, in pixels, from the left edge of the screen where a user interface displays a note.

Associated properties: | dispidNoteX
Property set: | PSETID_Note
Long ID (LID): | 0x00008B04
Data type: | PT_LONG
Area: | Sticky Note

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXONOTE]

Specifies the properties and operations that are permissible on notes.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidNoteY Canonical Property

 Copy code hover
[image]

PidLidNoteY Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the distance, in pixels, from the top edge of the screen where a user interface displays a note.

Associated properties: | dispidNoteY
Property set: | PSETID_Note
Long ID (LID): | 0x00008B05
Data type: | PT_LONG
Area: | Sticky Note

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXONOTE]

Specifies the properties and operations that are permissible on notes.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOfflineStatus Canonical Property

 Copy code hover
[image]

PidLidOfflineStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Determines the state of a document file on a server that implements [MS-LISTSWS].

Associated properties | dispidOfflineStatus
Property set: | PSETID_Common
Long ID (LID): | 0x000085B9
Data type: | PT_LONG
Area: | General messaging

Remarks

The following table shows the possible values of this property.

Value | Description
0 | Document is not checked out.
1 | Document is checked out to the current user.
2 | Document is not checked out, but the current user has a copy of the file saved for editing on the current computer.

This property is calculated locally and is not sent to a server at any time unless a user drags the item to another account. In that case, it is treated as a user-defined custom property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOldLocation Canonical Property

 Copy code hover
[image]

PidLidOldLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the original value of the dispidLocation (PidLidLocation) property before a meeting update.

Associated properties: | dispidOldLocation
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000028
Data type: | PT_UNICODE
Area: | Meetings

Remarks

This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOldWhenEndWhole Canonical Property

 Copy code hover
[image]

PidLidOldWhenEndWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the original value of the dispidApptEndWhole (PidLidAppointmentEndWhole) property before a meeting update.

Associated properties: | dispidOldWhenEndWhole
Property set: | PSETID_Meeting
Long ID (LID): | 0x0000002A
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOldWhenStartWhole Canonical Property

 Copy code hover
[image]

PidLidOldWhenStartWhole Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the original value of the dispidApptStartWhole (PidLidAppointmentStartWhole) property before a meeting update.

Associated properties: | dispidOldWhenStartWhole
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000029
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOriginalStoreEntryId Canonical Property

 Copy code hover
[image]

PidLidOriginalStoreEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the entry ID of the delegator's store.

Associated properties: | dispidOrigStoreEid
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008237
Data type: | PT_BINARY
Area: | Meetings

Remarks

This property should be set on meeting objects which have been created or updated by a delegate.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOtherAddress Canonical Property

 Copy code hover
[image]

PidLidOtherAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the complete address of the contact's other address.

Associated properties: | dispidOtherAddress
Property set: | PSETID_Address
Long ID (LID): | 0x0000801C
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property should be a combination of other physical address properties, and is based on client locale.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOtherAddressCountryCode Canonical Property

 Copy code hover
[image]

PidLidOtherAddressCountryCode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the country code portion of the contact's other address.

Associated properties: | dispidOtherAddressCountryCode
Property set: | PSETID_Address
Long ID (LID): | 0x000080DC
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications .

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidOwnerCriticalChange Canonical Property

 Copy code hover
[image]

PidLidOwnerCriticalChange Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time when a meeting request was sent by the organizer.

Associated properties: | LID_OWNER_CRITICAL_CHANGE
Property set: | PSETID_Meeting
Long ID (LID): | 0x0000001A
Data type: | PT_SYSTIME
Area: | Meetings

Remarks

The value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPageDirStream Canonical Property

 Copy code hover
[image]

PidLidPageDirStream Canonical Property
See also Send feedback

Published: July 16, 2012

Represents information about pages of the custom form associated with the message.

Associated properties: | dispidPageDirStream
Property set: | PSETID_Common
Long ID (LID): | 0x00008513
Data type: | PT_BINARY
Area: | Run-time configuration

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPercentComplete Canonical Property

 Copy code hover
[image]

PidLidPercentComplete Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the progress the user has made on a task.

Associated properties: | dispidPercentComplete
Property set: | PSETID_Task
Long ID (LID): | 0x00008102
Data type: | PT_R8
Area: | Task

Remarks

The value of this property must be a number greater than or equal to 0.0 and less than or equal to 1.0, where 1.0 indicates that work is completed and 0.0 indicates that work has not begun.

For a time-flagged message object, the value of this property must be set to 1.0 if the object is flagged completed, and should be set to 0.0 otherwise.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPostalAddressId Canonical Property

 Copy code hover
[image]

PidLidPostalAddressId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies which physical address is the contact's mailing address.

Associated properties: | dispidPostalAddressId
Property set: | PSETID_Address
Long ID (LID): | 0x00008022
Data type: | PT_LONG
Area: | Contact

Remarks

If present, this property must have one of the values that are specified in the table below or in [MS-OXOCNTC]. If not set, the application should assume that the value is "0x00000000".

Value | Description
0x00000000 | No address is selected as the mailing address. PR_STREET_ADDRESS (PidTagStreetAddress), PR_LOCALITY (PidTagLocality), PR_STATE_OR_PROVINCE (PidTagStateOrProvince), PR_POSTAL_CODE (PidTagPostalCode), PR_COUNTRY (PidTagCountry), dispidAddressCountryCode (PidLidAddressCountryCode), and PR_POSTAL_ADDRESS (PidTagPostalAddress) all must not be set.
0x00000001 | The Home Address is the mailing address. The values of the PR_STREET_ADDRESS, PR_LOCALITY, PR_STATE_OR_PROVINCE, PR_POSTAL_CODE, PR_POST_OFFICE_BOX (PidTagPostOfficeBox), PR_COUNTRY, dispidAddressCountryCode, and PR_POSTAL_ADDRESS properties must be equal to the values of the PR_HOME_ADDRESS_STREET (PidTagHomeAddressStreet), PR_HOME_ADDRESS_CITY (PidTagHomeAddressCity), PR_HOME_ADDRESS_STATE_OR_PROVINCE (PidTagHomeAddressStateOrProvince), PR_HOME_ADDRESS_POSTAL_CODE (PidTagHomeAddressPostalCode), PR_HOME_ADDRESS_POST_OFFICE_BOX (PidTagHomeAddressPostOfficeBox), PR_HOME_ADDRESS_COUNTRY (PidTagHomeAddressCountry), dispidHomeAddressCountryCode (PidLidHomeAddressCountryCode), and dispidHomeAddress (PidLidHomeAddress) properties, respectively.
0x00000002 | The Work Address is the mailing address. The values of the PR_STREET_ADDRESS, PR_LOCALITY, PR_STATE_OR_PROVINCE, PR_POSTAL_CODE, PR_POST_OFFICE_BOX, PR_COUNTRY, dispidAddressCountryCode, and PR_POSTAL_ADDRESS properties must be equal to the values of the dispidWorkAddressStreet (PidLidWorkAddressStreet), dispidWorkAddressCity (PidLidWorkAddressCity), dispidWorkAddressState (PidLidWorkAddressState), dispidWorkAddressPostalCode (PidLidWorkAddressPostalCode), dispidWorkAddressPostOfficeBox (PidLidWorkAddressPostOfficeBox), dispidWorkAddressCountry (PidLidWorkAddressCountry), dispidWorkAddressCountryCode (PidLidWorkAddressCountryCode), and dispidWorkAddress (PidLidWorkAddress) properties, respectively.
0x00000003 | The Other Address is the mailing address. The values of the, PR_STREET_ADDRESS, PR_LOCALITY, PR_STATE_OR_PROVINCE, PR_POSTAL_CODE, PR_POST_OFFICE_BOX, PR_COUNTRY, dispidAddressCountryCode, and PR_POSTAL_ADDRESS properties must be equal to the values of the PR_OTHER_ADDRESS_STREET (PidTagOtherAddressStreet), PR_OTHER_ADDRESS_CITY (PidTagOtherAddressCity), PR_OTHER_ADDRESS_STATE_OR_PROVINCE (PidTagOtherAddressStateOrProvince), PR_OTHER_ADDRESS_POSTAL_CODE (PidTagOtherAddressPostalCode), PR_OTHER_ADDRESS_POST_OFFICE_BOX (PidTagOtherAddressPostOfficeBox), dispidOtherAddressCountryCode (PidLidOtherAddressCountryCode), and dispidOtherAddress (PidLidOtherAddress) properties, respectively.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPostRssChannel Canonical Property

 Copy code hover
[image]

PidLidPostRssChannel Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the contents of the <title> field from the XML of the Atom <feed> or RSS <channel>.

Associated properties: | dispidPostRssChannel
Property set: | PSETID_PostRss
Long ID (LID): | 0x00008904
Data type: | PT_UNICODE
Area: | RSS

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPostRssChannelLink Canonical Property

 Copy code hover
[image]

PidLidPostRssChannelLink Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the URL of the RSS or Atom feed from which the XML file came.

Associated properties: | dispidPostRssChannelLink
Property set: | PSETID_PostRss
Long ID (LID): | 0x00008900
Data type: | PT_UNICODE
Area: | RSS

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPrivate Canonical Property

 Copy code hover
[image]

PidLidPrivate Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the end-user wants this message object hidden from other users who have access to the message object.

Associated properties: | dispidPrivate
Property set: | PSETID_Common
Long ID (LID): | 0x00008506
Data type: | PT_BOOLEAN
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidPropertyDefinitionStream Canonical Property

 Copy code hover
[image]

PidLidPropertyDefinitionStream Canonical Property
See also Send feedback

Published: July 16, 2012

Represents definitions of user-defined fields and data-binding settings of built-in fields of a message.

Associated properties: | dispidPropDefStream
Property set: | PSETID_Common
Long ID (LID): | 0x00008540
Data type: | PT_BINARY
Area: | Run-time configuration

Remarks

The value of the PidLidPropertyDefinitionStream property is saved as part of the custom form definition for the message.

The value of this property is a binary stream. For information on the structure of this stream, see PropertyDefinition Stream Structure.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

Outlook Items and Fields
How to: Add a Definition for a New User-Defined Field
PropertyDefinition Stream Sample
MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRecallTime Canonical Property

 Copy code hover
[image]

PidLidRecallTime Canonical Property
See also Send feedback

Published: July 16, 2012

Denotes the time at which a message recall was initiated.

Associated properties: | dispidRecallTime
Property set: | PSETID_Common
Long ID (LID): | 0x00008549
Data type: | PT_SYSTIME
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRecurrencePattern Canonical Property

 Copy code hover
[image]

PidLidRecurrencePattern Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a description of the recurrence pattern of the calendar object.

Associated properties: | dispidRecurPattern
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008232
Data type: | PT_UNICODE
Area: | Calendar

Remarks

If this property is set, it must be set to a description of the recurrence that is specified by the dispidApptRecur (PidLidAppointmentRecur) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRecurrenceType Canonical Property

 Copy code hover
[image]

PidLidRecurrenceType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the recurrence type of the recurring series.

Associated properties: | dispidRecurType
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008231
Data type: | PT_LONG
Area: | Calendar

Remarks

This property specifies the recurrence type of the recurring series by using one of the values listed below.

Status | Value | Description
rectypeNone | 0 | A single instance appointment.
rectypeDaily | 1 | A daily recurrence pattern.
rectypeWeekly | 2 | A weekly recurrence pattern.
rectypeMonthly | 3 | A monthly recurrence pattern.
rectypeYearly | 4 | A yearly recurrence pattern.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRecurring Canonical Property

 Copy code hover
[image]

PidLidRecurring Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether an appointment message is recurrent.

Associated properties: | dispidRecurring
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008223
Data type: | PT_BOOLEAN
Area: | Calendar

Remarks

This property is TRUE if the appointment is a recurring appointment, and is FALSE if it is not recurring.

This property specifies whether or not the object represents a recurring series. A value of TRUE indicates that the object represents a recurring series. A value of FALSE, or the absence of this property, indicates that the object represents either a single instance or an exception (including an orphan instance). Note the difference between this property and the LID_IS_RECURRING (PidLidIsRecurring) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReferenceEntryId Canonical Property

 Copy code hover
[image]

PidLidReferenceEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the reference ENTRYID for the contact.

Associated properties: | dispidReferenceEID
Property set: | PSETID_Common
Long ID (LID): | 0x000085BD
Data type: | PT_BINARY
Area: | Contact

Remarks

If present, this property should be equal to the value of the EntryId of the contact.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderDelta Canonical Property

 Copy code hover
[image]

PidLidReminderDelta Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the interval, in minutes, between the time when the reminder first becomes overdue and the start time of the calendar object.

Associated properties: | dispidReminderDelta
Property set: | PSETID_Common
Long ID (LID): | 0x00008501
Data type: | PT_LONG
Area: | Reminder

Remarks

This property must be set on calendar objects. For all non-calendar objects, this property should be set to "0x00000000" and is ignored. When a reminder is dismissed for one instance of a recurring calendar object, the value of this property is used in the calculation of the signal time for the next instance. See [MS- OXOCAL] for details about calendar object creation.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderFileParameter Canonical Property

 Copy code hover
[image]

PidLidReminderFileParameter Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the filename of the sound that a client should play when the reminder for that object becomes overdue.

Associated properties: | dispidReminderFileParam
Property set: | PSETID_Common
Long ID (LID): | 0x0000851F
Data type: | PT_UNICODE
Area: | Reminder

Remarks

If this property is not present, the client may use a default value.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderOverride Canonical Property

 Copy code hover
[image]

PidLidReminderOverride Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether the client should respect the values of the dispidReminderPlaySound (PidLidReminderPlaySound) and dispidReminderFileParam ( PidLidReminderFileParameter) properties.

Associated properties: | dispidReminderOverride
Property set: | PSETID_Common
Long ID (LID): | 0x0000851C
Data type: | PT_BOOLEAN
Area: | Reminder

Remarks

A client may use default values in place of the values of the dispidReminderPlaySound and dispidReminderFileParam properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderPlaySound Canonical Property

 Copy code hover
[image]

PidLidReminderPlaySound Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether the client should play a sound when the reminder becomes overdue.

Associated properties: | dispidReminderPlaySound
Property set: | PSETID_Common
Long ID (LID): | 0x0000851E
Data type: | PT_BOOLEAN
Area: | Reminder

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderSet Canonical Property

 Copy code hover
[image]

PidLidReminderSet Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether a reminder is set on the object.

Associated properties: | dispidReminderSet
Property set: | PSETID_Common
Long ID (LID): | 0x00008503
Data type: | PT_BOOLEAN
Area: | Reminder

Remarks

If a recurring calendar object has this property set to TRUE, the client can override this value for exceptions.

If this property is FALSE on a recurring calendar object, reminders are disabled for the entire series, including exceptions. For recurring task objects, this property cannot be overridden by exceptions (see [MS-OXOCAL] and [MS-OXOTASK] for details).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderSignalTime Canonical Property

 Copy code hover
[image]

PidLidReminderSignalTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the point in time when a reminder transitions from pending to overdue.

Associated properties: | dispidReminderNextTime
Property set: | PSETID_Common
Long ID (LID): | 0x00008560
Data type: | PT_SYSTIME
Area: | Reminder

Remarks

This property must be set if the dispidReminderSet (PidLidReminderSet) property is TRUE. Clients must set the value in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidReminderTime Canonical Property

 Copy code hover
[image]

PidLidReminderTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the initial signal time for a reminder.

Associated properties: | dispidReminderTime
Property set: | PSETID_Common
Long ID (LID): | 0x00008502
Data type: | PT_SYSTIME
Area: | Reminder

Remarks

For calendar objects, this property represents the time when the user would be late which is the start time of the appointment. Clients must set the value in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteAttachment Canonical Property

 Copy code hover
[image]

PidLidRemoteAttachment Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether a remote item has an attachment associated with it.

Associated properties: | dispidRemoteAttachment
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F07
Data type: | PT_BOOLEAN
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteEntryId Canonical Property

 Copy code hover
[image]

PidLidRemoteEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the entry ID of a remote item.

Associated properties: | dispidRemoteEID
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F01
Data type: | PT_BINARY
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteMessageClass Canonical Property

 Copy code hover
[image]

PidLidRemoteMessageClass Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the message class of a remote item.

Associated properties: | dispidRemoteMsgClass
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F02
Data type: | None
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteSearchKey Canonical Property

 Copy code hover
[image]

PidLidRemoteSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the search key of a remote item.

Associated properties: | dispidRemoteSearchKey
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F06
Data type: | PT_BINARY
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteTransferSize Canonical Property

 Copy code hover
[image]

PidLidRemoteTransferSize Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the transfer size, in bytes, for a remote item.

Associated properties: | dispidRemoteXferSize
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F05
Data type: | PT_LONG
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteTransferTime Canonical Property

 Copy code hover
[image]

PidLidRemoteTransferTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the transfer time, in seconds, for a remote item.

Associated properties: | dispidRemoteXferTime
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F04
Data type: | PT_LONG
Area: | Remote message

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidRemoteTransport Canonical Property

 Copy code hover
[image]

PidLidRemoteTransport Canonical Property
See also Send feedback

Published: July 16, 2012

Identifies what account the header item is associated with, primarily to implement the POP Leave on Server functionality.

Associated Properties | dispidRemoteXP
Property set: | PSETID_Remote
Long ID (LID): | 0x00008F03
Data type: | PT_STRING8
Area: | Remote message

Remarks

This property is relevant only on messages that have a message class of IPM.Remote. Microsoft Outlook keeps a mapping of various accounts that are downloading to a given store in a Folder Associated Information (FAI) message, but it could also keep this information in the registry.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidResendTime Canonical Property

 Copy code hover
[image]

PidLidResendTime Canonical Property
See also Send feedback

Published: July 16, 2012

If set on a nondelivery report, denotes the time the message was resent.

Associated properties: | dispidResendTime
Property set: | PSETID_Report
Long ID (LID): | 0x00008D00
Data type: | PT_SYSTIME
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidResponseStatus Canonical Property

 Copy code hover
[image]

PidLidResponseStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the response status of an attendee.

Associated properties: | dispidResponseStatus
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008218
Data type: | PT_LONG
Area: | Meetings

Remarks

The response status must be one of the values in the table below.

Response status | Value | Description
respNone | 0x00000000 | No response is required for this object. This is the case for appointment objects and meeting response objects.
respOrganized | 0x00000001 | This meeting belongs to the organizer.
respTentative | 0x00000002 | This value on the attendee's meeting indicates that the attendee has tentatively accepted the meeting request.
respAccepted | 0x00000003 | This value on the attendee's meeting t indicates that the attendee has accepted the meeting request.
respDeclined | 0x00000004 | This value on the attendee's meeting indicates that the attendee has declined the meeting request.
respNotResponded | 0x00000005 | This value on the attendee's meeting indicates the attendee has not yet responded. This value is on the meeting request, meeting update, and meeting cancelation.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidScriptStream Canonical Property

 Copy code hover
[image]

PidLidScriptStream Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the code written in Visual Basic Scripting Edition (VBScript) behind the custom form associated with the message.

Associated properties: | dispidScriptStream
Property set: | PSETID_Common
Long ID (LID): | 0x00008541
Data type: | PT_BINARY
Area: | Run-time configuration

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSendMeetingAsIcal Canonical Property

 Copy code hover
[image]

PidLidSendMeetingAsIcal Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies if a meeting request should be sent as an iCal message.

Associated properties: | dispidSendMtgAsICAL
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008200
Data type: | PT_BOOLEAN
Area: | Conferencing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingCapabilities Canonical Property

 Copy code hover
[image]

PidLidSharingCapabilities Canonical Property
See also Send feedback

Published: July 16, 2012

Designates as a property of a sharing message.

Associated properties: | dispidSharingCaps
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A17
Data type: | PT_LONG
Area: | Sharing

Remarks

This property must be set to one of the following values:

Value | Scenario
0x00040290 | This Sharing Message object relates to a special folder.
0x000402B0 | This Sharing Message object does not relate to a special folder.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingConfigurationUrl Canonical Property

 Copy code hover
[image]

PidLidSharingConfigurationUrl Canonical Property
See also Send feedback

Published: July 16, 2012

Designates as a property of a sharing message.

Associated properties: | dispidSharingConfigUrl
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A24
Data type: | PT_UNICODE
Area: | Sharing

Remarks

The value of this property must be a zero-length string.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingFlavor Canonical Property

 Copy code hover
[image]

PidLidSharingFlavor Canonical Property
See also Send feedback

Published: July 16, 2012

Designates as a property of a sharing message.

Associated properties: | dispidSharingFlavor
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A18
Data type: | PT_LONG
Area: | Sharing

Remarks

The value of this property must be one of the following:

Value | Type of Sharing Message object
0x00020310 | A sharing invitation for a special folder.
0x00000310 | A sharing invitation for a folder that is not a special folder.
0x00020500 | A sharing request.
0x00020710 | Both a sharing invitation for a special folder and a sharing request for the recipient's equivalent special folder.
0x00025100 | A sharing response denying a request.
0x00023310 | A sharing response accepting a request (also a type of sharing invitation).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingInitiatorEntryId Canonical Property

 Copy code hover
[image]

PidLidSharingInitiatorEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Designates as a property of a sharing message.

Associated properties: | dispidSharingInitiatorEid
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A09
Data type: | PT_BINARY
Area: | Sharing

Remarks

This property must be set to the value of the PR_ENTRYID (PidTagEntryId) property for the Address Book of the currently logged-on user (see [MS-OXOABK]).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingInitiatorName Canonical Property

 Copy code hover
[image]

PidLidSharingInitiatorName Canonical Property
See also Send feedback

Published: July 16, 2012

Designates as a property of a sharing message.

Associated properties: | dispidSharingInitiatorName
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A07
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property must be set to the value of PR_DISPLAY_NAME (PidTagDisplayName) from the Address Book identified by dispidSharingInitiatorEid (PidLidSharingInitiatorEntryId) and should be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingInitiatorSmtp Canonical Property

 Copy code hover
[image]

PidLidSharingInitiatorSmtp Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the SMTP address of the user who initiated the sharing message. This is a property of a sharing message.

Associated properties: | dispidSharingInitiatorSmtp
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A08
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property must be set to the value of the PR_SMTP_ADDRESS (PidTagSmtpAddress) property from the Address Book identified by the dispidSharingInitiatorEid (PidLidSharingInitiatorEntryId) property and should be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingLocalType Canonical Property

 Copy code hover
[image]

PidLidSharingLocalType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the value of the PR_CONTAINER_CLASS (PidTagContainerClass) property of the folder that is being shared. This is a property of a sharing message.

Associated properties: | dispidSharingLocalType
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A14
Data type: | PT_UNICODE
Area: | Sharing

Remarks

The value of this property must be one of the following:

  • "IPF.Appointment"

  • "IPF.Contact"

  • "IPF.Task"

  • "IPF.StickyNote"

  • "IPF.Journal"

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingProviderGuid Canonical Property

 Copy code hover
[image]

PidLidSharingProviderGuid Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the sharing provider globally unique identifier (GUID). This is a property of a sharing message.

Associated properties: | dispidSharingProviderGuid
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A01
Data type: | PT_BINARY
Area: | Sharing

Remarks

The value of this property must be set to "%xAE.F0.06.00.00.00.00.00.C0.00.00.00.00.00.00.46".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingProviderName Canonical Property

 Copy code hover
[image]

PidLidSharingProviderName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-displayable name of the sharing provider that is identified by dispidSharingProviderGuid (PidLidSharingProviderGuid). This is a property of a sharing message.

Associated properties: | dispidSharingProviderName
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A02
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property should be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingProviderUrl Canonical Property

 Copy code hover
[image]

PidLidSharingProviderUrl Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the URL that is related to the sharing provider and identified by the dispidSharingProviderGuid (PidLidSharingProviderGuid) property. This is a property of a sharing message.

Associated properties: | dispidSharingProviderUrl
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A03
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property is generally used to provide more information about the sharing provider, but should be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingRemoteName Canonical Property

 Copy code hover
[image]

PidLidSharingRemoteName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the name of the remote folder that is being shared. This is a property of a sharing message.

Associated properties: | dispidSharingRemoteName
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A05
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property must be set to the value of the PR_DISPLAY_NAME (PidTagDisplayName) property on the folder being shared.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingRemoteStoreUid Canonical Property

 Copy code hover
[image]

PidLidSharingRemoteStoreUid Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the hexadecimal string representation of the value of the PR_STORE_ENTRYID (PidTagStoreEntryId) property on the shared folder. This is a property of a sharing message.

Associated properties: | dispidSharingRemoteStoreUid
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A48
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingRemoteType Canonical Property

 Copy code hover
[image]

PidLidSharingRemoteType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the type of the remote shared folder. This is a property of a sharing message.

Associated properties: | dispidSharingRemoteType
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A1D
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property must be set to the same value as the dispidSharingLocalType (PidLidSharingLocalType) property and should be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingRemoteUid Canonical Property

 Copy code hover
[image]

PidLidSharingRemoteUid Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the entry ID of the remote folder being shared. This is a property of a sharing message.

Associated properties: | dispidSharingRemoteUid
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A06
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property must be set to the hexadecimal string representation of the value of the PR_ENTRYID (PidTagEntryId) property on the folder being shared. This is a property of a sharing message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingResponseTime Canonical Property

 Copy code hover
[image]

PidLidSharingResponseTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the time at which the recipient of the sharing request sent a sharing response. This is a property of a sharing message.

Associated properties: | dispidSharingResponseTime
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A28
Data type: | PT_SYSTIME
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSharingResponseType Canonical Property

 Copy code hover
[image]

PidLidSharingResponseType Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the type of response with which the recipient of the sharing request responded. This is a property of a sharing message.

Associated properties: | dispidSharingResponseType
Property set: | PSETID_Sharing
Long ID (LID): | 0x00008A27
Data type: | PT_LONG
Area: | Sharing

Remarks

The value of this property must be set to one of the following values:

Value | Description
0x00000000 | No response
0x00000001 | Accepted
0x00000002 | Denied

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSideEffects Canonical Property

 Copy code hover
[image]

PidLidSideEffects Canonical Property
See also Send feedback

Published: July 16, 2012

Controls how a message object is handled by the client when acting on end-user input.

Associated properties: | dispidSideEffects
Property set: | PSETID_Common
Long ID (LID): | 0x00008510
Data type: | PT_LONG
Area: | Run-time configuration

Remarks

Must be set to a bitwise or zero or more of the following flags.

Name | Value | Description
seOpenToDelete | 0x0001 | Additional processing is required on the message object when deleting.
seNoFrame | 0x0008 | No UI is associated with the message object.
seCoerceToInbox | 0x0010 | Additional processing is required on the message object when moving or copying to a folder object with a PR_CONTAINER_CLASS (PidTagContainerClass) property of "IPF.Note".
seOpenTocopy | 0x0020 | Additional processing is required on the message object when copying to another folder.
seOpenToMove | 0x0040 | Additional processing is required on the message object when moving to another folder.
seOpenForCtxMenu | 0x0100 | Additional processing is required on the message object when displaying verbs to the end-user.
seCannotUndoDelete | 0x0400 | Cannot undo delete operation, must not be set unless "seOpenToDelete" is set.
seCannotUndoCopy | 0x0800 | Cannot undo copy operation, must not be set unless "seOpenTocopy" is set.
seCannotUndoMove | 0x1000 | Cannot undo move operation, must not be set unless "seOpenToMove" is set.
seHasScript | 0x2000 | The message object contains end-user script.
seOpenToPermDelete | 0x4000 | Additional processing is required to permanently delete the message object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSmartNoAttach Canonical Property

 Copy code hover
[image]

PidLidSmartNoAttach Canonical Property
See also Send feedback

Published: July 16, 2012

Represents whether the attachments on a message are considered as hidden.

Associated properties: | dispidSmartNoAttach
Property set: | PSETID_Common
Long ID (LID): | 0x00008514
Data type: | PT_BOOLEAN
Area: | Run-time configuration

Remarks

This property is TRUE if the attachments of the message are considered as hidden.

It indicates whether the message object has no end-user visible attachments. This property may be unset; if so, a default value of FALSE is assumed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidSpamOriginalFolder Canonical Property

 Copy code hover
[image]

PidLidSpamOriginalFolder Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates which folder a message was in before it was filtered into the junk e-mail folder.

Associated properties: | dispidSpamOriginalFolder
Property set: | PSETID_Common
Long ID (LID): | 0x0000859C
Data type: | PT_BINARY
Area: | Spam

Remarks

The value of this property is the EntryID of the folder that contained the message before it was moved. This property should be set when a message is marked as spam.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskAcceptanceState Canonical Property

 Copy code hover
[image]

PidLidTaskAcceptanceState Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the acceptance state of the task.

Associated properties: | dispidTaskDelegValue
Property set: | PSETID_Task
Long ID (LID): | 0x0000812A
Data type: | PT_LONG
Area: | Task

Remarks

The following table shows the possible values for this property.

Value | Description
0x00000000 | The task is not assigned.
0x00000001 | The task's acceptance status is unknown.
0x00000002 | The task assignee accepted the task. This value is set when the client processes a task acceptance.
0x00000003 | The task assignee rejected the task. This value is set when the client processes a task rejection.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskAccepted Canonical Property

 Copy code hover
[image]

PidLidTaskAccepted Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether a task assignee has replied to a task request.

Associated properties: | dispidTaskAccepted
Property set: | PSETID_Task
Long ID (LID): | 0x00008108
Data type: | PT_BOOLEAN
Area: | Task

Remarks

The client sets this property to FALSE for a new task, or the client sets this property to TRUE when a task is either accepted or rejected. If the property is left unset, a value of FALSE is assumed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskActualEffort Canonical Property

 Copy code hover
[image]

PidLidTaskActualEffort Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the number of minutes that the user performed a task.

Associated properties: | dispidTaskActualEffort
Property set: | PSETID_Task
Long ID (LID): | 0x00008110
Data type: | PT_LONG
Area: | Task

Remarks

The value must be greater than or equal to 0 and less than 0x5AE980DF (1,525,252,319), where 480 minutes equal one day and 2400 minutes equal one week (eight hours in a work day and five days in a work week).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskAssigner Canonical Property

 Copy code hover
[image]

PidLidTaskAssigner Canonical Property
See also Send feedback

Published: July 16, 2012

Names the user who was last assigned the task.

Associated properties: | dispidTaskDelegator
Property set: | PSETID_Task
Long ID (LID): | 0x00008121
Data type: | PT_UNICODE
Area: | Task

Remarks

If the task has not been assigned, this property is left unset. Because the client sets this property after the task assignee receives a task request, the property will not be set on the task assigner's copy of the task. When the client adds or removes a task assigner from the task assigner list in the dispidTaskMyDelegators (PidLidTaskAssigners) property, the dispidTaskDelegator (PidLidTaskAssigner) property must be set to the added or removed task assigner.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskAssigners Canonical Property

 Copy code hover
[image]

PidLidTaskAssigners Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a stack of entries that represent task assigners. The most recent task assigner appears at the top of the stack.

Associated properties: | dispidTaskMyDelegators
Property set: | PSETID_Task
Long ID (LID): | 0x00008117
Data type: | PT_BINARY
Area: | Task

Remarks

When the client receives a task request, it appends to this property, which structure is defined in [MS-OXOTASK], an entry that represents the task's sender. When the client receives a task rejection, the client removes the last task assigner entry from this property. When the client sends a task response, the client sends it to the last task assigner listed in the value of this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskComplete Canonical Property

 Copy code hover
[image]

PidLidTaskComplete Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the task is complete.

Associated properties: | dispidTaskComplete
Property set: | PSETID_Task
Long ID (LID): | 0x0000811C
Data type: | PT_BOOLEAN
Area: | Task

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskDateCompleted Canonical Property

 Copy code hover
[image]

PidLidTaskDateCompleted Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date when the user completes the task.

Associated properties: | dispidTaskDateCompleted
Property set: | PSETID_Task
Long ID (LID): | 0x0000810F
Data type: | PT_SYSTIME
Area: | Task

Remarks

If set, this property must have a time component of midnight in the local time zone, converted to Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskDeadOccurrence Canonical Property

 Copy code hover
[image]

PidLidTaskDeadOccurrence Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether new occurrences must be generated.

Associated properties: | dispidTaskDeadOccur
Property set: | PSETID_Task
Long ID (LID): | 0x00008109
Data type: | PT_BOOLEAN
Area: | Task

Remarks

A recurrence pattern is no longer in effect when its final instance is in the past or its specified number of instances has been generated. The client sets this property to FALSE for a new task or to TRUE when it generates the last instance of a recurring task. When you copy a task to generate a new instance, this property is set to TRUE on the copy, which is the completed instance.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskDueDate Canonical Property

 Copy code hover
[image]

PidLidTaskDueDate Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the date when the user expects to complete the task.

Associated properties: | dispidTaskDueDate
Property set: | PSETID_Task
Long ID (LID): | 0x00008105
Data type: | PT_SYSTIME
Area: | Task

Remarks

The task has no due date if this property is unset or set to 0x5AE980E0 (1,525,252,320). However, a due date is optional only if no start date is indicated in the dispidTaskStartDate (PidLidTaskStartDate) property. If the task has a due date, the value must have a time component of midnight, and the dispidCommonEnd (PidLidCommonEnd) property must also be set. If dispidTaskStartDate has a start date, then the value of the dispidTaskDueDate property must be greater than or equal to the value of dispidTaskStartDate.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskEstimatedEffort Canonical Property

 Copy code hover
[image]

PidLidTaskEstimatedEffort Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the amount of time, in minutes, that the user expects to perform a task.

Associated properties: | dispidTaskEstimatedEffort
Property set: | PSETID_Task
Long ID (LID): | 0x00008111
Data type: | PT_LONG
Area: | Task

Remarks

The value must be greater than or equal to 0 and less than 0x5AE980DF (1,525,252,319), where 480 minutes equal one day and 2400 minutes equal one week (eight hours in a work day and five days in a work week).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskFCreator Canonical Property

 Copy code hover
[image]

PidLidTaskFCreator Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the task was originally created by the current user or user agent instead of by processing a task request.

Associated properties: | dispidTaskFCreator
Property set: | PSETID_Task
Long ID (LID): | 0x0000811E
Data type: | PT_BOOLEAN
Area: | Task

Remarks

The client sets this property to TRUE when the user creates the task and to FALSE when the task is assigned by another user. If this property is left unset, a value of TRUE is assumed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskFFixOffline Canonical Property

 Copy code hover
[image]

PidLidTaskFFixOffline Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the accuracy of the dispidTaskOwner (PidLidTaskOwner) property.

Associated properties: | dispidTaskFFixOffline
Property set: | PSETID_Task
Long ID (LID): | 0x0000812C
Data type: | PT_BOOLEAN
Area: | Task

Remarks

If the dispidTaskFFixOffline property is set to FALSE or is unset, the value for the dispidTaskOwner property is correct. If dispidTaskFFixOffline is set to TRUE, the client cannot determine an accurate value for dispidTaskOwner. In that case, the client can set dispidTaskOwner to a generic owner name, such as "Unknown". However, if a client encounters a dispidTaskFFixOffline value of TRUE and can determine an accurate owner name, the client should update dispidTaskOwner and set dispidTaskFFixOffline to FALSE.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskFRecurring Canonical Property

 Copy code hover
[image]

PidLidTaskFRecurring Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the task includes a recurrence pattern.

Associated properties: | dispidTaskFRecur
Property set: | PSETID_Task
Long ID (LID): | 0x00008126
Data type: | PT_BOOLEAN
Area: | Task

Remarks

If this property is left unset, a default value of FALSE is assumed. If it is set to TRUE, the dispidTaskRecur (PidLidTaskRecurrence) and dispidTaskDeadOccur (PidLidTaskDeadOccurrence) properties must also be set as specified in [MS-OXOTASK].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskGlobalId Canonical Property

 Copy code hover
[image]

PidLidTaskGlobalId Canonical Property
See also Send feedback

Published: July 16, 2012

Locates an existing task, by using a GUID, upon receipt of a task response or task update.

Associated properties: | dispidTaskGlobalObjId
Property set: | PSETID_Common
Long ID (LID): | 0x00008519
Data type: | PT_BINARY
Area: | Task

Remarks

This property is left unset for unassigned tasks.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskHistory Canonical Property

 Copy code hover
[image]

PidLidTaskHistory Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the type of change that was last made to the task.

Associated properties: | dispidTaskHistory
Property set: | PSETID_Task
Long ID (LID): | 0x0000811A
Data type: | PT_LONG
Area: | Task

Remarks

When the value of this property is set, the dispidTaskLastUpdate (PidLidTaskLastUpdate) property must also be set to the current time. The following table shows the dispidTaskHistory property values, listed in order of decreasing priority.

Value | Description
0x00000004 | The dispidTaskDueDate (PidLidTaskDueDate) property changed.
0x00000003 | Another property was changed.
0x00000001 | The task assignee accepted this task.
0x00000002 | The task assignee rejected this task.
0x00000005 | The task was assigned to a task assignee.
0x00000000 | No changes were made.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskLastDelegate Canonical Property

 Copy code hover
[image]

PidLidTaskLastDelegate Canonical Property
See also Send feedback

Published: July 16, 2012

Names the user who most recently assigned or was assigned the task.

Associated properties: | dispidTaskLastDelegate
Property set: | PSETID_Task
Long ID (LID): | 0x00008125
Data type: | PT_UNICODE
Area: | Task

Remarks

Before sending a task request, the client sets this property to the name of the task assigner. Before sending a task response, the client sets this property to the name of the task assignee.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskLastUpdate Canonical Property

 Copy code hover
[image]

PidLidTaskLastUpdate Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the Coordinated Universal Time (UTC) and date of the most recent change that was made to the task and indicated by the dispidTaskHistory (PidLidTaskHistory) property.

Associated properties: | dispidTaskLastUpdate
Property set: | PSETID_Task
Long ID (LID): | 0x00008115
Data type: | PT_SYSTIME
Area: | Task

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskLastUser Canonical Property

 Copy code hover
[image]

PidLidTaskLastUser Canonical Property
See also Send feedback

Published: July 16, 2012

Names the most recent user who was the task owner.

Associated properties: | dispidTaskLastUser
Property set: | PSETID_Task
Long ID (LID): | 0x00008122
Data type: | PT_UNICODE
Area: | Task

Remarks

Before a client sends a task request, it sets this property to the name of the task assigner. Before a client sends a task acceptance, it sets this property to the name of the task assignee. Before a client sends a task rejection, it sets this property to the name of the task assigner.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskMode Canonical Property

 Copy code hover
[image]

PidLidTaskMode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the assignment status of the task.

Associated properties: | dispidTaskMode
Property set: | PSETID_Common
Long ID (LID): | 0x00008518
Data type: | PT_LONG
Area: | Task

Remarks

The value must be one of the following.

Value | Description
0x00000000 | The task is not assigned.
0x00000001 | The task is embedded in a task request.
0x00000002 | The task was accepted by the task assignee.
0x00000003 | The task was rejected by the task assignee.
0x00000004 | The task is embedded in a task update.
0x00000005 | The task was assigned to the task assigner.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskMultipleRecipients Canonical Property

 Copy code hover
[image]

PidLidTaskMultipleRecipients Canonical Property
See also Send feedback

Published: July 16, 2012

Provides optimization hints about the recipients of a task.

Associated properties: | dispidTaskMultRecips
Property set: | PSETID_Task
Long ID (LID): | 0x00008120
Data type: | PT_LONG
Area: | Task

Remarks

If set, this property must be set to a bitwise OR operation of zero or more of the following values.

Name | Value | Description
Sent | 0x00000001 | The task has multiple primary recipients.
Received | 0x00000002 | Although the Sent hint was not present, the client detected that the task has multiple primary recipients.
Reserved | 0x00000004 | This value is reserved.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskOrdinal Canonical Property

 Copy code hover
[image]

PidLidTaskOrdinal Canonical Property
See also Send feedback

Published: July 16, 2012

Provides an aid to custom sorting tasks.

Associated properties: | dispidTaskOrdinal
Property set: | PSETID_Task
Long ID (LID): | 0x00008123
Data type: | PT_LONG
Area: | Task

Remarks

This property may be left unset. If set, its value must be greater than "0x800186A0" (-2,147,383,648) and less than "0x7FFE7960" (2,147,383,648) and must be unique among tasks in the same folder.

Whenever the client sets this property to a number less than the negative of the current value of the PR_ORDINAL_MOST (PidTagOrdinalMost) property of the folder, the client must also update PR_ORDINAL_MOST on the folder.

The PR_ORDINAL_MOST property of the folder provides an efficient way to determine a unique value among tasks in the same folder.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskOwner Canonical Property

 Copy code hover
[image]

PidLidTaskOwner Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the task owner.

Associated properties: | dispidTaskOwner
Property set: | PSETID_Task
Long ID (LID): | 0x0000811F
Data type: | PT_UNICODE
Area: | Task

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskOwnership Canonical Property

 Copy code hover
[image]

PidLidTaskOwnership Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the role of the current user relative to the task.

Associated properties: | dispidTaskOwnership
Property set: | PSETID_Task
Long ID (LID): | 0x00008129
Data type: | PT_LONG
Area: | Task

Remarks

This property must be one of the following values.

Value | Description
0x00000000 | The task is not assigned.
0x00000001 | The task is the task assigner's copy of the task.
0x00000002 | The task is the task assignee's copy of the task.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskRecurrence Canonical Property

 Copy code hover
[image]

PidLidTaskRecurrence Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a RecurrencePattern structure that provides information about recurring tasks.

Associated properties: | dispidTaskRecur
Property set: | PSETID_Task
Long ID (LID): | 0x00008116
Data type: | PT_BINARY
Area: | Task

Remarks

For information about how to create and specify a RecurrencePattern structure, see How to: Create a Simple Recurrent Task Item.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskResetReminder Canonical Property

 Copy code hover
[image]

PidLidTaskResetReminder Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether future instances of recurring tasks need reminders, even though dispidReminderSet (PidLidReminderSet) is FALSE.

Associated properties: | dispidTaskResetReminder
Property set: | PSETID_Task
Long ID (LID): | 0x00008107
Data type: | PT_BOOLEAN
Area: | Task

Remarks

This value is set to TRUE when the task's reminder is dismissed, and set to FALSE otherwise. If left unset, a default of FALSE is assumed.

As specified in [MS-OXORMDR], the dispidReminderSet property indicates whether a reminder is set on the task. However, this property only indicates the presence of a reminder on a single task. It cannot be used alone to determine whether a future instance of a recurring task needs a reminder.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidLidReminderSet Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskStartDate Canonical Property

 Copy code hover
[image]

PidLidTaskStartDate Canonical Property
See also Send feedback

Published: July 16, 2012

The date when the user expects to begin the task.

Associated properties: | dispidTaskStartDate
Property set: | PSETID_Task
Long ID (LID): | 0x00008104
Data type: | PT_SYSTIME
Area: | Task

Remarks

If this property value is left unset, the task does not have a start date. A value of "0x5AE980E0" (1,525,252,320) also means that the task does not have a start date. If the task has a start date, the value must have a time component of midnight, and the dispidTaskDueDate (PidLidTaskDueDate) and dispidCommonStart (PidLidCommonStart) properties must also be set.

This property is shared by the Informational Flagging Protocol Specification and Task-Related Object Protocol Specification located in [MS-OXOTASK].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Specifies the properties and operations that are permissible on contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidLidTaskDueDate Canonical Property
PidLidCommonStart Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskState Canonical Property

 Copy code hover
[image]

PidLidTaskState Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the current assignment state of the task.

Associated properties: | dispidTaskState
Property set: | PSETID_Task
Long ID (LID): | 0x00008113
Data type: | PT_LONG
Area: | Task

Remarks

The value of this property must be one of the following.

Value | Description
0x00000000 | This task was created to correspond to a task that was embedded in a task rejection but could not be found locally.
0x00000001 | The task is not assigned.
0x00000002 | The task is the task assignee's copy of an assigned task.
0x00000003 | The task is the task assigner's copy of an assigned task.
0x00000004 | The task is the task assigner's copy of a rejected task.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskStatus Canonical Property

 Copy code hover
[image]

PidLidTaskStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the status of the user's progress on the task.

Associated properties: | dispidTaskStatus
Property set: | PSETID_Task
Long ID (LID): | 0x00008101
Data type: | PT_LONG
Area: | Task

Remarks

The value of this property must be set to one of the following.

Value | Description
0x00000000 | The user has not started work on the task. If this value is set, dispidPercentComplete (PidLidPercentComplete) must be 0.0.
0x00000001 | The user's work on this task is in progress. If this value is set, dispidPercentComplete must be greater than 0.0 and less than 1.0.
0x00000002 | The user's work on this task is complete. If this value is set, dispidPercentComplete must be 1.0, dispidTaskDateCompleted (PidLidTaskDateCompleted) must be the current date, and dispidTaskComplete (PidLidTaskComplete) must be TRUE.
0x00000003 | The user is waiting on somebody else.
0x00000004 | The user has deferred work on the task.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidLidPercentComplete Canonical Property
PidLidTaskDateCompleted Canonical Property
PidLidTaskComplete Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskStatusOnComplete Canonical Property

 Copy code hover
[image]

PidLidTaskStatusOnComplete Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the task assignee has been requested to send an e-mail message update when they complete the assigned task.

Associated properties: | dispidTaskSOC
Property set: | PSETID_Task
Long ID (LID): | 0x00008119
Data type: | PT_BOOLEAN
Area: | Task

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskUpdates Canonical Property

 Copy code hover
[image]

PidLidTaskUpdates Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether the task assignee has been requested to send a task update when the assigned task changes.

Associated properties: | dispidTaskUpdates
Property set: | PSETID_Task
Long ID (LID): | 0x0000811B
Data type: | PT_BOOLEAN
Area: | Task

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTaskVersion Canonical Property

 Copy code hover
[image]

PidLidTaskVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates which copy is the latest update of a task.

Associated properties: | dispidTaskVersion
Property set: | PSETID_Task
Long ID (LID): | 0x00008112
Data type: | PT_LONG
Area: | Task

Remarks

Updates with lower versions than the task are ignored.

When embedding a task in a task communication, the client sets the current version of the embedded task on the task communication as well.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Defines several objects that model the electronic equivalent of tasks, task assignments, and task updates.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTimeZone Canonical Property

 Copy code hover
[image]

PidLidTimeZone Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies information about the time zone of a recurring meeting.

Associated properties: | LID_TIME_ZONE
Property set: | PSETID_Meeting
Long ID (LID): | 0x0000000C
Data type: | PT_LONG
Area: | Meetings

Remarks

This property is only read if the dispidApptRecur (PidLidAppointmentRecur) property is not set, but if the LID_IS_RECURRING (PidLidIsRecurring) property is TRUE and the LID_IS_EXCEPTION (PidLidIsException) property is FALSE. The lower WORD specifies an index into a table that contains time zone information. From the upper WORD, only the highest bit is read. If that bit is set, then the time zone referenced will not observe daylight saving time (DST), otherwise the DST dates detailed in [MS-OXOCAL] will be followed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTimeZoneDescription Canonical Property

 Copy code hover
[image]

PidLidTimeZoneDescription Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a string description of the time zone.

Associated properties: | dispidTimeZoneDesc
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008234
Data type: | PT_UNICODE
Area: | Calendar

Remarks

This property specifies a human-readable description of the time zone that is represented by the data in the dispidTimeZoneStruct (PidLidTimeZoneStruct) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidTimeZoneStruct Canonical Property

 Copy code hover
[image]

PidLidTimeZoneStruct Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a stream that maps to the persisted format of a TZREG structure, which describes the time zone to be used for the start and end time of a recurring appointment or meeting request.

Associated properties: | dispidTimeZoneStruct
Property set: | PSETID_Appointment
Long ID (LID): | 0x00008233
Data type: | PT_BINARY
Area: | Calendar

Remarks

Microsoft Office Outlook 2003, earlier versions of Outlook, and applications that are based on Collaboration Data Objects (CDO) 1.21 whose users have not run the calendar update tool provided by Outlook or Exchange Server store the start time and end time of a recurring appointment or meeting request as relative time, and store the time zone where the appointment or meeting request is created in dispidTimeZoneStruct. However, this scheme ignores that over time, time zone rules can change, resulting in some appointments and meetings that users scheduled before the rules changed and occur at incorrect times. Users and administrators who are not running Windows Vista or who do not have automatic updates turned on should use the calendar rebasing tools that are provided by Outlook or Exchange Server to adjust the time of such appointments and meeting requests. For more information about these calendar rebasing tools and APIs that rebase calendars, see About rebasing calendars programmatically for Daylight Saving Time

Use the following little-endian format when parsing a stream obtained from dispidTimeZoneStruct, or when persisting the TZREG structure to a stream to commit to the dispidTimeZoneStruct binary property.

Copy code Copy code
long        lBias;           // offset from GMT
long        lStandardBias;   // offset from bias during standard time
long        lDaylightBias;   // offset from bias during daylight time
WORD        wStandardYear;      // matches the stStandardDate's wYear member
SYSTEMTIME  stStandardDate;  // time to switch to standard time
WORD        wDaylightYear;      // matches the stDaylightDate's wYear field
SYSTEMTIME  stDaylightDate;  // time to switch to daylight time

This property is set on a recurring series to specify time-zone information, and specifies how to convert time fields between local time and Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidToAttendeesString Canonical Property

 Copy code hover
[image]

PidLidToAttendeesString Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of all the sendable attendees who are also required attendees.

Associated properties: | dispidToAttendeesString
Property set: | PSETID_Appointment
Long ID (LID): | 0x0000823B
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value for each attendee is the PR_DISPLAY_NAME (PidTagDisplayName) property of the attendee's Address Book. Separate entries must be delimited by a semicolon followed by a space. This property is not required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidToDoOrdinalDate Canonical Property

 Copy code hover
[image]

PidLidToDoOrdinalDate Canonical Property
See also Send feedback

Published: July 16, 2012

Determines the sort order of objects in a consolidated to-do list.

Associated properties: | dispidToDoOrdinalDate
Property set: | PSETID_Common
Long ID (LID): | 0x000085A0
Data type: | PT_SYSTIME
Area: | Task

Remarks

When an object is flagged, this property should be set to the current time in Coordinated Universal Time (UTC).

If the client allows a user to reorder tasks within the consolidated task list via dragging or other mechanisms, they can use any suitable algorithm to determine the new value of this property so that the task appears in the correct place when this property is used as a sorting field.

When this property is used to sort objects and the sort results in a tie, the dispidToDoSubOrdinal (PidLidToDoSubOrdinal) property is used as a tie breaker.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidLidToDoSubOrdinal Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidToDoSubOrdinal Canonical Property

 Copy code hover
[image]

PidLidToDoSubOrdinal Canonical Property
See also Send feedback

Published: July 16, 2012

Acts as a tie breaker when the dispidToDoOrdinalDate (PidLidToDoOrdinalDate) property sorts objects and the result in a tie.

Associated properties: | dispidToDoSubOrdinal
Property set: | PSETID_Common
Long ID (LID): | 0x000085A1
Data type: | PT_UNICODE
Area: | Task

Remarks

If used, this property must be sorted lexicographically. The component characters of the string must consist of only the numerals zero through nine. This property should be initially set to "5555555". The length of this property must not exceed 254 characters (excluding the terminating NULL character).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidLidToDoOrdinalDate Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidToDoTitle Canonical Property

 Copy code hover
[image]

PidLidToDoTitle Canonical Property
See also Send feedback

Published: July 16, 2012

Contains user-specifiable text to identify this message object in a consolidated to-do list.

Associated properties: | dispidToDoTitle
Property set: | PSETID_Common
Long ID (LID): | 0x000085A4
Data type: | PT_UNICODE
Area: | Task

Remarks

This property must not be set on a task. To indicate an empty property, do not set this property to the zero-length string, but instead delete it.

When flagging a message object, and the property does not exist, a client should write the value of PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) to this property.

In a consolidated to-do list, if this property does not exist, a client should substitute the value of the PR_NORMALIZED_SUBJECT property when displaying this property in the to-do list.

On a draft message object, if the client implements sender flags, this property should be set to the same value as dispidRequest (PidLidFlagRequest).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidTagNormalizedSubject Canonical Property
PidLidFlagRequest Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidUserX509Certificate Canonical Property

 Copy code hover
[image]

PidLidUserX509Certificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains X.509 version 3 security certificates for a messaging user.

Associated properties: | dispidEMSAbX509Cert
Property set: | PSETID_Address
Long ID (LID): | 0x000080D9
Data type: | PT_MV_BINARY
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidUseTnef Canonical Property

 Copy code hover
[image]

PidLidUseTnef Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether Transport Neutral Encapsulation Format (TNEF) should be included on a message when that message is converted from MAPI to Multipurpose Internet Mail Extensions (MIME) or Simple Mail Transfer Protocol (SMTP) format.

Associated properties: | dispidUseTNEF
Property set: | PSETID_Common
Long ID (LID): | 0x00008582
Data type: | PT_BOOLEAN
Area: | Run-time configuration

Remarks

This property specifies whether TNEF should be included on a message when that message is converted from TNEF to MIME or SMTP format. This property may be absent, and if so, TNEF must not be included on the message.

This property only applies when the message is sent from a POP3/SMTP mail account and does not apply when the message is sent by other providers, such as Microsoft Exchange Server.

Under certain circumstances, such as when voting buttons are enabled or an OLE embedded object is attached to a message, Outlook can set this property to force the use of TNEF.

The PR_MSG_EDITOR_FORMAT (PidTagMessageEditorFormat) property can be used to enforce only plain text, and not TNEF, when sending a message. Because PidLidUseTNEF overrides the setting in PR_MSG_EDITOR_FORMAT, an application that wants to force plain text on an outgoing message should also look for PidLidUseTNEF and reset it to FALSE. Additionally, the add-in must remove the message features that required TNEF to avoid unusable attachments on the message that is finally sent.

Use the CCSF_USE_TNEF flag when calling IConverterSession::MAPIToMIMEStm to convert an outgoing MAPI message to a MIME stream can also enforce TNEF. This applies even if PidLidUseTNEF is not set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidValidFlagStringProof Canonical Property

 Copy code hover
[image]

PidLidValidFlagStringProof Canonical Property
See also Send feedback

Published: July 16, 2012

Validates whether the dispidRequest (PidLidFlagRequest) property's value was set by an agent who knew the value of the PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) property.

Associated properties: | dispidValidFlagStringProof
Property set: | PSETID_Common
Long ID (LID): | 0x000085BF
Data type: | PT_SYSTIME
Area: | Task

Remarks

On non-sendable objects (received mail and non-mail objects), clients should set this value to the value of PR_MESSAGE_DELIVERY_TIME when modifying dispidRequest.

Since the value of PR_MESSAGE_DELIVERY_TIME cannot be predicted by the sender, if the value of this property is equal to the value of PR_MESSAGE_DELIVERY_TIME, it is reasonably certain that the value of dispidRequest did not originate from the sender of the message. A client can decide how to present the value of dispidRequest to the end user based on the result of this comparison in accordance with the specific security policy of the client. If the value of dispidRequest is ignored due to the presence of a value for dispidFlagStringEnum (PidLidFlagString), this property must be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Reference

PidTagMessageDeliveryTime Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidVerbResponse Canonical Property

 Copy code hover
[image]

PidLidVerbResponse Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the voting option that a respondent selected.

Associated properties: | dispidVerbResponse
Property set: | PSETID_Common
Long ID (LID): | 0x00008524
Data type: | PT_UNICODE
Area: | General messaging

Remarks

This property is usually set to one of the delimited values that are contained in the dispidVerbStream (PidLidVerbStream) property on which the respondent votes.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidVerbStream Canonical Property

 Copy code hover
[image]

PidLidVerbStream Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies what voting responses the user can make in response to the message.

Associated properties: | dispidVerbStream
Property set: | PSETID_Common
Long ID (LID): | 0x00008520
Data type: | PT_BINARY
Area: | Run-time configuration

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWhere Canonical Property

 Copy code hover
[image]

PidLidWhere Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the location of an event.

Associated properties: | LID_WHERE
Property set: | PSETID_Meeting
Long ID (LID): | 0x00000002
Data type: | PT_UNICODE
Area: | Meetings

Remarks

The value of this property should be the same as the value of the dispidLocation (PidLidLocation) property from the associated meeting.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddress Canonical Property

 Copy code hover
[image]

PidLidWorkAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the contact's complete work address.

Associated properties: | dispidWorkAddress
Property set: | PSETID_Address
Long ID (LID): | 0x0000801B
Data type: | PT_UNICODE
Area: | Contact

Remarks

This property should be a combination of other physical address properties, and is based on client locale.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressCity Canonical Property

 Copy code hover
[image]

PidLidWorkAddressCity Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the city or locality portion of the contact's work address.

Associated properties: | dispidWorkAddressCity
Property set: | PSETID_Address
Long ID (LID): | 0x00008046
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressCountry Canonical Property

 Copy code hover
[image]

PidLidWorkAddressCountry Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the country or region portion of the contact's work address.

Associated properties: | dispidWorkAddressCountry
Property set: | PSETID_Address
Long ID (LID): | 0x00008049
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressCountryCode Canonical Property

 Copy code hover
[image]

PidLidWorkAddressCountryCode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the country code portion of the contact's work address.

Associated properties: | dispidWorkAddressCountryCode
Property set: | PSETID_Address
Long ID (LID): | 0x000080DB
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definition and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressPostalCode Canonical Property

 Copy code hover
[image]

PidLidWorkAddressPostalCode Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the postal code (ZIP code) portion of the contact's work address.

Associated properties: | dispidWorkAddressPostalCode
Property set: | PSETID_Address
Long ID (LID): | 0x00008048
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressPostOfficeBox Canonical Property

 Copy code hover
[image]

PidLidWorkAddressPostOfficeBox Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the post office box portion of the contact's work.

Associated properties: | dispidWorkAddressPostOfficeBox
Property set: | PSETID_Address
Long ID (LID): | 0x0000804A
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressState Canonical Property

 Copy code hover
[image]

PidLidWorkAddressState Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the state or province portion of the contact's work mailing address.

Associated properties: | dispidWorkAddressState
Property set: | PSETID_Address
Long ID (LID): | 0x00008047
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidWorkAddressStreet Canonical Property

 Copy code hover
[image]

PidLidWorkAddressStreet Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the street portion of the contact's work mailing address.

Associated properties: | dispidWorkAddressStreet
Property set: | PSETID_Address
Long ID (LID): | 0x00008045
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidYomiCompanyName Canonical Property

 Copy code hover
[image]

PidLidYomiCompanyName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the phonetic pronunciation of the contact's company name.

Associated properties: | dispidYomiCompanyName
Property set: | PSETID_Address
Long ID (LID): | 0x0000802E
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidYomiFirstName Canonical Property

 Copy code hover
[image]

PidLidYomiFirstName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the phonetic pronunciation of the contact's given name.

Associated properties: | dispidYomiFirstName
Property set: | PSETID_Address
Long ID (LID): | 0x0000802C
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidLidYomiLastName Canonical Property

 Copy code hover
[image]

PidLidYomiLastName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the phonetic pronunciation of the contact's surname.

Associated properties: | dispidYomiLastName
Property set: | PSETID_Address
Long ID (LID): | 0x0000802D
Data type: | PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameAcceptLanguage Canonical Property

 Copy code hover
[image]

PidNameAcceptLanguage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Accept-Language header field value.

Friendly names: | AcceptLanguage
Property set: | PS_INTERNET_HEADERS
Property name: | Accept-Language
Data type: | PT_UNICODE
Area: | E-mail

Remarks

To set the value of this property, Multipurpose Internet Message Extensions (MIME) clients should write an Accept-Language header field with the desired value. MIME clients may write an X-Accept-Language header field instead. MIME readers should copy the value of either header field to the value of this property. If both header fields are present, MIME readers should use the Accept-Language header field.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameApplicationName Canonical Property

 Copy code hover
[image]

PidNameApplicationName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the application that might open the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | AppName
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameAttachmentMacContentType Canonical Property

 Copy code hover
[image]

PidNameAttachmentMacContentType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Content-Type header field value for attachments that are used by Macintosh-based e-mail clients.

Friendly names: | None
Property set: | PSETID_Attachment
Property name: | AttachmentMacContentType
Data type: | PT_UNICODE
Area: | Message attachment

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameAttachmentMacInfo Canonical Property

 Copy code hover
[image]

PidNameAttachmentMacInfo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] attachment value that is comprised of appropriate header and resource fork data used by Macintosh-based e-mail clients.

Friendly names: | None
Property set: | PSETID_Attachment
Property name: | AttachmentMacInfo
Data type: | PT_BINARY
Area: | Message attachment

Remarks

For more information, see MS-OXCMAIL section 2.2.4.2 Apple File Formats.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameAudioNotes Canonical Property

 Copy code hover
[image]

PidNameAudioNotes Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the textual notes that are attached to a voice message.

Friendly names: | UMAudioNotes
Property set: | PSETID_UnifiedMessaging
Property name: | UMAudioNotes
Data type: | PT_UNICODE
Area: | Unified messaging

Remarks

To enable an end user to read and edit audio notes directly on a voice message, a client provides an edit box where the user can type a set of notes that are added to this property of the voice message object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOUM]

Specifies the properties and operations that are permissible for representing voice mail and fax messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameAuthor Canonical Property

 Copy code hover
[image]

PidNameAuthor Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the author of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Author
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameByteCount Canonical Property

 Copy code hover
[image]

PidNameByteCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the size, in bytes, of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | ByteCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameCategory Canonical Property

 Copy code hover
[image]

PidNameCategory Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the category of the file attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Category
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameCharacterCount Canonical Property

 Copy code hover
[image]

PidNameCharacterCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the character count of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | CharCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameComments Canonical Property

 Copy code hover
[image]

PidNameComments Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the comments of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Comments
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameCompany Canonical Property

 Copy code hover
[image]

PidNameCompany Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the company for which the file was created.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Company
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameContentBase Canonical Property

 Copy code hover
[image]

PidNameContentBase Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Content-Base header field value.

Friendly names: | BodyContentBase
Property set: | PS_INTERNET_HEADERS
Property name: | Content-Base
Data type: | PT_UNICODE
Area: | E-mail

Remarks

To set the value of this property, Multipurpose Internet Message Extensions (MIME) clients must write the desired value to a Content-Base header field on a MIME entity that maps to a message body. MIME readers must copy the value of a Content-Base header field on such a MIME entity to the value of this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameContentClass Canonical Property

 Copy code hover
[image]

PidNameContentClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Content-Class header field value.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | Content-Class
Data type: | PT_UNICODE
Area: | E-mail

Remarks

To set the value of this property, Multipurpose Internet Message Extensions (MIME) clients must write a Content-Class header field with the desired value. MIME readers must copy the value of a Content-Class header field to the value of this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameContentTransferEncoding Canonical Property

 Copy code hover
[image]

PidNameContentTransferEncoding Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Content-Transfer-Encoding header field value.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | Content-Transfer-Encoding
Data type: | PT_UNICODE
Area: | E-mail

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameContentType Canonical Property

 Copy code hover
[image]

PidNameContentType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Content-Type header field value.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | Content-Type
Data type: | PT_UNICODE
Area: | E-mail

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameCreateDateTimeReadOnly Canonical Property

 Copy code hover
[image]

PidNameCreateDateTimeReadOnly Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the time when the file was created.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | CreateDtmRo
Data type: | PT_SYSTIME
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameCrossReference Canonical Property

 Copy code hover
[image]

PidNameCrossReference Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an [RFC3282] Xref header field value.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | Xref
Data type: | PT_UNICODE
Area: | E-mail

Remarks

To set the value of this property, Multipurpose Internet Message Extensions (MIME) clients must write the desired value to an XRef header field. MIME readers must copy the value of an XRef header field to the value of this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameEditTime Canonical Property

 Copy code hover
[image]

PidNameEditTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the time when the file was last edited.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | EditTime
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameExchangeJunkEmailMoveStamp Canonical Property

 Copy code hover
[image]

PidNameExchangeJunkEmailMoveStamp Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the persisted message value that indicates that the message should not be processed by a spam filter because the message was either already processed or is safe.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | http://schemas.microsoft.com/exchange/junkemailmovestamp
Data type: | PT_LONG
Area: | Secure messaging

Remarks

This property is stamped on every message that is moved by the Junk E-Mail Rule or is otherwise trusted content.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameHiddenCount Canonical Property

 Copy code hover
[image]

PidNameHiddenCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the hidden value of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | HiddenCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameKeywords Canonical Property

 Copy code hover
[image]

PidNameKeywords Canonical Property
See also Send feedback

Published: July 16, 2012

Contains keywords or categories for the message object.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Keywords
Data type: | PT_MV_UNICODE
Area: | General messaging

Remarks

A multi-string value that specifies the categories for a message object, the length of each string within this property multi-value string, must be less than 256.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameLastAuthor Canonical Property

 Copy code hover
[image]

PidNameLastAuthor Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the most recent author of the attached file.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | LastAuthor
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameLastPrinted Canonical Property

 Copy code hover
[image]

PidNameLastPrinted Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the time when the file was last printed.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | LastPrinted
Data type: | PT_SYSTIME
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameLastSaveDateTime Canonical Property

 Copy code hover
[image]

PidNameLastSaveDateTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the time when the file was last saved.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | LastSaveDtm
Data type: | PT_SYSTIME
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameLineCount Canonical Property

 Copy code hover
[image]

PidNameLineCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of lines in the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | LineCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameManager Canonical Property

 Copy code hover
[image]

PidNameManager Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the manager of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Manager
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameMultimediaClipCount Canonical Property

 Copy code hover
[image]

PidNameMultimediaClipCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of multimedia clips in the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | MMClipCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameNoteCount Canonical Property

 Copy code hover
[image]

PidNameNoteCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of notes in the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | NoteCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNamePhishingStamp Canonical Property

 Copy code hover
[image]

PidNamePhishingStamp Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message value that identifies and marks messages that are likely to be phishing.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | http://schemas.microsoft.com/outlook/phishingstamp
Data type: | PT_LONG
Area: | Secure messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXPHISH]

Identifies and marks e-mail messages that are designed to trick recipients into divulging sensitive information (such as passwords and other personal information) to a non-trustworthy source.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNamePageCount Canonical Property

 Copy code hover
[image]

PidNamePageCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the page count of the file attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | PageCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameParagraphCount Canonical Property

 Copy code hover
[image]

PidNameParagraphCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of paragraphs in the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | ParCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNamePresentationFormat Canonical Property

 Copy code hover
[image]

PidNamePresentationFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the presentation format of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | PresFormat
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameRevisionNumber Canonical Property

 Copy code hover
[image]

PidNameRevisionNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the revision number of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | RevNumber
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameRightsManagementLicense Canonical Property

 Copy code hover
[image]

PidNameRightsManagementLicense Canonical Property
See also Send feedback

Published: July 16, 2012

Caches the use license for the rights-managed e-mail message.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | DRMLicense
Data type: | PT_MV_BINARY
Area: | Secure messaging

Remarks

If the property is present on a rights-managed e-mail message, the first value of this multiple binary property must contain the ZLIB (as specified in [RFC1950]) compressed use license for the rights-managed e-mail message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameSecurity Canonical Property

 Copy code hover
[image]

PidNameSecurity Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the security level of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Security
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameSlideCount Canonical Property

 Copy code hover
[image]

PidNameSlideCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the number of slides in the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | SlideCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameSubject Canonical Property

 Copy code hover
[image]

PidNameSubject Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the subject of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Subject
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameTemplate Canonical Property

 Copy code hover
[image]

PidNameTemplate Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the template of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Template
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameTitle Canonical Property

 Copy code hover
[image]

PidNameTitle Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the title of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | Title
Data type: | PT_UNICODE
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameWordCount Canonical Property

 Copy code hover
[image]

PidNameWordCount Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the word count of the file that is attached to the document.

Friendly names: | None
Property set: | PS_PUBLIC_STRINGS
Property name: | WordCount
Data type: | PT_LONG
Area: | Common

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXODOC]

Specifies the properties and operations that are permissible on documents.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingCapabilities Canonical Property

 Copy code hover
[image]

PidNameXSharingCapabilities Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the sharing capabilities of the item.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Capabilities
Data type: | PT_UNICODE
Area: | Sharing

Remarks

This property contains a value that indicates the sharing capabilities of the message object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingConfigUrl Canonical Property

 Copy code hover
[image]

PidNameXSharingConfigUrl Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingConfigUrl (PidLidSharingConfigurationUrl) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Config-Url
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingFlavor Canonical Property

 Copy code hover
[image]

PidNameXSharingFlavor Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingFlavor (PidLidSharingFlavor) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Flavor
Data type: | PT_UNICODE
Area: | Sharing

Remarks

The dispidSharingFlavor property must be one of the following values.

Value | Type of Sharing Message
0x00020310 | A sharing invitation for a special folder.
0x00000310 | A sharing invitation for a folder that is not a special folder.
0x00020500 | A sharing request.
0x00020710 | Both a sharing invitation for a special folder and a sharing request for the recipient's equivalent special folder.
0x00025100 | A sharing response that denies a request.
0x00023310 | A sharing response that accepts a request (also a type of sharing invitation).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingLocalType Canonical Property

 Copy code hover
[image]

PidNameXSharingLocalType Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the string version of the dispidSharingLocalType (PidLidSharingLocalType) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Local-Type
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingProviderGuid Canonical Property

 Copy code hover
[image]

PidNameXSharingProviderGuid Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingProviderGuid (PidLidSharingProviderGuid) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Provider-Guid
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingProviderName Canonical Property

 Copy code hover
[image]

PidNameXSharingProviderName Canonical Property
See also Send feedback

Published: July 16, 2012

Represents a user-displayable name of the sharing provider identified by the dispidSharingProviderGuid (PidLidSharingProviderGuid) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Provider-Name
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingProviderUrl Canonical Property

 Copy code hover
[image]

PidNameXSharingProviderUrl Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingProviderUrl (PidLidSharingProviderUrl) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Provider-Url
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingRemoteName Canonical Property

 Copy code hover
[image]

PidNameXSharingRemoteName Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingRemoteName (PidLidSharingRemoteName) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Remote-Name
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingRemoteStoreUid Canonical Property

 Copy code hover
[image]

PidNameXSharingRemoteStoreUid Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingRemoteStoreUid (PidLidSharingRemoteStoreUid) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Remote-Store-Uid
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingRemoteType Canonical Property

 Copy code hover
[image]

PidNameXSharingRemoteType Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingRemoteType (PidLidSharingRemoteType) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Remote-Type
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidNameXSharingRemoteUid Canonical Property

 Copy code hover
[image]

PidNameXSharingRemoteUid Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the value of the dispidSharingRemoteUid (PidLidSharingRemoteUid) property.

Friendly names: | None
Property set: | PS_INTERNET_HEADERS
Property name: | X-Sharing-Remote-Uid
Data type: | PT_UNICODE
Area: | Sharing

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTag7BitDisplayName Canonical Property

 Copy code hover
[image]

PidTag7BitDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a 7-bit ASCII representation of a messaging user's name.

Associated properties: | PR_7BIT_DISPLAY_NAME, PR_7BIT_DISPLAY_NAME_A, PR_7BIT_DISPLAY_NAME_W
Identifier: | 0x39FF
Data type: | PT_STRING8, PT_UNICODE
Area: | Address book

Remarks

These properties map the PR_DISPLAY_NAME (PidTagDisplayName) property into a 7-bit character set. Some messaging systems, such as Internet and certain X.400 links, are limited to the 128-character 7-bit ASCII code set. Gateways to such messaging systems can improve their performance by calling the IAddrBook::PrepareRecips method directly to retrieve the this property, thereby avoiding extra processing for code conversion.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations on lists of users, contacts, groups and resources.

[MS-NSPI]

Handles a client's communications with an NSPI server.

[MS-OXCFXICS]

Handles the order and data flow that is used to transfers data between client and server.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbDefaultDir Canonical Property

 Copy code hover
[image]

PidTagAbDefaultDir Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the address book container to display first.

Associated properties: | PR_AB_DEFAULT_DIR
Identifier: | 0x3D06
Data type: | PT_BINARY
Area: | Address book

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Reference

IAddrBook::SetDefaultDir

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbDefaultPab Canonical Property

 Copy code hover
[image]

PidTagAbDefaultPab Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the address book container to use as the personal address book (PAB).

Associated properties: | PR_AB_DEFAULT_PAB
Identifier: | 0x3D07
Data type: | PT_BINARY
Area: | Address book

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbProviderId Canonical Property

 Copy code hover
[image]

PidTagAbProviderId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an address book provider's MAPIUID structure.

Associated properties: | PR_AB_PROVIDER_ID
Identifier: | 0x3615
Data type: | PT_BINARY
Area: | Address book

Remarks

The MAPIUID structure identifies which address book provider supplies this particular container in the container hierarchy. The value is unique to each provider.

An address book provider can provide more than one identifier. For example, a provider that supplies two different containers can publish in PR_AB_PROVIDER_ID unique identifiers for each container.

PR_AB_PROVIDER_ID is analogous to the PR_MDB_PROVIDER (PidTagStoreProvider) property for message stores. Client applications can use PR_AB_PROVIDER_ID to find related rows in an address book hierarchy table.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Reference

MAPIUID
PidTagStoreProvider Canonical Property

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbProviders Canonical Property

 Copy code hover
[image]

PidTagAbProviders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of identifiers for address book providers in the current profile.

Associated properties: | PR_AB_PROVIDERS
Identifier: | 0x3D01
Data type: | PT_BINARY
Area: | Address book

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbSearchPath Canonical Property

 Copy code hover
[image]

PidTagAbSearchPath Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of entry identifiers for address book containers that are to be searched to resolve names.

Associated properties: | PR_AB_SEARCH_PATH
Identifier: | 0x3D05
Data type: | PT_MV_BINARY
Area: | Address book

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAbSearchPathUpdate Canonical Property

 Copy code hover
[image]

PidTagAbSearchPathUpdate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of entry identifiers for address book containers explicitly configured by the user.

Associated properties: | PR_AB_SEARCH_PATH_UPDATE
Identifier: | 0x3D11
Data type: | PT_BINARY
Area: | Address book

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAccess Canonical Property

 Copy code hover
[image]

PidTagAccess Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags indicating the operations that are available to the client for the object.

Associated properties: | PR_ACCESS
Identifier: | 0x0FF4
Data type: | PT_LONG
Area: | Access Control Properties

Remarks

This property is read-only for the client. It must be a bitwise OR of zero or more values from the following table.

Name | Value | Description
MAPI_ACCESS_MODIFY | 0x00000001 | Write
MAPI_ACCESS_READ | 0x00000002 | Read
MAPI_ACCESS_DELETE | 0x00000004 | Delete
MAPI_ACCESS_CREATE_HIERARCHY | 0x00000008 | Create subfolders in the folder hierarchy
MAPI_ACCESS_CREATE_CONTENTS | 0x00000010 | Create content messages
MAPI_ACCESS_CREATE_ASSOCIATED | 0x00000020 | Create associated content messages

The MAPI_ACCESS_DELETE, MAPI_ACCESS_MODIFY, and MAPI_ACCESS_READ flags are found on folder and message objects and in the PR_ACCESS column in contents tables and associated contents tables. The MAPI_ACCESS_CREATE_ASSOCIATED, MAPI_ACCESS_CREATE_CONTENTS, and MAPI_ACCESS_CREATE_HIERARCHY flags are found on folder objects only.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAccessControlListTable Canonical Property

 Copy code hover
[image]

PidTagAccessControlListTable Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a table that consists of all the system access control lists (SACL) applied to a folder.

Associated properties: | PR_ACL_TABLE
Identifier: | 0x3FE0
Data type: | PT_OBJECT
Area: | Access Control

Remarks

This property is present on all folder objects on an Exchange Server. Values included in this property are used for reading and modifying access control lists (ACLs) on folders. You can use the IMAPIProp::OpenProperty method with the IID_IExchangeModifyTable interface identifier to obtain an IExchangeModifyTable : IUnknown interface to the ACL table on a folder. You can use this interface to read and modify those ACLs.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAccessLevel Canonical Property

 Copy code hover
[image]

PidTagAccessLevel Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the client's access level to the object.

Associated properties: | PR_ACCESS_LEVEL
Identifier: | 0x0FF7
Data type: | PT_LONG
Area: | Access Control Properties

Remarks

This property is read-only for the client. It must be one of the following values:

Value | Description
0x00000000 | Read-Only
0x00000001 | Modify

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAccount Canonical Property

 Copy code hover
[image]

PidTagAccount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's account name.

Associated properties: | PR_ACCOUNT, PR_ACCOUNT_A, PR_ACCOUNT_W
Identifier: | 0x3A00
Data type: | PT_STRING8, PT_UNICODE
Area: | Address book

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

These properties commonly contain the recipient's e-mail name, that is, the final component of the e-mail address, which uniquely identifies the recipient in the local organization. The e-mail name corresponds to the X.400 distinguished name, which is meant to be a short name guaranteed to be unique within a certain messaging domain.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

mapitags.h

Contains definitions of properties listed as associated properties.

mapidefs.h

Provides data type definitions.

See also

Reference

IMailUser : IMAPIProp

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAcknowledgementMode Canonical Property

 Copy code hover
[image]

PidTagAcknowledgementMode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the identifier of the mode for message acknowledgment.

Associated properties: | PR_ACKNOWLEDGEMENT_MODE
Identifier: | 0x0001
Data type: | PT_LONG
Area: | Exchange

Remarks

This property can have exactly one of the following values:

Value | Description
0 | Manual acknowledgment.
1 | Automatic acknowledgment.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAdditionalRenEntryIds Canonical Property

 Copy code hover
[image]

PidTagAdditionalRenEntryIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry IDs of certain special folders.

Associated properties: | PR_ADDITIONAL_REN_ENTRYIDS
Identifier: | 0x36D8
Data type: | PT_MV_BINARY
Area: | Outlook application

Remarks

The first five entries of this multi-valued property apply to following special folders, if they exist in the store:

0 - conflicts folder

1 - sync issues folder

2 - local failures folder

3 - server failures folder

4 - junk e-mail folder

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXPHISH]

Identifies and marks e-mail messages that are designed to trick recipients into divulging sensitive information (such as passwords and other personal information) to a non-trustworthy source.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names

Other resources

About the Store API


PidTagAdditionalRenEntryIdsEx Canonical Property

 Copy code hover
[image]

PidTagAdditionalRenEntryIdsEx Canonical Property
See also Send feedback

Published: July 16, 2012

Contains special folder entry IDs for a store object. Each entry in this multi-valued property can be mapped to one or more entry IDs, that is, there is a one-to-many relationship between an entry and its associated entry IDs.

Associated properties: | PR_ADDITIONAL_REN_ENTRYIDS_EX
Identifier: | 0x36D9
Data type: | PT_BINARY
Area: | Outlook application

Remarks

If this property is used, it contains an array of blocks that specifies the entry IDs for the folders. The blocks follow the format specified by the following four tables.

PersistData Block
Name | Type | Size | Description
PersistID | WORD | 2 | Type identifier value for this PersistData entry. See the "PersistBlockType Values" table for the list of valid values.
DataElementsSize | WORD | 2 | Size, in bytes, of the DataElements field.
DataElements | array of PersistElement blocks | variable | Indicates how many PersistElement entries exist for the store. See the "PersistElement Block" table for the format of this structure.
PersistBlockType Values
Name | Value | Description
PERSIST_SENTINEL | 0x0000 | Indicates that no more PersistData blocks will be processed.
RSF_PID_RSS_SUBSCRIPTION | 0x8001 | Indicates that this block contains data for the RSS Subscriptions folder.
RSF_PID_SEND_AND_TRACK | 0x8002 | Indicates that this block contains data for the Tracked Mail Processing folder.
RSF_PID_TODO_SEARCH | 0x8004 | Indicates that this block contains data for the To-Do Search folder.
RSF_PID_CONV_ACTIONS | 0x8006 | Indicates that this block contains data for the Conversation Action Settings folder.
RSF_PID_COMBINED_ACTIONS | 0x8007 | This value is reserved.
RSF_PID_SUGGESTED_CONTACTS | 0x8008 | Indicates that this block contains data for the Suggested Contacts folder.
RSF_PID_CONTACT_SEARCH | 0x8009 | Indicates that this block contains data for the Contacts Search folder. Used only by Outlook.
RSF_PID_BUDDYLIST_PDLS | 0x800A | Indicates that this block contains data for the Instant Messaging (IM) Contact Lists folder. The referenced folder contains Personal Distribution Lists (PDLs) representing each group within the IM Contact list. Used by both Outlook and Exchange.
RSF_PID_BUDDYLIST_CONTACTS | 0x800B | Indicates that this block contains data for the IM Contacts folder. The referenced folder contains the individual contacts referenced by the IM Contact List groups. Used by both Outlook and Exchange.

If the PersistBlockType value is not one of the ones defined here, the PersistData block is ignored and processing is continued until either a PERSIST_SENTINEL PersistID is processed or the end of the stream is reached.

PersistElementBlock
Name | Type | Size | Description
ElementID | WORD | 2 | Specifies the type identifier value for this PersistElement block. See the "PersistElementType Values" table for a list of valid values.
ElementDataSize | WORD | 2 | Specifies the size, in bytes, of the ElementData field.
ElementData | array of binary data | variable | Contains the data for this PersistID + ElementID pair.
PersistElementType Values
Name | Value | Value of ElementDataSize | Description
RSF_ELID_HEADER | 0x0002 | 0x0004 | Indicates that this block's ElementData field contains a DWORD Header value. How this value is interpreted depends on the block's PersistID type. For all PersistID types specified in [MS-OXOSFLD], this value is zero.
RSF_ELID_ENTRYID | 0x0001 | variable | Indicates that this block contains the EntryID of the folder specified by PersistID.
ELEMENT_SENTINEL | 0x0000 | 0x0000 | Indicates that no more PersistElement blocks will be processed.

If the PersistElementType value is not one of the ones defined here, the PersistElement block is ignored and processing is continued until either an ELEMENT_SENTINEL ElementID is processed or the end of the stream is reached.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXPHISH]

Identifies and marks e-mail messages that are designed to trick recipients into divulging sensitive information (such as passwords and other personal information) to a non-trustworthy source.

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Property Overview
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAddressBookChooseDirectoryAutomatically Canonical Property

 Copy code hover
[image]

PidTagAddressBookChooseDirectoryAutomatically Canonical Property
See also Send feedback

Published: July 16, 2012

Enables Microsoft Outlook 2010 and Microsoft Outlook 2013 to choose the most appropriate global address list (GAL) or contact folder for the current mailbox.

Associated properties: | PR_AB_CHOOSE_DIRECTORY_AUTOMATICALLY
Identifier: | 0x3D1C000B
Property type: | PT_BOOLEAN
Area: | Address book

Remarks

This property corresponds to the Choose automatically setting in the Address Book Options dialog. When this property exists in the IID_CAPONE_PROF profile section and is set to true, the Address Book dialog no longer defaults to the container specified by the SetDefaultDir method, but chooses an address book that Outlook 2010 or Outlook 2013 considers appropriate for the context in which the dialog was displayed. Note that this may result in a poor experience for third-party address book providers.

Related Resources

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
MAPI Constants
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAddressBookHierarchicalIsHierarchicalGroup

 Copy code hover
[image]

PidTagAddressBookHierarchicalIsHierarchicalGroup
See also Send feedback

Published: July 16, 2012

Contains TRUE if the distribution list is also a departmental group. This property is available only on distribution lists.

Associated properties: | PR_EMS_AB_HAB_IS_HIERARCHICAL_GROUP
Property set: | Address Book
Long ID (LID): | 0x8CDD
Data type: | PT_BOOLEAN
Area: | Exchange Address Book

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAddressBookHierarchicalRootDepartment

 Copy code hover
[image]

PidTagAddressBookHierarchicalRootDepartment
See also Send feedback

Published: July 16, 2012

Contains the distinguished name (DN) of the hierarchical address root (HAB).

Associated properties: | PR_EMS_AB_HAB_ROOT_DEPARTMENT, PR_EMS_AB_HAB_ROOT_DEPARTMENT_A
Property set: | Address Book
Long ID (LID): | 0x8C98
Data type: | PT_STRING8
Area: | Exchange Address Book

Remarks

This is a property on the global address list (GAL) container and represents the distinguished name of the hierarchical address root. This property is only present in the offline address book and never in Active Directory Domain Services (AD DS). Callers should pass MAPI_CACHE_ONLY to the GetProps call to avoid a remote procedure call. If this is not present, callers should use PR_EMS_AB_HAB_ROOT_DEPARTMENT, which is of type PT_OBJECT, to find the root department.

Once the root department is obtained, it can have an object type MAPI_MAILUSER or MAPI_DISTLIST. If the object type is MAPI_DISTLIST, the new schema is being employed. If the object type is MAPI_MAILUSER, the previous schema is being employed.

  • Microsoft Office Outlook 2007 Service Pack 2 supports both schemas.

  • Microsoft Outlook 2010 and Microsoft Outlook 2013 support the new schema.

In the new schema, all departmental groups are also distribution lists and are of type MAPI_DISTLIST. Members of departmental groups, and departments within departmental groups are obtained by using PR_EMS_AB_MEMBER, exactly like distribution list members.

Once the root department is obtained, it can have an object type MAPI_MAILUSER or MAPI_DISTLIST. If the object type is MAPI_DISTLIST, the new schema is being used. If the object type is MAPI_MAILUSER, the old schema is being used.

In the new schema, all departmental groups are also DLs and are of type MAPI_DISTLIST.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAddressType Canonical Property

 Copy code hover
[image]

PidTagAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the messaging user's e-mail address type, such as SMTP.

Associated properties: | PR_ADDRTYPE, PR_ADDRTYPE_A, PR_ADDRTYPE_W
Identifier: | 0x3002
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the base address properties common to all messaging users. It specifies which messaging system MAPI uses to handle a given message.

This property also determines the format of the address string in the PR_EMAIL_ADRESS (PidTagEmailAddress). The string it provides can contain only the uppercase alphabetic characters from A through Z and the numbers from 0 through 9.

Valid examples for the string include:

Copy code Copy code
FAX
MHS
PROFS
SMTP
X400

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-NSPI]

Handles a client's communications with a Name Service Provider Interface (NSPI) server.

[MS-OXCDATA]

Defines the basic data structures that are used in remote operations.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

[MS-OXOABKT]

Specifies the properties and operations that are permissible for address book templates.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names
MAPI Address Types


PidTagAgingGranularity Canonical Property

 Copy code hover
[image]

PidTagAgingGranularity Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the unit of time that is used in determining the length of time an item remains in a folder before the item is archived.

Associated properties: | PR_AGING_GRANULARITY
Identifier: | 0x36EE
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

The possible values for PR_AGING_GRANULARITY can be one of the following.

Name | Value | Description
AG_MONTHS | 0 | PR_AGING_PERIOD is defined in number of months.
AG_WEEKS | 1 | PR_AGING_PERIOD is defined in number of weeks.
AG_DAYS | 2 | PR_AGING_PERIOD is defined in number of days.

The length of time that an item remains in a folder before the item is archived is determined by two properties, PR_AGING_PERIOD and PR_AGING_GRANULARITY. PR_AGING_PERIOD represents the number of time units that the item remains in the folder before it is archived.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAgingPeriod Canonical Property

 Copy code hover
[image]

PidTagAgingPeriod Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the number of time units that are used to determine the length of time that an item remains in a folder before the item is archived.

Associated properties: | PR_AGING_PERIOD
Identifier: | 0x36EC
Property type: | PT_LONG
Area: | Miscellaneous

Remarks

The length of time that an item remains in a folder before the item is archived is determined by two properties, PR_AGING_PERIOD and PR_AGING_GRANULARITY. PR_AGING_GRANULARITY represents the time unit in which PR_AGING_PERIOD is expressed, when determining this length of time.

The possible values for PR_AGING_GRANULARITY can be one of the following.

Name | Description
AG_MONTHS | PR_AGING_PERIOD is defined in number of months.
AG_WEEKS | PR_AGING_PERIOD is defined in number of weeks.
AG_DAYS | PR_AGING_PERIOD is defined in number of days.

For example, if a folder archives an item only after the item has been in the folder for two weeks, then PR_AGING_GRANULARITY is AG_WEEKS and PR_AGING_PERIOD is 2.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permitted for email message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAlternateRecipient Canonical Property

 Copy code hover
[image]

PidTagAlternateRecipient Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of entry identifiers for alternate recipients designated by the original recipient.

Associated properties: | PR_ALTERNATE_RECIPIENT
Identifier: | 0x3A01
Data type: | PT_BINARY
Area: | Address

Remarks

This property is used for auto forwarded messages. It contains a FLATENTRYLIST structure of alternate recipients. If autoforwarding is not permitted or if no alternate recipient has been designated, a nondelivery report is generated.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapitags.h

Contains definitions of properties listed as associated properties.

Mapidefs.h

Provides data type definitions.

See also

Reference

FLATENTRYLIST

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAlternateRecipientAllowed Canonical Property

 Copy code hover
[image]

PidTagAlternateRecipientAllowed Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the sender permits auto forwarding of this message.

Associated properties: | PR_ALTERNATE_RECIPIENT_ALLOWED
Identifier: | 0x0002
Data type: | PT_BOOLEAN
Area: | Address

Remarks

If auto forwarding is not permitted or if no alternate recipient has been designated, a nondelivery report should be generated.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAnr Canonical Property

 Copy code hover
[image]

PidTagAnr Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a string value for use in a property restriction on an address book container contents table.

Associated properties: | PR_ANR, PR_ANR_A, PR_ANR_W
Identifier: | 0x360C
Data type: | PT_UNICODE, PT_STRING8
Area: | Address book

Remarks

These properties do not belong to any object; it is furnished by address book providers in SPropertyRestriction structures. This property contains an ambiguous name resolution (ANR) string that can be tested against an address book container's contents table to find corresponding message recipients.

Address book providers match the value of PR_ANR and associated properties against every entry in the contents table, using a provider-defined matching algorithm. The column or columns that are used in this match are chosen by the provider as part of the algorithm. The PR_DISPLAY_NAME (PidTagDisplayName) column is the most commonly used; the PR_ACCOUNT (PidTagAccount) column is also useful when it contains the user's e-mail name.

For more information on ambiguous name resolution, see Address Book Restrictions.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IAddrBook::ResolveName
IABContainer::ResolveNames

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAssistant Canonical Property

 Copy code hover
[image]

PidTagAssistant Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the recipient's administrative assistant.

Associated properties: | PR_ASSISTANT, PR_ASSISTANT_A, PR_ASSISTANT_W
Identifier: | 0x3A30
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagAssistantTelephoneNumber Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAssistantTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagAssistantTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the telephone number of the recipient's administrative assistant.

Associated properties: | PR_ASSISTANT_TELEPHONE_NUMBER, PR_ASSISTANT_TELEPHONE_NUMBER_A, PR_ASSISTANT_TELEPHONE_NUMBER_W
Identifier: | 0x3A2E
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

The telephone number is for the assistant specified in the PR_ASSISTANT (PidTagAssistant) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAssociatedContentCount Canonical Property

 Copy code hover
[image]

PidTagAssociatedContentCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the count of items in the associated contents table of the folder.

Associated properties: | PR_ASSOC_CONTENT_COUNT
Identifier: | 0x3617
Data type: | PT_LONG
Area: | Folder

Remarks

This property contains the number of entries in the contents table of the folder.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAssociatedSharingProvider Canonical Property

 Copy code hover
[image]

PidTagAssociatedSharingProvider Canonical Property
See also Send feedback

Published: July 16, 2012

Determines whether a personal folders file (PST) store provider is configured as a Microsoft SharePoint 2010 PST.

Associated properties: | PR_ASSOCIATED_SHARING_PROVIDER
Identifier: | 0x0EA00048
Data type: | PT_CLSID
Area: | Personal storage table (.pst) internal

Remarks

This property indicates whether a PST is configured for Microsoft SharePoint 2010. If the property is not present, the PST has not been configured as a Microsoft SharePoint 2010 PST.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachAdditionalInformation Canonical Property

 Copy code hover
[image]

PidTagAttachAdditionalInformation Canonical Property
See also Send feedback

Published: July 16, 2012

Provides file type information for a non-Windows attachment.

Associated properties: | PR_ATTACH_ADDITIONAL_INFO
Identifier: | 0x370F
Data type: | PT_BINARY
Area: | Message attachment

Remarks

This property provides metadata about a particular attachment based on the attachment's encoding. For example, when the PR_ATTACH_ENCODING (PidTagAttachEncoding) property contains MacBinary, PR_ATTACH_ADDITIONAL_INFO contains a string that represents the Macintosh file creator and file type, formatted as ":CREA:TYPE" for the encoded Macintosh file.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachContentBase Canonical Property

 Copy code hover
[image]

PidTagAttachContentBase Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the content base header of a Multipurpose Internet Mail Extensions (MIME) message attachment.

Associated properties: | PR_ATTACH_CONTENT_BASE, PR_ATTACH_CONTENT_BASE_A, PR_ATTACH_CONTENT_BASE_W
Identifier: | 0x3711
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties are used for MHTML support. They represent the content base header for the appropriate MIME body part.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachContentId Canonical Property

 Copy code hover
[image]

PidTagAttachContentId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the content identification header of a Multipurpose Internet Mail Extensions (MIME) message attachment.

Associated properties: | PR_ATTACH_CONTENT_ID, PR_ATTACH_CONTENT_ID_A, PR_ATTACH_CONTENT_ID_W
Identifier: | 0x3712
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties are used for MHTML support. They represent the content identification header for the appropriate MIME body part.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachContentLocation Canonical Property

 Copy code hover
[image]

PidTagAttachContentLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the content location header of a Multipurpose Internet Mail Extensions (MIME) message attachment.

Associated properties: | PR_ATTACH_CONTENT_LOCATION, PR_ATTACH_CONTENT_LOCATION_A, PR_ATTACH_CONTENT_LOCATION_W
Identifier: | 0x3713
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties are used for MHTML support. They represent the content location header for the appropriate MIME body part.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachDataBinary Canonical Property

 Copy code hover
[image]

PidTagAttachDataBinary Canonical Property
See also Send feedback

Published: July 16, 2012

Contains binary attachment data typically accessed through the Object Linking and Embedding (OLE) IStream interface.

Associated properties: | PR_ATTACH_DATA_BIN
Identifier: | 0x3701
Data type: | PT_BINARY
Area: | Message attachment

Remarks

This property holds the attachment when the value of the PR_ATTACH_METHOD (PidTagAttachMethod) property is ATTACH_BY_VALUE, which is the usual attachment method and the only one required to be supported. PR_ATTACH_DATA_BIN also holds an OLE 1.0 OLESTREAM attachment when the value of PR_ATTACH_METHOD is ATTACH_OLE.

OLESTREAM attachments can be copied into a file by calling the OLE IStream::CopyTo method. The OLE encoding type can be determined from the PR_ATTACH_TAG (PidTagAttachTag) property.

For an OLE document file attachment, the message store provider must respond to an IMAPIProp::OpenProperty call on PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) and may optionally respond to a call on PR_ATTACH_DATA_BIN. Note that PR_ATTACH_DATA_BIN and PR_ATTACH_DATA_OBJ share the same property identifier and thus are two renditions of the same property.

For a storage object, such as a compound file in OLE 2.0 docfile format, some service providers allow it to be opened with the MAPI IStreamDocfile interface for improved performance. A provider that supports IStreamDocfile must expose it on PR_ATTACH_DATA_OBJ and may optionally expose it on PR_ATTACH_DATA_BIN.

For more information on OLE interfaces and formats, see OLE and Data Transfer.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachDataObject Canonical Property

 Copy code hover
[image]

PidTagAttachDataObject Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an attachment object typically accessed through the Object Linking and Embedding (OLE) IStorage interface.

Associated properties: | PR_ATTACH_DATA_OBJ
Identifier: | 0x3701
Data type: | PT_OBJECT
Area: | Message attachment

Remarks

This property holds the attachment when the value of the PR_ATTACH_METHOD (PidTagAttachMethod) property is ATTACH_EMBEDDED_MSG or ATTACH_OLE. The OLE encoding type can be determined from PR_ATTACH_TAG (PidTagAttachTag).

For an attachment associated with the ATTACH_EMBEDDED_MSG value, the IMessage:IMAPIProp interface can be used for faster access.

For an embedded dynamic OLE object, the PR_ATTACH_DATA_OBJ property contains its own rendering information, and the PR_ATTACH_RENDERING (PidTagAttachRendering) property should be either nonexistent or empty.

For an OLE document file attachment, the message store provider must respond to an IMAPIProp::OpenProperty call on PR_ATTACH_DATA_OBJ and may optionally respond to a call on PR_ATTACH_DATA_BIN (PidTagAttachDataBinary). The PR_ATTACH_DATA_BIN and PR_ATTACH_DATA_OBJ properties share the same property identifier and thus are two renditions of the same property.

For a storage object, such as a compound file in OLE 2.0 docfile format, some service providers allow it to be opened with the MAPI IStreamDocfile interface, a subclass of IStream with no additional members, designed to optimize performance. The potential saving is enough to justify attempting to open PR_ATTACH_DATA_OBJ through IStreamDocfile. If MAPI_E_INTERFACE_NOT_SUPPORTED is returned, the client can then open PR_ATTACH_DATA_BIN with IStream.

If the client application or service provider cannot open an attachment subobject by using PR_ATTACH_DATA_OBJ with the help of PR_ATTACH_METHOD, it should use PR_ATTACH_DATA_BIN.

For more information on OLE interfaces and formats, see OLE and Data Transfer.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachEncoding Canonical Property

 Copy code hover
[image]

PidTagAttachEncoding Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 object identifier that specifies the encoding for an attachment.

Associated properties: | PR_ATTACH_ENCODING
Identifier: | 0x3702
Data type: | PT_BINARY
Area: | Message attachment

Remarks

This property identifies the algorithm used to transform the data in an attachment.

Note The PR_ATTACH_ENCODING and PR_ATTACH_TAG (PidTagAttachTag) properties should not be confused. They are not paired or related. PR_ATTACH_TAG identifies the application that originally generated the attachment. "Object" has a much more general meaning in the term object identifier, and in X.400, than in object-oriented programming.

The object identifier syntax and sample object identifiers are defined in the MAPIOID.H header file. Values for PR_ATTACH_ENCODING are not limited to those defined in MAPIOID.H. For example, attached Macintosh files can use an identifier such as MacBinary.

For complete information on these object identifiers, see the documentation on ASN.1, X.208, and X.209. The object identifier is found in the application-reference element of the FTBP (File Transfer Body Part) environment.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachExtension Canonical Property

 Copy code hover
[image]

PidTagAttachExtension Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a file name extension that indicates the document type of an attachment.

Associated properties: | PR_ATTACH_EXTENSION, PR_ATTACH_EXTENSION_A, PR_ATTACH_EXTENSION_W
Identifier: | 0x3703
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties are set by the client application at submission time.

The messaging system uses PR_ATTACH_EXTENSION when converting message attachments (in-route conversion) or launching applications based on attachments in received messages. If the sending client does not provide a value for these properties, the message store handling the attachment is not obligated to generate it. The receiving client should first check for PR_ATTACH_EXTENSION, and if it is not provided, should parse the file name extension from the attachment's PR_ATTACH_FILENAME (PidTagAttachFilename) or PR_ATTACH_LONG_FILENAME (PidTagAttachLongFilename) property.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachFilename Canonical Property

 Copy code hover
[image]

PidTagAttachFilename Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an attachment's base file name and extension, excluding path.

Associated properties: | PR_ATTACH_FILENAME, PR_ATTACH_FILENAME_A, PR_ATTACH_FILENAME_W
Identifier: | 0x3704
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

It is recommended that attachment objects expose these properties which pertain to the ATTACH_BY_VALUE, ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, and ATTACH_BY_REF_ONLY values of the PR_ATTACH_METHOD (PidTagAttachMethod) property. PR_ATTACH_FILENAME and associated properties are required when any of these values is used.

These properties can be used as a suggested file name for saving the attachment and to supply the file name extension if the PR_ATTACH_EXTENSION (PidTagAttachExtension) property is not provided.

The file name is restricted to eight characters plus a three-character extension. For a platform that supports long file names, set both this property and the PR_ATTACH_LONG_FILENAME (PidTagAttachLongFilename) property.

MAPI works only with file names, and other strings passed to it, in the American National Standards Institute (ANSI) character set. Client applications that use file names in an original equipment manufacturer (OEM) character set must convert them to ANSI before calling MAPI.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

[MS-OXOSMIME]

Specifies S/MIME signed and encrypted message properties.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachFlags Canonical Property

 Copy code hover
[image]

PidTagAttachFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags for an attachment.

Associated properties: | PR_ATTACH_FLAGS
Identifier: | 0x3714
Data type: | PT_LONG
Area: | Message attachment

Remarks

This property is used for MHTML support.

One or more of the following flags can be set for the PR_ATTACH_FLAGS bitmask:

ATT_INVISIBLE_IN_HTML

Indicates that this attachment is not available to HTML rendering applications and should be ignored in Multipurpose Internet Mail Extensions (MIME) processing.

ATT_INVISIBLE_IN_RTF

Indicates that this attachment is not available to applications rendering in Rich Text Format (RTF) and should be ignored by MAPI.

If the PR_ATTACH_FLAGS property is zero or absent, the attachment is to be processed by all applications.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachLongFilename Canonical Property

 Copy code hover
[image]

PidTagAttachLongFilename Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an attachment's long filename and extension, excluding path.

Associated properties: | PR_ATTACH_LONG_FILENAME, PR_ATTACH_LONG_FILENAME_A, PR_ATTACH_LONG_FILENAME_W
Identifier: | 0x3707
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties pertain to the ATTACH_BY_VALUE, ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, and ATTACH_BY_REF_ONLY values of the PR_ATTACH_METHOD (PidTagAttachMethod) property. Platforms that support long filenames should set both the PR_ATTACH_LONG_FILENAME and PR_ATTACH_FILENAME (PidTagAttachFilename) properties when sending, and should check PR_ATTACH_LONG_FILENAME first when receiving.

The client application should set this property to a suggested long filename to be used if the host computer receiving a message supports long filenames. PR_ATTACH_LONG_FILENAME can be used as a filename for saving the attachment, and to supply the filename extension if the PR_ATTACH_EXTENSION (PidTagAttachExtension) property is not provided.

Unlike the filename provided by PR_ATTACH_FILENAME, this name is not restricted to an eight-character filename plus a three-character extension. Instead, it can be up to 256 characters long, including the filename, extension, and separator period.

MAPI works only with filenames in the ANSI character set. Client applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

[MS-OXOUM]

Specifies the properties and operations that are permissible for representing voice mail and fax messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mmapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachLongPathname Canonical Property

 Copy code hover
[image]

PidTagAttachLongPathname Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an attachment's fully-qualified long path and filename.

Associated properties: | PR_ATTACH_LONG_PATHNAME, PR_ATTACH_LONG_PATHNAME_A, PR_ATTACH_LONG_PATHNAME_W
Identifier: | 0x370D
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

These properties are applicable when you use any of the PR_ATTACH_METHOD (PidTagAttachMethod) property's values that indicate attachment by reference: ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, or ATTACH_BY_REF_ONLY. Platforms that support long filenames should set both PR_ATTACH_LONG_PATHNAME or associated properties and PR_ATTACH_PATHNAME (PidTagAttachPathname) properties when sending, and should check PR_ATTACH_LONG_PATHNAME or associated properties first when receiving.

The client application should set these properties to a suggested long path and filename to be used if the host machine receiving a message supports long filenames. Setting these properties indicates that the attachment data is not included with the message but is available on a common file server.

Unlike the directories and filenames provided by PR_ATTACH_PATHNAME, these directories and filenames are not restricted to an eight-character directory or filename plus three-character extension. Instead, each directory or filename can be up to 256 characters long, including the name, extension, and separator period. However, the overall path is limited to 256 characters.

Clients should use a universal naming convention (UNC) in most cases when the file is shared, and should use an absolute path when the file is local.

MAPI works only with paths and filenames in the ANSI character set. Client applications that use paths and filenames in an OEM character set must convert them to ANSI before calling MAPI.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachmentContactPhoto Canonical Property

 Copy code hover
[image]

PidTagAttachmentContactPhoto Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the existence of a photo attachment for a contact.

Associated properties: | PR_ATTACHMENT_CONTACTPHOTO
Identifier: | 0x7FFF
Data type: | PT_BOOLEAN
Area: | Message attachment

Remarks

This property's value must be set to TRUE, and there should only be one attachment on a given Contact object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachmentFlags Canonical Property

 Copy code hover
[image]

PidTagAttachmentFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates special handling for this Attachment object.

Associated properties: | PR_ATTACHMENT_FLAGS
Identifier: | 0x7FFD
Data type: | PT_LONG
Area: | Message attachment

Remarks

Must be 0x00000000, unless overridden by other protocols that extend the Message and Attachment Object Protocol as noted in [MS-OXCMSG]

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachmentHidden Canonical Property

 Copy code hover
[image]

PidTagAttachmentHidden Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether an attachment is hidden from the end user.

Associated properties: | PR_ATTACHMENT_HIDDEN
Identifier: | 0x7FFE
Data type: | PT_BOOLEAN
Area: | Message attachment

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOCAL]

Defines the basic data structures that are used in remote operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachmentLinkId Canonical Property

 Copy code hover
[image]

PidTagAttachmentLinkId Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the type of Message object to which this attachment is linked.

Associated properties: | PR_ATTACHMENT_LINKID
Identifier: | 0x7FFA
Data type: | PT_LONG
Area: | Message attachment

Remarks

Must be 0, unless overridden by other protocols that extend the Message and Attachment Object Protocol as noted in [MS-OXCMSG].

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOJRNL]

Specifies the properties and operations that are permissible for journal objects.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachMethod Canonical Property

 Copy code hover
[image]

PidTagAttachMethod Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a MAPI-defined constant representing the way the contents of an attachment can be accessed.

Associated properties: | PR_ATTACH_METHOD
Identifier: | 0x3705
Data type: | PT_LONG
Area: | Message attachment

Remarks

This property can have exactly one of the following values:

NO_ATTACHMENT

The attachment has just been created.

ATTACH_BY_VALUE

The PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property contains the attachment data.

ATTACH_BY_REFERENCE

The PR_ATTACH_PATHNAME (PidTagAttachPathname) or PR_ATTACH_LONG_PATHNAME (PidTagAttachLongPathname) property contains a fully-qualified path identifying the attachment to recipients with access to a common file server.

ATTACH_BY_REF_RESOLVE

The PR_ATTACH_PATHNAME or PR_ATTACH_LONG_PATHNAME property contains a fully-qualified path identifying the attachment.

ATTACH_BY_REF_ONLY

The PR_ATTACH_PATHNAME or PR_ATTACH_LONG_PATHNAME property contains a fully-qualified path identifying the attachment.

ATTACH_EMBEDDED_MSG

The PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property contains an embedded object that supports the IMessage interface.

ATTACH_OLE

The attachment is an embedded OLE object.

When created, all attachment objects have an initial PR_ATTACH_METHOD value of NO_ATTACHMENT.

Client applications and service providers are only required to support the attachment method represented by the ATTACH_BY_VALUE value. The other attachment methods are optional. The message store does not enforce any consistency between the value of PR_ATTACH_METHOD and the values of the other attachment properties.

Universal naming convention (UNC) names are recommended for fully-qualified paths, which should be used with ATTACH_BY_REFERENCE and ATTACH_BY_REF_ONLY. With ATTACH_BY_REF_RESOLVE, an absolute path is faster, because the MAPI spooler converts the attachment to ATTACH_BY_VALUE.

If ATTACH_BY_REFERENCE is set, PR_ATTACH_DATA_BIN must be empty. An outbound gateway can turn an ATTACH_BY_REFERENCE attachment into an ATTACH_BY_VALUE attachment by copying the attachment data into the PR_ATTACH_DATA_BIN property.

If ATTACH_BY_REF_RESOLVE is set, PR_ATTACH_DATA_BIN must be empty. When the message that contains the ATTACH_BY_REF_RESOLVE attachment is sent, the MAPI spooler copies the attachment data into an ATTACH_BY_VALUE attachment. This resolution process places the attachment data in PR_ATTACH_DATA_BIN.

If ATTACH_BY_REF_ONLY is set, PR_ATTACH_DATA_BIN must be empty, and the messaging system never resolves the attachment reference. Use this value when you want to send the link but not the data.

When the OLE object is in OLE 2.0 IStorage format, the data is accessible through PR_ATTACH_DATA_OBJ. When the OLE object is in OLE 1.0 OLESTREAM format, the data is accessible through PR_ATTACH_DATA_BIN as an IStream. The type of the OLE encoding can be determined by the PR_ATTACH_TAG (PidTagAttachTag) value.

For more information on OLE interfaces and formats, see the OLE Programmer's Reference.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagStoreSupportMask Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachMimeSequence Canonical Property

 Copy code hover
[image]

PidTagAttachMimeSequence Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the MIME sequence number of a MIME message attachment.

Associated properties: | PR_ATTACH_MIME_SEQUENCE
Identifier: | 0x3710
Data type: | PT_LONG
Area: | Message Attachment Properties

Remarks

This property is used for MHTML support. It represents the sequence number of the attachment within the parent MIME multipart body part of the MIME message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachMimeTag Canonical Property

 Copy code hover
[image]

PidTagAttachMimeTag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains formatting information about a Multipurpose Internet Mail Extensions (MIME) attachment.

Associated properties: | PR_ATTACH_MIME_TAG, PR_ATTACH_MIME_TAG_A, PR_ATTACH_MIME_TAG_W
Identifier: | 0x370E
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

If the PR_ATTACH_TAG (PidTagAttachTag) property contains the value OID_MIMETAG, the transport provider should look at these properties to determine how the attachment is formatted.

These properties are copied from the Content-type parameter of the inbound MIME header. The composition of the string is defined in the RFC 1521 document. The format is type/subtype, such as application/binary or text/plain.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachNumber Canonical Property

 Copy code hover
[image]

PidTagAttachNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a number that uniquely identifies the attachment within its parent message.

Associated properties: | PR_ATTACH_NUM
Identifier: | 0x0E21
Data type: | PT_LONG
Area: | Message attachment

Remarks

Message stores generate and maintain this property. The attachment number is the secondary sort key, after the rendering position, in the attachment table.

PR_ATTACH_NUM is used to open the attachment with the IMessage::OpenAttach method. Within a client application's session, the PR_ATTACH_NUM property of a message attachment remains constant as long as the attachment table is open.

The message store propagates changes to the table using the IMessage::CreateAttach and IMessage::DeleteAttach methods. At its option the message store can generate table notifications on open attachment tables so that clients can resynchronize to those changes.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachPathname Canonical Property

 Copy code hover
[image]

PidTagAttachPathname Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an attachment's fully-qualified path and filename.

Associated properties: | PR_ATTACH_PATHNAME, PR_ATTACH_PATHNAME_A, PR_ATTACH_PATHNAME_W
Identifier: | 0x3708
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

It is recommended that attachment subobjects expose these properties. Setting them indicates that the attachment data is not included with the message but is available on a common file server. These properties are required in conjunction with any of the PR_ATTACH_METHOD (PidTagAttachMethod) flags that indicate attachment by reference: ATTACH_BY_REFERENCE, ATTACH_BY_REF_RESOLVE, or ATTACH_BY_REF_ONLY.

Each directory or filename is restricted to an eight-character name plus a three-character extension. The overall path is restricted to 256 characters. For a platform that supports long filenames, set both these properties and PR_ATTACH_LONG_PATHNAME (PidTagAttachLongPathname).

Client applications should use a universal naming convention (UNC) in most cases when the file is shared, and should use an absolute path when the file is local.

MAPI works only with paths and filenames in the ANSI character set. Clients that use paths and filenames in an OEM character set must convert them to ANSI before calling MAPI.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

ScLocalPathFromUNC
ScUNCFromLocalPath

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachPayloadClass Canonical Property

 Copy code hover
[image]

PidTagAttachPayloadClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a MIME X-Payload-Class header field.

Associated properties: | PR_ATTACH_PAYLOAD_CLASS, PR_ATTACH_PAYLOAD_CLASS_A, PR_ATTACH_PAYLOAD_CLASS_W
Identifier: | 0x371A
Data type: | PT_STRING8, PT_UNICODE
Area: | Outlook application

Remarks

To set the value of these properties, MIME clients should write an X-Payload-Class header field to a MIME entity that will be analyzed as an attachment.

MIME readers must copy this header field value to the value of the corresponding property. MIME readers should ignore this header field when it appears on a MIME entity that is analyzed as a message or message body, rather than as an attachment.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachPayloadProviderGuidString Canonical Property

 Copy code hover
[image]

PidTagAttachPayloadProviderGuidString Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a MIME X-Payload-Provider-Guid header field.

Associated properties: | PR_ATTACH_PAYLOAD_PROV_GUID_STR, PR_ATTACH_PAYLOAD_PROV_GUID_STR_A, PR_ATTACH_PAYLOAD_PROV_GUID_STR_W
Identifier: | 0x3719
Data type: | PT_STRING8, PT_UNICODE
Area: | Outlook application

Remarks

To set the value of these properties, MIME clients should write an X-Payload-Provider-Guid header field to a MIME entity that will be analyzed as an attachment.

MIME readers must copy this header field value to the value of the corresponding property. MIME readers should ignore this header field when it appears on a MIME entity that is analyzed as a message or message body, rather than as an attachment.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachRendering Canonical Property

 Copy code hover
[image]

PidTagAttachRendering Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Microsoft Windows metafile with rendering information for an attachment.

Associated properties: | PR_ATTACH_RENDERING
Identifier: | 0x3709
Data type: | PT_BINARY
Area: | Message attachment

Remarks

The purpose of this property is to provide an icon or other pictorial representation that can be displayed within the parent message at the point of attachment. Such representation typically includes the name of the attachment, if any, and the nature of the attachment, such as a Microsoft Office Word document. A client application can use this representation in the display of the message.

For an attached file, this property usually portrays an icon for the file.

For an attached message, this property is typically not set. A client application needing to render an attached message should obtain its PR_MESSAGE_CLASS (PidTagMessageClass) property, call IMAPIFormMgr::ResolveMessageClass for a pointer to the corresponding form information object, open the IMAPIFormInfo interface on that object, and use GetProps to retrieve the PR_ICON (PidTagIcon) or PR_MINI_ICON (PidTagMiniIcon) property.

For an embedded static OLE object, this property contains a Microsoft Windows metafile that can be used to draw the attachment representation in a window.

For an embedded dynamic OLE object, the client should use the OLE data to generate the rendering information.

In all cases, the client application should be aware that this property is usually several hundred bytes in size and is subject to truncation in the attachment table. If a client wishes to render the attachment from this property without opening the attachment itself, it must work within the table truncation rule. For more information, see Working with Large Columns.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachSize Canonical Property

 Copy code hover
[image]

PidTagAttachSize Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the sum, in bytes, of the sizes of all properties on an attachment.

Associated properties: | PR_ATTACH_SIZE
Identifier: | 0x0E20
Data type: | PT_LONG
Area: | Message attachment

Remarks

It is recommended that attachment subobjects expose the PR_ATTACH_SIZE property. The sum contained in PR_ATTACH_SIZE includes the size of the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) or PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property. Accordingly, PR_ATTACH_SIZE is usually larger than the contents of the attachment alone.

This property can be used to check the approximate size of the attachment before performing a remote transfer by modem and to display progress indicators when saving the attachment to disk. It is particularly useful with attached OLE objects.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagMessageSize Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachTag Canonical Property

 Copy code hover
[image]

PidTagAttachTag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 object identifier specifying the application that supplied an attachment.

Associated properties: | PR_ATTACH_TAG
Identifier: | 0x370A
Data type: | PT_BINARY
Area: | Message attachment

Remarks

This property identifies the application that originally generated the attachment.

Note The PR_ATTACH_ENCODING (PidTagAttachEncoding) and PR_ATTACH_TAG properties should not be confused. They are not paired or related. PR_ATTACH_ENCODING identifies the algorithm used to transform the data in an attachment. "Object" has a much more general meaning in the term object identifier, and in X.400 usage, than in object-oriented programming.

The object identifier syntax and sample object identifiers are defined in the MAPIOID.H header file. Values for PR_ATTACH_TAG are not limited to those defined in MAPIOID.H.

For complete information on these object identifiers, see the documentation on ASN.1, X.208, and X.209. The object identifier is found in the application-reference element of the File Transfer Body Part (FTBP) environment.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagAttachMimeTag Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAttachTransportName Canonical Property

 Copy code hover
[image]

PidTagAttachTransportName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of an attachment file modified so that it can be associated with TNEF messages.

Associated properties: | PR_ATTACH_TRANSPORT_NAME, PR_ATTACH_TRANSPORT_NAME_A, PR_ATTACH_TRANSPORT_NAME_W
Identifier: | 0x370C
Data type: | PT_STRING8, PT_UNICODE
Area: | Message attachment

Remarks

TNEF and the transport provider use these properties. They are usually not available to client applications.

These properties are commonly used by TNEF when the underlying messaging system does not support the supplied filenames. For example, they are used when the user attaches multiple files with the same name, such as five files named CONFIG.SYS. The transport provider must modify the names to make sure they are unique. Each modified name appears in its attachment's PR_ATTACH_TRANSPORT_NAME and associated properties.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAutoConfigurationUserEmail Canonical Property

 Copy code hover
[image]

PidTagAutoConfigurationUserEmail Canonical Property
Send feedback

Published: July 16, 2012

Represents the user's e-mail address.

Associated properties: | PR_AUTOCFG_USER_EMAIL_W
Identifier: | 0x67FD
Data type: | PT_UNICODE
Area: | Message attachment


PidTagAutoConfigurationUserName Canonical Property

 Copy code hover
[image]

PidTagAutoConfigurationUserName Canonical Property
Send feedback

Published: July 16, 2012

Represents the user's display name.

Associated properties: | PR_AUTOCFG_USER_NAME_W
Identifier: | 0x67FE
Data type: | PT_UNICODE
Area: | Message attachment


PidTagAutoConfigurationUserPassword Canonical Property

 Copy code hover
[image]

PidTagAutoConfigurationUserPassword Canonical Property
Send feedback

Published: July 16, 2012

Represents the user's password.

Associated properties: | PR_AUTOCFG_USER_PASSWORD_W
Identifier: | 0x67FC
Data type: | PT_UNICODE
Area: | Message attachment


PidTagAuthorizingUsers Canonical Property

 Copy code hover
[image]

PidTagAuthorizingUsers Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of entry identifiers for users who have authorized the sending of a message.

Associated properties: | PR_AUTHORIZING_USERS
Identifier: | 0x0003
Data type: | PT_BINARY
Area: | Exchange

Remarks

The message store does not maintain this property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAutoForwardComment Canonical Property

 Copy code hover
[image]

PidTagAutoForwardComment Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a comment added by the auto-forwarding agent.

Associated properties: | PR_AUTO_FORWARD_COMMENT, PR_AUTO_FORWARD_COMMENT_A, PR_AUTO_FORWARD_COMMENT_W
Identifier: | 0x0004
Data type: | PT_STRING8, PT_UNICODE
Area: | General reporting

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagAutoForwarded Canonical Property

 Copy code hover
[image]

PidTagAutoForwarded Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the client requests an X-MS-Exchange-Organization-AutoForwarded header field.

Associated properties: | PR_AUTO_FORWARDED
Identifier: | 0x0005
Data type: | PT_BOOLEAN
Area: | General reporting

Remarks

If this property is set to FALSE or not used, no X-MS-Exchange-Organization-AutoForwarded header field will be created.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Defines each property that is used in the objects that are described by MS-OXO-prefixed documents.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBirthday Canonical Property

 Copy code hover
[image]

PidTagBirthday Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the birthday of the contact.

Associated properties: | PR_BIRTHDAY
Identifier: | 0x3A42
Data type: | PT_SYSTIME
Area: | Contact

Remarks

This property is one of the properties that provides identification and access information about a contact. These properties are defined by the user and the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBody Canonical Property

 Copy code hover
[image]

PidTagBody Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message text.

Associated properties: | PR_BODY, PR_BODY_A, PR_BODY_W
Identifier: | 0x1000
Data type: | PT_UNICODE, PT_STRING8
Area: | General messaging

Remarks

These properties are typically used only in an interpersonal message (IPM).

Message stores that support Rich Text Format (RTF) ignore any changes to white space in the message text. When PR_BODY is stored for the first time, the message store also generates and stores the PR_RTF_COMPRESSED (PidTagRtfCompressed) property, the RTF version of the message text. If the IMAPIProp::SaveChanges method is subsequently called and PR_BODY has been modified, the message store calls the RTFSync function to ensure synchronization with the RTF version. If only white space has been changed, the properties are left unchanged. This preserves any nontrivial RTF formatting when the message travels through non-RTF-aware clients and messaging systems.

The value for this property must be expressed in the code page of the operating system that MAPI is running on.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagRtfInSync Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBodyContentLocation Canonical Property

 Copy code hover
[image]

PidTagBodyContentLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a MIME Content-Location header field.

Associated properties: | PR_BODY_CONTENT_LOCATION, PR_BODY_CONTENT_LOCATION_A, PR_BODY_CONTENT_LOCATION_W
Identifier: | 0x1014
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Remarks

To set the value of these properties, MIME clients should write the desired value to a Content-Location header field on a MIME entity that maps to a message body.

MIME readers should copy the value of a Content-Location header field on such a MIME entity to the value of these properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBodyCrc Canonical Property

 Copy code hover
[image]

PidTagBodyCrc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a cyclic redundancy check (CRC) value on the message text.

Associated properties: | PR_BODY_CRC
Identifier: | 0x0E1C
Data type: | PT_LONG
Area: | Exchange

Remarks

The message store can use any CRC algorithm that generates a PT_LONG value. It must compute this property as part of the IMAPIProp::SaveChanges method when the PR_BODY (PidTagBody) property has been set for the first time and whenever it has been subsequently modified.

A client application uses PR_BODY_CRC to aid in comparing message text strings contained in PR_BODY properties or their variants. Using this property, the client can quickly and easily detect when the message text has changed. It can realize significant performance gains by using PR_BODY_CRC instead of obtaining PR_BODY from the message store and comparing it with a local version.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBodyHtml Canonical Property

 Copy code hover
[image]

PidTagBodyHtml Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the Hypertext Markup Language (HTML) version of the message text.

Associated properties: | PR_BODY_HTML, PR_BODY_HTML_A, PR_BODY_HTML_W
Identifier: | 0x1013
Data type: | PT_UNICODE, PT_STRING8
Area: | General messaging

Remarks

These properties contain the same message text as the PR_BODY_CONTENT_LOCATION (PidTagBodyContentLocation), but in HTML.

A message store that supports HTML indicates this by setting the STORE_HTML_OK flag in its PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask).

Note STORE_HTML_OK is not defined in versions of Mapidefs.h included with Microsoft® Exchange 2000 Server and earlier. If STORE_HTML_OK is undefined, use the value 0x00010000 instead.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBusiness2TelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagBusiness2TelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a secondary telephone number at the recipient's place of business.

Associated properties: | PR_BUSINESS2_TELEPHONE_NUMBER, PR_BUSINESS2_TELEPHONE_NUMBER_A, PR_BUSINESS2_TELEPHONE_NUMBER_W, PR_OFFICE2_TELEPHONE_NUMBER, PR_OFFICE2_TELEPHONE_NUMBER_A, PR_OFFICE2_TELEPHONE_NUMBER_W
Identifier: | 0x3A1B
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are examples of the properties that provide identification and access information about a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagBusinessTelephoneNumber Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBusiness2TelephoneNumbers Canonical Property

 Copy code hover
[image]

PidTagBusiness2TelephoneNumbers Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of telephone numbers for a business.

Associated properties: | PR_BUSINESS2_TELEPHONE_NUMBER_A_MV
Identifier: | 0x3A1B
Data type: | PT_MV_STRING8
Area: | Contact

Remarks

This property can be used to list alternate phone numbers or a list of extensions for a business.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBusinessFaxNumber Canonical Property

 Copy code hover
[image]

PidTagBusinessFaxNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the telephone number of the recipient's business fax machine.

Associated properties: | PR_BUSINESS_FAX_NUMBER, PR_BUSINESS_FAX_NUMBER_A, PR_BUSINESS_FAX_NUMBER_W
Identifier: | 0x3A24
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are examples of the properties that provides identification and access information about a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBusinessHomePage Canonical Property

 Copy code hover
[image]

PidTagBusinessHomePage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the URL of the home page for the business.

Associated properties: | PR_BUSINESS_HOME_PAGE, PR_BUSINESS_HOME_PAGE_A, PR_BUSINESS_HOME_PAGE_W
Identifier: | 0x3A51
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are used as a link to the contact's business home page.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagBusinessTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagBusinessTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the primary telephone number of the recipient's place of business.

Associated properties: | PR_BUSINESS_TELEPHONE_NUMBER, PR_BUSINESS_TELEPHONE_NUMBER_A, PR_BUSINESS_TELEPHONE_NUMBER_W, PR_OFFICE_TELEPHONE_NUMBER, PR_OFFICE_TELEPHONE_NUMBER_A, PR_OFFICE_TELEPHONE_NUMBER_W
Identifier: | 0x3A08
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are examples of the properties that provides identification and access information about a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCallbackTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagCallbackTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a telephone number that the message recipient can use to reach the sender.

Associated properties: | PR_CALLBACK_TELEPHONE_NUMBER, PR_CALLBACK_TELEPHONE_NUMBER_A, PR_CALLBACK_TELEPHONE_NUMBER_W
Identifier: | 0x3A02
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are examples of the properties that provides identification and access information about a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCarTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagCarTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's car telephone number.

Associated properties: | PR_CAR_TELEPHONE_NUMBER, PR_CAR_TELEPHONE_NUMBER_A, PR_CAR_TELEPHONE_NUMBER_W
Identifier: | 0x3A1E
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagChildrensNames Canonical Property

 Copy code hover
[image]

PidTagChildrensNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of names of children

Associated properties: | PR_CHILDRENS_NAMES, PR_CHILDRENS_NAMES_A, PR_CHILDRENS_NAMES_W
Identifier: | 0x3A58
Data type: | PT_MV_UNICODE, PT_MV_STRING8
Area: | Contact

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagClientSubmitTime Canonical Property

 Copy code hover
[image]

PidTagClientSubmitTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time the message sender submitted a message.

Associated properties: | PR_CLIENT_SUBMIT_TIME
Identifier: | 0x0039
Data type: | PT_SYSTIME
Area: | Message time

Remarks

The store provider sets PR_CLIENT_SUBMIT_TIME to the time that the client application called IMessage::SubmitMessage.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagComment Canonical Property

 Copy code hover
[image]

PidTagComment Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a comment about the purpose or content of an object.

Associated properties: | PR_COMMENT, PR_COMMENT_A, PR_COMMENT_W
Identifier: | 0x3004
Data type: | PT_UNICODE, PT_STRING8
Area: | Common

Remarks

The content of the string is defined by the messaging user.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidef.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCommonViewsEntryId Canonical Property

 Copy code hover
[image]

PidTagCommonViewsEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the predefined common view folder.

Associated properties: | PR_COMMON_VIEWS_ENTRYID
Identifier: | 0x35E6
Data type: | PT_BINARY
Area: | Outlook application

Remarks

The common view folder contains a predefined set of standard view specifiers, while the view folder contains specifiers defined by a messaging user. These folders, which are not visible in the interpersonal message (IPM) hierarchy, can hold many view specifiers, each one stored as a message. A client application can choose to merge the two sets of specifiers and make them both available.

For more information on views, see View Folders.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagDefaultViewEntryId Canonical Property
PidTagViewsEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCompanyMainTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagCompanyMainTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the main telephone number for a company

Associated properties: | PR_COMPANY_MAIN_PHONE_NUMBER, PR_COMPANY_MAIN_PHONE_NUMBER_A, PR_COMPANY_MAIN_PHONE_NUMBER_W
Identifier: | 0x3A57
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCompanyName Canonical Property

 Copy code hover
[image]

PidTagCompanyName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's company name.

Associated properties: | PR_COMPANY_NAME, PR_COMPANY_NAME_A, PR_COMPANY_NAME_W
Identifier: | 0x3A16
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagComputerNetworkName Canonical Property

 Copy code hover
[image]

PidTagComputerNetworkName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the network used to transmit the message.

Associated properties: | PR_COMPUTER_NETWORK_NAME, PR_COMPUTER_NETWORK_NAME_A, PR_COMPUTER_NETWORK_NAME_W
Identifier: | 0x3A49
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConflictEntryId Canonical Property

 Copy code hover
[image]

PidTagConflictEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the conflict resolution message.

Associated properties: | PR_CONFLICT_ENTRYID
Identifier: | 0x3FF0
Data type: | PT_BINARY
Area: | Incremental Change Synchronization (ICS)

Related Resources

Protocol Specifications

[MS-OXPROPS]

Defines each property that is used in the objects that are described by MS-OXO-prefixed documents.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConflictItems Canonical Property

 Copy code hover
[image]

PidTagConflictItems Canonical Property
See also Send feedback

Published: July 16, 2012

Contains one or more entry IDs of items that have been involved in an automatic conflict resolution.

Associated properties: | PR_CONFLICT_ITEMS
Identifier: | 0x1098
Property type: | PT_MV_BINARY
Area: | ICS

Remarks

The types of standard Microsoft Outlook items that support automatic conflict resolution include the following standard item types: appointment items, contact items, journal items, mail items, meeting items, sticky note items, and task items. An item belonging to a message class that derives from one of these standard item types also supports automatic conflict resolution. In Microsoft Outlook 2003 and Microsoft Office Outlook 2007, when Outlook synchronizes items and considers that there is a possibility that the resultant copy may not contain all essential data, Outlook stores the conflicting copies in the Conflicts folder, under the Sync Issues folder.

Note Note

Sync Issues and its subfolders are hidden until you click Folder List on the Go menu.

An item exposes the PR_CONFLICT_ITEMS property if it is one of the item types that support automatic conflict resolution, has won in a conflict resolution, or was placed in the Conflicts folder because of a conflict resolution. The folder in which the item is placed determines the content of PR_CONFLICT_ITEMS. If the item is located in some folder other than the Conflicts folder, and the item exposes the PR_CONFLICT_ITEMS property, the item must have won the conflict resolution, and PR_CONFLICT_ITEMS would contain one or more entry IDs of those items that lost in the conflict resolution. If the item is located in the Conflicts folder and the item exposes the PR_CONFLICT_ITEMS property, this item must have lost the conflict resolution, and PR_CONFLICT_ITEMS would contain the entry ID of the item that won in the conflict resolution.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

About MAPI Additions
MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookDisplayNames Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookDisplayNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of display names for messaging users in the contact address book.

Associated properties: | PR_CONTAB_DISPLAY_NAMES, PR_CONTAB_DISPLAY_NAMES_A, PR_CONTAB_DISPLAY_NAMES_W
Identifier: | 0x6624
Data type: | PT_MV_UNICODE, PT_MV_STRING8
Area: | Contact address book

Remarks

These properties are defined by the user and the user's organization.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookFolderEntryId Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookFolderEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for the Contacts folder in the message store where mail users are kept.

Associated properties: | PR_CONTAB_FOLDER_ENTRYID
Identifier: | 0x6610
Data type: | PT_BINARY
Area: | Contact address book

Remarks

This is a property on a Contact Address Book container, and a column in the table of Contact Address Book containers.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookFolderEntryIds Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookFolderEntryIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains identifiers for the Contacts folders in the message stores where mail users are kept.

Associated properties: | PR_CONTAB_FOLDER_ENTRYIDS
Identifier: | 0x6620
Data type: | PT_MV_BINARY
Area: | Contact address book

Remarks

This is a property on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookFolderName Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookFolderName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a folder name used for address book entries.

Associated properties: | PR_CONTAB_FOLDER_NAME, PR_CONTAB_FOLDER_NAME_W
Identifier: | 0x6613
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact address book

Remarks

The following characters cannot be used in folder names:

[ ] / \ & ~ ? * | < > " ; : +

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookFolderNames Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookFolderNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the names of the Contacts folders where mail users are kept.

Associated properties: | PR_CONTAB_FOLDER_NAMES
Identifier: | 0x6623
Data type: | PT_MV_UNICODE, PT_MV_STRING8
Area: | Contact address book

Remarks

These are properties on a Contact Address Book profile section.

Related Resources

Header Files

Mapidef.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookMultipleAddressFlag Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookMultipleAddressFlag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a flag that is TRUE when the provider supports multiple e-mail addresses per contact item.

Associated properties: | PR_CONTAB_MULTI_ADDR_FLAG
Identifier: | 0x6614
Data type: | PT_BOOLEAN
Area: | Contact address book

Remarks

If this property is TRUE, the provider does not allow contacts without e-mail addresses. If FALSE, the provider shows all contacts whether or not they have a primary e-mail address. Only the primary e-mail address will be honored. This is a property on a Contact Address Book container, and a column in the table of Contact Address Book containers.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookMultipleAddressFlags Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookMultipleAddressFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains flags that indicating whether the providers will support multiple e-mail addresses per contact item.

Associated properties: | PR_CONTAB_MULTI_ADDR_FLAGS
Identifier: | 0x6625
Data type: | PT_MV_LONG
Area: | Contact address book

Remarks

If the flags in this property are TRUE, the provider does not include contacts without e-mail addresses. Only the primary e-mail address will be honored. This is a property on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookSortFlag Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookSortFlag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a flag that is TRUE when contacts should be sorted by File Under and FALSE when they should be sorted by Display Name.

Associated properties: | PR_CONTAB_SORT_FLAG
Identifier: | 0x6602
Data type: | PT_BOOLEAN
Area: | Contact address book

Remarks

This is a property on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookStoreEntryIds Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookStoreEntryIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the Entry IDs of the stores in which folders that act as contact address book entries are found.

Associated properties: | PR_CONTAB_STORE_ENTRYIDS
Identifier: | 0x6626
Data type: | PT_MV_BINARY
Area: | Contact address book

Remarks

This is a property on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookStoreName Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookStoreName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the store associated with the Address Book provider.

Associated properties: | PR_CONTAB_STORE_NAME, PR_CONTAB_STORE_NAME_A, PR_CONTAB_STORE_NAME_W
Identifier: | 0x6612
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact address book

Remarks

These properties are on a Contact Address Book container, and a column in the table of Contact Address Book containers.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookStoreNames Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookStoreNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display names of the stores associated with the Address Book.

Associated properties: | PR_CONTAB_STORE_NAMES, PR_CONTAB_STORE_NAMES_A, PR_CONTAB_STORE_NAMES_W
Identifier: | 0x6622
Data type: | PT_MV_UNICODE, PT_MV_STRING8
Area: | Contact address book

Remarks

These properties are on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookStoreSupportMask Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookStoreSupportMask Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property obtained from the store that contains the Contacts folder.

Associated properties: | PR_CONTAB_STORE_SUPPORT_MASK
Identifier: | 0x6611
Data type: | PT_LONG
Area: | Contact address book

Remarks

The Contact Address Book provider uses this property to evaluate the adequacy of the store's supported features. This is a property on a Contact Address Book container, and a column in the table of Contact Address Book containers.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookStoreSupportMasks Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookStoreSupportMasks Canonical Property
See also Send feedback

Published: July 16, 2012

Contains flags indicating the store's supported features.

Associated properties: | PR_CONTAB_STORE_SUPPORT_MASKS
Identifier: | 0x6621
Data type: | PT_MV_LONG
Area: | Contact address book

Remarks

This property is obtained from the stores which contains the Contacts folders. The Contact Address Book provider uses it to evaluate the adequacy of the store's supported features. It is a property on a Contact Address Book profile section.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressBookUid Canonical Property

 Copy code hover
[image]

PidTagContactAddressBookUid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the UID that identifies this session of the Contact Address Book.

Associated properties: | PR_CONTAB_UID
Identifier: | 0x6601
Data type: | PT_BINARY
Area: | Contact address book

Remarks

If you have multiple Contact Address Books configured, this property must be set for each one.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactAddressTypes Canonical Property

 Copy code hover
[image]

PidTagContactAddressTypes Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of address types for a contact.

Associated properties: | PR_CONTACT_ADDRTYPES, PR_CONTACT_ADDRTYPES_A, PR_CONTACT_ADDRTYPES_W
Identifier: | 0x3A54
Data type: | PT_MV_UNICODE, PT_MV_STRING8
Area: | Contact

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContactVersion Canonical Property

 Copy code hover
[image]

PidTagContactVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the version of a recipient's contact information.

Associated properties: | PR_CONTACT_VERSION
Identifier: | 0x3A52
Data type: | PT_CLSID
Area: | Contact

Remarks

This property is one of the properties that provides identification and access information about a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContainerClass Canonical Property

 Copy code hover
[image]

PidTagContainerClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a text string describing the type of a folder. Although this property is generally ignored, versions of Microsoft® Exchange Server prior to Exchange Server 2003 Mailbox Manager expect this property to be present.

Associated properties: | PR_CONTAINER_CLASS, PR_CONTAINER_CLASS_A, PR_CONTAINER_CLASS_W
Identifier: | 0x3613
Data type: | PT_STRING8, PT_UNICODE
Area: | Container

Remarks

These properties are not normally used by Exchange Server. However, Microsoft Office Outlook® attaches them to mailbox folders. In addition, versions of Exchange Server prior to Exchange Server 2003 Mailbox Manager might incorrectly handle folders that do not have these properties.

These properties can be assigned the string values in the following table.

Value | Contents of Folder
IPF.Appointment | Appointments
IPF.Contact | Contacts
IPF.Journal | Outlook Journal entries
IPF.Note | Mail Messages and notes
IPF.StickyNote | Outlook Sticky Notes
IPF.Task | Outlook Tasks

For folders that contain mail messages, these properties should be set to IPF.Note.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContainerContents Canonical Property

 Copy code hover
[image]

PidTagContainerContents Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an embedded contents table object that provides information about a container.

Associated properties: | PR_CONTAINER_CONTENTS
Identifier: | 0x360F
Data type: | PT_OBJECT
Area: | Container

Remarks

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMAPIContainer::GetContentsTable method. For more information, see Contents Tables.

This property, PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) , and PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) are similar in usage. Several MAPI properties provide access to tables:

Property | Table
PidTagContainerContents | Contents table
PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) | Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) | Associated contents table
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Attachment table
PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) | Recipient table

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContainerFlags Canonical Property

 Copy code hover
[image]

PidTagContainerFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags describing capabilities of an address book container.

Associated properties: | PR_CONTAINER_FLAGS
Identifier: | 0x3600
Data type: | PT_LONG
Area: | Address book

Remarks

One or more of the following flags can be set for the bitmask:

AB_FIND_ON_OPEN

Displays a dialog box to request a restriction before displaying any contents of the container.

AB_MODIFIABLE

Entries can be added to and removed from the container. This flag does not indicate whether any entries in the container can be modified.

AB_RECIPIENTS

The container can hold recipients. This flag does not indicate whether any recipients are actually present in the container, or whether they can be added or removed.

AB_SUBCONTAINERS

The container can hold child containers. This flag does not indicate whether any subcontainers are actually present in the container, nor whether they can be added or removed. AB_SUBCONTAINERS must be set for the container to support IMAPIContainer::GetHierarchyTable.

AB_UNMODIFIABLE

Entries cannot be added to or removed from the container. This flag does not indicate whether any entries in the container can be modified.

The AB_FIND_ON_OPEN flag is highly recommended for containers used with online services or with slow connections to servers. When a container is opened that has AB_FIND_ON_OPEN set, a Find dialog box is presented to the user to restrict the displayed messaging users. Even a partial specification limiting the messaging users can dramatically speed up a display of the contents.

Either the AB_MODIFIABLE or AB_UNMODIFIABLE flag must be set. Both flags can be set to indicate that the container does not know whether it can be modified or not, for example if modification depends on the user's access rights. In this case, a client application must attempt a call and examine the return code to determine the container's capabilities. A client typically starts by examining AB_MODIFIABLE. If it is set, the client makes a call that attempts to modify the container and checks the return value.

The AB_MODIFIABLE flag does not indicate what types of entries can be added to the container. To determine this, the client should use the appropriate OpenProperty method to open the container's PR_CREATE_TEMPLATES (PidTagCreateTemplates) property. Opening PR_CREATE_TEMPLATES causes the container's one-off table to be returned, listing the kinds of entries that can be created in the container.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-NSPI]

Handles a client's communications with a Name Service Provider Interface (NSPI) server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContainerHierarchy Canonical Property

 Copy code hover
[image]

PidTagContainerHierarchy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an embedded hierarchy table object that provides information about the child containers.

Associated properties: | PR_CONTAINER_HIERARCHY
Identifier: | 0x360E
Data type: | PT_OBJECT
Area: | Container

Remarks

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMAPIContainer::GetHierarchyTable method. For more information, see Hierarchy Tables.

PR_CONTAINER_CONTENTS (PidTagContainerContents), PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents), and this property are similar in usage. Several MAPI properties provide access to tables:

Property | Table
PR_CONTAINER_CONTENTS (PidTagContainerContents) | Contents table
PR_CONTAINER_HIERARCHY | Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) | Associated contents table
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Attachment table
PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) | Recipient table

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentConfidentialityAlgorithmId Canonical Property

 Copy code hover
[image]

PidTagContentConfidentialityAlgorithmId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for the algorithm used to confirm message content confidentiality.

Associated properties: | PR_CONTENT_CONFIDENTIALITY_ALGORITHM_ID
Identifier: | 0x0006
Data type: | PT_BINARY
Area: | Exchange

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentCorrelator Canonical Property

 Copy code hover
[image]

PidTagContentCorrelator Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value the message sender can use to match a report with the original message.

Associated properties: | PR_CONTENT_CORRELATOR
Identifier: | 0x0007
Data type: | PT_BINARY
Area: | Exchange

Remarks

The contents of the binary string are defined by the message originator. If set on an outgoing message, this property should be copied onto any reports generated in response to the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentCount Canonical Property

 Copy code hover
[image]

PidTagContentCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the number of messages in a folder, as computed by the message store.

Associated properties: | PR_CONTENT_COUNT
Identifier: | 0x3602
Data type: | PT_LONG
Area: | Folder

Remarks

This property computed by the message store is used for two different, though related, purposes. On a MapiFolder object, it contains the number of messages in a folder. In a heading row in categorized MAPI tables, it contains the number of non-associated messages in the category corresponding to that heading row.

The number contained in this property does not include associated entries in the folder. PR_CONTENT_UNREAD (PidTagContentUnreadCount) contains the count of unread messages for the folder. A client application can read but not change this property and PR_CONTENT_UNREAD.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCTABL]

Includes permissible operations for the core table objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentIdentifier Canonical Property

 Copy code hover
[image]

PidTagContentIdentifier Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a key value that enables the message recipient to identify its content.

Associated properties: | PR_CONTENT_IDENTIFIER, PR_CONTENT_IDENTIFIER_A, PR_CONTENT_IDENTIFIER_W
Identifier: | 0x0008
Data type: | PT_STRING8, PT_UNICODE
Area: | Exchange

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentIntegrityCheck Canonical Property

 Copy code hover
[image]

PidTagContentIntegrityCheck Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 content integrity check value that allows a message sender to protect message content from disclosure to unauthorized recipients.

Associated properties: | PR_CONTENT_INTEGRITY_CHECK
Identifier: | 0x0C00
Data type: | PT_BINARY
Area: | Exchange

Remarks

This property provides for non-repudiation of message content. In conjunction with PR_MESSAGE_TOKEN (PidTagMessageToken), it ensures that the content of a message arrives at its destination unchanged.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentLength Canonical Property

 Copy code hover
[image]

PidTagContentLength Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message length, in bytes, passed to a client application or service provider to determine if a message of that length can be delivered.

Associated properties: | PR_CONTENT_LENGTH
Identifier: | 0x0009
Data type: | PT_LONG
Area: | Exchange

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentReturnRequested Canonical Property

 Copy code hover
[image]

PidTagContentReturnRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message should be returned with a nondelivery report.

Associated properties: | PR_CONTENT_RETURN_REQUESTED
Identifier: | 0x000A
Data type: | PT_BOOLEAN
Area: | Report

Remarks

If this property is not set, MAPI treats it as having a TRUE value.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagContentUnreadCount Canonical Property

 Copy code hover
[image]

PidTagContentUnreadCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the number of unread messages in a folder, as computed by the message store.

Associated properties: | PR_CONTENT_UNREAD
Identifier: | 0x3603
Data type: | PT_LONG
Area: | Folder

Remarks

This property computed by the message store is used for two different, though related, purposes. On a MAPI folder object, it contains the number of messages in a folder. In a heading row in categorized MAPI tables, it contains the number of unread non-associated messages in the category corresponding to that heading row.

This property contains the number of messages in the folder contents table for which the MSGFLAG_READ flag is not set in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property. The PR_CONTENT_COUNT (PidTagContentCount) property contains the total message count for the folder. The PR_CONTENT_COUNT and this property are read-only to clients.

Some client applications display the heading row of a category differently depending on the value of this property. For example, a client can display a category that includes unread messages in bold. This property cannot be used as a category and an attempt to do so results in the MAPI_E_INVALID_PARAMETER value being returned from the IMAPITable::SortTable method.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCTABL]

Includes permissible operations for the core table objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagControlFlags Canonical Property

 Copy code hover
[image]

PidTagControlFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags governing the behavior of a control used in a dialog box built from a display table.

Associated properties: | PR_CONTROL_FLAGS
Identifier: | 0x3F00
Data type: | PT_LONG
Area: | MAPI display table

Remarks

One or more of the following flags can be set for this property:

DT_ACCEPT_DBCS

The control can have Double-Byte Character Set (DBCS) characters in it. This flag is used with edit controls. It allows multiple-byte character sets.

DT_EDITABLE

The control can be edited; the value associated with the control can be changed. When this flag is not set, the control is read-only. This value is ignored on label, group box, standard push button, multivalued drop down list box and list box controls.

DT_MULTILINE

The edit control can contain multiple lines. This means a return character can be entered within the control. This flag is valid for edit controls only.

DT_PASSWORD_EDIT

Applies to edit controls. The edit control is treated like a password. The value is displayed using asterisks instead of echoing the actual characters entered.

DT_REQUIRED

If the control allows changes (DT_EDITABLE), it must have a value before IMAPIProp::SaveChanges is called.

DT_SET_IMMEDIATE

Enables immediate setting of a value; as soon as a value in the control changes, MAPI calls the SetProps method for the property associated with that control. When this flag is not set, the values are set when the dialog box is dismissed.

DT_SET_SELECTION

When a selection is made within the list box, the index column of that list box is set as a property. Always used with DT_SET_IMMEDIATE.

This property is stored in the ulCtlFlags member of a control's DTCTL structure. Most of the control flags apply to all of the controls that allow user input; a few apply only to the edit control. Controls that do not allow user input, such as a button or a label, set 0 for their control flags.

Many of the flag values are self-explanatory. For example, when DT_REQUIRED is set for a control, it must contain a value before the dialog box is allowed to be dismissed. Either the service provider can supply a value through its IMAPIProp implementation or the user can enter one. DT_EDITABLE indicates that the value for the control can be modified. DT_MULTILINE allows the value for an edit control to span multiple lines.

Some control flags are not so obvious in their meaning. When a control sets the DT_SET_IMMEDIATE flag, any changes to its value take affect as soon as the user moves to a new control. MAPI makes a single call to the property interface's IMAPIProp::SetProps method for the control's property. This is different from the default behavior, which is to postpone having changes to control values take effect until after the user selects the OK button or dismisses the dialog box. The DT_SET_IMMEDIATE flag is often used in combination with display table notifications.

The following table lists the types of controls and all of the flag values that can be set for each type.

Control | Valid values for this property
Button | Must be zero
Check box | DT_EDITABLE, DT_SET_IMMEDIATE
Combo box | DT_EDITABLE, DT_REQUIRED, DT_SET_IMMEDIATE
Drop-down list box | DT_EDITABLE, DT_SET_IMMEDIATE
Edit | DT_ACCEPT_DBCS, DT_MULTILINE, DT_EDITABLE, DT_PASSWORD_EDIT, DT_REQUIRED, DT_SET_IMMEDIATE
Group box | Must be zero
Label | Must be zero
List box | Must be zero
Multivalue drop-down list box | Must be zero
Multivalue list box | Must be zero
Tabbed page | Must be zero
Radio button | Must be zero

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagControlId Canonical Property

 Copy code hover
[image]

PidTagControlId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a unique identifier for a control used in a dialog box.

Associated properties: | PR_CONTROL_ID
Identifier: | 0x3F07
Data type: | PT_BINARY
Area: | MAPI display table

Remarks

This property contains a unique identifier for the control. This identifier should contain a GUID structure and a binary value of type LONG. All controls in the dialog box should use the same GUID to identify the service provider, and each control should use a unique LONG value to ensure that the controls do not collide.

This property is used in notifications. For example, notifications sent on the display table must set this property to uniquely identify the control to update.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagControlStructure Canonical Property

 Copy code hover
[image]

PidTagControlStructure Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a pointer to a structure for a control used in a dialog box.

Associated properties: | PR_CONTROL_STRUCTURE
Identifier: | 0x3F01
Data type: | PT_BINARY
Area: | MAPI display table

Remarks

This property represents a long pointer that is cast to one of the control structures. The control structures include:

DTBLBUTTON | DTBLCHECKBOX
DTBLCOMBOBOX | DTBLDDLBX
DTBLEDIT | DTBLGROUPBOX
DTBLLABEL | DTBLLBX
DTBLMVDDLBOX | DTBLMVLISTBOX
DTBLPAGE | DTBLRADIOBUTTON

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagControlType Canonical Property

 Copy code hover
[image]

PidTagControlType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value indicating a control type for a control used in a dialog box.

Associated properties: | PR_CONTROL_TYPE
Identifier: | 0x3F02
Data type: | PT_LONG
Area: | MAPI display table

Remarks

This property can have exactly one of the following values:

DTCT_BUTTON

A dialog button control.

DTCT_CHECKBOX

A dialog check box.

DTCT_COMBOBOX

A dialog combo box.

DTCT_DDLBX

A dialog drop-down list box.

DTCT_EDIT

A dialog edit text box.

DTCT_GROUPBOX

A dialog group box.

DTCT_LABEL

A dialog label.

DTCT_LBX

A dialog list box.

DTCT_LISTBOX

A dialog list box.

DTCT_MVDDLBX

A multivalued list box populated by a multivalued property of type string.

DTCT_PAGE

A dialog tabbed page.

DTCT_RADIOBUTTON

A dialog radio button.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversationIndex Canonical Property

 Copy code hover
[image]

PidTagConversationIndex Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a binary value that indicates the relative position of this message within a conversation thread.

Associated properties: | PR_CONVERSATION_INDEX
Identifier: | 0x0071
Data type: | PT_BINARY
Area: | General messaging

Remarks

A conversation thread represents a series of messages and replies. This property is usually implemented using concatenated time stamp values. Its use is optional, even if PR_CONVERSATION_TOPIC (PidTagConversationTopic) is set.

MAPI provides the ScCreateConversationIndex function to create or update a conversation index. The function takes the current index value as a counted byte array and returns the index value with a time stamp concatenated onto the end. A message representing a reply to another message should use ScCreateConversationIndex to update this property.

A message store provider has the option of assuring that PR_CONVERSATION_INDEX is always set on incoming or outgoing messages. It can do this by calling ScCreateConversationIndex, either with the existing value if this property is set or with NULL if it is not. This action should be taken before IMAPIProp::SaveChanges is called.

All messages that have the same value for PR_CONVERSATION_TOPIC can be sorted on this property to reveal the hierarchical relationship of the messages.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversationKey Canonical Property

 Copy code hover
[image]

PidTagConversationKey Canonical Property
See also Send feedback

Contains the conversation key used in Microsoft Outlook only when locating IPM.MessageManager messages, such as the message that contains download history for a Post Office Protocol (POP3) account. This property has been deprecated in Exchange Server.

Associated properties: | PR_CONVERSATION_KEY
Identifier: | 0x000B
Data type: | PT_BINARY
Area: | General messaging

Remarks

When accessing email messages as conversations and converting message properties to Transport-Neutral Encapsulation Format (TNEF), do not use this property; instead, use the PidTagConversationIndex and PidTagConversationTopic canonical properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on email message objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

IPM Subtree
MAPI Special Folders
MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversationTopic Canonical Property

 Copy code hover
[image]

PidTagConversationTopic Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the topic of the first message in a conversation thread.

Associated properties: | PR_CONVERSATION_TOPIC, PR_CONVERSATION_TOPIC_A, PR_CONVERSATION_TOPIC_W
Identifier: | 0x0070
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

A conversation thread represents a series of messages and replies. These properties are set for the first message in a thread, usually to the PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) property. Subsequent messages in the thread should use the same topic without modification.

The PR_CONVERSATION_INDEX (PidTagConversationIndex) property indicates the order relationship between subsequent messages and replies. Its use is optional, even if these properties are set.

A message store provider has the option of assuring that these properties are always set on incoming or outgoing messages. If these properties are already set they should not be altered. If not, they can be set to PR_NORMALIZED_SUBJECT. Any action should be taken before IMAPIProp::SaveChanges is called.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversionEits Canonical Property

 Copy code hover
[image]

PidTagConversionEits Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the encoded information types (EITs) that are applied to a message in transit to describe conversions.

Associated properties: | PR_CONVERSION_EITS
Identifier: | 0x000C
Data type: | PT_BINARY
Area: | Exchange

Remarks

X.400 environments use this property for both non-delivery and delivery reports.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversionProhibited Canonical Property

 Copy code hover
[image]

PidTagConversionProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if message conversions are prohibited by default for the associated messaging user.

Associated properties: | PR_CONVERSION_PROHIBITED
Identifier: | 0x3A03
Data type: | PT_BOOLEAN
Area: | Address

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConversionWithLossProhibited Canonical Property

 Copy code hover
[image]

PidTagConversionWithLossProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message transfer agent (MTA) is prohibited from making message text conversions that lose information.

Associated properties: | PR_CONVERSION_WITH_LOSS_PROHIBITED
Identifier: | 0x000D
Data type: | PT_BOOLEAN
Area: | General configuration

Remarks

An example of the type of conversion being prohibited is the "lossy" mapping from Unicode (two bytes per character) to a single-byte character set.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagConvertedEits Canonical Property

 Copy code hover
[image]

PidTagConvertedEits Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for the types of text in a message after conversion.

Associated properties: | PR_CONVERTED_EITS
Identifier: | 0x000E
Data type: | PT_BINARY
Area: | Exchange

Remarks

This property indicates which encoded information types (EITs) were used to convert the text components of the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCorrelate Canonical Property

 Copy code hover
[image]

PidTagCorrelate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the sender of a message requests the correlation feature of the messaging system.

Associated properties: | PR_CORRELATE
Identifier: | 0x0E0C
Data type: | PT_BOOLEAN
Area: | Exchange

Remarks

This property is used to request the correlation of incoming reports with the original sent message. When a transport provider encounters a submitted message with PR_CORRELATE set to TRUE, it sets the PR_CORRELATE_MTSID (PidTagCorrelateMtsid) property to the message transfer system (MTS) identifier for that message.

PR_CORRELATE should be used with messaging systems that support correlation by MTS identifier, such as X.400.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCorrelateMtsid Canonical Property

 Copy code hover
[image]

PidTagCorrelateMtsid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message transfer system (MTS) identifier used in correlating reports with sent messages.

Associated properties: | PR_CORRELATE_MTSID
Identifier: | 0x0E0D
Data type: | PT_BINARY
Area: | Exchange

Remarks

When a transport provider encounters a submitted message with this property set to TRUE, it sets this property to the MTS identifier for that message. Following transmission, this property is stored with the message in the interpersonal message (IPM) Sent Items folder.

Messaging systems that support correlation by MTS identifier, such as X.400, retain the identifier as part of the transport envelope of the original message and also of any reports generated in response to it. When a report is delivered from such a messaging system, the transport provider sets this property to the original MTS identifier from the report's transport envelope. This property is then stored with the report.

A client application can maintain a search-results folder of all messages having this property. When a report comes in for such a message, the client can apply restrictions to the search-results folder, find the original version of the message, and correlate the original message information with the new information.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCountry Canonical Property

 Copy code hover
[image]

PidTagCountry Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the recipient's country/region.

Associated properties: | PR_COUNTRY, PR_COUNTRY_A, PR_COUNTRY_W, PR_BUSINESS_ADDRESS_COUNTRY, PR_BUSINESS_ADDRESS_COUNTRY_A, PR_BUSINESS_ADDRESS_COUNTRY_W
Identifier: | 0x3A26
Data type: | PT_UNICODE, PT_STRING8
Area: | Contact

Remarks

These properties are examples of the properties that provides identification and access information about a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCreateTemplates Canonical Property

 Copy code hover
[image]

PidTagCreateTemplates Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an embedded table object that contains dialog box template entry identifiers.

Associated properties: | PR_CREATE_TEMPLATES
Identifier: | 0x3604
Data type: | PT_OBJECT
Area: | Address book

Remarks

To learn what template objects can be created inside a container, call the IMAPIProp::OpenProperty method on this property. The resulting object is the one-off table that gives the entry identifiers for all the templates that you can create inside the container.

To create the template objects, call the container object's CreateEntry method on the PR_ENTRYID (PidTagEntryId) column values from the one-off table.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IABContainer::CreateEntry

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCreationTime Canonical Property

 Copy code hover
[image]

PidTagCreationTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the creation date and time of a message.

Associated properties: | PR_CREATION_TIME
Identifier: | 0x3007
Data type: | PT_SYSTIME
Area: | Message time

Remarks

A message store sets this property for each message that it creates.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagCustomerId Canonical Property

 Copy code hover
[image]

PidTagCustomerId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the contact's customer ID number.

Associated properties: | PR_CUSTOMER_ID, PR_CUSTOMER_ID_A, PR_CUSTOMER_ID_W
Identifier: | 0x3A4A
Data type: | PT_STRING8, PT_UNICODE
Area: | Contact

Remarks

The contents of these properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefaultPostMessageClass Canonical Property

 Copy code hover
[image]

PidTagDefaultPostMessageClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of a custom form Message class.

Associated properties: | PR_DEF_POST_MSGCLASS
Identifier: | 0x36E5
Data type: | PT_STRING8
Area: | MAPI container

Remarks

If this property is set on a folder, the value must contain either exactly the base message class (for example, "IPM.Contact" for a contacts folder or "IPM.Appointment" for a calendar folder), or begin with the base message class (for example, "IPM.Contact.MyContact").

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefaultProfile Canonical Property

 Copy code hover
[image]

PidTagDefaultProfile Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a messaging user profile is the MAPI default profile.

Associated properties: | PR_DEFAULT_PROFILE
Identifier: | 0x3D04
Data type: | PT_BOOLEAN
Area: | MAPI profile

Remarks

This property does not appear as a property of any object but only as a column in a profile table. A client application can use the IProfAdmin::SetDefaultProfile method to designate the default profile.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagDefaultStore Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefaultStore Canonical Property

 Copy code hover
[image]

PidTagDefaultStore Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message store is the default message store in the message store table.

Associated properties: | PR_DEFAULT_STORE
Identifier: | 0x3400
Data type: | PT_BOOLEAN
Area: | MAPI message store

Remarks

This property appears as a column in the message store table. The value is based on PR_RESOURCE_FLAGS (PidTagResourceFlags).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefaultViewEntryId Canonical Property

 Copy code hover
[image]

PidTagDefaultViewEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of a folder's default view.

Associated properties: | PR_DEFAULT_VIEW_ENTRYID
Identifier: | 0x3616
Data type: | PT_BINARY
Area: | MAPI container

Remarks

This property is the entry identifier of the folder view that should be set as the initial view. The property need not be set if the "Normal" view is to be used as the initial view.

A client application can obtain this property at the time it opens the folder and realize significant performance gains. This property can be used as a shortcut to obtain the default view, instead of opening the associated contents table and submitting a restriction.

A service provider implementation of the IMAPIFolder::CopyFolder method can copy this property when it copies folders.

Related Resources

Protocol Specifications

[MS-OXCFOLD]

Handles folder operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefCreateDl Canonical Property

 Copy code hover
[image]

PidTagDefCreateDl Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the template entry identifier for a default distribution list.

Associated properties: | PR_DEF_CREATE_DL
Identifier: | 0x3611
Data type: | PT_BINARY
Area: | Address book

Remarks

Client applications use this property to create a distribution list within a container. Support of entry creation is optional for address book containers; those that do not support it are not required to expose this property.

This property specifies an entry that can appear in the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property for distribution lists. After obtaining the identifier, the client uses it in a call to the IABContainer::CreateEntry method. The entry represents the template for the default distribution list.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IABLogon::CompareEntryIDs

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDefCreateMailuser Canonical Property

 Copy code hover
[image]

PidTagDefCreateMailuser Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the template entry identifier for a default messaging user object.

Associated properties: | PR_DEF_CREATE_MAILUSER
Identifier: | 0x3612
Data type: | PT_BINARY
Area: | Address book

Remarks

Client applications use this property to create a messaging user object within a container. Support of entry creation is optional for address book containers; those that do not support it are not required to expose this property.

This property specifies an entry that can appear in the PR_CREATE_TEMPLATES (PidTagCreateTemplates) property for messaging users. After obtaining the identifier, the client uses it in a call to the IABContainer::CreateEntry method. The entry represents the template for the default messaging user.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeferredDeliveryTime Canonical Property

 Copy code hover
[image]

PidTagDeferredDeliveryTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when a message sender wants a message delivered.

Associated properties: | PR_DEFERRED_DELIVERY_TIME
Identifier: | 0x000F
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

MAPI does not perform the deferred delivery; it is an option of the underlying messaging system to handle deferred delivery.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeferredSendNumber Canonical Property

 Copy code hover
[image]

PidTagDeferredSendNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a number that can be used to compute the deferment of sending a message.

Associated properties: | PR_DEFERRED_SEND_NUMBER
Identifier: | 0x3FEB
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property is used for computing the PR_DEFERRED_SEND_TIME (PidTagDeferredSendTime) property when it is not present. When sending a message is deferred, the PR_DEFERRED_SEND_NUMBER property should be set along with the PR_DEFERRED_SEND_UNITS (PidTagDeferredSendUnits) property, if the PR_DEFERRED_SEND_TIME property is absent.

The PR_DEFERRED_SEND_NUMBER value must be set between 0 and 999.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeferredSendTime Canonical Property

 Copy code hover
[image]

PidTagDeferredSendTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates a time when a client would like to defer sending a message.

Associated properties: | PR_DEFERRED_SEND_TIME
Identifier: | 0x3FEF
Data type: | PT_SYSTIME
Area: | MAPI status

Remarks

If the PR_DEFERRED_SEND_UNITS (PidTagDeferredSendUnits) and PR_DEFERRED_SEND_NUMBER (PidTagDeferredSendNumber) properties are present, the value of this property is recomputed by using the following formula and the old value is ignored.

PR_DEFERRED_SEND_TIME = PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) + PR_DEFERRED_SEND_NUMBER * TimeOf(PR_DEFERRED_SEND_UNITS)

If PR_DEFERRED_SEND_TIME value is earlier than the current time (in UTC), the message is sent immediately.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeferredSendUnits Canonical Property

 Copy code hover
[image]

PidTagDeferredSendUnits Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the unit of time by which the PR_DEFERRED_SEND_NUMBER (PidTagDeferredSendNumber) property value should be multiplied.

Associated properties: | PR_DEFERRED_SEND_UNITS
Identifier: | 0x3FEC
Data type: | PT_LONG
Area: | MAPI status

Remarks

If set, this property must have one of the following values:

PidTagDeferredSendUnits | Description
0 | Minutes, for example 60 seconds
1 | Hours, for example 60x60 seconds
2 | Day, for example 24x60x60 seconds
3 | Week, for example 7x24x60x60 seconds

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDelegatedByRule Canonical Property

 Copy code hover
[image]

PidTagDelegatedByRule Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether a folder's message is delegated by a rule.

Associated properties: | PR_DELEGATED_BY_RULE
Identifier: | 0x3FE3
Data type: | PT_BOOLEAN
Area: | MAPI status

Related Resources

Protocol Specifications

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDelegateFlags Canonical Property

 Copy code hover
[image]

PidTagDelegateFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether a delegate can view the delegator's private message objects.

Associated properties: | PR_DELEGATE_FLAGS
Identifier: | 0x686B
Data type: | PT_MV_LONG
Area: | Message class-defined transmittable

Remarks

Each entry of this property must be set to one of the following values.

Flag | Value | Description
HidePrivate | 0 | The delegate should not be allowed to view private message objects.
ShowPrivate | 1 | The delegate should be allowed to view private message objects.

This property must be set in the delegate information object. The value of "ShowPrivate" indicates that the delegator wants to make private message objects visible. This preference is applicable to all folders for which the delegate has a role of reviewer, author, or editor.

Related Resources

Protocol Specifications

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeleteAfterSubmit Canonical Property

 Copy code hover
[image]

PidTagDeleteAfterSubmit Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a client application wants MAPI to delete the associated message after submission.

Associated properties: | PR_DELETE_AFTER_SUBMIT
Identifier: | 0x0E01
Data type: | PT_BOOLEAN
Area: | MAPI non-transmittable

Remarks

A client application uses this property with the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property to control what happens to a message after it is submitted. Either one or the other should be set, but not both.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeliverTime Canonical Property

 Copy code hover
[image]

PidTagDeliverTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when the original message was delivered.

Associated properties: | PR_DELIVER_TIME
Identifier: | 0x0010
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

This property is a per-recipient property on a delivery report that indicates the time the original message was delivered to the messaging user for which the delivery report is being generated.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMAPISupport::StatusRecips

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeliveryPoint Canonical Property

 Copy code hover
[image]

PidTagDeliveryPoint Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the nature of the functional entity by means of which a message was or would have been delivered to the recipient.

Associated properties: | PR_DELIVERY_POINT
Identifier: | 0x0C07
Data type: | PT_LONG
Area: | MAPI recipient

Remarks

This property can have exactly one of the following values:

MAPI_MH_DP_ML

Delivered to a distribution list, a delivery point which in turn may distribute the message to many recipients.

MAPI_MH_DP_MS

Delivered to a message store instead of directly to a recipient.

MAPI_MH_DP_OTHER_AU

Delivered to an access unit (AU) other than a physical delivery access unit (PDAU), such as a FAX system.

MAPI_MH_DP_PDAU

Delivered to a physical delivery access unit, such as a human postal carrier.

MAPI_MH_DP_PDS_PATRON

Delivered to a physical delivery system patron, such as a conventional postal mailbox.

MAPI_MH_DP_PRIVATE_UA

Delivered to a private user agent (UA), such as a client in an in-house messaging system.

MAPI_MH_DP_PUBLIC_UA

Delivered to a public user agent, or public service provider.

The default value is MAPI_MH_DP_PRIVATE_UA, that is, a MAPI client.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeltaX Canonical Property

 Copy code hover
[image]

PidTagDeltaX Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the width of a dialog box control in standard Windows dialog units.

Associated properties: | PR_DELTAX
Identifier: | 0x3F03
Data type: | PT_LONG
Area: | MAPI display table

Remarks

The PR_XPOS (PidTagXCoordinate), PR_YPOS (PidTagYCoordinate), PR_DELTAY (PidTagDeltaY) properties ,and this property control the position and size the dialog box control.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDeltaY Canonical Property

 Copy code hover
[image]

PidTagDeltaY Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the height of a dialog box control in standard Windows dialog units.

Associated properties: | PR_DELTAY
Identifier: | 0x3F04
Data type: | PT_LONG
Area: | MAPI display table

Remarks

The PR_XPOS (PidTagXCoordinate), PR_YPOS (PidTagYCoordinate), PR_DELTAX (PidTagDeltaX), and this property control the position and size the dialog box control.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDepartmentName Canonical Property

 Copy code hover
[image]

PidTagDepartmentName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a name for the department in which the recipient works.

Associated properties: | PR_DEPARTMENT_NAME, PR_DEPARTMENT_NAME_A, PR_DEPARTMENT_NAME_W
Identifier: | 0x3A18
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDepth Canonical Property

 Copy code hover
[image]

PidTagDepth Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an integer that represents the relative level of indentation, or depth, of an object in a hierarchy table.

Associated properties: | PR_DEPTH
Identifier: | 0x3005
Data type: | PT_LONG
Area: | MAPI common

Remarks

This property can also specify the categorization level of a row in a contents table or the hierarchy depth in a hierarchy table. The depth is zero-based, where zero represents the leftmost category. In all cases, the property value represents a relative value rather than an absolute value. In the hierarchy table, for example, the depth value is relative to the container from which the hierarchy table was retrieved. The depth does not represent an absolute depth from the root container.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCTABL]

Includes permissible operations for the core table objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagObjectType Canonical Property
PidTagSelectable Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDetailsTable Canonical Property

 Copy code hover
[image]

PidTagDetailsTable Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an embedded display table object.

Associated properties: | PR_DETAILS_TABLE
Identifier: | 0x3605
Data type: | PT_OBJECT
Area: | MAPI container

Remarks

Passing this property to the IMAPIProp::OpenProperty method for the object returns an IMAPITable interface that allows creation of the display table. MAPI uses this table to display property sheets for an address book object in response to an IAddrBook::Details call.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagCreateTemplates Canonical Property
PidTagSearch Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDiscardReason Canonical Property

 Copy code hover
[image]

PidTagDiscardReason Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a reason why a message transfer agent (MTA) has discarded a message.

Associated properties: | PR_DISCARD_REASON
Identifier: | 0x0011
Data type: | PT_LONG
Area: | MAPI envelope

Remarks

The reason contained in this property is used in a nondelivery report for the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagNonDeliveryReportReasonCode Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisclosureOfRecipients Canonical Property

 Copy code hover
[image]

PidTagDisclosureOfRecipients Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if disclosure of recipients is allowed.

Associated properties: | PR_DISCLOSURE_OF_RECIPIENTS
Identifier: | 0x0012
Data type: | PT_BOOLEAN
Area: | MAPI envelope

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDiscreteValues Canonical Property

 Copy code hover
[image]

PidTagDiscreteValues Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a nondelivery report applies only to discrete members of a distribution list rather than the entire list.

Associated properties: | PR_DISCRETE_VALUES
Identifier: | 0x0E0E
Data type: | PT_BOOLEAN
Area: | MAPI non-transmittable

Remarks

This property is used within a nondelivery report when the message could not be delivered to one or more members of a distribution list. Its purpose is to limit retransmission attempts to only those individual members and not the distribution list as a whole.

The recipient table of a nondelivery report contains entries for all recipients to whom the message could not be delivered, and also for the distribution lists, if any, to which they belong. The transport provider should set this property to TRUE for each distribution list entry, and it should copy the PR_DISPLAY_NAME (PidTagDisplayName), PR_ENTRYID (PidTagEntryId), and PR_SEARCH_KEY (PidTagSearchKey) from the distribution list to PR_ORIGINAL_DISPLAY_NAME (PidTagOriginalDisplayName), PR_ORIGINAL_ENTRYID (PidTagOriginalEntryId), and PR_ORIGINAL_SEARCH_KEY (PidTagOriginalSearchKey) properties for each member of that distribution list.

PR_DISCRETE_VALUES should not be set for any nondelivery report recipient entry other than a distribution list.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayBcc Canonical Property

 Copy code hover
[image]

PidTagDisplayBcc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASCII list of the display names of any blind carbon copy (BCC) message recipients, separated by semicolons (;).

Associated properties: | PR_DISPLAY_BCC, PR_DISPLAY_BCC_A, PR_DISPLAY_BCC_W
Identifier: | 0x0E02
Data type: | PT_STRING8, PT_UNICODE
Area: | Message

Remarks

The message store computes these properties on message objects by using the IMessage::ModifyRecipients method. The message store also maintains these properties so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to the IMAPIProp::SaveChanges method.

If a message has no blind carbon copy recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for PR_DISPLAY_BCC.

Because of the possible need for localization, MAPI provides these guidelines for all recipient names:

  • All names should be able to be localized.

  • The semicolon should be the character that is used to separate names in the PR_DISPLAY_BCC, PR_DISPLAY_CC (PidTagDisplayCc), and PR_DISPLAY_TO (PidTagDisplayTo) properties. Semicolons are not permitted within recipient names in MAPI.

  • Clients should translate each semicolon encountered in this property to a localized separator character before making the property information visible in the user interface.

  • When forwarding messages, clients do not need to translate the separator characters on the blind carbon copy recipient line.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Describes the format of messages used to send information related to sharing folders on the client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayCc Canonical Property

 Copy code hover
[image]

PidTagDisplayCc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASCII list of the display names of any carbon copy (CC) message recipients, separated by semicolons (;).

Associated properties: | PR_DISPLAY_CC, PR_DISPLAY_CC_A, PR_DISPLAY_CC_W
Identifier: | 0x0E03
Data type: | PT_STRING8, PT_UNICODE
Area: | Message

Remarks

The message store computes these properties on message objects by using the IMessage::ModifyRecipients method. The message store also maintains these properties so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to IMAPIProp::SaveChanges.

If a message has no carbon copy recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for these properties.

Because of the possible need for localization, MAPI provides these guidelines for all recipient names:

  • All names should be able to be localized.

  • The semicolon should be the character that is used to separate names in the PR_DISPLAY_BCC (PidTagDisplayBcc), PR_DISPLAY_CC, and PR_DISPLAY_TO (PidTagDisplayTo) properties. Semicolons are not permitted within recipient names in MAPI.

  • Clients should translate each semicolon encountered in this property to a localized separator character before making the property information visible in the user interface.

  • When forwarding messages, clients do not need to translate the separator characters on the carbon copy recipient line.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayName Canonical Property

 Copy code hover
[image]

PidTagDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for a given MAPI object.

Associated properties: | PR_DISPLAY_NAME, PR_DISPLAY_NAME_A, PR_DISPLAY_NAME_W
Identifier: | 0x3001
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

Folders require sibling subfolders to have unique display names. For example, if a folder contains two subfolders, the two subfolders cannot use the same value for this property. This restriction does not apply to other containers, such as address books and distribution lists.

Service providers should set the value of this property so that it contains both the provider type and configuration information. The additional information helps to distinguish between instances of providers of the same type. Unconfigured providers should use a string that names the provider. Configured providers should use the same string followed by a distinguishing string in parentheses. For example, an unconfigured message store provider might set these properties to:

Personal Information Store

The configured version could then set these properties to:

Personal Information Store (February 6, 1998)

For status objects, these properties contain the name of the component that can be displayed by the user interface.

Note Note

Semicolons cannot be used within recipient names in MAPI messaging.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-XWDVSEC]

Extends the WebDAV protocol that specifies how to request and set the Exchange security descriptor via WebDAV methods.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagTransmittableDisplayName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayNamePrefix Canonical Property

 Copy code hover
[image]

PidTagDisplayNamePrefix Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name prefix (such as Miss, Mr., Mrs.) for the messaging user.

Associated properties: | PR_DISPLAY_NAME_PREFIX, PR_DISPLAY_NAME_PREFIX_A, PR_DISPLAY_NAME_PREFIX_W
Identifier: | 0x3A45
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a messaging user. The content is defined by the messaging user and the messaging user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayTo Canonical Property

 Copy code hover
[image]

PidTagDisplayTo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of the display names of the primary (To) message recipients, separated by semicolons (;).

Associated properties: | PR_DISPLAY_TO, PR_DISPLAY_TO_A, PR_DISPLAY_TO_W
Identifier: | 0x0E04
Data type: | PT_STRING8, PT_UNICODE
Area: | Message

Remarks

The message store computes these properties on message objects by using the IMessage::ModifyRecipients method. The message store also maintains these properties so that it always reflects the last saved state of a message. The value is synchronized at the time of every call to the IMAPIProp::SaveChanges method.

If a message has no primary recipients, the message store should respond to an IMAPIProp::GetProps call with a return value of S_OK and an empty string for PR_DISPLAY_TO.

Because of the possible need for localization, MAPI provides these guidelines for all recipient names:

  • All names should be able to be localized.

  • The semicolon should be the character that is used to separate names in the PR_DISPLAY_BCC (PidTagDisplayBcc), PR_DISPLAY_CC (PidTagDisplayCc), and PR_DISPLAY_TO properties. Semicolons are not permitted within recipient names in MAPI.

  • Clients should translate each semicolon encountered in the PR_DISPLAY_TO and related properties to a localized separator character before making the information visible in the user interface.

  • When forwarding messages, clients do not need to translate the separator characters on the primary recipient line.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayType Canonical Property

 Copy code hover
[image]

PidTagDisplayType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value used to associate an icon with a particular row of a table.

Associated properties: | PR_DISPLAY_TYPE
Identifier: | 0x3900
Data type: | PT_LONG
Area: | MAPI address book

Remarks

This property contains a long integer that facilitates special treatment of the table entry based on its type. This special treatment typically consists of displaying an icon, or other display element, associated with the display type.

This property is not used in folder contents tables. Client applications should use a message's PR_MESSAGE_CLASS (PidTagMessageClass) property and appropriate IMAPIFormInfo interface to get the PR_ICON (PidTagIcon) and PR_MINI_ICON (PidTagMiniIcon) properties for that message.

This property can have exactly one of the following values:

DT_AGENT

An automated agent, such as Quote-Of-The-Day or a weather chart display.

DT_DISTLIST

A distribution list.

DT_FOLDER

Display default folder icon adjacent to folder.

DT_FOLDER_LINK

Display default folder link icon adjacent to folder rather than the default folder icon.

DT_FOLDER_SPECIAL

Display icon for a folder with an application-specific distinction, such as a special type of public folder.

DT_FORUM

A forum, such as a bulletin board service or a public or shared folder.

DT_GLOBAL

A global address book.

DT_LOCAL

A local address book that you share with a small workgroup.

DT_MAILUSER

A typical messaging user.

DT_MODIFIABLE

Modifiable; the container should be denoted as modifiable in the user interface.

DT_NOT_SPECIFIC

Does not match any of the other settings.

DT_ORGANIZATION

A special alias defined for a large group, such as helpdesk, accounting, or blood-drive coordinator.

DT_PRIVATE_DISTLIST

A private, personally administered distribution list.

DT_REMOTE_MAILUSER

A recipient known to be from a foreign or remote messaging system.

DT_WAN

A wide area network address book.

Address book contents tables use the DT_AGENT, DT_DISTLIST, DT_FORUM, DT_MAILUSER, DT_ORGANIZATION, DT_PRIVATE_DISTLIST, and DT_REMOTE_MAILUSER values. Address book hierarchy tables and one-off tables use the DT_GLOBAL, DT_LOCAL, DT_MODIFIABLE, DT_NOT_SPECIFIC, and DT_WAN values. Folder hierarchy tables use the DT_FOLDER, DT_FOLDER_LINK, and DT_FOLDER_SPECIAL values.

If this property is not set, the client should assume the default type appropriate for the table, typically DT_FOLDER, DT_LOCAL, or DT_MAILUSER.

Note All values not documented are reserved for MAPI. Client applications must not define any new values and must be prepared to deal with an undocumented value.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOABK]

Specifies the properties and operations that are permissible for address book templates.

[MS-OXLDAP]

Enables directory access.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDisplayTypeEx Canonical Property

 Copy code hover
[image]

PidTagDisplayTypeEx Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the type of an entry, with respect to how the entry should be displayed in a row in a table for the Global Address List.

Associated properties: | PR_DISPLAY_TYPE_EX
Identifier: | 0x3905
Data type: | PT_LONG
Area: | MAPI address book

Remarks

This property specifies the type of an entry, with respect to how it should be displayed in the Global Address List. It provides additional information that cannot be represented in PR_DISPLAY_TYPE (PidTagDisplayType).

Note Note

The values of both PR_DISPLAY_TYPE and this property begin with "DT_" and are defined in Mapitags.h. All values not documented are reserved for MAPI. Client applications must not define any new values and must be prepared to deal with an undocumented value.

There are some macros that can help determine attributes of an object such as whether it is local, remote, or security-controlled. These macros include:

Macro | Value
DTE_FLAG_REMOTE_VALID | 0x80000000)
DTE_FLAG_ACL_CAPABLE | 0x40000000
DTE_MASK_REMOTE | 0x0000ff00
DTE_MASK_LOCAL | 0x000000ff
DTE_IS_REMOTE_VALID(v) | (!!((v) & DTE_FLAG_REMOTE_VALID)
DTE_IS_ACL_CAPABLE(v) | (!!((v) & DTE_FLAG_ACL_CAPABLE))
DTE_REMOTE(v) | (((v) & DTE_MASK_REMOTE) >> 8)
DTE_LOCAL(v) | ((v) & DTE_MASK_LOCAL)
DT_ROOM | ((ULONG) 0x00000007)
DT_EQUIPMENT | ((ULONG) 0x00000008)
DT_SEC_DISTLIST | ((ULONG) 0x00000009)

The following are a few notes about how to use these macros.

  • To check whether an entry is a remote entry in another forest, apply the DTE_IS_REMOTE_VALID macro to the value of this property to check whether the DTE_FLAG_REMOTE_VALID flag is set in the entry. If it is a remote entry, you can then find out the type of the remote entry by using the DTE_REMOTE macro.

  • In both single-forest and cross-forest configurations, when PR_DISPLAY_TYPE has the value of DT_DISTLIST, and DTE_IS_REMOTE_VALID is false, applying the macro DTE_LOCAL to the value of this property can let you further identify the type of the object as either DT_DISTLIST (a distribution list) or DT_SEC_DISTLIST (a security distribution list).

  • If you apply the macro DTE_LOCAL to the value of PR_DISPLAY_TYPE_EX and it returns the type DT_REMOTE_MAILUSER, then the entry is a remote entry.

  • In a single forest or in a cross-forest configuration where replication is controlled by an Access Control List (ACL), you can use the DTE_IS_ACL_CAPABLE macro to determine whether an entry is a security principal.

In a cross-forest configuration, PR_DISPLAY_TYPE has the value of DT_REMOTE_MAILUSER. Applying the macro DTE_REMOTE to the value of this property can let you obtain the type of the remote entry. The possible types of remote entry are the following:

Type of Remote Entry | Value | Description
DT_AGENT | ((ULONG) 0x00000003) | Dynamic distribution list.
DT_DISTLIST | ((ULONG) 0x00000001) | Distribution list.
DT_EQUIPMENT | ((ULONG) 0x00000008) | Equipment, for example, a printer or a projector.
DT_MAILUSER | ((ULONG) 0x00000000) | User with a mailbox.
DT_REMOTE_MAILUSER | ((ULONG) 0x00000000) | An address list entry in the Global Address List.
DT_ROOM | ((ULONG) 0x00000007) | Conference room.
DT_SEC_DISTLIST | ((ULONG) 0x00000009) | Security distribution list.

In both a single forest and in a cross-forest configuration, when PR_DISPLAY_TYPE has the value of DT_DISTLIST and DTE_IS_REMOTE_VALID is false, applying the DTE_LOCAL macro to the value of this property can let you obtain the type of the distribution list. The possible types of distribution list are the following:

Type of Distribution List | Value | Description
DT_DISTLIST | ((ULONG) 0x00000001) | Distribution list.
DT_SEC_DISTLIST | ((ULONG) 0x00000009) | Security distribution list.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDistributionListExpansionHistory Canonical Property

 Copy code hover
[image]

PidTagDistributionListExpansionHistory Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a history showing how a distribution list has been expanded during message transmission.

Associated properties: | PR_DL_EXPANSION_HISTORY
Identifier: | 0x0013
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is available to receiving client applications if the transport provider has set it. It is also available to the sending client if the message content is returned with a report.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagDistributionListExpansionProhibited Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagDistributionListExpansionProhibited Canonical Property

 Copy code hover
[image]

PidTagDistributionListExpansionProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message transfer agent (MTA) is prohibited from expanding distribution lists.

Associated properties: | PR_DL_EXPANSION_PROHIBITED
Identifier: | 0x0014
Data type: | PT_BOOLEAN
Area: | MAPI envelope

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagEmailAddress Canonical Property

 Copy code hover
[image]

PidTagEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the messaging user's e-mail address.

Associated properties: | PR_EMAIL_ADDRESS, PR_EMAIL_ADDRESS_A, PR_EMAIL_ADDRESS_W
Identifier: | 0x3003
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

These properties are examples of the base address properties for all messaging users. It is a null-terminated string whose format has meaning only for the underlying messaging system.

These properties are used in conjunction with the PR_ADDRTYPE (PidTagAddressType) and PR_MESSAGE_CLASS (PidTagMessageClass) properties in addressing messages. The string format is qualified by PR_ADDRTYPE.

Valid values for this property include:

Copy code Copy code
network/postoffice/user
Bruce@XYZZY.COM
/c=US/a=att/p=Microsoft/o=Finance/ou=Purchasing/s=Furthur/g=Joe

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagEmsAbServer Canonical Property

 Copy code hover
[image]

PidTagEmsAbServer Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies either the path of an address book container in an offline scenario or the fully qualified domain name of the global catalog server where the address book container resides in an online scenario.

Associated properties: | PR_EMS_AB_SERVER, PR_EMS_AB_SERVER_A, PR_EMS_AB_SERVER_W
Identifier: | 0xFFFE
Data type: | PT_TSTRING
Area: | Address Book

Remarks

This property has the property type reset to PT_UNICODE when it is compiled with the UNICODE symbol on a Unicode platform, and to PT_STRING8 when it is not compiled with the UNICODE symbol.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagEndDate Canonical Property

 Copy code hover
[image]

PidTagEndDate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the ending date and time of an appointment as managed by a scheduling application.

Associated properties: | PR_END_DATE
Identifier: | 0x0061
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

Scheduling applications should set both the PR_START_DATE (PidTagStartDate) and this property when sending meeting requests.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagEntryId Canonical Property

 Copy code hover
[image]

PidTagEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a MAPI entry identifier used to open and edit properties of a particular MAPI object.

Associated properties: | PR_ENTRYID
Identifier: | 0x0FFF
Data type: | PT_BINARY
Area: | ID properties

Remarks

This property identifies an object for OpenEntry to instantiate and provides access to all of its properties through the appropriate derived interface of IMAPIProp.

This property is one of the base address properties for all messaging users.

This property can contain either a long-term or a short-term identifier. Short-term identifiers are easier and faster to construct, but are limited in their scope and duration, typically to the current session and workstation. They are commonly used for objects of a temporary nature, such as table rows or dialog box entries, and then abandoned. Long-term identifiers are used for objects of a more wide-ranging and long-lasting nature.

This property is always available through the IMAPIProp::GetProps method following the first call to the IMAPIProp::SaveChanges method. Some service providers can make it available immediately after instantiation. The provider must always return a long-term entry identifier from GetProps. Therefore, to convert a short-term identifier to long-term, simply open the object and get its this property through GetProps.

The following table summarizes important differences among this property, PR_RECORD_KEY (PidTagRecordKey), and PR_SEARCH_KEY (PidTagSearchKey).

Characteristic | PR_ENTRYID | PR_RECORD_KEY | PR_SEARCH_KEY
Required on attachment objects | No | Yes | No
Required on folder objects | Yes | Yes | No
Required on message store objects | Yes | Yes | No
Required on status objects | Yes | No | No
Created by client | No | No | Yes
Available before call to SaveChanges | Depends on provider implementation | Depends on provider implementation | For messages, Yes. For others, depends on provider implementation.
Changed in a copy operation | Yes | Yes | No
Changeable by client after a copy | No | No | Yes
Unique within | Entire world | Provider instance | Entire world
Binary comparable (as with memcmp) | No use IMAPISupport:: CompareEntryIDs | Yes | Yes

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCPERM]

Handles the retrieval of folder permission lists that are stored on the server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXWAVLS]

Specifies the schema and methods that are used to request availability information for users and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagStoreEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExceptionEndTime Canonical Property

 Copy code hover
[image]

PidTagExceptionEndTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the end date and time of the exception in the local time zone of the machine when the exception is created.

Associated properties: | PR_EXCEPTION_ENDTIME
Identifier: | 0x7FFC
Data type: | PT_SYSTIME
Area: | Message class-defined non-transmittable

Remarks

Note Note

This property is informational and must not be relied on for critical information.

Related Resources

Protocol Specifications

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExceptionReplaceTime Canonical Property

 Copy code hover
[image]

PidTagExceptionReplaceTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the original date and time when the instance in the recurrence pattern would have occurred if it were not an exception.

Associated properties: | PR_EXCEPTION_REPLACETIME
Identifier: | 0x7FF9
Data type: | PT_SYSTIME
Area: | Message class-defined non-transmittable

Remarks

This value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExceptionStartTime Canonical Property

 Copy code hover
[image]

PidTagExceptionStartTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the start date and time of the exception in the local time zone of the machine when the exception is created.

Associated properties: | PR_EXCEPTION_STARTTIME
Identifier: | 0x7FFB
Data type: | PT_SYSTIME
Area: | Message class-defined non-transmittable

Remarks

Note Note

This property is informational and must not be relied on for critical information.

Related Resources

Protocol Specifications

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExchangeProfileSectionId Canonical Property

 Copy code hover
[image]

PidTagExchangeProfileSectionId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a dynamically generated GUID used to determine an account when you are using multiple Exchange Server accounts.

Associated properties: | PR_EMSMDB_SECTION_UID
Identifier: | 0x3d150102
Data type: | PT_BINARY
Area: | Multiple Exchange Accounts

Remarks

Microsoft Outlook 2010 and Microsoft Outlook 2013 support multiple Exchange accounts instead of one single Exchange account. To accommodate multiple Exchange accounts, the MAPI profile layout was changed. In Microsoft Office Outlook 2007 and earlier, profiles contained a fixed profile section dedicated to Exchange settings such as server name, user name, and Offline Folder file (.ost). location. These settings were identified by using a unique identifier, the pbGlobalProfileSectionGuid property. The section used for Exchange settings is called the Exchange Global Profile Section. For more information about the Exchange Global Profile in Outlook 2007, see How To Open the Global Profile Section.

A fixed profile section location is no longer sufficient to accommodate multiple Exchange accounts. Instead, for each Exchange account in your profile, a section exists that is dedicated to settings for that account. The new section used for Exchange settings is identified by the unique identifier emsmdbUID.

In the message service profile section for the Exchange account, you can find a property that contains a GUID that is dynamically generated at the time that the account is created. This GUID is stored in the PidTagExchangeProfileSectionId property. Message stores and address book containers expose a property to determine which Exchange account they belong to. Accessible in the message services table, each Exchange service exposes this property.

You can retrieve this property through a call to IMAPIProp::GetProps on PidTagExchangeProfileSectionId after querying for any of the following interfaces:

  • IMsgStore : IMAPIProp

  • IMAPIFolder : IMAPIContainer

  • IABContainer : IMAPIContainer

If the object is not affiliated with Exchange, the call returns MAPI_E_NOT_FOUND.

You can restrict containers on a PidTagExchangeProfileSectionId when displaying the address book. Once you have an opened container, you can query the emsmdbUID from it. It is also worth noting that if a recipient was selected from an Exchange address book, the recipient also has the PidTagExchangeProfileSectionId in its list of properties.

Note Note

Throughout the code samples and function headers, this GUID is known as emsmdbUID.

One of the Exchange accounts is marked as the legacy Exchange account. Usually, it is the first account added to the profile. Every call to open pbGlobalProfileSectionGuid is redirected to the Exchange global section of the legacy account. The object model calls that interact with the non-legacy Exchange account also interact with the legacy Exchange account.

The legacy Exchange service has the property PR_EMSMDB_LEGACY (0x3D18000B), which is set to true in the message services table.

The legacy emsmdbUID is also stamped in the Outlook Global Profile Section of the profile as PidTagExchangeProfileSectionId. Code written to support multiple Exchange accounts should not have to retrieve the legacy emsmdbUID because it should get the correct emsmdbUID, depending on the account your code is interacting with.

See also

Concepts

Using Multiple Exchange Accounts

Other resources

How To Open the Global Profile Section


PidTagExpiryNumber Canonical Property

 Copy code hover
[image]

PidTagExpiryNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Defines the expiry send time in conjunction with the PR_EXPIRY_UNITS (PidTagExpiryUnits) property.

Associated properties: | PR_EXPIRY_NUMBER
Identifier: | 0x3FED
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property's value must be set between 0 and 999 inclusive, if it is present.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExpiryTime Canonical Property

 Copy code hover
[image]

PidTagExpiryTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when the messaging system can invalidate the content of a message.

Associated properties: | PR_EXPIRY_TIME
Identifier: | 0x0015
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

This property is used to direct the messaging system in handling delivered interpersonal messages.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExpiryUnits Canonical Property

 Copy code hover
[image]

PidTagExpiryUnits Canonical Property
See also Send feedback

Published: July 16, 2012

Describes the unit of time when the PR_EXPIRY_NUMBER (PidTagExpiryNumber) property multiplies.

Associated properties: | PR_EXPIRY_UNITS
Identifier: | 0x3FEE
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property, if set, must be one of the following values:

PidTagExpiryUnits | Description (TimeOf)
0x00000000 | Minutes, for example 60 seconds
0x00000001 | Hours, for example 60x60 seconds
0x00000002 | Day, for example 24x60x60 seconds
0x00000003 | Week, for example 7x24x60x60 seconds

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExplicitConversion Canonical Property

 Copy code hover
[image]

PidTagExplicitConversion Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates that a message sender has requested a message content conversion for a particular recipient.

Associated properties: | PR_EXPLICIT_CONVERSION
Identifier: | 0x0C01
Data type: | PT_LONG
Area: | MAPI recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExtendedFolderFlags Canonical Property

 Copy code hover
[image]

PidTagExtendedFolderFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains extended flags about a folder

Associated properties: | PR_EXTENDED_FOLDER_FLAGS
Identifier: | 0x36DA
Data type: | PT_BINARY
Area: | MAPI container

Remarks

This property is a binary stream that contains encoded sub-properties for the folder. It is formatted as a series of variable length sub items. The first 8 bits of the sub item is an ID field, which indicates what kind of flag the sub item represents. The second 8 bits is the number of bytes of data that follow.

Possible ID values include:

  • Invalid

    Do not use this value

  • ExtendedFlags

    The data is a four byte value formatted as:

    Bits

    Description

    0-1

    Reserved.

    2

    Set to 0 if the application should show a policy description.

    3-5

    Reserved.

    6-7

    Controls the display of the number of messages in the folder.

    0 - Use the default setting

    1 - Use the number of unread messages

    3 - Use the total number of messages

    8-31

    Reserved.

    Reserved items can be ignored, but existing values must be preserved.

  • SearchFolderID

    The data field is a 16-byte field. When the application creates a persistent search folder, it must set this field on the folder to the same value as the PR_WB_SF_TAG (PidTagSearchFolderId)) binary property on the Search Folder Message.

  • ToDoFolderVersion

    The data field is a 4-byte field. When the application creates the to-do search folder, it must set the value of this field on the folder to the little-endian integer value of" 0x000c0000":

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExtendedRuleMessageActions Canonical Property

 Copy code hover
[image]

PidTagExtendedRuleMessageActions Canonical Property
See also Send feedback

Published: July 16, 2012

Contains additional information about the named properties used in a Folder Associated Information (FAI) message.

Associated properties: | PR_EXTENDED_RULE_MSG_ACTIONS
Identifier: | 0x0E99
Data type: | PT_BINARY
Area: | Rules

Remarks

This property must be set on an FAI message. This property serves the same purpose as PR_RULE_ACTIONS (PidTagRuleActions), but contains additional information about the version of the rule and the named properties stored in the rule action, as well as information about the actions to be performed by this rule. All string values contained in any part of the action buffer used to contain actions must be in Unicode format.

For information about the format of this binary property, see [MS-OXORULE].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications..

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExtendedRuleMessageCondition Canonical Property

 Copy code hover
[image]

PidTagExtendedRuleMessageCondition Canonical Property
See also Send feedback

Published: July 16, 2012

Contains information about any named properties that are contained inside of extended rule conditions.

Associated properties: | PR_EXTENDED_RULE_MSG_CONDITION
Identifier: | 0x0E9A
Data type: | PT_BINARY
Area: | Rules

Remarks

This property must be set on an FAI message. It serves the same purpose as PR_RULE_CONDITION (PidTagRuleCondition), but contains additional information about the named properties used. All string values contained in any part of this condition property value must be in Unicode format.

For information about the format of this binary property, see [MS-OXORULE].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagExtendedRuleSizeLimit Canonical Property

 Copy code hover
[image]

PidTagExtendedRuleSizeLimit Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the maximum size, in bytes, the user is allowed to accumulate for a single "extended" rule.

Associated properties: | PR_EXTENDED_RULE_SIZE_LIMIT
Identifier: | 0x0E9B
Data type: | PT_LONG
Area: | Rules

Remarks

If this property is set on the logon object, the client should keep the size of the PR_EXTENDED_RULE_MSG_CONDITION (PidTagExtendedRuleMessageCondition) property under the value specified by this property. Conversely, the server should return an error if the client does attempt to set a binary property that is too large.

For information about extended rules, see [MS-OXORULE].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFinderEntryId Canonical Property

 Copy code hover
[image]

PidTagFinderEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier for the folder where search results are typically created.

Associated properties: | PR_FINDER_ENTRYID
Identifier: | 0x35E7
Data type: | PT_BINARY
Area: | MAPI message store

Remarks

The entry identifier contained in this property has the same format as the ENTRYID structure.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFlagCompleteTime Canonical Property

 Copy code hover
[image]

PidTagFlagCompleteTime Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the date and time in Coordinated Universal Time (UTC) that the message object was flagged as completed.

Associated properties: | PR_FLAG_COMPLETE_TIME
Identifier: | 0x1091
Data type: | PT_SYSTIME
Area: | Miscellaneous

Remarks

This property is deleted if the message object is not flagged complete. The time's smallest resolution must be minutes (the value must be a multiple of 600,000,000). This property must not exist if the object is a meeting-related object, and it should not exist on a task object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFlagStatus Canonical Property

 Copy code hover
[image]

PidTagFlagStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the flag state of the message object.

Associated properties: | PR_FLAG_STATUS
Identifier: | 0x1090
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

This property must not exist on a meeting-related object, and it should not exist on a task object. When set on other message objects, this property must be set to one of the following values:

Numeric value | Name | Description
Not present | N/A | Unflagged
0x00000001 | followupComplete | Flagged complete
0x00000002 | followupFlagged | Flagged

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFolderAssociatedContents Canonical Property

 Copy code hover
[image]

PidTagFolderAssociatedContents Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an embedded contents table object that provides information about the associated contents table.

Associated properties: | PR_FOLDER_ASSOCIATED_CONTENTS
Identifier: | 0x3610
Data type: | PT_OBJECT
Area: | MAPI container

Remarks

The associated contents table represents a subfolder that does not appear in the standard contents table. It contains the folder's associated, or hidden, messages.

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, client applications should call the IMAPIContainer::GetContentsTable method. For more information on folder contents tables, see Contents Tables and Displaying a Folder Contents Table.

The PR_CONTAINER_CONTENTS (PidTagContainerContents), PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy), and this property are similar in usage. Several MAPI properties provide access to tables:

Property | Table
PR_CONTAINER_CONTENTS (PidTagContainerContents) | Contents table
PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) | Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS | Associated contents table
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Attachment table
PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) | Recipient table

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting items.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagAssociatedContentCount Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFolderType Canonical Property

 Copy code hover
[image]

PidTagFolderType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a constant that indicates the folder type.

Associated properties: | PR_FOLDER_TYPE
Identifier: | 0x3601
Data type: | PT_LONG
Area: | MAPI container

Remarks

This property can have exactly one of the following values:

FOLDER_GENERIC

A generic folder that contains messages and other folders.

FOLDER_ROOT

The root folder of the folder hierarchy table, that is, a folder that has no parent folder.

FOLDER_SEARCH

A folder that contains the results of a search, in the form of links to messages that meet search criteria.

The root of a message store should not be confused with the root of the interpersonal message (IPM) subtree in that store. The store's root folder, which has no parent, is obtained by calling the IMsgStore::OpenEntry method with a null entry identifier. The IPM subtree's root folder, which does have a parent, is obtained by using the value of the PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId) property for the OpenEntry call.

MAPI allows only one root folder per message store. This folder contains messages and other folders. The root folder's PR_PARENT_ENTRYID (PidTagParentEntryId) property contains the folder's own entry identifier.

The information in a search-results folder is mainly stored in its contents table, which contains the same columns as a typical contents table, as well as two extra columns identifying the folder in which each message was found: PR_PARENT_DISPLAY (PidTagParentDisplay) (display name, required) and this property (entry identifier, optional).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFolderWebViewInfo Cannonical Property

 Copy code hover
[image]

PidTagFolderWebViewInfo Cannonical Property
Send feedback

Published: July 16, 2012

Contains the URL for the home page of a folder in Microsoft Outlook. This property contains a binary stream called WebViewPersistenceObject.

Associated properties: | PR_FOLDER_WEBVIEWINFO
Identifier: | 0x36DF
Data type: | PT_BINARY
Area: | MAPI folder

Remarks

A home page URL can be specified for any Outlook folder. This information can be accessed in Outlook from the Home Page tab of the Properties dialog box for a folder.

Depending on certain policy settings, the home page might be ignored by Outlook if the MAPI store that contains this folder does not report MSCAP_SECURE_FOLDER_HOMEPAGES in its IMSCapabilities::GetCapabilities implementation.

Both the Outlook Today folder and a public folder can have home page URLs. However the Outlook Today folder uses a different mechanism to manage its home page URL; that mechanism is not covered in this topic. A public folder might also have a home page URL defined in it that is specific to a user. However, that capability is not described in this topic.

The value of this property is a binary stream called WebViewPersistenceObject.

WebViewPersistenceObject Stream Structure

The WebViewPersistenceObject stream structure contains information about a home page URL for a folder.

Data elements in this structure are stored in little-endian byte order, immediately following one another in the following specified order.

Note Note

The following description may not list all of the field values supported by Outlook; therefore, when your code reads an existing stream, some flags that are not listed here might also be found. However, you can use this description to programmatically create values for the PidTagFolderWebViewInfo property that Outlook will understand.

dwVersion

DWORD (4 bytes). The version of the structure's format. As of Microsoft Office Outlook 2007, the only supported value for this field is as follows.

Value name | Value
WEBVIEW_PERSISTENCE_VERSION | 0x00000002
dwType

DWORD (4 bytes). The type of the home page information. As of Microsoft Office Outlook 2007, the only supported value for this field is as follows.

Value name | Value
WEBVIEWURL | 0x00000001
dwFlags

DWORD (4 bytes). A combination of zero or more flags whose values and meanings are listed in the following table.

Flag name | Value | Description
WEBVIEW_FLAGS_SHOWBYDEFAULT | 0x00000001 | The Show home page by default for this folder check box was checked in the Home Page tab of the Properties dialog box for a folder.
dwUnused[7]

An array of 7 DWORD elements (28 bytes total). Unused.

cbData

A ULONG (4 bytes). The size, in bytes, of the wzURL data element.

wzURL

An array of WCHAR elements. The UTF-16 representation of the zero-terminated home page URL string.

WebViewPersistenceObject Stream Sample

This section describes an example of a WebViewPersistenceObject stream. The stream specifies the home page URL "http://www.microsoft.com".

Data dump

The following is a data dump of the stream as it would be displayed in a binary editor.

Stream offset | Data bytes | ASCII data
0000000000 | 02 00 00 00 01 00 00 00 01 00 00 00 00 00 00 00 | ?...?...?.......
0000000010 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................
0000000020 | 00 00 00 00 00 00 00 00 32 00 00 00 68 00 74 00 | ........2...h.t.
0000000030 | 74 00 70 00 3A 00 2F 00 2F 00 77 00 77 00 77 00 | t.p.:././.w.w.w.
0000000040 | 2E 00 6D 00 69 00 63 00 72 00 6F 00 73 00 6F 00 | ..m.i.c.r.o.s.o.
0000000050 | 66 00 74 00 2E 00 63 00 6F 00 6D 00 00 00 | f.t...c.o.m...

The following is a parse of the sample data for the WebViewPersistenceObject stream.

dwVersion

Offset 0x0, 4 bytes: 0x00000002 (WEBVIEW_PERSISTENCE_VERSION).

dwType

Offset 0x4, 4 bytes: 0x00000001 (WEBVIEWURL).

dwFlags

Offset 0x8, 4 bytes: 0x00000001 (WEBVIEW_FLAGS_SHOWBYDEFAULT).

dwUnused[7]

Offset 0xC, 28 bytes: all zeros.

cbData

Offset 0x28, 4 bytes: 0x00000032.

wzURL

Offset 0x2C, 0x32 bytes: array of 25 WCHARs. A Unicode zero-terminated string value: "http://www.microsoft.com".


PidTagFollowupIcon Canonical Property

 Copy code hover
[image]

PidTagFollowupIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the flag color of the message object.

Associated properties: | PR_FOLLOWUP_ICON
Identifier: | 0x1095
Data type: | PT_LONG
Area: | Rename message folder

Remarks

This property must not exist unless the value of the PR_FLAG_STATUS (PidTagFlagStatus) property is set to "followupFlagged", or the message object is a meeting-related object. This property should not exist on a task object. When set on other message objects, this property must be set to one of the following values.

Numeric value | Name | Description
Not present | N/A | No color
1 | followupIcon1 | Purple flag
2 | followupIcon2 | Orange flag
3 | followupIcon3 | Green flag
4 | followupIcon4 | Yellow flag
5 | followupIcon5 | Blue flag
6 | followupIcon6 | Red flag

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormCategory Canonical Property

 Copy code hover
[image]

PidTagFormCategory Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the category of a form.

Associated properties: | PR_FORM_CATEGORY, PR_FORM_CATEGORY_A, PR_FORM_CATEGORY_W
Identifier: | 0x3304
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

The category name is defined by a client application in a way that is appropriate to the application.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormCategorySub Canonical Property

 Copy code hover
[image]

PidTagFormCategorySub Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the subcategory of a form, as defined by a client application.

Associated properties: | PR_FORM_CATEGORY_SUB, PR_FORM_CATEGORY_SUB_A, PR_FORM_CATEGORY_SUB_W
Identifier: | 0x3305
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

These properties are subordinate to the main form category that is provided in the PR_FORM_CATEGORY (PidTagFormCategory) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormClassId Canonical Property

 Copy code hover
[image]

PidTagFormClassId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the 128-bit Object Linking and Embedding (OLE) globally unique identifier (GUID) of a form.

Associated properties: | PR_FORM_CLSID
Identifier: | 0x3302
Data type: | PT_CLSID
Area: | MAPI common

Remarks

The MAPIUID structure contains the definition of the unique identifier.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormContactName Canonical Property

 Copy code hover
[image]

PidTagFormContactName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of a contact for information about a form.

Associated properties: | PR_FORM_CONTACT_NAME, PR_FORM_CONTACT_NAME_A, PR_FORM_CONTACT_NAME_W
Identifier: | 0x3303
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

The contact typically contains the name of a person or an alias that is responsible for maintaining the form.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormDesignerGuid Canonical Property

 Copy code hover
[image]

PidTagFormDesignerGuid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the unique identifier for the object that is used to design a form.

Associated properties: | PR_FORM_DESIGNER_GUID
Identifier: | 0x3309
Data type: | PT_GUID
Area: | MAPI common

Remarks

This property usually contains the globally unique identifier (GUID) of the design program that is used to create the form. This property can be empty.

The MAPIUID structure contains the definition of the unique identifier.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormDesignerName Canonical Property

 Copy code hover
[image]

PidTagFormDesignerName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for the object that is used to design the form.

Associated properties: | PR_FORM_DESIGNER_NAME, PR_FORM_DESIGNER_NAME_A, PR_FORM_DESIGNER_NAME_W
Identifier: | 0x3308
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

These properties contain the unique identifier for the form designer object.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormHidden Canonical Property

 Copy code hover
[image]

PidTagFormHidden Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a form is to be suppressed from display by compose menus and dialog boxes.

Associated properties: | PR_FORM_HIDDEN
Identifier: | 0x3307
Data type: | PT_BOOLEAN
Area: | MAPI common

Remarks

Form-related properties are read-only.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormHostMap Canonical Property

 Copy code hover
[image]

PidTagFormHostMap Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a host map of available forms.

Associated properties: | PR_FORM_HOST_MAP
Identifier: | 0x3306
Data type: | PT_MV_LONG
Area: | MAPI common

Remarks

A client application should update this property, along with the PR_DISPLAY_NAME (PidTagDisplayName) property, when changing the underlying structure in the IMAPIFormProp interface.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormMessageBehavior Canonical Property

 Copy code hover
[image]

PidTagFormMessageBehavior Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message should be composed in the current folder.

Associated properties: | PR_FORM_MESSAGE_BEHAVIOR
Identifier: | 0x330A
Data type: | PT_LONG
Area: | MAPI common

Remarks

A value of FALSE indicates that the message should be composed as any other interpersonal message, that is, in the Outbox folder.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFormVersion Canonical Property

 Copy code hover
[image]

PidTagFormVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the version of a form.

Associated properties: | PR_FORM_VERSION, PR_FORM_VERSION_A, PR_FORM_VERSION_W
Identifier: | 0x3301
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

These properties indicate what design version is currently in effect for the form. The version is defined and maintained by the form's designer and is not necessarily related to any MAPI component version.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFreeBusyCountMonths Canonical Property

 Copy code hover
[image]

PidTagFreeBusyCountMonths Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value for calculating the start and end dates of the range of free/busy data to be published to public folders.

Associated properties: | PR_FREEBUSY_COUNT_MONTHS
Identifier: | 0x6869
Data type: | PT_LONG
Area: | Message class-defined transmittable

Remarks

This property's value must be greater than or equal to 0 and less than or equal to 36. This is not a required property.

Related Resources

Protocol Specifications

[MS-OXOPFFB]

Publishes the availability of a user or resource.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFreeBusyEntryIds Canonical Property

 Copy code hover
[image]

PidTagFreeBusyEntryIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryIDs for the delegate information message, the free/busy message of the logged in user, and the folder whose PR_DISPLAY_NAME (PidTagDisplayName) is equal to "FreeBusy Data."

Associated properties: | PR_FREEBUSY_ENTRYIDS
Identifier: | 0x36E4
Data type: | PT_MV_BINARY
Area: | MAPI container

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar items when they act on behalf of another user.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFreeBusyPublishEnd Canonical Property

 Copy code hover
[image]

PidTagFreeBusyPublishEnd Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the end time of the publishing range.

Associated properties: | PR_FREEBUSY_PUBLISH_END
Identifier: | 0x6848
Data type: | PT_LONG
Area: | Free/Busy

Remarks

The value for this property is computed by adding the value of PR_FREEBUSY_COUNT_MONTHS (PidTagFreeBusyCountMonths) to the start date of the publishing range. This value is expressed as the number of minutes since midnight, January 1, 1601 in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFreeBusyPublishStart Canonical Property

 Copy code hover
[image]

PidTagFreeBusyPublishStart Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the start time of the publishing range.

Associated properties: | PR_FREEBUSY_PUBLISH_START
Identifier: | 0x6847
Data type: | PT_LONG
Area: | Free/Busy

Remarks

The value for this property is the number of minutes since midnight, January 1, 1601 in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFreeBusyRangeTimestamp Canonical Property

 Copy code hover
[image]

PidTagFreeBusyRangeTimestamp Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the time when the data was published.

Associated properties: | PR_FREEBUSY_RANGE_TIMESTAMP
Identifier: | 0x6868
Data type: | PT_SYSTIME
Area: | Free/Busy

Remarks

This property is the number of minutes since midnight, January 1, 1601 in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagFtpSite Canonical Property

 Copy code hover
[image]

PidTagFtpSite Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the contact's File Transfer Protocol (FTP) URL. FTP is a protocol that is used to transfer data, as specified in [RFC959].

Associated properties: | PR_FTP_SITE, PR_FTP_SITE_A, PR_FTP_SITE_W
Identifier: | 0x3A4C
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagGender Canonical Property

 Copy code hover
[image]

PidTagGender Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the gender of the messaging user.

Associated properties: | PR_GENDER
Identifier: | 0x3A4D
Data type: | PT_I2
Area: | MAPI mail user

Remarks

This property provides identification and access information about a messaging user and the content is. The content is defined by the messaging user and the messaging user's organization.

The possible values for this property are defined in the gender enumeration. They are listed as follows:

Gender enumeration | Value | Description
genderUnspecified | 0x0000 | The contact's gender is unspecified.
genderFemale | 0x0001 | The contact is female.
genderMale | 0x0002 | The contact is male.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagGeneration Canonical Property

 Copy code hover
[image]

PidTagGeneration Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a generational abbreviation that follows the full name of the recipient.

Associated properties: | PR_GENERATION, PR_GENERATION_A, PR_GENERATION_W
Identifier: | 0x3A05
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and their organization.

Common values include Jr., Sr., and III.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagGivenName Canonical Property

 Copy code hover
[image]

PidTagGivenName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the first or given name of the recipient.

Associated properties: | PR_GIVEN_NAME, PR_GIVEN_NAME_A, PR_GIVEN_NAME_W
Identifier: | 0x3A06
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagGovernmentIdNumber Canonical Property

 Copy code hover
[image]

PidTagGovernmentIdNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a government identifier for the recipient.

Associated properties: | PR_GOVERNMENT_ID_NUMBER, PR_GOVERNMENT_ID_NUMBER_A, PR_GOVERNMENT_ID_NUMBER_W
Identifier: | 0x3A07
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and the recipient's organization.

These properties are commonly set to a passport number, citizen number, or taxpayer number such as a Social Security number.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHasAttachments Canonical Property

 Copy code hover
[image]

PidTagHasAttachments Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message contains at least one attachment.

Associated properties: | PR_HASATTACH
Identifier: | 0x0E1B
Data type: | PT_BOOLEAN
Area: | Message attachment

Remarks

The message store copies this property from the MSGFLAG_HASATTACH flag of the PR_MESSAGE_FLAGS (PidTagMessageFlags) property. A client application can then use PR_HASATTACH to sort on message attachments in a message viewer.

The value this property is updated with the IMAPIProp::SaveChanges method.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHasDeferredActionMessages Canonical Property

 Copy code hover
[image]

PidTagHasDeferredActionMessages Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message has at least one deferred action rule.

Associated properties: | PR_HAS_DAMS
Identifier: | 0x3FEA
Data type: | PT_BOOLEAN
Area: | Rules

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHobbies Canonical Property

 Copy code hover
[image]

PidTagHobbies Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the names of the hobbies of the messaging user.

Associated properties: | PR_HOBBIES, PR_HOBBIES_A, PR_HOBBIES_W
Identifier: | 0x3A43
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a messaging user and the content is defined by the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHome2TelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagHome2TelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a secondary telephone number at the recipient's home.

Associated properties: | PR_HOME2_TELEPHONE_NUMBER, PR_HOME2_TELEPHONE_NUMBER_A, PR_HOME2_TELEPHONE_NUMBER_W
Identifier: | 0x3A2F
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHome2TelephoneNumbers Canonical Property

 Copy code hover
[image]

PidTagHome2TelephoneNumbers Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of secondary telephone numbers at the recipient's home.

Associated properties: | PR_HOME2_TELEPHONE_NUMBER_A_MV
Identifier: | 0x3A2F
Data type: | PT_MV_UNICODE8
Area: | MAPI mail user

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressCity Canonical Property

 Copy code hover
[image]

PidTagHomeAddressCity Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the city for the recipient's home address.

Associated properties: | PR_HOME_ADDRESS_CITY, PR_HOME_ADDRESS_CITY_A, PR_HOME_ADDRESS_CITY_W
Identifier: | 0x3A59
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressCountry Canonical Property

 Copy code hover
[image]

PidTagHomeAddressCountry Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the county in a contact's address.

Associated properties: | PR_HOME_ADDRESS_COUNTRY, PR_HOME_ADDRESS_COUNTRY_A, PR_HOME_ADDRESS_COUNTRY_W
Identifier: | 0x3A5A
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressPostalCode Canonical Property

 Copy code hover
[image]

PidTagHomeAddressPostalCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the postal code for the user's home address.

Associated properties: | PR_HOME_ADDRESS_POSTAL_CODE, PR_HOME_ADDRESS_POSTAL_CODE_A, PR_HOME_ADDRESS_POSTAL_CODE_W
Identifier: | 0x3A5B
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressPostOfficeBox Canonical Property

 Copy code hover
[image]

PidTagHomeAddressPostOfficeBox Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the post office box information for a user's address.

Associated properties: | PR_HOME_ADDRESS_POST_OFFICE_BOX, PR_HOME_ADDRESS_POST_OFFICE_BOX_A, PR_HOME_ADDRESS_POST_OFFICE_BOX_W
Identifier: | 0x3A5E
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressStateOrProvince Canonical Property

 Copy code hover
[image]

PidTagHomeAddressStateOrProvince Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the state or province portion of a user's address.

Associated properties: | PR_HOME_ADDRESS_STATE_OR_PROVINCE, PR_HOME_ADDRESS_STATE_OR_PROVINCE_A, PR_HOME_ADDRESS_STATE_OR_PROVINCE_W
Identifier: | 0x3A5C
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeAddressStreet Canonical Property

 Copy code hover
[image]

PidTagHomeAddressStreet Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the street portion of a user's address.

Associated properties: | PR_HOME_ADDRESS_STREET, PR_HOME_ADDRESS_STREET_A, PR_HOME_ADDRESS_STREET_W
Identifier: | 0x3A5D
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeFaxNumber Canonical Property

 Copy code hover
[image]

PidTagHomeFaxNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the telephone number of the recipient's home fax machine.

Associated properties: | PR_HOME_FAX_NUMBER, PR_HOME_FAX_NUMBER_A, PR_HOME_FAX_NUMBER_W
Identifier: | 0x3A25
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHomeTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagHomeTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the primary telephone number of the recipient's home.

Associated properties: | PR_HOME_TELEPHONE_NUMBER, PR_HOME_TELEPHONE_NUMBER_A, PR_HOME_TELEPHONE_NUMBER_W
Identifier: | 0x3A09
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagHtml Canonical Property

 Copy code hover
[image]

PidTagHtml Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message body text in HTML format.

Associated properties: | PR_HTML
Identifier: | 0x1013
Data type: | PT_BINARY
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Defines each property that is used in the objects that are described by MS-OXO-prefixed documents.

[MS-OXBBODY]

Defines properties related to the message body.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible on post objects.

[MS-OXORMMS]

Specifies the properties of rights-managed encoded messages.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIcon Canonical Property

 Copy code hover
[image]

PidTagIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmap of a full size icon for a form.

Associated properties: | PR_ICON
Identifier: | 0x0FFD
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

This property contains a 32 × 32 pixel image of an icon, the same as the contents of a .ICO file. This property is normally copied from the .ICO file specified in the LargeIcon line of the appropriate [Description] section of the form configuration file.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagMiniIcon Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIconIndex Canonical Property

 Copy code hover
[image]

PidTagIconIndex Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a number that indicates which icon to use when you display a group of e-mail objects.

Associated properties: | PR_ICON_INDEX
Identifier: | 0x1080
Data type: | PT_LONG
Area: | General messaging

Remarks

This property, if it exists, is a hint to the client. The client may ignore the value of this property.

Mail item state | Icon Index
New mail | 0xFFFFFFFF
Post | 0x00000001
Other | 0x00000003
Read mail | 0x00000100
Unread mail | 0x00000101
Submitted mail | 0x00000102
Unsent mail | 0x00000103
Receipt mail | 0x00000104
Replied mail | 0x00000105
Forwarded mail | 0x00000106
Remote mail | 0x00000107
Delivery mail | 0x00000108
Read mail | 0x00000109
Nondelivery mail | 0x0000010A
Nonread mail | 0x0000010B
Recall_S mail | 0x0000010C
Recall_F mail | 0x0000010D
Tracking mail | 0x0000010E
Out of office mail | 0x0000011B
Recall mail | 0x0000011C
Tracked mail | 0x00000130
Contact | 0x00000200
Distribution list | 0x00000202
Sticky note blue | 0x00000300
Sticky note green | 0x00000301
Sticky note pink | 0x00000302
Sticky note yellow | 0x00000303
Sticky note white | 0x00000304
Single instance appointment | 0x00000400
Recurring appointment | 0x00000401
Single instance meeting | 0x00000402
Recurring meeting | 0x00000403
Meeting request | 0x00000404
Accept | 0x00000405
Decline | 0x00000406
Tentativly | 0x00000407
Cancellation | 0x00000408
Informational update | 0x00000409
Task/task | 0x00000500
Unassigned recurring task | 0x00000501
Assignee's task | 0x00000502
Assigner's task | 0x00000503
Task request | 0x00000504
Task acceptance | 0x00000505
Task rejection | 0x00000506
Journal conversation | 0x00000601
Journal e-mail message | 0x00000602
Journal meeting request | 0x00000603
Journal meeting response | 0x00000604
Journal task request | 0x00000606
Journal task response | 0x00000607
Journal note | 0x00000608
Journal fax | 0x00000609
Journal phone call | 0x0000060A
Journal letter | 0x0000060C
Journal Microsoft Office Word | 0x0000060D
Journal Microsoft Office Excel | 0x0000060E
Journal Microsoft Office PowerPoint | 0x0000060F
Journal Microsoft Office Access | 0x00000610
Journal document | 0x00000612
Journal meeting | 0x00000613
Journal meeting cancellation | 0x00000614
Journal remote session | 0x00000615

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOTASK]

Specifies the properties and operations that are permissible on contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIdentityDisplay Canonical Property

 Copy code hover
[image]

PidTagIdentityDisplay Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for a service provider's identity as defined within a messaging system.

Associated properties: | PR_IDENTITY_DISPLAY, PR_IDENTITY_DISPLAY_A, PR_IDENTITY_DISPLAY_W
Identifier: | 0x3E00
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI status

Remarks

These properties do not appear as properties on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider's identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMAPISession::QueryIdentity

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIdentityEntryId Canonical Property

 Copy code hover
[image]

PidTagIdentityEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier for a service provider's identity as defined within a messaging system.

Associated properties: | PR_IDENTITY_ENTRYID
Identifier: | 0x3E01
Data type: | PT_BINARY
Area: | MAPI status

Remarks

This property does not appear as a property on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider's identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

This proprerty is commonly set to the appropriate address book entry identifier.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMAPISession::QueryIdentity

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIdentitySearchKey Canonical Property

 Copy code hover
[image]

PidTagIdentitySearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key for a service provider's identity as defined within a messaging system.

Associated properties: | PR_IDENTITY_SEARCH_KEY
Identifier: | 0x3E05
Data type: | PT_BINARY
Area: | MAPI status

Remarks

This property does not appear as a property on any object but only as a column in a status table. It is part of the identity of the service provider exposing the status table row. The provider's identity typically refers to its account on the server, but can refer to any representation the provider defines within the messaging system.

A service provider furnishing any of the identity properties should furnish all of them. Providers that belong to the same message service should expose the same values for the identity properties.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMAPISession::QueryIdentity

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagImapCachedMsgsize Canonical Property

 Copy code hover
[image]

PidTagImapCachedMsgsize Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the size of the cached Internet Message Access Protocol message.

Associated properties: | None
Identifier: | 0x10F0
Data type: | PT_BINARY
Area: | Rename message folder

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagImplicitConversionProhibited Canonical Property

 Copy code hover
[image]

PidTagImplicitConversionProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message transfer agent (MTA) is prohibited from making implicit message text conversions.

Associated properties: | PR_IMPLICIT_CONVERSION_PROHIBITED
Identifier: | 0x0016
Data type: | PT_BOOLEAN
Area: | Server

Remarks

If this property is TRUE, the messaging system must not perform any content conversion on the message unless it is explicitly requested on a per-recipient basis with the PR_EXPLICIT_CONVERSION (PidTagExplicitConversion) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagImportance Canonical Property

 Copy code hover
[image]

PidTagImportance Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the message sender's opinion of the importance of a message.

Associated properties: | PR_IMPORTANCE
Identifier: | 0x0017
Data type: | PT_LONG
Area: | General messaging

Remarks

This property and the PR_PRIORITY (PidTagPriority) property should not be confused. Importance indicates a value to users, while priority indicates the order or speed at which the message should be sent by the messaging system software. Higher priority usually indicates a higher cost. Higher importance usually is associated with a different display by the user interface.

This property can have exactly one of the following values:

IMPORTANCE_LOW

The message has low importance.

IMPORTANCE_HIGH

The message has high importance.

IMPORTANCE_NORMAL

The message has normal importance.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIncompleteCopy Canonical Property

 Copy code hover
[image]

PidTagIncompleteCopy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if this message is an incomplete copy of another message.

Associated properties: | PR_INCOMPLETE_COPY
Identifier: | 0x0035
Data type: | PT_BOOLEAN
Area: | General Message Properties

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInConflict Canonical Property

 Copy code hover
[image]

PidTagInConflict Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE when the attachment represents an alternate replica.

Associated properties: | PR_IN_CONFLICT
Identifier: | 0x666C
Data type: | PT_BOOLEAN
Area: | Conflict note

Remarks

The email client and server must generate a conflict resolve message when detecting a conflict against the current version of a message in the replica during synchronization. It is important to understand that it is possible that the current version of the message in the local replica was transmitted during the current synchronization operation. This will happen when the conflict already exists on the server before any of the conflicting messages were downloaded to the local replica. A conflict resolve message must be synchronized as independent replicas with conflicting PCLs. The conflict resolve message itself must not be synchronized between client and server; only the independent replicas should be exchanged. The synchronization partner must then generate a new message that matches the structure of the conflict message. Therefore, it is important that client and server use the same algorithm to detect the "winner" item. The following rules must be applied to detect the "winner":

  1. Last modification time.

  2. Higher CN GUID (using memory compare) to break tie.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInferenceEnabled Canonical Property

 Copy code hover
[image]

PidTagInferenceEnabled Canonical Property
See also Send feedback

Published: July 16, 2012

Store property controlling Inference logging.

Associated properties: | PR_INFERENCES_ENABLED
Identifier: | 0x3439000
Data type: | Boolean
Area: | Message Store

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInitialDetailsPane Canonical Property

 Copy code hover
[image]

PidTagInitialDetailsPane Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the page of a display template to display first.

Associated properties: | PR_INITIAL_DETAILS_PANE
Identifier: | 0x3F08
Data type: | PT_LONG
Area: | MAPI Display Tables

Remarks

It must be present on all address book objects on an Name Service Provider Interface (NSPI) server, and must have the value zero (0). It must not be defined for any objects in an Offline Address Book.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInitials Canonical Property

 Copy code hover
[image]

PidTagInitials Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the initials for parts of the full name of the recipient.

Associated properties: | PR_INITIALS, PR_INITIALS_A, PR_INITIALS_W
Identifier: | 0x3A0A
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOAB]

Specifies the offline address book (OAB) file formats for the local address book objects cache.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInReplyToId Canonical Property

 Copy code hover
[image]

PidTagInReplyToId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the original message's PR_INTERNET_MESSAGE_ID (PidTagInternetMessageId) property value.

Associated properties: | PR_IN_REPLY_TO_ID, PR_IN_REPLY_TO_ID_A, PR_IN_REPLY_TO_ID_W
Identifier: | 0x1042
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties must be set on all message replies.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagInternetMessageId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInstanceKey Canonical Property

 Copy code hover
[image]

PidTagInstanceKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that uniquely identifies a row in a table.

Associated properties: | PR_INSTANCE_KEY
Identifier: | 0x0FF6
Data type: | PT_BINARY
Area: | Table

Remarks

This property is a binary value that uniquely identifies a row in a table view. It is a required column in most tables. If a row is included in two views, there are two different instance keys. The instance key of a row may differ each time the table is opened, but remains constant while the table is open. Rows added while a table is in use do not reuse an instance key that was previously used.

Use the PR_ENTRYID (PidTagEntryId) or PR_RECORD_KEY (PidTagRecordKey) properties to correlate all the rows of an expansion. Use PR_INSTANCE_KEY to locate a particular instance within the expansion.

When a multivalued property is expanded in a table, a row is created for each instance of the expansion, that is, for each value of that property. Each row has a unique value for the PR_INSTANCE_KEY property, while all the other columns retain their original values throughout the expansion.

In a categorized sort of a table, rows not corresponding to actual data can be added to the result of the sort. Each such row, like all rows in all tables, has its own unique instance key.

PR_INSTANCE_KEY is also used in table event notifications. The propIndex and propPrior members of the TABLE_NOTIFICATION structure are SPropValue structures holding PR_INSTANCE_KEY values. The propIndex member indicates the row that was added or changed. The propPrior member indicates the row before the added or changed row (PR_NULL indicates a change to the first row).

This value is not copied as part of the display table.

PR_INSTANCE_KEY is a MAPIUID structure. All instance keys can be directly compared as binary values.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetApproved Canonical Property

 Copy code hover
[image]

PidTagInternetApproved Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Approved header.

Associated properties: | PR_INTERNET_APPROVED, PR_INTERNET_APPROVED_A, PR_INTERNET_APPROVED_W
Identifier: | 0x1030
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetArticleNumber Canonical Property

 Copy code hover
[image]

PidTagInternetArticleNumber Canonical Property
See also Send feedback

Published: July 16, 2012

A number associated with an item in a message store.

Associated properties: | PR_INTERNET_ARTICLE_NUMBER
Identifier: | 0x0E23
Data type: | PT_LONG
Area: | MIME

Remarks

In IMAPI message stores, this property corresponds to the IMAPI UID.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetCodepage Canonical Property

 Copy code hover
[image]

PidTagInternetCodepage Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the code page used for PR_BODY (PidTagBody) or PR_BODY_HTML (PidTagBodyHtml) properties.

Associated properties: | PR_INTERNET_CPID
Identifier: | 0x3FDE
Data type: | PT_LONG
Area: | Miscellaneous

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetControl Canonical Property

 Copy code hover
[image]

PidTagInternetControl Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Control header.

Associated properties: | PR_INTERNET_CONTROL, PR_INTERNET_CONTROL_A, PR_INTERNET_CONTROL_W
Identifier: | 0x1031
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetDistribution Canonical Property

 Copy code hover
[image]

PidTagInternetDistribution Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Distribution header.

Associated properties: | PR_INTERNET_DISTRIBUTION, PR_INTERNET_DISTRIBUTION_A, PR_INTERNET_DISTRIBUTION_W
Identifier: | 0x1032
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetFollowupTo Canonical Property

 Copy code hover
[image]

PidTagInternetFollowupTo Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Followup-To header.

Associated properties: | PR_INTERNET_FOLLOWUP_TO, PR_INTERNET_FOLLOWUP_TO_A, PR_INTERNET_FOLLOWUP_TO_W
Identifier: | 0x1033
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetLines Canonical Property

 Copy code hover
[image]

PidTagInternetLines Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Lines header.

Associated properties: | PR_INTERNET_LINES
Identifier: | 0x1034
Data type: | PT_LONG
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetMailOverrideFormat Canonical Property

 Copy code hover
[image]

PidTagInternetMailOverrideFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the encoding method and HTML inclusion for attachments that should be set on outgoing mail.

Associated properties: | PR_INETMAIL_OVERRIDE_FORMAT
Identifier: | 0x5902
Data type: | PT_LONG
Area: | MIME

Remarks

For information about the sub-portions into which this property is broken up, see [MS-OXOMSG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Handles message and attachment objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetMessageId Canonical Property

 Copy code hover
[image]

PidTagInternetMessageId Canonical Property
See also Send feedback

Published: July 16, 2012

Corresponds to the message ID field as specified in [RFC2822].

Associated properties: | PR_INTERNET_MESSAGE_ID, PR_INTERNET_MESSAGE_ID_A, PR_INTERNET_MESSAGE_ID_W
Identifier: | 0x1035
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Remarks

These properties should be present on all e-mail messages.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetNntpPath Canonical Property

 Copy code hover
[image]

PidTagInternetNntpPath Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Path header.

Associated properties: | PR_INTERNET_NNTP_PATH, PR_INTERNET_NNTP_PATH_A, PR_INTERNET_NNTP_PATH_W
Identifier: | 0x1038
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetOrganization Canonical Property

 Copy code hover
[image]

PidTagInternetOrganization Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Organization header.

Associated properties: | PR_INTERNET_ORGANIZATION, PR_INTERNET_ORGANIZATION_A, PR_INTERNET_ORGANIZATION_W
Identifier: | 0x1037
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetReferences Canonical Property

 Copy code hover
[image]

PidTagInternetReferences Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a Multipurpose Internet Mail Extensions (MIME) message's References header field.

Associated properties: | PR_INTERNET_REFERENCES, PR_INTERNET_REFERENCES_A, PR_INTERNET_REFERENCES_W
Identifier: | 0x1039
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Remarks

To generate a References header field, clients must set these properties to the desired value. MIME writers must copy the value of these properties to the References header field.

To set the value of these properties, MIME clients must write the desired value to a References header field. MIME readers must copy the value of the References header field to these properties. MIME readers may truncate the value of these properties if it exceeds 64KB in length.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagInternetReturnPath Canonical Property

 Copy code hover
[image]

PidTagInternetReturnPath Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a Multipurpose Internet Mail Extensions (MIME) message's Return-Path header field. The e-mail address of the message's sender.

Associated properties: | PR_INTERNET_RETURN_PATH, PR_INTERNET_RETURN_PATH_A, PR_INTERNET_RETURN_PATH_W
Identifier: | 0x1046
Data type: | PT_STRING8, PT_UNICODE
Area: | MIME

Remarks

To retrieve the value of this property, first use IMAPIProp::GetIDsFromNames to obtain the property tag, and then specify this property tag in IMAPIProp::GetProps to get the value. When calling IMAPIProp::GetIDsFromNames, specify the following values for the MAPINAMEID structure pointed at by the input parameter lppPropNames:

lpGuid: | PS_INTERNET_HEADERS
ulKind: | MNID_STRING
Kind.lpwstrName: | L"return-path"

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Constants
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmAppointmentEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmAppointmentEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Calendar folder.

Associated properties: | PR_IPM_APPOINTMENT_ENTRYID
Identifier: | 0x36D0
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is stored in the Inbox folder and in the root folder of the message store. To access the property on a specific message store, do the following.

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmContactEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmContactEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Contacts folder.

Associated properties: | PR_IPM_CONTACT_ENTRYID
Identifier: | 0x36D1
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is stored in the Inbox folder and in the root folder of the message store. To access the property on a specific message store, do the following:

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmDraftsEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmDraftsEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Drafts folder.

Associated properties: | PR_IPM_DRAFTS_ENTRYID
Identifier: | 0x36D7
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is stored in the Inbox folder as well as the root folder of the message store. To access the property on a specific message store, do the following:

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmJournalEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmJournalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Journal folder.

Associated properties: | PR_IPM_JOURNAL_ENTRYID
Identifier: | 0x36D2
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is stored in the Inbox folder as well as the root folder of the message store. To access the property on a specific message store, do the following:

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmNoteEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmNoteEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Notes folder.

Associated properties: | PR_IPM_NOTE_ENTRYID
Identifier: | 0x36D3
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is stored in the Inbox folder as well as the root folder of the message store. To access the property on a specific message store, do the following:

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmOutboxEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmOutboxEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the standard interpersonal message (IPM) Outbox folder.

Associated properties: | PR_IPM_OUTBOX_ENTRYID
Identifier: | 0x35E2
Data type: | PT_BINARY
Area: | Folder

Remarks

Outbound messages are usually created in the Outbox folder. Interpersonal messages should be placed in this folder for submission.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmReturnRequested Canonical Property

 Copy code hover
[image]

PidTagIpmReturnRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if this message should be returned with a report.

Associated properties: | PR_IPM_RETURN_REQUESTED
Identifier: | 0x0C02
Data type: | PT_BOOLEAN
Area: | General messaging

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmSentMailEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmSentMailEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the standard interpersonal message (IPM) Sent Items folder.

Associated properties: | PR_IPM_SENTMAIL_ENTRYID
Identifier: | 0x35E4
Data type: | PT_BINARY
Area: | Folder

Remarks

After being sent, interpersonal messages are usually placed in the Sent Items folder. A client can use this property to set the PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId) property on a submitted message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmSubtreeEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmSubtreeEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the root of the interpersonal message (IPM) folder subtree in the message store's folder tree.

Associated properties: | PR_IPM_SUBTREE_ENTRYID
Identifier: | 0x35E0
Data type: | PT_BINARY
Area: | Folder

Remarks

This property represents the root of the IPM hierarchy. IPM clients should not display any folders that are not subfolders of the folder represented by this property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmTaskEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmTaskEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the Outlook Tasks folder.

Associated properties: | PR_IPM_TASK_ENTRYID
Identifier: | 0x36D4
Data type: | PT_BINARY
Area: | Folder

Remarks

This property is read or written by using the Property and Stream Object protocol. It is read from and written to the Inbox or Root folder. The implementation must use the Inbox folder when the store is that of the primary messaging user, and it must use the Root folder when the store is that of a delegate user.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIpmWastebasketEntryId Canonical Property

 Copy code hover
[image]

PidTagIpmWastebasketEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the standard interpersonal message (IPM) Deleted Items folder.

Associated properties: | PR_IPM_WASTEBASKET_ENTRYID
Identifier: | 0x35E3
Data type: | PT_BINARY
Area: | Folder

Remarks

A client application should move deleted interpersonal messages to the Deleted Items folder. If the message is already in this folder, or if this property is not supported, the client should delete the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagIsdnNumber Canonical Property

 Copy code hover
[image]

PidTagIsdnNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's ISDN-capable telephone number.

Associated properties: | PR_ISDN_NUMBER, PR_ISDN_NUMBER_A, PR_ISDN_NUMBER_W
Identifier: | 0x3A2D
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagItemTemporaryflags Canonical Property

 Copy code hover
[image]

PidTagItemTemporaryflags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a flag that indicates that a message has been read, but not marked as read.

Associated properties: | PR_ITEM_TMPFLAGS
Identifier: | 0x1097
Data type: | PT_LONG
Area: | General messaging

Remarks

This property is used in Outlook's Unread Messages search folder to keep track of which messages have been read without actually marking them as read, which would remove them from the folder. When the view changes this property is removed and the item is marked as read. This property will not synchronize to the Exchange Server.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagJunkAddRecipientsToSafeSendersList Canonical Property

 Copy code hover
[image]

PidTagJunkAddRecipientsToSafeSendersList Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether or not the mail recipients are to be added to the safe senders list.

Associated properties: | PR_JUNK_ADD_RECIPS_TO_SSL
Identifier: | 0x6103
Data type: | PT_LONG
Area: | Spam

Remarks

If present, this property must be set to 0 or 1. A value of 1 indicates that the mail recipients are to be added to the safe senders list. A value of 0 indicates that the mail recipients are not to be added to the safe senders list.

If this property is present with a value of 1, the SMTP addresses of the e-mail recipients must be added to trusted senders clause of the Junk E-Mail Rule condition. If this property is 0, no action is required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagJunkIncludeContacts Canonical Property

 Copy code hover
[image]

PidTagJunkIncludeContacts Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether e-mail addresses of the contacts in the Contacts folder are treated specially with respect to the spam filter.

Associated properties: | PR_JUNK_INCLUDE_CONTACTS
Identifier: | 0x6100
Data type: | PT_LONG
Area: | Spam

Remarks

If set to "0x00000001", these e-mail addresses must populate the "trusted" contact e-mail address portion of the Junk E-Mail Rule Restriction such that mail from these addresses is treated as "not junk". If set to "0x00000000", e-mail addresses from the Contacts folder must not be added to the Junk E-Mail Rule, and the section of the rule must be NULL.

If this property is present with a value of "0x00000001" and if the added contact has e-mail addresses that are not yet included in the trusted contacts section of the Junk E-Mail Rule, those e-mail addresses must be added to the restriction. If this property is "0x00000000", no action is required.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagJunkPermanentlyDelete Canonical Property

 Copy code hover
[image]

PidTagJunkPermanentlyDelete Canonical Property
See also Send feedback

Published: July 16, 2012

Signifies, if set to 1, that messages identified as spam may be permanently deleted.

Associated properties: | PR_JUNK_PERMANENTLY_DELETE
Identifier: | 0x6102
Data type: | PT_LONG
Area: | Spam

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagJunkPhishingEnableLinks Canonical Property

 Copy code hover
[image]

PidTagJunkPhishingEnableLinks Canonical Property
See also Send feedback

Published: July 16, 2012

Signifies, if TRUE, that the phishing stamp on the message should be ignored.

Associated properties: | PR_JUNK_PHISHING_ENABLE_LINKS
Identifier: | 0x6107
Data type: | PT_BOOLEAN
Area: | Spam

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

[MS-OXPHISH]

Identifies and marks e-mail messages that are designed to trick recipients into divulging sensitive information (such as passwords and other personal information) to a non-trustworthy source.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagJunkThreshold Canonical Property

 Copy code hover
[image]

PidTagJunkThreshold Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates how aggressively incoming mail should be sent to the Junk E-mail folder.

Associated properties: | PR_JUNK_THRESHOLD
Identifier: | 0x6101
Data type: | PT_LONG
Area: | Spam

Remarks

This property corresponds to the high / low / none filter setting. A value of "0xFFFFFFFF" indicates that spam filtering should not be applied, however block lists must still be applied. A value of "0x80000000" indicates that all mail is spam except those messages from senders on the trusted senders list or sent to recipients on the trusted recipients list. Values for this are as follows:

Value | Description
0xFFFFFFFF | No spam filtering
0x00000006 | Low spam filtering
0x00000003 | High spam filtering
0x80000000 | Trusted Lists Only

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagKeyword Canonical Property

 Copy code hover
[image]

PidTagKeyword Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a keyword that identifies the recipient to the recipient's system administrator.

Associated properties: | PR_KEYWORD, PR_KEYWORD_A, PR_KEYWORD_W
Identifier: | 0x3A0B
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLanguage Canonical Property

 Copy code hover
[image]

PidTagLanguage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the language in which the messaging user is writing messages.

Associated properties: | PR_LANGUAGE, PR_LANGUAGE_A, PR_LANGUAGE_W
Identifier: | 0x3A0C
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

The string contains a single two-character country/region code.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagLanguages Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLanguages Canonical Property

 Copy code hover
[image]

PidTagLanguages Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASCII list of the languages that are incorporated in a message.

Associated properties: | PR_LANGUAGES, PR_LANGUAGES_A, PR_LANGUAGES_W
Identifier: | 0x002F
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties contain a sequence of two-character country/region codes that are separated by commas.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLastModificationTime Canonical Property

 Copy code hover
[image]

PidTagLastModificationTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when the object or subobject was last modified.

Associated properties: | PR_LAST_MODIFICATION_TIME
Identifier: | 0x3008
Data type: | PT_SYSTIME
Area: | Message time

Remarks

This property is initially set to the same value as the PR_CREATION_TIME (PidTagCreationTime) property. Attachment subobjects can update it as necessary by copying the last modification time maintained by the native file system. A client application can set this property until the first call to the IMAPIProp::SaveChanges method. From then on the provider should update PR_LAST_MODIFICATION_TIME during every IMAPIProp::SaveChanges call.

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLastVerbExecuted Canonical Property

 Copy code hover
[image]

PidTagLastVerbExecuted Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the last verb executed.

Associated properties: | PR_LAST_VERB_EXECUTED
Identifier: | 0x1081
Data type: | PT_LONG
Area: | History

Remarks

This property can have one the following values:

Verb | Property value
Post | 0x00000001
Other | 0x00000003
Read mail | 0x00000100
Unread mail | 0x00000101
Submitted mail | 0x00000102
Unsent mail | 0x00000103
Receipt mail | 0x00000104
Replied mail | 0x00000105
Forwarded mail | 0x00000106
Remote mail | 0x00000107
Delivery Receipt | 0x00000108
Read Receipt | 0x00000109
Nondelivery Receipt | 0x0000010A
Nonread Receipt | 0x0000010B
Recall_S mail | 0x0000010C
Recall_F mail | 0x0000010D
Tracking mail | 0x0000010E
Out of Office mail | 0x0000011B
Recall mail | 0x0000011C
Tracked mail | 0x00000139
Contact | 0x00000200
Distribution List | 0x00000201
Sticky Note, Blue | 0x00000300
Sticky Note, Green | 0x00000301
Sticky Note, Pink | 0x00000302
Sticky Note, Yellow | 0x00000303
Sticky Note, White | 0x00000304
Single Instance Appointment | 0x00000400
Recurring Appointment | 0x00000401
Single Instance Meeting | 0x00000402
Recurring Meeting | 0x00000403
Meeting Request / Full Update | 0x00000404
Accept | 0x00000405
Decline | 0x00000406
Tentatively Accept | 0x00000407
Cancelation | 0x00000408
Informational Update | 0x00000409
Task/Task Update | 0x00000500
Unassigned Recurring Task | 0x00000501
Assignee's Task | 0x00000502
Assigner's Task | 0x00000503
Task Request | 0x00000504
Task Acceptance | 0x00000505
Task Rejection | 0x00000506
Journal Conversation | 0x00000601
Journal E-mail Message | 0x00000602
Journal Meeting request | 0x00000603
Journal Meeting response | 0x00000604
Journal Task request | 0x00000606
Journal Task response | 0x00000607
Journal Note | 0x00000608
Journal Fax | 0x00000609
Journal Phone call | 0x0000060A
Journal Task | 0x0000060B
Journal Letter | 0x0000060C
Journal Microsoft Office Word | 0x0000060D
Journal Microsoft Office Excel | 0x0000060E
Journal Microsoft Office PowerPoint | 0x0000060F
Journal Microsoft Office Access | 0x00000610
Journal Document | 0x00000612
Journal Meeting | 0x00000613
Journal Meeting cancellation | 0x00000614
Journal Remote session | 0x00000615
New mail | 0xFFFFFFFF

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLastVerbExecutionTime Canonical Property

 Copy code hover
[image]

PidTagLastVerbExecutionTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the time when the last verb was executed.

Associated properties: | PR_LAST_VERB_EXECUTION_TIME
Identifier: | 0x1082
Data type: | PT_SYSTIME
Area: | History

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLatestDeliveryTime Canonical Property

 Copy code hover
[image]

PidTagLatestDeliveryTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the latest date and time when a message transfer agent (MTA) should deliver a message.

Associated properties: | PR_LATEST_DELIVERY_TIME
Identifier: | 0x0019
Data type: | PT_SYSTIME
Area: | General messaging

Remarks

If an MTA cannot deliver a message by the time this property specifies, it cancels the message without delivery.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagListHelp Canonical Property

 Copy code hover
[image]

PidTagListHelp Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a Multipurpose Internet Mail Extensions (MIME) message's List-Help header field.

Associated properties: | PR_LIST_HELP, PR_LIST_HELP_A, PR_LIST_HELP_W
Identifier: | 0x1043
Data type: | PT_STRING8, PT_UNICODE
Area: | Miscellaneous

Remarks

To generate a List-Help header field, clients must set the value of PR_LIST_HELP or an associated property to the desired value. MIME writers must copy this value to the List-Help header field.

To set the value of these list server-related properties, MIME clients must write the header fields as specified in the following table:

Property | Preferred header field name | Alternate header field name
PR_LIST_HELP | List-Help | X-List-Help

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagListSubscribe Canonical Property

 Copy code hover
[image]

PidTagListSubscribe Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a Multipurpose Internet Mail Extensions (MIME) message's List-Subscribe header field.

Associated properties: | PR_LIST_SUBSCRIBE, PR_LIST_SUBSCRIBE_A, PR_LIST_SUBSCRIBE_W
Identifier: | 0x1044
Data type: | PT_STRING8, PT_UNICODE
Area: | Miscellaneous

Remarks

To generate a List-Subscribe header field, clients must set the value of these properties to the desired value. MIME writers must copy the value of these properties to the List-Subscribe header field.

To set the value of server-related properties like these, MIME clients must write the header fields as specified in the following table.

Property | Preferred header field name | Alternate header field name
PidTagListSubscribe | List-Subscribe | X-List-Subscribe

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagListUnsubscribe Canonical Property

 Copy code hover
[image]

PidTagListUnsubscribe Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of a Multipurpose Internet Mail Extensions (MIME) message's List-Unsubscribe header field.

Associated properties: | PR_LIST_UNSUBSCRIBE, PR_LIST_UNSUBSCRIBE_A, PR_LIST_UNSUBSCRIBE_W
Identifier: | 0x1045
Data type: | PT_STRING8, PT_UNICODE
Area: | Miscellaneous

Remarks

To generate a List-Unsubscribe header field, clients must set these properties to the desired value. MIME writers must copy the value of these properties to the List-Unsubscribe header field.

To set the value of these list server-related properties, MIME clients must write the header fields as specified in the following table.

Property | Preferred header field name | Alternate header field name
PR_LIST_UNSUBSCRIBE | List-Unsubscribe | X-List-Unsubscribe

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLocaleId Canonical Property

 Copy code hover
[image]

PidTagLocaleId Canonical Property
See also Send feedback

Published: July 16, 2012

Establishes the language locale for translating system-generated messages, such as delivery reports.

Associated properties: | PR_LOCALE_ID
Identifier: | 0x66A1
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

This property is available on a private mailbox logon.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLocality Canonical Property

 Copy code hover
[image]

PidTagLocality Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the recipient's locality, such as the town or city.

Associated properties: | PR_LOCALITY, PR_LOCALITY_A, PR_LOCALITY_W, PR_BUSINESS_ADDRESS_LOCALITY, PR_BUSINESS_ADDRESS_LOCALITY_A, PR_BUSINESS_ADDRESS_LOCALITY_W
Identifier: | 0x3A27
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. Theys are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLocation Canonical Property

 Copy code hover
[image]

PidTagLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the location of the recipient in a format that is useful to the recipient's organization.

Associated properties: | PR_LOCATION, PR_LOCATION_A, PR_LOCATION_W
Identifier: | 0x3A0D
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

The contents are defined by the needs of the recipient's organization. For example, some organizations might identify messaging users by specifying the building number and office number.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagLongTermEntryIdFromTable Canonical Property

 Copy code hover
[image]

PidTagLongTermEntryIdFromTable Canonical Property
See also Send feedback

Published: July 16, 2012

Obtains the long- term entry identifier of an item.

Associated properties: | PR_LONGTERM_ENTRYID_FROM_TABLE
Identifier: | 0x6670
Data type: | PT_BINARY
Area: | Table Properties

Remarks

This property can be used in a contents table to get the entry identifier of an item as a long-term entry identifier instead of a short-term entry identifier. For information about long-term and short-term identifiers, see PR_ENTRYID (PidTagEntryId).

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMailboxOwnerName Canonical Property

 Copy code hover
[image]

PidTagMailboxOwnerName Canonical Property
See also Send feedback

Published: July 16, 2012

Displays the name of the owner of the mailbox.

Associated properties: | PR_MAILBOX_OWNER_NAME, PR_MAILBOX_OWNER_NAME_A, PR_MAILBOX_OWNER_NAME_W
Identifier: | 0x001F
Data type: | PT_UNICODE, PT_UNICODE
Area: | Message Store

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMailPermission Canonical Property

 Copy code hover
[image]

PidTagMailPermission Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the messaging user is allowed to send and receive messages.

Associated properties: | PR_MAIL_PERMISSION
Identifier: | 0x3A0E
Data type: | PT_BOOLEAN
Area: | Address

Remarks

If this property is not set, MAPI treats it as having a TRUE value.

Set this property to FALSE in a corporate directory where some of the entries are not e-mail-enabled.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagManagerName Canonical Property

 Copy code hover
[image]

PidTagManagerName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the recipient's manager.

Associated properties: | PR_MANAGER_NAME, PR_MANAGER_NAME_A, PR_MANAGER_NAME_W
Identifier: | 0x3A4E
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidef.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMappingSignature Canonical Property

 Copy code hover
[image]

PidTagMappingSignature Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the mapping signature for named properties of a particular MAPI object.

Associated properties: | PR_MAPPING_SIGNATURE
Identifier: | 0x0FF8
Data type: | PT_BINARY
Area: | Miscellaneous

Remarks

It is recommended that objects having named properties expose this property. A client application should check the PR_MAPPING_SIGNATURE property of both objects when copying named properties from one object to another. Use of this property can minimize translating between copied properties' names and identifiers.

If this property does not exist for a given MAPI object, then the object has its own unique mapping of names and identifiers. In this case the client must call the IMAPIProp::GetNamesFromIDs method on the source object and then the IMAPIProp::GetIDsFromNames method on the destination object.

When two objects have the same PR_MAPPING_SIGNATURE value, the client does not need to translate name to identifier and identifier to name. The client can simply call the IMAPIProp::GetProps method on the source and then the IMAPIProp::SetProps method on the destination. This is convenient for clients that perform custom copying of named properties, and for providers implementing the IMAPIProp::CopyTo and IMAPIProp::CopyProps methods.

For more information on named properties and mapping of names and identifiers, see MAPI Named Properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

MAPINAMEID

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMemberEntryId Canonical Property

 Copy code hover
[image]

PidTagMemberEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the directory object entry identifier of a system access control list (SACL) table member.

Associated properties: | PR_MEMBER_ENTRYID
Identifier: | 0x0FFF
Data type: | PT_BINARY
Area: | Server Side Rules

Remarks

This property is used by the IExchangeModifyTable interface to uniquely identify a person or role to whom the SACL applies. After a member is created in the SACL table, the ENTRYID cannot be changed. To change it, you must delete the table member and re-create it with a different ENTRYID.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMemberId Canonical Property

 Copy code hover
[image]

PidTagMemberId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the identifier of a table member that has the described rights on a Microsoft Exchange Server folder or mailbox.

Associated properties: | PR_MEMBER_ID
Identifier: | 0x6671
Data type: | PT_I8
Area: | Access Control

Remarks

This property returns an identifier unique to the table. A directory user identifier is associated with each member identifier and is given by this property. This property is used by the IExchangeModifyTable interface to retrieve the directory entry identifier of a member with explicit rights on a folder.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCPERM]

Handles the retrieval of folder permission lists that are stored on the server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagMemberEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMemberName Canonical Property

 Copy code hover
[image]

PidTagMemberName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of a member of the access control list (ACL) table.

Associated properties: | PR_MEMBER_NAME, PR_MEMBER_NAME_A, PR_MEMBER_NAME_W
Identifier: | 0x6672
Data type: | PT_STRING8
Area: | Access Control

Remarks

These properties are used by the IExchangeModifyTable : IUnknown interface to display the name of a member of an ACL table, which is a person or role with explicit rights on a folder or mailbox.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCPERM]

Handles the retrieval of folder permission lists that are stored on the server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IExchangeModifyTable : IUnknown

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMemberRights Canonical Property

 Copy code hover
[image]

PidTagMemberRights Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a set of bits that indicated the rights of this member on a folder or mailbox.

Associated properties: | PR_MEMBER_RIGHTS
Identifier: | 0x6673
Data type: | PT_LONG
Area: | Access Control

Remarks

This property is used by the IExchangeModifyTable interface to define rights of a member on a folder. These rights can be displayed and modified. The following values are rights defined for this property.

frightsReadAny

Member can read any messages.

frightsCreate

Member can create messages.

frightsEditOwned

Member can edit any messages owned by the user.

frightsDeleteOwned

Member can delete any messages owned by the user.

frightsEditAny

Member can edit any message.

frightsDeleteAny

Member can delete any message.

frightsCreateSubfolder

Member can create subfolders for the folder.

frightsOwner

Member has all the previous rights on the folder.

frightsContact

Member can have your name appear as the contact on the folder.

frightsVisible

Member can see that the folder exists.

rightsNone

Member does not have rights on the folder.

rightsReadOnly

Member can read any message in the folder.

rightsReadWrite

Member can read from and write to any message in the folder.

rightsAll

Member has all the previous rights on the folder.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCPERM]

Handles the retrieval of folder permission lists that are stored on the server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar items when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IExchangeModifyTable : IUnknown

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageAttachments Canonical Property

 Copy code hover
[image]

PidTagMessageAttachments Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a table of restrictions that can be applied to a contents table to find all messages that contain attachment subobjects that meet the restrictions.

Associated properties: | PR_MESSAGE_ATTACHMENTS
Identifier: | 0x0E13
Data type: | PT_OBJECT
Area: | Message attachment

Remarks

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method. Its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMessage::GetAttachmentTable method. For more information, see Attachment Tables.

This property can be used for subobject restriction by specifying it in the SSubRestriction structure. This allows the client to limit the view of a container to messages with attachments meeting given criteria. A message qualifies for viewing if at least one row in its attachments table, that is, one attachment, satisfies the subobject restriction.

Related Resources

Protocol Specifications

[MS-OXCDATA]

Defines the basic data structures that are used in remote operations.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageCcMe Canonical Property

 Copy code hover
[image]

PidTagMessageCcMe Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if this messaging user is specifically named as a carbon copy (CC) recipient of this message and is not part of a distribution list.

Associated properties: | PR_MESSAGE_CC_ME
Identifier: | 0x0058
Data type: | PT_BOOLEAN
Area: | General messaging

Remarks

This property provides a convenient way to determine whether the user name appears explicitly in the carbon copy recipient list, without examining all entries in the list.

This property also assists automated handling of received messages at the time of receipt. At the transport provider's option, this property either contains FALSE or is not set if the messaging user is not listed directly in the recipient table.

Message delivery resulting from distribution list expansion or a blind carbon copy designation does not cause this property to be set. The recipient must be explicitly named.

Unsent messages generally do not set this property, PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe), or PR_MESSAGE_TO_ME (PidTagMessageToMe). If they are present in messages the user can access in public message stores, in other users' private stores, in files on disk, or embedded inside other received messages, they generally contain the values to which they were set the last time a transport provider delivered the message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageClass Canonical Property

 Copy code hover
[image]

PidTagMessageClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a text string that identifies the sender-defined message class, such as IPM.Note.

Associated properties: | PR_MESSAGE_CLASS, PR_MESSAGE_CLASS_A, PR_MESSAGE_CLASS_W
Identifier: | 0x001A
Data type: | PT_UNICODE, PT_STRING8
Area: | Common

Remarks

The message class specifies the type of the message. It determines the set of properties defined for the message, the kind of information the message conveys, and how to handle the message.

These properties contain strings concatenated with periods. Each string represents a level of subclassing. For example, IPM.Note is a subclass of IPM and a superclass of IPM.Note.Private.

These properties must consist of the ASCII characters 32 through 127 and must not end with a period (ASCII 46). Sort and compare operations must treat it as a case-insensitive string. The maximum possible length is 255 characters, but in order to allow MAPI room to append qualifiers it is recommended that the original length be kept under 128 characters.

Every message is required to furnish these properties. Normally, the client application creating a new message sets it as soon as IMAPIFolder::CreateMessage returns successfully. But if the property has not been set when the client calls IMAPIProp::SaveChanges, the message store should set it to IPM.

The values defined by MAPI are:

Copy code Copy code
IPM.Note for a standard interpersonal message
REPORT.<subject message class>.DR for a delivery report
REPORT.<subject message class>.NDR for a nondelivery report
REPORT.<subject message class>.IPNRN for a read report
REPORT.<subject message class>.IPNNRN for a nonread report

IPM and IPC are intended to be superclasses only, and a message should have at least one subclass qualifier appended before being stored or submitted. For more information on message class usage, see Message Classes. For lists of required and optional properties for message classes, see the subtopics of About Message Properties.

A custom message class can define properties in a reserved range for use with that message class only. For more information, see About Property Identifiers.

Message classes control which receive folder an incoming message is stored in. For more information, see the IMsgStore::GetReceiveFolderTable method.

For more information on using message classes with forms and form servers, see Choosing a Message Class.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXOUM]

Specifies the properties and operations that are permissible for representing voice mail and fax messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageCodepage Canonical Property

 Copy code hover
[image]

PidTagMessageCodepage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the code page that is used for the message.

Associated properties: | PR_MESSAGE_CODEPAGE
Identifier: | 0x3FFD
Data type: | PT_LONG
Area: | Common

Remarks

The folder object code page is used if this property is set to zero (0).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXPFOAB]

Specifies the method of delivering offline address book (OAB) data from server to client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageDeliveryId Canonical Property

 Copy code hover
[image]

PidTagMessageDeliveryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message transfer system (MTS) identifier for a message delivered to a client application.

Associated properties: | PR_MESSAGE_DELIVERY_ID
Identifier: | 0x001B
Data type: | PT_BINARY
Area: | Server

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageDeliveryTime Canonical Property

 Copy code hover
[image]

PidTagMessageDeliveryTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when a message was delivered.

Associated properties: | PR_MESSAGE_DELIVERY_TIME
Identifier: | 0x0E06
Data type: | PT_SYSTIME
Area: | Message time

Remarks

This property describes the time the message was stored at the server, rather than the download time when the transport provider copied the message from the server to the local store.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageDownloadTime Canonical Property

 Copy code hover
[image]

PidTagMessageDownloadTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the estimated time to download a message from a remote server to a local message store.

Associated properties: | PR_MESSAGE_DOWNLOAD_TIME
Identifier: | 0x0E18
Data type: | PT_LONG
Area: | General messaging

Remarks

This property is expressed in seconds and represents the best estimate of the time it would take a remote transport provider to download a given message from its current location to a message store local to the client viewing the header folder. The remote transport provider typically calculates the value for this property by dividing the value of the PR_MESSAGE_SIZE (PidTagMessageSize) property by the speed of the communications link in bytes per second. If the provider cannot calculate the download time, for example if it does not know the link speed, it should furnish a PT_ERROR value such as MAPI_E_NO_SUPPORT for this column in the header folder contents table.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageEditorFormat Canonical Property

 Copy code hover
[image]

PidTagMessageEditorFormat Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the format for an editor to use to display a message.

Associated properties: | PR_MSG_EDITOR_FORMAT
Identifier: | 0x5909
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

The possible values for PR_MSG_EDITOR_FORMAT can be one of the following:

Value | Description
EDITOR_FORMAT_DONTKNOW | The format for the editor to use is unknown.
EDITOR_FORMAT_PLAINTEXT | The editor should display the message in plain text format.
EDITOR_FORMAT_HTML | The editor should display the message in HTML format.
EDITOR_FORMAT_RTF | The editor should display the message in Rich Text Format.

By default, mail messages (with the message class IPM.Note or with a custom message class derived from IPM.Note) sent from a POP3/SMTP mail account are sent in the Transport Neutral Encapsulation Format (TNEF). The PR_MSG_EDITOR_FORMAT property can be used to enforce only plain text, and not TNEF, when sending a message. If PR_MSG_EDITOR_FORMAT is set to EDITOR_FORMAT_PLAINTEXT, the message is sent as plain text without TNEF. If PR_MSG_EDITOR_FORMAT is set to EDITOR_FORMAT_RTF, TNEF encoding is implicitly enabled, and the message is sent by using the default Internet format that is specified in the Outlook client.

There are two other ways to enforce the use of TNEF when sending a message.

  • Setting the dispidUseTNEF (PidLidUseTnef) named property to True on a message indicates TNEF should be included when converting the message from MAPI to MIME/SMTP. Note that dispidUseTNEF only applies when the message is sent from a POP3/SMTP mail account, and does not apply when the message is sent by other providers, such as Microsoft Exchange Server. dispidUseTNEF overrides the setting in PR_MSG_EDITOR_FORMAT.

  • Using the CCSF_USE_TNEF flag when calling IConverterSession::MAPIToMIMEStm to convert an outgoing MAPI message to a MIME stream can also enforce TNEF. This applies even if dispidUseTNEF is not set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageFlags Canonical Property

 Copy code hover
[image]

PidTagMessageFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that indicate the origin and current state of a message.

Associated properties: | PR_MESSAGE_FLAGS
Identifier: | 0x0E07
Data type: | PT_LONG
Area: | General messaging

Remarks

This property is a nontransmittable message property exposed at both the sending and receiving ends of a transmission, with different values depending upon the client application or store provider involved. This property is initialized by the client or message store provider when a message is created and saved for the first time and then updated periodically by the message store provider, a transport provider, and the MAPI spooler as the message is processed and its state changes.

This property exists on a message both before and after submission, and on all copies of the received message. Although it is not a recipient property, it is exposed differently to each recipient according to whether it has been read or modified by that recipient.

One or more of the following flags can be set for this property:

MSGFLAG_ASSOCIATED

The message is an associated message of a folder. The client or provider has read-only access to this flag. The MSGFLAG_READ flag is ignored for associated messages, which do not retain a read/unread state.

MSGFLAG_FROMME

The messaging user sending was the messaging user receiving the message. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter. This flag is meant to be set by the transport provider.

MSGFLAG_HASATTACH

The message has at least one attachment. This flag corresponds to the message's PR_HASATTACH (PidTagHasAttachments) property. The client has read-only access to this flag.

MSGFLAG_NRN_PENDING

A nonread report needs to be sent for the message. The client or provider has read-only access to this flag.

MSGFLAG_ORIGIN_INTERNET

The incoming message arrived over the Internet. It originated either outside the organization or from a source the gateway cannot consider trusted. The client should display an appropriate message to the user. Transport providers set this flag; the client has read-only access.

MSGFLAG_ORIGIN_MISC_EXT

The incoming message arrived over an external link other than X.400 or the Internet. It originated either outside the organization or from a source the gateway cannot consider trusted. The client should display an appropriate message to the user. Transport providers set this flag; the client has read-only access.

MSGFLAG_ORIGIN_X400

The incoming message arrived over an X.400 link. It originated either outside the organization or from a source the gateway cannot consider trusted. The client should display an appropriate message to the user. Transport providers set this flag; the client has read-only access.

MSGFLAG_READ

The message is marked as having been read. This can occur as the result of a call at any time to IMessage::SetReadFlag or IMAPIFolder::SetReadFlags. Clients can also set this flag by calling a message's IMAPIProp::SetProps method before the message has been saved for the first time. This flag is ignored if the MSGFLAG_ASSOCIATED flag is set.

MSGFLAG_RESEND

The message includes a request for a resend operation with a nondelivery report. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter.

MSGFLAG_RN_PENDING

A read report needs to be sent for the message. The client or provider has read-only access to this flag.

MSGFLAG_SUBMIT

The message is marked for sending as a result of a call to IMessage::SubmitMessage. Message store providers set this flag; the client has read-only access.

MSGFLAG_UNMODIFIED

The outgoing message has not been modified since the first time that it was saved; the incoming message has not been modified since it was delivered.

MSGFLAG_UNSENT

The message is still being composed. It is saved, but has not been sent. The client or provider has read/write access to this flag until the first IMAPIProp::SaveChanges call and read-only thereafter. If a client doesn't set this flag by the time the message is sent, the message store provider sets it when IMessage::SubmitMessage is called. Typically, this flag is cleared after the message is sent.

A client or message store provider can check the current state of the message at any time by calling the IMAPIProp::GetProps method to read the flag values. The client or provider can also call the IMAPIProp::SetProps method to change any flags that currently have read/write access.

Several of the flags are always read-only. Some are read/write until the first call to the IMAPIProp::SaveChanges method and thereafter become read-only as far as IMAPIProp::SetProps is concerned. One of these, MSGFLAG_READ, can be changed later through IMessage::SetReadFlag or IMAPIFolder::SetReadFlags.

The initial values for this property are typically MSGFLAG_UNSENT and MSGFLAG_UNMODIFIED to indicate a message that has not yet been sent or changed. When a message is saved for the second time, the message store provider clears the MSGFLAG_UNMODIFIED flag. Another value that a message store provider can set when a message is saved is the MSGFLAG_HASATTACH flag, indicating that the message has one or more attachments. The PR_HASATTACH property is computed from this setting.

When a client calls the IMessage::SubmitMessage method to send the message, the message store provider makes a copy of it for the MAPI spooler and updates this property by setting the MSGFLAG_SUBMIT flag. The message store provider also sets MSGFLAG_UNSENT if it is not yet set. MSGFLAG_SUBMIT indicates that SubmitMessage has been called, beginning the send process, and that the message is now read-only to the client. MSGFLAG_UNSENT indicates that the MAPI spooler is handling the message. If the send process is canceled, the message store provider resets this flag.

When the message is given to a transport provider for delivery, the transport provider sets the MSGFLAG_FROMME flag if the sender had the same account on the messaging server as the message was received on. Transport providers set MSGFLAG_FROMME for an incoming message that was sent by the currently logged on user. A client can use this value to determine that it is more appropriate to show recipient names in the contents table of the Sent Items folder than sender names. Messages that have been saved during the composition process and not yet sent should also be displayed with recipient names rather than sender names.

For an incoming message, a message store provider clears the MSGFLAG_READ flag to reset its read status. A client can set or clear the MSGFLAG_READ flag when it is necessary to change the read status and control the sending of read and nonread reports, by calling either the message's IMessage::SetReadFlag method or its folder's IMAPIFolder::SetReadFlags method. The main difference between these methods, other than the object implementing them, is that the folder method can affect one, several, or all of the messages in the folder. The message method affects a single message.

A client should also test an incoming message for the MSGFLAG_ORIGIN_X400, MSGFLAG_ORIGIN_INTERNET, and MSGFLAG_ORIGIN_MISC_EXT flags. These flags are set by the inbound transport provider and indicate that the message arrived from a source that the gateway cannot consider trusted. This means the message originated either outside the organization, or internally but from a workstation not known to the gateway. In any case, the identity of the sender may not be confirmed, and there is a risk of introducing a computer virus into the organization. The client should display a warning message to the user and offer an option of deleting the message without opening it.

Message store providers set the MSGFLAG_UNMODIFIED flag for incoming messages. MSGFLAG_UNMODIFIED indicates that a message has not been changed since delivery. A client cannot clear this value after it has been set by a message store provider.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMsgStore::AbortSubmit

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageHandlingSystemCommonName Canonical Property

 Copy code hover
[image]

PidTagMessageHandlingSystemCommonName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the common name of the message handling system.

Associated properties: | PR_MHS_COMMON_NAME, PR_MHS_COMMON_NAME_A, PR_MHS_COMMON_NAME_W
Identifier: | 0x3A0F
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties contain the common name of the message handling system.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageLocaleId Canonical Property

 Copy code hover
[image]

PidTagMessageLocaleId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the Windows LCID of the end user who created this message.

Associated properties: | PR_MESSAGE_LOCALE_ID
Identifier: | 0x3FF1
Data type: | PT_LONG
Area: | Miscellaneous

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageRecipientMe Canonical Property

 Copy code hover
[image]

PidTagMessageRecipientMe Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if this messaging user is specifically named as a primary (To), carbon copy (CC), or blind carbon copy (BCC) recipient of this message and is not part of a distribution list.

Associated properties: | PR_MESSAGE_RECIP_ME
Identifier: | 0x0059
Data type: | PT_BOOLEAN
Area: | General messaging

Remarks

This property provides a convenient way to determine whether the user name appears explicitly in the recipient list, without examining all entries in the list. The value represents the logical OR operation of the properties PR_MESSAGE_CC_ME (PidTagMessageCcMe) and PR_MESSAGE_TO_ME (PidTagMessageToMe), and the BCC information (which does not otherwise appear in a property).

This property assists automated handling of received messages at the time of receipt. At the transport provider's option, this property either contains FALSE or is not included if the messaging user is not listed directly in the recipient table.

Message delivery that results from distribution list expansion does not cause this property to be set. The recipient must be explicitly named.

Unsent messages generally do not set this property, PR_MESSAGE_CC_ME, or PR_MESSAGE_TO_ME. If they are present in messages the user can access in public message stores, in other users' private stores, in files on disk, or embedded inside other received messages, they generally contain the values to which they were set the last time a transport provider delivered the message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageRecipients Canonical Property

 Copy code hover
[image]

PidTagMessageRecipients Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a table of restrictions that can be applied to a contents table to find all messages that contain recipient subobjects that meet the restrictions.

Associated properties: | PR_MESSAGE_RECIPIENTS
Identifier: | 0x0E12
Data type: | PT_OBJECT
Area: | General messaging

Remarks

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method. Its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the IID_IMAPITable interface identifier. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but may optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMessage::GetRecipientTable method.

This property can be used for subobject restriction by specifying it in the SSubRestriction structure. This enables a client to limit the view of a container to messages with recipients meeting given criteria. A message qualifies for viewing if at least one row in its recipient table, that is, one recipient satisfies the subobject restriction.

Note Using subobject restriction results is the equivalent of an IMAPISession::OpenEntry call on every message in the table. Depending on the client application and the number of messages to be searched, it can affect performance.

The PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property and this property are similar in usage. Several MAPI properties provide access to tables:

Property | Table
PR_CONTAINER_CONTENTS (PidTagContainerContents) | Contents table
PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) | Hierarchy table
PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) | Associated contents table
PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) | Attachment table
PR_MESSAGE_RECIPIENTS | Recipient table

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageSecurityLabel Canonical Property

 Copy code hover
[image]

PidTagMessageSecurityLabel Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a security label for a message.

Associated properties: | PR_MESSAGE_SECURITY_LABEL
Identifier: | 0x001E
Data type: | PT_BINARY
Area: | Server

Remarks

This property provides the basis on which the PR_MESSAGE_TOKEN (PidTagMessageToken) property protects a message. Its association with the message content is guaranteed by the token.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageSize Canonical Property

 Copy code hover
[image]

PidTagMessageSize Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the sum, in bytes, of the sizes of all properties on a message object.

Associated properties: | PR_MESSAGE_SIZE
Identifier: | 0x0E08
Data type: | PT_LONG
Area: | General messaging

Remarks

It is recommended that message objects expose this property. The message size indicates the approximate number of bytes that are transferred when the message is moved from one message store to another. Being the sum of the sizes of all properties on the message object, it is usually considerably greater than the message text alone.

Most message store providers compute this property for messages that they handle. However, some message store providers do not support this property. In any case, this property is not available until the IMAPIProp::SaveChanges or IMessage::SubmitMessage method has been called.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageSizeExtended Canonical Property

 Copy code hover
[image]

PidTagMessageSizeExtended Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a 64 bit integer version of the PR_MESSAGE_SIZE (PidTagMessageSize) property.

Associated properties: | PR_MESSAGE_SIZE_EXTENDED
Identifier: | 0x0E08
Data type: | PT_I8
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagMessageSize Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageStatus Canonical Property

 Copy code hover
[image]

PidTagMessageStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a 32-bit bitmask of flags that defines the status of a message in a contents table.

Associated properties: | PR_MSG_STATUS
Identifier: | 0x0E17
Data type: | PT_LONG
Area: | General messaging

Remarks

A message can exist in a contents table and in one or more search-results tables, and each instance of the message can have a different status. This property should not be considered a property on a message but a column in a contents table.

A client application can set one or more of the following flags in this property:

MSGSTATUS_ANSWERED

The message has been replied to.

MSGSTATUS_DELMARKED

The message has been marked for subsequent deletion.

MSGSTATUS_DRAFT

The message is in draft revision status.

MSGSTATUS_HIDDEN

The message is to be suppressed from recipients' folder displays.

MSGSTATUS_HIGHLIGHTED

The message is to be highlighted in recipients' folder displays.

MSGSTATUS_REMOTE_DELETE

The message has been marked for deletion at the remote message store without downloading to the local client.

MSGSTATUS_REMOTE_DOWNLOAD

The message has been marked for downloading from the remote message store to the local client.

MSGSTATUS_TAGGED

The message has been tagged for a client-defined purpose.

The MSGSTATUS_DELMARKED, MSGSTATUS_HIDDEN, MSGSTATUS_HIGHLIGHTED, and MSGSTATUS_TAGGED flags are defined by the client. Transport and store providers pass these bits without any action.

Clients can interpret these values in any way that is appropriate for their applications. One way that many clients use this property is to display messages marked for deletion with a representative icon.

A remote viewer client can set MSGSTATUS_REMOTE_DELETE or MSGSTATUS_REMOTE_DOWNLOAD on messages in the header folder presented to it by the remote transport provider. The client application can examine each message header in this folder to determine whether the message should be downloaded or deleted at the remote message store. It then uses the IMAPIFolder::SetMessageStatus method to set the appropriate flag. SetMessageStatus is the only way to set any of the flags in this property; the IMAPIProp::SetProps method cannot be used. To retrieve this property, clients call IMAPIFolder::GetMessageStatus rather than IMAPIProp::GetProps.

Bits 16 through 31 (0x10000 through 0x80000000) of this property are available for use by the interpersonal message (IPM) client application. All other bits are reserved for use by MAPI; those not defined in the preceding table should be initially set to zero and not altered subsequently.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMAPITable::QueryRows

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageSubmissionId Canonical Property

 Copy code hover
[image]

PidTagMessageSubmissionId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message transfer system (MTS) identifier for the message transfer agent (MTA).

Associated properties: | PR_MESSAGE_SUBMISSION_ID
Identifier: | 0x0047
Data type: | PT_BINARY
Area: | Email

Remarks

This property is returned by the MTA upon successful completion of message submission. Any future contact with the MTA regarding this message, such as requesting cancellation, uses the MTS identifier in this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageToken Canonical Property

 Copy code hover
[image]

PidTagMessageToken Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 security token for a message.

Associated properties: | PR_MESSAGE_TOKEN
Identifier: | 0x0C03
Data type: | PT_BINARY
Area: | Secure Messaging Properties

Remarks

This property conveys protected security-related information from its originator to its recipient. In conjunction with the PR_MESSAGE_SECURITY_LABEL (PidTagMessageSecurityLabel) property, it guarantees the label's association with the message content. In conjunction with the PR_CONTENT_INTEGRITY_CHECK (PidTagContentIntegrityCheck) property, it verifies that the message content is unchanged.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMessageToMe Canonical Property

 Copy code hover
[image]

PidTagMessageToMe Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if this messaging user is specifically named as a primary (To) recipient of this message and is not part of a distribution list.

Associated properties: | PR_MESSAGE_TO_ME
Identifier: | 0x0057
Data type: | PT_BOOLEAN
Area: | General messaging

Remarks

This property provides a convenient way to determine whether the user name appears explicitly in the primary recipient list, without examining all entries in the list.

This property also assists automated handling of received messages at the time of receipt. At the transport provider's option, this property either contains FALSE or is not included if the messaging user is not listed directly in the recipient table.

Message delivery resulting from distribution list expansion or a blind carbon copy designation does not cause this property to be set. The recipient must be explicitly named.

Unsent messages generally do not set the PR_MESSAGE_CC_ME (PidTagMessageCcMe), PR_MESSAGE_RECIP_ME (PidTagMessageRecipientMe), or this property. If they are present in messages the user can access in public message stores, in other users' private stores, in files on disk, or embedded inside other received messages, they generally contain the values to which they were set the last time a transport provider delivered the message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMiddleName Canonical Property

 Copy code hover
[image]

PidTagMiddleName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the middle name of a contact.

Associated properties: | PR_MIDDLE_NAME, PR_MIDDLE_NAME_A, PR_MIDDLE_NAME_W
Identifier: | 0x3A44
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMiniIcon Canonical Property

 Copy code hover
[image]

PidTagMiniIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmap of a half-size icon for a form.

Associated properties: | PR_MINI_ICON
Identifier: | 0x0FFC
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property contains a 32 × 32 pixel image of an icon, the same as the contents of a .ICO file, but only the upper left 16 × 16 pixels are considered significant. This property is normally copied from the .ICO file specified in the SmallIcon line of the appropriate [Description] section of the form configuration file.

Note Some platforms do not support 16 × 16 pixel icons. The 32 × 32 format of this property is usable in such a case but client applications should be aware of display inconsistencies.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagIcon Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagMobileTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagMobileTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's cellular telephone number.

Associated properties: | PR_MOBILE_TELEPHONE_NUMBER, PR_MOBILE_TELEPHONE_NUMBER_A, PR_MOBILE_TELEPHONE_NUMBER_W, PR_CELLULAR_TELEPHONE_NUMBER, PR_CELLULAR_TELEPHONE_NUMBER_A, PR_CELLULAR_TELEPHONE_NUMBER_W
Identifier: | 0x3A1C
Data type: | PT_UNICODE, PT_STRING8
Area: | Address book

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNextSendAcct Canonical Property

 Copy code hover
[image]

PidTagNextSendAcct Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the server that a client is currently attempting to use to send e-mail.

Associated properties: | PR_NEXT_SEND_ACCT
Identifier: | 0x0E29
Data type: | PT_UNICODE
Area: | Outlook application

Remarks

The format of this property is implementation dependent. This property can be used by the client to determine which server to direct the e-mail to, but is optional and the value has no meaning to the server.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNickname Canonical Property

 Copy code hover
[image]

PidTagNickname Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the nickname of the contact.

Associated properties: | PR_NICKNAME, PR_NICKNAME_A, PR_NICKNAME_W
Identifier: | 0x3A4F
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are optional. Their contents are defined by the user.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonDeliveryReportDiagCode Canonical Property

 Copy code hover
[image]

PidTagNonDeliveryReportDiagCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a diagnostic code that forms part of a nondelivery report.

Associated properties: | PR_NDR_DIAG_CODE
Identifier: | 0x0C05
Data type: | PT_LONG
Area: | General messaging

Remarks

This property can have exactly one of the following values:

MAPI_DIAG_ALPHABETIC_CHARACTER_LOST

MAPI_DIAG_CONTENT_SYNTAX_IN_ERROR

MAPI_DIAG_CONTENT_TOO_LONG

MAPI_DIAG_CONTENT_TYPE_UNSUPPORTED

MAPI_DIAG_CONVERSION_LOSS_PROHIB

MAPI_DIAG_CONVERSION_UNSUBSCRIBED

MAPI_DIAG_CRITICAL_FUNC_UNSUPPORTED

MAPI_DIAG_EITS_UNSUPPORTED

MAPI_DIAG_EXPANSION_FAILED

MAPI_DIAG_EXPANSION_PROHIBITED

MAPI_DIAG_IMPRACTICAL_TO_CONVERT

MAPI_DIAG_LENGTH_CONSTRAINT_VIOLATD

MAPI_DIAG_LINE_TOO_LONG

MAPI_DIAG_LOOP_DETECTED

MAPI_DIAG_MAIL_ADDRESS_INCOMPLETE

MAPI_DIAG_MAIL_ADDRESS_INCORRECT

MAPI_DIAG_MAIL_FORWARDING_PROHIB

MAPI_DIAG_MAIL_FORWARDING_UNWANTED

MAPI_DIAG_MAIL_NEW_ADDRESS_UNKNOWN

MAPI_DIAG_MAIL_OFFICE_INCOR_OR_INVD

MAPI_DIAG_MAIL_ORGANIZATION_EXPIRED

MAPI_DIAG_MAIL_RECIPIENT_DECEASED

MAPI_DIAG_MAIL_RECIPIENT_DEPARTED

MAPI_DIAG_MAIL_RECIPIENT_MOVED

MAPI_DIAG_MAIL_RECIPIENT_TRAVELLING

MAPI_DIAG_MAIL_RECIPIENT_UNKNOWN

MAPI_DIAG_MAIL_REFUSED

MAPI_DIAG_MAIL_UNCLAIMED

MAPI_DIAG_MAXIMUM_TIME_EXPIRED

MAPI_DIAG_MTS_CONGESTED

MAPI_DIAG_MULTIPLE_INFO_LOSSES

MAPI_DIAG_NO_BILATERAL_AGREEMENT

MAPI_DIAG_NO_DIAGNOSTIC

MAPI_DIAG_NUMBER_CONSTRAINT_VIOLATD

MAPI_DIAG_OR_NAME_AMBIGUOUS

MAPI_DIAG_OR_NAME_UNRECOGNIZED

MAPI_DIAG_PAGE_TOO_LONG

MAPI_DIAG_PARAMETERS_INVALID

MAPI_DIAG_PICTORIAL_SYMBOL_LOST

MAPI_DIAG_PROHIBITED_TO_CONVERT

MAPI_DIAG_PUNCTUATION_SYMBOL_LOST

MAPI_DIAG_REASSIGNMENT_PROHIBITED

MAPI_DIAG_RECIPIENT_UNAVAILABLE

MAPI_DIAG_REDIRECTION_LOOP_DETECTED

MAPI_DIAG_RENDITION_UNSUPPORTED

MAPI_DIAG_SECURE_MESSAGING_ERROR

MAPI_DIAG_SUBMISSION_PROHIBITED

MAPI_DIAG_TOO_MANY_RECIPIENTS

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagNonDeliveryReportReasonCode Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonDeliveryReportFromEntryId Canonical Property

 Copy code hover
[image]

PidTagNonDeliveryReportFromEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

If set on a nondelivery report, denotes the entry ID of the failed Send-As user.

Associated properties: | PR_NDR_FROM_ENTRYID
Identifier: | 0x6904
Data type: | PT_BINARY
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonDeliveryReportFromName Canonical Property

 Copy code hover
[image]

PidTagNonDeliveryReportFromName Canonical Property
See also Send feedback

Published: July 16, 2012

If set on a nondelivery report, denotes the name of the failed Send-As user.

Associated properties: | PR_NDR_FROM_NAME
Identifier: | 0x6905
Data type: | PT_STRING8
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonDeliveryReportFromSearchKey Canonical Property

 Copy code hover
[image]

PidTagNonDeliveryReportFromSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

If set on a nondelivery report, denotes the search key of the failed Send-As user.

Associated properties: | PR_NDR_FROM_SEARCH_KEY
Identifier: | 0x6906
Data type: | PT_BINARY
Area: | General messaging

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonDeliveryReportReasonCode Canonical Property

 Copy code hover
[image]

PidTagNonDeliveryReportReasonCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a diagnostic code that forms part of a nondelivery report.

Associated properties: | PR_NDR_REASON_CODE
Identifier: | 0x0C04
Data type: | PT_LONG
Area: | General messaging

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonIpmSubtreeEntryId Canonical Property

 Copy code hover
[image]

PidTagNonIpmSubtreeEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Shows the entry ID of the NON_IPM_SUBTREE folder in an Exchange Public Folder store.

Associated properties: | PR_NON_IPM_SUBTREE_ENTRYID
Identifier: | 0x6620
Data type: | PT_BINARY
Area: | Message store

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonReceiptNotificationRequested Canonical Property

 Copy code hover
[image]

PidTagNonReceiptNotificationRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender wants notification of non-receipt for a specified recipient.

Associated properties: | PR_NON_RECEIPT_NOTIFICATION_REQUESTED
Identifier: | 0x0C06
Data type: | PT_BOOLEAN
Area: | Exchange

Remarks

If this property contains FALSE and the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property contains TRUE, the service provider can override the PR_NON_RECEIPT_NOTIFICATION_REQUESTED property and generate a non-delivery report.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNonReceiptReason Canonical Property

 Copy code hover
[image]

PidTagNonReceiptReason Canonical Property
See also Send feedback

Published: July 16, 2012

Contains reasons why a message was not received that forms part of a non-delivery report.

Associated properties: | PR_NON_RECEIPT_REASON
Identifier: | 0x003E
Data type: | PT_LONG
Area: | Exchange

Remarks

Reasons can include, for example, that the message was discarded.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNormalizedSubject Canonical Property

 Copy code hover
[image]

PidTagNormalizedSubject Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message subject with any prefix removed.

Associated properties: | PR_NORMALIZED_SUBJECT, PR_NORMALIZED_SUBJECT_A, PR_NORMALIZED_SUBJECT_W
Identifier: | 0x0E1D
Data type: | PT_STRING8, PT_UNICODE
Area: | E-mail

Remarks

These properties are computed by message store or transport providers from the PR_SUBJECT (PidTagSubject) and PR_SUBJECT_PREFIX (PidTagSubjectPrefix) properties in the following manner.

  • If the PR_SUBJECT_PREFIX is present and is an initial substring of PR_SUBJECT, PR_NORMALIZED_SUBJECT and associated properties are set to the contents of PR_SUBJECT with the prefix removed.

  • If PR_SUBJECT_PREFIX is present, but it is not an initial substring of PR_SUBJECT, PR_SUBJECT_PREFIX is deleted and recalculated from PR_SUBJECT using the following rule: If the string contained in PR_SUBJECT begins with one to three non-numeric characters followed by a colon and a space, then the string together with the colon and the blank becomes the prefix. Numbers, blanks, and punctuation characters are not valid prefix characters.

  • If PR_SUBJECT_PREFIX is not present, it is calculated from PR_SUBJECT using the rule outlined in the previous step. This property then is set to the contents of PR_SUBJECT with the prefix removed.

Note When PR_SUBJECT_PREFIX is an empty string, PR_SUBJECT and this property are the same.

Ultimately, this property should be the part of PR_SUBJECT following the prefix. If there is no prefix, this property becomes the same as PR_SUBJECT.

PR_SUBJECT_PREFIX and this property should be computed as part of the IMAPIProp::SaveChanges implementation. A client application should not prompt the IMAPIProp::GetProps method for their values until they have been committed by an IMAPIProp::SaveChanges call.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the Object Linking and Embedding (OLE) IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagNull Canonical Property

 Copy code hover
[image]

PidTagNull Canonical Property
See also Send feedback

Published: July 16, 2012

Represents a null value or setting of a property or reserves array space.

Associated properties: | PR_NULL
Identifier: | 0x0000
Data type: | PT_NULL
Area: | Common

Remarks

This property is used to reserve space in arrays of SPropValue structures. It is used in an array of SPropTagArray structures to tell the method to reserve space in the returned array of SPropValue structures. This allows for computed properties to be filled in an inexpensive way.

For more information, see MAPI Property Type Overview.

Related Resources

Protocol Specifications

[MS-OXOCNTC]

Specifies the properties and operations that are permissible on contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagObjectType Canonical Property

 Copy code hover
[image]

PidTagObjectType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the type of an object.

Associated properties: | PR_OBJECT_TYPE
Identifier: | 0x0FFE
Data type: | PT_LONG
Area: | Common

Remarks

The object type contained in this property corresponds to the primary interface available for an object accessible through the OpenEntry interface. It is usually obtained by consulting the lpulObjType parameter returned by the appropriate OpenEntry method. When the interface is obtained in other ways, call IMAPIProp::GetProps to obtain the value for this property.

This property can have exactly one of the following values:

MAPI_ABCONT

Address book container object

MAPI_ADDRBOOK

Address book object

MAPI_ATTACH

Message attachment object

MAPI_DISTLIST

Distribution list object

MAPI_FOLDER

Folder object

MAPI_FORMINFO

Form object

MAPI_MAILUSER

Messaging user object

MAPI_MESSAGE

Message object

MAPI_PROFSECT

Profile section object

MAPI_SESSION

Session object

MAPI_STATUS

Status object

MAPI_STORE

Message store object

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-NSPI]

Handles a client's communications with a Name Service Provider Interface (NSPI) server.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOAB]

Specifies the offline address book (OAB) file formats for the local address book objects cache.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagObsoletedMessageIds Canonical Property

 Copy code hover
[image]

PidTagObsoletedMessageIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the identifiers of messages that this message supersedes.

Associated properties: | PR_OBSOLETED_IPMS
Identifier: | 0x001F
Data type: | PT_BINARY
Area: | Server

Remarks

The identifiers contained in this property are standard search keys using the format of the PR_SEARCH_KEY (PidTagSearchKey) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOfficeLocation Canonical Property

 Copy code hover
[image]

PidTagOfficeLocation Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's office location.

Associated properties: | PR_OFFICE_LOCATION, PR_OFFICE_LOCATION_A, PR_OFFICE_LOCATION_W
Identifier: | 0x3A19
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOrdinalMost Canonical Property

 Copy code hover
[image]

PidTagOrdinalMost Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a positive number whose negative is less than or equal to the value of the dispidTaskOrdinal (PidLidTaskOrdinal) property of all tasks in the folder.

Associated properties: | PR_ORDINAL_MOST
Identifier: | 0x36E2
Data type: | PT_LONG
Area: | Task

Remarks

This property must be updated to maintain this condition whenever the dispidTaskOrdinal property of any task object in the folder changes in a way that would violate the condition.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOrganizationalIdNumber Canonical Property

 Copy code hover
[image]

PidTagOrganizationalIdNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an organizational ID number for the contact, such as an employee ID number.

Associated properties: | PR_ORGANIZATIONAL_ID_NUMBER, PR_ORGANIZATIONAL_ID_NUMBER_A, PR_ORGANIZATIONAL_ID_NUMBER_W
Identifier: | 0x3A10
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These are optional properties. Their use is determined by the messaging user or organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOrgEmailAddress Canonical Property

 Copy code hover
[image]

PidTagOrgEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the email address of the originating email account.

Associated properties: | PR_ORG_EMAIL_ADDRESS, PR_ORG_EMAIL_ADDRESS_A, PR_ORG_EMAIL_ADDRESS_W
Identifier: | TBD
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalAuthorAddressType Canonical Property

 Copy code hover
[image]

PidTagOriginalAuthorAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type of the author of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_AUTHOR_ADDRTYPE, PR_ORIGINAL_AUTHOR_ADDRTYPE_A, PR_ORIGINAL_AUTHOR_ADDRTYPE_W
Identifier: | 0x0079
Data type: | PT_STRING8, PT_UNICODE
Area: | Server

Remarks

These properties are examples of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of the PR_SENDER_ADDRTYPE (PidTagSenderAddressType) property. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalAuthorEmailAddress Canonical Property

 Copy code hover
[image]

PidTagOriginalAuthorEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address of the author of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS, PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_A, PR_ORIGINAL_AUTHOR_EMAIL_ADDRESS_W
Identifier: | 0x007A
Data type: | PT_STRING8, PT_UNICODE
Area: | Server

Remarks

These properties are examples of the address properties for the author of a message. At first submission of the message, the client application should set these properties to the value of the PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress) property. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalAuthorEntryId Canonical Property

 Copy code hover
[image]

PidTagOriginalAuthorEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the author of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_AUTHOR_ENTRYID
Identifier: | 0x004C
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_ENTRYID (PidTagSenderEntryId). It is never changed when the message is forwarded or replied to.

The original author property allows for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, this property provides a way to ensure that original information is not lost.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalAuthorName Canonical Property

 Copy code hover
[image]

PidTagOriginalAuthorName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the author of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_AUTHOR_NAME, PR_ORIGINAL_AUTHOR_NAME_A, PR_ORIGINAL_AUTHOR_NAME_W
Identifier: | 0x004D
Data type: | PT_UNICODE, PT_STRING8
Area: | E-mail

Remarks

These properties are examples of the address properties for the author of a message. At first submission of the message, the client application should set these properties to the value of PR_SENDER_NAME (PidTagSenderName). It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagDisplayName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalAuthorSearchKey Canonical Property

 Copy code hover
[image]

PidTagOriginalAuthorSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key of the author of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_AUTHOR_SEARCH_KEY
Identifier: | 0x0056
Data type: | PT_BINARY
Area: | Server

Remarks

This property is one of the address properties for the author of a message. At first submission of the message, the client application should set this property to the value of the PR_SENDER_SEARCH_KEY PidTagSenderSearchKey property. It is never changed when the message is forwarded or replied to.

The original author properties allow for preservation of information from outside the local messaging domain. When a message arrives from another messaging domain, such as from the Internet, these properties provide a way to ensure that original information is not lost.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalDeliveryTime Canonical Property

 Copy code hover
[image]

PidTagOriginalDeliveryTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a copy of the original message's delivery date and time in a thread.

Associated properties: | PR_ORIGINAL_DELIVERY_TIME
Identifier: | 0x0055
Data type: | PT_SYSTIME
Area: | General messaging

Remarks

This property is copied from the original PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) property in subsequent reply or forward operations and used in read and nonread reports. Delivery reports use the PR_DELIVER_TIME (PidTagDeliverTime) property instead.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalDisplayBcc Canonical Property

 Copy code hover
[image]

PidTagOriginalDisplayBcc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display names of any blind carbon copy (BCC) recipients of the original message.

Associated properties: | PR_ORIGINAL_DISPLAY_BCC, PR_ORIGINAL_DISPLAY_BCC_A, PR_ORIGINAL_DISPLAY_BCC_W
Identifier: | 0x0072
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties contain a list separated by semicolons. They is furnished by MAPI and are copied directly from PR_DISPLAY_BCC (PidTagDisplayBcc) when a delivery or nondelivery report or a read or nonread report is generated. These properties may be present on other messages as defined by their message classes.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalDisplayCc Canonical Property

 Copy code hover
[image]

PidTagOriginalDisplayCc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display names of any carbon copy (CC) recipients of the original message.

Associated properties: | PR_ORIGINAL_DISPLAY_CC, PR_ORIGINAL_DISPLAY_CC_A, PR_ORIGINAL_DISPLAY_CC_W
Identifier: | 0x0073
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties contain a list separated by semicolons. It is furnished by MAPI and is copied directly from PR_DISPLAY_CC (PidTagDisplayCc) when a delivery or nondelivery report or a read or nonread report is generated. This property may be present on other messages as defined by their message classes.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalDisplayName Canonical Property

 Copy code hover
[image]

PidTagOriginalDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the original display name for an entry copied from an address book to a personal address book or other writable address book.

Associated properties: | PR_ORIGINAL_DISPLAY_NAME, PR_ORIGINAL_DISPLAY_NAME_A, PR_ORIGINAL_DISPLAY_NAME_W
Identifier: | 0x3A13
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties contain information about the original source of a copied entry.

For a nonread report, these properties contain a copy of the display name of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the display name of the distribution list is preserved for the report.

A client application can use these properties to prevent alteration or "spoofing" of entries, by giving an unaltered copy of the display name to compare.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagTransmittableDisplayName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalDisplayTo Canonical Property

 Copy code hover
[image]

PidTagOriginalDisplayTo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display names of the primary (To) recipients of the original message.

Associated properties: | PR_ORIGINAL_DISPLAY_TO, PR_ORIGINAL_DISPLAY_TO_A, PR_ORIGINAL_DISPLAY_TO_W
Identifier: | 0x0074
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties contain an ASCII list separated by semicolons. It is furnished by MAPI and is copied directly from PR_DISPLAY_TO (PidTagDisplayTo) when a delivery or nondelivery report or a read or nonread report is generated. This property may be present on other messages as defined by their message classes.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalEits Canonical Property

 Copy code hover
[image]

PidTagOriginalEits Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a copy of the original encoded information types (EITs) for message text.

Associated properties: | PR_ORIGINAL_EITS
Identifier: | 0x0021
Data type: | PT_BINARY
Area: | Server

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalEntryId Canonical Property

 Copy code hover
[image]

PidTagOriginalEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the original entry identifier for an entry copied from an address book to a personal address book or other writeable address book.

Associated properties: | PR_ORIGINAL_ENTRYID
Identifier: | 0x3A12
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the properties that contain information about the original source of a copied entry.

For a nonread report, this property contains a copy of the entry identifier of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the entry identifier of the distribution list is preserved for the report.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginallyIntendedRecipAddrtype Canonical Property

 Copy code hover
[image]

PidTagOriginallyIntendedRecipAddrtype Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type of the originally intended recipient of an autoforwarded message.

Associated properties: | PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE, PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_A, PR_ORIGINALLY_INTENDED_RECIP_ADDRTYPE_W
Identifier: | 0x007B
Data type: | PT_STRING8, PT_UNICODE
Area: | Server

Remarks

These properties are one of the address properties for the originally intended message recipient. It must be set by the automatic agent that has forwarded the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginallyIntendedRecipEmailAddress Canonical Property

 Copy code hover
[image]

PidTagOriginallyIntendedRecipEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address of the originally intended recipient of an autoforwarded message.

Associated properties: | PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS, PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_A, PR_ORIGINALLY_INTENDED_RECIP_EMAIL_ADDRESS_W
Identifier: | 0x007C
Data type: | PT_STRING8, PT_UNICODE
Area: | Server

Remarks

These properties are examples of the address properties for the originally intended message recipient. They must be set by the automatic agent that has forwarded the message.

These properties correspond to the X.400 report per-recipient attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginallyIntendedRecipEntryId Canonical Property

 Copy code hover
[image]

PidTagOriginallyIntendedRecipEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the originally intended recipient of an auto-forwarded message.

Associated properties: | PR_ORIGINALLY_INTENDED_RECIP_ENTRYID
Identifier: | 0x1012
Data type: | PT_BINARY
Area: | Server

Remarks

This property is one of the address properties for the originally intended message recipient. It must be set by the automatic agent that has forwarded the message.

This property corresponds to the X.400 report per-recipient attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginallyIntendedRecipientName Canonical Property

 Copy code hover
[image]

PidTagOriginallyIntendedRecipientName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the encoded name of the originally intended recipient of an autoforwarded message.

Associated properties: | PR_ORIGINALLY_INTENDED_RECIPIENT_NAME
Identifier: | 0x0020
Data type: | PT_BINARY
Area: | Server

Remarks

The PR_ORIGINALLY_INTENDED_RECIPIENT_NAME property must be set by the automatic agent that has forwarded the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalMessageClass Canonical Property

 Copy code hover
[image]

PidTagOriginalMessageClass Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the class of the original message for use in a report.

Associated properties: | PR_ORIG_MESSAGE_CLASS, PR_ORIG_MESSAGE_CLASS_A, PR_ORIG_MESSAGE_CLASS_W
Identifier: | 0x004B
Data type: | PT_STRING8, PT_UNICODE
Area: | Secure Messaging Properties

Remarks

These properties contain a copy of the PR_MESSAGE_CLASS (PidTagMessageClass) property of the message for which the report is being generated.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSearchKey Canonical Property

 Copy code hover
[image]

PidTagOriginalSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the original search key for an entry copied from an address book to a personal address book or other writeable address book.

Associated properties: | PR_ORIGINAL_SEARCH_KEY
Identifier: | 0x3A14
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the properties that contain information about the original source of a copied entry.

For a nonread report, this property contains a copy of the search key of the original message recipient for which the report is generated. When the original recipient is part of a distribution list, the search key of the distribution list is preserved for the report.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSenderAddressType Canonical Property

 Copy code hover
[image]

PidTagOriginalSenderAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENDER_ADDRTYPE, PR_ORIGINAL_SENDER_ADDRTYPE_A, PR_ORIGINAL_SENDER_ADDRTYPE_W
Identifier: | 0x0066
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are examples of the address properties for the original sender of a message. At first submission of the message, the client application should set these properties to the value of PR_SENDER_ADDRTYPE (PidTagSenderAddressType). It is never changed when the message is forwarded or replied to.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSenderEmailAddress Canonical Property

 Copy code hover
[image]

PidTagOriginalSenderEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENDER_EMAIL_ADDRESS, PR_ORIGINAL_SENDER_EMAIL_ADDRESS_A, PR_ORIGINAL_SENDER_EMAIL_ADDRESS_W
Identifier: | 0x0067
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are examples of the address properties for the original sender of a message. At first submission of the message, the client application should set this property to the value of PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress). It is never changed when the message is forwarded or replied to.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSenderEntryId Canonical Property

 Copy code hover
[image]

PidTagOriginalSenderEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENDER_ENTRYID
Identifier: | 0x005B
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the address properties for the original sender of a message. At first submission of the message, a client application should set this property to the value of the PR_SENDER_ENTRYID (PidTagSenderEntryId) property. It is never changed when the message is forwarded or replied to.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSenderName Canonical Property

 Copy code hover
[image]

PidTagOriginalSenderName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the sender of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENDER_NAME, PR_ORIGINAL_SENDER_NAME_A, PR_ORIGINAL_SENDER_NAME_W
Identifier: | 0x005A
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are examples of the address properties for the original sender of a message. At first submission of the message, a client application should set these properties to the value of the PR_SENDER_NAME (PidTagSenderName) property. It is never changed when the message is forwarded or replied to.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSenderSearchKey Canonical Property

 Copy code hover
[image]

PidTagOriginalSenderSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key for the sender of the first version of a message, that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENDER_SEARCH_KEY
Identifier: | 0x005C
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the address properties for the original sender of a message. At first submission of the message, the client application should set this property to the value of the PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) property. It is never changed when the message is forwarded or replied to.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSensitivity Canonical Property

 Copy code hover
[image]

PidTagOriginalSensitivity Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the sensitivity value assigned by the sender of the first version of a message that is, the message before being forwarded or replied to.

Associated properties: | PR_ORIGINAL_SENSITIVITY
Identifier: | 0x002E
Data type: | PT_LONG
Area: | General messaging

Remarks

A client application should set this property to the same value as the PR_SENSITIVITY (PidTagSensitivity) property when the message is first submitted. It should never be changed subsequently.

This property is used by the transport provider to protect the sensitivity on copied entries. It enables it, for example, to block modification of the original message text in a forward of or reply to a message that was originally marked SENSITIVITY_PRIVATE.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSentRepresentingAddressType Canonical Property

 Copy code hover
[image]

PidTagOriginalSentRepresentingAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type of the messaging user on whose behalf the original message was sent.

Associated properties: | PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE, PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_A, PR_ORIGINAL_SENT_REPRESENTING_ADDRTYPE_W
Identifier: | 0x0068
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are the type for the original represented sender of a message. They are used in a conversation thread.

A client application sending a message on behalf of another client should set these properties to the value of the PR_SENT_REPRESENTING_ADDRTYPE (PidTagSentRepresentingAddressType) property at the first submission of the message. Once set, it should never be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSentRepresentingEmailAddress Canonical Property

 Copy code hover
[image]

PidTagOriginalSentRepresentingEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address of the messaging user on whose behalf the original message was sent.

Associated properties: | PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS, PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_A, PR_ORIGINAL_SENT_REPRESENTING_EMAIL_ADDRESS_W
Identifier: | 0x0069
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are examples of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set these properties to the value of the PR_SENT_REPRESENTING_EMAIL_ADDRESS (PidTagSentRepresentingEmailAddress) property at the first submission of the message. Once set, it should never be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSentRepresentingEntryId Canonical Property

 Copy code hover
[image]

PidTagOriginalSentRepresentingEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the messaging user on whose behalf the original message was sent.

Associated properties: | PR_ORIGINAL_SENT_REPRESENTING_ENTRYID
Identifier: | 0x005E
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId) property at the first submission of the message. Once set, it should never be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSentRepresentingName Canonical Property

 Copy code hover
[image]

PidTagOriginalSentRepresentingName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the messaging user on whose behalf the original message was sent.

Associated properties: | PR_ORIGINAL_SENT_REPRESENTING_NAME, PR_ORIGINAL_SENT_REPRESENTING_NAME_A, PR_ORIGINAL_SENT_REPRESENTING_NAME_W
Identifier: | 0x005D
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties examples of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set these properties to the value of the PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) property at the first submission of the message. Once set, it should never be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSentRepresentingSearchKey Canonical Property

 Copy code hover
[image]

PidTagOriginalSentRepresentingSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key of the messaging user on whose behalf the original message was sent.

Associated properties: | PR_ORIGINAL_SENT_REPRESENTING_SEARCH_KEY
Identifier: | 0x005F
Data type: | PT_BINARY
Area: | General messaging

Remarks

This property is one of the address properties for the original represented sender of a message. It is used in a conversation thread.

A client application sending a message on behalf of another client should set this property to the value of the PR_SENT_REPRESENTING_SEARCH_KEY (PidTagSentRepresentingSearchKey) property at the first submission of the message. Once set, it should never be changed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSubject Canonical Property

 Copy code hover
[image]

PidTagOriginalSubject Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the subject of an original message for use in a report about the message.

Associated properties: | PR_ORIGINAL_SUBJECT, PR_ORIGINAL_SUBJECT_A, PR_ORIGINAL_SUBJECT_W
Identifier: | 0x0049
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are originally set to the same value as the PR_SUBJECT (PidTagSubject) property.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the Object Linking and Embedding (OLE) IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles synchronizing messaging object data between a server and a client.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginalSubmitTime Canonical Property

 Copy code hover
[image]

PidTagOriginalSubmitTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the original submission date and time of the message in the report.

Associated properties: | PR_ORIGINAL_SUBMIT_TIME
Identifier: | 0x004E
Data type: | PT_SYSTIME
Area: | General messaging

Remarks

At first submission of a message, a client application should set this property to the value of the PR_CLIENT_SUBMIT_TIME (PidTagClientSubmitTime) property. It is not changed when the message is forwarded. This is used in reports only.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatingMtaCertificate Canonical Property

 Copy code hover
[image]

PidTagOriginatingMtaCertificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for the message transfer agent (MTA) that originated the message.

Associated properties: | PR_ORIGINATING_MTA_CERTIFICATE
Identifier: | 0x0E25
Data type: | PT_BINARY
Area: | Server

Remarks

This property, if set, is available on sent messages in the Sent Items folder.

This property corresponds to the X.400 report per-message attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorAndDistributionListExpansionHistory Canonical Property

 Copy code hover
[image]

PidTagOriginatorAndDistributionListExpansionHistory Canonical Property
See also Send feedback

Published: July 16, 2012

Contains information about a message originator and a distribution list expansion history.

Associated properties: | PR_ORIGINATOR_AND_DL_EXPANSION_HISTORY
Identifier: | 0x1002
Data type: | PT_BINARY
Area: | MIME

Remarks

This property is used in report generation.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorCertificate Canonical Property

 Copy code hover
[image]

PidTagOriginatorCertificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 certificate for the message originator.

Associated properties: | PR_ORIGINATOR_CERTIFICATE
Identifier: | 0x0022
Data type: | PT_BINARY
Area: | MIME

Remarks

This property is a copy of the originator's PR_USER_CERTIFICATE (PidTagUserCertificate) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorDeliveryReportRequested Canonical Property

 Copy code hover
[image]

PidTagOriginatorDeliveryReportRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender requests a delivery report for a particular recipient from the messaging system before the message is placed in the message store.

Associated properties: | PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED
Identifier: | 0x0023
Data type: | PT_BOOLEAN
Area: | MIME

Remarks

This property is used to direct the messaging system in handling delivered messages. In this case, the message must also furnish the PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED (PidTagOriginatorNonDeliveryReportRequested) property set to FALSE.

Setting the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED property on a message is a way to request delivery status reports for all recipients.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorNonDeliveryReportRequested Canonical Property

 Copy code hover
[image]

PidTagOriginatorNonDeliveryReportRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender requests a nondelivery report for a particular recipient.

Associated properties: | PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED
Identifier: | 0x0C08
Data type: | PT_BOOLEAN
Area: | MIME

Remarks

This property is used to direct the messaging system in handling undelivered messages. In this case, the message must also furnish the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) property set to FALSE.

Related Resources

Protocol Specifications

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorRequestedAlternateRecipient Canonical Property

 Copy code hover
[image]

PidTagOriginatorRequestedAlternateRecipient Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an entry identifier for an alternate recipient designated by the sender.

Associated properties: | PR_ORIGINATOR_REQUESTED_ALTERNATE_RECIPIENT
Identifier: | 0x0C09
Data type: | PT_BINARY
Area: | MIME

Remarks

This property is used in autoforwarded messages. If autoforwarding is not permitted or if no alternate recipient has been designated, a nondelivery report should be generated.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginatorReturnAddress Canonical Property

 Copy code hover
[image]

PidTagOriginatorReturnAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the binary-encoded return address of the message originator.

Associated properties: | PR_ORIGINATOR_RETURN_ADDRESS
Identifier: | 0x0024
Data type: | PT_BINARY
Area: | MIME

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOriginCheck Canonical Property

 Copy code hover
[image]

PidTagOriginCheck Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a binary verification value that enables a delivery report recipient to verify the origin of the original message.

Associated properties: | PR_ORIGIN_CHECK
Identifier: | 0x0027
Data type: | PT_BINARY
Area: | Server

Remarks

This property provides a means for a third party, such as a message transfer agent (MTA) or a messaging user receiving a delivery report, to verify the submitted message's origin. If present on a received message, this property should be copied onto any delivery report generated in response to the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressCity Canonical Property

 Copy code hover
[image]

PidTagOtherAddressCity Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the mail user's other locality, such as the town or city.

Associated properties: | PR_OTHER_ADDRESS_CITY, PR_OTHER_ADDRESS_CITY_A, PR_OTHER_ADDRESS_CITY_W
Identifier: | 0x3A5F
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressCountry Canonical Property

 Copy code hover
[image]

PidTagOtherAddressCountry Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the mail user's other country/region.

Associated properties: | PR_OTHER_ADDRESS_COUNTRY, PR_OTHER_ADDRESS_COUNTRY_A, PR_OTHER_ADDRESS_COUNTRY_W
Identifier: | 0x3A60
Data type: | PT_UNICODE, PT_STRING8
Area: | Address book

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressPostalCode Canonical Property

 Copy code hover
[image]

PidTagOtherAddressPostalCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the postal code for the mail user's other postal address.

Associated properties: | PR_OTHER_ADDRESS_POSTAL_CODE, PR_OTHER_ADDRESS_POSTAL_CODE_A, PR_OTHER_ADDRESS_POSTAL_CODE_W
Identifier: | 0x3A61
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressPostOfficeBox Canonical Property

 Copy code hover
[image]

PidTagOtherAddressPostOfficeBox Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the post office box for a contact's other address.

Associated properties: | PR_OTHER_ADDRESS_POST_OFFICE_BOX, PR_OTHER_ADDRESS_POST_OFFICE_BOX_A, PR_OTHER_ADDRESS_POST_OFFICE_BOX_W
Identifier: | 0x3A64
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressStateOrProvince Canonical Property

 Copy code hover
[image]

PidTagOtherAddressStateOrProvince Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of state or province used in the other address.

Associated properties: | PR_OTHER_ADDRESS_STATE_OR_PROVINCE, PR_OTHER_ADDRESS_STATE_OR_PROVINCE_A, PR_OTHER_ADDRESS_STATE_OR_PROVINCE_W
Identifier: | 0x3A62
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherAddressStreet Canonical Property

 Copy code hover
[image]

PidTagOtherAddressStreet Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the mail user's other street address.

Associated properties: | PR_OTHER_ADDRESS_STREET, PR_OTHER_ADDRESS_STREET_A, PR_OTHER_ADDRESS_STREET_W
Identifier: | 0x3A63
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOtherTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagOtherTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an alternate telephone number for the recipient.

Associated properties: | PR_OTHER_TELEPHONE_NUMBER, PR_OTHER_TELEPHONE_NUMBER_A, PR_OTHER_TELEPHONE_NUMBER_W
Identifier: | 0x3A1F
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

These properties are used for a telephone number other than at the recipient's place of business, home, or office.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations that are permissible for address book templates.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOwnerAppointmentId Canonical Property

 Copy code hover
[image]

PidTagOwnerAppointmentId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for an appointment in the owner's schedule.

Associated properties: | PR_OWNER_APPT_ID
Identifier: | 0x0062
Data type: | PT_LONG
Area: | Appointment

Remarks

This property is used in meeting requests. It does not represent an entry identifier, but a long integer that uniquely identifies the appointment within the sender's schedule.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagOriginalAuthorSearchKey Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagOwnStoreEntryId Canonical Property

 Copy code hover
[image]

PidTagOwnStoreEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of a transport's tightly coupled message store.

Associated properties: | PR_OWN_STORE_ENTRYID
Identifier: | 0x3E06
Data type: | PT_BINARY
Area: | Message Store Properties

Remarks

This property specifies the entry identifier for the tightly coupled store, if one exists. For example, a transport provider can specify the private folder store entry identifier so that the MAPI spooler can connect the transport provider to the store.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPagerTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagPagerTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's pager telephone number.

Associated properties: | PR_PAGER_TELEPHONE_NUMBER, PR_PAGER_TELEPHONE_NUMBER_A, PR_PAGER_TELEPHONE_NUMBER_W, PR_BEEPER_TELEPHONE_NUMBER, PR_BEEPER_TELEPHONE_NUMBER_A, PR_BEEPER_TELEPHONE_NUMBER_W
Identifier: | 0x3A21
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagParentDisplay Canonical Property

 Copy code hover
[image]

PidTagParentDisplay Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the folder where a message was found during a search.

Associated properties: | PR_PARENT_DISPLAY, PR_PARENT_DISPLAY_A, PR_PARENT_DISPLAY_W
Identifier: | 0x0E05
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI non-transmittable

Remarks

These properties is not on any object. They can only appear in the contents table of a search-results folder.

These properties and PR_PARENT_ENTRYID (PidTagParentEntryId) properties are not related to each other. They belong to entirely different contexts.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagParentEntryId Canonical Property

 Copy code hover
[image]

PidTagParentEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the folder that contains a folder or message.

Associated properties: | PR_PARENT_ENTRYID
Identifier: | 0x0E09
Data type: | PT_BINARY
Area: | ID properties

Remarks

This property is computed by message stores for all folders and messages.

For a message store root folder, this property contains the folder's own entry identifier.

PR_PARENT_DISPLAY (PidTagParentDisplay) and this property are not related to each other. They belong to entirely different contexts.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCDATA]

Defines the basic data structures that are used in remote operations.

[MS-OXCFOLD]

Handles folder operations.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

[MS-OXPFOAB]

Specifies the method of delivering offline address book (OAB) data from server to client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagFolderType Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPersonalHomePage Canonical Property

 Copy code hover
[image]

PidTagPersonalHomePage Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the URL of a user's personal home page.

Associated properties: | PR_PERSONAL_HOME_PAGE, PR_PERSONAL_HOME_PAGE_A, PR_PERSONAL_HOME_PAGE_W
Identifier: | 0x3A50
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalDeliveryBureauFaxDelivery Canonical Property

 Copy code hover
[image]

PidTagPhysicalDeliveryBureauFaxDelivery Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the messaging system should use a fax bureau for physical delivery of this message.

Associated properties: | PR_PHYSICAL_DELIVERY_BUREAU_FAX_DELIVERY
Identifier: | 0x0C0A
Data type: | PT_BOOLEAN
Area: | MAPI recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalDeliveryMode Canonical Property

 Copy code hover
[image]

PidTagPhysicalDeliveryMode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that define the physical delivery mode (for example, special delivery) for a message designated for a specific recipient.

Associated properties: | PR_PHYSICAL_DELIVERY_MODE
Identifier: | 0x0C0B
Data type: | PT_LONG
Area: | MAPI recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalDeliveryReportRequest Canonical Property

 Copy code hover
[image]

PidTagPhysicalDeliveryReportRequest Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the mode of a report to be delivered to a particular message recipient upon completion of physical message delivery or delivery by the message handling system.

Associated properties: | PR_PHYSICAL_DELIVERY_REPORT_REQUEST
Identifier: | 0x0C0C
Data type: | PT_LONG
Area: | MAPI recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalForwardingAddress Canonical Property

 Copy code hover
[image]

PidTagPhysicalForwardingAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the physical forwarding address of a message recipient and is used only with message reports.

Associated properties: | PR_PHYSICAL_FORWARDING_ADDRESS
Identifier: | 0x0C0D
Data type: | PT_BINARY
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalForwardingAddressRequested Canonical Property

 Copy code hover
[image]

PidTagPhysicalForwardingAddressRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender requests the message transfer agent to attach a physical forwarding address for a message recipient.

Associated properties: | PR_PHYSICAL_FORWARDING_ADDRESS_REQUESTED
Identifier: | 0x0C0E
Data type: | PT_BOOLEAN
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalForwardingProhibited Canonical Property

 Copy code hover
[image]

PidTagPhysicalForwardingProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender prohibits physical message forwarding for a specific recipient.

Associated properties: | PR_PHYSICAL_FORWARDING_PROHIBITED
Identifier: | 0x0C0F
Data type: | PT_BOOLEAN
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPhysicalRenditionAttributes Canonical Property

 Copy code hover
[image]

PidTagPhysicalRenditionAttributes Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 object identifier that is used for rendering message attachments.

Associated properties: | PR_PHYSICAL_RENDITION_ATTRIBUTES
Identifier: | 0x0C10
Data type: | PT_BINARY
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPostalAddress Canonical Property

 Copy code hover
[image]

PidTagPostalAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's postal address.

Associated properties: | PR_POSTAL_ADDRESS, PR_POSTAL_ADDRESS_A, PR_POSTAL_ADDRESS_W
Identifier: | 0x3A15
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPostalCode Canonical Property

 Copy code hover
[image]

PidTagPostalCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the postal code for the recipient's postal address.

Associated properties: | PR_POSTAL_CODE, PR_POSTAL_CODE_A, PR_POSTAL_CODE_W, PR_BUSINESS_ADDRESS_POSTAL_CODE, PR_BUSINESS_ADDRESS_POSTAL_CODE_A, PR_BUSINESS_ADDRESS_POSTAL_CODE_W
Identifier: | 0x3A2A
Data type: | PT_UNICODE, PT_STRING8
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

The postal code is specific to the recipient's country/region. In the United States of America, this property contains the ZIP code.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPostOfficeBox Canonical Property

 Copy code hover
[image]

PidTagPostOfficeBox Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the number or identifier of the recipient's post office box.

Associated properties: | PR_POST_OFFICE_BOX, PR_POST_OFFICE_BOX_A, PR_POST_OFFICE_BOX_W, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_A, PR_BUSINESS_ADDRESS_POST_OFFICE_BOX_W
Identifier: | 0x3A2B
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPreferredByName Canonical Property

 Copy code hover
[image]

PidTagPreferredByName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name that the recipient prefers to be called.

Associated properties: | PR_PREFERRED_BY_NAME, PR_PREFERRED_BY_NAME_A, PR_PREFERRED_BY_NAME_W
Identifier: | 0x3A47
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPreprocess Canonical Property

 Copy code hover
[image]

PidTagPreprocess Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the message requires preprocessing.

Associated properties: | PR_PREPROCESS
Identifier: | 0x0E22
Data type: | PT_BOOLEAN
Area: | MAPI non-transmittable

Remarks

Important note Important

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagSubmitFlags Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPrimaryFaxNumber Canonical Property

 Copy code hover
[image]

PidTagPrimaryFaxNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the telephone number of the recipient's primary fax machine.

Associated properties: | PR_PRIMARY_FAX_NUMBER, PR_PRIMARY_FAX_NUMBER_A, PR_PRIMARY_FAX_NUMBER_W
Identifier: | 0x3A23
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and their organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPrimarySendAccount Canonical Property

 Copy code hover
[image]

PidTagPrimarySendAccount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a string that names the first server that is used to send the message.

Associated properties: | PR_PRIMARY_SEND_ACCOUNT
Identifier: | 0x0E28
Data type: | PT_UNICODE
Area: | Account

Remarks

Specifies the first server that a client should use to send the mail. The format of these properties is implementation dependent. These properties can be used by the client to determine which server to direct the mail through, but is optional and the value has no meaning to the server.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPrimaryTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagPrimaryTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's primary telephone number.

Associated properties: | PR_PRIMARY_TELEPHONE_NUMBER, PR_PRIMARY_TELEPHONE_NUMBER_A, PR_PRIMARY_TELEPHONE_NUMBER_W
Identifier: | 0x3A1A
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are examples of the properties that provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPriority Canonical Property

 Copy code hover
[image]

PidTagPriority Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the relative priority of a message.

Associated properties: | PR_PRIORITY
Identifier: | 0x0026
Data type: | PT_LONG
Area: | E-mail

Remarks

This property and the PR_IMPORTANCE (PidTagImportance) property should not be confused. Importance indicates a value to users, while priority indicates the order or speed at which the message should be sent by the messaging system software. Higher priority usually indicates a higher cost. Higher importance usually is associated with a different display by the user interface.

The priority of a report message should be the same as the priority of the original message being reported.

This property can have exactly one of the following values:

PRIO_NONURGENT

The message is not urgent.

PRIO_NORMAL

The message has normal priority.

PRIO_URGENT

The message is urgent.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProcessed Canonical Property

 Copy code hover
[image]

PidTagProcessed Canonical Property
See also Send feedback

Published: July 16, 2012

Set to TRUE when the meeting request has been processed.

Associated properties: | PR_PROCESSED
Identifier: | 0x7D01
Data type: | PT_BOOLEAN
Area: | Calendar

Remarks

This property ensures that meeting requests get processed once. The creator of the request should set this property to FALSE and the receiver should set it to TRUE once the request is in the calendar.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfession Canonical Property

 Copy code hover
[image]

PidTagProfession Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the profession of the user.

Associated properties: | PR_PROFESSION, PR_PROFESSION_A, PR_PROFESSION_W
Identifier: | 0x3A46
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfileHomeServerFQDN Canonical Property

 Copy code hover
[image]

PidTagProfileHomeServerFQDN Canonical Property
See also Send feedback

Published: July 16, 2012

Enables Kerberos authentication of a profile configuration.

Associated properties: | PR_PROFILE_HOME_SERVER_FQDN
Identifier: | 0x662A001F
Data type: | PT_UNICODE
Area: | MAPI profile configuration

Remarks

Setting this property to the Domain Name of the user's directory server allows direct connection to the Domain Controller (DC), which is necessary for a profile that has been configured to use Kerberos authentication against Microsoft Exchange Server 2007 and earlier versions, by setting RPC_C_AUTHN_GSS_KERBEROS in PR_PROFILE_AUTH_PACKAGE.

Note Note

Microsoft Exchange Server 2010 and Exchange Server 2013 handle address book calls made to the Client Access Server differently from the way in which Exchange Server 2007 and earlier versions handle them. The DSProxy process is no longer used, so Kerberos authentication may succeed. However, the client would still be communicating with the Exchange server instead of directly with the DC, which may not be desired: Setting PR_PROFILE_HOME_SERVER_FQDN avoids this.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfileName Canonical Property

 Copy code hover
[image]

PidTagProfileName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the profile.

Associated properties: | PR_PROFILE_NAME, PR_PROFILE_NAME_A, PR_PROFILE_NAME_W
Identifier: | 0x3D12
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI profile configuration

Remarks

These properties are computed by service providers. A provider's implementation of the ServiceEntry function can use these properties to discover the profile name.

Client applications can use these properties as a convenient alternative to obtaining the profile name by examining the PR_DISPLAY_NAME (PidTagDisplayName) property in the MAPI subsystem's status table row.

These properties may not be unique across time, for example where a profile is deleted and later recreated with the same name. MAPI furnishes a totally unique PR_SEARCH_KEY (PidTagSearchKey) property in a hard-coded profile section called MUID_PROFILE_INSTANCE.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfileServerFullVersion Canonical Property

 Copy code hover
[image]

PidTagProfileServerFullVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies complete version and build information about the Exchange Server to which accounts in a profile are connected.

Associated properties: | PR_PROFILE_SERVER_FULL_VERSION
Identifier: | 0x663B
Property type: | PT_BINARY
Area: | MAPI profile configuration

Remarks

A profile can specify one or more accounts that connect to an Exchange Server, but they must be connected to the same Exchange Server.

Versions of Outlook earlier than Microsoft Office Outlook 2007 do not support this property. For those versions of Outlook, check for the existence of PR_PROFILE_SERVER_VERSION in the profile.

Generally, if the active mailbox is connected to an Exchange Server, Outlook 2007 stores complete Exchange Server version information in the PR_PROFILE_SERVER_FULL_VERSION property in the active profile. Outlook stores the information in an EXCHANGE_STORE_VERSION_NUM structure that contains the major and minor version numbers and the major and minor build numbers. For example, to store the Exchange Server version identifier of 8.0.685.24, the major version number is 8 and minor version number is 0, and the major build number is 685 and minor build number is 24.

Only one of PR_PROFILE_SERVER_VERSION or PR_PROFILE_SERVER_FULL_VERSION is likely to exist in a profile, but there is no guarantee that either always exists in a profile. Outlook does not write to either property until it has successfully connected to the Exchange Server.

In the Outlook object model, you can use the ExchangeMailboxServerVersion property of the NameSpace object to find the version of Exchange Server on which the active mailbox is hosted.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfileServerVersion Canonical Property

 Copy code hover
[image]

PidTagProfileServerVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies information about the version of Exchange Server to which accounts in a Microsoft Outlook profile are connected.

Associated properties: | PR_PROFILE_SERVER_VERSION
Identifier: | 0x661B
Property type: | PT_LONG
Area: | MAPI profile configuration

Remarks

A profile can specify one or more accounts that connect to an Exchange Server, but they must be connected to the same Exchange Server.

Versions of Outlook earlier than Microsoft Office Outlook 2007 can write to this property to store information about the version of Exchange Server to which the active profile is connected. However, the format of the version information varies for different versions of Exchange Server. For example, Outlook stores in PR_PROFILE_SERVER_VERSION the decimal value 6944 to represent only the major build number in the version identifier of 6.5.6944.3 for Microsoft Exchange Server 2003. For an Exchange 2007 connection, Outlook stores the major version number and the major build number in a concatenated hexadecimal representation of these numbers in the property. An Exchange 2007 version identifier of 8.0.685.24 has a major version number 8 and a major build number 685 in decimal. Converting both numbers to hexadecimal, you get 0x8 and 0x2AD. Concatenating these two numbers, Outlook stores the value 0x82AD in PR_PROFILE_SERVER_VERSION in hexadecimal representation.

Outlook 2007 does not read or write to this property. It supports PR_PROFILE_SERVER_FULL_VERSION.

Only one of PR_PROFILE_SERVER_VERSION or PR_PROFILE_SERVER_FULL_VERSION is likely to exist in a profile, but there is no guarantee that either always exists in a profile. Outlook does not write to either property until it has successfully connected to the Exchange Server.

In the Outlook object model, you can use the ExchangeMailboxServerVersion property of the NameSpace object to find the version of Exchange Server on which the active mailbox is hosted.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProfileType Canonical Property

 Copy code hover
[image]

PidTagProfileType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the type of information store.

Associated properties: | PR_PROFILE_TYPE
Identifier: | 0x660A
Data type: | PT_LONG
Area: | MAPI profile configuration

Remarks

The possible values for this property are:

  • 1 - Primary user

  • 2 - Delegate

  • 3 - Public store

  • 4 - Subscription

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProofOfDelivery Canonical Property

 Copy code hover
[image]

PidTagProofOfDelivery Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains an ASN.1 proof of delivery value.

Associated properties: | PR_PROOF_OF_DELIVERY
Identifier: | 0x0C11
Data type: | PT_BINARY
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProofOfDeliveryRequested Canonical Property

 Copy code hover
[image]

PidTagProofOfDeliveryRequested Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains TRUE if a message sender requests proof of delivery for a particular recipient.

Associated properties: | PR_PROOF_OF_DELIVERY_REQUESTED
Identifier: | 0x0C12
Data type: | PT_BOOLEAN
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProofOfSubmission Canonical Property

 Copy code hover
[image]

PidTagProofOfSubmission Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains TRUE if a message sender requests proof that the message transfer system has submitted a message for delivery to the originally intended recipient.

Associated properties: | PR_PROOF_OF_SUBMISSION
Identifier: | 0x0E26
Data type: | PT_BINARY
Area: | MAPI Non-transmittable

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProofOfSubmissionRequested Canonical Property

 Copy code hover
[image]

PidTagProofOfSubmissionRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 proof of submission value.

Associated properties: | PR_PROOF_OF_SUBMISSION_REQUESTED
Identifier: | 0x0028
Data type: | PT_BOOLEAN
Area: | MAPI envelope

Remarks

This property corresponds to an X.400 submission envelope per-message attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderDisplay Canonical Property

 Copy code hover
[image]

PidTagProviderDisplay Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the vendor-defined display name for a service provider.

Associated properties: | PR_PROVIDER_DISPLAY, PR_PROVIDER_DISPLAY_A, PR_PROVIDER_DISPLAY_W
Identifier: | 0x3006
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

These properties and PR_PROVIDER_DLL_NAME (PidTagProviderDllName) are defined only on profile sections belonging to service providers. They must be present in MAPISVC.INF.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderDisplayName Canonical Property

 Copy code hover
[image]

PidTagProviderDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of a provider.

Associated properties: | PR_PROVIDER_DISPLAY_NAME, PR_PROVIDER_DISPLAY_NAME_A, PR_PROVIDER_DISPLAY_NAME_W
Identifier: | 0x3418
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI message store

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderDllName Canonical Property

 Copy code hover
[image]

PidTagProviderDllName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the base file name of the MAPI service provider dynamic-link library (DLL).

Associated properties: | PR_PROVIDER_DLL_NAME, PR_PROVIDER_DLL_NAME_A, PR_PROVIDER_DLL_NAME_W
Identifier: | 0x300A
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI common

Remarks

MAPI uses a DLL file naming convention. The base filename contains up to six characters that uniquely identify the DLL. MAPI appends the string 32 to the base DLL name to identify the version that runs on 32-bit platforms. For example, when the name MAPI.DLL is specified, MAPI constructs the name MAPI32.DLL to represent the corresponding 32-bit version of the DLL.

These properties should specify the base name. MAPI appends the string 32 as appropriate. Including the string 32 as part of this property results in an error.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderIcon Canonical Property

 Copy code hover
[image]

PidTagProviderIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Unicode string that specifies a custom icon or icons to be displayed for a MAPI provider in the Microsoft Office Outlook status bar in both online and offline states.

Associated properties: | PR_PROVIDER_ICON, PR_PROVIDER_ICON_W
Identifier: | 0x3417
Data type: | PT_UNICODE
Area: | MAPI message store

Remarks

These properties specify the resource file that contains a custom icon that represents a MAPI provider in an online state, and optionally, another custom icon in the offline state. Outlook always requests these properties in Unicode representation.

For example, the following property value instructs Outlook to load icon ID 1001 from the module mymod32.dll and use that icon for the online state: mymod32.dll,#1001. Since there is no provider-specific icon for the offline state, in this case, the standard Outlook offline icon is used in the status bar.

The following property value instructs Outlook to load icon ID 1001 from the module mymod32.dll and use that icon for the online state, and to also load icon ID 1002 from this same module to be used for the offline state: mymod32.dll,#1001,#1002. No Outlook icon is used in the status bar.

By default, if no custom icons are specified, the provider is represented by the Outlook default icons for the online state and the offline state. The provider can optionally specify a display name to be shown adjacent to the icon in the status bar. For more information, see PR_PROVIDER_DISPLAY_NAME_W (PidTagProviderDisplayName).

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderItemId Canonical Property

 Copy code hover
[image]

PidTagProviderItemId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies an identifier for a folder or an item in a store.

Associated properties: | PR_PROVIDER_ITEMID
Identifier: | 0x0EA3
Data type: | PT_BINARY
Area: | MapiNonTransmittable

Remarks

Store providers can specify a value for this property for a folder or an item, but should keep the value the same between sessions. Store providers use this property to identify search results returned from a search engine.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderOrdinal Canonical Property

 Copy code hover
[image]

PidTagProviderOrdinal Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the zero-based index of a service provider's position in the provider table.

Associated properties: | PR_PROVIDER_ORDINAL
Identifier: | 0x300D
Data type: | PT_LONG
Area: | MAPI common

Remarks

This property is computed by MAPI.

Obtain the provider table by calling the IMsgServiceAdmin::GetProviderTable method. Sort the provider table on this property to display the transport order.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderParentItemId Canonical Property

 Copy code hover
[image]

PidTagProviderParentItemId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies an identifier for the parent of a folder or an item in a store.

Associated properties: | PR_PROVIDER_PARENT_ITEMID
Identifier: | 0x0EA4
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

Store providers can specify a value for this property for a parent of a folder or an item, but should keep the value the same between sessions. Store providers use this property to identify search results returned from a search engine.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderSubmitTime Canonical Property

 Copy code hover
[image]

PidTagProviderSubmitTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time a transport provider passed a message to its underlying messaging system.

Associated properties: | PR_PROVIDER_SUBMIT_TIME
Identifier: | 0x0048
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

This property is set by the outgoing transport provider at the time a message is sent.

This property corresponds to an X.400 submission envelope per-message attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagProviderUid Canonical Property

 Copy code hover
[image]

PidTagProviderUid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a MAPIUID structure of the service provider that is handling a message.

Associated properties: | PR_PROVIDER_UID
Identifier: | 0x300C
Data type: | PT_BINARY
Area: | MAPI common

Remarks

This property is computed by all service providers. It contains a MAPIUID structure associated with, and usually hard-coded by, the provider. It is typically used by a client application that is interested in only the address book containers supplied by a particular provider.

This property appears only as a column entry in the provider table.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstConfigurationFlags Canonical Property

 Copy code hover
[image]

PidTagPstConfigurationFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Specfies configuration flags for a personal storage table (.pst file).

Associated properties: | PR_PST_CONFIG_FLAGS
Identifier: | 0x6770
Data type: | PT_LONG
Area: | Personal storage table (.pst) internal

Remarks

The following are valid values for this property:

PST_CONFIG_UNICODE

Indicates a Unicode .pst file.

#define PST_CONFIG_UNICODE 0x80000000

PST_CONFIG_CREATE_NOWARN

When set from the client flags to the IMsgServiceAdmin::ConfigureMsgService method, treats ConfigureMsgService like a IMsgServiceAdmin::CreateMsgService call and skips the "This information service has not been configured" warning.

#define PST_CONFIG_CREATE_NOWARN 0x00000001

PST_CONFIG_PRESERVE_DISPLAY_NAME

Tells ConfigureMsgService to not change the value of the PR_DISPLAY_NAME (PidTagDisplayName) property, even though it was supplied. In that case, it was supplied only for new .pst files.

#define PST_CONFIG_PRESERVE_DISPLAY_NAME 0x00000002

OST_CONFIG_POLICY_DELAY_IGNORE_OST

Tells the configuration code to first display a dialog box to confirm whether an Offline Folder (.ost) file was found and, depending on the user's response, either use the found Offline Folder or enable the user to browse for another Offline Folder.

#define OST_CONFIG_POLICY_DELAY_IGNORE_OST 0x00000008

OST_CONFIG_CREATE_NEW_DEFAULT

Copies the .ost file with a new unique name and discards the current name. The existing .ost file remains on the computer but is no longer used in this profile. This typically occurs when Microsoft Outlook no longer permits a particular .ost file, and registry policies do not allow the user to rename the file.

#define OST_CONFIG_CREATE_NEW_DEFAULT_OST 0x00000010

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstPasswordSzNew Canonical Property

 Copy code hover
[image]

PidTagPstPasswordSzNew Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the new password to use for future access to the personal folder store.

Associated properties: | PR_PST_PW_SZ_NEW, PR_PST_PW_SZ_NEW_A, PR_PST_PW_SZ_NEW_W
Identifier: | 0x6704
Data type: | PT_STRING8, PT_UNICODE
Area: | Personal storage table (.pst) internal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstPasswordSzOld Canonical Property

 Copy code hover
[image]

PidTagPstPasswordSzOld Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the password of the personal storage table (.pst file) being configured.

Associated properties: | PR_PST_PW_SZ_OLD, PR_PST_PW_SZ_OLD_A, PR_PST_PW_SZ_OLD_W
Identifier: | 0x6703
Data type: | PT_STRING8, PT_UNICODE
Area: | Personal storage table (.pst) internal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstPath Canonical Property

 Copy code hover
[image]

PidTagPstPath Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the location of the object in the personal folder store to create or configure.

Associated properties: | PR_PST_PATH, PR_PST_PATH_A, PR_PST_PATH_W
Identifier: | 0x6700
Data type: | PT_STRING8, PT_UNICODE
Area: | Personal storage table (.pst) internal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstPathHint Canonical Property

 Copy code hover
[image]

PidTagPstPathHint Canonical Property
See also Send feedback

Published: July 16, 2012

Provides the personal storage table (.pst file) name, which the user can edit, for the configuration dialog box.

Associated properties: | PR_PST_PATH_HINT, PR_PST_PATH_HINT_A, PR_PST_PATH_HINT_W
Identifier: | 0x6771
Data type: | PT_STRING8, PT_UNICODE
Area: | Personal storage table (.pst) internal

Remarks

If the PR_PST_PATH (PidTagPstPath) property is used instead, the configuration dialog box will open, but the user will not be allowed to edit the path and many other properties.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagPstRememberPassword Canonical Property

 Copy code hover
[image]

PidTagPstRememberPassword Canonical Property
See also Send feedback

Published: July 16, 2012

Determines whether to remember the password in the profile.

Associated properties: | PR_PST_REMEMBER_PW
Identifier: | 0x6701
Data type: | PT_BOOLEAN
Area: | Personal storage table (.pst) internal

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRadioTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagRadioTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's radio telephone number.

Associated properties: | PR_RADIO_TELEPHONE_NUMBER, PR_RADIO_TELEPHONE_NUMBER_A, PR_RADIO_TELEPHONE_NUMBER_W
Identifier: | 0x3A1D
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRead Canonical Property

 Copy code hover
[image]

PidTagRead Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether a table row has been read.

Associated properties: | PR_READ
Identifier: | 0x0E69
Data type: | PT_BOOLEAN
Area: | MAPI non-transmittable

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCTABL]

Includes permissible operations for the core table objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReadReceiptEntryId Canonical Property

 Copy code hover
[image]

PidTagReadReceiptEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an entry identifier for the messaging user where the messaging system should direct a read report for this message.

Associated properties: | PR_READ_RECEIPT_ENTRYID
Identifier: | 0x0046
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is ignored unless the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set to TRUE.

If a client application wants to receive read reports itself, it can leave this property unset or set it to the entry identifier contained in the PR_SENDER_ENTRYID (PidTagSenderEntryId) property at message submission time.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReadReceiptRequested Canonical Property

 Copy code hover
[image]

PidTagReadReceiptRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender wants the messaging system to generate a read report when the recipient has read a message.

Associated properties: | PR_READ_RECEIPT_REQUESTED
Identifier: | 0x0029
Data type: | PT_BOOLEAN
Area: | E-mail

Remarks

This property must be set to TRUE to validate the values in the PR_READ_RECEIPT_ENTRYID (PidTagReadReceiptEntryId) and PR_READ_RECEIPT_SEARCH_KEY (PidTagReadReceiptSearchKey) properties.

If a message with PR_READ_RECEIPT_REQUESTED set is deleted or expires before the messaging system can generate a read report, a nonread report is generated.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReadReceiptSearchKey Canonical Property

 Copy code hover
[image]

PidTagReadReceiptSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a search key for the messaging user to which the messaging system should direct a read report for a message.

Associated properties: | PR_READ_RECEIPT_SEARCH_KEY
Identifier: | 0x0053
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is ignored unless the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set to TRUE.

If a client application wants to receive read reports itself, it can leave this property unset or set it to the search key contained in the PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) property at message submission time.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidef.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceiptTime Canonical Property

 Copy code hover
[image]

PidTagReceiptTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time a delivery report is generated.

Associated properties: | PR_RECEIPT_TIME
Identifier: | 0x002A
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

This property must be set by the message store provider receiving the original message and generating the report.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedByAddressType Canonical Property

 Copy code hover
[image]

PidTagReceivedByAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address type, such as SMTP, for the messaging user who actually receives the message.

Associated properties: | PR_RECEIVED_BY_ADDRTYPE, PR_RECEIVED_BY_ADDRTYPE_A, PR_RECEIVED_BY_ADDRTYPE_W
Identifier: | 0x0075
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Remarks

These properties are examples of the address properties for the messaging user who actually receives the message. They must be set by the incoming transport provider.

The address type string can contain only the uppercase alphabetic characters A through Z and the numbers zero through nine. These properties qualify the PR_RECEIVED_BY_EMAIL_ADDRESS (PidTagReceivedByEmailAddress) property by specifying an address type, such as SMTP, thereby indicating how the address should be constructed.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedByEmailAddress Canonical Property

 Copy code hover
[image]

PidTagReceivedByEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address for the messaging user who receives the message.

Associated properties: | PR_RECEIVED_BY_EMAIL_ADDRESS, PR_RECEIVED_BY_EMAIL_ADDRESS_A, PR_RECEIVED_BY_EMAIL_ADDRESS_W
Identifier: | 0x0076
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user who receives the message. They must be set by the incoming transport provider.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagEmailAddress Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedByEntryId Canonical Property

 Copy code hover
[image]

PidTagReceivedByEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the messaging user who actually receives the message.

Associated properties: | PR_RECEIVED_BY_ENTRYID
Identifier: | 0x003F
Data type: | PT_BINARY
Area: | Address book

Remarks

This property is one of the address properties for the messaging user who receives the message. It must be set by the incoming transport provider.

This property corresponds to an X.400 delivery envelope per-message MH_T_ attribute.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting items.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedByName Canonical Property

 Copy code hover
[image]

PidTagReceivedByName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of the messaging user who receives the message.

Associated properties: | PR_RECEIVED_BY_NAME, PR_RECEIVED_BY_NAME_A, PR_RECEIVED_BY_NAME_W
Identifier: | 0x0040
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are an example of the address properties for the messaging user who receives the message. They must be set by the incoming transport provider.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagDisplayName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedBySearchKey Canonical Property

 Copy code hover
[image]

PidTagReceivedBySearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key of the messaging user who receives the message.

Associated properties: | PR_RECEIVED_BY_SEARCH_KEY
Identifier: | 0x0051
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the messaging user who receives the message. It must be set by the incoming transport provider.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedRepresentingAddressType Canonical Property

 Copy code hover
[image]

PidTagReceivedRepresentingAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type for the messaging user who is represented by the user actually receiving the message.

Associated properties: | PR_RCVD_REPRESENTING_ADDRTYPE, PR_RCVD_REPRESENTING_ADDRTYPE_A, PR_RCVD_REPRESENTING_ADDRTYPE_W
Identifier: | 0x0077
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user who is being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, this property should be set to the address type contained in the PR_RECEIVED_BY_ADDRTYPE (PidTagReceivedByAddressType) property.

A client application replying to a message received on behalf of another client should copy this property from the received message into the PR_SENT_REPRESENTING_ADDRTYPE (PidTagSentRepresentingAddressType) property for the reply.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagAddressType Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedRepresentingEmailAddress Canonical Property

 Copy code hover
[image]

PidTagReceivedRepresentingEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address for the messaging user who is represented by the receiving user.

Associated properties: | PR_RCVD_REPRESENTING_EMAIL_ADDRESS, PR_RCVD_REPRESENTING_EMAIL_ADDRESS_A, PR_RCVD_REPRESENTING_EMAIL_ADDRESS_W
Identifier: | 0x0078
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user who is being represented by the receiving user. They must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, these properties should be set to the e-mail address contained in the PR_RECEIVED_BY_EMAIL_ADDRESS (PidTagReceivedByEmailAddress) property.

A client application replying to a message received on behalf of another client should copy these properties from the received message into the PR_SENT_REPRESENTING_EMAIL_ADDRESS (PidTagSentRepresentingEmailAddress) property for the reply.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagEmailAddress Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedRepresentingEntryId Canonical Property

 Copy code hover
[image]

PidTagReceivedRepresentingEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier for the messaging user who is represented by the receiving user.

Associated properties: | PR_RCVD_REPRESENTING_ENTRYID
Identifier: | 0x0043
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the messaging user who is being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, this property should be set to the entry identifier contained in the PR_RECEIVED_BY_ENTRYID (PidTagReceivedByEntryId) property.

A client application replying to a message received on behalf of another client should copy this property from the received message into the PR_SENT_REPRESENTING_ENTRYID (PidTagSentRepresentingEntryId) property for the reply.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedRepresentingName Canonical Property

 Copy code hover
[image]

PidTagReceivedRepresentingName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for the messaging user who is represented by the receiving user.

Associated properties: | PR_RCVD_REPRESENTING_NAME, PR_RCVD_REPRESENTING_NAME_A, PR_RCVD_REPRESENTING_NAME_W
Identifier: | 0x0044
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user who is being represented by the receiving user. They must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, these properties should be set to the display name contained in the PR_RECEIVED_BY_NAME (PidTagReceivedByName) property.

A client application replying to a message received on behalf of another client should copy these properties from the received message into the PR_SENT_REPRESENTING_NAME (PidTagSentRepresentingName) property for the reply.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceivedRepresentingSearchKey Canonical Property

 Copy code hover
[image]

PidTagReceivedRepresentingSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key for the messaging user represented by the receiving user.

Associated properties: | PR_RCVD_REPRESENTING_SEARCH_KEY
Identifier: | 0x0052
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the messaging user being represented by the receiving user. It must be set by the incoming transport provider, which is also responsible for authorization or verification of the delegate. If no messaging user is being represented, this property should be set to the search key contained in the PR_RECEIVED_BY_SEARCH_KEY (PidTagReceivedBySearchKey) property.

A client application replying to a message received on behalf of another client should copy this property from the received message into the PR_SENT_REPRESENTING_SEARCH_KEY (PidTagSentRepresentingSearchKey) property for the reply.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagSearchKey Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReceiveFolderSettings Canonical Property

 Copy code hover
[image]

PidTagReceiveFolderSettings Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a table of a message store's receive folder settings.

Associated properties: | PR_RECEIVE_FOLDER_SETTINGS
Identifier: | 0x3415
Data type: | PT_OBJECT
Area: | MAPI message store

Remarks

This property can be excluded in IMAPIProp::CopyTo operations or included in IMAPIProp::CopyProps operations. As a property of type PT_OBJECT, it cannot be successfully retrieved by the IMAPIProp::GetProps method; its contents should be accessed by the IMAPIProp::OpenProperty method, requesting the interface with identifier IID_IMAPITable. Service providers must report it to the IMAPIProp::GetPropList method if it is set, but can optionally report it or not if it is not set.

To retrieve table contents, a client application should call the IMsgStore::GetReceiveFolderTable method. For more information, see Receive Folder Tables.

This property contains a table of mappings of the receive folders for the message store. Calling OpenProperty on this property is equivalent to calling GetReceiveFolderTable on the message store.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientCertificate Canonical Property

 Copy code hover
[image]

PidTagRecipientCertificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message recipient's ASN.1 certificate for use in a report.

Associated properties: | PR_RECIPIENT_CERTIFICATE
Identifier: | 0x0C13
Data type: | PT_BINARY
Area: | MAPI Recipient

Remarks

This property is a copy of the recipient's PR_USER_CERTIFICATE (PidTagUserCertificate) property for use in a report. It can be used to prove to the originator that the recipient actually received the message, which a delivery report does not necessarily indicate.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientDisplayName Canonical Property

 Copy code hover
[image]

PidTagRecipientDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value of the PR_DISPLAY_NAME (PidTagDisplayName) property.

Associated properties: | PR_RECIPIENT_DISPLAY_NAME, PR_RECIPIENT_DISPLAY_NAME_A, PR_RECIPIENT_DISPLAY_NAME_W
Identifier: | 0x5FF6
Data type: | PT_STRING8, PT_UNICODE
Area: | Transport recipient

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides data type definitions.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientEntryId Canonical Property

 Copy code hover
[image]

PidTagRecipientEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the recipient

Associated properties: | PR_RECIPIENT_ENTRYID
Identifier: | 0x5FF7
Data type: | PT_BINARY
Area: | ID properties

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientFlags Canonical Property

 Copy code hover
[image]

PidTagRecipientFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a bit field that describes the recipient status.

Associated properties: | PR_RECIPIENT_FLAGS
Identifier: | 0x5FFD
Data type: | PT_LONG
Area: | Transport recipient

Remarks

This property is not required. The following are the individual flags that can be set.

Value | Description
S (recipSendable, 0x00000001) | The recipient is a Sendable Attendee. This flag is only used in the dispidApptUnsendableRecips (PidLidAppointmentUnsendableRecipients) property.
O (recipOrganizer, 0x0000002) | The RecipientRow on which this flag is set represents the meeting Organizer.
ER (recipExceptionalResponse, 0x00000010) | Indicates that the attendee gave a response for the exception on which this RecipientRow resides. This flag is only used in a RecipientRow of an exception embedded message object of the organizer's meeting object.
ED (recipExceptionalDeleted, 0x00000020) | Indicates that although the RecipientRow exists, it should be treated as if the corresponding recipient does not. This flag is only used in a RecipientRow of an exception embedded message object of the organizer's meeting object.
X (reserved, 0x00000040) | Must not be set.
X (reserved, 0x00000080) | Must not be set.
G (recipOriginal, 0x00000100) | Indicates the recipient is an original attendee. This flag is only used in the dispidApptUnsendableRecips property.
X (reserved, 0x00000200) | Reserved.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientNumber Canonical Property

 Copy code hover
[image]

PidTagRecipientNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the recipient number of a recipient on the message.

Associated properties: | PR_RECIPIENT_NUMBER
Identifier: | 0x6662
Data type: | PT_LONG
Area: | Exchange Message Read/Write

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientNumberForAdvice Canonical Property

 Copy code hover
[image]

PidTagRecipientNumberForAdvice Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains a message recipient's telephone number to call to advise of the physical delivery of a message.

Associated properties: | PR_RECIPIENT_NUMBER_FOR_ADVICE, PR_RECIPIENT_NUMBER_FOR_ADVICE_A, PR_RECIPIENT_NUMBER_FOR_ADVICE_W
Identifier: | 0x0C14
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI Recipient

Remarks

These properties are meant to be used in conjunction with delivery to a physical destination, rather than an electronic mailbox, when the human recipient is not expected to be present at delivery. An example is the telephone number on a fax cover sheet.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientProposed Canonical Property

 Copy code hover
[image]

PidTagRecipientProposed Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates whether a meeting attendee has responded.

Associated properties: | PR_RECIPIENT_PROPOSED
Identifier: | 0x5FE1
Data type: | PT_BOOLEAN
Area: | Transport recipient

Remarks

A value of TRUE for this property indicates that the attendee proposed a new date and/or time. A value of FALSE, or the absence of this property, means either that the attendee has not yet responded, or the most recent response from the attendee did not include a new date/ time proposal. This value must not be TRUE for attendees in a recurring series.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientProposedEndTime Canonical Property

 Copy code hover
[image]

PidTagRecipientProposedEndTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates a proposed end time of a meeting.

Associated properties: | PR_RECIPIENT_PROPOSEDENDTIME
Identifier: | 0x5FE4
Data type: | PT_SYSTIME
Area: | Transport recipient

Remarks

When the value of the PR_RECIPIENT_PROPOSED (PidTagRecipientProposed) property is set to TRUE, the value of this property indicates the value requested by the attendee to set as the value of the dispidApptEndWhole (PidLidAppointmentEndWhole) property for the single instance meeting object or exception object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientProposedStartTime Canonical Property

 Copy code hover
[image]

PidTagRecipientProposedStartTime Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates a proposed starting time of a meeting.

Associated properties: | PR_RECIPIENT_PROPOSEDSTARTTIME
Identifier: | 0x5FE3
Data type: | PT_SYSTIME
Area: | Transport recipient

Remarks

When the value of the PR_RECIPIENT_PROPOSED (PidTagRecipientProposed) property is set to TRUE, the value of this property indicates the value requested by the attendee to set as the value of the dispidApptStartWhole (PidLidAppointmentStartWhole) property for the single instance meeting object or exception object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientReassignmentProhibited Canonical Property

 Copy code hover
[image]

PidTagRecipientReassignmentProhibited Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies whether adding additional recipients, when forwarding the message, is prohibited for the e-mail message.

Associated properties: | PR_RECIPIENT_REASSIGNMENT_PROHIBITED
Identifier: | 0x002B
Data type: | PT_BOOLEAN
Area: | MAPI Envelope

Remarks

This property is set based on the e-mail message's PR_SENSITIVITY (PidTagSensitivity) value. If PR_SENSITIVITY is set to "0x00000000" (normal) or "0x00000003" (confidential), this property must be set to "0x00" or absent meaning that adding additional or different recipients to the e-mail message is allowed. If the e-mail object's PR_SENSITIVITY is set to "0x00000001" (personal) or "0x00000002" (private), this property must be set "0x01" to prevent adding additional or different recipients of this e-mail through forwarding.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientStatus Canonical Property

 Copy code hover
[image]

PidTagRecipientStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that is used by the MAPI spooler in assigning delivery responsibility among transport providers.

Associated properties: | PR_RECIPIENT_STATUS
Identifier: | 0x0E15
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientTrackStatus Canonical Property

 Copy code hover
[image]

PidTagRecipientTrackStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the response status returned by the attendee.

Associated properties: | PR_RECIPIENT_TRACKSTATUS
Identifier: | 0x5FFF
Data type: | PT_LONG
Area: | Transport recipient

Remarks

If this value is not set, it must be assumed to be respNone. Otherwise, it must be one of the following:

Response status | Value | Description
respNone | 0x00000000 | No response is required for this object. This is the case for appointment objects and meeting response objects.
respTentative | 0x00000002 | This value on the attendee's meeting object indicates that the attendee has tentatively accepted the meeting request object.
respAccepted | 0x00000003 | This value on the attendee's meeting object indicates that the attendee has accepted the meeting request object.
respDeclined | 0x00000004 | This value on the attendee's meeting object indicates that the attendee has declined the meeting request object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientTrackStatusTime Canonical Property

 Copy code hover
[image]

PidTagRecipientTrackStatusTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when the attendee responded.

Associated properties: | PR_RECIPIENT_TRACKSTATUS_TIME
Identifier: | 0x5FFB
Data type: | PT_SYSTIME
Area: | Transport recipient

Remarks

The value must be specified in Coordinated Universal Time (UTC).

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecipientType Canonical Property

 Copy code hover
[image]

PidTagRecipientType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient type for a message recipient.

Associated properties: | PR_RECIPIENT_TYPE
Identifier: | 0x0C15
Data type: | PT_LONG
Area: | MAPI recipient

Remarks

The recipient type contained in this property consists of one required value and one optional flag.

This property must contain exactly one of the following values:

MAPI_TO

The recipient is a primary (To) recipient. Clients are required to handle primary recipients. All other types are optional.

MAPI_CC

The recipient is a carbon copy (CC) recipient, a recipient that receives a message in addition to the primary recipients.

MAPI_BCC

The recipient is a blind carbon copy (BCC) recipient. Primary and carbon copy recipients are unaware of the existence of BCC recipients.

MAPI_P1

The recipient did not successfully receive the message on the previous attempt. This is a resend of an earlier transmission.

In addition, the following flag can be set:

MAPI_SUBMITTED

The recipient has already received the message and does not need to receive it again. This is a resend of an earlier transmission. This flag is set in conjunction with the MAPI_TO, MAPI_CC, and MAPI_BCC values.

The MAPI_P1 value and the MAPI_SUBMITTED flag are used when a message is being retransmitted due to nondelivery to one or more of the intended recipients. For this retransmission, the client sets MAPI_SUBMITTED on every recipient that does not need the message again but should be displayed in the recipient list. For every recipient that did not receive the message previously, the client retains the original recipient with its PR_RECIPIENT_TYPE value unchanged, but additionally submits a copy of the recipient with MAPI_P1 in place of the original value. This copy, which is discarded before actual delivery, forces the recipient into the P1 envelope and guarantees physical retransmission to that recipient. The PR_RESPONSIBILITY (PidTagResponsibility) property is set to FALSE for MAPI_P1 recipients.

When a client displays a resend form, only the MAPI_P1 recipients are visible. Unless the user enters additional recipients, when the message is delivered, the recipient list appears exactly as it did when the message was sent for the first time.

The PR_DISPLAY_TO (PidTagDisplayTo), PR_DISPLAY_CC (PidTagDisplayCc) and PR_DISPLAY_BCC (PidTagDisplayBcc) properties are related to recipient type. When a client calls a message's IMAPIProp::SaveChanges and there is at least one recipient in the recipient list, the message store provider sets these properties as follows:

Property | Description
PR_DISPLAY_TO | Set to TRUE if one or more of the recipients are MAPI_TO recipients.
PR_DISPLAY_CC | Set to TRUE if one or more of the recipients are MAPI_CC recipients.
PR_DISPLAY_BCC | Set to TRUE if one or more of the recipients are MAPI_BCC recipients.

In X.400, the P1 or delivery envelope is the information needed to deliver a message, including the recipient's address properties and any option flags controlling delivery and replies. The P2 or display envelope is the information usually displayed to each recipient other than the message text itself. It typically includes the subject, importance, priority, sensitivity, and submission time, as well as the primary and copied recipient names.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagRecipientStatus Canonical Property
PidTagDisplayTo Canonical Property
PidTagDisplayBcc Canonical Property
PidTagDisplayCc Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRecordKey Canonical Property

 Copy code hover
[image]

PidTagRecordKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a unique binary-comparable identifier for a specific object.

Associated properties: | PR_RECORD_KEY
Identifier: | 0x0FF9
Data type: | PT_BINARY
Area: | ID properties

Remarks

This property facilitates locating references to an object, such as finding its row in a contents table. This property cannot be used to open an object; use the entry identifier for that purpose.

An attachment subobject should be uniquely identified within a message by this property. This identifier is the only attachment characteristic guaranteed to stay the same after the message is closed and reopened. The store provider must preserve this property across sessions to ensure this guarantee.

For folders, this property contains a key used in the folder hierarchy table. Typically this is the same value as that provided by the PR_ENTRYID (PidTagEntryId) property.

For message stores, this property is identical to the PR_STORE_RECORD_KEY (PidTagStoreRecordKey) property.

In a message store object, this property should be unique across all store providers. One way to do this is to combine the value of the PR_MDB_PROVIDER (PidTagStoreProvider) property for the store (unique to that provider type) with a GUID structure or other value unique to the specific message store.

This property is always available through the IMAPIProp::GetProps method following the first call to the IMAPIProp::SaveChanges method. Some providers can make it available immediately after instantiation.

A client or service provider can compare values from this property by using memcmp. This is not possible for entry identifier values. However, this property is guaranteed to be unique within the same message store or address book container; two objects from different containers can have the same value of this property.

One distinction between the record and search keys is that the record key is specific to the object, whereas the search key can be copied to other objects. For example, two copies of the object can have the same PR_SEARCH_KEY (PidTagSearchKey) value but must have different values for this property.

The following table summarizes important differences among PR_ENTRYID, PR_SEARCH_KEY (PidTagSearchKey) and this property.

Characteristic | PR_ENTRYID | PR_RECORD_KEY | PR_SEARCH_KEY
Required on attachment objects | No | Yes | No
Required on folder objects | Yes | Yes | No
Required on message store objects | Yes | Yes | No
Required on status objects | Yes | No | No
Creatable by client | No | No | Yes
Available before a call to SaveChanges | Maybe | Maybe | Messages Yes Others Maybe
Changed in a copy operation | Yes | Yes | No
Changeable by a client after a copy | No | No | Yes
Unique within ... | Entire world | Provider instance | Entire world
Binary comparable (as with memcmp) | No -- use IMAPISupport:: CompareEntryIDs | Yes | Yes

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRedirectionHistory Canonical Property

 Copy code hover
[image]

PidTagRedirectionHistory Canonical Property
See also Send feedback

Published: July 16, 2012

Contains information about the route covered by a delivered message.

Associated properties: | PR_REDIRECTION_HISTORY
Identifier: | 0x002C
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is used when a message is autoforwarded by an automatic agent.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReferredByName Canonical Property

 Copy code hover
[image]

PidTagReferredByName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the mail user's referral.

Associated properties: | PR_REFERRED_BY_NAME, PR_REFERRED_BY_NAME_A, PR_REFERRED_BY_NAME_W
Identifier: | 0x3A47
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRegisteredMailType Canonical Property

 Copy code hover
[image]

PidTagRegisteredMailType Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains the type of registration used for physical delivery of a message.

Associated properties: | PR_REGISTERED_MAIL_TYPE
Identifier: | 0x0C16
Data type: | PT_LONG
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRelatedMessageIds Canonical Property

 Copy code hover
[image]

PidTagRelatedMessageIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of identifiers for messages to which a message is related.

Associated properties: | PR_RELATED_IPMS
Identifier: | 0x002D
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

The identifiers use the same specific construction rules as are used for the PR_SEARCH_KEY (PidTagSearchKey) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRemindersOnlineEntryId Canonical Property

 Copy code hover
[image]

PidTagRemindersOnlineEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryID of the reminders folder.

Associated properties: | PR_REM_ONLINE_ENTRYID
Identifier: | 0x36D5
Data type: | PT_BINARY
Area: | MAPI container

Remarks

This property is stored in the Inbox folder and in the root folder of the message store. To access the property on a specific message store, do the following.

  1. First, look for the property in the Inbox folder. Use IMsgStore::GetReceiveFolder to obtain a reference to the EntryID for the Inbox folder.

  2. If IMsgStore::GetReceiveFolder is successful, then use the reference to the EntryID of the Inbox and IMsgStore::OpenEntry to open the Inbox and obtain a reference to an IMAPIFolder object.

  3. If IMsgStore::OpenEntry is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

  4. If Step 1, 2, or 3 fails, look for the property in the root folder. To do that, use IMsgStore::OpenEntry, specifying NULL for lpEntryID, to open the root folder of the message store and obtain a reference to the IMAPIFolder object.

  5. If opening the root folder is successful, then use the returned reference to the IMAPIFolder object and IMAPIProp::GetProps to obtain the desired property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSFLD]

Specifies the properties and operations for creating and locating the special folders in a mailbox.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRemoteProgress Canonical Property

 Copy code hover
[image]

PidTagRemoteProgress Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains a number that indicates the status of a remote transfer.

Associated properties: | PR_REMOTE_PROGRESS
Identifier: | 0x3E0B
Data type: | PT_LONG
Area: | MAPI Status

Remarks

If no transfer is in progress, this property should be set to 1. If a transfer is in progress, it should be set to a value from 0 to 100 indicating the transfer's percent of completion.

The text associated with the numeric status code appears in the PR_REMOTE_PROGRESS_TEXT (PidTagRemoteProgressText) property.

The following flags can be set for this property:

MSGSTATUS_REMOTE_DELETE

The message transfer is deleted.

MSGSTATUS_REMOTE_DOWNLOAD

The message transfer is in progress.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRemoteProgressText Canonical Property

 Copy code hover
[image]

PidTagRemoteProgressText Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains a string that indicates the status of a remote transfer.

Associated properties: | PR_REMOTE_PROGRESS_TEXT, PR_REMOTE_PROGRESS_TEXT_A, PR_REMOTE_PROGRESS_TEXT_W
Identifier: | 0x3E0C
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI Status

Remarks

A numeric code associated with this text is passed in the PR_REMOTE_PROGRESS (PidTagRemoteProgress) property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRemoteValidateOk Canonical Property

 Copy code hover
[image]

PidTagRemoteValidateOk Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains TRUE if the remote viewer is allowed to call the IMAPIStatus::ValidateState method.

Associated properties: | PR_REMOTE_VALIDATE_OK
Identifier: | 0x3E0D
Data type: | PT_BOOLEAN
Area: | MAPI Status

Remarks

This property appears in the status table and offers some control over transport performance. It can be considered as another way of directing the remote viewer to idle. When it is set to TRUE, the remote viewer can call IMAPIStatus::ValidateState as often as desired. A value of FALSE indicates that the remote viewer cannot make any more calls.

The transport provider usually sets this property dynamically, by setting the value to FALSE to disable additional calls when the transport provider has a sufficient amount of processing to perform. When the transport provider is done, it then sets the value to TRUE to allow the client application to make further IMAPIStatus::ValidateState calls.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRenderingPosition Canonical Property

 Copy code hover
[image]

PidTagRenderingPosition Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an offset, in characters, to use in rendering an attachment within the main message text.

Associated properties: | PR_RENDERING_POSITION
Identifier: | 0x370B
Data type: | PT_LONG
Area: | MAPI attachment

Remarks

When the supplied offset is -1 (0xFFFFFFFF), the attachment is not rendered by using this property. All values other than -1 indicate the position within the PR_BODY (PidTagBody) property at which the attachment is to be rendered.

Note The character indicated by this property in PR_BODY is replaced by the attachment. Typically this character is a space, although a special placeholder character can also be used.

This property is expressed in characters. In some character sets this is not equivalent to bytes. Unicode applications can compute the position based on two-byte characters. Double-Byte Character Set (DBCS) applications must scan the text up to this property value, because their character representation varies between one and two bytes per character.

This property should not be used with Rich Text Format (RTF) text. The rendering position is indicated in RTF by an escape sequence called the object attachment placeholder. This sequence consists of the string \objattph followed by a single character, normally a space, that will be replaced by the attachment rendering.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReplyRecipientEntries Canonical Property

 Copy code hover
[image]

PidTagReplyRecipientEntries Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a sized array of entry identifiers for recipients that are to get a reply.

Associated properties: | PR_REPLY_RECIPIENT_ENTRIES
Identifier: | 0x004F
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property contains a FLATENTRYLIST structure and is not a multivalued property.

When this property is not present, a reply is sent only to the user identified by the PR_SENDER_ENTRYID (PidTagSenderEntryId) property. When this and the PR_REPLY_RECIPIENT_NAMES (PidTagReplyRecipientNames) properties are defined, the reply is sent to all of the recipients identified by these two properties. A transport provider uses these properties to override the usual reply logic.

If either this property or the PR_REPLY_RECIPIENT_NAMES property is set, the other property must be set also. These properties must contain the same number of recipients, and they must contain them in the same order. Failure to observe these requirements can cause unpredictable results.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReplyRecipientNames Canonical Property

 Copy code hover
[image]

PidTagReplyRecipientNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of display names for recipients that are to get a reply.

Associated properties: | PR_REPLY_RECIPIENT_NAMES, PR_REPLY_RECIPIENT_NAMES_A, PR_REPLY_RECIPIENT_NAMES_W
Identifier: | 0x0050
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Remarks

These properties contain the display names separated by semicolons.

When this property is not present, a reply is sent only to the user identified by the PR_SENDER_NAME (PidTagSenderName) property. When PR_REPLY_RECIPIENT_ENTRIES (PidTagReplyRecipientEntries) and these properties are defined, the reply is sent to all of the recipients identified by these two properties. A transport provider uses these properties to override the usual reply logic.

If either PR_REPLY_RECIPIENT_ENTRIES or these properties are set, the other property must be set also. These properties must contain the same number of recipients, and they must contain them in the same order. Failure to observe these requirements can cause unpredictable results.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReplyRequested Canonical Property

 Copy code hover
[image]

PidTagReplyRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a message sender requests a reply from a recipient.

Associated properties: | PR_REPLY_REQUESTED
Identifier: | 0x0C17
Data type: | PT_BOOLEAN
Area: | MAPI recipient

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReplyTemplateId Canonical Property

 Copy code hover
[image]

PidTagReplyTemplateId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the globally unique identifier (GUID) for the reply template.

Associated properties: | PR_REPLY_TEMPLATE_ID
Identifier: | 0x65C2
Data type: | PT_BINARY
Area: | Rules

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReplyTime Canonical Property

 Copy code hover
[image]

PidTagReplyTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the deadline on a message.

Associated properties: | PR_REPLY_TIME
Identifier: | 0x0030
Data type: | PT_SYSTIME
Area: | MAPI envelope

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportDisposition Canonical Property

 Copy code hover
[image]

PidTagReportDisposition Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the receipt status for messages that request receipts.

Associated properties: | PR_REPORT_DISPOSITION, PR_REPORT_DISPOSITION_A, PR_REPORT_DISPOSITION_W
Identifier: | 0x0080
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Remarks

The following are valid values:

  • "deleted"

  • "processed"

  • "dispatched"

  • "denied"

  • "failed"

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportDispositionMode Canonical Property

 Copy code hover
[image]

PidTagReportDispositionMode Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the disposition of the receipt for messages that request receipts.

Associated properties: | PR_REPORT_DISPOSITION_MODE, PR_REPORT_DISPOSITION_MODE_A, PR_REPORT_DISPOSITION_MODE_W
Identifier: | 0x0081
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Remarks

The possible values for this property are "manual-action/MDN-sent-automatically" and "manual-action/MDN-sent-manually".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportDispositionOptions Canonical Property

 Copy code hover
[image]

PidTagReportDispositionOptions Canonical Property
See also Send feedback

Published: July 16, 2012

Maps to the MIME Disposition-Options header for messages that request receipts. The value of this property should be an empty string.

Associated properties: | PR_REPORT_DISPOSITION_OPTIONS, PR_REPORT_DISPOSITION_OPTIONS_A, PR_REPORT_DISPOSITION_OPTIONS_W
Identifier: | 0x0085
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportDispositionToEmailAddresses Canonical Property

 Copy code hover
[image]

PidTagReportDispositionToEmailAddresses Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates e-mail addresses of the report recipients for messages that request receipts.

Associated properties: | PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES, PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_A, PR_REPORT_DISPOSITION_TO_EMAIL_ADDRESSES_W
Identifier: | 0x0084
Data type: | PT_MV_STRING8, PT_UNICODE
Area: | MAPI envelope

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportDispositionToNames Canonical Property

 Copy code hover
[image]

PidTagReportDispositionToNames Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the names of the report recipients for messages that request receipts.

Associated properties: | PR_REPORT_DISPOSITION_TO_NAMES, PR_REPORT_DISPOSITION_TO_NAMES_A, PR_REPORT_DISPOSITION_TO_NAMES_W
Identifier: | 0x0083
Data type: | PT_MV_STRING8, PT_UNICODE
Area: | MAPI envelope

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportEntryId Canonical Property

 Copy code hover
[image]

PidTagReportEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier for the recipient who should receive reports for this message.

Associated properties: | PR_REPORT_ENTRYID
Identifier: | 0x0045
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is one of the address properties for the recipient who the sender has delegated to receive any reports generated for this message.

A client application that must route reports to another user should set this property at message submission time. If it is not set, the reports are sent to the message sender.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportingDistributionListName Canonical Property

 Copy code hover
[image]

PidTagReportingDistributionListName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name of a distribution list where the messaging system delivers a report.

Associated properties: | PR_REPORTING_DL_NAME
Identifier: | 0x1003
Data type: | PT_BINARY
Area: | MAPI Message

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportingMessageTransferAgentCertificate Canonical Property

 Copy code hover
[image]

PidTagReportingMessageTransferAgentCertificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an identifier for the message transfer agent that generated a report.

Associated properties: | PR_REPORTING_MTA_CERTIFICATE
Identifier: | 0x1004
Data type: | PT_BINARY
Area: | MAPI Message

Remarks

This property corresponds to an X.400 report per-message attribute.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportName Canonical Property

 Copy code hover
[image]

PidTagReportName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for the recipient that should get reports for this message.

Associated properties: | PR_REPORT_NAME, PR_REPORT_NAME_A, PR_REPORT_NAME_W
Identifier: | 0x003A
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Remarks

These properties are examples of the address properties for the recipient that the sender has delegated to receive any reports generated for this message.

A client application that must route reports to another user should set these properties at message submission time. If they are not set, the reports are sent to the message sender.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportOriginalSender Canonical Property

 Copy code hover
[image]

PidTagReportOriginalSender Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the original sender of the message for messages that request receipts.

Associated properties: | PR_REPORT_ORIGINAL_SENDER, PR_REPORT_ORIGINAL_SENDER_A, PR_REPORT_ORIGINAL_SENDER_W
Identifier: | 0x0082
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI envelope

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportSearchKey Canonical Property

 Copy code hover
[image]

PidTagReportSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key for the recipient that should get reports for this message.

Associated properties: | PR_REPORT_SEARCH_KEY
Identifier: | 0x0054
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property is one of the address properties for the recipient that the sender has delegated to receive any reports generated for this message.

A client application that must route reports to another user should set this property at message submission time. If it is not set, the reports are sent to the message sender.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportTag Canonical Property

 Copy code hover
[image]

PidTagReportTag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a binary tag value that the messaging system should copy to any report generated for the message.

Associated properties: | PR_REPORT_TAG
Identifier: | 0x0031
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property, like the PR_SUBJECT_IPM (PidTagSubjectMessageId) property, is used to correlate a report with the original message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportText Canonical Property

 Copy code hover
[image]

PidTagReportText Canonical Property
See also Send feedback

Published: July 16, 2012

Contains optional text for a report generated by the messaging system.

Associated properties: | PR_REPORT_TEXT, PR_REPORT_TEXT_A, PR_REPORT_TEXT_W
Identifier: | 0x1001
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI message

Remarks

Usually, the text contained in these properties is generated in response to a delivery or nondelivery report or a read or nonread report received from the underlying messaging system, but is not itself text that was transferred through that system.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReportTime Canonical Property

 Copy code hover
[image]

PidTagReportTime Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date and time when the messaging system generated a report.

Associated properties: | PR_REPORT_TIME
Identifier: | 0x0032
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

This property represents a per-recipient property on delivery and nondelivery reports and a per-message property on read and nonread reports.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk e-mail messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRequestedDeliveryMethod Canonical Property

 Copy code hover
[image]

PidTagRequestedDeliveryMethod Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains a binary array of delivery methods (service providers), in the order of a message sender's preference.

Associated properties: | PR_REQUESTED_DELIVERY_METHOD
Identifier: | 0x0C18
Data type: | PT_LONG
Area: | MAPI Recipient

Remarks

The array contained in the this property consists of ASN.1 identifiers for each of the service providers.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResolveMethod Canonical Property

 Copy code hover
[image]

PidTagResolveMethod Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a folder's conflict resolution value.

Associated properties: | PR_RESOLVE_METHOD
Identifier: | 0x3FE7
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property on the folder containing the conflict resolution message will indicate how to resolve the conflict. This property is not required. However, if it is set, flags other than the following must not be present:

RESOLVE_METHOD_DEFAULT (0x00000000) | Conflict resolve message should be generated.
RESOLVE_METHOD_LAST_WRITER_WINS (0x00000001) | Overwrite target message with current changes being applied.
RESOLVE_NO_CONFLICT_NOTIFICATION (0x00000002) | Do not send conflict notification message when generating conflict resolve message in public folder.

A client or server must not generate a conflict resolve message for associated messages. These messages must be resolved by using RESOLVE_METHOD_LAST_WRITER_WINS semantics.

Related Resources

Protocol Specifications

[MS-OXCSYNC]

Handles synchronizing messaging object data between a server and a client.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResourceFlags Canonical Property

 Copy code hover
[image]

PidTagResourceFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags for message services and providers.

Associated properties: | PR_RESOURCE_FLAGS
Identifier: | 0x3009
Data type: | PT_LONG
Area: | MAPI common

Remarks

This property describes the characteristics of a message service, a service provider, or a status object. The flags that are set for this property depend on its context. For example, some flags are valid only for status objects and other flags only for columns in the message service table.

The flags are of three classes: static, modifiable, and dynamic. Static flags are set by MAPI from data in MAPISVC.INF and never altered. Modifiable flags are set by MAPI from MAPISVC.INF but can be subsequently changed. Dynamic flags can be set and reset by MAPI methods.

For a message service, one or more of the following flags can be set in this property:

SERVICE_CREATE_WITH_STORE

Reserved. Do not use.

SERVICE_DEFAULT_STORE

Dynamic. The message service contains the default store. A user interface should be displayed prompting the user for confirmation before deleting or moving this service out of the profile.

SERVICE_NO_PRIMARY_IDENTITY

Static. The service level flag that should be set to indicate that none of the providers in the message service can be used to supply an identity. Either this flag or SERVICE_PRIMARY_IDENTITY should be set, but not both.

SERVICE_PRIMARY_IDENTITY

Modifiable. The corresponding message service contains the provider used for the primary identity for this session. Use IMsgServiceAdmin::SetPrimaryIdentity to set this flag. Either this flag or SERVICE_NO_PRIMARY_IDENTITY should be set, but not both.

SERVICE_SINGLE_COPY

Static. Any attempt to create or copy this message service into a profile where the service already exists will fail. To create a single copy message service add the PR_RESOURCE_FLAGS property to the service's section in MAPISVC.INF and set this flag.

For a service provider, one or more of the following flags can be set in PR_RESOURCE_FLAGS:

HOOK_INBOUND

Static. The spooler hook needs to process inbound messages.

HOOK_OUTBOUND

Static. The spooler hook needs to process outbound messages.

STATUS_DEFAULT_OUTBOUND

Modifiable. This identity should be applied to outbound messages if the profile contains multiple instances of this transport provider. This can happen if multiple instances of a single transport provider appear in the profile.

STATUS_DEFAULT_STORE

Modifiable. This message store is the default store for the profile.

STATUS_NEED_IPM_TREE

Dynamic. The standard folders in this message store, including the interpersonal message (IPM) root folder, have not yet been verified. MAPI sets and clears this flag.

STATUS_NO_DEFAULT_STORE

Static. This message store is incapable of becoming the default message store for the profile.

STATUS_NO_PRIMARY_IDENTITY

Static. This provider does not furnish an identity in its status row. Either this flag or STATUS_PRIMARY_IDENTITY must be set.

STATUS_OWN_STORE

Static. This transport provider is tightly coupled with a message store and furnishes the PR_OWN_STORE_ENTRYID (PidTagOwnStoreEntryId) property in its status row.

STATUS_PRIMARY_IDENTITY

Modifiable. This provider furnishes the primary identity for the session; the entry identifier for the object furnishing the identity is returned from IMAPISession::QueryIdentity. Either this flag or STATUS_NO_PRIMARY_IDENTITY must be set.

STATUS_PRIMARY_STORE

Modifiable. This message store is to be used when a client application logs on. Once opened, this store should be set as the default store for the profile.

STATUS_SECONDARY_STORE

Modifiable. This message store is to be used if the primary store is not available when a client application logs on. Once opened, this store should be set as the default store for the profile.

STATUS_SIMPLE_STORE

Dynamic. This message store will be used by Simple MAPI as its default message store.

STATUS_TEMP_SECTION

Dynamic. This message store should not be published in the message store table and will be deleted from the profile after logoff.

STATUS_XP_PREFER_LAST

Static. This transport expects to be the last transport selected to send a message when multiple transport providers are able to transmit the message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMsgServiceAdmin::MsgServiceTransportOrder
PidTagIdentityEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResourceMethods Canonical Property

 Copy code hover
[image]

PidTagResourceMethods Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that indicate the methods in the IMAPIStatus interface that are supported by the status object.

Associated properties: | PR_RESOURCE_METHODS
Identifier: | 0x3E02
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property indicates which of the methods in a status object's implementation of IMAPIStatus are supported. Status objects are allowed to return MAPI_E_NO_SUPPORT from unsupported methods.

Clients use a status object's PR_RESOURCE_METHODS property to avoid making calls to unsupported methods. If the flag that corresponds to a particular method is set, the method exists and can be called. If that flag is clear, the method should not be called.

The status objects implemented by MAPI support the following methods:

Status object | Supported methods
MAPI subsystem | ValidateState only
MAPI address book | ValidateState only
MAPI spooler | ValidateState and FlushQueues

One or more of the following flags can be set in PR_RESOURCE_METHODS:

STATUS_CHANGE_PASSWORD

Indicates that the IMAPIStatus::ChangePassword method is supported.

STATUS_FLUSH_QUEUES

Indicates that the IMAPIStatus::FlushQueues method is supported.

STATUS_SETTINGS_DIALOG

Indicates that the IMAPIStatus::SettingsDialog method is supported.

STATUS_VALIDATE_STATE

Indicates that the IMAPIStatus::ValidateState method is supported.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResourcePath Canonical Property

 Copy code hover
[image]

PidTagResourcePath Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a path to the service provider's server.

Associated properties: | PR_RESOURCE_PATH, PR_RESOURCE_PATH_A, PR_RESOURCE_PATH_W
Identifier: | 0x3E07
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI status

Remarks

The path contained in these properties represents the suggested path where the user can find resources. The definition of these properties is provider specific. For example, a scheduling application uses these properties to specify the suggested location for its scheduling application files.

The messaging user profile furnishes these properties as a convenience so that a client application does not have to prompt the messaging user for a network path or network drive letter.

MAPI works only with filenames in the American National Standards Institute (ANSI) character set. Applications that use filenames in an original equipment manufacturer (OEM) character set must convert them to ANSI before calling MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResourceType Canonical Property

 Copy code hover
[image]

PidTagResourceType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the service provider type.

Associated properties: | PR_RESOURCE_TYPE
Identifier: | 0x3E03
Data type: | PT_LONG
Area: | MAPI status

Remarks

This property can have exactly one of the following values:

MAPI_AB

Address book

MAPI_AB_PROVIDER

Address book provider

MAPI_HOOK_PROVIDER

Spooler hook provider

MAPI_PROFILE_PROVIDER

Profile provider

MAPI_SPOOLER

Message spooler

MAPI_STORE_PROVIDER

Message store provider

MAPI_SUBSYSTEM

Internal MAPI subsystem

MAPI_TRANSPORT_PROVIDER

Transport provider

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResponseRequested Canonical Property

 Copy code hover
[image]

PidTagResponseRequested Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the message sender wants a response to a meeting request.

Associated properties: | PR_RESPONSE_REQUESTED
Identifier: | 0x0063
Data type: | PT_BOOLEAN
Area: | MAPI envelope

Remarks

This property is used for meeting requests. The receiving client application should prompt the user to accept or decline the request and then send this response back to the sender.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail messages.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagResponsibility Canonical Property

 Copy code hover
[image]

PidTagResponsibility Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if some transport provider has already accepted responsibility for delivering the message to this recipient, and FALSE if the MAPI spooler considers that this transport provider should accept responsibility.

Associated properties: | PR_RESPONSIBILITY
Identifier: | 0x0E0F
Data type: | PT_BOOLEAN
Area: | MAPI non-transmittable

Remarks

When the MAPI spooler presents an outbound message to a transport provider, through IXPLogon::SubmitMessage, it sets this property to FALSE for all recipients for which the MAPI spooler considers that transport provider responsible, and TRUE for all other recipients. The transport provider should attempt to handle all recipients with PR_RESPONSIBILITY set to FALSE. After successfully sending, or conclusively failing to send, to a recipient, the transport provider should set this property to TRUE in the source message to indicate that it has accepted responsibility for that recipient.

If, after examining a recipient, a transport provider decides that it cannot or should not handle it, the transport provider should leave PR_RESPONSIBILITY set to FALSE. The MAPI spooler will then look for another transport provider that can handle that recipient. The MAPI spooler ultimately creates a nondelivery report for any recipients for which no transport provider accepts responsibility.

If the transport provider attempts and fails to deliver the message, it should call the IMAPISupport::StatusRecips method to indicate to MAPI the reasons for the failure, so that MAPI can generate a nondelivery report.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagDeleteAfterSubmit Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagReturnedMessageid Canonical Property

 Copy code hover
[image]

PidTagReturnedMessageid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the original message is being returned with a nonread report.

Associated properties: | PR_RETURNED_IPM
Identifier: | 0x0033
Data type: | PT_BOOLEAN
Area: | MAPI envelope

Remarks

An X.400 transport provider sets this property in the unread report.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRoamingBinary Canonical Property

 Copy code hover
[image]

PidTagRoamingBinary Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message stream associated with a subclass of the IPM.Configuration class.

Associated properties: | PR_ROAMING_BINARYSTREAM
Identifier: | 0x7C09
Data type: | PT_BINARY
Area: | Configuration

Remarks

This property contains the data stream associated with an IPM.Configuration message class message. The format of the stream depends on the message class. For instance, a message of class type IPM.Configuration.Autocomplete would be formatted as an Autocomplete Stream.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRoamingDatatypes Canonical Property

 Copy code hover
[image]

PidTagRoamingDatatypes Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask that indicates which stream properties exist on the message.

Associated properties: | PR_ROAMING_DATATYPES
Identifier: | 0x7C06
Data type: | PT_LONG
Area: | Configuration

Remarks

This property must be set to one or more of the following values:

Value | Description
0x00000002 | Indicates that the Folder Associated Information (FAI) message should contain a Dictionary stream, serialized into a fixed XML schema and stored in the PR_ROAMING_DICTIONARY (PidTagRoamingDictionary) property. If the FAI message does not contain a Dictionary stream, the application must treat the Dictionary as having no entries.
0x00000004 | Indicates that the FAI message must contain an XML stream stored in the PR_ROAMING_XMLSTREAM (PidTagRoamingXmlStream) property that uses an arbitrary XML schema.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRoamingDictionary Canonical Property

 Copy code hover
[image]

PidTagRoamingDictionary Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an XML document that describes the roaming dictionary.

Associated properties: | PR_ROAMING_DICTIONARY
Identifier: | 0x7C07
Data type: | PT_BINARY
Area: | Configuration

Remarks

This property contains a UNICODE XML document that is using UTF8 encoding. A message with a dictionary stream must set this property with the following schema:

Copy code Copy code
<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="Dictionary.xsd" xmlns="Dictionary.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="UserConfiguration">
   <xs:complexType>
   <xs:sequence>
   <xs:element name="Info">
   <xs:complexType>
   <xs:sequence />
   <xs:attribute name="version" type="VersionString">
   </xs:attribute>
   </xs:complexType>

The following is a sample XML document stored in this property on a Configuration Data message:

Copy code Copy code
<?xml version="1.0"?>
<UserConfiguration>
<Info version="Outlook.12"/>
<Data> <e k="18-piAutoProcess" v="3-True"/>
<e k="18-piRemindDefault" v="9-15"/>
<e k="18-piReminderUpgradeTime" v="9-212864507"/>
<e k="18-OLPrefsVersion" v="9-1"/>
</Data>
</UserConfiguration>

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRoamingXmlStream Canonical Property

 Copy code hover
[image]

PidTagRoamingXmlStream Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an arbitrary XML stream.

Associated properties: | PR_ROAMING_XMLSTREAM
Identifier: | 0x7C08
Data type: | PT_BINARY
Area: | Configuration

Remarks

This property contains an arbitrary stream of XML data. Other properties in the message may imply specific schemas to use in this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRowid Canonical Property

 Copy code hover
[image]

PidTagRowid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a unique identifier for a recipient in a recipient table or status table.

Associated properties: | PR_ROWID
Identifier: | 0x3000
Data type: | PT_LONG
Area: | MAPI common

Remarks

This property is a temporary value that is valid only for the life of the object that owns the table. It appears as a column of the table but is not stored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMessage::GetRecipientTable
IMessage::ModifyRecipients

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRowType Canonical Property

 Copy code hover
[image]

PidTagRowType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the type of a row in a table.

Associated properties: | PR_ROW_TYPE
Identifier: | 0x0FF5
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

This property appears only on contents tables. A category only exists when it has items.

This property can have exactly one of the following values:

TBL_LEAF_ROW

Represents actual data, rather than a category row.

TBL_EMPTY_CATEGORY

Not currently used.

TBL_EXPANDED_CATEGORY

The category is expanded; the user interface usually displays this with the minus sign ( - ) next to it.

TBL_COLLAPSED_CATEGORY

The category is collapsed; the user interface usually displays this with the plus sign (+) next to it.

Related Resources

Protocol Specifications

[MS-OXCTABL]

Includes permissible operations for the core table objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagRowid Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRpcOverHttpFlags Canonical Property

 Copy code hover
[image]

PidTagRpcOverHttpFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the settings in a profile used by Microsoft Office Outlook to connect to Microsoft Exchange Server by using a remote procedure call (RPC) over Hypertext Transfer Protocol (HTTP).

Associated properties: | PR_ROH_FLAGS
Identifier: | 0x6623
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

The PR_ROH_FLAGS property is stored in the Global Profile Section of a Messaging Application Programming Interface (MAPI) profile. The value of PR_ROH_FLAGS is a bitmask that is made up of one or more of the following flags.

Name | Value | Description
ROHFLAGS_USE_ROH | 0x1 | Connect to the Exchange Server using RPC over HTTP.
ROHFLAGS_SSL_ONLY | 0x2 | Connect to the Exchange Server using Secure Socket Layer (SSL) only.
ROHFLAGS_MUTUAL_AUTH | 0x4 | Mutually authenticate the session when connecting by using SSL.
ROHFLAGS_HTTP_FIRST_ON_FAST | 0x8 | On fast networks, connect by using HTTP first. Then, connect by using TCP/IP.
ROHFLAGS_HTTP_FIRST_ON_SLOW | 0x20 | On slow networks, connect by using HTTP first. Then, connect by using TCP/IP.

For example, to set the PR_ROH_FLAGS property to turn on RPC over HTTP, to require SSL, and to specify that the HTTP protocol should be used first on slow connections, set the value of the PR_ROH_FLAGS property to ROHFLAGS_USE_ROH | ROHFLAGS_SSL_ONLY | ROHFLAGS_HTTP_FIRST_ON_SLOW which is equal to 0x23.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRpcOverHttpProxyAuthScheme Canonical Property

 Copy code hover
[image]

PidTagRpcOverHttpProxyAuthScheme Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the authentication protocol to be used for this profile.

Associated properties: | PR_ROH_PROXY_AUTH_SCHEME
Identifier: | 0x6627
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

This property can be set for either basic authentication or NT LAN Manager (NTLM) authentication. The possible values for this property are as follow.

Name | Value | Description
ROHAUTH_BASIC | 0x1 | Basic authentication
ROHAUTH_NTLM | 0x2 | NTLM authentication

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRpcOverHttpProxyPrincipalName Canonical Property

 Copy code hover
[image]

PidTagRpcOverHttpProxyPrincipalName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the principal name of the proxy server that is used by Microsoft Outlook to connect to Exchange Server by using a remote procedure call (RPC) over Hypertext Transfer Protocol (HTTP).

Associated properties: | PR_ROH_PROXY_PRINCIPAL_NAME
Identifier: | 0x6625
Property type: | PT_UNICODE
Area: | Miscellaneous

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permitted for email message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRpcOverHttpProxyServer Canonical Property

 Copy code hover
[image]

PidTagRpcOverHttpProxyServer Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the URL of the proxy server that is used to connect Microsoft Outlook to Exchange Server without the HTTP protocol or the Hypertext Transfer Protocol Secure (HTTPS) protocol that comes before the URL.

Associated properties: | PR_ROH_PROXY_SERVER
Identifier: | 0x6622
Property type: | PT_UNICODE
Area: | Miscellaneous

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Defines the basic data structures that are used in remote operations.

[MS-OXOMSG]

Specifies the properties and operations that are permitted for email message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfCompressed Canonical Property

 Copy code hover
[image]

PidTagRtfCompressed Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the Rich Text Format (RTF) version of the message text, usually in compressed form.

Associated properties: | PR_RTF_COMPRESSED
Identifier: | 0x1009
Data type: | PT_BINARY
Area: | E-mail

Remarks

This property contains the same message text as the PR_BODY (PidTagBody) property but in RTF.

Message text in RTF is normally stored in compressed form. However, some systems do not compress formatted text. To accommodate them, MAPI provides the dwMagicUncompressedRTF value for a stream header to identify uncompressed RTF, and the STORE_UNCOMPRESSED_RTF flag in PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) for the message store to indicate it can store uncompressed RTF.

To obtain the contents of this property, call OpenProperty, then call WrapCompressedRTFStream with the MAPI_READ flag. To write into this property, open it with the MAPI_MODIFY and MAPI_CREATE flags. This ensures that the new data completely replace any old data and that the writes are performed using the minimum number of store updates.

Message stores that support RTF ignore any changes to white space in the message text. When PR_BODY is stored for the first time, the message store also generates and stores this property. If the IMAPIProp::SaveChanges method is subsequently called and PR_BODY has been modified, the message store calls the RTFSync function to ensure synchronization with the RTF version. If only white space has been changed, the properties are left unchanged. This preserves any nontrivial RTF formatting when the message travels through non-RTF-aware clients and messaging systems.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXRTFCP]

Encodes and decodes a compressed stream in RTF message bodies.

[MS-OXRTFEX]

Encapsulates additional content formats (such as HTML) within the RTF body property of messages and attachments.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfInSync Canonical Property

 Copy code hover
[image]

PidTagRtfInSync Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the PR_RTF_COMPRESSED (PidTagRtfCompressed) property has the same text content as the PR_BODY (PidTagBody) property for this message.

Associated properties: | PR_RTF_IN_SYNC
Identifier: | 0x0E1F
Data type: | PT_BOOLEAN
Area: | E-mail

Remarks

A value of TRUE means that the PR_BODY (PidTagBody) property, the plain text version of this message, and the PR_RTF_COMPRESSED (PidTagRtfCompressed) property, the Rich Text Format (RTF) version, are identical except for white space in PR_BODY and formatting in PR_RTF_COMPRESSED. The text in the two versions consists of the same characters in the same sequence.

A value of FALSE means that the two versions are not synchronized for text content but are capable of being synchronized by the RTFSync function. One version has been altered and the other version has not.

No value means that the two versions, if both exist or ever existed, cannot be synchronized. One version has been deleted or altered so radically that synchronization is no longer possible.

A client application that has modified PR_RTF_COMPRESSED should set a value of FALSE in this property to force synchronization. RTF-aware message stores should perform the synchronization using RTFSync during an IMAPIProp::SaveChanges call. RTF-aware clients should check the setting of PR_RTF_IN_SYNC before reading PR_RTF_COMPRESSED, and call RTFSync first if necessary.

If PR_BODY has had modifications to anything other than its white space, the message store must delete PR_RTF_IN_SYNC to terminate synchronization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfSyncBodyCount Canonical Property

 Copy code hover
[image]

PidTagRtfSyncBodyCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a count of the significant characters of the message text.

Associated properties: | PR_RTF_SYNC_BODY_COUNT
Identifier: | 0x1007
Data type: | PT_LONG
Area: | MAPI message

Remarks

The RTFSync function computes the count of characters in the text using only those that it considers to be significant to the message. For example, some white space and other ignorable characters are omitted from the count.

This property is a Rich Text Format (RTF) auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfSyncBodyCrc Canonical Property

 Copy code hover
[image]

PidTagRtfSyncBodyCrc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the cyclical redundancy check (CRC) computed for the message text.

Associated properties: | PR_RTF_SYNC_BODY_CRC
Identifier: | 0x1006
Data type: | PT_LONG
Area: | MAPI message

Remarks

The RTFSync function computes the CRC by using only the characters that it considers to be significant to the message. For example, some white space and other ignorable characters are omitted from the CRC.

This property is a Rich Text Format (RTF) auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfSyncBodyTag Canonical Property

 Copy code hover
[image]

PidTagRtfSyncBodyTag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains significant characters that appear at the beginning of the message text.

Associated properties: | PR_RTF_SYNC_BODY_TAG, PR_RTF_SYNC_BODY_TAG_A, PR_RTF_SYNC_BODY_TAG_W
Identifier: | 0x1008
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI message

Remarks

The RTFSync function uses the text tag to indicate the beginning of the message text. When the text is modified, the tag is used to find the beginning of the previous text.

These properties are Rich Text Format auxiliary properties. They are used by the RTFSync function and are not intended to be used directly by client applications.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfSyncPrefixCount Canonical Property

 Copy code hover
[image]

PidTagRtfSyncPrefixCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a count of the ignorable characters that appear before the significant characters of the message.

Associated properties: | PR_RTF_SYNC_PREFIX_COUNT
Identifier: | 0x1010
Data type: | PT_LONG
Area: | MAPI message

Remarks

The count of prefix characters does not include white space.

This property is a Rich Text Format (RTF) auxiliary property. RTF auxiliary properties are used by the RTFSync function and are not intended to be used directly by client applications.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRtfSyncTrailingCount Canonical Property

 Copy code hover
[image]

PidTagRtfSyncTrailingCount Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a count of the ignorable characters that appear after the significant characters of the message.

Associated properties: | PR_RTF_SYNC_TRAILING_COUNT
Identifier: | 0x1011
Data type: | PT_LONG
Area: | MAPI message

Remarks

This property is a Rich Text Format (RFT) auxiliary property. These properties are used by the RTFSync function and are not intended to be used directly by client applications.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleActions Canonical Property

 Copy code hover
[image]

PidTagRuleActions Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the set of actions associated with the rule.

Associated properties: | PR_RULE_ACTIONS
Identifier: | 0x6680
Data type: | PT_ACTIONS
Area: | Server Side Rules

Remarks

The actions are expressed as a rule action and the property value buffer contains the rule action data buffer structure packaged as specified in [MS-OXORULE].

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ImportProcs.cpp | PropCopyMore, HrCopyActions | These functions demonstrate how to parse a PT_ACTIONS property for the purposes of copying to another property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleCondition Canonical Property

 Copy code hover
[image]

PidTagRuleCondition Canonical Property
See also Send feedback

Published: July 16, 2012

The condition used when you evaluate the rule.

Associated properties: | PR_RULE_CONDITION
Identifier: | 0x6679
Data type: | PT_SRESTRICTION
Area: | Server Side Rules

Remarks

The condition is expressed as a Restriction and the PropertyValue buffer contains the Restriction structure packaged as specified in [MS-OXCDATA].

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
ImportProcs.cpp | PropCopyMore, HrCopyRestriction | These functions demonstrate how to parse a PT_SRESTRICTION property for the purposes of copying to another property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

[MS-OXCDATA]

Defines the basic data structures that are used in remote operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleId Canonical Property

 Copy code hover
[image]

PidTagRuleId Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies a unique identifier the messaging server generates for each rule when the rule is first created.

Associated properties: | PR_RULE_ID
Identifier: | 0x6674
Data type: | PT_I8
Area: | Server Side Rules

Remarks

The client must not specify this property when creating a new rule but must specify it when modifying or deleting a rule.

When deleting a rule, the only property the client must pass is PR_RULE_ID and should not pass in any other property. The server must ignore properties other than this property. When adding a rule, the client must not pass in PR_RULE_ID, it must pass in the PR_RULE_CONDITION (PidTagRuleCondition), PR_RULE_ACTIONS (PidTagRuleActions) and PR_RULE_PROVIDER (PidTagRuleProvider) properties. When modifying a rule, the client must pass in PR_RULE_ID and should pass in the rest of the properties that need to be modified.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagRuleCondition Canonical Property
PidTagRuleActions Canonical Property
PidTagRuleProvider Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleLevel Canonical Property

 Copy code hover
[image]

PidTagRuleLevel Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the exit level of a rule.

Associated properties: | PR_RULE_LEVEL
Identifier: | 0x6683
Data type: | PT_LONG
Area: | Server Side Rules

Remarks

If setting this property, the client must pass in 0x00000000.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar items when they act on behalf of another user.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IExchangeModifyTable : IUnknown

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleMsgName Canonical Property

 Copy code hover
[image]

PidTagRuleMsgName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of an extended rule.

Associated properties: | PR_RULE_MSG_NAME
Identifier: | 0x65EC
Data type: | PT_UNICODE
Area: | Rules

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleMsgProvider Canonical Property

 Copy code hover
[image]

PidTagRuleMsgProvider Canonical Property
See also Send feedback

Published: July 16, 2012

Contains additional information about the client application that owns an extended rule.

Associated properties: | PR_RULE_MSG_PROVIDER
Identifier: | 0x65EB
Data type: | PT_UNICODE
Area: | Rules

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleName Canonical Property

 Copy code hover
[image]

PidTagRuleName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the user-readable name of the rule.

Associated properties: | PR_RULE_NAME
Identifier: | 0x6682
Data type: | PT_STRING8
Area: | Server Side Rules

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar items when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleProvider Canonical Property

 Copy code hover
[image]

PidTagRuleProvider Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the application that sets a rule.

Associated properties: | PR_RULE_PROVIDER, PR_RULE_PROVIDER_A , PR_RULE_PROVIDER_W
Identifier: | 0x6681
Data type: | PT_STRING8, PT_UNICODE
Area: | Server Side Rules

Remarks

Deferred actions need these properties to identify the code that must interpret and execute the rule action.

Rules stored on mailboxes and folders are associated with the application that owns them by a rule provider string. A rule provider sets and handles rules in a rule table. It also provides a means of handling any deferred actions if such rules are set. Deferred actions are created implicitly by the information store. For move or copy operations to a different store, if a provider sets a deferred action rule, it must provide a handler to perform the action when the rule is fired and a deferred action is created.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleProviderData Canonical Property

 Copy code hover
[image]

PidTagRuleProviderData Canonical Property
See also Send feedback

Published: July 16, 2012

An opaque property that the client sets for the exclusive use of the client.

Associated properties: | PR_RULE_PROVIDER_DATA
Identifier: | 0x6684
Data type: | PT_BINARY
Area: | Server Side Rules

Remarks

The server must preserve the value of this property if it was set by the client but must ignore its contents during rule evaluation and processing.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagRuleProvider Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleSequence Canonical Property

 Copy code hover
[image]

PidTagRuleSequence Canonical Property
See also Send feedback

Published: July 16, 2012

A value used to determine the order in which rules are evaluated and executed.

Associated properties: | PR_RULE_SEQUENCE
Identifier: | 0x6676
Data type: | PT_LONG
Area: | Server Side Rules

Remarks

Rules are evaluated in sequence according to the increasing order of this value. The evaluation order for rules that have the same value in this property is undefined.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar items when they act on behalf of another user.

[MS-OXCTABL]

Includes permissible operations for the core table objects.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRulesTable Canonical Property

 Copy code hover
[image]

PidTagRulesTable Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a table with all rules applied to a folder.

Associated properties: | PR_RULES_TABLE
Identifier: | 0x3FE1
Data type: | PT_OBJECT
Area: | Server Side Rules

Remarks

This property is present on all folder objects on an Exchange Server that have rules. Values included in this property are used for reading and modifying rules. You can use the IMAPIProp::OpenProperty method with the IID_IExchangeModifyTable interface identifier to obtain an IExchangeModifyTable : IUnknown interface to the rules table on a folder. You can use this interface to read and modify those rules.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IExchangeModifyTable : IUnknown
IMAPIProp::OpenProperty

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleState Canonical Property

 Copy code hover
[image]

PidTagRuleState Canonical Property
See also Send feedback

Published: July 16, 2012

A value interpreted as a bitmask combination of flags that specify the state of the rule.

Associated properties: | PR_RULE_STATE
Identifier: | 0x6677
Data type: | PT_LONG
Area: | Server Side Rules

Remarks

The following table defines the possible values of this property.

EN (ST_ENABLED, bitmask 0x00000001)

The rule is enabled for execution. If this flag is not set, the server must skip this rule when evaluating rules.

ER (ST_ERROR, bitmask 0x00000002)

The server has encountered an error processing the rule.

OF (ST_ONLY_WHEN_OOF, bitmask 0x00000004)

The rule is executed only when the user sets the Out of Office (OOF) state on the mailbox. This flag must not be set in a public folder rule.

HI (ST_KEEP_OOF_HIST, bitmask 0x00000008)

This flag must not be set in a public folder rule.

EL (ST_EXIT_LEVEL, bitmask 0x00000010)

Rule evaluation will end after executing this rule, except for evaluation of Out of Office rules.

SCL (ST_SKIP_IF_SCL_IS_SAFE, bitmask 0x00000020)

Evaluation of this rule may be skipped.

PE (ST_RULE_PARSE_ERROR, bitmask 0x00000040)

The server has encountered an error parsing the rule data provided by the client.

X

Unused by this protocol. This bit must not be modified by the client.

Note on the interaction between ST_ONLY_WHEN_OOF and ST_EXIT_LEVEL flags:

When the "Out of Office" state is set on the mailbox, and a rule condition evaluates to TRUE,

AND:

  • The rule has the ST_EXIT_LEVEL flag set and does not have ST_ONLY_WHEN_OOF flag set. Then, the server must not evaluate subsequent rules that do not have ST_ONLY_WHEN_OOF flag set, and must evaluate subsequent rules that have ST_ONLY_WHEN_OOF flag set.

OR:

  • The rule has both the ST_EXIT_LEVEL and ST_ONLY_WHEN_OOF flags set. Then, the server must not evaluate any subsequent rules.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagRuleUserFlags Canonical Property

 Copy code hover
[image]

PidTagRuleUserFlags Canonical Property
See also Send feedback

Published: July 16, 2012

This property is set by the client for the exclusive use of the client.

Associated properties: | PR_RULE_USER_FLAGS
Identifier: | 0x6678
Data type: | PT_LONG
Area: | Server Side Rules

Remarks

The server must preserve the value of this property if it was set by the client. The server must ignore it during rule evaluation and processing.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXORULE]

Manipulates incoming e-mail messages on a server.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoAppointmentTombstone Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoAppointmentTombstone Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of data blocks that represent meetings that have been declined.

Associated properties: | PR_SCHDINFO_APPT_TOMBSTONE
Identifier: | 0x686A
Data type: | PT_BINARY
Area: | Free/Busy

Remarks

The data blocks begin with a header of 32 bit values defined as:

Value | Description
Identifier | This field must be the value 0xBEDEAFCD.
HeaderSize | This field must have the value 0x00000014.
Version | This field must have the value 3.
RecordsCount | The count of records that follow.
RecordsSize | This field must have the value 0x00000014.

The header is followed by RecordsCount entries of 32 bit values defined as:

Value | Description
StartTime | The meeting object's start time in minutes since midnight, January 1, 1601, UTC.
EndTime | The meeting object's end time in minutes since midnight, January 1, 1601, UTC.
GlobalObjectIdSize | The size, in bytes, of the GlobalObjectId field.
GlobalObjectId | The value of the LID_GLOBAL_OBJID (PidLidGlobalObjectId) property of the meeting this record represents.
UserName | The first two bytes are the length of the PT_STRING8 string that follows.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoAutoAcceptAppointments Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoAutoAcceptAppointments Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a client or server should automatically respond to all meeting requests for the attendee or resource.

Associated properties: | PR_SCHDINFO_AUTO_ACCEPT_APPTS
Identifier: | 0x686D
Data type: | PT_BOOLEAN
Area: | Free/Busy

Remarks

When responding, the response must be acceptance, unless for an additional constraint that is specified by the PR_SCHDINFO_DISALLOW_RECURRING_APPTS (PidTagScheduleInfoDisallowRecurringAppts) or PR_SCHDINFO_DISALLOW_OVERLAPPING_APPTS (PidTagScheduleInfoDisallowOverlappingAppts) properties is met. A value of FALSE or the absence of this property indicates that a client or server must not automatically accept meeting requests. This is not a required property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDelegateEntryIds Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDelegateEntryIds Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the EntryIDs of the delegates.

Associated properties: | PR_SCHDINFO_DELEGATE_ENTRYIDS
Identifier: | 0x6845
Data type: | PT_MV_BINARY
Area: | Free/Busy

Remarks

Each entry must contain the value of the PR_ENTRYID (PidTagEntryId) property of each delegate's address book entry. This property must be set in the delegate information object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDelegateNames Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDelegateNames Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the names of the delegates.

Associated properties: | PR_SCHDINFO_DELEGATE_NAMES, PR_SCHDINFO_DELEGATE_NAMES_A, PR_SCHDINFO_DELEGATE_NAMES_W
Identifier: | 0x6844
Data type: | PT_MV_STRING8, PT_MV_UNICODE
Area: | Free/Busy

Remarks

Each entry in these properties must contain the value of the PR_DISPLAY_NAME (PidTagDisplayName) property of each delegate's address book.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDelegatorWantsCopy Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDelegatorWantsCopy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the delegator wants to receive copies of the meeting-related objects that are sent to the delegate.

Associated properties: | PR_SCHDINFO_BOSS_WANTS_COPY
Identifier: | 0x6842
Data type: | PT_BOOLEAN
Area: | Free/Busy

Remarks

This property must be set in the delegate information object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDelegatorWantsInfo Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDelegatorWantsInfo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the delegator who wants to receive informational updates.

Associated properties: | PR_SCHDINFO_BOSS_WANTS_INFO
Identifier: | 0x684B
Data type: | PT_BOOLEAN
Area: | Free/Busy

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDisallowOverlappingAppts Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDisallowOverlappingAppts Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if overlapping appointments are disallowed.

Associated properties: | PR_SCHDINFO_DISALLOW_OVERLAPPING_APPTS
Identifier: | 0x686F
Data type: | PT_BOOLEAN
Area: | Free/Busy

Remarks

This property is only meaningful when the value of the PR_SCHDINFO_AUTO_ACCEPT_APPTS (PidTagScheduleInfoAutoAcceptAppointments) property is TRUE. A value of TRUE indicates that when automatically responding to meeting requests, a client or server must decline instances that overlap previously scheduled events. A value of FALSE or the absence of this property indicates that overlapping instances must be accepted. This is not a required property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDisallowRecurringAppts Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDisallowRecurringAppts Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE when the automatic response to recurring appointments is decline.

Associated properties: | PR_SCHDINFO_DISALLOW_RECURRING_APPTS
Identifier: | 0x686E
Data type: | PT_BOOLEAN
Area: | Free/Busy

Remarks

This property is only meaningful when the value of the PR_SCHDINFO_AUTO_ACCEPT_APPTS (PidTagScheduleInfoAutoAcceptAppointments) property is TRUE. The absence of this property indicates that recurring meetings must be accepted. This is not a required property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoDontMailDelegates Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoDontMailDelegates Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the delegate does not want to receive updates.

Associated properties: | PR_SCHDINFO_DONT_MAIL_DELEGATES
Identifier: | 0x6843
Data type: | PT_BOOLEAN
Area: | Free/Busy

Remarks

This property must be set in the delegate information object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoFreeBusy Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoFreeBusy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains obsolete information.

Associated properties: | PR_SCHDINFO_FREEBUSY
Identifier: | 0x686C
Data type: | PT_BINARY
Area: | Free/Busy

Remarks

This property should not be set and must be ignored.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoFreeBusyAway Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoFreeBusyAway Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the times for which the free/busy status is set to OOF.

Associated properties: | PR_SCHDINFO_FREEBUSY_OOF
Identifier: | 0x6856
Data type: | PT_MV_BINARY
Area: | Free/Busy

Remarks

The format, computation and constraints of this property are the same as those of PR_SCHDINFO_FREEBUSY_TENTATIVE (PidTagScheduleInfoFreeBusyTentative) but refer to appointments that are marked OOF on the associated calendar.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoFreeBusyBusy Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoFreeBusyBusy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the blocks of time for which the status is busy.

Associated properties: | PR_SCHDINFO_FREEBUSY_BUSY
Identifier: | 0x6854
Data type: | PT_MV_BINARY
Area: | Free/Busy

Remarks

The format, computation and constraints of this property are the same as those of PR_SCHDINFO_FREEBUSY_TENTATIVE (PidTagScheduleInfoFreeBusyTentative) but refer to appointments that are marked busy on the associated calendar object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoFreeBusyMerged Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoFreeBusyMerged Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the times for which the free/busy status is set to busy or OOF.

Associated properties: | PR_SCHDINFO_FREEBUSY_MERGED
Identifier: | 0x6850
Data type: | PT_MV_BINARY
Area: | Free/Busy

Remarks

Events of free/busy type tentative are not included in this property. The format, computation and the restrictions of this property are the same as those of PR_SCHDINFO_FREEBUSY_TENTATIVE (PidTagScheduleInfoFreeBusyTentative) but refer to appointments that are marked OOF or busy on the associated calendar.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoFreeBusyTentative Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoFreeBusyTentative Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the blocks of times for which the free/busy status is tentative.

Associated properties: | PR_SCHDINFO_FREEBUSY_TENTATIVE
Identifier: | 0x6852
Data type: | PT_MV_BINARY
Area: | Free/Busy

Remarks

This property has as many values as the number of values in PR_SCHDINFO_MONTHS_TENTATIVE (PidTagScheduleInfoMonthsTentative). Each binary value represents a month and corresponds to the value at the same index in PR_SCHDINFO_MONTHS_TENTATIVE. The binary values are sorted in the same order as the values in PR_SCHDINFO_MONTHS_TENTATIVE.

Each binary value has one or more 4-BYTE blocks and each of them contains the start time in the first two bytes and end time in the second two bytes in little-endian format. The start time is the number of minutes between midnight Coordinated Universal Time (UTC) of the first day of the month and the start time of the event in UTC. The end time is the number of minutes between midnight UTC of the first day of the month and the end time of the event in UTC. The 4-BYTE blocks are sorted in ascending order.

Consecutive or overlapping blocks of time are merged into one block with start time as the start time of the first block and end time as the end time of the last block. If an event is spread across multiple months or years, the event is split into multiple blocks, one for each month. If there are no tentative events in the publishing range, then this property and PR_SCHDINFO_MONTHS_TENTATIVE must not be set or must be deleted if they already exist. Otherwise, this property must be set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoMonthsAway Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoMonthsAway Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of the months for which free/busy data of type out of office (OOF) is present in the free/busy message.

Associated properties: | PR_SCHDINFO_MONTHS_OOF
Identifier: | 0x6855
Data type: | PT_MV_LONG
Area: | Free/Busy

Remarks

The format, computation and constraints of this property are the same as those of PR_SCHDINFO_FREEBUSY_TENTATIVE (PidTagScheduleInfoFreeBusyTentative) but refer to appointments that are marked out of office (OOF) on the associated calendar object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoMonthsBusy Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoMonthsBusy Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the months for which free/busy data of type busy is present in the free/busy message.

Associated properties: | PR_SCHDINFO_MONTHS_BUSY
Identifier: | 0x6853
Data type: | PT_MV_LONG
Area: | Free/Busy

Remarks

The format, computation and constraints of this property are the same as those of PR_SCHDINFO_MONTHS_TENTATIVE (PidTagScheduleInfoMonthsTentative) but refer to appointments that are marked busy on the associated calendar object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoMonthsMerged Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoMonthsMerged Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of the months for which free/busy data of type busy or an out of office (OOF) message is present in the free/busy message.

Associated properties: | PR_SCHDINFO_MONTHS_MERGED
Identifier: | 0x684F
Data type: | PT_MV_LONG
Area: | Free/Busy

Remarks

Events of free/busy type tentative are not included in this property. The syntax/format and constraints of this property are the same as those of PR_SCHDINFO_MONTHS_TENTATIVE (PidTagScheduleInfoMonthsTentative) but refer to appointments that are marked OOF or Busy on the associated calendar object.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoMonthsTentative Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoMonthsTentative Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the months marked tentative in the free/busy message.

Associated properties: | PR_SCHDINFO_MONTHS_TENTATIVE
Identifier: | 0x6851
Data type: | PT_MV_LONG
Area: | Free/Busy

Remarks

The number of values in this property must be between zero and the number of months covered by the publishing range, which is the period between the PR_FREEBUSY_PUBLISH_START (PidTagFreeBusyPublishStart) and PR_FREEBUSY_PUBLISH_END (PidTagFreeBusyPublishEnd) properties.

Each value in this property, has a month and year encoded in it. This is calculated by using the expression "year × 16 + month" where year and month are based on the Gregorian calendar. The values are sorted in ascending order and are encoded in little-endian format. If an event is spread across multiple months, or multiple years, there must be one value for each of the months that fall in the publishing range. If there are no tentative events in the publishing range, then this property and PR_SCHDINFO_FREEBUSY_TENTATIVE (PidTagScheduleInfoFreeBusyTentative) must not be set or must be deleted if they already exist. Otherwise, this property must be set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagScheduleInfoResourceType Canonical Property

 Copy code hover
[image]

PidTagScheduleInfoResourceType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that must be set to zero (0).

Associated properties: | PR_SCHDINFO_RESOURCE_TYPE
Identifier: | 0x6841
Data type: | PT_LONG
Area: | Free/Busy

Remarks

This property must be set to zero (0) when sent and ignored upon receipt.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOPFFB]

Publishes the availability of a user or resource.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearch Canonical Property

 Copy code hover
[image]

PidTagSearch Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a container object that is used for advanced searches.

Associated properties: | PR_SEARCH
Identifier: | 0x3607
Data type: | PT_OBJECT
Area: | Address book container

Remarks

A container that does not support advanced search capabilities does not have to supply the property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IMAPIContainer : IMAPIProp

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchAttachments Canonical Property

 Copy code hover
[image]

PidTagSearchAttachments Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Unicode string that is being queried in attachment contents on the store.

Associated properties: | PR_SEARCH_ATTACHMENTS_W
Identifier: | 0x0EA5
Property type: | PT_UNICODE
Area: | Search

Related Resources

Note Note

This MAPI restriction tag, used when you are searching for attachment contents, might not be defined in the downloadable header file that you currently have. You can add it to your code by using the following value:

#define PR_SEARCH_ATTACHMENTS_W PROP_TAG(PT_UNICODE, 0x0EA5)

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchRecipientEmailBcc Canonical Property

 Copy code hover
[image]

PidTagSearchRecipientEmailBcc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Unicode string that is being queried in the list of email addresses or display names of recipients addressed in the BCC line of unsent messages on the store.

Associated properties: | PR_SEARCH_RECIP_EMAIL_BCC_W
Identifier: | 0x0EA8
Property type: | PT_UNICODE
Access: | Search

Remarks

This property is only relevant to messages on the store that have not been sent, because messages that have been sent or received do not contain BCC information.

Note Note

This MAPI restriction tag, used when searching for email addresses or display names to which the message will be sent as a blind carbon copy, might not be defined in the downloadable header file that you currently have. You can add it to your code by using the following value:

#define PR_SEARCH_RECIP_EMAIL_BCC_W PROP_TAG(PT_UNICODE, 0x0EA8)

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchRecipientEmailCc Canonical Property

 Copy code hover
[image]

PidTagSearchRecipientEmailCc Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Unicode string that is being queried in the list of email addresses or display names of recipients that are addressed in the CC line of messages on the store.

Associated properties: | PR_SEARCH_RECIP_EMAIL_CC_W
Identifier: | 0x0EA7
Property type: | PT_UNICODE
Area: | Search

Related Resources

Note Note

This MAPI restriction tag, used when you search for email addresses or display names to which the message is sent as a carbon copy, might not be defined in the downloadable header file that you currently have. You can add it to your code by using the following value:

#define PR_SEARCH_RECIP_EMAIL_CC_W PROP_TAG(PT_UNICODE, 0x0EA7)

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties that are listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchRecipientEmailTo Canonical Property

 Copy code hover
[image]

PidTagSearchRecipientEmailTo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a Unicode string that is being queried in the list of email addresses or display names of recipients that are addressed in the To line of messages on the store.

Associated properties: | PR_SEARCH_RECIP_EMAIL_TO_W
Identifier: | 0x0EA6
Property type: | PT_UNICODE
Area: | Search

Related Resources

Note Note

This MAPI restriction tag, used when you search for email addresses or display names to which the message is sent, might not be defined in the downloadable header file that you currently have. You can add it to your code by using the following value:

#define PR_SEARCH_RECIP_EMAIL_TO_W PROP_TAG(PT_UNICODE, 0x0EA6)

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties that are listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderDefinition Canonical Property

 Copy code hover
[image]

PidTagSearchFolderDefinition Canonical Property
See also Send feedback

Published: July 16, 2012

Contains data that specifies the search criteria.

Associated properties: | PR_WB_SF_DEFINITION
Identifier: | 0x6845
Data type: | PT_BINARY
Area: | Search

Remarks

The specific content of each field of the binary large object (BLOB) contained in this property is dependent upon the template ID that is specified in PidTagSearchFolderTemplateId (PidTagSearchFolderTemplateId) property. For information about the BLOB structure and search templates, see [MS-OXOSRCH].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderEfpFlags Canonical Property

 Copy code hover
[image]

PidTagSearchFolderEfpFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains extended folder flags that apply to the search folder container for the search folder.

Associated properties: | PR_WB_SF_EFP_FLAGS
Identifier: | 0x6848
Data type: | PT_LONG
Area: | Search

Remarks

This property should specifically contain the flags in the PR_EXTENDED_FOLDER_FLAGS (PidTagExtendedFolderFlags) property, and the ExtendedFlags sub-property, in field b for the folder. For information about folder flags see the [MS-OXOCFG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderExpiration Canonical Property

 Copy code hover
[image]

PidTagSearchFolderExpiration Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the time at which the search folder container will be stale and should be updated or recreated.

Associated properties: | PR_WB_SF_EXPIRATION
Identifier: | 0x683A
Data type: | PT_LONG
Area: | Search

Remarks

This property must be formatted as the number of minutes since midnight Coordinated Universal Time (UTC) January 1, 1601.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderId Canonical Property

 Copy code hover
[image]

PidTagSearchFolderId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a globally unique identifier (GUID) that identifies the search folder.

Associated properties: | PR_WB_SF_ID
Identifier: | 0x6842
Data type: | PT_BINARY
Area: | Search

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderLastUsed Canonical Property

 Copy code hover
[image]

PidTagSearchFolderLastUsed Canonical Property
See also Send feedback

Published: July 16, 2012

Represents the last time the folder was accessed.

Associated properties: | PR_WB_SF_LAST_USED
Identifier: | 0x6834
Data type: | PT_LONG
Area: | Search

Remarks

This property must be formatted as the number of minutes since midnight Coordinated Universal Time (UTC) January 1, 1601.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderStorageType Canonical Property

 Copy code hover
[image]

PidTagSearchFolderStorageType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains flags that specify the Binary Large Object (BLOB) data that appears in the PR_WB_SF_DEFINITION (PidTagSearchFolderDefinition) property.

Associated properties: | PR_WB_SF_STORAGE_TYPE
Identifier: | 0x6846
Data type: | PT_LONG
Area: | Search

Remarks

The definitions of the flags are specified in [MS-OXOSRCH]. Search for PR_WB_SF_STORAGE_TYPE.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderTag Canonical Property

 Copy code hover
[image]

PidTagSearchFolderTag Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the value used to synchronize this definition message with the matching search folder container.

Associated properties: | PR_WB_SF_TAG
Identifier: | 0x6847
Data type: | PT_LONG
Area: | Search

Remarks

This property is changed when the definition message is changed. It must change each iteration, but it may not be unique.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchFolderTemplateId Canonical Property

 Copy code hover
[image]

PidTagSearchFolderTemplateId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the ID of the template that is being used for the search.

Associated properties: | PR_WB_SF_TEMPLATE_ID
Identifier: | 0x6841
Data type: | PT_LONG
Area: | Search

Remarks

Search folder criteria is specified by a template. This property on the message that defines the search folder identifies its corresponding template. In addition to defining search criteria, a template also defines folders to exclude from the search, defines items to exclude from the search, and specifies the value of PR_WB_SF_STORAGE_TYPE (PidTagSearchFolderStorageType).

For more information about Search Folder Templates see [MS-OXOSRCH] .

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOSRCH]

Specifies the properties and operations for manipulating a search folder list configuration.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchKey Canonical Property

 Copy code hover
[image]

PidTagSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a binary-comparable key that identifies correlated objects for a search.

Associated properties: | PR_SEARCH_KEY
Identifier: | 0x300B
Data type: | PT_BINARY
Area: | ID properties

Remarks

This property provides a trace for related objects, such as message copies, and facilitates finding unwanted occurrences, such as duplicate recipients.

MAPI uses specific rules for constructing search keys for message recipients. The search key is formed by concatenating the address type (in uppercase characters), the colon character ':', the e-mail address in canonical form, and the terminating null character. Canonical form here means that case-sensitive addresses appear in the correct case, and addresses that are not case-sensitive are converted to uppercase. This is important in preserving correlations among messages.

For message objects, this property is available through the IMAPIProp::GetProps method immediately following message creation. For other objects, it is available following the first call to the IMAPIProp::SaveChanges method. Because this property is changeable, it is unreliable to obtain it through GetProps until a SaveChanges call has committed any values set or changed by the IMAPIProp::SetProps method.

For profiles, MAPI also furnishes a hard-coded profile section named MUID_PROFILE_INSTANCE, with this property as its single property. This key is guaranteed to be unique among all profiles ever created, and can be more reliable than the PR_PROFILE_NAME (PidTagProfileName) property, which can be, for example, deleted and recreated with the same name.

The following table summarizes important differences among the PR_ENTRYID (PidTagEntryId), PR_RECORD_KEY (PidTagRecordKey), and this property.

Characteristic | PR_ENTRYID | PR_RECORD_KEY | PR_SEARCH_KEY
Required on attachment objects | No | Yes | No
Required on folder objects | Yes | Yes | No
Required on message store objects | Yes | Yes | No
Required on status objects | Yes | No | No
Creatable by client | No | No | Yes
Available before SaveChanges | Depends on the provider implementation | Depends on the provider implementation | For messages, Yes. For others, It depends on the provider implementation.
Changed in a copy operation | Yes | Yes | No
Changeable by client after a copy | No | No | Yes
Unique within ... | Entire world | Provider instance | Entire world
Binary comparable (as with memcmp) | No -- use IMAPISupport::CompareEntryIDs | Yes | Yes

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagResponsibility Canonical Property
PidTagStoreRecordKey Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSearchOwnerId Canonical Property

 Copy code hover
[image]

PidTagSearchOwnerId Canonical Property
Send feedback

Published: July 16, 2012

Contains the process ID of the process that is sending notifications to the indexer about objects ready for indexing.

Quick Info

Associated properties: | PR_SEARCH_OWNER_ID
Exposed by: | Message store object
Identifier: | 0x3419
Property type: | PT_LONG
Property tag: | 0x34190003
Access: | Read-only


PidTagSelectable Canonical Property

 Copy code hover
[image]

PidTagSelectable Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the entry in the one-off table can be selected.

Associated properties: | PR_SELECTABLE
Identifier: | 0x3609
Data type: | PT_BOOLEAN
Area: | Address book container

Remarks

This property is used primarily for visual formatting of a one-off table. Templates can be grouped by creating an entry that indicates the heading for the group. Setting this property to FALSE for the heading ensures that the user can select only the actual templates in the group and not this heading entry.

This property applies only to a one-off table, not to an address book hierarchy table.

MAPI allows an address book provider to group items visually by two means. First, certain rows can function as headings by being unselectable. Second, the selectable items can be indented relative to their headings by using the PR_DEPTH (PidTagDepth) property. This property is used in such grouping to indicate whether or not this item can be selected from a list to create a one-off address. For example, if a client has several templates for building fax addresses, it can display them as follows:

FAX templates (depth 0, not selectable)

Local (depth 1, selectable)

Long-distance (depth 1, selectable)

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABKT]

Specifies the properties and operations that are permissible for address book templates.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

IABLogon::GetOneOffTable
PidTagFolderType Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderAddressType Canonical Property

 Copy code hover
[image]

PidTagSenderAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message sender's e-mail address type.

Associated properties: | PR_SENDER_ADDRTYPE, PR_SENDER_ADDRTYPE_A, PR_SENDER_ADDRTYPE_W
Identifier: | 0x0C1E
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores "Unknown" in all the sender address properties of type PT_TSTRING.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderEmailAddress Canonical Property

 Copy code hover
[image]

PidTagSenderEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message sender's e-mail address.

Associated properties: | PR_SENDER_EMAIL_ADDRESS, PR_SENDER_EMAIL_ADDRESS_A, PR_SENDER_EMAIL_ADDRESS_W
Identifier: | 0x0C1F
Data type: | PT_UNICOIDE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the message sender. They must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores "Unknown" in all the sender address properties of type PT_TSTRING.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderEntryId Canonical Property

 Copy code hover
[image]

PidTagSenderEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message sender's entry identifier.

Associated properties: | PR_SENDER_ENTRYID
Identifier: | 0x0C19
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler an identifier corresponding to the string "Unknown" in this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderName Canonical Property

 Copy code hover
[image]

PidTagSenderName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message sender's display name.

Associated properties: | PR_SENDER_NAME, PR_SENDER_NAME_A, PR_SENDER_NAME_W
Identifier: | 0x0C1A
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores "Unknown" in all the sender address properties of type PT_TSTRING.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Describes the format of messages used to send information related to sharing folders on the client.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderSearchKey Canonical Property

 Copy code hover
[image]

PidTagSenderSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the message sender's search key.

Associated properties: | PR_SENDER_SEARCH_KEY
Identifier: | 0x0C1D
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores a key corresponding to the string "Unknown" in this property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagSearchKey Canonical Property
PidTagSentRepresentingSearchKey Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSenderSmtpAddress Canonical Property

 Copy code hover
[image]

PidTagSenderSmtpAddress Canonical Property
See also Send feedback

Contains the format of the Simple Mail Transport Protocol (SMTP) email address of the sending mailbox owner.

Associated properties: | PR_SENDER_SMTP_ADDRESS, PR_SENDER_SMTP_ADDRESS_A, PR_SENDER_SMTP_ADDRESS_W
Identifier: | 0x5D01
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

This property is an example of the address properties for the message sender. It must be set by the outgoing transport provider, which should never propagate any previously existing values.

If no transport provider has supplied any sender address properties, the MAPI spooler attempts to fill them in by calling the IMAPISession::QueryIdentity method for an entry identifier. If no entry identifiers have been provided, the MAPI spooler stores "Unknown" in all the sender address properties of type PT_UNICODE or PT_STRING8.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for email message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSendInternetEncoding Canonical Property

 Copy code hover
[image]

PidTagSendInternetEncoding Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of encoding preferences.

Associated properties: | PR_SEND_INTERNET_ENCODING
Identifier: | 0x3A71
Data type: | PT_LONG
Area: | Address

Remarks

Set this property to indicate the encoding options used.

This property contains the following flags:

BODY_ENCODING_HTML

Encode the message text in HTML. This flag is ignored unless the ENCODING_MIME flag is set.

BODY_ENCODING_TEXT_AND_HTML

Encode the message text using text and HTML as Multipurpose Internet Mail Extensions (MIME) multipart alternatives. This flag is ignored unless the ENCODING_MIME flag is set.

ENCODING_MIME

Encode the message using MIME. If this flag is not set, MAPI encodes the message text in plain text and the attachments in UUENCODE.

ENCODING_PREFERENCE

Use the other flags in this bitmask to determine the encoding. If this flag is not set, MAPI leaves it to the messaging system to make encoding decisions.

MAC_ATTACH_ENCODING_APPLEDOUBLE

Encode Macintosh attachments in Apple double mode. This flag is ignored unless the ENCODING_MIME flag is set.

MAC_ATTACH_ENCODING_APPLESINGLE

Encode Macintosh attachments in Apple single mode. This flag is ignored unless the ENCODING_MIME flag is set.

MAC_ATTACH_ENCODING_UUENCODE

Encode Macintosh attachments in UUENCODE. If the ENCODING_MIME flag is set, this flag is ignored and BinHex encoding is used instead.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSendRichInfo Canonical Property

 Copy code hover
[image]

PidTagSendRichInfo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if the recipient can receive all message content, including Rich Text Format (RTF) and Object Linking and Embedding (OLE) objects.

Associated properties: | PR_SEND_RICH_INFO
Identifier: | 0x3A40
Data type: | PT_BOOLEAN
Area: | Address

Remarks

It is recommended that distribution list and messaging user objects expose this property.

This property indicates whether the sender considers the recipient to be MAPI-enabled.

When this property is set to TRUE, the transport and gateway can transmit the full content of the message, including RTF and OLE objects. The transport provider and gateway should use Transport Neutral Encapsulation Format (TNEF) to encapsulate any properties that are not native to all the messaging systems involved.

When this property is set to FALSE, the transport provider and gateway are free to discard message content that their native clients cannot use. For example, when the clients do not support RTF, the transport provider can send only plain text.

When this property is not set, default behavior is determined by the implementation of the transport provider, message transfer agent (MTA), or gateway. Address book providers are not required to support this property. For example, a tightly coupled address book and transport provider can choose to send TNEF but never use RTF.

The client should not assume the transport provider and gateway will use TNEF on their own initiative. Some transport providers and gateways that support TNEF transmit it without regard to the value of this property, but others decline to construct or send TNEF if it is not set to TRUE.

Note Note

The setting of this property, and the decisions based on its value, are on a per-recipient basis.

By default, MAPI sets the value to TRUE. A client calling IAddrBook::CreateOneOff or a provider calling IMAPISupport::CreateOneOff can set the MAPI_SEND_NO_RICH_INFO bit in the ulFlags parameter, which causes MAPI to set this property to FALSE. One-offs created by the user interface use the value specified by the creating template.

On calls to the IAddrBook::ResolveName method when the name cannot be resolved but can be interpreted as an Internet address (SMTP), this property is set to FALSE. To be construed as an Internet address, the display name of the unresolved entry must be in the format X@Y.Z, such as "pete@pinecone.com".

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCMAIL]

from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagAttachDataObject Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSensitivity Canonical Property

 Copy code hover
[image]

PidTagSensitivity Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that indicates the message sender's opinion of the sensitivity of a message.

Associated properties: | PR_SENSITIVITY
Identifier: | 0x0036
Data type: | PT_LONG
Area: | General messaging

Remarks

It is recommended that message objects expose this property.

This property can have exactly one of the following values:

SENSITIVITY_NONE

The message has no special sensitivity.

SENSITIVITY_PERSONAL

The message is personal.

SENSITIVITY_PRIVATE

The message is private.

SENSITIVITY_COMPANY_CONFIDENTIAL

The message is designated company confidential.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentMailEntryId Canonical Property

 Copy code hover
[image]

PidTagSentMailEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the folder where the message should be moved after submission.

Associated properties: | PR_SENTMAIL_ENTRYID
Identifier: | 0x0E0A
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

This property is often copied from the PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId) property, the client application's standard Sent Items folder.

The client application uses this property with the PR_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit) property to control what happens to a message after it is submitted. Either one or the other should be set, but not both.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingAddressType Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingAddressType Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the address type for the messaging user who is represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_ADDRTYPE, PR_SENT_REPRESENTING_ADDRTYPE_A, PR_SENT_REPRESENTING_ADDRTYPE_W
Identifier: | 0x0064
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave this property unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to the PR_SENDER_ADDRTYPE (PidTagSenderAddressType) property on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagAddressType Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingEmailAddress Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingEmailAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the e-mail address for the messaging user who is represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_EMAIL_ADDRESS, PR_SENT_REPRESENTING_EMAIL_ADDRESS_A, PR_SENT_REPRESENTING_EMAIL_ADDRESS_W
Identifier: | 0x0065
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave these properties unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to the PR_SENDER_EMAIL_ADDRESS (PidTagSenderEmailAddress) property on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingEntryId Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier for the messaging user represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_ENTRYID
Identifier: | 0x0041
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave this property unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_ENTRYID (PidTagSenderEntryId) on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingName Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the display name for the messaging user represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_NAME, PR_SENT_REPRESENTING_NAME_A, PR_SENT_REPRESENTING_NAME_W
Identifier: | 0x0042
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties are examples of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave this property unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_NAME (PidTagSenderName) on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXORSS]

Specifies the properties and operations that represent RSS items.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution list objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Reference

PidTagDisplayName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingSearchKey Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingSearchKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the search key for the messaging user represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_SEARCH_KEY
Identifier: | 0x003B
Data type: | PT_BINARY
Area: | Address

Remarks

This property is one of the address properties for the messaging user who is being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave this property unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to PR_SENDER_SEARCH_KEY (PidTagSenderSearchKey) on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

[MS-OXOPOST]

Specifies the properties and operations that are permissible for post objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contact and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSentRepresentingSmtpAddress Canonical Property

 Copy code hover
[image]

PidTagSentRepresentingSmtpAddress Canonical Property
See also Send feedback

Contains the Simple Mail Transport Protocol (SMTP) email address for the messaging user who is represented by the sender.

Associated properties: | PR_SENT_REPRESENTING_SMTP_ADDRESS, PR_SENT_REPRESENTING_SMTP_ADDRESS_A, PR_SENT_REPRESENTING_SMTP_ADDRESS_W
Identifier: | 0x5D02
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

This property is an example of the address properties for the messaging user being represented by the sender. When a client application sends a message on behalf of another client, it should set all the represented sender properties to the values for that client. A messaging user sending on its own behalf typically leaves the represented sender properties unset.

The outgoing transport provider must always leave this property unchanged if it has been set by the sending client. If it is unset, the transport provider should set it to the PR_SENDER_SMTP_ADDRESS (PidTagSenderSmtpAddress) property on the outbound copy of the message, and leave it unset on the local copy.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for email message objects.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXODLGT]

Specifies methods for connecting to and configuring mailboxes as delegates, and interactions with message and calendar objects when they act on behalf of another user.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXCMAIL]

Converts from Internet standard email conventions to message objects.

[MS-OXOTASK]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServerAccountIcon Canonical Property

 Copy code hover
[image]

PidTagServerAccountIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the icon displayed in the Account Picker.

Associated properties: | PR_SERVER_ACCOUNT_ICON
Identifier: | 0x341F
Data type: | PT_BINARY
Area: | Common

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServerConnectedIcon Canonical Property

 Copy code hover
[image]

PidTagServerConnectedIcon Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the icon displayed in the status bar.

Associated properties: | PR_SERVER_CONNECTED_ICON
Identifier: | 0x341E
Data type: | PT_BINARY
Area: | Common

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServerTypeDisplayName Canonical Property

 Copy code hover
[image]

PidTagServerTypeDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Specifies the Unicode string to display in the status bar with this property.

Associated properties: | PR_SERVER_TYPE_DISPLAY_NAME
Identifier: | 0x341D
Data type: | PT_BINARY
Area: | Common

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceDeleteFiles Canonical Property

 Copy code hover
[image]

PidTagServiceDeleteFiles Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of filenames that are to be deleted when the message service is uninstalled.

Associated properties: | PR_SERVICE_DELETE_FILES, PR_SERVICE_DELETE_FILES_A, PR_SERVICE_DELETE_FILES_W
Identifier: | 0x3D10
Data type: | PT_MV_STRING8, PT_MV_UNICODE
Area: | MAPI profile

Remarks

The filenames in the list contained in these properties are deleted from the computer when using the control panel to uninstall the message service. Do not include in the list any DLL that supports multiple message services, or additional message services could be inadvertently removed.

MAPI works only with filenames, and other strings passed to it, in the ANSI character set. Applications that use filenames in an OEM character set must convert them to ANSI before calling MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceDllName Canonical Property

 Copy code hover
[image]

PidTagServiceDllName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the filename of the DLL containing the message service provider entry point function to call for configuration.

Associated properties: | PR_SERVICE_DLL_NAME, PR_SERVICE_DLL_NAME_A, PR_SERVICE_DLL_NAME_W
Identifier: | 0x3D0A
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI profile

Remarks

When the entry point function name appears in the PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) method, it indicates that the entry point exists.

MAPI uses a DLL file naming convention. The base filename contains up to six characters that uniquely identify the DLL. MAPI appends the string 32 to the base DLL name to identify the version that runs on 32-bit platforms. For example, when the name MAPI.DLL is specified, MAPI constructs the name MAPI32.DLL to represent the corresponding 32-bit version of the DLL.

These properties should specify the base name. MAPI appends the string 32 as appropriate. Including the string 32 as part of these properties result in an error.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagProviderDllName Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceEntryName Canonical Property

 Copy code hover
[image]

PidTagServiceEntryName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the entry point function for configuration of a message service.

Associated properties: | PR_SERVICE_ENTRY_NAME
Identifier: | 0x3D0B
Data type: | PT_STRING8
Area: | MAPI profile

Remarks

It is recommended that message service implementers provide a message service entry point, but the entry point is not required. However, the entry point should be supplied only if the related configuration properties exist. If these properties do not exist, MAPI assumes that no entry point is provided.

The dynamic-link library (DLL) in which the entry point function appears is named by the PR_SERVICE_DLL_NAME (PidTagServiceDllName) property.

For more information on message service entry points, see Implementing a Service Provider Entry Point Function.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceExtraUids Canonical Property

 Copy code hover
[image]

PidTagServiceExtraUids Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of MAPIUID structures that identify additional profile sections for the message service.

Associated properties: | PR_SERVICE_EXTRA_UIDS
Identifier: | 0x3D0D
Data type: | PT_BINARY
Area: | MAPI profile

Remarks

New profile sections can be created for each message filter. When the information about the message service is to be copied to another profile, it is important to copy the additional profile sections for the filters as well. A service provider that uses additional profile sections can store the MAPIUID structures of those profile sections in PR_SERVICE_EXTRA_UIDS, which allows MAPI to copy the additional message service information.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceInstallId Canonical Property

 Copy code hover
[image]

PidTagServiceInstallId Canonical Property
See also Send feedback

Published: July 16, 2012

The component ID of the provider.

Associated properties: | PR_SERVICE_INSTALL_ID, PR_SERVICE_INSTALL_ID_A, PR_SERVICE_INSTALL_ID_W
Identifier: | 0x3D13
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI profile

Remarks

These properties may be used as the component parameter of an MsiProvideQualifiedComponent call to install the provider.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceName Canonical Property

 Copy code hover
[image]

PidTagServiceName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of a message service as set by the user in the MapiSvc.inf file.

Associated properties: | PR_SERVICE_NAME, PR_SERVICE_NAME_A, PR_SERVICE_NAME_W
Identifier: | 0x3D09
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI profile

Remarks

The name contained in these properties is specific to the message service. It comes from the [Services] section in MapiSvc.inf.

These properties appear as a column in the message service table and can be used to filter services. Because it is used to identify and filter services, the value should not be localized.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServices Canonical Property

 Copy code hover
[image]

PidTagServices Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of identifiers of message services in the current profile.

Associated properties: | PR_SERVICES
Identifier: | 0x3D0E
Data type: | PT_BINARY
Area: | MAPI profile

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

MAPIUID

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceSupportFiles Canonical Property

 Copy code hover
[image]

PidTagServiceSupportFiles Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of the files that belong to the message service.

Associated properties: | PR_SERVICE_SUPPORT_FILES, PR_SERVICE_SUPPORT_FILES_A, PR_SERVICE_SUPPORT_FILES_W
Identifier: | 0x3D0F
Data type: | PT_MV_STRING8, PT_MV_UNICODE
Area: | MAPI profile

Remarks

Using a dialog box in the control panel applet, a user can obtain the list of files that belong to the message service. For example, the user can obtain the names of all dynamic-link libraries (DLLs) that belong to the service. The user can then seek additional details about the specified files, such as the names and version numbers of all the DLLs. MAPI uses the these properties to create a support file list in a dialog box for messaging user selection.

MAPI works only with filenames, and other strings passed to it, in the Active Directory Service Interfaces (ANSI) character set. Client applications that use filenames in an original equipment manufacturer (OEM) character set must convert them to ANSI before calling MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagServiceUid Canonical Property

 Copy code hover
[image]

PidTagServiceUid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the MAPIUID structure for a message service.

Associated properties: | PR_SERVICE_UID
Identifier: | 0x3D0C
Data type: | PT_BINARY
Area: | MAPI profile

Remarks

This property is computed by MAPI on profile section objects. MAPI uses it to group all the providers that belong to the same message service. This property is supplied as a parameter to most of the IMsgServiceAdmin methods. It must not appear in Mapisvc.inf.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMsgServiceAdmin : IUnknown

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSmtpAddress Canonical Property

 Copy code hover
[image]

PidTagSmtpAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the SMTP address for the address book object.

Associated properties: | PR_SMTP_ADDRESS, PR_SMTP_ADDRESS_A, PR_SMTP_ADDRESS_W
Identifier: | 0x39FE
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-NSPI]

Handles a client's communications with a Name Service Provider Interface (NSPI) server.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOAB]

Specifies the offline address book (OAB) file formats for the local address book objects cache.

[MS-OXOMSG]

Specifies the properties and operations that are permissible for e-mail message objects.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpamJunkSenders Canonical Property

 Copy code hover
[image]

PidTagSpamJunkSenders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a semicolon-delimited list of email addresses and domains that comprise blocked senders.

Associated properties: | PR_SPAM_JUNK_SENDERS_W
Long ID (LID): | 0x041A
Data type: | PT_UNICODE
Area: | Spam

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk email messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpamThreshold Canonical Property

 Copy code hover
[image]

PidTagSpamThreshold Canonical Property
See also Send feedback

Published: July 16, 2012

A long value that indicates the level of spam filtering.

Associated properties: | PR_SPAM_THRESHOLD
Long ID (LID): | 0x041B
Data type: | PT_LONG
Area: | Spam

Values

The values for spam filtering are as follows:

Spam Level | Value
None | 0xFFFFFFFF
Low | 0x00000006
Medium | 0x00000005
High | 0x00000003

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk email messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpamTrustedRecipients Canonical Property

 Copy code hover
[image]

PidTagSpamTrustedRecipients Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a semicolon-delimited list of email addresses and domains that represent the trusted recipients.

Associated properties: | PR_SPAM_TRUSTED_RECIPIENTS_W
Long ID (LID): | 0x0419
Data type: | PT_UNICODE
Area: | Spam

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk email messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties that are listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpamTrustedSenders Canonical Property

 Copy code hover
[image]

PidTagSpamTrustedSenders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a semicolon-delimited list of email addresses and domains that are made up of trusted senders.

Associated properties: | PR_SPAM_TRUSTED_SENDERS_W
Long ID (LID): | 0x0418
Data type: | PT_UNICODE
Area: | Spam

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

[MS-OXCSPAM]

Enables the handling of allow/block lists and the determination of junk email messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties that are listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpoolerStatus Canonical Property

 Copy code hover
[image]

PidTagSpoolerStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the status of the message based on information that is available to the MAPI spooler.

Associated properties: | PR_SPOOLER_STATUS
Identifier: | 0x0E10
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

This property is computed by MAPI on message objects.

This property appears on inbound messages only and is reserved in all other cases. It indicates whether or not a message has been delivered to its final location or whether a messaging hook provider potentially deleted the message while rerouting it.

Client applications should never set this property. For an inbound message, a client or service provider can call IMAPIProp::GetProps on this property to determine the message status. The value S_OK indicates that the message was successfully delivered to the message store. The value MAPI_E_OBJECT_DELETED indicates that the message was deleted and was never committed to the store.

Message store providers should support this property on messages, recipient tables, and the outgoing queue table. Clients and providers should be able to set columns on the outgoing queue table and restrict based on this property.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSpouseName Canonical Property

 Copy code hover
[image]

PidTagSpouseName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the user's spouse name.

Associated properties: | PR_SPOUSE_NAME, PR_SPOUSE_NAME_A, PR_SPOUSE_NAME_W
Identifier: | 0x3A48
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties are defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStartDate Canonical Property

 Copy code hover
[image]

PidTagStartDate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the starting date and time of an appointment as managed by a scheduling application.

Associated properties: | PR_START_DATE
Identifier: | 0x0060
Data type: | PT_SYSTIME
Area: | MAPI envelope

Remarks

Scheduling applications should set both this property and PR_END_DATE (PidTagEndDate) properties when sending meeting requests.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCAL]

Specifies the properties and operations for appointment, meeting request, and response messages.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStateOrProvince Canonical Property

 Copy code hover
[image]

PidTagStateOrProvince Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of the recipient's state or province.

Associated properties: | PR_STATE_OR_PROVINCE, PR_STATE_OR_PROVINCE_A, PR_STATE_OR_PROVINCE_W, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_A, PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE_W
Identifier: | 0x3A28
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStatus Canonical Property

 Copy code hover
[image]

PidTagStatus Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a 32-bit bitmask of flags that define folder status.

Associated properties: | PR_STATUS
Identifier: | 0x360B
Data type: | PT_LONG
Area: | MAPI container

Remarks

This property for folders is analogous to the PR_MSG_STATUS (PidTagMessageStatus) property for messages. Its flags are provided for the client application only and do not affect the message store. Clients can use or ignore these settings. The client can also define its own values for the client-definable bits of this property.

One or more of the following flags can be set for the bitmask:

FLDSTATUS_DELMARKED

The folder is marked for deletion. The client application sets this flag.

FLDSTATUS_HIDDEN

The folder is hidden.

FLDSTATUS_HIGHLIGHTED

The folder is highlighted, for example, shown in reverse video.

FLDSTATUS_TAGGED

The folder is tagged.

Message store providers set this property on a folder to one or more of these values and clients interpret the status as appropriate for their applications. For example, a client can use the folder status to visually differentiate between folders in a hierarchy table, displaying folders with the same status in the same way. Highlighted folders can be shown in reverse video, tagged folders and folders marked for deletion can be shown with a meaningful icon, and hidden folders can be concealed.

Bits 16 through 31 ("0x10000" through "0x80000000") of this property are available for use by the IPM client application. All other bits are reserved for use by MAPI; those not defined in the preceding list should be initially set to zero and not altered.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStatusCode Canonical Property

 Copy code hover
[image]

PidTagStatusCode Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that indicate the current status of a session resource. All service providers set status codes as does MAPI to report on the status of the subsystem, the MAPI spooler, and the integrated address book.

Associated properties: | PR_STATUS_CODE
Identifier: | 0x3E04
Data type: | PT_LONG
Area: | MAPI status

Remarks

The status code must appear in the Mapisvc.inf file for all providers.

Status objects are implemented by MAPI and by all service providers. There are two sets of valid values for status codes, one set for all status objects and another set for transport providers only. All status objects can set this property to the following values:

STATUS_AVAILABLE

Indicates that the resource is operational.

STATUS_FAILURE

Indicates that the resource is experiencing a problem. For service providers, STATUS_FAILURE indicates that the provider might soon be shut down to end the current session.

STATUS_OFFLINE

Indicates that only local data or services are available.

Transport providers can also set their status objects' PR_STATUS_CODE properties to the following values:

STATUS_INBOUND_ACTIVE

Indicates that the transport provider is receiving an inbound message.

STATUS_INBOUND_ENABLED

Indicates that the transport provider can receive inbound messages.

STATUS_INBOUND_FLUSH

Indicates that the transport provider is downloading messages from the inbound queue.

STATUS_OUTBOUND_ACTIVE

Indicates that the transport provider is receiving an outbound message.

STATUS_OUTBOUND_ENABLED

Indicates that the transport provider can handle outbound messages.

STATUS_OUTBOUND_FLUSH

Indicates that the transport provider is uploading messages from its outbound queue.

STATUS_REMOTE_ACCESS

Indicates that the transport provider supports remote access.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagStatusString Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStatusString Canonical Property

 Copy code hover
[image]

PidTagStatusString Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message that indicates the current status of a session resource.

Associated properties: | PR_STATUS_STRING, PR_STATUS_STRING_A, PR_STATUS_STRING_W
Identifier: | 0x3E08
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI status

Remarks

These properties give service providers and MAPI the opportunity to supply specific information about the status of a session resource, such as the integrated address book or a particular service provider. This property explains and provides additional information about a status code, or the PR_STATUS_CODE (PidTagStatusCode) property. Whereas PR_STATUS_CODE is required for all status objects, PR_STATUS_STRING and associated properties are optional. When the transport provider does not supply a value, the MAPI spooler supplies a default value.

The string is generated on the same side of the remote procedure call as the MAPI spooler; it travels through shared memory rather than being marshaled across a process boundary.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagStatusCode Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreEntryId Canonical Property

 Copy code hover
[image]

PidTagStoreEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the unique entry identifier of the message store where an object resides.

Associated properties: | PR_STORE_ENTRYID
Identifier: | 0x0FFB
Data type: | PT_BINARY
Area: | ID properties

Remarks

This property is used to open a message store with the IMAPISession::OpenMsgStore method. It is also used to open any object that is owned by the message store.

For a message store, this property is identical to the store's own PR_ENTRYID (PidTagEntryId) property. A client application can compare the two properties using the IMAPISession::CompareEntryIDs method.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXSHARE]

Shares mailbox folders between clients.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreEntryIdEmsmdbV1 Canonical Property

 Copy code hover
[image]

PidTagStoreEntryIdEmsmdbV1 Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the old style (Microsoft Outlook 2002 and earlier versions) of the entry identifier of a Microsoft Exchange Server 2010 or Exchange Server 2013 message store.

Associated properties: | PR_STORE_ENTRYID_EMSMDB_V1
Identifier: | 0x65F60102
Data type: | PT_BINARY
Area: | ID properties

Remarks

Starting with Microsoft Outlook 2003, the server FQDNs were integrated into the entry IDs, thereby avoiding additional RPCs for referrals. However, this makes entry IDs longer and introduces more scenarios where the CompareEntryIDs method must be used to determine whether two entry IDs are equivalent. The PR_STORE_ENTRYID_EMSMDB_V1 (PidTagStoreIdEmsbdbV1) property accesses the older format of the Exchange Server entry ID used by Microsoft Outlook 2002 (Microsoft Office XP) and earlier versions. This can save space and also reduce the number of CompareEntryIDs calls needed to determine when entry IDs are equivalent. Note that using the older entry IDs to open a mailbox may incur some additional RPCs if a referral is required.

To access the PR_STORE_ENTRYID_EMSMDB_V1 property while in cached mode, you must bypass the cache using the MAPI_NO_CACHE flag with the IMAPIProp::GetProps method. If PR_STORE_ENTRYID_EMSMDB_V1 isn't available, the code should fall back to PR_STORE_ENTRYID. Only Outlook 2003 through Microsoft Outlook 2013 support the PR_STORE_ENTRYID_EMSMDB_V1 property.

See also

Reference

PidTagStoreEntryId Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreProvider Canonical Property

 Copy code hover
[image]

PidTagStoreProvider Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a provider-defined MAPIUID structure that indicates the type of the message store.

Associated properties: | PR_MDB_PROVIDER
Identifier: | 0x3414
Data type: | PT_BINARY
Area: | ID properties

Remarks

The MAPIUID structure identifies the type of message store. The value is computed by message store providers on message store objects and is unique to each provider. It is typically used for browsing through the message store table to find a store of the desired type, such as public folders.

This property is analogous to the PR_AB_PROVIDER_ID (PidTagAbProviderId) property for address books.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreProviders Canonical Property

 Copy code hover
[image]

PidTagStoreProviders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of identifiers of message store providers in the current profile.

Associated properties: | PR_STORE_PROVIDERS
Identifier: | 0x3D00
Data type: | PT_BINARY
Area: | MAPI profile

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

MAPIUID

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreRecordKey Canonical Property

 Copy code hover
[image]

PidTagStoreRecordKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the unique binary-comparable identifier (record key) of the message store in which an object resides.

Associated properties: | PR_STORE_RECORD_KEY
Identifier: | 0x0FFA
Data type: | PT_BINARY
Area: | ID properties

Remarks

For a message store, this property is identical to the store's own PR_RECORD_KEY (PidTagRecordKey) property.

The relationship between this property and PR_RECORD_KEY is the same as the relationship between PR_STORE_ENTRYID (PidTagStoreEntryId) and PR_ENTRYID (PidTagEntryId).

Related Resources

Protocol Specifications

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreState Canonical Property

 Copy code hover
[image]

PidTagStoreState Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a flag that describes the state of the message store.

Associated properties: | PR_STORE_STATE
Identifier: | 0x340E
Data type: | PT_LONG
Area: | MAPI message store

Remarks

This property is dynamic and can change based on user actions, unlike the PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property.

The following value can be set:

STORE_HAS_SEARCHES

The user has created one or more active searches in the store.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCSTOR]

Specifies permissible operations for the core message store objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreSupportMask Canonical Property

 Copy code hover
[image]

PidTagStoreSupportMask Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that client applications query to determine the characteristics of a message store.

Associated properties: | PR_STORE_SUPPORT_MASK
Identifier: | 0x340D
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

This property discloses the capabilities of a message store to client applications that are planning to send it a message. The flags can support decisions by a client or another store, such as whether to send PR_BODY (PidTagBody) or only PR_RTF_COMPRESSED (PidTagRtfCompressed). A client should never set PR_STORE_SUPPORT_MASK; an attempt to set this flag returns MAPI_E_COMPUTED.

One or more of the following flags can be set for the PR_STORE_SUPPORT_MASK bitmask:

STORE_ANSI_OK

(131072, 0x00020000) The message store supports properties that contain ANSI (8-bit) characters.

STORE_ATTACH_OK

(32, 0x00000020) The message store supports attachments (OLE or non-OLE) to messages.

STORE_CATEGORIZE_OK

(1024, 0x00000400) The message store supports categorized views of tables.

STORE_CREATE_OK

(16, 0x00000010) The message store supports creation of new messages.

STORE_ENTRYID_UNIQUE

(1, 0x00000001) Entry identifiers for the objects in the message store are unique, that is, never reused during the life of the store.

STORE_HTML_OK

(65536, 0x00010000) The message store supports HTML messages, stored in the PR_BODY_HTML (PidTagBodyHtml) property. If your development environment uses a MAPIDEFS.H file that does not include STORE_HTML_OK, use the value 0x00010000 instead.

STORE_ITEMPROC

(2097152, 0x00200000) In a wrapped PST store, indicates that when a new message arrives at the store, the store performs rules and spam filter processing on the message separately. The store calls IMAPISupport::Notify, setting fnevNewMail in the NOTIFICATION structure that is passed as a parameter, and then passes the details of the new message to the listening client. Subsequently, when the listening client receives the notification, it does not process rules on the message.

STORE_LOCALSTORE

(524288, 0x00080000) This flag is reserved and should not be used.

STORE_MODIFY_OK

(8, 0x00000008) The message store supports modification of its existing messages.

STORE_MV_PROPS_OK

(512, 0x00000200) The message store supports multivalued properties, guarantees the stability of value order in a multivalued property throughout a save operation, and supports instantiation of multivalued properties in tables.

STORE_NOTIFY_OK

(256, 0x00000100) The message store supports notifications.

STORE_OLE_OK

(64, 0x00000040) The message store supports OLE attachments. The OLE data can be accessed through an IStorage interface, such as that available through the PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property.

STORE_PUBLIC_FOLDERS

(16384, 0x00004000) The folders in this store are public (multi-user), not private (possibly multi-instance but not multi-user).

STORE_PUSHER_OK

(8388608, 0x00800000) The MAPI Protocol Handler will not crawl the store, and the store is responsible for pushing any changes through notifications to the indexer to have messages indexed.

STORE_READONLY

(2, 0x00000002) All interfaces for the message store have a read-only access level.

STORE_RESTRICTION_OK

(4096, 0x00001000) The message store supports restrictions.

STORE_RTF_OK

(2048, 0x00000800) The message store supports Rich Text Format (RTF) messages, usually compressed, and the store itself keeps PR_BODY and PR_RTF_COMPRESSED synchronized.

STORE_RULES_OK

(268435456, 0x10000000) Indicates that rules should be stored in this PST store even if it is not the default store. When STORE_RULES_OK is used in conjunction with NON_EMS_XP_SAVE, rules are able to run on non-default PST wrapped stores.

STORE_SEARCH_OK

(4, 0x00000004) The message store supports search-results folders.

STORE_SORT_OK

(8192, 0x00002000) The message store supports sorting views of tables.

STORE_SUBMIT_OK

(128, 0x00000080) The message store supports marking a message for submission.

STORE_UNCOMPRESSED_RTF

(32768, 0x00008000) The message store supports storage of RTF messages in uncompressed form. An uncompressed RTF stream is identified by the value dwMagicUncompressedRTF in the stream header. The dwMagicUncompressedRTF value is defined in the RTFLIB.H file.

STORE_UNICODE_OK

(262144, 0x00040000) Indicates that the message store supports Unicode storage. A client can look for the presence of the flag to decide whether to request or to save Unicode information to the store.

An RTF version of a message can always be stored, even if the message store is non-RTF-aware. If the STORE_RTF_OK bit is not set for a particular store, a client maintaining RTF versions must itself call the RTFSync function to keep the PR_BODY and PR_RTF_COMPRESSED versions synchronized for text content. RTF is always stored in PR_RTF_COMPRESSED, whether it is actually compressed or not.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXMSG]

Describes the format of messages used to send information related to sharing folders on the client.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStoreUnicodeMask Canonical Property

 Copy code hover
[image]

PidTagStoreUnicodeMask Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that client applications should query to determine the characteristics of a message store.

Associated properties: | PR_STORE_UNICODE_MASK
Identifier: | 0x340F
Data type: | PT_LONG
Area: | MAPI message store

Remarks

This property discloses the capabilities of a message store to client applications planning to send it a message. The flags can facilitate decisions by a client or another store, such as whether to send PR_BODY (PidTagBody) or only PR_RTF_COMPRESSED (PidTagRtfCompressed). A client should never set this property. An attempt returns MAPI_E_COMPUTED.

One or more of the following flags can be set for this property:

STORE_ANSI_OK

(131072, 0x00020000) The message store supports properties that contain American National Standards Institute (ANSI) (8-bit) characters.

STORE_ATTACH_OK

(32, 0x00000020) The message store supports Object Linking and Embedding (OLE) or non-OLE attachments to messages.

STORE_CATEGORIZE_OK

(1024, 0x00000400) The message store supports categorized views of tables.

STORE_CREATE_OK

(16, 0x00000010) The message store supports creation of new messages.

STORE_ENTRYID_UNIQUE

(1, 0x00000001) Entry identifiers for the objects in the message store are unique, that is, never reused during the life of the store.

STORE_HTML_OK

(65536, 0x00010000) The message store supports HTML messages, stored in the PR_BODY_HTML (PidTagBodyHtml) property. Note that STORE_HTML_OK is not defined in versions of MAPIDEFS.H that are included with Microsoft Exchange 2000 Server and earlier. If your development environment uses a MAPIDEFS.H file that does not include STORE_HTML_OK, use the value "0x00010000" instead.

STORE_ITEMPROC

(2097152, 0x00200000) In a wrapped PST store, indicates that when a new message arrives at the store, the store does rules and spam filter processing on the message separately. The store calls IMAPISupport::Notify, setting fnevNewMail in the NOTIFICATION structure that is passed as a parameter, and then passes the details of the new message to the listening client. Subsequently, when the listening client receives the notification, it does not process rules on the message.

STORE_LOCALSTORE

(524288, 0x00080000) This flag is reserved and should not be used.

STORE_MODIFY_OK

(8, 0x00000008) The message store supports modification of its existing messages.

STORE_MV_PROPS_OK

(512, 0x00000200) The message store supports multivalued properties, guarantees the stability of value order in a multivalued property throughout a save operation, and supports instantiation of multivalued properties in tables.

STORE_NOTIFY_OK

(256, 0x00000100) The message store supports notifications.

STORE_OLE_OK

(64, 0x00000040) The message store supports OLE attachments. The OLE data is accessible through an IStorage interface, such as that available through the PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) property.

STORE_PUBLIC_FOLDERS

(16384, 0x00004000) The folders in this store are public (multi-user), not private (possibly multi-instance but not multi-user).

STORE_PUSHER_OK

(8388608, 0x00800000) The MAPI Protocol Handler will not crawl the store, and the store is responsible to push any changes through notifications to the indexer to have messages indexed.

STORE_READONLY

(2, 0x00000002) All interfaces for the message store have a read-only access level.

STORE_RESTRICTION_OK

(4096, 0x00001000) The message store supports restrictions.

STORE_RTF_OK

(2048, 0x00000800) The message store supports Rich Text Format (RTF) messages, usually compressed, and the store itself keeps PR_BODY and PR_RTF_COMPRESSED synchronized.

STORE_SEARCH_OK

(4, 0x00000004) The message store supports search-results folders.

STORE_SORT_OK

(8192, 0x00002000) The message store supports sorting views of tables.

STORE_SUBMIT_OK

(128, 0x00000080) The message store supports marking a message for submission.

STORE_UNCOMPRESSED_RTF

(32768, 0x00008000) The message store supports storage of revisable form text (RTF) messages in uncompressed form. An uncompressed RTF stream is identified by the value dwMagicUncompressedRTF in the stream header. The dwMagicUncompressedRTF value is defined in the RTFLIB.H file.

STORE_UNICODE_OK

(262144, 0x00040000) The message store supports properties containing Unicode characters.

An RTF version of a message can always be stored, even if the message store is non-RTF-aware. If the STORE_RTF_OK bit is not set for a particular store, a client maintaining RTF versions must itself call the RTFSync function to keep the PR_BODY and PR_RTF_COMPRESSED versions synchronized for text content. RTF is always stored in PR_RTF_COMPRESSED, whether it is actually compressed or not.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagStreetAddress Canonical Property

 Copy code hover
[image]

PidTagStreetAddress Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's street address.

Associated properties: | PR_STREET_ADDRESS, PR_STREET_ADDRESS_A, PR_STREET_ADDRESS_W, PR_BUSINESS_ADDRESS_STREET, PR_BUSINESS_ADDRESS_STREET_A, PR_BUSINESS_ADDRESS_STREET_W
Identifier: | 0x3A29
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSubfolders Canonical Property

 Copy code hover
[image]

PidTagSubfolders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains TRUE if a folder contains subfolders.

Associated properties: | PR_SUBFOLDERS
Identifier: | 0x360A
Data type: | PT_BOOLEAN
Area: | MAPI container

Remarks

Message stores must supply this property for all folders.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFOLD]

Handles folder operations.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSubject Canonical Property

 Copy code hover
[image]

PidTagSubject Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the full subject of a message.

Associated properties: | PR_SUBJECT, PR_SUBJECT_A, PR_SUBJECT_W
Identifier: | 0x0037
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are recommended on all message objects.

These properties are always the full subject text, that is, the concatenation of the prefix and the normalized subject. If there is no prefix, the normalized subject should be the same as the subject. A message store or transport provider uses both these properties and PR_SUBJECT_PREFIX (PidTagSubjectPrefix) properties to compute the normalized subject using the rule described under PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject).

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the IStream interface on them. The client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.

For a report, this property contains the original message's subject preceded by a string indicating what has happened to the message.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSubjectMessageId Canonical Property

 Copy code hover
[image]

PidTagSubjectMessageId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a binary value that is copied from the message for which a report is being generated.

Associated properties: | PR_SUBJECT_IPM
Identifier: | 0x0038
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

This property, like the PR_REPORT_TAG (PidTagReportTag) property, can be used to correlate a report with the original message.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSubjectPrefix Canonical Property

 Copy code hover
[image]

PidTagSubjectPrefix Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a subject prefix that typically indicates some action on a message, such as "FW: " for forwarding.

Associated properties: | PR_SUBJECT_PREFIX, PR_SUBJECT_PREFIX_A, PR_SUBJECT_PREFIX_W
Identifier: | 0x003D
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties are recommended on all message objects.

The subject prefix consists of one or more alphanumeric characters, followed by a colon and a space (which are part of the prefix). It must not contain any nonalphanumeric characters before the colon. Absence of a prefix can be represented by an empty string or by this property not being set.

If these properties are set explicitly, the string can be of any length and use any alphanumeric characters, but it must match a substring at the beginning of the PR_SUBJECT (PidTagSubject) property. If these properties are not set by the sender and must be computed, their contents are more restricted. The rule for computing the prefix is that PR_SUBJECT must begin with one, two, or three letters (alphabetic only) followed by a colon and a space. If such a substring is found at the beginning of PR_SUBJECT, it then becomes the string for these properties (and also stays at the beginning of PR_SUBJECT). Otherwise, these properties remain unset.

These properties and PR_NORMALIZED_SUBJECT (PidTagNormalizedSubject) should be computed as part of the IMAPIProp::SaveChanges implementation. A client should not prompt IMAPIProp::GetProps for their values until they have been committed by an IMAPIProp::SaveChanges call.

The subject properties are typically small strings of fewer than 256 characters, and a message store provider is not obligated to support the OLE IStream interface on them. A client should always attempt access through the IMAPIProp interface first, and resort to IStream only if MAPI_E_NOT_ENOUGH_MEMORY is returned.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSubmitFlags Canonical Property

 Copy code hover
[image]

PidTagSubmitFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags indicating details about a message submission.

Associated properties: | PR_SUBMIT_FLAGS
Identifier: | 0x0E14
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

One or more of the following flags can be set for the PR_SUBMIT_FLAGS bitmask:

SUBMITFLAG_LOCKED

The MAPI spooler currently has the message locked.

SUBMITFLAG_PREPROCESS

The message needs preprocessing. When the MAPI spooler is done preprocessing this message, it should call the IMessage::SubmitMessage method. The message store provider recognizes that the spooler, rather than the client application, has called SubmitMessage, clears the flag, and continues message submission.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCICAL]

Converts between IETF RFC2445, RFC2446, and RFC2447, and appointment and meeting objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

IMsgStore::SetLockState

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSupplementaryInfo Canonical Property

 Copy code hover
[image]

PidTagSupplementaryInfo Canonical Property
See also Send feedback

Published: July 16, 2012

Contains additional information for use in a report.

Associated properties: | PR_SUPPLEMENTARY_INFO, PR_SUPPLEMENTARY_INFO_A, PR_SUPPLEMENTARY_INFO_W
Identifier: | 0x0C1B
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI recipient

Remarks

These properties contain information generated by the message transfer agent or transport provider related to the report. It is typically used for delivery or nondelivery report text that originated with the underlying messaging system.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSurname Canonical Property

 Copy code hover
[image]

PidTagSurname Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the last or surname of the recipient.

Associated properties: | PR_SURNAME, PR_SURNAME_A, PR_SURNAME_W
Identifier: | 0x3A11
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSwappedToDoData Canonical Property

 Copy code hover
[image]

PidTagSwappedToDoData Canonical Property
See also Send feedback

Published: July 16, 2012

Maintains a second set of property values that do not affect the flagged state of the Message object.

Associated properties: | PR_SWAPPED_TODO_DATA
Identifier: | 0x0E2D
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

Acting as the secondary flag storage location if sender flags or sender reminders are supported, this structure provides a location in which to store all of the properties relating to the Informational Flagging Protocol that are supported in sender flags, and all properties relating to the Reminder Settings Protocol that are supported in sender reminders without exposing the sender flag or sender reminder information to the recipients of a message.

Similarly, this structure provides a location in which to store all of the properties relating to the Informational Flagging Protocol that are supported in recipient flags and properties relating to the Reminder Settings Protocol that are supported in recipient reminders on a previously sent message.

For more information about this property, see [MS-OXOFLAG].

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagSwappedToDoStore Canonical Property

 Copy code hover
[image]

PidTagSwappedToDoStore Canonical Property
See also Send feedback

Published: July 16, 2012

Determines the need for post-transmit processing of an e-mail.

Associated properties: | PR_SWAPPED_TODO_STORE
Identifier: | 0x0E2C
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

If this property is set on a draft message, then its value must be set to the value of PR_STORE_ENTRYID (PidTagStoreEntryId) property of the message.

For more information, see [MS-OXOFLAG] section "Post-Transmit Processing of a Flagged Message."

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

[MS-OXORMDR]

Specifies the properties and the interaction model for e-mail and other object reminders.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTelecommunicationsDeviceForDeafTelephoneNumber Canonical Property

 Copy code hover
[image]

PidTagTelecommunicationsDeviceForDeafTelephoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the messaging user's Telecommunications Device for the Deaf (TTYTDD) telephone number.

Associated properties: | PR_TTYTDD_PHONE_NUMBER, PR_TTYTDD_PHONE_NUMBER_A, PR_TTYTDD_PHONE_NUMBER_W
Identifier: | 0x3A4B
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information about a messaging user. The content is defined by the messaging user and the messaging user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTelexNumber Canonical Property

 Copy code hover
[image]

PidTagTelexNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's telex number.

Associated properties: | PR_TELEX_NUMBER, PR_TELEX_NUMBER_A, PR_TELEX_NUMBER_W
Identifier: | 0x3A2C
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. These properties are defined by the recipient and the recipient's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTemplateid Canonical Property

 Copy code hover
[image]

PidTagTemplateid Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the PR_ENTRYID (PidTagEntryId), expressed as a permanent entry ID format.

Associated properties: | PR_TEMPLATEID
Identifier: | 0x3902
Data type: | PT_BINARY
Area: | MAPI Address Book

Remarks

This value must be present for all address book objects on an Name Service Provider Interface (NSPI) server, its distinguished name (DN) must match the value for PR_EMAIL_ADDRESS (PidTagEmailAddress), and its DN must follow the DN format specification particular to the type of object.

This property is not present on objects in an offline address book.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTextAttachmentCharset Canonical Property

 Copy code hover
[image]

PidTagTextAttachmentCharset Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a message attachment's character set value.

Associated properties: | None
Identifier: | 0x371B
Data type: | PT_UNICODE
Area: | Message attachment

Remarks

This property's data is derived from a Content-Type MIME header field that starts with "text/", if a "charset" parameter is present.

Related Resources

Protocol Specifications

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTitle Canonical Property

 Copy code hover
[image]

PidTagTitle Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the recipient's job title.

Associated properties: | PR_TITLE, PR_TITLE_A, PR_TITLE_W
Identifier: | 0x3A17
Data type: | PT_STRING8, PT_UNICODE
Area: | MAPI mail user

Remarks

These properties provide identification and access information for a recipient. They are defined by the recipient and the recipient's organization.

These properties are commonly used to indicate the recipient's formal job title, such as Senior Programmer, rather than occupational class, such as programmer. It is not typically used for "suffix" titles such as Esq. or DDS.

Common values for this property include: Managing Director, Programmer II, Associate Professor, and Development Lead.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTnefCorrelationKey Canonical Property

 Copy code hover
[image]

PidTagTnefCorrelationKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value that correlates a Transport Neutral Encapsulation Format (TNEF) attachment with a message.

Associated properties: | PR_TNEF_CORRELATION_KEY
Identifier: | 0x007F
Data type: | PT_BINARY
Area: | MAPI envelope

Remarks

It is recommended that TNEF attachment sub-objects expose this property. This property determines whether or not an inbound TNEF file belongs to the message it is attached to. It is used primarily by transport providers and gateways.

On an outbound message, the transport provider should compute a binary value unique to that message, or use an existing value that satisfies the uniqueness requirement, such as a message identifier. The transport provider should store this value in this property and then call the ITnef::AddProps method to encapsulate it. The same value should also be stored in the transport envelope in a place defined by the provider, such as the message header.

On an inbound message, the transport provider should call the ITnef::ExtractProps method to decapsulate the TNEF attachment and then compare this property with the value stored in the transport envelope. If the values match, TNEF should be processed normally, that is, all the properties extracted from the TNEF attachment should be used. If the values do not match, all the properties from the TNEF attachment should be ignored. If this property is not set, the TNEF file should be considered to belong to this message, and the other properties extracted from it should be used.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTnefUnprocessedProps Canonical Property

 Copy code hover
[image]

PidTagTnefUnprocessedProps Canonical Property
See also Send feedback

Published: July 16, 2012

Serializes properties when filtering Transport Neutral Encapsulation Format (TNEF).

Associated properties: | PR_TNEF_UNPROCESSED_PROPS
Identifier: | 0x0E9C
Data type: | PT_BINARY
Area: | MAPI non-transmittable

Remarks

Used by Microsoft Outlook and Outlook Web Access (OWA) for saving the original TNEF in cases where the TNEF contains named properties that cannot be created in the store.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagToDoItemFlags Canonical Property

 Copy code hover
[image]

PidTagToDoItemFlags Canonical Property
See also Send feedback

Published: July 16, 2012

Represents a To-Do item's flagged condition.

Associated properties: | PR_TODO_ITEM_FLAGS
Identifier: | 0x0E2B
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

This property is a bit field in which each bit should be set to 1 if the associated condition in the following table applies, otherwise 0.

Numeric value | Name | Description
Not present | N/A | Unflagged
1 | todoTimeFlagged | Object is time flagged
8 | todoRecipientFlagged | Should only be set on a draft message object, and it means that the object is flagged for recipients.

All bits that are not specified in the table are reserved. They must be ignored, but should be preserved if they are set.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOFLAG]

Specifies the properties and operations related to flagging.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTransmittableDisplayName Canonical Property

 Copy code hover
[image]

PidTagTransmittableDisplayName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a recipient's display name in a secure form that cannot be changed.

Associated properties: | PR_TRANSMITABLE_DISPLAY_NAME, PR_TRANSMITABLE_DISPLAY_NAME_A, PR_TRANSMITABLE_DISPLAY_NAME_W
Identifier: | 0x3A20
Data type: | PT_UNICODE, PT_STRING8
Area: | Address

Remarks

These properties should be implemented by all address book providers. They contain the version of the recipient's display name that is transmitted with the message. For most address book providers these properties have the same value as the PR_DISPLAY_NAME (PidTagDisplayName) property. Providers that do not have a secure display name return PT_ERROR and MAPI changes the display name by adding quotation marks around the name.

A client application can use this property to prevent alteration or "spoofing" of entries. An example of spoofing is transmitting John Doe as John (What a Guy) Doe.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

[MS-NSPI]

Handles a client's communications with a Name Service Provider Interface (NSPI) server.

[MS-OXCFXICS]

Handles the order and flow for data transfers between a client and server.

[MS-OXCMSG]

Handles message and attachment objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTransportKey Canonical Property

 Copy code hover
[image]

PidTagTransportKey Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a value used by the MAPI spooler to track the progress of an outbound message through the outgoing transport providers.

Associated properties: | PR_TRANSPORT_KEY
Identifier: | 0x0E16
Data type: | PT_LONG
Area: | MAPI non-transmittable

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagTransportProviders Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTransportMessageHeaders Canonical Property

 Copy code hover
[image]

PidTagTransportMessageHeaders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains transport-specific message envelope information.

Associated properties: | PR_TRANSPORT_MESSAGE_HEADERS, PR_TRANSPORT_MESSAGE_HEADERS_A, PR_TRANSPORT_MESSAGE_HEADERS_W
Identifier: | 0x007D
Data type: | PT_STRING8, PT_UNICODE
Area: | E-mail

Remarks

The transport provider can generate the message header information for inbound messages.

These properties offer an alternative to either discarding the transport message header information or prepending it to the message text. The client can choose whether or not to display the information.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOMSG]

Specifies the properties and operations that are permissible on e-mail message objects.

[MS-OXCMAIL]

Converts from Internet standard e-mail conventions to message objects.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

PidTagBody Canonical Property

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTransportProviders Canonical Property

 Copy code hover
[image]

PidTagTransportProviders Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a list of identifiers of transport providers in the current profile.

Associated properties: | PR_TRANSPORT_PROVIDERS
Identifier: | 0x3D02
Data type: | PT_BINARY
Area: | MAPI profile

Remarks

Do not use this property. It is reserved for use by MAPI.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Reference

MAPIUID

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTtyTddPhoneNumber Canonical Property

 Copy code hover
[image]

PidTagTtyTddPhoneNumber Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the telephone number for the contact's text telephone (TTY) or telecommunication device for the deaf (TDD).

Associated properties: | PR_TTYTDD_PHONE_NUMBER, PR_TTYTDD_PHONE_NUMBER_A, PR_TTYTDD_PHONE_NUMBER_W
Identifier: | 0x3A4B
Data type: | PT_STRING8, PT_UNICODE
Area: | Contact

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagTypeOfX400User Canonical Property

 Copy code hover
[image]

PidTagTypeOfX400User Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains the type of a message recipient for use in a report.

Associated properties: | PR_TYPE_OF_MTS_USER
Identifier: | 0x0C1C
Data type: | PT_LONG
Area: | MAPI Recipient

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagUrlComponentName Canonical Property

 Copy code hover
[image]

PidTagUrlComponentName Canonical Property
See also Send feedback

Published: July 16, 2012

The URL component name for a message.

Associated properties: | PR_URL_COMP_NAME, PR_URL_COMP_NAME_A, PR_URL_COMP_NAME_W
Identifier: | 0x10F3
Data type: | PT_STRING8, PT_UNICODE
Area: | General messaging

Remarks

These properties should be unique within a folder. If not set when the message is created, the message store should set these properties based on various message properties, depending on the message class. For example, the IPM.Note and IPM.Appointment messages should have this property set based on the PR_SUBJECT (PidTagSubject) property and the IPM.Contact messages should have this property set based on the dispidFileUnder (PidLidFileUnder) property. For most other message classes, this property should be based on the PR_DISPLAY_NAME (PidTagDisplayName) property.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXCMSG]

Handles message and attachment objects.

[MS-OXTNEF]

Encodes and decodes message and attachment objects to an efficient stream representation.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagUserCertificate Canonical Property

 Copy code hover
[image]

PidTagUserCertificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains an ASN.1 authentication certificate for a messaging user.

Associated properties: | PR_USER_CERTIFICATE
Identifier: | 0x3A22
Data type: | PT_BINARY
Area: | MAPI mail user

Remarks

An authentication certificate is similar to a digital signature. Several MAPI properties supply ASN.1 certificates.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagUserFields Canonical Property

 Copy code hover
[image]

PidTagUserFields Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name, data type, and other information about a user-defined field.

Associated properties: | PR_USERFIELDS
Identifier: | 0x36E3
Data type: | PT_BINARY
Area: | MAPI folder

Remarks

For each item, Outlook stores the definitions of all user-defined fields in the PidLidPropertyDefinitionStream property of the corresponding IMessage object. The PidLidPropertyDefinitionStream property contains a binary stream known as PropertyDefinition, which contains the field definitions. For more information about stream structures for field definitions, see Stream Structures.

For each folder, Outlook stores the definitions of all user-defined fields in that folder in the PidTagUserFields property of an associated message of the message class IPC.MS.REN.USERFIELDS - each folder presumed to contain no more than one message of this class in its associated contents table.

Note Note

The set of user-defined fields in a folder may not necessarily match the sets of user-defined fields in each of its items.

The set of user-defined fields in a folder is displayed in various places in the Outlook UI, such as the folder's Field Chooser. The message's PidTagUserFields property contains a binary stream, FolderUserFields, which contains the folder field definitions. For more information about stream structures for folder field definitions, see Folder Fields Stream Structures and the FolderUserFields Stream Sample.

Section Heading

Protocol Specifications

[MS-OXPROPS]

Provides property set definitions and references to related Exchange Server protocol specifications.

Header Files

Mapidefs.h

Provides data type definitions.

See also

Concepts

Outlook Items and Fields
How to: Add a Definition for a New User-Defined Field
PropertyDefinition Stream Sample
MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagUserX509Certificate Canonical Property

 Copy code hover
[image]

PidTagUserX509Certificate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains X.509 version 3 security certificates for a messaging user.

Associated properties: | PR_USER_X509_CERTIFICATE
Identifier: | 0x3A70
Data type: | PT_MV_BINARY
Area: | MAPI mail user

Remarks

This property is used by applications that utilize public-key security. It holds a binary representation of one or more X.509 version 3 security certificates.

Various applications and clients can use this property for their own security certificates. The binary format of the X.509 data can vary among vendors.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagValidFolderMask Canonical Property

 Copy code hover
[image]

PidTagValidFolderMask Canonical Property
See also Send feedback

Published: July 16, 2012

Contains a bitmask of flags that indicate the validity of the entry identifiers of the folders in a message store.

Associated properties: | PR_VALID_FOLDER_MASK
Identifier: | 0x35DF
Data type: | PT_LONG
Area: | MAPI message store

Remarks

A folder's entry identifier can become invalid if a user deletes the folder or if the message store becomes corrupted.

One or more of the following flags can be set for the bitmask:

FOLDER_COMMON_VIEWS_VALID

The common views folder has a valid entry identifier. See PR_COMMON_VIEWS_ENTRYID (PidTagCommonViewsEntryId).

FOLDER_FINDER_VALID

The finder folder has a valid entry identifier. See PR_FINDER_ENTRYID (PidTagFinderEntryId).

FOLDER_IPM_INBOX_VALID

The interpersonal message (IPM) receive folder has a valid entry identifier. See IMsgStore::GetReceiveFolder.

FOLDER_IPM_OUTBOX_VALID

The IPM Outbox folder has a valid entry identifier. See PR_IPM_OUTBOX_ENTRYID (PidTagIpmOutboxEntryId).

FOLDER_IPM_SENTMAIL_VALID

The IPM Sent Items folder has a valid entry identifier. See PR_IPM_SENTMAIL_ENTRYID (PidTagIpmSentMailEntryId).

FOLDER_IPM_SUBTREE_VALID

The IPM folder subtree has a valid entry identifier. See PR_IPM_SUBTREE_ENTRYID (PidTagIpmSubtreeEntryId).

FOLDER_IPM_WASTEBASKET_VALID

The IPM Deleted Items folder has a valid entry identifier. See PR_IPM_WASTEBASKET_ENTRYID (PidTagIpmWastebasketEntryId).

FOLDER_VIEWS_VALID

The views folder has a valid entry identifier. See PR_VIEWS_ENTRYID (PidTagViewsEntryId).

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagViewDescriptorName Canonical Property

 Copy code hover
[image]

PidTagViewDescriptorName Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the name of a view descriptor.

Associated properties: | PR_VD_NAME, PR_VD_NAME_A, PR_VD_NAME_W
Identifier: | 0x7006
Data type: | PT_STRING8, PT_UNICODE
Area: | Message class-defined transmittable

Remarks

These properties must be set to a non-empty string for a Folder Associate Information (FAI) message that contains view definitions.

Related Resources

Protocol Specifications

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagViewDescriptorVersion Canonical Property

 Copy code hover
[image]

PidTagViewDescriptorVersion Canonical Property
See also Send feedback

Published: July 16, 2012

Indicates the version of a view descriptor.

Associated properties: | PR_VD_VERSION
Identifier: | 0x7007
Data type: | PT_LONG
Area: | Miscellaneous

Remarks

This property's value must be 8.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCFG]

Specifies the location and properties of client and server configuration data, such as shared category lists and working hours.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagViewsEntryId Canonical Property

 Copy code hover
[image]

PidTagViewsEntryId Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the entry identifier of the user-defined Views folder.

Associated properties: | PR_VIEWS_ENTRYID
Identifier: | 0x35E5
Data type: | PT_BINARY
Area: | MAPI message store

Remarks

The common view folder contains a predefined set of standard view specifiers, while the view folder contains specifiers defined by a messaging user. These folders, which are not visible in the interpersonal message (IPM) hierarchy, can hold many view specifiers, each one stored as a message. The client application can choose to merge the two sets of specifiers and make them both available.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagWeddingAnniversary Canonical Property

 Copy code hover
[image]

PidTagWeddingAnniversary Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the date of a user's wedding anniversary.

Associated properties: | PR_WEDDING_ANNIVERSARY
Identifier: | 0x3A41
Data type: | PT_SYSTIME
Area: | MAPI mail user

Remarks

This property is defined by the user or the user's organization.

Related Resources

Protocol Specifications

[MS-OXPROPS]

Provides references to related Exchange Server protocol specifications.

[MS-OXOCNTC]

Specifies the properties and operations that are permissible for contacts and personal distribution lists.

[MS-OXOABK]

Specifies the properties and operations for lists of users, contacts, groups, and resources.

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagWizardNoPabPage Canonical Property

 Copy code hover
[image]

PidTagWizardNoPabPage Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains TRUE if the profile wizard is to suppress the personal address book (PAB) page.

Associated properties: | PR_WIZARD_NO_PAB_PAGE
Identifier: | 0x6701
Data type: | PT_BOOLEAN
Area: | Exchange Administrative

Remarks

Service providers can set this property when calling a function based on the LAUNCHWIZARDENTRY function prototype. This property tells the profile wizard that the provider does not want the PAB page to be displayed during the user dialog.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagWizardNoPstPage Canonical Property

 Copy code hover
[image]

PidTagWizardNoPstPage Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains TRUE if the profile wizard is to suppress the personal message store (PST) page.

Associated properties: | PR_WIZARD_NO_PST_PAGE
Identifier: | 0x6700
Data type: | PT_BOOLEAN
Area: | Exchange Administrative

Remarks

Service providers can set this property when calling a function based on the LAUNCHWIZARDENTRY function prototype. This property tells the profile wizard that the provider does not want the PST page to be displayed during the user dialog.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagX400ContentType Canonical Property

 Copy code hover
[image]

PidTagX400ContentType Canonical Property
See also Send feedback

Published: July 16, 2012

This property contains the content type for a submitted message.

Associated properties: | PR_X400_CONTENT_TYPE
Identifier: | 0x003C
Data type: | PT_BINARY
Area: | X400

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as associated properties.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagXCoordinate Canonical Property

 Copy code hover
[image]

PidTagXCoordinate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the x coordinate of the starting position (the upper-left corner) of a dialog box control, in standard Windows dialog units.

Associated properties: | PR_XPOS
Identifier: | 0x3F05
Data type: | PT_LONG
Area: | MAPI display table

Remarks

This property, PR_YPOS (PidTagYCoordinate), PR_DELTAX (PidTagDeltaX), and PR_DELTAY (PidTagDeltaY) properties position and size the dialog box control.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


PidTagYCoordinate Canonical Property

 Copy code hover
[image]

PidTagYCoordinate Canonical Property
See also Send feedback

Published: July 16, 2012

Contains the y coordinate of the starting position (the upper-left corner) of a dialog box control, in standard Windows dialog units.

Associated properties: | PR_YPOS
Identifier: | 0x3F06
Data type: | PT_LONG
Area: | MAPI display table

Remarks

The PR_XPOS (PidTagXCoordinate), this property, PR_DELTAX (PidTagDeltaX), and PR_DELTAY (PidTagDeltaY) properties position and size the control.

Related Resources

Header Files

Mapidefs.h

Provides data type definitions.

Mapitags.h

Contains definitions of properties listed as alternate names.

See also

Concepts

MAPI Properties
MAPI Canonical Properties
Mapping Canonical Property Names to MAPI Names
Mapping MAPI Names to Canonical Property Names


MAPI Structures

 Copy code hover
[image]

MAPI Structures
See also Send feedback

Published: July 16, 2012

The following alphabetized entries describe MAPI structures. For more detailed information, cross references to other publications or to other topics in this documentation are also included.

ADRENTRY | ADRLIST
ADRPARM | CURRENCY
CONTAB_ENTRYID | DIR_ENTRYID
DTBLBUTTON | DTBLCHECKBOX
DTBLCOMBOBOX | DTBLDDLBX
DTBLEDIT | DTBLGROUPBOX
DTBLLABEL | DTBLLBX
DTBLMVDDLBOX | DTBLMVLISTBOX
DTBLPAGE | DTBLRADIOBUTTON
DTCTL | DTPAGE
ENTRYID | ENTRYLIST
ERROR_NOTIFICATION | EXTENDED_NOTIFICATION
FILETIME | FLAGLIST
FLATENTRY | FLATENTRYLIST
FLATMTSIDLIST | FORMPRINTSETUP
GUID | IID
MAPIERROR | MAPIINIT_0
MAPINAMEID | MAPIUID
MTSID | NEWMAIL_NOTIFICATION
NOTIFICATION | NOTIFKEY
OBJECT_NOTIFICATION | ROWENTRY
ROWLIST | SAndRestriction
SAppTimeArray | SBinary
SBinaryArray | SBitMaskRestriction
SCommentRestriction | SComparePropsRestriction
SContentRestriction | SCurrencyArray
SDateTimeArray | SDoubleArray
SExistRestriction | SGuidArray
SLargeIntegerArray | SLongArray
SLPSTRArray | SMAPIFormInfoArray
SMAPIFormProp | SMAPIFormPropArray
SMAPIFormPropEnumVal | SMAPIVerb
SMAPIVerbArray | SMessageClassArray
SNotRestriction | SOrRestriction
SPropAttrArray | SPropertyRestriction
SPropProblem | SPropProblemArray
SPropTagArray | SPropValue
SRealArray | SRestriction
SRow | SRowSet
SShortArray | SSizeRestriction
SSortOrder | SSortOrderSet
SSubRestriction | STATUS_OBJECT_NOTIFICATION
STnefProblem | STnefProblemArray
SWStringArray | TABLE_NOTIFICATION

See also

Concepts

MAPI Functions, Callbacks, and Macros

Other resources

MAPI Reference


ADRENTRY

 Copy code hover
[image]

ADRENTRY
See also Send feedback

Published: July 16, 2012

Describes zero or more properties that belong to a recipient.

Header file:

Mapidefs.h

C++
typedef struct _ADRENTRY
{
  ULONG ulReserved1;
  ULONG cValues;
  LPSPropValue rgPropVals;
} ADRENTRY, FAR *LPADRENTRY;

Members

ulReserved1

Reserved; must be zero.

cValues

Count of properties in the property value array pointed to by the rgPropVals member. The cValues member can be zero.

rgPropVals

Pointer to a property value array describing the properties for the recipient. The rgPropVals member can be NULL.

Remarks

An ADRENTRY structure describes properties that belong to a single recipient. The properties that are typically used to describe a recipient include the following:

PR_DISPLAY_NAME (PidTagDisplayName)

PR_ADDRTYPE (PidTagAddressType)

PR_EMAIL_ADDRESS (PidTagEmailAddress)

PR_ENTRYID (PidTagEntryId)

When an entry identifier or PR_ENTRYID property appears in the SPropValue array for a recipient, this indicates that the recipient has been resolved. Clients call the IAddrBook::ResolveName method to make sure that all recipients in the recipient list of an outgoing message have been resolved. Only resolved recipients can be sent with messages.

ADRENTRY structures are typically combined to form an array for the aEntries member of an ADRLIST structure.

ADRENTRY structures and SRow structures are identical because they both contain a reserved member, an array of property values, and a count of values in the array. Whereas ADRENTRY structures are combined to form the aEntries member of an ADRLIST structure, SRow structures are combined to form the aRow member of an SRowSet structure. Both types of structures follow the same allocation rules, implying that an SRowSet structure that is retrieved from the contents table of an address book container can be cast to an ADRLIST structure and used as is.

An ADRENTRY structure can be empty. For example, an ADRENTRY structure that is contained in the ADRLIST structure pointed to by the lppAdrList parameter in a call to IAddrBook::Address can be empty when a recipient is being removed.

For more information about how to allocate memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.

See also

Reference

IAddrBook::Address
IMessage::ModifyRecipients
MAPIAllocateBuffer
ADRLIST
SRow
SRowSet

Concepts

MAPI Structures


ADRLIST

 Copy code hover
[image]

ADRLIST
See also Send feedback

Published: July 16, 2012

Describes zero or more properties that belong to one or more recipients.

Header file: | Mapidefs.h
Related macros: | CbADRLIST, CbNewADRLIST, CbNewADRLIST
C++
typedef struct _ADRLIST
{
  ULONG cEntries;
  ADRENTRY aEntries[MAPI_DIM];
} ADRLIST, FAR *LPADRLIST;

Members

cEntries

Count of entries in the array specified by the aEntries member.

aEntries

Array of ADRENTRY structures, one structure for each recipient.

Remarks

An ADRLIST structure contains one or more ADRENTRY structures, each describing the properties of a recipient. A recipient can be unresolved. This means that it is lacking an entry identifier in its array of property values. A resolved recipient means that the PR_ENTRYID (PidTagEntryId) property is included. Typically, resolved recipients also have an e-mail address the PR_EMAIL_ADDRESS (PidTagEmailAddress) property. However, the e-mail address is not required. ADRLIST structures are used, for example, to describe the recipient list for an outgoing message and by MAPI to display the entries in the address book.

ADRLIST structures resemble SRowSet structures the structures used for representing rows in tables. In fact, these two structures are designed so that they can be used interchangeably. Both contain an array of structures describing a group of properties and a count of the values in the array. Whereas in the ADRLIST structure, the array contains ADRENTRY structures, in the SRowSet structure the array contains SRow structures. ADRENTRY structures and SRow structures are identical in layout. Because ADRLIST and SRowSet structures follow the same allocation rules, an SRowSet structure that is retrieved from the contents table of an address book container can be cast to an ADRLIST structure and used as is.

The following illustration shows the layout of an ADRLIST structure.

ADRLIST components

The ADRENTRY and SPropValue portions in an ADRLIST structure must be allocated and freed independently of the other parts. That is, each SPropValue structure must be allocated individually after memory for the ADRENTRY structure has been allocated and freed before the ADRENTRY structure is freed. This independence in handling memory allows recipients and individual recipient properties to be freely added or deleted from the address list.

The MAPIAllocateBuffer and MAPIFreeBuffer functions must be used to allocate and free the ADRLIST structure and all its parts.

If a recipient list is too large to fit in memory, clients can call the IMessage::ModifyRecipients method to work with a subset of the list. Clients should not use the address book common dialog boxes in this situation.

For more information about how to allocate memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.

See also

Reference

ADRENTRY
CbNewADRLIST
IMessage::ModifyRecipients
SRowSet

Concepts

MAPI Structures


ADRPARM

 Copy code hover
[image]

ADRPARM
See also Send feedback

Published: July 16, 2012

Describes the display and behavior of the common address dialog box.

Header file:

Mapidefs.h

C++
typedef struct _ADRPARM
{
  ULONG cbABContEntryID;
  LPENTRYID lpABContEntryID;
  ULONG ulFlags;
  LPVOID lpReserved;
  ULONG ulHelpContext;
  LPSTR lpszHelpFileName;
  LPFNABSDI lpfnABSDI;
  LPFNDISMISS lpfnDismiss;
  LPVOID lpvDismissContext;
  LPSTR lpszCaption;
  LPSTR lpszNewEntryTitle;
  LPSTR lpszDestWellsTitle;
  ULONG cDestFields;
  ULONG nDestFieldFocus;
  LPSTR FAR *lppszDestTitles;
  ULONG FAR *lpulDestComps;
  LPSRestriction lpContRestriction;
  LPSRestriction lpHierRestriction;
} ADRPARM, FAR *LPADRPARM;

Members

cbABContEntryID

Count of bytes in the entry identifier pointed to by lpABContEntryID.

lpABContEntryID

Pointer to the entry identifier of the container that supplies the initial list of recipient addresses that are displayed in the address dialog box.

ulFlags

Bitmask of flags associated with various address dialog box options. The following flags can be set:

AB_RESOLVE

Enable all names to be resolved after the address dialog box is closed. If there are ambiguous entries that result from the name resolution process, a dialog box appears to prompt the user for help in resolving them. Setting this flag guarantees that all of the names returned by IAddrBook::Address are resolved.

AB_SELECTONLY

Disable the creation of one-off addresses for a recipient list. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

ADDRESS_ONE

The user can select exactly one recipient instead of multiple recipients from a list. This flag is valid only when cDestFields is zero and the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_MODAL

Causes the modal version of the common address dialog box to be displayed. Either this flag or DIALOG_SDI should be set; they cannot both be set.

DIALOG_OPTIONS

Causes the Send Options button to be displayed in the dialog box. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_SDI

Causes the modeless version of the common address dialog box to be displayed. Either this flag or DIALOG_MODAL should be set; they cannot both be set. The DIALOG_SDI flag is ignored for non-Outlook clients, and the modal version of the dialog box will be displayed. Consequently, a pointer to a handle should not be expected in the lpulUIParam parameter of IAddrBook::Address.

lpReserved

Reserved, must be zero.

ulHelpContext

Specifies the context within Help that will first be shown when the user clicks the Help button in the address dialog box.

lpszHelpFileName

Pointer to the name of a Help file that will be associated with the address dialog box. The lpszHelpFileName member is used together with ulHelpContext to call the Windows WinHelp function.

lpfnABSDI

Pointer to a MAPI function based on the ACCELERATEABSDI prototype or NULL. This member applies to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set. Clients building an ADRPARM structure to pass to IAddrBook::Address must always set the lpfnABSDI member to NULL. If the DIALOG_SDI flag is set, MAPI will then set it to a valid function before returning. Clients call this function from in their message loop to make sure that accelerators in the address book dialog box work. When the dialog box is dismissed and MAPI calls the function pointed to by the lpfnDismiss member, clients should unhook the ACCELERATEABSDI function from their message loop.

lpfnDismiss

Pointer to a function based on the DISMISSMODELESS prototype or NULL. This member applies only to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client calling IAddrBook::Address that the dialog box is no longer active.

lpvDismissContext

Pointer to context information to be passed to the DISMISSMODELESS function pointed to by the lpfnDismiss member. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set.

lpszCaption

Pointer to text to be used as the title for the common address dialog box.

lpszNewEntryTitle

Pointer to text to be used as the button label for the button that invokes either the New Entry dialog box or another dialog box.

lpszDestWellsTitle

Pointer to text to be used as a title for the recipient text box controls that can appear in the modal version of the common address dialog box. This member is not used for modeless dialog boxes.

cDestFields

Count of recipient text box controls in the modal version of the address dialog box, or zero if the dialog box is modeless. The address dialog box is open for browsing only when the following conditions are true:

  • The cDestFields member is set to zero.

  • The DIALOG_BOX flag is set.

  • The ADDRESS_ONE flag is not set.

Setting cDestFields to 0XFFFFFFFF implies that MAPI should create the default number of recipient text box controls. In this case, the lppszDestTitles and lpulDestComps members must be NULL.

nDestFieldFocus

Indicates the particular text box control that should have the initial focus when the modal version of the dialog box appears. This value must be between 0 and the value of cDestFields minus 1.

lppszDestTitles

Pointer to an array of labels for buttons associated with each of the text box controls that are displayed in the modal version of the address dialog box. The value of the cDestFields member indicates the number of labels included in the array. If the lppszDestTitles member is NULL, the Address method uses default titles.

lpulDestComps

Pointer to an array of recipient type values, such as MAPI_TO, MAPI_CC, and MAPI_BCC, that is associated with each text box control. The value of the CDestFields member indicates the number of recipient types included in the array. The values pointed to by lpulDestComps can be used to set the PR_RECIPIENT_TYPE (PidTagRecipientType) property of each recipient. If the lpulDestComps member is NULL, the Address method uses default recipient types.

lpContRestriction

Pointer to an SRestriction structure that limits the type of address entries that can be displayed in the dialog box.

lpHierRestriction

Pointer to an SRestriction structure that limits the address book containers that can supply address entries to be displayed in the dialog box.

Remarks

ADRPARM structures are used by clients and service providers to control the appearance and behavior of the MAPI common address dialog boxes. There are two varieties of the address dialog box: modeless and modal. Some of the members in the ADRPARM structure apply to both versions of the dialog box, but some only apply to one of the two versions. The following table relates the members of an ADRPARM structure to their use with the common address dialog boxes.

ADRPARM member | Type of dialog box
cbABContEntryID and lpABContEntryID | Modal and modeless
ulFlags | Modal and modeless
lpReserved | Modal and modeless
ulHelpContext and lpszHelpFileName | Modal and modeless
lpfnABSDI | Modeless
lpfnDismiss and lpvDismissContext | Modeless
lpszCaption | Modal and modeless
lpszNewEntryTitle | Modal
lpszDestWellsTitle, cDestFields, nDestFieldFocus, lppszDestTitles,and lpulDestComps | Modal
lpContRestriction | Modal and modeless
lpHierRestriction | Modal and modeless

The modeless dialog box is a read-only display of entries from one or more address book containers. The dialog box can display all entries from the selected containers or be limited to only those entries and containers that match criteria established by a restriction. The contents restriction pointed to by lpContRestriction can limit the types of entries displayed and the hierarchy restriction pointed to by lpHierRestriction can limit the containers providing the entries. To inform the caller when the dialog box is dismissed, MAPI invokes a function that is provided by the caller that matches the DISMISSMODELESS prototype. Another function, one that matches the ACCELERATEABSDI prototype, is provided by MAPI and invoked by the caller in the Windows message loop to facilitate the working of keyboard shortcuts. The modeless version of the MAPI address dialog box can be displayed when clients call IAddrBook::Address or when service providers call IMAPISupport::Address.

The modal dialog box is a read/write display of entries from one or more containers. Its contents can be affected in the same manner as the modeless version by restrictions set in the lpContRestriction and lpHierRestriction members. In addition to the list box displaying container entries, the modal dialog box can contain between one and three text box controls for holding entries selected by the user. Each edit control is associated with a particular recipient type or PR_RECIPIENT_TYPE property such as MAPI_TO. The modal address dialog box can be displayed by either of the Address methods or when clients call IAddrBook::Details and service providers call IMAPISupport::Details.

This illustration includes two text box controls because the cDestFields member of the ADRPARM structure controlling the display of this dialog box is set to 2. The first control has initial focus because the nDestFieldFocus member is set to 0.

The lpszNewEntryTitle member points to text for a button label that, when it is selected, causes an additional dialog box to be displayed. Typically, as is shown in the illustration of the modal dialog box, the button is labeled New and the dialog box that appears lists all of the types of addresses that can be created by any of the address book providers in the profile. Clients cause this New Entry dialog box to be displayed by calling IAddrBook::NewEntry and passing zero for the cbEidNewEntryTpl parameter and NULL for the lpEidNewEntryTpl parameter when the user selects the button. The information that is included in this dialog box comes from the MAPI one-off table.

Every entry in this dialog box is associated with a template for entering the data required to create an address of the particular type. Most address book providers supply one template for every type of address entry they can create. When a user makes a selection from this dialog box, MAPI displays the corresponding template.

The most significant four bits of the ADRPARM structure's ulFlags member contain a version number identifying the version of the ADRPARM structure. The current version is 0 (zero) or ADRPARM_HELP_CTX. The current implementation of MAPI will fail for any version of the structure other than zero.

Future versions of the structure may be completely different; they may not support the version-zero structure. The following macros are provided for extracting the version number from the ulFlags member and for combining it with the defined flags:

GET_ADRPARM_VERSION (ulFlags)

SET_ADRPARM_VERSION (ulFlags, ulVersion)

ADRPARM_HELP_CTX

See also

Reference

ACCELERATEABSDI
DISMISSMODELESS
IAddrBook::Address
IMAPISupport::Address
SRestriction

Concepts

MAPI Structures


CONTAB_ENTRYID

 Copy code hover
[image]

CONTAB_ENTRYID
See also Send feedback

Published: August 16, 2013

Contains the entry ID of the contacts folder.

Header file:

msomapiutil.h

C++
#pragma pack(4)
typedef struct _contab_entryid
{
    BYTE abFlags[4];
    MAPIUID muid;
    ULONG ulVersion;
    ULONG ulType;
    ULONG ulIndex;
    ULONG cbeid;
    BYTE abeid[1];
}   CONTAB_ENTRYID, *LPCONTAB_ENTRYID;
#pragma pack()

Members

abFlags

A bitmask of flags that provides information describing the object. For more information, see the description of the abFlags field of an ENTRYID structure.

muid

GUID that identifies the store provider.

ulVersion

The version number of the CONTAB_ENTRYID structure. Must be set to CONTAB_VERSION.

ulType

An integer representing the contact entry ID type. It must be one of the following values:

Name

Description

CONTAB_USER

A messaging user object.

CONTAB_DISTLIST

A distribution list object.

ulIndex

The index into the email property subset.

cbeid

The size of the entry identifier of the Contact message associated with this entry in the Contacts Address Book.

abeid

The entry identifier of the Contact message associated with this entry in the Contacts Address Book.

Remarks

A Contacts Address Book is an Address Book that contains all the contact items in a Contacts folder that have either an email address or a fax number. Each entry in a Contacts Address Book is associated with either an email address or a fax number. Since a contact item can have up to three email addresses and three fax numbers, a contact item can be represented by up to six entries in the corresponding Contacts Address Book.

The purpose of a Contacts Address Book is to support users addressing email messages to contacts in a Contacts folder. The Contacts Address Book provider that Microsoft Outlook 2010 and Microsoft Outlook 2013 support is contab32.dll.

The CONTAB_ENTRYID structure supports a subset of the information that is present in the underlying MAPI Contact message. It identifies the Contact message that a particular Contacts Address Book entry is associated with.

The cbeid and abeid fields are only valid when the ulType field value is set to CONTAB_DISTLIST or CONTAB_USER. When the ulType field value is set to CONTAB_ROOT, CONTAB_SUBROOT, or CONTAB_CONTAINER, the DIR_ENTRYID structure should be used instead.

See also

Reference

DIR_ENTRYID

Concepts

MAPI Structures


CURRENCY

 Copy code hover
[image]

CURRENCY
See also Send feedback

Published: July 16, 2012

Contains a signed 64-bit integer representing a currency value.

Header file:

Mapidefs.h

C++
typedef struct tagCY
{
  unsigned long Lo;
  long Hi;
} CURRENCY;

Members

Lo

Low-order 32 bits of the currency value.

Hi

High-order 32 bits of the currency value.

Remarks

The CURRENCY structure is a scaled integer representation of a decimal number with four digits to the right of the decimal point. For example, a stored value of 327500 is to be construed as representing a currency value of 32.7500.

The CURRENCY structure is used to describe a property of type PT_CURRENCY. For information about property types, see MAPI Property Type Overview.

See also

Reference

SPropValue

Concepts

MAPI Structures


DIR_ENTRYID

 Copy code hover
[image]

DIR_ENTRYID
See also Send feedback

Published: August 16, 2013

Describes the properties of a directory entry id.

Header file:

entryid.h

C++
#pragma pack(4)
typedef struct _dir_entryid
{
    BYTE abFlags[4];
    MAPIUID muid;
    ULONG ulVersion;
    ULONG ulType;
    MAPIUID muidID;
}   DIR_ENTRYID, *LPDIR_ENTRYID;
#pragma pack()

Members

abFlags

A bitmask of flags that provides information describing the object. For more information, see the description of the abFlags field of an ENTRYID structure.

muid

GUID that identifies the store provider.

ulVersion

The version number of the DIR_ENTRYID structure. Must be set to CONTAB_VERSION.

ulType

An integer representing the directory entry ID type. It must be one of the following values:

Name

Description

CONTAB_ROOT

The root folder for a MAPI address book.

CONTAB_SUBROOT

A subfolder contained within the root folder of the MAPI address book object.

CONTAB_CONTAINER

An address book container object.

muidID

A GUID that identifies the logon object.

Remarks

The structures DIR_ENTRYID and CONTAB_ENTRYID are identical, except for the ulType member. The contents of the ulType member determine which structure is appropriate for the remaining fields.

See also

Reference

CONTAB_ENTRYID

Concepts

MAPI Structures


DTBLBUTTON

 Copy code hover
[image]

DTBLBUTTON
See also Send feedback

Published: July 16, 2012

Contains information about a button control for a dialog box built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblButton
C++
typedef struct _DTBLBUTTON
{
  ULONG ulbLpszLabel;
  ULONG ulFlags;
  ULONG ulPRControl;
} DTBLBUTTON, FAR *LPDTBLBUTTON;

Members

ulbLpszLabel

Position in memory of the character string that is displayed on the button.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulPRControl

Property tag for a property of type PT_OBJECT that implements the IMAPIControl interface. When the button is clicked, MAPI calls the IMAPIProp::OpenProperty method for the display table's IMAPIProp implementation to retrieve this property.

Remarks

A DTBLBUTTON structure describes a button a control that, when clicked, allows a user to begin an operation. Typically, clicking a button causes a modal dialog box to be displayed or a programmatic task to be invoked. Service providers can implement anything through a button control. If the button is supposed to perform a task based on the values of other controls, those controls must have set the DT_SET_IMMEDIATE flag.

The ulbLpszLabel member is the position in memory of the character string that is displayed on the button. Service providers can add an ampersand character (&) to indicate a Windows accelerator in the button label. Pressing an accelerator key has the same effect as clicking the button.

The ulPRControl member describes an object property that, when opened with the IMAPIProp::OpenProperty method, returns a pointer to a control object. Implementing a control object that supports the IMAPIControl interface is a way to extend the MAPI feature set and define the operation or task that occurs when the button is clicked. IMAPIControl supplies two methods for manipulating buttons: GetState to disable or enable buttons and Activate to handle button clicks.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLCHECKBOX

 Copy code hover
[image]

DTBLCHECKBOX
See also Send feedback

Published: July 16, 2012

Contains information about a check box that will be used in a dialog box built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblCheckBox
C++
typedef struct _DTBLCHECKBOX
{
  ULONG ulbLpszLabel;
  ULONG ulFlags;
  ULONG ulPRPropertyName;
} DTBLCHECKBOX, FAR *LPDTBLCHECKBOX;

Members

ulbLpszLabel

Position in memory of the character string that is displayed with the check box.

ulFlags

Bitmask of flags used to designate the format of the check box label. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulPRPropertyName

Property tag for a property of type PT_BOOLEAN. The value of this property is affected by the state of the check box.

Remarks

A DTBLCHECKBOX structure describes a check box a control that reflects one of two states: enabled (a checked box) or disabled (an empty box).

The ulPRPropertyName member describes a Boolean property whose value is manipulated by changing the state of the check box. When the check box is first displayed, MAPI calls the GetProps method of the IMAPIProp implementation that is associated with the display table to retrieve a set of default properties. If one of the properties maps to the property tag in the DTBLCHECKBOX structure, the value for that property is displayed as the check box's initial value.

Check box controls can be modifiable. This allows a user to change their states. Modifiable check boxes set the DT_EDITABLE flag in the ulCtlFlags member of their DTCTL structure and in their PR_CONTROL_FLAGS (PidTagControlFlags) property. When a check box changes its state, MAPI calls IMAPIProp::SetProps to set the property identified in the property tag member of the DTBLCHECKBOX structure to the new state.

For example, an address book provider might include a modifiable check box control in its configuration dialog box to adjust the setting of a recipient's PR_SEND_RICH_INFO (PidTagSendRichInfo) property. When the user selects the check box, MAPI sets this property to TRUE. When the check box is unselected, the property is set to FALSE.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table. For information about property types, see MAPI Property Type Overview.

See also

Reference

DTCTL
PidTagControlType Canonical Property

Concepts

MAPI Structures


DTBLCOMBOBOX

 Copy code hover
[image]

DTBLCOMBOBOX
See also Send feedback

Published: July 16, 2012

Describes a combo box control that will be used in a dialog box built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblComboBox
C++
typedef struct _DTBLCOMBOBOX
{
  ULONG ulbLpszCharsAllowed;
  ULONG ulFlags;
  ULONG ulNumCharsAllowed;
  ULONG ulPRPropertyName;
  ULONG ulPRTableName;
} DTBLCOMBOBOX, FAR *LPDTBLCOMBOBOX;

Members

ulbLpszCharsAllowed

An offset from the start of the DTBLCOMBOBOX structure to a character string filter that describes restrictions, if any, to the characters that can be entered into the combo box's edit control. The filter is not interpreted as a regular expression and the same filter is applied to every character entered. The format of the filter is as follows:

Character

Description

*

Any character is allowed (for example, "*").

[ ]

Defines a set of characters (for example, "[0123456789]").

-

Indicates a range of characters (for example, "[a-z]").

~

Indicates that these characters are not allowed. (for example, "[~0-9]").

\

Used to quote any of the previous symbols (for example, "[\-\\\[\]]" means -, \, [, and ] characters are allowed).

ulFlags

Bitmask of flags used to designate the format of the character string filter. The following flag can be set:

MAPI_UNICODE

The filter is in Unicode format. If the MAPI_UNICODE flag is not set, the filter is in ANSI format.

ulNumCharsAllowed

Maximum number of characters that can be entered in the combo box's text box.

ulPRPropertyName

Property tag for a property of type PT_TSTRING.

ulPRTableName

Property tag for a property of type PT_OBJECT on which an IMAPITable interface can be opened by using an OpenProperty call. The table must have one column with a property that is the same type as the property identified by the ulPRPropertyName member. The rows of the table are used to populate the list.

Remarks

A DTBLCOMBOBOX structure describes a combo box a control that consists of a list and a selection field. The list presents the information from which a user can select, and the selection field displays the current selection. The selection field is an edit control that can also be used to enter text not already in the list.

The two property tag members work together to coordinate the list display with the edit control. When MAPI first displays the combo box, it calls the OpenProperty method of the IMAPIProp implementation that is associated with the display table to retrieve the table represented by the ulPRTableName member. This table has one column a column that contains values for the property represented by the ulPRPropertyName member. Therefore, this column must be of the same type as the ulPRPropertyName property and both columns must be character strings.

The values for the column are displayed in the list section of the combo box. Therefore, PR_NULL (PidTagNull) is not a valid property tag for ulPRPropertyName. When a user either selects one of the rows or enters new data into the text box, the ulPRPropertyName property is set to the selected or entered value.

To display an initial value for the edit control, MAPI calls IMAPIProp::GetProps to retrieve the property values for the display table. If one of the retrieved properties matches the property represented by the ulPRPropertyName member, its value becomes the initial value.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL
PidTagControlType Canonical Property

Concepts

MAPI Structures


DTBLDDLBX

 Copy code hover
[image]

DTBLDDLBX
See also Send feedback

Published: July 16, 2012

Describes a drop-down list control that will be used in a dialog box built from a display table.

Header file:

Mapidefs.h

C++
typedef struct _DTBLDDLBX
{
  ULONG ulFlags;
  ULONG ulPRDisplayProperty;
  ULONG ulPRSetProperty;
  ULONG ulPRTableName;
} DTBLDDLBX, FAR *LPDTBLDDLBX;

Members

ulFlags

Reserved, must be zero.

ulPRDisplayProperty

Property tag for a property of type PT_TSTRING. This property is one of the columns in the table identified by the ulPRTableName member. The values for this property are displayed in the list.

ulPRSetProperty

Property tag for a property of any type. This property is one of the columns in the table identified by the ulPRTableName member. When the user of the list selects a property value for the ulPRDisplayProperty member from the rows of the table identified by the ulPRTableName member, the corresponding ulPRSetProperty member is set.

ulPRTableName

Property tag for a table property of type PT_OBJECT that can be opened by using an OpenProperty call. The table should have two columns: ulPRDisplayProperty and ulPRSetProperty. The rows of the table should correspond to items in the list.

Remarks

A DTBLDDLBX structure describes a drop-down list control that is displayed as a single item until the user elects to expand it.

The three properties identified by the property tags work together to display the information in the list and set a related property. The ulPRTableName member is a table object that is accessed through a call to IMAPIProp::OpenProperty. The table has two columns: one column for the property identified by the ulPRDisplayProperty member and the other for the property identified by the ulPRSetProperty member.

The ulPRDisplayProperty property drives the list display. When a user selects one of the values from the display, MAPI calls IMAPIProp::SetProps to set the corresponding property as identified by the ulPRSetProperty member. This means that the property in the same row as the selected display property. The ulPRSetProperty member cannot be set to PR_NULL (PidTagNull).

An initial value is displayed in the list if MAPI has retrieved the property represented by the ulPRSetProperty member through a call to IMAPIProp::GetProps and located a row in the table with the value for the ulPRSetProperty member. The initial displayed value is the contents of the ulPRDisplayProperty column from that row that matches the property in the ulPRDisplayProperty member of the structure. The value returned by GetProps for the property identified by the ulPRDisplayProperty member becomes the initial value that is shown when the list is first displayed.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table. For information about property types, see MAPI Property Type Overview.

See also

Reference

DTCTL
IMAPIProp::OpenProperty
IMAPIProp::SetProps
IMAPIProp::GetProps

Concepts

MAPI Structures
Display Table Implementation
Display Tables
MAPI Property Type Overview


DTBLEDIT

 Copy code hover
[image]

DTBLEDIT
See also Send feedback

Published: July 16, 2012

Describes an edit control that will be used in a dialog box built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblEdit
C++
typedef struct _DTBLEDIT
{
  ULONG ulbLpszCharsAllowed;
  ULONG ulFlags;
  ULONG ulNumCharsAllowed;
  ULONG ulPropTag;
} DTBLEDIT, FAR *LPDTBLEDIT;

Members

ulbLpszCharsAllowed

An offset from the start of the DTBLEDIT structure to a character string filter that describes restrictions, if any, to the characters that can be entered into the edit control. The filter is not interpreted as a regular expression and the same filter is applied to every character entered. The format of the filter is as follows:

Character

Description

*

Any character is allowed (for example, "*").

[ ]

Defines a set of characters (for example, "[0123456789]".)

-

Indicates a range of characters (for example, "[a-z]").

~

Indicates that these characters are not allowed (for example, "[~0-9]").

\

Used to quote any of the previous symbols (for example, "[\-\\\[\]]" means -, \, [, and ] characters are allowed).

ulFlags

Bitmask of flags used to designate the format of the character filter. The following flag can be set:

MAPI_UNICODE

The filter is in Unicode format. If the MAPI_UNICODE flag is not set, the filter is in ANSI format.

ulNumCharsAllowed

Maximum number of characters that the user can type into the text box.

ulPropTag

Property tag for a property of type PT_TSTRING. The ulPropTag member identifies the string property whose data is displayed and edited in the edit control.

Remarks

A DTBLEDIT structure describes an edit control an area on a dialog box that contains alphanumeric information. Almost all dialog boxes have at least one edit control. Edit controls can be modifiable by a user or read-only.

Edit controls can also be single line or multiline. Multiline edit controls typically have a scroll bar associated with them.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL
IMAPIProp::GetProps
PidTagControlType Canonical Property

Concepts

MAPI Structures


DTBLGROUPBOX

 Copy code hover
[image]

DTBLGROUPBOX
See also Send feedback

Published: July 16, 2012

Describes a group box control that will be used in a dialog box built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblGroupBox
C++
typedef struct _DTBLGROUPBOX
{
  ULONG ulbLpszLabel;
  ULONG ulFlags;
} DTBLGROUPBOX, FAR *LPDTBLGROUPBOX;

Members

ulbLpszLabel

Position in memory of the character string that accompanies the group box. If displayed, the label appears on the top, left-hand side of the box.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

Remarks

A DTBLGROUPBOX structure describes a group box control that is used to visually associate other controls in the dialog box. The highlighting technique involves surrounding the other controls by a box.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLLABEL

 Copy code hover
[image]

DTBLLABEL
See also Send feedback

Published: July 16, 2012

Describes a label that will be used in a dialog box that is built from a display table.

Header file: | Mapidefs.h
Related macro | SizedDtblLabel
C++
typedef struct _DTBLLABEL
{
  ULONG ulbLpszLabelName;
  ULONG ulFlags;
} DTBLLABEL, FAR *LPDTBLLABEL;

Members

ulbLpszLabelName

Position in memory of the character string label.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabelName member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

Remarks

A DTBLLABEL structure describes a label control text that is displayed with another type of control to add meaning to that control. For example, most edit controls are positioned next to labels to inform the user of the type of information to be entered. Some controls, such as group boxes and radio buttons, hold their own labels.

The label can include a Windows accelerator, identified as the character following the ampersand (&). Pressing the accelerator key puts the focus in the first nonlabel, nonbutton control following this label in the display table.

There is no support for multiline labels. Showing multiple lines requires multiple labels.

It is not possible to use a label as a read-only edit control. The difference is that an edit control can be selected and copied whereas a label cannot.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLLBX

 Copy code hover
[image]

DTBLLBX
See also Send feedback

Published: July 16, 2012

Describes a list that will be used in a dialog box that is built from a display table.

Header file:

Mapidefs.h

C++
typedef struct _DTBLLBX
{
  ULONG ulFlags;
  ULONG ulPRSetProperty;
  ULONG ulPRTableName;
} DTBLLBX, FAR *LPDTBLLBX

Members

ulFlags

Bitmask of flags used to eliminate a horizontal or vertical scroll bar from the list. The following flags can be set:

MAPI_NO_HBAR

No horizontal scroll bar should be shown with the list.

MAPI_NO_VBAR

No vertical scroll bar should be shown with the list.

ulPRSetProperty

Property tag for a property of any type. This property is one of the columns in the table identified by the ulPRTableTable member.

ulPRTableName

Property tag for a table property of type PT_OBJECT that can be opened by using an OpenProperty call. The number of columns that the table should have depends on whether the list is a single or multiple selection list. If the ulPRSetProperty member is set to PR_NULL (PidTagNull), the list allows for multiple selection.

Remarks

A DTBLLBX structure describes a list a control that is used to show multiple items and let a user select one or more of the items.

The ulPRSetProperty member and ulPRTableName member work together; when one value is chosen from the table, it is written back to ulPRSetProperty when the dialog box is dismissed.

The flags value indicates whether a horizontal or vertical scroll bar should be displayed with the list. The default is to have types of scroll bars appear if it is required. Service providers can set MAPI_NO_HBAR to suppress a horizontal scroll bar and MAPI_NO_VBAR to suppress a vertical scroll bar.

The two property tag members work together to display values in the list and set corresponding properties when an item in the list is selected. When MAPI first displays the list, it calls the IMAPIProp implementation's OpenProperty method to retrieve the table identified in the ulPRTableName member. The number of columns in the table depends on the value of the ulPRSetProperty member. If ulPRSetProperty is set to PR_NULL, the list is a multiple selection list based on an object that contains recipients, such as an address book container, a recipient table for a message, or a distribution list contents table.

A table for a multiple selection list must include the following columns:

PR_DISPLAY_NAME (PidTagDisplayName)

PR_ENTRYID (PidTagEntryId)

PR_INSTANCE_KEY (PidTagInstanceKey)

PR_DISPLAY_TYPE (PidTagDisplayType) and a maximum of five other multivalued string properties can also be displayed with the three required columns.

If the ulPRSetProperty member is not set to PR_NULL, the list is a single selection list. The initial value of ulPRSetProperty determines the first selected row. When a user selects one of the rows, the ulPRSetProperty member is set to the selected value and this value is written back to the property interface implementation with a call to IMAPIProp::SetProps.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLMVDDLBOX

 Copy code hover
[image]

DTBLMVDDLBOX
See also Send feedback

Published: July 16, 2012

Describes a drop-down list that will be used in a dialog box that is built from a display table.

Header file:

Mapidefs.h

C++
typedef struct _DTBLMVDDLBX
{
  ULONG ulFlags;
  ULONG ulMVPropTag;
} DTBLMVDDLBX, FAR * LPDTBLMVDDLBX;

Members

ulFlags

Reserved; must be zero.

ulMVPropTag

Property tag for a multi-valued property of type PT_MV_TSTRING. The different values of this property are displayed as distinct entries in the drop-down list.

Remarks

A DTBLMVDDLBOX structure describes a multi-valued drop-down list a read-only list of items. By using a multi-valued drop-down list, values are displayed when a user clicks on a scroll bar.

The data that is displayed comes from the property identified in the ulMVPropTag member. There is no requirement to read from the property interface that is associated with the display table. Also, because users are not able to make selections from these types of list boxes, data is not written to the property interface.

Only multi-valued string properties are supported for the multi-valued drop-down list; other multi-valued property types are not supported.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLMVLISTBOX

 Copy code hover
[image]

DTBLMVLISTBOX
See also Send feedback

Published: July 16, 2012

Describes a multi-valued list that will be displayed in a dialog box that is built from a display table.

Header file:

Mapidefs.h

C++
typedef struct _DTBLMVLISTBOX
{
  ULONG ulFlags;
  ULONG ulMVPropTag;
} DTBLMVLISTBOX, FAR * LPDTBLMVLISTBOX;

Members

ulFlags

Reserved; must be zero.

ulMVPropTag

Property tag for a multi-valued property of type PT_MV_TSTRING.

Remarks

A DTBLMVLISTBOX structure describes a standard multi-valued list that has a read-only list of items. By using a standard multi-valued list, the values are displayed immediately.

The data that is displayed comes from the property identified in the ulMVPropTag member. There is no requirement to read from the property interface that is associated with the display table. Also, because users are not able to make selections from these types of lists, data is not written to the property interface.

Only multi-valued string properties are supported for the multi-valued list; other multi-valued property types are not supported.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLPAGE

 Copy code hover
[image]

DTBLPAGE
See also Send feedback

Published: July 16, 2012

Describes a tabbed page that will be used in a dialog box that is built from a display table.

Header file: | Mapidefs.h
Related macro: | SizedDtblPage
C++
typedef struct _DTBLPAGE
{
  ULONG ulbLpszLabel;
  ULONG ulFlags;
  ULONG ulbLpszComponent;
  ULONG ulContext;
} DTBLPAGE, FAR *LPDTBLPAGE;

Members

ulbLpszLabel

Position in memory of the character string label for the page tab.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabelName member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulbLpszComponent

Position in memory of a character string identifying the [Help File Mappings] section in the MAPISVC.INF configuration file or 0. The file name appearing in the MAPISVC.INF section can be used by a user to access extended Help for the tabbed page by clicking the Help button in the dialog box. For more information about the entries in MAPISVC.INF, see File Format of MAPISVC.INF.

ulContext

A unique identifier for the tabbed page in the string defined by the ulbLpszComponent member. The ulbLpszComponent member and the ulContext member must both be nonzero for the Help button to work. If this identifier is zero and the component string is NULL, there is no Help associated with the page.

Remarks

A DTBLPAGE structure describes a tabbed page a control that is used to separate several related dialog boxes. Typically, these dialog boxes are property sheets for displaying configuration, message, or recipient options. By clicking the tab, the user can switch from one sheet to another.

The component string and context identifier provide information about whether extended Help is available for the tabbed page. If extended Help is available, the component string and context identifier will provide information about how to access it. The component string maps to the Help file; the context identifier maps to the initial Help topic. If the context identifier is zero and the component string is NULL, extended Help is not available.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

DTCTL

Concepts

MAPI Structures


DTBLRADIOBUTTON

 Copy code hover
[image]

DTBLRADIOBUTTON
See also Send feedback

Published: July 16, 2012

Describes one radio button that will be part of a radio button group. The radio button group will be used in a dialog box that is built from a display table.

Header file:

Mapidefs.h

C++
typedef struct _DTBLRADIOBUTTON
{
  ULONG ulbLpszLabel;
  ULONG ulFlags;
  ULONG ulcButtons;
  ULONG ulPropTag;
  long lReturnValue;
} DTBLRADIOBUTTON, FAR *LPDTBLRADIOBUTTON;

Members

ulbLpszLabel

Position in memory of the character string label for the radio button.

ulFlags

Bitmask of flags used to designate the format of the label pointed to by the ulbLpszLabel member. The following flag can be set:

MAPI_UNICODE

The label is in Unicode format. If the MAPI_UNICODE flag is not set, the label is in ANSI format.

ulcButtons

Count of buttons in the radio button group. The DTBLRADIOBUTTON structures for the other buttons in the group must be contained in successive rows of the display table. Each of these rows should contain the same value for the ulcButtons member.

ulPropTag

Property tag for a property of type PT_LONG. The initial selection in the radio button group is based on the initial value of this property. Each button in the group must have ulPropTag set to the same property.

lReturnValue

Unique number that identifies the selected button.

Remarks

A DTBLRADIOBUTTON structure describes a radio button a button control that is associated with a group of buttons. Only one button in the group can be checked; setting one button causes the other buttons in the group to be unset.

The button count is the number of radio buttons in the group. The structures for the other radio buttons in the group must be in subsequent rows in the display table. Each of these structures should have the same value for its button count.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

BuildDisplayTable
DTCTL
SizedDtblButton

Concepts

MAPI Structures


DTCTL

 Copy code hover
[image]

DTCTL
See also Send feedback

Published: July 16, 2012

Describes a control that will be used in a dialog box built from a display table.

Header file:

Mapidefs.h

C++
typedef struct
{
  ULONG ulCtlType;
  ULONG ulCtlFlags;
  LPBYTE lpbNotif;
  ULONG cbNotif;
  LPSTR lpszFilter;
  ULONG ulItemID;
  union
  {
    LPVOID lpv;
    LPDTBLLABEL lplabel;
    LPDTBLEDIT lpedit;
    LPDTBLLBX lplbx;
    LPDTBLCOMBOBOX lpcombobox;
    LPDTBLDDLBX lpddlbx;
    LPDTBLCHECKBOX lpcheckbox;
    LPDTBLGROUPBOX lpgroupbox;
    LPDTBLBUTTON lpbutton;
    LPDTBLRADIOBUTTON lpradiobutton;
    LPDTBLMVLISTBOX lpmvlbx;
    LPDTBLMVDDLBX lpmvddlbx;
    LPDTBLPAGE lppage;
  } ctl;
} DTCTL, FAR *LPDTCTL;

Members

ulCtlType

Type of control that is included in the ctl member and corresponds to the control's PR_CONTROL_TYPE (PidTagControlType) property. Possible values are as follows:

DTCT_LABEL

Label control.

DTCT_EDIT

Edit control.

DTCT_LBX

List box control.

DTCT_COMBOBOX

Combo box control.

DTCT_DDLBX

Drop-down list control.

DTCT_CHECKBOX

Check box control.

DTCT_GROUPBOX

Group box control.

DTCT_BUTTON

Button control.

DTCT_PAGE

Tabbed page control.

DTCT_RADIOBUTTON

Radio button control.

DTCT_MVLISTBOX

Multi-valued list control.

DTCT_MVDDLBX

Multi-valued drop-down list control.

ulCtlFlags

Bitmask of flags that describes the control's features and corresponds to the control's PR_CONTROL_FLAGS (PidTagControlFlags) property. These flags can be set for check boxes, combo boxes, list boxes, and edit controls only. Possible values are as follows:

DT_ACCEPT_DBCS

Either the ANSI or DBCS format is accepted. This flag is valid for edit controls only.

DT_EDITABLE

A user can modify the text in the control.

DT_MULTILINE

The control can contain multiple text lines. This flag is valid for edit controls only.

DT_PASSWORD_EDIT

The control contains a password; therefore, the contents of the control should not be displayed to the user. This flag is valid for edit controls only.

DT_REQUIRED

The dialog box control is required. This flag is valid only for edit and combo box controls.

DT_SET_IMMEDIATE

Enables immediate output of a value upon a change in the control. This allows a dependency relationship to be established between two controls.

lpbNotif

Pointer to a structure that consists of a GUID structure, to represent the service provider and an identifier for the control. The lpbNotif and cbNotif members correspond to the control's PR_CONTROL_ID (PidTagControlId) property and are used to notify the user interface when the control has to be updated.

cbNotif

Count of bytes in the structure pointed to by the lpbNotif member.

lpszFilter

Pointer to a character string that describes which characters can be entered into an edit or combo box control. For other types of controls, the lpszFilter member can be NULL. For edit and combo box controls, it should be a regular expression that applies to a single character at a time. The same filter is applied to all characters in the control. The format of the filter string is as follows:

Character

Description

*

Any character is allowed (for example, "*").

[ ]

Defines a set of characters (for example, "[0123456789]".)

-

Indicates a range of characters (for example, "[a-z]").

~

Indicates that these characters are not allowed (for example, "[~0-9]").

\

Used to quote any of the previous symbols (for example, "[\-\\\[\]]" means -, \, [, and ] characters are allowed).

ulItemID

Value that identifies the control in the dialog box resource. For tabbed pages controls of type DTCT_PAGE the ulItemID member is optionally used to load the component name for the page from a string resource. Position and label information are read from the dialog box resource.

ctl

A structure that holds the data for the control and corresponds to the control's PR_CONTROL_STRUCTURE (PidTagControlStructure) property. Each type of control has a different structure.

Remarks

The DTCTL structure describes one control of any type. Most of its members are used to set properties on the control.

The ctl member is a union of structures that relate to a particular type of control. If the DTCTL structure is describing an edit control, for example, the ctl member will point to a DTBLEDIT structure. This structure corresponds to the control's PR_CONTROL_STRUCTURE property. The union has as its first member a variable of type LPVOID to allow compile time initialization of the DTCTL structure.

Although the BuildDisplayTable function uses the DTCTL structure for building the display table from control resources, the DTCTL structure never appears in the display table itself. This structure just supplies information to BuildDisplayTable.

In the ulCtlFlags member, four flags DT_ACCEPT_DBCS, DT_EDITABLE, DT_MULTILINE_and DT_PASSWORD_EDIT affect edit controls only. Two others DT_REQUIRED and DT_SET_IMMEDIATE affect any editable control.

The controls available for a dialog box are label, text box, ink-aware text box, list, drop-down list, combo box, check box, group box, button, radio button, and tabbed page.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

BuildDisplayTable
DTBLBUTTON
DTBLCHECKBOX
DTBLCOMBOBOX
DTBLDDLBX
DTBLEDIT
DTBLGROUPBOX
DTBLLABEL
DTBLLBX
DTBLMVDDLBOX
DTBLMVLISTBOX
DTBLPAGE
DTBLRADIOBUTTON

Concepts

MAPI Structures


DTPAGE

 Copy code hover
[image]

DTPAGE
See also Send feedback

Published: July 16, 2012

Describes the dialog box that is built from a display table by the BuildDisplayTable function.

Header file:

Mapidefs.h

C++
typedef struct DTPAGE
{
  ULONG cctl;
  LPSTR lpszResourceName;
  union
  {
    LPSTR lpszComponent;
    ULONG ulItemID;
  }
  LPDTCTL lpctl;
} DTPAGE, FAR *LPDTPAGE;

Members

cctl

Count of controls pointed to by the lpctl member.

lpszResourceName

Pointer to the name or integer identifier for the dialog box resource.

lpszComponent

Pointer to the string that appears in the [Help File Mappings] section in MAPISVC.INF. Because lpszComponent is in a union with the ulItemID member, only one of these members has valid data.

ulItemID

Integer resource identifier with a value less than or equal to 65535 from which the Help file name can be read. Because ulItemID is in a union with the lpszComponent member, only one of these members has valid data.

lpctl

Pointer to an array of DTCTL structures, one for each control on the page.

Remarks

To identify the Help file for the tabbed page, set either the lpszComponent member to a hard-coded string or the ulItemID member to an integer resource identifier.

Each entry in the [Help File Mappings] section in MAPISVC.INF consists of a component string, no longer than 30 characters, on the left side and a Help file path on the right. Both ulItemID and lpszResourceName are found in the hInstance parameter of BuildDisplayTable. For more information, see MAPISVC.INF [Help File Mappings] Section.

Although BuildDisplayTable uses this structure to build the display table from control resources, the DTPAGE structure never appears in the display table itself.

For an overview of display tables, see Display Tables. For information about how to implement a display table, see Implementing a Display Table.

See also

Reference

BuildDisplayTable
DTBLPAGE
DTCTL

Concepts

MAPI Structures


ENTRYID

 Copy code hover
[image]

ENTRYID
See also Send feedback

Published: July 16, 2012

Contains an entry identifier for a MAPI object.

Header file: | Mapidefs.h
Related macros: | CbNewENTRYID, SizedENTRYID
C++
typedef struct
{
  BYTE abFlags[4];
  BYTE ab[MAPI_DIM];
} ENTRYID, FAR *LPENTRYID;

Members

abFlags

Bitmask of flags that provide information that describes 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 only set 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 enabled.

MAPI_THISSESSION

The entry identifier cannot be used on other sessions.

ab

Indicates an array of binary data that is 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 types of objects:

  • Message stores

  • Folders

  • Messages

  • Address book containers

  • Distribution lists

  • Messaging users

  • Status objects

  • Profile sections

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 instead of 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 the abFlags member.

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

An ENTRYID structure resembles a FLATENTRY structure. However, there are some differences:

  • An ENTRYID structure does not store the size of the entry identifier; a FLATENTRY structure does.

  • An ENTRYID structure stores the flag data and the rest of the entry identifier separately; a FLATENTRY structure stores the flag data with the rest of the entry identifier.

  • An ENTRYID structure is passed as a parameter to the methods of the IMAPIProp interface and to the following OpenEntry methods: IABLogon::OpenEntry, IAddrBook::OpenEntry, IMAPIContainer::OpenEntry, IMAPISession::OpenEntry, IMAPISupport::OpenEntry, IMsgStore::OpenEntry, IMSLogon::OpenEntry

  • An ENTRYID structure is used to store an entry identifier on disk. A FLATENTRY structure is used to store an entry identifier in a file or pass it in a stream of bytes.

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 good aligned entry identifier to a method can cause an alignment fault on RISC processors.

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.

For more information, see Entry Identifiers.

See also

Reference

FLATENTRY
IMAPISupport::CompareEntryIDs
PidTagRecordKey Canonical Property

Concepts

MAPI Structures


ENTRYLIST

 Copy code hover
[image]

ENTRYLIST
See also Send feedback

Published: July 16, 2012

An array of entry identifiers representing MAPI object that uses the same implementation as the SBinaryArray structure.

Header file:

Mapidefs.h

C++
typedef SBinaryArray ENTRYLIST, FAR *LPENTRYLIST;

Members

See the SBinaryArry structure for members.

See also

Reference

ENTRYID
SBinaryArray

Concepts

MAPI Structures


ERROR_NOTIFICATION

 Copy code hover
[image]

ERROR_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Describes information that relate to a critical error. This causes an error notification to be generated.

Header file:

Mapidefs.h

C++
typedef struct _ERROR_NOTIFICATION
{
  ULONG cbEntryID;
  LPENTRYID lpEntryID;
  SCODE scode;
  ULONG ulFlags;
  LPMAPIERROR lpMAPIError;
} ERROR_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by lpEntryID.

lpEntryID

Pointer to the entry identifier of the object that causes the error.

scode

Error value for the critical error.

ulFlags

Bitmask of flags used to designate the format of the text pointed to by the lpszError member in the structure pointed to by lpMAPIError. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpMAPIError

Pointer to a MAPIERROR structure describing the error.

Remarks

The ERROR_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an ERROR_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevCriticalError.

The value of the cbEntryID member and the lpEntryID member can be NULL.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

See also

Reference

MAPIERROR
NOTIFICATION

Concepts

MAPI Structures


EXTENDED_NOTIFICATION

 Copy code hover
[image]

EXTENDED_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Describes information that relates to an event that is service provider-specific.

Header file:

Mapidefs.h

C++
typedef struct _EXTENDED_NOTIFICATION
{
  ULONG ulEvent;
  ULONG cb;
  LPBYTE pbEventParameters;
} EXTENDED_NOTIFICATION;

Members

ulEvent

Extended event code that is defined by the provider.

cb

Count of bytes in the event-specific parameters pointed to by pbEventParameters.

pbEventParameters

Pointer to event-specific parameters. The type of parameters that are used depends on the value of the ulEvent member; these parameters are documented by the provider that issued the event.

Remarks

The EXTENDED_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an EXTENDED_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevExtended.

The extended event is defined by a service provider to represent a type of change that cannot be covered by any of the other predefined events. Only clients that know before they register that a service provider supports an extended event can register for that event. It is not possible for clients to determine without advanced knowledge if a service provider supports an extended event. If a service provider supports an extended event, it shows how to handle such an event when it is received.

An extended notification is sent by the session when a client logs off. Register for this notification by calling IMAPISession::Advise with the lpEntryID parameter set to NULL and the cbEntryID parameter set to zero.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport methods to generate notifications.

See also

Reference

NOTIFICATION

Concepts

MAPI Structures


FILETIME

 Copy code hover
[image]

FILETIME
See also Send feedback

Published: July 16, 2012

Holds an unsigned 64-bit date and time value for a file. This value represents the number of 100-nanosecond units since the start of January 1, 1601.

Header file:

Mapidefs.h

C++
typedef struct _FILETIME
{
  DWORD dwLowDateTime;
  DWORD dwHighDateTime;
} FILETIME, FAR *LPFILETIME;

Members

dwLowDateTime

Low-order 32 bits of the file time value.

dwHighDateTime

High-order 32 bits of the file time value.

Remarks

A property of type PT_SYSTIME has a FILETIME structure for its value. Such a property has a FILETIME data type for the Value member in its definition in an SPropValue structure.

The definition of the FILETIME structure is in the Win32 Programmer's Reference and in the MAPI header file Mapidefs.h. MAPI defines the structure conditionally to make sure that it is defined when the Win32 definition is unavailable.

See also

Reference

SPropValue

Concepts

MAPI Structures


FLAGLIST

 Copy code hover
[image]

FLAGLIST
See also Send feedback

Published: July 16, 2012

Contains a list of flags used to indicate the status of address entries during the name resolution process.

Header file:

Mapidefs.h

C++
typedef struct
{
  ULONG cFlags;
  ULONG ulFlags[MAPI_DIM];
} FlagList, FAR * LPFlagList;

Members

cFlags

Count of MAPI-defined flags in the list.

ulFlags

An array of flags that provides the status of the name resolution operation for a recipient. The following flags can be set:

MAPI_AMBIGUOUS

The recipient has been resolved, but not to a unique entry identifier. Other address book containers should not try to resolve this recipient.

MAPI_RESOLVED

The recipient has been resolved to a unique entry identifier. Other address book containers should not try to resolve this recipient.

MAPI_UNRESOLVED

The entry has not been resolved. Other address book containers should try to resolve this recipient.

Remarks

The FLAGLIST structure is used as a parameter to IABContainer::ResolveNames. Each of the recipients to be resolved is included in an ADRLIST structure. As the address book container attempts to resolve each recipient, it sets the appropriate flag in the corresponding entry in the FLAGLIST structure. All of the entries in the FLAGLIST structure are in the same order as the entries in the ADRLIST structure. This makes it easy to associate a flag setting with a recipient.

See also

Reference

ADRLIST
IABContainer::ResolveNames

Concepts

MAPI Structures


FLATENTRY

 Copy code hover
[image]

FLATENTRY
See also Send feedback

Published: July 16, 2012

An ENTRYID structure plus a byte count that specifies the size of the ENTRYID structure.

Header file: | Mapidefs.h
Related macros: | cbFLATENTRY, CbNewFLATENTRY
C++
typedef struct
{
  ULONG cb;
  BYTE abEntry[MAPI_DIM];
} FLATENTRY, FAR *LPFLATENTRY;

Members

cb

Count of bytes in the abEntry member.

abEntry

The complete entry identifier that includes the array of flags and binary data.

Remarks

A FLATENTRY structure resembles an ENTRYID structure. However, there are some differences:

  • A FLATENTRY structure stores the size of the entry identifier; ENTRYID does not.

  • A FLATENTRY structure stores the flag data together with the rest of the entry identifier; ENTRYID stores them separately.

  • A FLATENTRY structure is used to store an entry identifier in a file or pass it in a stream of bytes whereas an ENTRYID structure is used by the IMAPIProp interface methods and by the following OpenEntry methods: IABLogon::OpenEntry, IAddrBook::OpenEntry, IMAPIContainer::OpenEntry, IMAPISession::OpenEntry, IMAPISupport::OpenEntry, IMsgStore::OpenEntry, IMSLogon::OpenEntry

  • A FLATENTRY structure is used to store an entry identifier in a file or pass it in a stream of bytes. An ENTRYID structure is used to store an entry identifier on disk.

See also

Reference

ENTRYID

Concepts

MAPI Structures


FLATENTRYLIST

 Copy code hover
[image]

FLATENTRYLIST
See also Send feedback

Published: July 16, 2012

Contains an array of FLATENTRY structures.

Header file: | Mapidefs.h
Related macros: | CbFLATENTRYLIST, CbNewFLATENTRYLIST
C++
typedef struct
{
  ULONG cEntries;
  ULONG cbEntries;
  BYTE abEntries[MAPI_DIM];
} FLATENTRYLIST, FAR *LPFLATENTRYLIST;

Members

cEntries

Count of FLATENTRY structures in the array described by the abEntries member.

cbEntries

Count of bytes in the array described by abEntries.

abEntries

Byte array that contains one or more FLATENTRY structures, arranged end to end.

Remarks

In the abEntries array, each FLATENTRY structure is aligned on a naturally aligned boundary. Extra bytes are included as padding to make sure natural alignment between any two FLATENTRY structures. The first FLATENTRY structure in the array is always aligned correctly because the offset of the abEntries member is 8. To compute the offset of the next structure, use the size of the first entry rounded up to the next multiple of 4. Use the CbFLATENTRY macro to compute the size of a FLATENTRY structure.

For example, the second FLATENTRY structure starts at an offset that consists of the offset of the first entry plus the length of the first entry rounded to the next four bytes. The length of the first entry is the length of its cb member plus the length of its abEntry member.

The following code sample indicates how to compute offsets in a FLATENTRYLIST structure. Assume that lpFlatEntry is a pointer to the first structure in the list.

C++ Copy code Copy code
(offsetof(lpFlatEntry->ab) // for example, 4
+ lpFlatEntry->cb // size of lpFlatEntry->ab
+ 4) & ~3 // round to next 4 byte boundary

See also

Reference

FLATENTRY
PidTagReplyRecipientEntries Canonical Property

Concepts

MAPI Structures


FLATMTSIDLIST

 Copy code hover
[image]

FLATMTSIDLIST
See also Send feedback

Published: July 16, 2012

Contains an array of MTSID structures, each of which contains an X.400 message transport system (MTS) entry identifier.

Header file: | Mapidefs.h
Related macros: | CbFLATMTSIDLIST, CbNewFLATMTSIDLIST
C++
typedef struct
{
  ULONG cMTSIDs;
  ULONG cbMTSIDs;
  BYTE abMTSIDs[MAPI_DIM];
} FLATMTSIDLIST, FAR *LPFLATMTSIDLIST;

Members

cMTSIDs

Count of MTSID structures in the array described by the abMTSIDs member.

cbMTSIDs

Count of bytes in the array described by abMTSIDs.

abMTSIDs

Byte array that contains one or more MTSID structures.

Remarks

The FLATMTSIDLIST structure's use in X.400 messaging corresponds to the FLATENTRYLIST structure's use in MAPI messaging. MAPI uses FLATMTSIDLIST structures to maintain X.400 properties during message handling. Service providers use FLATMTSIDLIST structures when handling incoming and outgoing X.400 messages.

In the abMTSIDs array, each MTSID structure is aligned on a naturally aligned boundary. Extra bytes are included as padding to make sure natural alignment between any two MTSID structures. The first MTSID structure in the array is always aligned correctly because the offset of the abMTSIDs member is 8. To compute the offset of the next structure, use the size of the first entry rounded up to the next multiple of 4. Use the CbNewMTSID macro to compute the size of an MTSID structure.

See also

Reference

CbNewFLATMTSIDLIST
FLATENTRYLIST
MTSID

Concepts

MAPI Structures


FORMPRINTSETUP

 Copy code hover
[image]

FORMPRINTSETUP
See also Send feedback

Published: July 16, 2012

Describes the print setup information for the form object.

Header file:

Mapiform.h

C++
typedef struct
{
  ULONG ulFlags;
  HDEVMODE hDevMode;
  HDEVNAMES hDevNames;
  ULONG ulFirstPageNumber;
  ULONG ulFPrintAttachments;
} FORMPRINTSETUP, FAR * LPFORMPRINTSETUP;

Members

ulFlags

Bitmask of flags that controls the type of the strings. The following flag can be used:

MAPI_UNICODE

The strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

hDevmode

Handle to the mode of the printer.

hDevnames

Handle to the path of the printer.

ulFirstPageNumber

Page number of the first page to be printed.

ulFPrintAttachments

Flag that indicates whether there are attachments to be printed. If there are attachments to print, the ulFPrintAttachments member is set to 1. If there are no attachments to print, it is set to 0.

Remarks

The FORMPRINTSETUP structure is used to describe the print setup information for a form object. Implementations of IMAPIViewContext::GetPrintSetup fill in the FORMPRINTSETUP structure and return it in the contents of the lppFormPrintSetup output parameter of GetPrintSetup.

If the MAPI_UNICODE flag is passed in the ulFlags parameter of GetPrintSetup, the strings referenced by the hDevmode and hDevnames members should be in Unicode format. Otherwise, the strings should be in ANSI format.

Form viewers implementing IMAPIViewContext must allocate the FORMPRINTSETUP structure using the MAPI allocator function MAPIAllocateBuffer, but allocate the individual members, hDevMode and hDevNames, with the Windows function GlobalAlloc. The release of memory is handled similarly. The hDevMode and hDevNames members must be freed using the Windows function GlobalFree whereas the FORMPRINTSETUP structure must be freed with the MAPIFreeBuffer function.

See also

Reference

IMAPIViewContext::GetPrintSetup
MAPIFreeBuffer
MAPIAllocateBuffer

Concepts

MAPI Structures


GUID

 Copy code hover
[image]

GUID
See also Send feedback

Published: July 16, 2012

Describes a globally unique identifier (GUID).

Header file:

Mapiguid.h

C++
typedef struct _GUID
{
  unsigned long Data1;
  unsigned short Data2;
  unsigned short Data3;
  unsigned char Data4[8];
} GUID;

Members

Data1

An unsigned long integer data value.

Data2

An unsigned short integer data value.

Data3

An unsigned short integer data value.

Data4

An array of unsigned characters.

Remarks

GUID structures are used in MAPI as follows:

  • In the MAPIUID structures that uniquely identify service providers.

  • For interface identifiers.

  • In the property set names of named properties.

Message store and address book providers generate a GUID structure to use in their MAPIUID structure. By passing the resulting MAPIUID to IMAPISupport::SetProviderUID, these service providers inform MAPI of their unique identifier.

Also, they are used in the implementation of Microsoft Remote Procedure Call (RPC) and the Object Description Language (ODL). For more information about these uses, see the Microsoft RPC Programmer's Guide and Reference, OLE Programmer's Reference,and Inside OLE, Second Edition.

The GUID structure is defined in the Win32 Programmer's Reference. Specific values for GUID structures that are used within MAPI are defined in the MAPI header file Mapiguid.h.

See also

Reference

MAPIUID

Concepts

MAPI Structures


IID

 Copy code hover
[image]

IID
See also Send feedback

Published: July 16, 2012

Describes a GUID structure used to describe an identifier for a MAPI interface.

C++
typedef struct _GUID
{
  unsigned long Data1;
  unsigned short Data2;
  unsigned short Data3;
  unsigned char Data4[8];
} GUID;

Members

See the GUID structure.

Remarks

An IID structure is used to uniquely identify a MAPI interface and to associate a particular interface with an object. For example, when a client calls IMAPISession::OpenEntry to open a folder, the client sets the lpInterface parameter to point to an IID representing the IMAPIFolder interface. MAPI defines the IMAPIFolderIID to be IID_IMAPIFolder. IID structures are also used to uniquely identify OLE interfaces.

All of the specific IID structures for the MAPI interfaces are defined in the Mapiguid.h header file.

See also

Reference

GUID

Concepts

MAPI Structures


INDEX_SEARCH_PUSHER_PROCESS

 Copy code hover
[image]

INDEX_SEARCH_PUSHER_PROCESS
Send feedback

Published: July 16, 2012

Specifies the process that is sending a notification to the MAPI Protocol Handler that an object in that store is ready for indexing.

Quick Info

Copy code Copy code
typedef struct _INDEX_SEARCH_PUSHER_PROCESS {
    DWORD dwPID;
} INDEX_SEARCH_PUSHER_PROCESS;

Members

dwPID

Process ID for the process that is sending an indexing notification to the indexer of the MAPI Protocol Handler.


MAPIERROR

 Copy code hover
[image]

MAPIERROR
See also Send feedback

Published: July 16, 2012

Provides detailed information about an error, typically generated by the operating system, MAPI, or a service provider.

Header file:

Mapidefs.h

C++
typedef struct _MAPIERROR
{
  ULONG ulVersion;
  LPSTR lpszError;
  LPSTR lpszComponent;
  ULONG ulLowLevelError;
  ULONG ulContext;
} MAPIERROR, FAR * LPMAPIERROR;

Members

ulVersion

Version number of the structure. The ulVersion member is used for future expansion and should be set to MAPI_ERROR_VERSION, which is currently defined as zero.

lpszError

Pointer to a string that describes the error. This string will be in Unicode format if the ulFlags parameter to the method in which this structure is used is set to MAPI_UNICODE.

lpszComponent

Pointer to a string that describes the component that generated the error. This string will be in Unicode format if the ulFlags parameter to the method in which this structure is used is set to MAPI_UNICODE.

ulLowLevelError

Low-level error value that is used only when the error to be returned is low-level.

ulContext

Value that represents the location in the component pointed to by the lpszComponent member that identifies where the error occurred.

Remarks

The MAPIERROR structure is used to describe error information. Clients and service providers pass a pointer to a MAPIERROR structure in the lppMAPIError parameter of the IMAPIProp::GetLastError method. GetLastError returns information about the previous error that has occurred to an object. Callers of GetLastError free the memory for the MAPIERROR structure by calling MAPIFreeBuffer.

The lpszComponent member can be used to map the component's Help file, if one exists. Service providers should limit the size of the component string to 30 characters so that it can easily be displayed in a dialog box. The ulContext member can also be used to refer to an online Help topic for common errors.

Because service providers are not required to provide detailed error information, clients should not expect any of the members of the MAPIERROR structure that are returned to contain valid data. However, at a minimum MAPI strongly recommends that providers specify information in the lpszComponent and ulContext members.

For more information about error handling in MAPI, see Error Handling.

See also

Reference

IABLogon::GetLastError
IABProvider::Logon
IMAPIControl::GetLastError
IMAPIProp::GetLastError
IMAPISession::GetLastError
IMAPISupport::GetLastError
IMAPISupport::OpenAddressBook
IMAPISession::OpenAddressBook
IMAPITable::GetLastError
IMsgServiceAdmin::GetLastError
IMSLogon::GetLastError
IMSProvider::Logon
IProfAdmin::GetLastError
IProviderAdmin::GetLastError

Concepts

MAPI Structures


MAPIINIT_0

 Copy code hover
[image]

MAPIINIT_0
See also Send feedback

Published: July 16, 2012

Conveys options to the MAPIInitialize function.

Header file:

MAPIX.H

C++
typedef struct
{
  ULONG ulVersion;
  ULONG ulFlags;
} MAPIINIT_0, FAR *LPMAPIINIT_0;

Members

ulVersion

An integer value that represents the version number of the MAPIINIT_0 structure. The ulVersion member is for future expansion and does not represent the version of the MAPI interface. Currently, ulVersion must be set to MAPI_INIT_VERSION.

ulFlags

The bitmask of flags used to control the initialization of the MAPI session. The following flags can be set:

MAPI_MULTITHREAD_NOTIFICATIONS

MAPI should generate notifications using a thread dedicated to notification handling instead of the first thread used to call MAPIInitialize.

MAPI_NT_SERVICE

The caller is running as a Windows service. Callers that are not running as a Windows service should not set this flag; callers that are running as a service must set this flag.

MAPI_NO_COINIT

Set the MAPI_NO_COINT flag so that MAPIInitialize does not try to initialize COM with a call to CoInitialize. If a MAPIINIT_0 structure is passed into MAPIInitialize with ulFlags set to MAPI_NO_COINIT, MAPI will assume that COM has already been initialized and will bypass the call to CoInitialize.

Remarks

Multithreaded clients should set the MAPI_MULTITHREAD_NOTIFICATIONS flag. If the flag is not set, notifications are generated on the thread used to make the first call to MAPIInitialize.

For more information about when to set this flag and how to implement thread safety in a client, see Threading in MAPI.

See also

Reference

MAPIInitialize

Concepts

MAPI Structures


MAPINAMEID

 Copy code hover
[image]

MAPINAMEID
See also Send feedback

Published: July 16, 2012

Describes a named property.

Header file:

Mapidefs.h

C++
typedef struct _MAPINAMEID
{
  LPGUID lpguid;
  ULONG ulKind;
  union
  {
    LONG lID;
    LPWSTR lpwstrName;
  } Kind;
} MAPINAMEID, FAR *LPMAPINAMEID;

Members

lpguid

Pointer to a GUID structure defining a particular property set; this member cannot be NULL. Valid values are as follows:

PS_PUBLIC_STRINGS

PS_MAPI

A client-defined value

ulKind

Value describing the type of value in the Kind member. Valid values are as follows:

MNID_ID

The Kind member contains an integer value that represents the property name.

MNID_STRING

The Kind member contains a Unicode character string representing the property name.

Kind

Union describing the name of the named property. The name can be either an integer value, stored in lID, or a Unicode character string, stored in lpwstrName.

Remarks

The MAPINAMEID structure is used to describe named properties properties that have identifiers over 0x8000. A property set is an important part a named property. For example PS_PUBLIC_STRINGS or PS_ROUTING_ADDRTYPE are property sets defined by MAPI.

Named properties enable clients to define custom properties in a larger namespace than is available in the MAPI-defined property identifier range. Property names cannot be used to obtain property values directly; they must first be mapped to property identifiers through the IMAPIProp::GetIDsFromNames method. For particular objects such as messages, MAPI reserves a range of property identifiers for custom properties. Therefore, for these objects, clients do not have to use named properties and can save the associated overhead.

For more information about named properties, see Named Properties.

See also

Reference

GUID
IMAPIProp::GetIDsFromNames

Concepts

MAPI Structures


MAPISIB

 Copy code hover
[image]

MAPISIB
See also Send feedback

Published: July 16, 2012

This structure is used with IMAPISync::SynchronizeInBackground.

C++
typedef struct _MAPISIB
{
ULONG           ulSize;
ULONG           ulFlags;
LPMAPISESSION   psesSync;
LPUNKNOWN       punkCallBack;
HANDLE          *phSyncDoneEvent;
} MAPISIB, *PMAPISIB

Members

ulSize

The size of the structure.

ulFlags

A flag that indicates the type of sync. It must be one of the following values:

SYNC_OUTGOING_MAIL

0x00000200

Send the message to the server (not currently in use).

SYNC_UPLOAD_HIERARCHY

0x00000001

Push hierarchy changes to the server.

SYNC_DOWNLOAD_HIERARCHY

0x00000002

Pull hierarchy changes from server.

SYNC_UPLOAD_CONTENTS

0x00000040

Push message changes to server.

SYNC_DOWNLOAD_CONTENTS

0x00000080

Pull message changes from server.

SYNC_ON_DEMAND

0x20000000

The sync was initiated by the user and should be a higher priority.

SYNC_GLOBAL_HEADERS

0x02000000

Should only sync headers and not full bodies.

psesSync

[IN] A pointer to the MAPI session.

punkCallBack

[IN] A pointer to the interface on which to provide progress. It can be used to query the interface for IMAPISyncProgressCallback : IUnknown.

*phSyncDoneEvent

[OUT] The event that will occur when the thread that was just created is complete. The pointer must be valid because it will contain the event.

See also

Reference

IMAPISyncProgressCallback : IUnknown
IMAPISync : IUnknown


MAPIUID

 Copy code hover
[image]

MAPIUID
See also Send feedback

Published: July 16, 2012

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

Header file: | Mapidefs.h
Related macro: | IsEqualMAPIUID
C++
typedef struct _MAPIUID
{
  BYTE ab[16];
} MAPIUID, FAR *LPMAPIUID;

Members

ab

An array that contains a 16-byte identifier.

Remarks

A MAPIUID structure is a GUID structure put into Intel® processor byte order.

MAPI creates MAPIUID structures in a way that makes it very rare for two different items to have the same identifier. MAPIUID structures can be stored as binary properties or as files, without regard to the byte ordering of the computer storing or accessing the information.

MAPIUID structures are used:

  • To identify a profile section.

  • In the entry identifiers of message store and address book objects to identify the responsible service provider.

  • In the PR_SEARCH_KEY (PidTagSearchKey) property of messages.

To generate a MAPIUID identifier for a search key, service providers call IMAPISupport::NewUID.

When a client transmits a message across a network, it should use a protocol or transmission format that does not change the byte order of MAPIUID data.

For more information about how MAPIUID structures are used, see the following topics:

Registering Service Provider Unique Identifiers

Setting Transport Order

See also

Reference

GUID
IMAPISession::OpenProfileSection
IMAPISupport::NewUID

Concepts

MAPI Structures


MTSID

 Copy code hover
[image]

MTSID
See also Send feedback

Published: July 16, 2012

Contains an X.400 message transport system (MTS) entry identifier.

Header file: | Mapidefs.h
Related macros: | CbMTSID, CbNewMTSID
C++
typedef struct
{
  ULONG cb;
  BYTE abEntry[MAPI_DIM];
} MTSID, FAR *LPMTSID;

Members

cb

Count of bytes in the array described by the abEntry member.

abEntry

Byte array that contains the MTS entry identifier data.

Remarks

The MTSID structure is used only for X.400 mappings of MAPI entry identifiers. It corresponds to the MAPI FLATENTRY structure.

An MTS identifier has the same format as a MAPI entry identifier or a binary property value. MTS identifiers can be particularly useful for canceling deferred messages.

See also

Reference

FLATENTRY
FLATMTSIDLIST

Concepts

MAPI Structures


NEWMAIL_NOTIFICATION

 Copy code hover
[image]

NEWMAIL_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Describes information that relate to the arrival of a new message.

Header file:

Mapidefs.h

C++
typedef struct _NEWMAIL_NOTIFICATION
{
  ULONG cbEntryID;
  LPENTRYID lpEntryID;
  ULONG cbParentID;
  LPENTRYID lpParentID;
  ULONG ulFlags;
  LPSTR lpszMessageClass;
  ULONG ulMessageFlags;
} NEWMAIL_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to the entry identifier of the newly arrived message.

cbParentID

Count of bytes in the entry identifier pointed to by the lpParentID member.

lpParentID

Pointer to the entry identifier of the receive folder for the newly arrived message.

ulFlags

Bitmask of flags used to describe the format of the string properties included with the message. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpszMessageClass

Pointer to the message class of the newly arrived message.

ulMessageFlags

Bitmask of flags that describes the current state of the newly arrived message. The ulMessageFlags member is a copy of the message's PR_MESSAGE_FLAGS (PidTagMessageFlags) property.

Remarks

The NEWMAIL_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains a NEWMAIL_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevNewMail.

MAPI uses the NEWMAIL_NOTIFICATION structure only as a member of the NOTIFICATION structure, which holds information about a notification event for the advise sink.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

See also

Reference

NOTIFICATION
PidTagMessageFlags Canonical Property

Concepts

MAPI Structures


NOTIFICATION

 Copy code hover
[image]

NOTIFICATION
See also Send feedback

Published: July 16, 2012

Contains information about an event that has occurred and the data that has been affected by the event.

Header file:

Mapidefs.h

C++
typedef struct
{
  ULONG ulEventType;
  union
  {
    ERROR_NOTIFICATION err;
    NEWMAIL_NOTIFICATION newmail;
    OBJECT_NOTIFICATION obj;
    TABLE_NOTIFICATION tab;
    EXTENDED_NOTIFICATION ext;
    STATUS_OBJECT_NOTIFICATION statobj;
  } info;
} NOTIFICATION, FAR *LPNOTIFICATION;

Members

ulEventType

Type of notification event that occurred. The value of the ulEventType member corresponds to the structure that is included in the info union. The ulEventType member can be set to one of the following values:

fnevCriticalError

A global error has occurred, such as a session shut down in progress. The info member contains an ERROR_NOTIFICATION structure.

fnevExtended

An internal event defined by a particular service provider has occurred. The info member contains an EXTENDED_NOTIFICATION structure.

fnevNewMail

A message has been delivered to the appropriate receive folder for the message class and is waiting to be processed. The info member contains an NEWMAIL_NOTIFICATION structure.

fnevObjectCopied

A MAPI object has been copied. The info member contains an OBJECT_NOTIFICATION structure.

fnevObjectCreated

A MAPI object has been created. The info member contains an OBJECT_NOTIFICATION structure.

fnevObjectDeleted

A MAPI object has been deleted. The info member contains an OBJECT_NOTIFICATION structure.

fnevObjectModified

A MAPI object has changed. The info member contains an OBJECT_NOTIFICATION structure.

fnevObjectMoved

A message store or address book object has been moved. The info member contains an OBJECT_NOTIFICATION structure.

fnevSearchComplete

A search operation has finished and the results are available. The info member contains an OBJECT_NOTIFICATION structure.

fnevTableModified

Information in a table has changed. The info member contains an TABLE_NOTIFICATION structure.

info

Union of notification structures describing the affected data for a particular type of event. The structure included in the info member depends on the value of the ulEventType member.

Remarks

One or more NOTIFICATION structures are passed as input parameters with every call to a registered advise sink's IMAPIAdviseSink::OnNotify method. The NOTIFICATION structures contain information about the particular events that have occurred and describe the affected objects.

Before clients or service providers receiving a notification can use the structure to process the event, they must check the event type as indicated in the ulEventType member. For example, the code sample that is shown here checks for the arrival of a new message and upon detecting an event of this kind, prints out the message class of the message.

C++ Copy code Copy code
if (pNotif -> ulEventType == fnevNewMail)
{
printf("%s\n", pNotif -> newmail.lpszMessageClass)
}

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

See also

Reference

ERROR_NOTIFICATION
EXTENDED_NOTIFICATION
NEWMAIL_NOTIFICATION
OBJECT_NOTIFICATION
STATUS_OBJECT_NOTIFICATION
TABLE_NOTIFICATION

Concepts

MAPI Structures


NOTIFKEY

 Copy code hover
[image]

NOTIFKEY
See also Send feedback

Published: July 16, 2012

Uniquely identifies a connection between an advise sink, an advise source, and MAPI.

Header file:

Mapispi.h

C++
typedef struct
{
  ULONG cb;
  BYTE ab[MAPI_DIM];
} NOTIFKEY, FAR *LPNOTIFKEY;

Members

cb

Count of bytes in the ab member.

ab

Array of bytes describing the notification key.

Remarks

The Subscribe and Notify methods of IMAPISupport use the NOTIFKEY structure to generate notifications to the appropriate advise sink about the appropriate advise source.

Service providers generate notification keys when their Advise method is called and they want to call Subscribe to handle the notification registration and the subsequent sending of notifications. A notification key can be the entry identifier of the advise source or it can be any other identifying item such as a constant. For example, a message store provider might use the path of a folder as its notification key.

The notification key should work across multiple processes.

The scope requirements for a notification key resemble those for a long-term entry identifier. However, unlike an entry identifier, a notification key must be binary-comparable. Typically, a notification key includes a GUID value defined by the service provider followed by other provider-specific information unique to the object.

For a discussion of the use of the NOTIFKEY structure to manage the connections between the advise sinks and the objects that generate the notifications, see Supporting Event Notification.

See also

Concepts

MAPI Structures


OBJECT_NOTIFICATION

 Copy code hover
[image]

OBJECT_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Contains information about an object that has undergone a change, such as being copied or modified.

Header file:

Mapidefs.h

C++
typedef struct _OBJECT_NOTIFICATION
{
  ULONG cbEntryID;
  LPENTRYID lpEntryID;
  ULONG ulObjType;
  ULONG cbParentID;
  LPENTRYID lpParentID;
  ULONG cbOldID;
  LPENTRYID lpOldID;
  ULONG cbOldParentID;
  LPENTRYID lpOldParentID;
  LPSPropTagArray lpPropTagArray;
} OBJECT_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to the entry identifier of the affected object.

ulObjType

Type of object affected. Possible types are as follows:

MAPI_STORE

Message store.

MAPI_ADDRBOOK

Address book.

MAPI_FOLDER

Folder.

MAPI_ABCONT

Address book container.

MAPI_MESSAGE

Message.

MAPI_MAILUSER

Messaging user.

MAPI_ATTACH

Attachment.

MAPI_DISTLIST

Distribution list.

MAPI_PROFSECT

Profile section.

MAPI_STATUS

Status object.

MAPI_SESSION

Session object.

cbParentID

Count of bytes in the entry identifier pointed to by the lpParentID member.

lpParentID

Pointer to the entry identifier of the parent of the affected object.

cbOldID

Count of bytes in the entry identifier pointed to by the lpOldID member.

lpOldID

Pointer to the entry identifier of the original object. This pointer can be NULL if the event does not require an original object.

cbOldParentID

Count of bytes in the entry identifier pointed to by the lpOldParentID member.

lpOldParentID

Pointer to the entry identifier of the parent of the original object. This pointer can be NULL if the event does not require an original object.

lpPropTagArray

Pointer to an SPropTagArray structure that contains the property tags identifying properties affected by the event.

Remarks

The OBJECT_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. When the info member of a NOTIFICATION structure contains an OBJECT_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to one of the following types of events:

  • fnevObjectCreated

  • fnevObjectModified

  • fnevObjectDeleted

  • fnevObjectMoved

  • fnevObjectCopied

  • fnevSearchComplete

The search complete event, represented by the fnevSearchComplete event type, indicates that the initial search of the domain for one search folder has completed.

The following members that contain information about the original object are used only in move and copy events.

  • cbOldID

  • lpOldID

  • cbOldParentID

  • lpOldParentID

These members do not apply to the other types of events.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

See also

Reference

NOTIFICATION
SPropTagArray

Concepts

MAPI Structures


ROWENTRY

 Copy code hover
[image]

ROWENTRY
See also Send feedback

Published: July 16, 2012

Contains a row and the operation that is performed on that row in a table through the IExchangeModifyTable interface.

C++
typedef struct
{
  ULONG         ulRowFlags;
  ULONG         cValues;
  LPSPropValue  rgPropVals;
}  ROWENTRY, FAR * LPROWENTRY;

Members

ulRowFlags

One of the following operations to be performed on the data:

ROW_ADD

Add the data to the table as a new row.

ROW_MODIFY

Modify this row in the table.

ROW_REMOVE

Remove this row from the table.

ROW_EMPTY

Do not add the row data to the table. (The row is empty.)

cValues

The number of property values in rgPropvals.

rgPropVals

An array of SPropValue structures representing the columns values to be inserted into the table.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
RulesDlg.cpp | CRulesDlg::GetSelectedItems | Used to build a list of selected rules for subsequent ModifyTable actions.

See also

Reference

ROWENTRY
IExchangeModifyTable : IUnknown

Concepts

MAPI Structures


ROWLIST

 Copy code hover
[image]

ROWLIST
See also Send feedback

Published: July 16, 2012

Contains an array of ROWENTRY structures representing rows and the operations that are performed on those rows in a table through the IExchangeModifyTable interface.

C++
typedef struct
{
  ULONG     cEntries;
  ROWENTRY  aEntries[MAPI_DIM];
}  ROWLIST, FAR * LPROWLIST;

Members

cEntries

Count of entries in the array specified by the aEntries member.

aEntries[MAPI_DIM]

Array of ROWENTRY structures that contains the rows and the operations that are performed on those rows in the table.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File | Function | Comment
RulesDlg.cpp | CRulesDlg::GetSelectedItems | Used to build a list of selected rules for subsequent ModifyTable actions.

See also

Reference

ROWENTRY
IExchangeModifyTable : IUnknown

Concepts

MAPI Structures


RTF_WCSINFO

 Copy code hover
[image]

RTF_WCSINFO
See also Send feedback

Published: July 16, 2012

This structure enables you to specify information to decompress the body of a message in compressed Rich Text Format (RTF) and, optionally, return the body stream in its native format.

Quick Info

Copy code Copy code
typedef struct {
    ULONG size;
    ULONG ulFlags;
    ULONG ulInCodePage;
    ULONG ulOutCodePage;
} RTF_WCSINFO;

Members

size

The size of the RTF_WCSINFO structure in number of bytes.

ulFlags

This is the bitmask of option flags for the WrapCompressedRTFStreamEx function. The supported option flags are:

MAPI_MODIFY

This indicates whether the client intends to write the wrapped stream interface that is returned.

STORE_UNCOMPRESSED_RTF

This indicates whether the decompressed RTF is supposed to be written to the stream that is pointed to by the lpCompressedRTFStream pointer of the WrapCompressedRTFStreamEx function.

MAPI_NATIVE_BODY

This indicates whether the decompressed stream is also converted to the native body before returning the stream. This flag cannot be combined with the MAPI_MODIFY flag.

ulInCodePage

This is the code page value of the message. Typically, this value is obtained from the PidTagInternetCodepage Canonical Property on the message. This value is only used when the MAPI_NATIVE_BODY flag is passed in ulFlags. Otherwise, this value is ignored.

ulOutCodePage

This is the code page value of the returned decompressed stream that you want. If this is set to a non-zero value, the WrapCompressedRTFStreamEx function converts the stream to the specified code page. If this is set to a zero value, MAPI decides which code page to use. This value is used only when the MAPI_NATIVE_BODY flag is passed in ulFlags, and the body format is not RTF. Otherwise, this value is ignored.

See also

Concepts

WrapCompressedRTFStreamEx


RTF_WCSRETINFO

 Copy code hover
[image]

RTF_WCSRETINFO
See also Send feedback

Published: July 16, 2012

This structure provides information about a stream in native format returned from decompressing the body of a message that is encapsulated in compressed Rich Text Format (RTF).

Quick Info

Copy code Copy code
typedef struct {
    ULONG size;
    ULONG ulStreamFlags;
} RTF_WCSRETINFO;

Members

size

The size of the RTF_WCSRETINFO structure in number of bytes.

ulStreamFlags

This is a value that indicates the format of the native body. This value is only valid if the MAPI_NATIVE_BODY flag is passed in the ulFlags parameter of the RTF_WCSINFO structure that is passed to the WrapCompressedRTFStreamEx function. This can be one of the following values:

MAPI_NATIVE_BODY_TYPE_RTF

This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is RTF.

MAPI_NATIVE_BODY_TYPE_PLAIN_TEXT

This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is plain text format.

MAPI_NATIVE_BODY_TYPE_HTML

This value is only used if ulFlags includes the MAPI_NATIVE_BODY flag, and the body is Hypertext Markup Language (HTML) format.

See also

Concepts

WrapCompressedRTFStreamEx


SAndRestriction

 Copy code hover
[image]

SAndRestriction
See also Send feedback

Published: July 16, 2012

Describes an AND restriction, which is used to join a group of restrictions using a logical AND operation.

Header file:

Mapidefs.h

C++
typedef struct _SAndRestriction
{
  ULONG cRes;
  LPSRestriction lpRes;
} SAndRestriction;

Members

cRes

Count of search restrictions in the array pointed to by the lpRes member.

lpRes

Pointer to an array of SRestriction structures that will be combined with a logical AND operation.

Remarks

The result of the SAndRestriction is TRUE if all its child restrictions evaluate to TRUE. It is FALSE if any child restriction evaluates to FALSE.

For a description of types of restrictions, how to build them, and sample code, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SAppTimeArray

 Copy code hover
[image]

SAppTimeArray
See also Send feedback

Published: July 16, 2012

Contains an array of time values.

Header file:

Mapidefs.h

C++
typedef struct _SAppTimeArray
{
  ULONG cValues;
  double FAR *lpat;
} SAppTimeArray;

Members

cValues

Count of values in the array pointed to by the lpat member.

lpat

Pointer to an array of application time values.

Remarks

The SAppTimeArray structure is used to define properties of type PT_MV_APPTIME. For more information about PT_MV_APPTIME, see List of Property Types.

See also

Concepts

MAPI Structures


SBinary

 Copy code hover
[image]

SBinary
See also Send feedback

Published: July 16, 2012

Describes a property of type PT_BINARY.

Header file:

Mapidefs.h

C++
typedef struct _SBinary
{
  ULONG      cb;
  LPBYTE     lpb;
} SBinary, FAR *LPSBinary;

Members

cb

Count of bytes in the lpb member.

lpb

Pointer to the PT_BINARY property value.

Remarks

For information about property types, see MAPI Property Type Overview.

See also

Reference

SPropValue

Concepts

MAPI Structures


SBinaryArray

 Copy code hover
[image]

SBinaryArray
See also Send feedback

Published: July 16, 2012

Contains an array of binary values.

Header file:

Mapidefs.h

C++
typedef struct _SBinaryArray
{
  ULONG cValues;
  SBinary FAR *lpbin;
} SBinaryArray;

Members

cValues

Count of values in the array pointed to by the lpbin member.

lpbin

Pointer to an array of SBinary structures that holds the binary values.

Remarks

The SBinaryArray structure is used to describe properties of type PT_MV_BINARY.

For more information about PT_MV_BINARY, see List of Property Types.

See also

Reference

SBinary
SPropValue

Concepts

MAPI Structures


SBitMaskRestriction

 Copy code hover
[image]

SBitMaskRestriction
See also Send feedback

Published: July 16, 2012

Describes a bitmask restriction, which is used to perform a bitwise AND operation and test the result.

Header file:

Mapidefs.h

C++
typedef struct _SBitMaskRestriction
{
  ULONG relBMR;
  PT_LONG ulPropTag;
  ULONG ulMask;
} SBitMaskRestriction;

Members

relBMR

Relational operator that describes how the mask specified in the ulMask member should be applied to the property tag. Possible values are as follows:

BMR_EQZ

Perform a bitwise AND operation of the mask in the ulMask member with the property represented by the ulPropTag member and test for being equal to zero.

BMR_NEZ

Perform a bitwise AND operation of the mask in the ulMask member with the property represented by the ulPropTag member and test for being not equal to zero.

ulPropTag

Property tag of the property to which the bitmask is applied.

ulMask

Bitmask to apply to the property identified by ulPropTag.

Remarks

The SBitMaskRestriction structure performs a bitwise AND operation using the bitmask described in the ulMask member and the value of the property described by the ulPropTag member. If the result is zero, BMR_EQZ is satisfied. If it is nonzero, that is, if the property value has at least one of the same bits set as ulMask, then BMR_NEZ is satisfied.

For more information about the SBitMaskRestriction structure and restrictions in general, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SCommentRestriction

 Copy code hover
[image]

SCommentRestriction
See also Send feedback

Published: July 16, 2012

Describes a comment restriction, which is used to annotate a restriction.

Header file:

Mapidefs.h

C++
typedef struct _SCommentRestriction
{
  ULONG          cValues;
  LPSRestriction lpRes;
  LPSPropValue   lpProp;
} SCommentRestriction;

Members

cValues

Count of property values in the array pointed to by the lpProp member.

lpRes

Pointer to an SRestriction structure.

lpProp

Pointer to an array of SPropValue structures, each containing the property tag and value for a named property.

Remarks

The SCommentRestriction structure associates an object together with a set of named properties. Comment restrictions are unlike other restrictions because they are not evaluated. That is, they are ignored by the IMAPITable::Restrict method. There is no effect on the rows returned by the IMAPITable::QueryRows method after an IMAPITable::Restrict call has been made.

The SCommentRestriction structure can be used to keep application-specific information with a restriction when it is saved on disk. For example, a client saving the name of a named property used in a property restriction can do so in an SCommentRestriction structure. Saving a property name is not possible in a property restriction because the associated SPropertyRestriction structure holds only the property tag.

For more information about the SCommentRestriction structure and restrictions in general, see About Restrictions.

See also

Reference

SPropValue
SRestriction
SPropertyRestriction

Concepts

MAPI Structures


SComparePropsRestriction

 Copy code hover
[image]

SComparePropsRestriction
See also Send feedback

Published: July 16, 2012

Describes a compare property restriction, which tests two properties using a relational operator.

Header file:

Mapidefs.h

C++
typedef struct _SComparePropsRestriction
{
  ULONG relop;
  ULONG ulPropTag1;
  ULONG ulPropTag2;
} SComparePropsRestriction;

Members

relop

Relational operator to use to compare the two properties. Possible values are as follows:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag1

Property tag of the first property to be compared.

ulPropTag2

Property tag of the second property to be compared.

Remarks

The comparison order is (property tag 1) (relational operator) (property tag 2). The properties to be compared must be of the same type. Attempting to compare properties of different types causes MAPI or the service provider to return the error value MAPI_E_TOO_COMPLEX from the IMAPITable method to which the structure is passed as a parameter.

The result of a compare property value restriction is undefined when one or both of the properties do not exist. When a client requires well-defined behavior for such a restriction and is not sure whether the property exists, (for example, it is not a required column of a table) it should create an AND restriction to join the compare property restriction with an exist restriction. Use an SExistRestriction structure to define the exist restriction and an SAndRestriction structure to define the AND restriction.

The properties specified in the ulPropTag1 and ulPropTag2 members can be multi-valued if the service provider supports it.

For more information about the SComparePropsRestriction structure and restrictions in general, see About Restrictions.

See also

Reference

SBitMaskRestriction
SRestriction

Concepts

MAPI Structures


SContentRestriction

 Copy code hover
[image]

SContentRestriction
See also Send feedback

Published: July 16, 2012

Describes a content restriction, which is used to limit a table view to only those rows that include a column with contents matching a search string.

Header file:

Mapidefs.h

C++
typedef struct _SContentRestriction
{
  ULONG        ulFuzzyLevel;
  ULONG        ulPropTag;
  LPSPropValue lpProp;
} SContentRestriction;

Members

ulFuzzyLevel

Option settings defining the level of preciseness that the content restriction should enforce when you verify for a match.

The lower 16 bits of the ulFuzzyLevel member apply to properties of type PT_BINARY and PT_STRING8 and must be set to one of the following values:

FL_FULLSTRING

To match, the lpProp search string must be contained in the property identified by ulPropTag.

FL_PREFIX

To match, the lpProp search string must appear at the start of the property identified by ulPropTag. The two strings should be compared only up to the length of the search string indicated by lpProp.

FL_SUBSTRING

To match, the lpProp search string must be contained anywhere in the property identified by ulPropTag.

The upper 16 bits of the ulFuzzyLevel member apply only to properties of type PT_STRING8 and can be set to the following values in any combination:

FL_IGNORECASE

The comparison should be made without considering case.

FL_IGNORENONSPACE

The comparison should ignore Unicode-defined non-spacing characters such as diacritical marks.

FL_LOOSE

The comparison should give you a match whenever possible, ignoring case and non-spacing characters.

ulPropTag

Property tag identifying the string property to be checked for occurrence of the search string.

lpProp

Pointer to a property value structure that contains the string value to use as the search string.

Remarks

There are two property tags in an SContentRestriction structure: one in the ulPropTag member and the other in the ulPropTag member of the SPropValue structure pointed to by lpProp. In both tags, MAPI requires only the property type field and ignores the property identifier field. However, the two property types must match, or else the error value MAPI_E_TOO_COMPLEX is returned when the restriction is used in a call to IMAPITable::Restrict or IMAPITable::FindRow.

The values FL_FULLSTRING, FL_PREFIX, and FL_SUBSTRING are mutually exclusive. Only one of them can be set, and one of them must be set. Their meanings are fixed, and the provider must implement them exactly as defined. The provider should return MAPI_E_TOO_COMPLEX if it is unable to support these values.

The values FL_IGNORECASE, FL_IGNORENONSPACE, and FL_LOOSE are independent. Anywhere from zero to all three of them can be set. Their definitions are provided as a guideline only, and the provider is free to implement its own specific meaning of each flag. The provider should not return any error indication if it has no implementation of a specified flag.

The result of a content restriction imposed against a property is undefined when the property does not exist. When a client requires well-defined behavior for such a restriction and is not sure whether the property exists for example, it is not a required column of a table it should create an AND restriction to join the content restriction with an exist restriction. Use an SExistRestriction structure to define the exist restriction and an SAndRestriction structure to define the AND restriction.

For more information about the SContentRestriction structure and restrictions in general, see About Restrictions.

See also

Reference

SPropValue
SRestriction

Concepts

MAPI Structures


SCurrencyArray

 Copy code hover
[image]

SCurrencyArray
See also Send feedback

Published: July 16, 2012

Contains an array of currency values that are used to describe a property of type PT_MV_CURRENCY.

Header file:

Mapidefs.h

C++
typedef struct _SCurrencyArray
{
  ULONG         cValues;
  CURRENCY FAR *lpcur;
} SCurrencyArray;

Members

cValues

Count of values in the array pointed to by the lpcur member.

lpcur

Pointer to an array of CURRENCY structures that contain the currency values.

Remarks

For information about PT_MV_CURRENCY, see List of Property Types.

See also

Reference

CURRENCY
SPropValue

Concepts

MAPI Structures


SDateTimeArray

 Copy code hover
[image]

SDateTimeArray
See also Send feedback

Published: July 16, 2012

Contains an array of time values that are used to describe a property of type PT_MV_SYSTIME.

Header file:

Mapidefs.h

C++
typedef struct _SDateTimeArray
{
  ULONG cValues;
  FILETIME FAR *lpft;
} SDateTimeArray;

Members

cValues

Count of values in the array pointed to by the lpft member.

lpft

Pointer to an array of FILETIME structures that contain the time values.

Remarks

For more information about PT_MV_SYSTIME, see List of Property Types.

See also

Reference

FILETIME
SPropValue

Concepts

MAPI Structures


SDoubleArray

 Copy code hover
[image]

SDoubleArray
See also Send feedback

Published: July 16, 2012

Contains an array of doubles used to describe a property of type PT_MV_DOUBLE.

Header file:

Mapidefs.h

C++
typedef struct _SDoubleArray
{
  ULONG cValues;
  double FAR *lpdbl;
} SDoubleArray;

Members

cValues

Count of values in the array pointed to by the lpdbl member.

lpdbl

Pointer to an array of double values.

Remarks

For more information about PT_MV_DOUBLE, see List of Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SExistRestriction

 Copy code hover
[image]

SExistRestriction
See also Send feedback

Published: July 16, 2012

Describes an exist restriction which is used to test whether a particular property exists as a column in the table.

Header file:

Mapidefs.h

C++
typedef struct _SExistRestriction
{
  ULONG ulReserved1;
  ULONG ulPropTag;
  ULONG ulReserved2;
} SExistRestriction;

Members

ulReserved1

Reserved; must be zero.

ulPropTag

Property tag identifying the column to be tested for existence in each row.

ulReserved2

Reserved; must be zero.

Remarks

The exist restriction is used to guarantee meaningful results for other types of restrictions that involve properties, such as property and content restrictions. When a restriction that involves a property is passed to IMAPITable::Restrict or IMAPITable::FindRow and the property does not exist, the results of the restriction are undefined. By creating an AND restriction that joins the property restriction with an exist restriction, a caller can be guaranteed accurate results.

Exist restrictions cannot be used with sub-object properties that have type PT_OBJECT.

For more information about the SExistRestriction structure, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SGuidArray

 Copy code hover
[image]

SGuidArray
See also Send feedback

Published: July 16, 2012

Contains an array of GUID structures that are used to describe a property of type PT_MV_CLSID.

Header file:

Mapidefs.h

C++
typedef struct _SGuidArray
{
  ULONG cValues;
  GUID FAR *lpguid;
} SGuidArray;

Members

cValues

Count of values in the array pointed to by the lpguid member.

lpguid

Pointer to an array of GUID structures that contains the class identifier values.

Remarks

For more information about PT_MV_CLSID, see List of Property Types.

See also

Reference

GUID
SPropValue

Concepts

MAPI Structures


SLargeIntegerArray

 Copy code hover
[image]

SLargeIntegerArray
See also Send feedback

Published: July 16, 2012

Contains an array of LARGE_INTEGER structures that are used to describe a property of type PT_MV_I8.

Header file:

Mapidefs.h

C++
typedef struct _SLargeIntegerArray
{
  ULONG cValues;
  LARGE_INTEGER FAR *lpli;
} SLargeIntegerArray;

Members

cValues

Count of values in the array pointed to by the lpli member.

lpli

Pointer to an array of LARGE_INTEGER structures holding the integer values.

Remarks

For more information about PT_MV_18, see List of Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SLongArray

 Copy code hover
[image]

SLongArray
See also Send feedback

Published: July 16, 2012

Contains an array of LONG value types that are used to describe a property of type PT_MV_LONG.

Header file:

Mapidefs.h

C++
typedef struct _SLongArray
{
  ULONG cValues;
  LONG FAR *lpl;
} SLongArray;

Members

cValues

Count of values in the array pointed to by the lpl member.

lpl

Pointer to an array of LONG values.

Remarks

For more information about PT_MV_LONG, see List of Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SLPSTRArray

 Copy code hover
[image]

SLPSTRArray
See also Send feedback

Published: July 16, 2012

Contains an array of string values that are used to describe a property of type PT_MV_STRING8.

Header file:

Mapidefs.h

C++
typedef struct _SLPSTRArray
{
  ULONG cValues;
  LPSTR FAR *lppszA;
} SLPSTRArray;

Members

cValues

Count of values in the array pointed to by the lppszA member.

lppszA

Pointer to an array of null-ended 8-bit character strings.

Remarks

For more information about PT_MV_STRING8, see List of Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SMAPIFormInfoArray

 Copy code hover
[image]

SMAPIFormInfoArray
See also Send feedback

Published: July 16, 2012

Contains an array of pointers to form information objects.

Header file: | Mapiform.h
Related macro: | CbMAPIFormInfoArray
C++
typedef struct
{
  ULONG cForms;
  LPMAPIFORMINFO aFormInfo[MAPI_DIM];
} SMAPIFormInfoArray, FAR * LPSMAPIFORMINFOARRAY;

Members

cForms

Count of pointers in the array pointed to by the aFormInfo member.

aFormInfo

Pointer to an array of pointers to form information objects.

Remarks

The SMAPIFormInfoArray structure is passed as a parameter in the following methods:

  • IMAPIFormMgr::ResolveMultipleMessageClasses

  • IMAPIFormMgr::CalcFormPropSet

  • IMAPIFormMgr::SelectMultipleForms

  • IMAPIFormContainer::ResolveMultipleMessageClasses

See also

Concepts

MAPI Structures


SMAPIFormProp

 Copy code hover
[image]

SMAPIFormProp
See also Send feedback

Published: July 16, 2012

Describes a named property used with a form.

Header file:

Mapiform.h

C++
typedef struct _SMAPIFormProp
{
  ULONG ulFlags;
  ULONG nPropType;
  MAPINAMEID nmid;
  LPSTR pszDisplayName;
  FORMPROPSPECIALTYPE nSpecialType;
  union
  {
    struct
    {
      MAPINAMEID nmidIdx;
      ULONG cfpevAvailable;
      LPMAPIFORMPROPENUMVAL pfpevAvailable;
    } s1;
  } u;
} SMAPIFormProp, FAR * LPMAPIFORMPROP;

Members

ulFlags

Flags used to distinguish the format of the strings in the SMAPIFormProp structure. The following flag can be set:

MAPI_UNICODE

The strings returned are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

nPropType

Type of the named property, with the most significant word set to zero.

nmid

Name for the named property, which includes a GUID structure identifying the property set and either a numeric or string value that represents an interface identifier and form name.

pszDisplayName

Pointer to the display name of the named property.

nSpecialType

Value describing the type of data included in the u member. Possible values are as follows:

FPST_VANILLA

The u member does not contain an enumeration.

FPST_ENUM_PROP

The u member contains a structure that describes an enumeration.

u

Union describing the association between the name and number of the named property. By using some properties, the u member is empty. With other properties, it is represented in a structure consisting of the following members:

nmidIdx

The MAPINAMEID structure that contains the property set and identifier for the named property.

cfpevAvailable

Count of SMAPIFormPropEnumVal structures in the array pointed to by the pfpevAvailable member.

pfpevAvailable

Pointer to an array of SMAPIFormPropEnumVal structures, each of which holds a value for the named property.

Remarks

The SMAPIFormProp structure contains information about a form property used as part of the definitions of the IMAPIFormInfo interface; nSpecialType contains a tag that applies to the u union that is part of SMAPIFormProp.

See also

Reference

MAPINAMEID
SMAPIFormPropEnumVal

Concepts

MAPI Structures


SMAPIFormPropArray

 Copy code hover
[image]

SMAPIFormPropArray
See also Send feedback

Published: July 16, 2012

Contains an array of SMAPIFormProp structures.

Header file: | Mapiform.h
Related macro: | CbMAPIFormPropArray
C++
typedef struct
{
  ULONG cProps;
  ULONG ulPad;
  SMAPIFormProp aFormProp[MAPI_DIM];
} SMAPIFormPropArray, FAR * LPMAPIFORMPROPARRAY;

Members

cProps

Count of named properties in the array in the aFormProp member.

ulPad

Eight bytes of padding used to guarantee correct alignment.

aFormProp

Array of form properties.

Remarks

The SMAPIFormPropArray structure is passed as a parameter to the following methods:

  • IMAPIFormInfo::CalcFormPropSet

  • IMAPIFormMgr::CalcFormPropSet

  • IMAPIFormContainer::CalcFormPropSet

See also

Reference

CbMAPIFormPropArray
SMAPIFormProp

Concepts

MAPI Structures


SMAPIFormPropEnumVal

 Copy code hover
[image]

SMAPIFormPropEnumVal
See also Send feedback

Published: July 16, 2012

Maps an enumerated integer value to a display name for that value.

Header file:

Mapiform.h

C++
typedef struct _SMAPIFormPropEnumVal
{
  LPSTR pszDisplayName;
  ULONG nVal;
} SMAPIFormPropEnumVal;

Members

pszDisplayName

String that contains the display name for the value specified in the nVal member.

nVal

An enumeration value for the display name pointed to by the pszDisplayName member.

Remarks

When a user selects a display name from a form, the name's corresponding enumeration value is stored by using the IMAPIProp interface implementation that is associated with the form.

See also

Reference

SMAPIFormProp
SPropValue

Concepts

MAPI Structures


SMAPIVerb

 Copy code hover
[image]

SMAPIVerb
See also Send feedback

Published: July 16, 2012

Describes a MAPI verb.

Header file:

Mapiform.h

C++
typedef struct
{
  ULONG lVerb;
  LPSTR szVerbname;
  DWORD fuFlags;
  DWORD grfAttribs;
  ULONG ulFlags; /* Either 0 or MAPI_UNICODE */
} SMAPIVerb, FAR * LPMAPIVERB;

Members

lVerb

Code representing the verb that is passed to IMAPIForm::DoVerb. Standard verbs are defined in the header file Exchform.h.

szVerbname

Display name of the verb as it appears on the form menu.

fuFlags

Flags for the verb.

grfAttribs

Attributes of the verb.

ulFlags

Flag indicating the format of the verb's display name. The following flag can be set:

MAPI_UNICODE

The display name is in Unicode format. If the MAPI_UNICODE flag is not set, the display name is in ANSI format.

Remarks

The SMAPIVerb structure is passed as a parameter in the following methods:

  • IMAPIFormContainer::ResolveMultipleMessageClasses

  • IMAPIFormMgr::ResolveMultipleMessageClasses

See also

Reference

CbMessageClassArray

Concepts

MAPI Structures


SMAPIVerbArray

 Copy code hover
[image]

SMAPIVerbArray
See also Send feedback

Published: July 16, 2012

Contains an array of SMAPIVerb structures that describe MAPI verbs.

Header file: | Mapiform.h
Related macro: | CbMAPIVerbArray
C++
typedef struct
{
  ULONG cMAPIVerb;
  SMAPIVerb aMAPIVerb[MAPI_DIM];
} SMAPIVerbArray, FAR * LPMAPIVERBARRAY;

Members

cForms

Count of verbs in the array.

aFormInfo

Array of MAPI verbs.

Remarks

The SMAPIVerbArray structure is passed as a parameter in the IMAPIFormInfo::CalcVerbSet method.

See also

Reference

SMAPIVerb

Concepts

MAPI Structures


SMessageClassArray

 Copy code hover
[image]

SMessageClassArray
See also Send feedback

Published: July 16, 2012

Contains an array of pointers to message class strings.

Header file: | Mapiform.h
Related macro: | CbMessageClassArray
C++
typedef struct
{
  ULONG cValues;
  LPCSTR aMessageClass[MAPI_DIM];
} SMessageClassArray, FAR * LPSMESSAGECLASSARRAY;

Members

cValues

Count of message class string pointers in the array.

aMessageClass

Array of pointers to message class strings.

Remarks

The SMessageClassArray structure is passed as a parameter in the following methods:

  • IMAPIFormContainer::ResolveMultipleMessageClasses

  • IMAPIFormMgr::ResolveMultipleMessageClasses

See also

Concepts

MAPI Structures


SNotRestriction

 Copy code hover
[image]

SNotRestriction
See also Send feedback

Published: July 16, 2012

Describes a NOT restriction, which is used to apply a logical NOT operation to a restriction.

Header file:

Mapidefs.h

C++
typedef struct _SNotRestriction
{
  ULONG ulReserved;
  LPSRestriction lpRes;
} SNotRestriction;

Members

ulReserved

[in] Reserved; must be zero.

lpRes

Pointer to a SRestriction structure describing the restriction to be joined to the logical NOT operator.

Remarks

For more information about the SNotRestriction structure, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SOrRestriction

 Copy code hover
[image]

SOrRestriction
See also Send feedback

Published: July 16, 2012

Describes an OR restriction which is used to apply a logical OR operation to a restriction.

Header file:

Mapidefs.h

C++
typedef struct _SOrRestriction
{
  ULONG cRes;
  LPSRestriction lpRes;
} SOrRestriction;

Members

cRes

Count of structures in the array pointed to by the lpRes member.

lpRes

Pointer to the SRestriction structure describing the restriction to be joined using the logical OR operation.

Remarks

For more information about the SOrRestriction structure, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SPropAttrArray

 Copy code hover
[image]

SPropAttrArray
See also Send feedback

Published: July 16, 2012

Contains a list of attributes for properties of an object.

Header file: | Imessage.h
Related macros: | CbNewSPropAttrArray, CbSPropAttrArray
C++
typedef struct
{
  ULONG cValues;
  ULONG aPropAttr[MAPI_DIM];
} SPropAttrArray, FAR *LPSPropAttrArray;

Members

cValues

Count of property attributes in the aPropAttr member.

aPropAttr

An array of property attributes. Valid values for attributes are as follows:

  • PROPATTR_MANDATORY

  • PROPATTR_READABLE

  • PROPATTR_WRITEABLE

  • PROPATTR_NOT_PRESENT

Remarks

The SPropAttrArray structure is used by property data objects that implement the IPropData : IMAPIProp interface. It is also used by MAPI's implementation of IMAPIMessageSite : IUnknown that is based on structured storage.

See also

Reference

IPropData : IMAPIProp
IMAPIMessageSite : IUnknown
CbNewSPropAttrArray
CbSPropAttrArray

Concepts

MAPI Structures


SPropertyRestriction

 Copy code hover
[image]

SPropertyRestriction
See also Send feedback

Published: July 16, 2012

Describes a property restriction that is used to match a constant with the value of a property.

Header file:

Mapidefs.h

C++
typedef struct _SPropertyRestriction
{
  ULONG relop;
  ULONG ulPropTag;
  LPSPropValue lpProp;
} SPropertyRestriction;

Members

relop

Relational operator that will be used in the search. Possible values are as follows:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag

Property tag identifying the property to be compared.

lpProp

Pointer to an SPropValue structure that contains the constant value that will be used in the comparison.

Remarks

There are two property tags in an SPropertyRestriction structure. One is in the ulPropTag member and the other is in the ulPropTag member of the SPropValue structure pointed to by lpProp. MAPI requires both the property identifier field and the property type field. The ulPropTag in SPropertyRestriction is the property to be matched, and the lpProp pointer of the SPropertyRestriction to the ulPropTag's type of the SPropValue indicates how the members value of the lpProp union are interpreted. The two property types must match, or else the error value MAPI_E_TOO_COMPLEX is returned when the restriction is used in a call to IMAPITable::Restrict or IMAPITable::FindRow.

The comparison order is (property value) (relational operator) (constant value).

When a property restriction is passed to IMAPITable::Restrict or IMAPITable::FindRow and the target property does not exist, the results of the restriction are undefined. By creating an AND restriction that joins the property restriction with an EXIST restriction, a caller can be guaranteed accurate results. Use an SExistRestriction structure to define the EXIST restriction and an SAndRestriction structure to define the AND restriction.

Multi-valued property tags can be used in property restrictions if the service provider implementing the table supports them. If supported, multi-valued property tags can be used anywhere single-valued property tags can be used.

Multi-valued property tags can be used in the following methods:

  • IMAPIProp::SetProps

  • IMAPIProp::GetProps

  • IMAPITable::SetColumns

  • IMAPITable::SortTable

  • IMAPITable::Restrict

Important note Important

A notable case when the two property tags won't match is if restricting on a multi-value property. In this case the following must be true.

If the property type of the ulPropTag of SPropertyRestriction contains the multi-value property type bit flag MV_FLAG (0x1000), the property type of the ulPropTag of SPropValue should match the former minus the MV_FLAG bit flag, that is, its inverse.

For example, to restrict using a multi-value custom string property such as a category with a property tag for the property 0x8012101f, that is, PROP_TAG(MV_FLAG|PT_UNICODE, 0x8012)), the corresponding SPropertyRestriction would appear as follows.

SPropertyRestriction.ulPropTag = 0x8012101f; // attempt to restrict a MultiValue property

SPropertyRestriction.lpProp->ulPropTag = 0x8012001f; // the lpszW member of the Value property is valid

SPropertyRestriction.lpProp.Value->lpszW = L"My Category";

Note that if the property type of the ulPropTag of SPropValue contains the MV_FLAG bit flag, the likely return is MAPI_E_TOO_COMPLEX.

For more information about the SPropertyRestriction structure, see About Restrictions.

See also

Reference

SExistRestriction
SAndRestriction
SPropValue
SRestriction
IMAPITable::FindRow
IMAPITable::Restrict

Concepts

MAPI Structures


SPropProblem

 Copy code hover
[image]

SPropProblem
See also Send feedback

Published: July 16, 2012

Describes an error that relate to an operation involving a property.

Header file:

Mapidefs.h

C++
typedef struct _SPropProblem
{
  ULONG ulIndex;
  ULONG ulPropTag;
  SCODE scode;
} SPropProblem, FAR *LPSPropProblem;

Members

ulIndex

An index in an array of property tags.

ulPropTag

Property tag for the property that has the error.

scode

Error value describing the problem with the property. This value can be any MAPI SCODE value.

Remarks

An array of SPropProblem structures is returned from the following methods:

  • IMAPISupport::DoCopyTo

  • IMAPISupport::DoCopyProps

  • IMAPIProp::DeleteProps

  • IMAPIProp::SetProps

  • IMAPIProp::CopyProps

  • IMAPIProp::CopyTo

  • IPropData::HrAddObjProps

An SPropProblem structure contains an SCODE error value that results from an operation trying to modify or delete a MAPI property.

For more information about how the SPropProblem structure works with errors related to properties, see MAPI Named Properties.

See also

Reference

SCODE
SPropProblemArray

Concepts

MAPI Structures


SPropProblemArray

 Copy code hover
[image]

SPropProblemArray
See also Send feedback

Published: July 16, 2012

Contains an array of one or more SPropProblem structures.

Header file:

Mapidefs.h

Related macros:

  • CbNewSPropProblemArray

  • CbSPropProblemArray

  • SizedSPropProblemArray

C++
typedef struct _SPropProblemArray
{
  ULONG cProblem;
  SPropProblem aProblem[MAPI_DIM];
} SPropProblemArray, FAR *LPSPropProblemArray;

Members

cProblem

Count of SPropProblem structures in the array indicated by the aProblem member.

aProblem

Array of SPropProblem structures, each describing a property error.

Remarks

For more information about how the SPropProblem and SPropProblemArray structures work with errors related to properties, see MAPI Named Properties.

See also

Reference

SCODE
SPropProblem

Concepts

MAPI Structures


SPropTagArray

 Copy code hover
[image]

SPropTagArray
See also Send feedback

Published: July 16, 2012

Contains an array of property tags.

Header file: | Mapidefs.h
Related macros: | CbNewSPropTagArray, CbSPropTagArray, SizedSPropTagArray
C++
typedef struct _SPropTagArray
{
  ULONG cValues;
  ULONG aulPropTag[MAPI_DIM];
} SPropTagArray, FAR *LPSPropTagArray;

Members

cValues

Count of property tags in the array indicated by the aulPropTag member.

aulPropTag

Array of property tags.

Remarks

A property tag is a 32-bit unsigned integer that consists of two parts:

  • An identifier in the high-order 16 bits.

  • A type in the low-order 16 bits.

The identifier is a numeric value in a particular range. MAPI defines ranges for identifiers to describe what the property is used for and who is responsible for maintaining it. MAPI defines constraints for each of the property tags that it supports in the Mapitags.h header file.

The type indicates the format for the property's value. MAPI defines constants for each of the property types that it supports in the Mapidefs.h header file.

For more information about property tags and their components, see one of the following topics:

MAPI Property Tags

MAPI Property Identifier Overview

MAPI Property Type Overview

For a complete list of the single-valued and multi-valued property types, see the appendix, Property Identifiers and Types.

See also

Concepts

MAPI Structures


SPropValue

 Copy code hover
[image]

SPropValue
See also Send feedback

Published: July 16, 2012

Describes a MAPI property.

Header file: | Mapidefs.h
Related macros: | CHANGE_PROP_TYPE, MVI_PROP, PROP_ID, PROP_TAG, PROP_TYPE
C++
typedef struct _SPropValue
{
  ULONG ulPropTag;
  ULONG dwAlignPad;
  union _PV Value;
} SPropValue, FAR *LPSPropValue;

Members

ulPropTag

Property tag for the property. Property tags are 32-bit unsigned integers consisting of the property's unique identifier in the high-order 16 bits and the property's type in the low-order 16 bits.

dwAlignPad

Reserved for MAPI; do not use.

Value

Union of data values, the specific value dictated by the property type. The following table lists for each property type, the member of the union that should be used and its associated data type.

Property type

Value

Data type of Value

PT_I2 or PT_SHORT

i

short int

PT_I4 or PT_LONG (signed)

l

LONG

PT_I4 or PT_LONG (unsigned)

ul

ULONG

PT_R4 or PT_FLOAT

flt

float

PT_R8 or PT_DOUBLE

dbl

double

PT_BOOLEAN

b

unsigned short int

PT_CURRENCY

cur

CURRENCY

PT_APPTIME

at

double

PT_SYSTIME

ft

FILETIME

PT_STRING8

lpszA

LPSTR

PT_BINARY

bin

BYTE [array]

PT_UNICODE

lpszW

LPWSTR

PT_CLSID

lpguid

LPGUID

PT_I8 or PT_LONGLONG

li

LARGE_INTEGER

PT_MV_I2

MVi

SShortArray

PT_MV_LONG

MVI

SLongArray

PT_MV_R4

MVflt

SRealArray

PT_MV_DOUBLE

MVdbl

SDoubleArray

PT_MV_CURRENCY

MVcur

SCurrencyArray

PT_MV_APPTIME

MVat

SAppTimeArray

PT_MV_SYSTIME

MVft

SDateTimeArray

PT_MV_BINARY

MVbin

SBinaryArray

PT_MV_STRING8

MVszA

SLPSTRArray

PT_MV_UNICODE

MVszW

SWStringArray

PT_MV_CLSID

MVguid

SGuidArray

PT_MV_I8

MVli

SLargeIntegerArray

PT_ERROR

err

SCODE

PT_NULL or PT_OBJECT

x

LONG

PT_PTR

lpv

VOID *

Remarks

The ulPropTag member is made up of two parts:

  • An identifier in the high-order 16 bits.

  • A type in the low-order 16 bits.

The identifier is a numeric value within a particular range. MAPI defines ranges for identifiers to describe what the property is used for and who is responsible for maintaining it. MAPI defines constraints for each of the property tags that it supports in the Mapitags.h header file.

The type indicates the format for the property's value. MAPI defines constants for each of the property types that it supports in the Mapidefs.h header file.

For a complete list of the valid property ranges for identifiers and property types, see the Property Identifiers and Types appendix.

The dwAlignPad member is used as padding to make sure proper alignment on computers that require 8-byte alignment for 8-byte values. Developers who write code on such computers should use memory allocation routines that allocate the SPropValue arrays on 8-byte boundaries.

For more information, see MAPI Property Type Overview and Updating MAPI Properties.

See also

Concepts

MAPI Structures


SRealArray

 Copy code hover
[image]

SRealArray
See also Send feedback

Published: July 16, 2012

Contains an array of float values that are used to describe a property of type PT_MV_R4.

Header file:

Mapidefs.h

C++
typedef struct _SRealArray
{
  ULONG cValues;
  float FAR *lpflt;
} SRealArray;

Members

cValues

Count of values in the array pointed to by the lpflt member.

lpflt

Pointer to an array of float values.

Remarks

For more information about the PT_MV_R4 property type, see Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SRestriction

 Copy code hover
[image]

SRestriction
See also Send feedback

Published: July 16, 2012

Describes a filter for limiting the view of a table to particular rows.

Header file:

Mapidefs.h

C++
typedef struct _SRestriction
{
  ULONG rt;
  union
  {
    SComparePropsRestriction resCompareProps;
    SAndRestriction resAnd;
    SOrRestriction resOr;
    SNotRestriction resNot;
    SContentRestriction resContent;
    SPropertyRestriction resProperty;
    SBitMaskRestriction resBitMask;
    SSizeRestriction resSize;
    SExistRestriction resExist;
    SSubRestriction resSub;
    SCommentRestriction resComment;
  } res;
} SRestriction;

Members

rt

The restriction type. Possible values are as follows:

RES_AND

An AND restriction, which applies a bitwise AND operation to a restriction.

RES_BITMASK

A bitmask restriction, which applies a bitmask to a property value.

RES_COMMENT

A comment restriction, which associates a comment with a restriction.

RES_COMPAREPROPS

A property comparison restriction, which compares two property values.

RES_CONTENT

A content restriction, which searches a property value for specific content.

RES_EXIST

An exist restriction, which determines whether a property is supported.

RES_NOT

A NOT restriction, which applies a logical NOT operation to a restriction.

RES_OR

An OR restriction, which applies a logical OR operation to a restriction.

RES_PROPERTY

A property restriction, which determines whether a property value matches a particular value.

RES_SIZE

A size restriction, which determines whether a property value is a particular size.

RES_SUBRESTRICTION

A sub-object restriction, which applies a restriction to a message's attachments or recipients.

res

Union of restriction structures describing the filter to be applied. The specific structure included in the res member depends on the value of the rt member. The mapping between restriction type and structure is listed in the following table.

Restriction type | Restriction structure
RES_AND | SAndRestriction
RES_BITMASK | SBitMaskRestriction
RES_COMMENT | SCommentRestriction
RES_COMPAREPROPS | SComparePropsRestriction
RES_CONTENT | SContentRestriction
RES_EXIST | SExistRestriction
RES_NOT | SNotRestriction
RES_OR | SOrRestriction
RES_PROPERTY | SPropertyRestriction
RES_SIZE | SSizeRestriction
RES_SUBRESTRICTION | SSubRestriction

Remarks

Clients use an SRestriction structure to limit the number and type of rows in their view of a table and to search for specific messages in a folder. To impose the limitation on a table, clients call either IMAPITable::Restrict or IMAPITable::FindRow. To impose the limitation on a folder, clients call the folder's IMAPIContainer::SetSearchCriteria method.

For information about how to use restrictions with tables, see About Restrictions.

See also

Reference

SAndRestriction
SBitMaskRestriction
SCommentRestriction
SComparePropsRestriction
SContentRestriction
SExistRestriction
SNotRestriction
SOrRestriction
SPropertyRestriction
SSizeRestriction
SSubRestriction

Concepts

MAPI Structures


SRow

 Copy code hover
[image]

SRow
See also Send feedback

Published: July 16, 2012

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

Header file:

Mapidefs.h

C++
typedef struct _SRow
{
  ULONG ulAdrEntryPad;
  ULONG cValues;
  LPSPropValue lpProps;
} SRow, FAR *LPSRow;

Members

ulAdrEntryPad

Padding bytes to properly align the property values pointed to by the lpProps member.

cValues

Count of property values pointed to by lpProps.

lpProps

Pointer to an array of SPropValue structures that describe the property values for the columns in the row.

Remarks

An SRow structure describes a row in a table. It is included in the TABLE_NOTIFICATION structure that accompanies a table notification.

SRow structures are used in the following methods:

  • IAddrBook::GetSearchPath

  • IAddrBook::SetSearchPath

  • IMAPITable::QueryRows

  • IMAPITable::ExpandRow

  • ITableData : IUnknown (many methods)

  • FBadRowSet

  • FreeProws

  • HrQueryAllRows

When more than one row needs to be described, an SRowSet structure is used. An SRowSet structure contains an array of SRow structures and a count of structures in the array.

The following illustration shows the relationship between an SRow and an SRowSet data structure.

Relationship between SRow and SRowSet

Relationship between SRow and SRowSet

SRow structures are defined the same as ADRENTRY structures. Therefore, a row of a recipient table and an entry in an address list can be treated the same.

For information about how the memory for SRow structures should be allocated, see Managing Memory for ADRLIST and SRowSet Structures.

See also

Reference

ADRENTRY
SPropValue
SRowSet
TABLE_NOTIFICATION

Concepts

MAPI Structures
Managing Memory for ADRLIST and SRowSet Structures


SRowSet

 Copy code hover
[image]

SRowSet
See also Send feedback

Published: July 16, 2012

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

Header file: | Mapidefs.h
Related macros: | CbNewSRowSet, CbSRowSet, SizedSRowSet
C++
typedef struct _SRowSet
{
  ULONG cRows;
  SRow aRow[MAPI_DIM];
} SRowSet, FAR *LPSRowSet;

Members

cRows

Count of SRow structures in the aRow member.

aRow

Array of SRow structures. There is one structure for each row in the table.

Remarks

An SRowSet structure is used to describe multiple rows of data from a table. SRowSet structures are used in the IAddrBook, ITableData, and IMAPITable interface methods, in addition to the following functions:

  • HrQueryAllRows

  • FBadRowSet

  • FreeProws

SRowSet structures are defined the same as ADRLIST structures to allow the rows of a recipient table and the entries in an address list to be treated the same. Both SRowSet structures and ADRLIST structures can be passed to methods such as IMessage::ModifyRecipients and IAddrBook::Address.

Also, the rules for memory allocation for SRowSet structures are the same as for ADRLIST structures. To summarize, each SPropValue structure in the array pointed to by the lpProps member of each row in the row set must be allocated separately using MAPIAllocateBuffer. Each property value structure must also be deallocated using MAPIFreeBuffer before the deallocation of its SRowSet structure so that pointers to the allocated SPropValue structures are not lost. A row's allocated memory can then be preserved and reused outside the context of the SRowSet structure.

For more information about how the memory for SRowSet structures should be allocated, see Managing Memory for ADRLIST and SRowSet Structures.

See also

Reference

ADRLIST
SPropValue
SRow
MAPIAllocateBuffer
MAPIFreeBuffer

Concepts

MAPI Structures


SShortArray

 Copy code hover
[image]

SShortArray
See also Send feedback

Published: July 16, 2012

Contains an array of unsigned integer values that are used to describe a property of type PT_MV_SHORT.

Header file:

Mapidefs.h

C++
typedef struct _SShortArray
{
  ULONG cValues;
  short int FAR *lpi;
} SShortArray;

Members

cValues

Count of values in the array pointed to by the lpi member.

lpi

Pointer to an array of unsigned integer values.

Remarks

For more information about PT_MV_SHORT and other property types, see Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


SSizeRestriction

 Copy code hover
[image]

SSizeRestriction
See also Send feedback

Published: July 16, 2012

Describes a size restriction which is used to test the size of a property value.

Header file:

Mapidefs.h

C++
typedef struct _SSizeRestriction
{
  ULONG relop;
  ULONG ulPropTag;
  ULONG cb;
} SSizeRestriction;

Members

relop

Relational operator that is used in the size comparison. Possible values are as follows:

RELOP_GE

The comparison is made based on a greater or equal first value.

RELOP_GT

The comparison is made based on a greater first value.

RELOP_LE

The comparison is made based on a lesser or equal first value.

RELOP_LT

The comparison is made based on a lesser first value.

RELOP_NE

The comparison is made based on unequal values.

RELOP_RE

The comparison is made based on LIKE (regular expression) values.

RELOP_EQ

The comparison is made based on equal values.

ulPropTag

Property tag identifying the property to test.

cb

Count of bytes in the property value.

Remarks

For a general discussion of how restrictions work, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


SSortOrder

 Copy code hover
[image]

SSortOrder
See also Send feedback

Published: July 16, 2012

Defines how to sort the rows of a table, what column to use as the sort key, and the direction of the sort.

Header file:

Mapidefs.h

C++
typedef struct _SSortOrder
{
  ULONG ulPropTag;
  ULONG ulOrder;
} SSortOrder, FAR *LPSSortOrder;

Members

ulPropTag

Property tag identifying the sort key or, for a categorized sort, the category column.

ulOrder

The order in which the data is to be sorted. Possible values are as follow:

TABLE_SORT_ASCEND

The table should be sorted in ascending order.

TABLE_SORT_COMBINE

The sort operation should create a category that combines the property identified as the sort key column in the ulPropTag member with the sort key column specified in the previous SSortOrder structure.

TABLE_SORT_COMBINE can only be used when the SSortOrder structure is being used as an entry in an SSortOrderSet structure to specify multiple sort orders for a categorized sort. TABLE_SORT_COMBINE cannot be used in the first SSortOrder structure in an SSortOrderSet structure.

TABLE_SORT_DESCEND

The table should be sorted in descending order.

TABLE_SORT_CATEG_MAX

The table should be sorted on the maximum value of the ulPropTag member for the data rows in the categories specified by the previous sort order in the SSortOrderSet structure.

TABLE_SORT_CATEG_MIN

The table should be sorted on the minimum value of the ulPropTag member for the data rows in the categories specified by the previous sort order in the in SSortOrderSet structure.

Remarks

An SSortOrder structure is used to describe how to perform either a standard sort operation or a categorized sort operation. SSortOrder structures are typically combined into an SSortOrderSet structure to describe multiple sort keys and directions. SSortOrderSet structures are used in the following functions and interface methods:

  • ITableData::HrGetView

  • IMAPIFolder::SaveContentsSort

  • IMAPITable::QuerySortOrder

  • IMAPITable::SortTable

  • FBadSortOrderSet

  • HrQueryAllRows

The range of allowed columns in a table that can be used as a sort key depends on the provider. Columns that are part of the current column set can always be used as sort keys. However, each provider determines whether sort keys can be defined by using available columns that are not in the current column set. An available column is a column that is returned from IMAPITable::QueryColumns when the TBL_ALL_COLUMNS flag is set.

The ulOrder member indicates both directional order and categorization information, for example, by conversation (PidTagConversationTopic), that is, conversational thread, which is a series of messages and replies. Rows can be sorted in either an ascending or descending sequence with all NULL entries positioned last.

The TABLE_SORT_COMBINE value indicates that the column specified in ulPropTag should be combined with the previous category column to form a composite category. That is, instead of categorizing on unique values of individual columns, TABLE_SORT_COMBINE allows for categorization on unique values of a combination of columns. For example, a single category could be defined to group messages received from a particular sender on a particular subject. Setting the value to TABLE_SORT_COMBINE reduces the number of category rows that are displayed.

Sorting on multi-valued columns is not universally supported by all table implementations. If supported, apply the MV_FLAG using the MVI_PROP macro to the property tag in the ulPropTag member to identify the sort key as a multi-valued column. Sorting on a multi-valued column is based on using the individual values.

Important note Important

The ulOrder member values TABLE_SORT_CATEG_MAX and TABLE_SORT_CATEG_MIN might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following values:

#define TABLE_SORT_CATEG_MAX ((ULONG) 0x00000004)

#define TABLE_SORT_CATEG_MIN ((ULONG) 0x00000008)

For more information about standard and categorized sorting, see Sorting and Categorization.

See also

Reference

SSortOrderSet

Concepts

MAPI Structures


SSortOrderSet

 Copy code hover
[image]

SSortOrderSet
See also Send feedback

Published: July 16, 2012

Defines a collection of sort keys for a table that is used for standard or categorized sorting.

Header file: | Mapidefs.h
Related macros: | CbNewSSortOrderSet, CbSSortOrderSet, SizedSSortOrderSet
C++
typedef struct _SSortOrderSet
{
  ULONG cSorts;
  ULONG cCategories;
  ULONG cExpanded;
  SSortOrder aSort[MAPI_DIM];
} SSortOrderSet, FAR *LPSSortOrderSet;

Members

cSorts

Count of SSortOrder structures that are included in the aSort member.

cCategories

Count of columns that are designated as category columns. Possible values range from zero, which indicates a non-categorized or standard sort, to the number indicated by the cSorts member.

cExpanded

Count of categories that start in an expanded state, where all of the rows that apply to the category are visible in the table view. Possible values range from 0 to the number indicated by cCategories.

aSort

Array of SSortOrder structures, each defining a sort order.

Remarks

A SSortOrderSet structure is used for defining multiple sort orders for standard and categorized sorting.

Each SSortOrderSet structure contains at least one SSortOrder structure defining the direction of the sort and the column that will be used as the sort key. For categorized sorting, this column is used as the category. When the value of the cSorts member exceeds the value of the cCategories member, there are more sort keys than categories, and categories are created from the columns that appear first in the SSortOrder array.

For example, if cSorts is set to 3 and cCategories is set to 2, the columns described by the ulPropTag member of the first two entries in the SSortOrder array are used as the category columns. The first entry serves as the top-level category grouping; the second entry as the secondary grouping. All of the rows that match the two category columns are sorted by using the sort key defined in the third entry.

The cExpanded member specifies the number of categories that are at first expanded. When there are multiple categories, the table implementation starts with the first column to be designated as a category and continues in sequential order with the subsequent category columns until the number of cCategories has been exceeded. If there are more category columns than there are expanded columns, the category columns are collapsed. If cExpanded is equal to zero, only the top level heading row is available to the table user for display. If cExpanded is equal to one less than the number of categories, then all of the heading rows and none of the leaf rows are available. If cExpanded is equal to the number of categories, then the table is fully expanded.

For more information about standard and categorized sorting, see Sorting and Categorization.

See also

Reference

SSortOrder
IMAPITable::ExpandRow
IMAPITable::CollapseRow

Concepts

MAPI Structures


SSubRestriction

 Copy code hover
[image]

SSubRestriction
See also Send feedback

Published: July 16, 2012

Describes a sub-object restriction which is used to filter the rows of a message's attachment or recipient table.

Header file:

Mapidefs.h

C++
typedef struct _SSubRestriction
{
  ULONG ulSubObject;
  LPSRestriction lpRes;
} SSubRestriction;

Members

ulSubObject

Type of sub-object to serve as the target for the restriction. Possible values are as follows:

PR_MESSAGE_RECIPIENTS

Apply the restriction to a message's recipient table.

PR_MESSAGE_ATTACHMENTS

Apply the restriction to a message's attachment table.

lpRes

Pointer to an SRestriction structure.

Remarks

Sub-object restrictions are not supported by all tables. Typically, only folder contents tables and search results folders support them. For example, sub-object restrictions are used to find a message that has a particular type of attachment or recipient.

If an implementation does not support sub-object restrictions, it returns MAPI_E_TOO_COMPLEX from its IMAPITable::Restrict or IMAPITable::FindRow methods.

For a general discussion of how restrictions work, see About Restrictions.

See also

Reference

SRestriction

Concepts

MAPI Structures


STATUS_OBJECT_NOTIFICATION

 Copy code hover
[image]

STATUS_OBJECT_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Describes a status object that has been affected by a change.

Header file:

Mapidefs.h

C++
typedef struct
{
  ULONG cbEntryID;
  LPENTRYID lpEntryID;
  ULONG cValues;
  LPSPropValue lpPropVals;
} STATUS_OBJECT_NOTIFICATION;

Members

cbEntryID

Count of bytes in the entry identifier pointed to by the lpEntryID member.

lpEntryID

Pointer to the entry identifier of the changed status object.

cValues

Count of SPropValue structures in the array pointed to by the lpPropVals member.

lpPropVals

Pointer to an array of SPropValue structures that describe the properties of the changed status object.

Remarks

The STATUS_OBJECT_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. The STATUS_OBJECT_NOTIFICATION structure is included with a status object notification for an event of type fnevStatusObjectModified. Status object notification is an internal MAPI notification; clients and service providers cannot register for it and service providers cannot generate it.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

See also

Reference

NOTIFICATION
SPropValue

Concepts

MAPI Structures


STnefProblem

 Copy code hover
[image]

STnefProblem
See also Send feedback

Published: July 16, 2012

Contains information about a property or attribute processing problem that occurred during the encoding or decoding of a Transport Neutral Encapsulation Format (TNEF) stream.

Header file:

Tnef.h

C++
typedef struct _STnefProblem
{
  ULONG ulComponent;
  ULONG ulAttribute;
  ULONG ulPropTag;
  SCODE scode;
} STnefProblem;

Members

ulComponent

The type of processing during which the problem occurred. If the problem occurred during message processing, the ulComponent member is set to zero. If the problem occurred during attachment processing, ulComponent is set equal to the corresponding attachment's PR_ATTACH_NUM (PidTagAttachNumber) value.

ulAttribute

Attribute associated with the property indicated by the ulPropTag member or, when the TNEF processing problem occurs when decoding an encapsulation block, one of the following values:

attMAPIProps

Message level

attAttachment

Attachment level

ulPropTag

Property tag of the property that caused the TNEF processing problem, except when the problem occurs when decoding an encapsulation block, in which case ulPropTag is set to zero.

scode

Error value indicating the problem encountered during processing.

Remarks

If an STnefProblem structure is not generated during the processing of an attribute or property, the application can continue under the assumption that the processing of that attribute or property succeeded. The only exception occurs when the problem arose during decoding of an encapsulation block. In this case, the decoding of the component corresponding to the block is stopped and decoding is continued in another component.

See also

Reference

STnefProblemArray
PidTagAttachNumber Canonical Property

Concepts

MAPI Structures


STnefProblemArray

 Copy code hover
[image]

STnefProblemArray
See also Send feedback

Published: July 16, 2012

Contains an array of STnefProblem structures describing one or more processing problems that occurred during the encoding or decoding of a Transport Neutral Encapsulation Format (TNEF) stream.

Header file:

Tnef.h

C++
typedef struct _STnefProblemArray
{
  ULONG cProblem;
  STnefProblem aProblem[MAPI_DIM];
}STnefProblemArray, FAR * LPSTnefProblemArray

Members

cProblem

Count of elements in the array specified in the aProblem member.

aProblem

Array of STnefProblem structures. Each structure contains information about a property or attribute processing problem.

Remarks

If a problem occurs during attribute or property processing, an output parameter in the ITnef::ExtractProps method and in the ITnef::Finish method each receive a pointer to an STnefProblemArray structure and ExtractProps and Finish each return the value MAPI_W_ERRORS_RETURNED. This error value indicates that a problem arose during processing and an STnefProblemArray structure was generated.

If an STnefProblem structure is not generated during the processing of an attribute or property, the client application can continue under the assumption that the processing of that attribute or property succeeded. The only exception occurs when the problem arose during decoding of an encapsulation block. If the error occurred during this decoding, MAPI_E_UNABLE_TO_COMPLETE can be returned as the SCODE in the structure. In this case, the decoding of the component corresponding to the block is stopped and decoding is continued in another component.

See also

Reference

STnefProblem
SCODE

Concepts

MAPI Structures


SWStringArray

 Copy code hover
[image]

SWStringArray
See also Send feedback

Published: July 16, 2012

Contains an array of character strings that are used to describe a property of type PT_MV_UNICODE.

Header file:

Mapidefs.h

C++
typedef struct _SWStringArray
{
  ULONG cValues;
  LPWSTR FAR *lppszW;
} SWStringArray;

Members

cValues

Count of strings in the array pointed to by the lppszW member.

lppszW

Pointer to an array of null-ended Unicode character strings.

Remarks

For more information about PT_MV_UNICODE, see Property Types.

See also

Reference

SPropValue

Concepts

MAPI Structures


TABLE_NOTIFICATION

 Copy code hover
[image]

TABLE_NOTIFICATION
See also Send feedback

Published: July 16, 2012

Describes a row in a table that has been affected by some type of event, such as a change or an error. This causes a table notification to be generated.

Header file:

Mapidefs.h

C++
typedef struct _TABLE_NOTIFICATION
{
  ULONG ulTableEvent;
  HRESULT hResult;
  SPropValue propIndex;
  SPropValue propPrior;
  SRow row;
} TABLE_NOTIFICATION;

Members

ulTableEvent

Bitmask of flags used to represent the table event type. The following flags can be set:

TABLE_CHANGED

Indicates at a high level that something about the table has changed. The table's state is as it was before the event. This means that all PR_INSTANCE_KEY (PidTagInstanceKey) properties, bookmarks, current positioning, and user interface selections are still valid. Handle this event by rereading the table. Service providers that do not want to implement rich table notifications send TABLE_CHANGED events instead of more detailed events to indicate a particular type of change.

TABLE_ERROR

An error has occurred, usually during the processing of an asynchronous operation. Errors during the processing of the following methods can generate this event:

  • IMAPITable::SortTable

  • IMAPITable::SetColumns

  • IMAPITable::Restrict

After receiving a TABLE_ERROR event, a client cannot rely on the accuracy of the table contents. Also, pending notifications about other changes might be lost. The IMAPITable::GetLastError method might not provide any additional information about the error because it was generated at some previous point, not necessarily from the last method call.

TABLE_RELOAD

The data in the table should be reloaded. Service providers send TABLE_RELOAD when, for example, the underlying data is stored in a database and the database is replaced. Handle this event by assuming that nothing about the table is still valid and by rereading the table. All bookmarks, instance keys, status and positioning information are invalid.

TABLE_RESTRICT_DONE

A restriction operation initiated with an IMAPITable::Restrict method call has completed.

TABLE_ROW_ADDED

A new row has been added to the table and the corresponding object saved. TABLE_ROW_ADDED events are generated after a call to the IMAPIProp::SaveChanges method.

TABLE_ROW_DELETED

A row has been removed from the table. The propPrior member is set to NULL.

TABLE_ROW_MODIFIED

A row has been changed. The row member contains the affected properties for the row. Multiple TABLE_ROW_MODIFIED events are sent in the order that they appear in the table view.

TABLE_ROW_MODIFIED events are sent after changes to the corresponding object have been committed with a call to the IMAPIProp::SaveChanges method. If the modified row is now the first row in the table, the value of the property tag in the propPrior member is PR_NULL (PidTagNull).

TABLE_SETCOL_DONE

A column setting operation initiated with an IMAPITable::SetColumns method call has completed.

TABLE_SORT_DONE

A table sorting operation initiated with an IMAPITable::SortTable method call has completed.

hResult

HRESULT value for the error that has occurred, if the ulTableEvent member is set to TABLE_ERROR.

propIndex

SPropValue structure for the PR_INSTANCE_KEY property of the affected row.

propPrior

SPropValue structure for the PR_INSTANCE_KEY property of the row before the affected one. If the affected row is the first row in the table, propPrior must be set to PR_NULL and not zero. Zero is not a valid property tag.

row

SRow structure describing the affected row. This structure is filled for all table notification events. For table notification events that do not pass row data, the cValues member of the SRow structure is set to zero and the lpProps member is set to NULL. Because this SRow structure is read-only; clients must make a copy of it if they want to make modifications. The ScDupPropset function can be used to make the copy.

Remarks

The TABLE_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. The info member includes a TABLE_NOTIFICATION structure when the ulEventType member of the structure is set to fnevTableModified.

The order and type of columns in the row member reflect the order and type that was in effect at the time that the notification was generated. The order and type at the time that the notification was generated is not necessarily the same as when the notification was delivered.

For more information about notification, see the topics described in the following table.

Topic | Description
Event Notification in MAPI | General overview of notification and notification events.
Handling Notifications | Discussion of how clients should handle notifications.
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications.

Because table notifications are asynchronous, clients can receive notification of an added row after learning about the addition through another means. It is possible to receive a TABLE_ERROR event when there is an error in an IMAPITable::Sort, IMAPITable::Restrict, or IMAPITable::SetColumns method or when an underlying process attempts to update a table with, for example, new or modified rows.

See also

Reference

NOTIFICATION
ScDupPropset
SRow
SPropValue

Concepts

MAPI Structures


Macros Related to Structures

 Copy code hover
[image]

Macros Related to Structures
See also Send feedback

Published: July 16, 2012

The topics in this section describe the macros related to MAPI structures. For more detailed information, cross references to other publications or to other topics in this documentation are also included.

The following table lists macros that are related to MAPI structures:

CbADRLIST | CbFLATENTRY
CbFLATENTRYLIST | CbFLATMTSIDLIST
CbMAPIFormInfoArray | CbMAPIFormPropArray
CbMAPIVerbArray | CbMessageClassArray
CbMTSID | CbNewADRLIST
CbNewENTRYID | CbNewFLATENTRY
CbNewFLATENTRYLIST | CbNewFLATMTSIDLIST
CbNewMTSID | CbNewSPropAttrArray
CbNewSPropProblemArray | CbNewSPropTagArray
CbNewSRowSet | CbNewSSortOrderSet
CbSPropAttrArray | CbSPropProblemArray
CbSPropTagArray | CbSRowSet
CbSSortOrderSet | CHANGE_PROP_TYPE
IsEqualMAPIUID | MVI_PROP
PROP_ID | PROP_TAG
PROP_TYPE | SizedADRLIST
SizedDtblButton | SizedDtblCheckBox
SizedDtblComboBox | SizedDtblEdit
SizedDtblGroupBox | SizedDtblLabel
SizedDtblPage | SizedENTRYID
SizedSPropProblemArray | SizedSPropTagArray
SizedSRowSet | SizedSSortOrderSet

See also

Concepts

MAPI Structures

Other resources

MAPI Reference


CbADRLIST

 Copy code hover
[image]

CbADRLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing ADRLIST structure.

Header file: | Mapidefs.h
Related structure | ADRLIST
CbADRLIST (_lpadrlist)

Parameters

_lpadrlist

Pointer to the existing ADRLIST structure.

See also

Reference

ADRLIST

Concepts

Macros Related to Structures


CbFLATENTRY

 Copy code hover
[image]

CbFLATENTRY
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing FLATENTRY structure.

Header file: | Mapidefs.h
Related structure: | FLATENTRY
CbFLATENTRY (_lpentry)

Parameters

_lpentry

Pointer to the existing FLATENTRY structure.

See also

Reference

FLATENTRY

Concepts

Macros Related to Structures


CbFLATENTRYLIST

 Copy code hover
[image]

CbFLATENTRYLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing FLATENTRYLIST structure.

Header file: | Mapidefs.h
Related structure: | FLATENTRYLIST
CbFLATENTRYLIST(_lplist)

Parameters

_lplist

Pointer to the FLATENTRYLIST structure in question.

See also

Reference

FLATENTRYLIST

Concepts

Macros Related to Structures


CbFLATMTSIDLIST

 Copy code hover
[image]

CbFLATMTSIDLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing FLATMTSIDLIST structure.

Header file: | Mapidefs.h
Related structure: | FLATMTSIDLIST
CbFLATMTSIDLIST (_lplist)

Parameters

_lplist

Pointer to the existing FLATMTSIDLIST structure.

See also

Reference

FLATMTSIDLIST

Concepts

Macros Related to Structures


CbMAPIFormInfoArray

 Copy code hover
[image]

CbMAPIFormInfoArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SMAPIFormInfoArray structure that contains a specified number of form information objects.

Header file: | Mapiform.h
Related structure: | SMAPIFormInfoArray
CbMAPIFormInfoArray (_c)

Parameters

_c

Count of form information objects in the existing SMAPIFormInfoArray structure.

See also

Reference

SMAPIFormInfoArray

Concepts

Macros Related to Structures


CbMAPIFormPropArray

 Copy code hover
[image]

CbMAPIFormPropArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SMAPIFormPropArray structure that contains a specified number of SMAPIFormProp structures.

Header file: | Mapiform.h
Related structure: | SMAPIFormPropArray
CbMAPIFormPropArray (_c)

Parameters

_c

Count of SMAPIFormProp structures in the SMAPIFormPropArray structure in question.

See also

Reference

SMAPIFormPropArray
SMAPIFormProp

Concepts

Macros Related to Structures


CbMAPIVerbArray

 Copy code hover
[image]

CbMAPIVerbArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SMAPIVerbArray structure that contains a specified number of SMAPIVerb structures.

Header file: | Mapiform.h
Related structure: | SMAPIVerbArray
int CbMAPIVerbArray (_c)

Parameters

_c

Count of SMAPIVerb structures in the existing SMAPIVerbArray structure.

See also

Reference

SMAPIVerbArray
SMAPIVerb

Concepts

Macros Related to Structures


CbMessageClassArray

 Copy code hover
[image]

CbMessageClassArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SMessageClassArray structure that contains a specified number of string pointers to message classes.

Header file: | Mapidefs.h
Related structure: | SMessageClassArray
CbMessageClassArray (_c)

Parameters

_c

Count of the pointers to message classes that are included in the existing SMessageClassArray.

See also

Reference

SMessageClassArray

Concepts

Macros Related to Structures


CbMTSID

 Copy code hover
[image]

CbMTSID
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing MTSID structure.

Header file: | Mapidefs.h
Related structure: | MTSID
CbMTSID (_lpentry)

Parameters

_lpentry

Pointer to the existing MTSID structure.

See also

Reference

MTSID

Concepts

Macros Related to Structures


CbNewADRLIST

 Copy code hover
[image]

CbNewADRLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new ADRLIST structure that contains a specified number of recipients represented by ADRENTRY structures.

Header file: | Mapidefs.h
Related structure: | ADRLIST
CbNewADRLIST (_centries)

Parameters

_centries

Count of ADRENTRY structures to be included in the new ADRLIST structure.

See also

Reference

ADRLIST
ADRENTRY

Concepts

Macros Related to Structures


CbNewENTRYID

 Copy code hover
[image]

CbNewENTRYID
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new ENTRYID structure of a specified size.

Header file: | Mapidefs.h
Related structure: | ENTRYID
CbNewENTRYID (_cb)

Parameters

_cb

Count of bytes in the entry identifier to be stored in the new ENTRYID structure.

See also

Reference

ENTRYID

Concepts

Macros Related to Structures


CbNewFLATENTRY

 Copy code hover
[image]

CbNewFLATENTRY
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new FLATENTRY structure that contains an entry identifier of a specified byte size.

Header file: | Mapidefs.h
Related structure: | FLATENTRY
CbNewFLATENTRY (_cb)

Parameters

_cb

Count of bytes in the entry identifier to be included in the new FLATENTRY structure.

See also

Reference

FLATENTRY

Concepts

Macros Related to Structures


CbNewFLATENTRYLIST

 Copy code hover
[image]

CbNewFLATENTRYLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new FLATENTRYLIST structure that contains several FLATENTRY structures of a specified size.

Header file: | Mapidefs.h
Related structure: | FLATENTRYLIST
CbNewFLATENTRY (_cb)

Parameters

_cb

Count of bytes in the FLATENTRY structures to be included in the new FLATENTRYLIST structure.

See also

Reference

FLATENTRYLIST
FLATENTRY

Concepts

Macros Related to Structures


CbNewFLATMTSIDLIST

 Copy code hover
[image]

CbNewFLATMTSIDLIST
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new FLATMTSIDLIST structure that contains several MTSID structures of a specified size.

Header file: | Mapidefs.h
Related structure: | FLATMTSIDLIST
CbNewFLATMTSIDIDLIST (_cb)

Parameters

_cb

Count of bytes in the MTSID structures to be included in the new FLATMTSIDLIST structure.

See also

Reference

FLATMTSIDLIST
MTSID

Concepts

Macros Related to Structures


CbNewMTSID

 Copy code hover
[image]

CbNewMTSID
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new MTSID structure with a message transfer agent identifier of a specified size.

Header file: | Mapidefs.h
Related structure: | MTSID
CbNewMTSID (_cb)

Parameters

_cb

Count of bytes for the message transfer agent identifier to be included in the new MTSID structure.

See also

Reference

MTSID

Concepts

Macros Related to Structures


CbNewSPropAttrArray

 Copy code hover
[image]

CbNewSPropAttrArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes that should be allocated for a new SPropAttrArray structure that contains a specified number of property attributes.

Header file: | Imessage.h
Related structure: | SPropAttrArray
CbNewSPropAttrArray (_cattr)

Parameters

_cattr

Count of property attributes to be included in the new SPropAttrArray structure.

See also

Reference

SPropAttrArray

Concepts

Macros Related to Structures


CbNewSPropProblemArray

 Copy code hover
[image]

CbNewSPropProblemArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes to be allocated for a new SPropProblemArray structure that contains a specified number of SPropProblem structures.

Header file: | Mapidefs.h
Related structure: | SPropProblemArray
CbNewSPropProblemArray (_cprob)

Parameters

_cprob

Count of SPropProblem structures to be included in the new SPropProblemArray structure.

See also

Reference

SPropProblemArray
SPropProblem

Concepts

Macros Related to Structures


CbNewSPropTagArray

 Copy code hover
[image]

CbNewSPropTagArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes to be allocated for a new SPropTagArray structure that contains a specified number of property tags.

Header file: | Mapidefs.h
Related structure: | SPropTagArray
CbNewSPropTagArray (_ctag)

Parameters

_ctag

Count of property tags to be included in the new SPropTagArray structure.

See also

Reference

SPropTagArray

Concepts

Macros Related to Structures


CbNewSRowSet

 Copy code hover
[image]

CbNewSRowSet
See also Send feedback

Published: July 16, 2012

Computes the number of bytes to be allocated for a new SRowSet structure that contains a specified number of rows represented by SRow structures.

Header file: | Mapidefs.h
Related structure: | SRowSet
CbNewSRowSet (_crow)

Parameters

_crow

Count of SRow structures indicating the number of rows to be included in the new SRowSet structure.

See also

Reference

SRowSet
SRow

Concepts

Macros Related to Structures


CbNewSSortOrderSet

 Copy code hover
[image]

CbNewSSortOrderSet
See also Send feedback

Published: July 16, 2012

Computes the number of bytes to be allocated for a new SizedSSortOrderSet structure that contains a specified number of sort orders represented by SSortOrder structures.

Header file: | Mapidefs.h
Related structure: | SSortOrderSet
CbNewSSortOrderSet (_csort)

Parameters

_csort

Count of SSortOrder structures to be included in the SSortOrderSet structure.

See also

Reference

SizedSSortOrderSet
SSortOrder

Concepts

Macros Related to Structures


CbSPropAttrArray

 Copy code hover
[image]

CbSPropAttrArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SPropAttrArray structure.

Header file: | Imessage.h
Related structure: | SPropAttrArray
CbSPropAttrArray (_lparray)

Parameters

_lparray

Pointer to the existing SPropAttrArray structure.

See also

Reference

SPropAttrArray

Concepts

Macros Related to Structures


CbSPropProblemArray

 Copy code hover
[image]

CbSPropProblemArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SPropProblemArray structure.

Header file: | Mapidefs.h
Related structure: | SPropProblemArray
CbSPropProblemArray (_lparray)

Parameters

_lparray

Pointer to the existing SPropProblemArray structure.

See also

Reference

SPropProblemArray

Concepts

Macros Related to Structures


CbSPropTagArray

 Copy code hover
[image]

CbSPropTagArray
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SPropTagArray structure.

Header file: | Mapidefs.h
Related structure: | SPropTagArray
CbSPropTagArray (_lparray)

Parameters

_lparray

Pointer to the existing SPropTagArray structure.

See also

Reference

SPropTagArray

Concepts

Macros Related to Structures


CbSRowSet

 Copy code hover
[image]

CbSRowSet
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SRowSet structure.

Header file: | Mapidefs.h
Related structure: | SRowSet
CbSRowSet (_lprowset)

Parameters

_lprowset

Pointer to the existing SRowSet structure.

See also

Reference

SRowSet

Concepts

Macros Related to Structures


CbSSortOrderSet

 Copy code hover
[image]

CbSSortOrderSet
See also Send feedback

Published: July 16, 2012

Computes the number of bytes in an existing SSortOrderSet structure.

Header file: | Mapidefs.h
Related structure: | SSortOrderSet
CbSSortOrderSet (_lpset)

Parameters

_lpset

Pointer to the existing SSortOrderSet structure.

See also

Reference

SSortOrderSet

Concepts

Macros Related to Structures


CHANGE_PROP_TYPE

 Copy code hover
[image]

CHANGE_PROP_TYPE
See also Send feedback

Published: July 16, 2012

Updates the property type of a property tag to a specified value. The property identifier is unchanged.

Header file: | Mapidefs.h
Related structure: | SPropValue
CHANGE_PROP_TYPE (ulPropTag, ulPropType)

Parameters

ulPropTag

The property tag to be modified.

ulPropType

The new value for the property type.

See also

Reference

SPropValue

Concepts

Macros Related to Structures


IsEqualMAPIUID

 Copy code hover
[image]

IsEqualMAPIUID
See also Send feedback

Published: July 16, 2012

Tests two MAPIUID structures to determine whether they contain the same identifier.

Header file: | Mapidefs.h
Related structure: | MAPIUID
IsEqualMAPIUID(lpuid1, lpuid2)

Parameters

lpuid1

Pointer to the first MAPIUID structure to be tested.

lpuid2

Pointer to the second MAPIUID structure to be tested.

Remarks

The IsEqualMAPIUID macro returns TRUE if the two MAPIUID structures contain the same identifier and FALSE if they do not.

The IsEqualMAPIUID macro requires that the header file Memory.h be included.

See also

Reference

MAPIUID

Concepts

Macros Related to Structures


MVI_PROP

 Copy code hover
[image]

MVI_PROP
See also Send feedback

Published: July 16, 2012

Sets the MVI_FLAG for a specified property.

Header file: | Mapidefs.h
Related structure: | SPropValue
MVI_PROP (tag)

Parameters

tag

The property tag to be modified.

Remarks

The MVI_FLAG combines the setting of MV_FLAG, identifying a property as multi-valued, and MV_INSTANCE, requesting that a multi-valued property be displayed in a table in multiple rows. The property type of the affected property is modified, but the identifier remains unchanged.

For example, when the MVI_PROP macro is applied to a property of type PT_FLOAT, its type is changed to PT_MV_FLOAT. When included in a table, multiple rows are used to represent the property that has one row for each value. The properties for the other columns are repeated.

For more information about these flags, see MAPI Property Type Overview and Working with Multivalued Columns.

See also

Reference

SPropValue

Concepts

Macros Related to Structures


PROP_ID

 Copy code hover
[image]

PROP_ID
See also Send feedback

Published: July 16, 2012

Returns the property identifier of a specified property tag.

Header file: | Mapidefs.h
Related structure: | SPropValue
PROP_ID (ulPropTag)

Parameters

ulPropTag

Property tag that contains the identifier to be returned.

Remarks

Every property tag contains the property type in the low-order word (bits 0 through 15) and the property identifier in the high-order word (bits 16 through 31). The PROP_ID macro extracts the property identifier and puts it in bits 0 through 15 of the integer to be returned. The remaining bits of the return value are set to zeros.

The PROP_ID macro can be used, for example, to retrieve an identifier to pass to IMAPIProp::GetNamesFromIDs. GetNamesFromIDs retrieves the property name associated with an identifier for a named property.

See also

Reference

SPropValue

Concepts

Macros Related to Structures


PROP_TAG

 Copy code hover
[image]

PROP_TAG
See also Send feedback

Published: July 16, 2012

Returns a property tag created by combining a specified property type and identifier.

Header file: | Mapidefs.h
Related structure: | SPropValue
PROP_TAG (ulPropType, ulPropID)

Parameters

ulPropType

Property type for the new property tag.

ulPropID

Property identifier for the new property tag.

Remarks

The PROP_TAG macro creates a property tag for a property of type ulPropType and the identifier that is specified in ulPropID. For example, a property tag for an entry identifier can be created by using the PROP_TAG macro as follows:

Copy code Copy code
PROP_TAG( PT_BINARY, 0x0FFF)

The low-order 16 bits of the returned property tag contain the property type, PT_BINARY, and the high-order 16 bits contain the property identifier, 0xFFFF.

For more information about property tags, see MAPI Property Tags.

See also

Reference

SPropValue

Concepts

Macros Related to Structures


PROP_TYPE

 Copy code hover
[image]

PROP_TYPE
See also Send feedback

Published: July 16, 2012

Returns the property type of a specified property tag.

Header file: | Mapidefs.h
Related structure: | SPropValue
PROP_TYPE (ulPropTag)

Parameters

ulPropTag

Property tag that contains the property type to be returned.

Remarks

The PROP_TYPE macro can be used to determine the type of a property. For example, calling PROP_TYPE (PR_ENTRYID (PidTagEntryId)) results in the value PT_BINARY being returned.

Every property tag contains the property type in the low-order word (bits 0 through 15) and the property identifier in the high-order word (bits 16 through 31). The PROP_TYPE macro extracts the property type and puts it in bits 0 through 15 of the integer to be returned. The remaining bits of the return value are set to zeros.

See also

Reference

SPropValue

Concepts

Macros Related to Structures


SizedADRLIST

 Copy code hover
[image]

SizedADRLIST
See also Send feedback

Published: July 16, 2012

Defines an ADRLIST structure with the specified name that contains a specified number of ADRENTRY structures.

Header file: | Mapidefs.h
Related structure: | ADRLIST
SizedADRLIST (_centries,_name)

Parameters

_centries

Count of ADRENTRY structures to be included in the new ADRLIST structure.

_name

Name for the new ADRLIST structure.

Remarks

The SizedADRLIST macro lets you define a recipient list that has explicit bounds when array length requirements are known. The following code shows how to cast the result of the SizedADRLIST macro to an ADRLIST structure pointer:

Copy code Copy code
lpADRList = (LPADRLIST) &SizedADRList;

See also

Reference

ADRLIST
ADRENTRY

Concepts

Macros Related to Structures


SizedDtblButton

 Copy code hover
[image]

SizedDtblButton
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLBUTTON structure for describing a button and a label of a specified length.

Header file: | Mapidefs.h
Related structure: | DTBLBUTTON
SizedDtblButton (n, u)

Parameters

n

Length of the label to be included in the new structure.

u

Name for the new structure.

Remarks

The new structure is created with the following members:

Copy code Copy code
DTBLBUTTON dtblbutton;
TCHAR lpszLabel[n];

See also

Reference

DTBLBUTTON

Concepts

Macros Related to Structures


SizedDtblCheckBox

 Copy code hover
[image]

SizedDtblCheckBox
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLCHECKBOX structure for describing a check box control and a label of a specified length.

Header file: | Mapidefs.h
Related structure: | DTBLCHECKBOX
SizedDtblCheckBox (n, u)

Parameters

n

Length of the label to be included in the new structure.

u

Name for the new structure.

Remarks

The SizedDtblCheckBox macro lets you define a check box when the number of label characters is known. The new structure is created with the following members:

Copy code Copy code
DTBLCHECKBOX dtblcheckbox;
TCHAR lpszLabel[n];

To use a pointer to the resulting structure from the SizedDtblCheckBox macro as a DTBLCHECKBOX structure pointer, perform the following cast:

Copy code Copy code
lpDtblCheckBox = (LPDTBLCHECKBOX) &SizedDtblCheckBox;

See also

Reference

DTBLCHECKBOX

Concepts

Macros Related to Structures


SizedDtblComboBox

 Copy code hover
[image]

SizedDtblComboBox
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLCOMBOBOX structure for describing a combo box control and the maximum number of characters that can be entered in the associated edit control.

Header file: | Mapidefs.h
Related structure: | DTBLCOMBOBOX
SizedDtblComboBox (n, u)

Parameters

n

Number of characters that can be entered in the combo box's edit control.

u

Name for the new structure.

Remarks

The SizedDtblComboBox macro lets you define a combo box when the length of the enabled character string is known. The new structure is created with the following members:

Copy code Copy code
DTBLCOMBOBOX dtblcombobox;
TCHAR lpszCharsAllowed[n];

To use a pointer to the resulting structure from the SizedDtblComboBox macro as a DTBLCOMBOBOX structure pointer, perform the following cast:

Copy code Copy code
lpDtblComboBox = (LPDTBLCOMBOBOX) &SizedDtblComboBox;

See also

Reference

DTBLCOMBOBOX

Concepts

Macros Related to Structures


SizedDtblEdit

 Copy code hover
[image]

SizedDtblEdit
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLEDIT structure for describing an edit control and the maximum number of characters that can be entered in the control.

Header file: | Mapidefs.h
Related structure: | DTBLEDIT
SizedDtblEdit (n, u)

Parameters

n

Maximum number of characters that can be entered in the edit control.

u

Name for the new structure.

Remarks

The SizedDtblEdit macro lets you define an edit control when the number of enabled characters is known. The new structure is created with the following members:

Copy code Copy code
DTBLEDIT dtbledit;
TCHAR lpszCharsAllowed[n];

To use a pointer to the resulting structure from the SizedDtblEdit macro as a DTBLEDIT structure pointer, perform the following cast:

Copy code Copy code
lpDtblEdit = (LPDTBLEDIT) &SizedDtblEdit;

See also

Reference

DTBLEDIT

Concepts

Macros Related to Structures


SizedDtblGroupBox

 Copy code hover
[image]

SizedDtblGroupBox
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLGROUPBOX structure for describing a group box control and a label of a specified length.

Header file: | Mapidefs.h
Related structure: | DTBLGROUPBOX
SizedDtblGroupBox (n, u)

Parameters

n

Length of the group box's label.

u

Name for the new structure.

Remarks

The SizedDtblGroupBox macro lets you define a group box control when the length of the label is known. The new structure is created with the following members:

Copy code Copy code
DTBLGROUPBOX dtblgroupbox;
TCHAR lpszLabel[n];

To use a pointer to the resulting structure from the SizedDtblGroupBox macro as a DTBLGROUPBOX structure pointer, perform the following cast:

Copy code Copy code
lpDtblGroupBox = (LPDTBLGROUPBOX) &SizedDtblGroupBox;

See also

Reference

DTBLGROUPBOX

Concepts

Macros Related to Structures


SizedDtblLabel

 Copy code hover
[image]

SizedDtblLabel
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLLABEL structure for describing a label control and the associated label of a specified length.

Specified in header file: | Mapidefs.h
Related structure | DTBLLABEL
SizedDtblLabel (n, u)

Parameters

n

Length of the label. This includes the ending NULL character.

u

Name for the new structure.

Remarks

The SizedDtblLabel macro lets you define a display table label when the number of characters in the label is known. The new structure is created with the following members:

Copy code Copy code
DTBLLABEL dtbllabel;
TCHAR lpszLabelName[n];

To use a pointer to the resulting structure from the SizedDtblLabel macro as a DTBLLABEL structure pointer, perform the following cast:

Copy code Copy code
lpDtblLabel = (LPDTBLLABEL) &SizedDtblLabel;

See also

Reference

DTBLLABEL

Concepts

Macros Related to Structures


SizedDtblPage

 Copy code hover
[image]

SizedDtblPage
See also Send feedback

Published: July 16, 2012

Creates a named structure that includes a DTBLPAGE structure for describing a tabbed page control, a label of a specified length, and a Help file entry of a specified length.

Header file: | Mapidefs.h
Related structure: | DTBLPAGE
SizedDtblPage (n, n1, u)

Parameters

n

Length of the label for the page tab.

n1

Length of the entry appearing in the Mapisvc.inf file identifying the Help file that will be used with the tabbed page control.

u

Name for the new structure.

Remarks

The SizedDtblPage macro lets you define a tabbed page control when the number of characters in the associated label and Help file entry is known. The new structure is created with the following members:

Copy code Copy code
DTBLPAGE dtblpage;
TCHAR lpszLabel[n];
TCHAR lpszComponent[n1];

To use a pointer to the resulting structure from the SizedDtblPage macro as a DTBLPAGE structure pointer, perform the following cast:

Copy code Copy code
lpDtblPage = (LPDTBLPAGE) &SizedDtblPage;

See also

Reference

DTBLPAGE

Concepts

Macros Related to Structures


SizedENTRYID

 Copy code hover
[image]

SizedENTRYID
See also Send feedback

Published: July 16, 2012

Creates a named ENTRYID structure that contains an ab member of a specified size.

Header file: | Mapidefs.h
Related structure: | ENTRYID
C++
SizedENTRYID (_cb, _name)

Parameters

_cb

Count of bytes in the ab member of the new structure.

_name

Name for the new structure.

Remarks

The SizedENTRYID macro lets you define an entry identifier after array length requirements are known. Use this macro to create an entry identifier with explicit bounds.

To use the new structure that results from the SizedENTRYID macro as a pointer to an ENTRYID structure, perform the following cast:

Copy code Copy code
lpENTRYID = (LPENTRYID) &SizedENTRYID;

See also

Reference

ENTRYID

Concepts

Macros Related to Structures


SizedSPropProblemArray

 Copy code hover
[image]

SizedSPropProblemArray
See also Send feedback

Published: July 16, 2012

Creates a named SPropProblemArray structure that contains a specified number of SPropProblem structures.

Header file: | Mapidefs.h
Related structure: | SPropProblemArray
SizedSPropProblemArray(_cprob, _name)

Parameters

_ cprob

Count of SPropProblem structures to be included in the new structure.

_ name

Name for the new structure.

Remarks

Use the SizedSPropProblemArray macro to create a property problem array with explicit bounds. To use the new structure that results from the SizedSPropProblemArray macro as a pointer to an SPropProblemArray structure, perform the following cast:

Copy code Copy code
lpPropProbArray = (LPSPropProblemArray) &SizedSPropProblemArray;

See also

Reference

SPropProblemArray
SPropProblem

Concepts

Macros Related to Structures


SizedSPropTagArray

 Copy code hover
[image]

SizedSPropTagArray
See also Send feedback

Published: July 16, 2012

Creates a named SPropTagArray structure that includes a specified number of property tags.

Header file: | Mapidefs.h
Related structure: | SPropTagArray
SizedSPropTagArray (_ctag, _name)

Parameters

_ ctag

Count of property tags to be included in the new structure.

_name

Name for the new structure.

Remarks

Use the SizedSPropTagArray macro to create a property tag array with explicit bounds.

To use the new structure that results from the SizedSPropTagArray macro as a pointer to an SPropTagArray structure, perform the following cast:

Copy code Copy code
lpPropTagArray = (LPPropTagArray) &SizedSPropTagArray;

See also

Reference

SPropTagArray

Concepts

Macros Related to Structures


SizedSRowSet

 Copy code hover
[image]

SizedSRowSet
See also Send feedback

Published: July 16, 2012

Creates a named SRowSet structure that contains a specified number of rows.

Header file: | Mapidefs.h
Related structure: | SRowSet
SizedSRowSet (_crow, _name)

Parameters

_crow

Count of the number of rows to be included in the new structure.

_name

Name for the new structure.

Remarks

To use the new structure that results from the SizedSRowSet macro as a pointer to an SRowSet structure, perform the following cast:

Copy code Copy code
lpSRowSet = (LPSRowSet) &SizedSRowSet;

See also

Reference

SRowSet

Concepts

Macros Related to Structures


SizedSSortOrderSet

 Copy code hover
[image]

SizedSSortOrderSet
See also Send feedback

Published: July 16, 2012

Creates a named SSortOrderSet structure that contains a specified number of sort orders.

Header file: | Mapidefs.h
Related structure: | SSortOrderSet
SizedSSortOrderSet (_csort,_name)

Parameters

_csort

Count of sort orders to be included in the new structure.

_name

Name for the new structure.

Remarks

Use the SizedSSortOrderSet macro to create a sort order set with explicit bounds.

To use the new structure that results from the SizedSSortOrderSet macro as a pointer to an SSortOrderSet structure, perform the following cast:

Copy code Copy code
lpSSortOrderSet = (LPSSortOrderSet) &SizedSSortOrderSet;

See also

Reference

SSortOrderSet

Concepts

Macros Related to Structures


MAPI Data Types

 Copy code hover
[image]

MAPI Data Types
See also Send feedback

Published: July 16, 2012

The following alphabetized entries contain documentation for the data types used in MAPI methods, functions, and structures.

BOOKMARK

DNHIER

DNTBL

DNTBLE

EXCHANGE_STORE_VERSION_NUM

FEID

FollowUpStatus

Gender

HDRSYNC

HRESULT

LTID

MAPIOFFLINE_ADVISEINFO

MAPIOFFLINE_CALLBACK_TYPE

MAPIOFFLINE_NOTIFY

MAPIOFFLINE_NOTIFY_TYPE

MEID

MSCAP_SELECTOR

OLFI

OlFlagIcon

SCODE

SKEY

SYNC

SYNCCONT

SYNCSTATE

TCHAR

UPDEL

UPDELE

UPFLD

UPHIER

UPMOV

UPMSG

UPREAD

UPREADE

UPTBL

UPTBLE

See also

Other resources

MAPI Reference


BOOKMARK

 Copy code hover
[image]

BOOKMARK
See also Send feedback

Published: July 16, 2012

Defines bookmarks data for remembering a position in a table.

Header file: | Mapidefs.h
Related methods: | IMAPITable::CreateBookmark IMAPITable::FreeBookmark
C++
typedef ULONG_PTR BOOKMARK;

Remarks

MAPI defines three bookmarks, listed as follows:

BOOKMARK_BEGINNING

Remembers the starting position of the table.

BOOKMARK_CURRENT

Remembers the current position of the table.

BOOKMARK_END

Remembers the ending position of the table.

Clients can create other bookmarks for remembering other table positions. Bookmarks are valid only when the table is open. Clients must free any bookmarks that they have created before closing the associated table.

See also

Reference

IMAPITable::CreateBookmark
IMAPITable::FindRow
IMAPITable::FreeBookmark
IMAPITable::SeekRow

Concepts

MAPI Data Types


DNHIER

 Copy code hover
[image]

DNHIER
See also Send feedback

Published: July 16, 2012

Information for downloading a hierarchy from the server during the download hierarchy state, which is part of a full hierarchy synchronization. This downloading process uses Microsoft Exchange Incremental Change Synchronization (ICS). For more information on ICS, see ICS Evaluation Criteria.

Quick Info

Copy code Copy code
struct DNHIER
{
    ULONG ulFlags;
    LPSTREAM pstmReserved;
    PXIHC pxihc;
    UINT cEntNew;
   UINT cEntMod;
    UINT cEntDel;
};

Members

ulFlags

[in] Flags to determine the appropriate behavior during the download.

  • DNH_OK

    • [in] Download was successful. The client sets this after downloading information from the server.

pstmReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

pxihc

[out] Pointer to the IExchangeImportHierarchyChanges hierarchy interface that supports downloading incremental hierarchy changes. For more information on IExchangeImportHierarchyChanges, see ICS Evaluation Criteria.

cEntNew

[out] Number of folders added to the local store. Outlook populates this value during the downloading when using ICS.

cEntMod

[out] Number of folders to be modified on the local store. Outlook populates this value during the downloading when using ICS.

cEntDel

[out] Number of folders to be deleted on the local store. Outlook populates this value during the downloading when using ICS.

See also

Concepts

About the Replication State Machine
MAPI Constants


DNTBL

 Copy code hover
[image]

DNTBL
See also Send feedback

Published: July 16, 2012

Information for downloading the contents of a folder from the server during the download table state, as part of a full synchronization for contents on a store.

Quick Info

Copy code Copy code
struct DNTBL
{
    ULONG ulFlags;
    LPSTREAM pstmReserved1;
    LPSTREAM pstmReserved2;
    LPSTREAM pstmReserved3;
    LPSTREAM pstmReserved4;
    PXICC pxicc;
    PXIHC pxihc;
    LPSTR pszName;
    FILETIME ftLastMod;
    ULONG ulRights;
    FEID feid;
    UINT uintReserved;
    DNTBLE rgte[2];
    LPSRestriction psrReserved;
    BOOL boReserved;
    void* pReserved1;
    void* pReserved2;
};

Members

ulFlags

[in] Flags to modify behavior

  • DNT_OK

    • [in] Download was successful. The client sets this after downloading information from the server.

pstmReserved1

[out] This member is reserved for the internal use of Outlook and is not supported.

pstmReserved2

[out] This member is reserved for the internal use of Outlook and is not supported.

pstmReserved3

[out] This member is reserved for the internal use of Outlook and is not supported.

pstmReserved4

[out] This member is reserved for the internal use of Outlook and is not supported.

pxicc

[out] Pointer to the IExchangeImportContentsChanges contents interface that supports downloading content changes. For more information on IExchangeImportContentsChanges, see ICS Evaluation Criteria.

pxihc

[out] Pointer to the IExchangeImportHierarchyChanges hierarchy interface that supports downloading incremental hierarchy changes. For more information on IExchangeImportHierarchyChanges, seeICS Evaluation Criteria.

pszName

[out] Name of the folder.

ftLastMod

[out] Last modification time of the folder.

ulRights

[out] Value of the PR_RIGHTS property of the folder.

feid

[out] Entry ID of the folder.

uintReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

rgte

[out] Changes for normal (or non-hidden) and associated (or hidden) items. rgte[0] is for normal items, and rgte[1] is for associated items. Outlook populates this member during the downloading when using Incremental Change Synchronization (ICS). For more information on ICS, seeICS Evaluation Criteria.

lpsrReserved

[in]/[out] This member is reserved for the internal use of Outlook and is not supported.

boReserved

[in]This member is reserved for the internal use of Outlook and is not supported.

pReserved1

[out]This member is reserved for the internal use of Outlook and is not supported.

pReserved2

[in]This member is reserved for the internal use of Outlook and is not supported.

See also

Concepts

About the Replication State Machine
MAPI Constants
DNTBLE


DNTBLE

 Copy code hover
[image]

DNTBLE
See also Send feedback

Published: July 16, 2012

Information for downloading the contents of a folder from the server during the download table state. This downloading process uses Microsoft Exchange Incremental Change Synchronization (ICS). For more information on ICS, see ICS Evaluation Criteria.

Quick Info

Copy code Copy code
struct DNTBLE
{
    UINT cEntNew;
    UINT cEntMod;
    UINT cEntRead;
    UINT cEntDel;
};

Members

cEntNew

[out] Number of items added to the local store. Outlook populates this value during the downloading when using ICS.

cEntMod

[out] Number of items modified on the local store. Outlook populates this value during the downloading when using ICS.

cEntRead

[out] Number of items read or marked unread on the local store. Outlook populates this value during the downloading when using ICS.

cEntDel

[out] Number of items deleted on the local store. Outlook populates this value during the downloading when using ICS.

See also

Concepts

About the Replication State Machine
MAPI Constants
DNTBL


FEID

 Copy code hover
[image]

FEID
See also Send feedback

Published: July 16, 2012

Identifier for a folder. It contains an entry identifier and other relevant information.

Quick Info

Copy code Copy code
struct FEID
{
    BYTE abFlags[4];
    MAPIUID muid;
    WORD placeholder;
    LTID ltid;
};

Members

abFlags

4-byte entry identifier for the folder. For more information about MAPI entry identifiers, see ENTRYID.

muid

GUID that identifies the store provider. See mapidefs.h for the type definition of MAPIUID.

placeholder

This member is reserved for the internal use of Outlook and is not supported.

ltid

Long-term ID of the folder.

See also

Concepts

About the Replication State Machine
MAPI Constants
LTID
UPFLD
SYNC


EXCHANGE_STORE_VERSION_NUM

 Copy code hover
[image]

EXCHANGE_STORE_VERSION_NUM
See also Send feedback

Published: July 16, 2012

Stores version information for the Microsoft Exchange Server that accounts in a Microsoft Office Outlook profile are connected to.

Quick Info

Copy code Copy code
typedef struct {
    WORD wMajorVersion;
    WORD wMinorVersion;
    WORD wBuild;
    WORD wMinorBuild;
} EXCHANGE_STORE_VERSION_NUM;

Members

wMajorVersion

  • Major version number that is generally incremented when a release contains significant new features and changes in functionality.

wMinorVersion

  • Minor version number that corresponds to a specific major version number and that is generally incremented when a release contains minor new features or significant fixes.

wBuild

  • Major build number that corresponds to specific major and minor version numbers and that is generally incremented in an internal release that contains new features or fixes. This value is also incremented when the release is a major internal code branch or milestone, such as a release candidate.

wMinorBuild

  • Minor build number that is generally incremented in an internal release that contains new features or fixes corresponding to a specific major build that denotes a major code branch or milestone.

See also

Concepts

About MAPI Additions
PidTagProfileServerFullVersion Canonical Property


FollowUpStatus

 Copy code hover
[image]

FollowUpStatus
See also Send feedback

Published: July 16, 2012

Specifies the different follow-up statuses for a message.

Quick Info

Copy code Copy code
enum FollowUpStatus {
    flwupNone = 0,
    flwupComplete,
    flwupMarked,
    flwupMAX};

Members

flwupNone

No follow-up has been specified.

flwupComplete

The message is complete.

flwupMarked

The message is marked for follow-up.

flwupMAX

The number of different statuses supported for follow-up.

See also

Reference

PidTagFlagStatus Canonical Property


Gender

 Copy code hover
[image]

Gender
See also Send feedback

Published: July 16, 2012

Specifies the possible values for the gender of a messaging user.

Quick Info

Copy code Copy code
enum Gender {
    genderMin = 0,
    genderUnspecified = genderMin,
    genderFemale,
    genderMale,
    genderCount,
    genderMax = genderCount - 1
};

Members

genderMin

The minimum number of different values supported for the gender.

genderUnspecified

The gender is not specified for the messaging user.

genderFemale

The messaging user is female.

genderMale

The messaging user is male.

genderCount

The number of different values supported for the gender.

genderMax

The maximum number of different values supported for the gender.

See also

Reference

PidTagGender Canonical Property


HDRSYNC

 Copy code hover
[image]

HDRSYNC
See also Send feedback

Published: July 16, 2012

Information for synchronizing a message header during the download message header state.

Quick Info

Copy code Copy code
struct HDRSYNC
{
    UPMSG *pupmsg;
    FEID feidPar;
    LPSTREAM pstmReserved;
    ULONG ulFlags;
    LPMESSAGE pmsgFull;
};

Members

pupmsg

  • [out] Information for the current message header in the local store.

feidPar

  • [out] Entry ID for the parent folder of the message item.

pstmReserved

  • [out] This member is reserved for the internal use of Outlook and is not supported.

ulFlags

  • [in] Flags to modify behavior:

  • HSF_LOCAL

    • [in] Full item resides in the same local store as the header item.

  • HSF_COPYDESTRUCTIVE

    • [in] Optimize internal copy operations. This might cause data loss. HSF_LOCAL must be set.

  • HSF_OK

    • [in] Header synchronization was successful. The client sets this after downloading information from the server.

    pmsgFull

    • [in] The full message item including the message header downloaded from the server. See mapidefs.h for the type definition of LPMESSAGE.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
FEID


HRESULT

 Copy code hover
[image]

HRESULT
See also Send feedback

Published: July 16, 2012

A 32-bit value that is used to describe an error or warning.

C++
typedef LONG HRESULT;

Remarks

The HRESULT data type is the same as the SCODE data type.

An HRESULT value consists of the following fields:

  • A 1-bit code indicating severity, where zero represents success and 1 represents failure.

  • A 4-bit reserved value.

  • An 11-bit code indicating responsibility for the error or warning, also known as a facility code.

  • A 16-bit code describing the error or warning.

Most MAPI interface methods and functions return HRESULT values to provide detailed cause formation. HRESULT values are also used widely in OLE interface methods. OLE provides several macros for converting between HRESULT values and SCODE values, another common data type for error handling.

Note Note

In 64-bit MAPI, HRESULT is still a 32-bit value.

For information about the OLE use of HRESULT values, see the OLE Programmer's Reference. For more information about the use of these values in MAPI, see Error Handling and any of the following interface methods:

IABLogon::GetLastError

IMAPISupport::GetLastError

IMAPIControl::GetLastError

IMAPITable::GetLastError

IMAPIProp::GetLastError

IMAPIViewAdviseSink::OnPrint

See also

Reference

SCODE

Concepts

MAPI Data Types


LTID

 Copy code hover
[image]

LTID
See also Send feedback

Published: July 16, 2012

Generic Long Term ID of an object in an Outlook store.

Quick Info

Copy code Copy code
struct LTID
{
    GUID guid;
    BYTE globcnt[6];
    WORD wLevel;
};

Members

guid

  • [out] The GUID of the server that created the object.

globcnt

  • [out] A 6-byte unique number that identifies the object within the Outlook store.

wLevel

  • [out] The hierarchy level of the entry ID for an Exchange Favorite Public folder.

See also

Concepts

About the Replication API
About the Replication State Machine
FEID


MAPIOFFLINE_ADVISEINFO

 Copy code hover
[image]

MAPIOFFLINE_ADVISEINFO
See also Send feedback

Published: July 16, 2012

Provides information to IMAPIOfflineMgr::Advise to register callback for an offline object.

Quick Info

See IMAPIOfflineMgr::Advise.

Copy code Copy code
typedef struct
{
      ULONG                   ulSize;
      ULONG                   ulClientToken;
      MAPIOFFLINE_CALLBACK_TYPE     CallbackType;
      IUnknown*               pCallback;
      ULONG                   ulAdviseTypes;
      ULONG                   ulStateMask;
} MAPIOFFLINE_ADVISEINFO;

Members

ulSize

The size of MAPIOFFLINE_ADVISEINFO.

ulClientToken

A token defined by the client about a callback. It is the ulClientToken member of the MAPIOFFLINE_NOTIFY structure passed to IMAPIOfflineNotify::Notify.

CallbackType

Type of callback to make.

  • MAPIOFFLINE_CALLBACK_TYPE_NOTIFY

    • The type of callback is by notification. This is the only supported type of callback. pCallback must indicate the interface IMAPIOfflineNotify.

pCallback

Interface to use for callback. This is the client's implementation of IMAPIOfflineNotify.

ulAdviseTypes

The types of advise, as identified by the condition for advising. The only supported type is MAPIOFFLINE_ADVISE_TYPE_STATECHANGE.

ulStateMask

The only supported state is MAPIOFFLINE_STATE_ALL.

See also

Reference

IMAPIOfflineMgr::Advise

Concepts

About the Offline State API
MAPI Constants
MAPIOFFLINE_CALLBACK_TYPE


MAPIOFFLINE_CALLBACK_TYPE

 Copy code hover
[image]

MAPIOFFLINE_CALLBACK_TYPE
See also Send feedback

Published: July 16, 2012

Enumeration of supported types of callbacks.

Quick Info

Copy code Copy code
typedef enum
{
     MAPIOFFLINE_CALLBACK_TYPE_NOTIFY = 0
} MAPIOFFLINE_CALLBACK_TYPE;

See also

Concepts

About the Offline State API
MAPI Constants
MAPIOFFLINE_ADVISEINFO


MAPIOFFLINE_NOTIFY

 Copy code hover
[image]

MAPIOFFLINE_NOTIFY
See also Send feedback

Published: July 16, 2012

This is the notification for a change in the connection state. It indicates the part of the connection state that has changed, the old connection state, and the new connection state.

Quick Info

See IMAPIOfflineNotify.

Copy code Copy code
typedef struct
{
      ULONG ulSize;
      MAPIOFFLINE_NOTIFY_TYPE NotifyType;
      ULONG ulClientToken;
      union {
         struct
           {
           ULONG ulMask;
           ULONG ulStateOld;
           ULONG ulStateNew;
           } StateChange;
             } Info;
} MAPIOFFLINE_NOTIFY;

Members

ulSize

Size of the MAPIOFFLINE_NOTIFY structure.

NotifyType

Type of notification. Note that only notification on change of the connection state is supported; the only supported values are:

  • MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_START

  • MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE

  • MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_DONE

ulClientToken

A token defined by the client in the MAPIOFFLINE_ADVISEINFO structure in IMAPIOfflineMgr::Advise.

ulMask

The part of the connection state that has changed. The only supported value is MAPIOFFLINE_STATE_OFFLINE_MASK.

ulStateOld

The old connection state. The only supported values are:

  • MAPIOFFLINE_STATE_OFFLINE

  • MAPIOFFLINE_STATE_ONLINE

ulStateNew

The new connection state. The only supported values are:

  • MAPIOFFLINE_STATE_OFFLINE

  • MAPIOFFLINE_STATE_ONLINE

Remarks

The Offline State API supports only notifications for online/offline changes. A client must check that Outlook returns the following values before examining the actual change:

  1. NotifyType has the value MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_START, MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE, or MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_DONE. In this case, the client can assume that the change is a connection state change, and Info is of the structure StateChange.

  2. ulMask has the value MAPIOFFLINE_STATE_OFFLINE_MASK. In this case, the client can assume that the change is an online/offline connection state change, and can proceed with examining ulStateOld and ulStateNew.

It is possible that Outlook notifies a client of other changes that are not supported. In such cases, NotifyType would not be any one of the three values stated previously, or ulMask would not be MAPIOFFLINE_STATE_OFFLINE_MASK, and the client must ignore the rest of the data in Info.

See also

Concepts

About the Offline State API
MAPI Constants
MAPIOFFLINE_NOTIFY_TYPE


MAPIOFFLINE_NOTIFY_TYPE

 Copy code hover
[image]

MAPIOFFLINE_NOTIFY_TYPE
See also Send feedback

Published: July 16, 2012

The MAPIOFFLINE_NOTIFY_TYPE of a notification identifies if a change in the connection state is going to take place, is taking place, or has completed.

Quick Info

See IMAPIOfflineNotify.

Copy code Copy code
typedef enum {
    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_START = 1,
    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE = 2,
    MAPIOFFLINE_NOTIFY_TYPE_STATECHANGE_DONE = 3
} MAPIOFFLINE_NOTIFY_TYPE;

See also

Concepts

About the Offline State API
MAPI Constants
MAPIOFFLINE_NOTIFY


MEID

 Copy code hover
[image]

MEID
See also Send feedback

Published: July 16, 2012

Identifier for an Outlook item. It contains an entry identifier and other relevant information.

Quick Info

Copy code Copy code
struct MEID
{
    BYTE abFlags[4];
    MAPIUID muid;
    WORD placeholder;
    LTID ltidFld;
    LTID ltidMsg;
};

Members

abFlags

4-byte entry identifier for the Outlook item. For more information about MAPI entry identifiers, see ENTRYID.

muid

GUID that identifies the store provider. See mapidefs.h for the type definition of MAPIUID.

placeholder

This member is reserved for the internal use of Outlook and is not supported.

ltidFld

Long-term ID of the folder.

ltidMsg

Long-term ID of the Outlook item.

See also

Concepts

About the Replication API
About the Replication State Machine
LTID
SYNC
UPMSG


MSCAP_SELECTOR

 Copy code hover
[image]

MSCAP_SELECTOR
Send feedback

Published: July 16, 2012

Specifies the capabilities to return for a store.

Quick Info

Copy code Copy code
typedef enum
{
    MSCAP_SEL_RESERVED1 = 0,
    MSCAP_SEL_RESERVED2,
    MSCAP_SEL_FOLDER,
    MSCAP_SEL_RESERVED3,
    MSCAP_SEL_RESTRICTION,
} MSCAP_SELECTOR;

Members

MSCAP_SEL_RESERVED1

This member is reserved for the internal use of Outlook and is not supported.

MSCAP_SEL_RESERVED2

This member is reserved for the internal use of Outlook and is not supported.

MSCAP_SEL_FOLDER

Capabilities about supporting folders on a store.

MSCAP_SEL_RESERVED3

This member is reserved for the internal use of Outlook and is not supported.

MSCAP_SEL_RESTRICTION

Capabilities about supporting restrictions on a store.


OLFI

 Copy code hover
[image]

OLFI
See also Send feedback

Published: July 16, 2012

Queue of long-term ID structures used by the Personal Folders file (PST) store provider to assign an Entry ID for a new message or folder in offline mode.

Quick Info

Copy code Copy code
typedef struct {
    ULONG    ulVersion;
    MAPIUID  muidReserved;
    ULONG    ulReserved;
    DWORD    dwAlloc;
    DWORD    dwNextAlloc;
    LTID     ltidAlloc;
    LTID     ltidNextAlloc;
} OLFI, *POLFI;

Members

ulVersion

  • Version number for the structure.

muidReserved

  • This member is reserved for the internal use of Outlook and is not supported.

ulReserved

  • This member is reserved for the internal use of Outlook and is not supported.

dwAlloc

  • The number of entries that are available for allocation. These entries share the same globally unique identifier (GUID).

dwNextAlloc

  • The number of entries that are available next for allocation. These entries share the same GUID.

ltidAlloc

  • The long-term ID structure, LTID, identifying the entry currently available for allocation. The long-term ID structure contains a GUID and an index identifying an object in the store. Together, the GUID and the index can form a unique Entry ID for an object.

ltidNextAlloc

  • Long-term ID structure identifying the next available entry.

Remarks

An Entry ID is a 4-byte MAPI entry identifier for a folder or a message. For more information, see ENTRYID.

When a PST store provider assigns an Entry ID to a new object, it first needs a GUID that identifies the server, and an index that identifies the object in the store. Even though the GUID is not unique across all Entry IDs, the GUID and the index combined provide a unique entry. This GUID and index pair is tracked by a long-term ID structure, LTID, which is part of the OLFI structure.

The PST store provider does not physically keep in OLFI an LTID structure for each GUID-index pair. It keeps one LTID structure, ltidAlloc, for the currently first available GUID-index pair; a count, dwAlloc, of the number of available entries that share this same GUID; and a second LTID structure, ltidNextAlloc, for the next available GUID-index pair that has a different GUID. The PST store provider uses the OLFI structure to track the GUIDs and indexes that it has handed out. At a virtual level, the provider maintains a reserve of a number of LTID structures that are ready to be allocated. dwAlloc maintains a count of the available LTID structures.

Requests for Entry IDs come in blocks. When there is a request for a block, the PST store provider checks if there is sufficient reserve on hand by comparing the requested size with dwAlloc. If there is sufficient reserve, it returns the GUID and index in ltidAlloc for allocation. It then decreases dwAlloc by the requested size, and increments the index in ltidAlloc by the requested size. This prepares the PST store provider to allocate ltidAlloc on the next request for another block of Entry IDs. Note that the GUID remains the same for the next request.

If the size of a request is larger than dwAlloc, the PST store provider tries to use what it has next in reserve, as specified by dwNextAlloc and ltidNextAlloc. It copies dwNextAlloc and ltidNextAlloc to dwAlloc and ltidAlloc respectively, and sets dwNextAlloc and ltidNextAlloc to NULL.

A provider that wraps the PST store provider should periodically check ltidNextAlloc to see if it is NULL. If it is, the provider should populate it with a new GUID and reset dwNextAlloc so that more entry IDs can be allocated.

See also

Concepts

About the Replication API
About the Replication State Machine
LTID


OlFlagIcon

 Copy code hover
[image]

OlFlagIcon
See also Send feedback

Published: July 16, 2012

Specifies whether an item is flagged, and if it is, the color associated with the flagged item.

Quick Info

Copy code Copy code
enum OlFlagIcon {
    olNoFlagIcon=0,
    olPurpleFlagIcon=1,
    olOrangeFlagIcon=2,
    olGreenFlagIcon=3,
    olYellowFlagIcon=4,
    olBlueFlagIcon=5,
    olRedFlagIcon=6,
};

Members

olNoFlagIcon

No flag has been associated with the item.

olPurpleFlagIcon

Purple has been associated with the flagged item.

olOrangeFlagIcon

Orange has been associated with the flagged item.

olGreenFlagIcon

Green has been associated with the flagged item.

olYellowFlagIcon

Yellow has been associated with the flagged item.

olBlueFlagIcon

Blue has been associated with the flagged item.

olRedFlagIcon

Red has been associated with the flagged item.

See also

Reference

PidTagFollowupIcon Canonical Property


SCODE

 Copy code hover
[image]

SCODE
See also Send feedback

Published: July 16, 2012

A 32-bit status value that is used to describe an error or warning.

C++
typedef ULONG SCODE;

Remarks

The SCODE data type is the same as the HRESULT data type.

An SCODE value is divided into four fields:

  • A single-bit severity code which is set to 0 to indicate success and 1 to indicate failure.

  • An 11-bit reserved field

  • A 4-bit facility code which indicates the area responsible for the error or warning.

  • A 16-bit error or warning code which describes the problem that is causing the error or warning.

Many of the MAPI functions and methods return SCODE values defined as HRESULT data types as do the OLE methods and functions. OLE defines several macros that can be used to convert between an SCODE and an HRESULT.

Note Note

In 64-bit MAPI, SCODE is still a 32-bit value.

For more information about how MAPI uses the SCODE data type, see Error Handling. For more information about OLE and the SCODE data type, see the OLE Programmer's Reference.

See also

Reference

HRESULT

Concepts

MAPI Data Types


SKEY

 Copy code hover
[image]

SKEY
See also Send feedback

Published: July 16, 2012

Source key for an Outlook item.

Quick Info

Copy code Copy code
struct SKEY
{
    GUID guid;
    BYTE globcnt[6];
};

Members

guid

GUID of the server creating the object.

See also

Concepts

About the Replication API
About the Replication State Machine
UPDELE
UPMSG
UPREADE


SYNC

 Copy code hover
[image]

SYNC
See also Send feedback

Published: July 16, 2012

Information for starting synchronization between a local store and a server. This information is used during the synchronize state.

Quick Info

Copy code Copy code
struct SYNC
{
    ULONG ulFlags;
    LPWSTR pwzPath;
    FEID Reserved1;
    MEID Reserved2;
    LPENTRYLIST pel;
    ULONG const * pulFolderOptions;
};

Members

ulFlags

  • [out]/[in] A bitmask of the following flags that modifies the behavior during synchronization:

  • UPS_UPLOAD_ONLY

    • [in] The client will be performing only upload. Outlook only returns locally modified folders.

  • UPS_DNLOAD_ONLY

    • [in] The client will be performing only download. Outlook should not clear upload bits for folders.

  • UPS_THESE_FOLDERS

    • [in] The client will be synchronizing a specified set of folders with the provided entry IDs. This flag can be combined with either the UPS_UPLOAD_ONLY or UPS_DNLOAD_ONLY flag.

  • UPS_OK

    • [out] Synchronization was successful. The client sets this after uploading or a full synchronization completes.

  • Note Note

    Even though the client can either upload or fully synchronize (upload then download) folders and items with the Replication API, the client specifies ulFlags with only one direction of the replication at a time — either the UPS_UPLOAD_ONLY or UPS_DNLOAD_ONLY flag. In the case of a full synchronization, the client first does an upload with the UPS_UPLOAD_ONLY flag, and then a download with the UPS_DNLOAD_ONLY flag.

pwzPath

  • [out] Path to the local store.

Reserved1

  • This member is reserved for the internal use of Outlook and is not supported.

Reserved2

  • This member is reserved for the internal use of Outlook and is not supported.

pel

  • [in] This is the list of entry IDs of the folders to synchronize if UPS_THESE_FOLDERS has been set. See mapidefs.h for the type definition of LPENTRYLIST.

pulFolderOptions

  • [in] This is an array of folder options for corresponding folders in pel if UPS_THESE_FOLDERS has been set. These folder options are used when uploading each of the folders listed in pel during the upload folder state. For more information about folder options, see UPFLD.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


SYNCCONT

 Copy code hover
[image]

SYNCCONT
See also Send feedback

Published: July 16, 2012

Information for synchronizing the contents of specified folders in a local store with the server during the synchronize contents state. This involves just uploading, or a full synchronization involving an upload and then a download.

Quick Info

Copy code Copy code
struct SYNCCONT
{
   ULONG   ulFlags;
   UINT   iEnt;
   UINT   cEnt;
   LPVOID    pvReserved;
   LPSPropTagArray   ptagaReserved;
   LPSSortOrderSet   psosReserved;
};

Members

ulFlags

[in] Flags to determine the appropriate behavior during synchronization.

  • UPC_OK

    • [in] Upload or full synchronization was successful. The client sets this after synchronizing information with the server.

iEnt

[out] Index to track synchronizing the contents in the number of folders specified by cEnt.

cEnt

[out] Number of folders to be replicated.

pvReserved

This member is reserved for the internal use of Outlook and is not supported.

ptagaReserved

This member is reserved for the internal use of Outlook and is not supported.

psosReserved

This member is reserved for the internal use of Outlook and is not supported.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


SYNCSTATE

 Copy code hover
[image]

SYNCSTATE
See also Send feedback

Published: July 16, 2012

This structure defines the states for the replication state machine.

Quick Info

Copy code Copy code
typedef enum {
    LR_SYNC_IDLE = 0,
    LR_SYNC,
    LR_SYNC_UPLOAD_HIERARCHY,
    LR_SYNC_UPLOAD_FOLDER,
    LR_SYNC_CONTENTS,
    LR_SYNC_UPLOAD_TABLE,
    LR_SYNC_UPLOAD_MESSAGE,
    LR_SYNC_UPLOAD_MESSAGE_READ = 8,
    LR_SYNC_UPLOAD_MESSAGE_DEL,
    LR_SYNC_DOWNLOAD_HIERARCHY,
    LR_SYNC_DOWNLOAD_TABLE,
    LR_SYNC_DOWNLOAD_HEADER = 17
} SYNCSTATE;

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


TCHAR

 Copy code hover
[image]

TCHAR
See also Send feedback

Published: July 16, 2012

A Win32 character string that can be used to describe ANSI, DBCS, or Unicode strings. For ANSI and DBCS platforms, TCHAR is defined as follows:

C++
typedef char TCHAR;

Remarks

For Unicode platforms, TCHAR is defined as synonymous with the WCHAR type.

MAPI clients can use the TCHAR data type to represent a string of either the WCHAR or char type. Be sure to define the symbolic constant UNICODE and limit the platform when it is required. MAPI will interpret the platform information and internally translate TCHAR to the appropriate string. The MAPI property type, PT_TSTRING, works just like the TCHAR data type. When the platform supports Unicode, properties of type PT_TSTRING are assigned the type PT_UNICODE at compile time. When the platform does not support Unicode, these properties are assigned the type PT_STRING8.

For more information about this functionality, see Character Sets and List of Property Types.

See also

Concepts

MAPI Data Types


UPDEL

 Copy code hover
[image]

UPDEL
See also Send feedback

Published: July 16, 2012

Information for items that have been deleted in a local store. This information is used during the upload delete status state.

Quick Info

Copy code Copy code
struct UPDEL
{
    PUPDELE pupde;
    UINT cEnt;
};

Members

pupde

[out] Vector of UPDELE entries.

cEnt

[out] Number of entries in pupde.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


UPDELE

 Copy code hover
[image]

UPDELE
See also Send feedback

Published: July 16, 2012

Extended information for items that have been deleted in a local store. This information is used during the upload delete status state.

Quick Info

Copy code Copy code
struct UPDELE
{
    ULONG ulFlags;
    SKEY skey;
    DWORD   dwReserved;
    SBinary binChg;
    SBinary binPcl;
    SKEY skeyDst;
    PUPMOV pupmov;
};

Members

ulFlags

[out]/[in] Flags to determine appropriate behavior during uploading.

  • UPD_ASSOC

    • [out] Item is associated.

  • UPD_MOV

    • [out] Item was moved out.

  • UPD_OK

    • [in] Upload was successful. The client sets this after uploading information to server.

  • UPD_MOVED

    • [in] Item was moved successfully.

  • UPD_UPDATE

    • [in] Mark source item as modified.

  • UPD_COMMIT

    • [in] Commit upload state now (entry 0).

skey

[out] Source key of item.

dwReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

binChg

[out] Change key of destination item if item has been moved.

binPcl

[out] Change list of destination item if item has been moved.

skeyDst

[out] Source key of destination item if item has been moved.

pupmov

[out] Destination folder information if item has been moved.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
SKEY
UPDEL
UPMOV


UPFLD

 Copy code hover
[image]

UPFLD
See also Send feedback

Published: July 16, 2012

Information for uploading a folder during the upload folder state.

Quick Info

Copy code Copy code
struct UPFLD
{
    ULONG ulFlags;
    LPMAPIFOLDER pfld;
    FEID feid;
};

Members

ulFlags

[out]/[in] Flags to determine appropriate actions for the uplaod.

  • UPF_NEW

    • [out] Folder is new.

  • UPF_MOD_PARENT

    • [out] Folder has been moved.

  • UPF_MOD_PROPS

    • [out] Folder properties have been modified.

  • UPF_DEL

    • [out] Folder was deleted.

  • UPF_OK

    • [in] Upload was successful. The client sets this after uploading folder information to the server.

pfld

[out] The open folder object to upload.

feid

[out] Entry ID of the folder.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


UPHIER

 Copy code hover
[image]

UPHIER
See also Send feedback

Published: July 16, 2012

Information for synchronizing a folder hierarchy during the upload hierarchy state.

Quick Info

Copy code Copy code
struct UPHIER
{
    ULONG ulFlags;
    LPSTREAM pstmReserved;
    UINT iEnt;
    UINT cEnt;
};

Members

ulFlags

[in] Flags to modify the behavior when synchronizing the folder hierarchy.

  • UPH_OK

    • [in] Upload was successful. The client sets this after successfully uploading information to the server. Upon seeing this flag, Outlook clears any internal bookkeeping information that indicated the folder hierarchy needed updating.

  • The client passes the HRESULT if the upload was not successful.

pstmReserved

[out] This member is reserved for Outlook internal use and is not supported.

iEnt

[out] Index to track synchronizing the number of folders specified by cEnt.

cEnt

[out] Number of folders that are out of sync.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants


UPMOV

 Copy code hover
[image]

UPMOV
See also Send feedback

Published: July 16, 2012

Information for uploading items that have been moved. This information is used during the upload delete status state and upload table state.

Quick Info

Copy code Copy code
struct UPMOV
{
      ULONG          ulFlags;
      LPVOID         pReserved;
      LPSTREAM       pstmReserved;
      LPSTR          pszName;
      FEID           feid;
      LPMAPIFOLDER   pfld;
      PXICC          pxicc;
      DWORD          dwReserved;
      PUPMOV         pupmovNext;
      UINT           cEntMov;
};

Members

ulFlags

[in] Flags to determine the appropriate behavior during the upload.

  • UPV_ERROR

    • [in] Problem opening server folder.

  • UPV_DIRTY

    • [in] The upload state has changed. This is used by the client to track the change in state for the local store.

  • UPV_COMMIT

    • [in] Commit upload state.

pReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

pstmReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

pszName

[out] Name of the destination folder.

Note Note

This member does not support UNICODE.

feid

[out] Entry ID of destination folder.

pfld

[in] Pointer to server folder.

pxicc

[in] Pointer to the IExchangeImportContentsChanges contents interface that supports uploading content changes when using Incremental Change Synchronization (ICS). For more information on IExchangeImportContentsChanges and ICS, see ICS Evaluation Criteria.

dwReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

pupmovNext

[out] Next move context.

cEntMov

[in] Number of items moved here.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
FEID


UPMSG

 Copy code hover
[image]

UPMSG
See also Send feedback

Published: July 16, 2012

Information for uploading an Outlook item during the upload message state.

Quick Info

Copy code Copy code
struct UPMSG
{
    ULONG ulFlags;
    LPMESSAGE pmsg;
    MEID meid;
    SBinary binReserved1;
    SBinary binReserved2;
    FEID feid;
    SBinary binChg;
    SBinary binPcl;
    SKEY skeySrc;
};

Members

ulFlags

[out]/[in] Flags to determine appropriate behavior during the upload.

  • UPM_ASSOC

    • [out] Item is associated.

  • UPM_NEW

    • [out] New item.

  • UPM_MOV

    • [out] Item was moved here.

  • UPM_MOD_PROPS

    • [out] Item properties were modified.

  • UPM_HEADER

    • [out] Item is a message header.

  • UPM_OK

    • [in] Upload was successful. The client sets this after uploading information to the server.

  • UPM_MOVED

    • [in] Item was moved successfully.

  • UPM_COMMIT

    • [in] Commit upload state now.

  • UPM_DELETE

    • [in] Delete item now.

  • UPM_SAVE

    • [in] Save changes to the item.

pmsg

[out] Open item object. See mapidefs.h for the type definition of LPMESSAGE.

meid

[out] Entry ID of item.

binReserved1

[in] This member is reserved for the internal use of Outlook and is not supported.

binReserved2

[in] This member is reserved for the internal use of Outlook and is not supported.

feid

[out] Entry ID of the source folder, if item was moved.

binChg

[out] Change key of the destination item, if item was moved. See mapidefs.h for the type definition of SBinary.

binPcl

[out] Change list of the destination item, if item was moved. See mapidefs.h for the type definition of SBinary.

skeySrc

[out] Source key of the source item, if item was moved.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
FEID
MEID
SKEY


UPREAD

 Copy code hover
[image]

UPREAD
See also Send feedback

Published: July 16, 2012

Information for uploading the read state of items during the upload read status state.

Quick Info

Copy code Copy code
struct UPREAD
{
    PUPREADE pupre;
    UINT cEnt;
};

Members

pupre

[out] Vector of UPREADE entries.

cEnt

[out] Number of UPREADE entries.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
UPREADE


UPREADE

 Copy code hover
[image]

UPREADE
See also Send feedback

Published: July 16, 2012

Extended information for uploading the read state of an item during the upload read status state.

Quick Info

Copy code Copy code
struct UPREADE
{
    ULONG ulFlags;
    SKEY skey;
};

Members

ulFlags

[out]/[in] Flags to determine the appropriate behavior during the upload.

  • [out]/[in] Flags to determine the appropriate behavior during the upload.

  • UPR_ASSOC

    • [out] Item is hidden.

  • UPR_READ

    • [out] The read status of the item has been changed.

  • UPR_OK

    • [in] Upload was successful. The client sets this after uploading information to the server.

  • UPR_COMMIT

    • [in] Upload the read status of the item now, instead of waiting to the end of the upload table state to batch-process more than one item.

skey

[out] Source key of the item.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
UPREAD


UPTBL

 Copy code hover
[image]

UPTBL
See also Send feedback

Published: July 16, 2012

Information for uploading the contents of a folder during the upload table state.

Quick Info

Copy code Copy code
struct UPTBL
{
    ULONG ulFlags;
    LPSTREAM pstmReserved;
    LPSTR pszName;
    FEID feid;
    UINT uintReserved;
    UPTBLE rgte[2];
    UINT iEnt;
    UINT cEnt;
    PUPMOV pupmovHead;
    void* pReserved;
};

Members

ulFlags

[in] Flags to determine the appropriate behavior during the upload.

  • UPT_OK

    • [in] Upload was successful. The client sets this after uploading the folder contents to the server.

pstmReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

pszName

[out] Name of the folder.

feid

[out] Entry ID of the folder.

uintReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

rgte

[out] Structure to hold the following information for normal (or non-hidden) items and associated (or hidden) items in the folder: rgte[0] is for normal items, and rgte[1] is for associated items.

  • the number of new or modified items

  • the number of read items

  • the number of deleted items

iEnt

[out] Index to track uploading the number of changes specified by cEnt.

cEnt

[out] Number of changes to the folder.

pupmovHead

[out] Chain of UPMOV structures.

pReserved

[out] This member is reserved for the internal use of Outlook and is not supported.

See also

Concepts

About the Replication API
About the Replication State Machine
MAPI Constants
UPTBLE


UPTBLE

 Copy code hover
[image]

UPTBLE
See also Send feedback

Published: July 16, 2012

Extended information for uploading the contents of a folder during the upload table state.

Quick Info

Copy code Copy code
struct UPTBLE
{
    UINTiEntMod;
    UINTcEntMod;
    UINTiEntRead;
    UINTcEntRead;
    UINTiEntDel;
    UINTcEntDel;
};

Members

iEntMod

[out] Index to track uploading the cEntMod number of new or modified items.

cEntMod

[out] Number of new or modified items in the folder.

iEntRead

[out] Index to track uploading the number of cEntRead read items.

cEntRead

[out] Number of read items in the folder.

iEntDel

[out] Index to track uploading the number of cEntDel deleted items.

cEntDel

[out] Number of deleted items in the folder.

See also

Concepts

About the Replication API
About the Replication State Machine
UPTBL


MAPI Constants

 Copy code hover
[image]

MAPI Constants
See also Send feedback

Published: July 16, 2012

This topic contains constant definitions, MAPI interface declarations, and class and interface identifiers used by the MAPI APIs.

Class and Interface Identifiers

Use the DEFINE_GUID macro defined in the Microsoft Windows Software Development Kit (SDK) header file guiddef.h to associate globally unique identifier (GUID) symbolic names with their values, unless otherwise indicated.

Attachment Security Conversion API

This section contains constant definitions and interface identifiers for the Attachment Security API.

Copy code Copy code
// {b2533636-c3f3-416f-bf04-aefe41abaae2}
DEFINE_GUID(IID_IAttachmentSecurity, 0xb2533636, 0xc3f3, 0x416f, 0xbf, 0x04, 0xae, 0xfe, 0x41, 0xab, 0xaa, 0xe2);

Use the MAPIMETHOD macro defined in the Windows SDK header file mapidefs.h to define the pure virtual function IsAttachmentBlocked.

Copy code Copy code
#define MAPI_IATTACHMENTSECURITY_METHODS(IPURE)         MAPIMETHOD(IsAttachmentBlocked)         (LPCWSTR pwszFileName, BOOL *pfBlocked) IPURE;

Use the DECLARE_MAPI_INTERFACE_ macro defined in the Windows SDK header file mapidefs.h to define the virtual method table for IAttachmentSecurity.

Copy code Copy code
DECLARE_MAPI_INTERFACE_(IAttachmentSecurity, IUnknown)
{
    BEGIN_INTERFACE
    MAPI_IUNKNOWN_METHODS(PURE)
    MAPI_IATTACHMENTSECURITY_METHODS(PURE)
};

MAPI-MIME Conversion API

This section contains constant definitions and class and interface identifiers for the MAPI-MIME Conversion API.

Constants

CCSF_SMTP | 0x0002
CCSF_NOHEADERS | 0x0004
CCSF_USE_TNEF | 0x0010
CCSF_INCLUDE_BCC | 0x0020
CCSF_8BITHEADERS | 0x0040
CCSF_USE_RTF | 0x0080
CCSF_PLAIN_TEXT_ONLY | 0x1000
CCSF_NO_MSGID | 0x4000
E_INVALIDARG | As defined in the Microsoft Windows Software Development Kit (SDK) header file winerror.h

Class Identifiers

Copy code Copy code
// {4e3a7680-b77a-11d0-9da5-00c04fd65685}
DEFINE_GUID(CLSID_IConverterSession, 0x4e3a7680, 0xb77a, 0x11d0, 0x9d, 0xa5, 0x0, 0xc0, 0x4f, 0xd6, 0x56, 0x85);

Interface Identifiers

Copy code Copy code
// {4b401570-b77b-11d0-9da5-00c04fd65685}
DEFINE_GUID(IID_IConverterSession, 0x4b401570, 0xb77b, 0x11d0, 0x9d, 0xa5, 0x0, 0xc0, 0x4f, 0xd6, 0x56, 0x85);

Offline State API

This section contains constant definitions and class and interface identifiers for the Offline State API.

Constants

E_INVALIDARG | As defined in the Microsoft Windows Software Development Kit (SDK) header file winerror.h
E_NOINTERFACE | As defined in the Windows (SDK) header file winerror.h
MAPIOFFLINE_ADVISE_DEFAULT | (ULONG)0
MAPIOFFLINE_UNADVISE_DEFAULT | (ULONG)0
MAPIOFFLINE_ADVISE_TYPE_STATECHANGE | 1
MAPIOFFLINE_CAPABILITY_OFFLINE | 0x1
MAPIOFFLINE_CAPABILITY_ONLINE | 0x2
MAPIOFFLINE_FLAG_BLOCK | 0x00002000
MAPIOFFLINE_FLAG_DEFAULT | 0x00000000
MAPIOFFLINE_STATE_ALL | 0x003f037f
Online or offline |
MAPIOFFLINE_STATE_OFFLINE_MASK | 0x00000003
MAPIOFFLINE_STATE_OFFLINE | 0x00000001
MAPIOFFLINE_STATE_ONLINE | 0x00000002

Class Identifiers

Copy code Copy code
//{fbeffd93-b11f-4094-842b-96dcd31e63d1}
DEFINE_GUID(GUID_GlobalState, 0xfbeffd93, 0xb11f, 0x4094, 0x84, 0x2b, 0x96, 0xdc, 0xd3, 0x1e, 0x63, 0xd1);

Interface Identifiers

Copy code Copy code
//{000672B5-0000-0000-c000-000000000046}
DEFINE_GUID(IID_IMAPIOffline, 0x000672B5, 0x0000, 0x0000, 0xc0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x46);
Copy code Copy code
//{0317bde5-fc29-44cd-8dcd-36125a3be9ec}
DEFINE_GUID(IID_IMAPIOfflineNotify, 0x0317bde5, 0xfc29, 0x44cd, 0x8d, 0xcd, 0x36, 0x12, 0x5a, 0x3b, 0xe9, 0xec);
Copy code Copy code
//{42175607-ff3e-4790-bc18-66c8643e6424
DEFINE_GUID(IID_IMAPIOfflineMgr, 0x42175607, 0xFF3E, 0x4790, 0xbc, 0x18, 0x66, 0xc8, 0x64, 0x3e, 0x64, 0x24);

Outlook Named Properties

This section contains constant definitions for named properties and their namespaces, and other related constants.

Definitions for Named Properties

C++ Copy code Copy code

#define dispidMeetingType0x0026
#define dispidFileUnder0x8005
#define dispidYomiFirstName 0x802C
#define dispidYomiLastName 0x802D
#define dispidYomiCompanyName 0x802E
#define dispidWorkAddressStreet 0x8045
#define dispidWorkAddressCity 0x8046
#define dispidWorkAddressState 0x8047
#define dispidWorkAddressPostalCode 0x8048
#define dispidWorkAddressCountry 0x8049
#define dispidWorkAddressPostOfficeBox 0x804A
#define dispidInstMsg 0x8062
#define dispidEmailDisplayName 0x8080
#define dispidEmailAddrType 0x8082
#define dispidEmailEmailAddress 0x8083
#define dispidEmailOriginalDisplayName 0x8084
#define dispidEmail1OriginalEntryID0x8085
#define dispidEmail2DisplayName 0x8090
#define dispidEmail2AddrType 0x8092
#define dispidEmail2EmailAddress 0x8093
#define dispidEmail2OriginalDisplayName 0x8094
#define dispidEmail2OriginalEntryID0x8095
#define dispidEmail3DisplayName 0x80A0
#define dispidEmail3AddrType 0x80A2
#define dispidEmail3EmailAddress 0x80A3
#define dispidEmail3OriginalDisplayName 0x80A4
#define dispidEmail3OriginalEntryID0x80A5
#define dispidTaskStatus 0x8101
#define dispidTaskStartDate 0x8104
#define dispidTaskDueDate 0x8105
#define dispidTaskActualEffort 0x8110
#define dispidTaskEstimatedEffort 0x8111
#define dispidTaskFRecur 0x8126
#define dispidBusyStatus0x8205
#define dispidLocation 0x8208
#define dispidApptStartWhole 0x820D
#define dispidApptEndWhole 0x820E
#define dispidApptDuration 0x8213
#define dispidRecurring 0x8223
#define dispidTimeZoneStruct0x8233
#define dispidAllAttendeesString 0x8238
#define dispidToAttendeesString 0x823B
#define dispidCCAttendeesString 0x823C
#define dispidConfCheck0x8240
#define dispidApptCounterProposal 0x8257
#define dispidApptTZDefStartDisplay0x825E
#define dispidApptTZDefEndDisplay0x825F
#define dispidApptTZDefRecur0x8260
#define dispidReminderTime0x8502
#define dispidReminderSet 0x8503
#define dispidFormStorage0x850F
#define dispidPageDirStream0x8513
#define dispidSmartNoAttach 0x8514
#define dispidCommonStart 0x8516
#define dispidCommonEnd 0x8517
#define dispidFormPropStream0x851B
#define dispidRequest 0x8530
#define dispidCompanies 0x8539
#define dispidContacts0x853A
#define dispidPropDefStream0x8540
#define dispidScriptStream0x8541
#define dispidCustomFlag0x8542
#define dispidReminderNextTime 0x8560
#define dispidHeaderItem0x8578
#define dispidUseTNEF0x8582
#define dispidToDoTitle0x85A4
#define dispidLogType 0x8700
#define dispidLogStart 0x8706
#define dispidLogDuration 0x8707
#define dispidLogEnd 0x8708

Definitions for Namespaces

The following globally unique identifiers (GUIDs) represent the namespaces of the named properties.

C++ Copy code Copy code
const GUID PS_INTERNET_HEADERS  = {0x00020386, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PS_PUBLIC_STRINGS    = {0x00020329, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Appointment= {0x00062002, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Address       = {0x00062004, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Common        = {0x00062008, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Log           = {0x0006200A, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Meeting = {0x6ED8DA90, 0x450B, 0x101B, {0x98, 0xDA, 0x00, 0xAA, 0x00, 0x3F, 0x13, 0x05}};
const GUID PSETID_Task          = {0x00062003, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};

Refer to the section MAPI Store for the PSETID definitions.

Other Constants

INSP_ONEOFFFLAGS | 0xD000000
INSP_PROPDEFINITION | 0x2000000
MNID_ID | As defined in the header file mapidefs.h.
MNID_STRING | As defined in the header file mapidefs.h.
mtgNone | 0x0
mtgRequest | 0x00000001
mtgFullUpdate | 0x00010000
mtgInfoUpdate | 0x00020000
mtgOutofDate | 0x00080000
mtgDelegated | 0x00100000

Replication API

This section contains constant definitions, MAPI interface declarations, and class and interface identifiers for the Replication API.

Constants

The following is a MAPIUID structure identifying a MAPI service provider:

Copy code Copy code
const MAPIUID g_muidProvPrvNST =
 { 0xE9, 0x2F, 0xEB, 0x75, 0x96, 0x50, 0x44, 0x86,
      0x83, 0xB8, 0x7D, 0xE5, 0x22, 0xAA, 0x49, 0x48 };
DNH_OK | 0x00010000
DNT_OK | 0x00010000
HSF_LOCAL | 0x00000008
HSF_COPYDESTRUCTIVE | 0x00000010
HSF_OK | 0x00010000
MDB_OST_LOGON_UNICODE | ((ULONG) 0x00000800)
MDB_OST_LOGON_ANSI | ((ULONG) 0x00001000)
SHOW_SOFT_DELETES | ((ULONG) 0x00000002)
SS_ACTIVE | 0
SS_SUSPENDED | 1
SYNC_UPLOAD_HIERARCHY | 0x00000001
SYNC_DOWNLOAD_HIERARCHY | 0x00000002
SYNC_UPLOAD_CONTENTS | 0x00000040
SYNC_DOWNLOAD_CONTENTS | 0x00000080
SYNC_OUTGOING_MAIL | 0x00000200
SYNC_BACKGROUND | 0x00001000
SYNC_THESE_FOLDERS | 0x00020000
SYNC_HEADERS | 0x02000000
UPC_OK | 0x00010000
UPD_ASSOC | 0x00000001
UPD_MOV | 0x00000002
UPD_OK | 0x00010000
UPD_MOVED | 0x00020000
UPD_UPDATE | 0x00040000
UPD_COMMIT | 0x00080000
UPF_NEW | 0x00000001
UPF_MOD_PARENT | 0x00000002
UPF_MOD_PROPS | 0x00000004
UPF_DEL | 0x00000008
UPF_OK | 0x00010000
UPH_OK | 0x00010000
UPM_ASSOC | 0x00000001
UPM_NEW | 0x00000002
UPM_MOV | 0x00000004
UPM_MOD_PROPS | 0x00000008
UPM_HEADER | 0x00000010
UPM_OK | 0x00010000
UPM_MOVED | 0x00020000
UPM_COMMIT | 0x00040000
UPM_DELETE | 0x00080000
UPM_SAVE | 0x00100000
UPR_ASSOC | 0x00000001
UPR_READ | 0x00000002
UPR_OK | 0x00010000
UPR_COMMIT | 0x00020000
UPS_UPLOAD_ONLY | 0x00000001
UPS_DNLOAD_ONLY | 0x00000002
UPS_ONE_FOLDER | 0x00000004
UPS_THESE_FOLDERS | 0x00000080
UPS_OK | 0x00010000
UPT_OK | 0x00010000
UPT_PUBLIC | 0x00000001
UPV_ERROR | 0x00010000
UPV_DIRTY | 0x00020000
UPV_COMMIT | 0x00040000

Interface Declarations

Copy code Copy code
DECLARE_MAPI_INTERFACE_PTR(IExchangeImportHierarchyChanges,PXIHC);
Copy code Copy code
DECLARE_MAPI_INTERFACE_PTR(IExchangeImportContentsChanges,PXICC);

Interface Identifiers

Copy code Copy code
//{4FDEEFF0-0319-11CF-B4CF-00AA0DBBB6E6}
DEFINE_GUID (IID_IPSTX, 0x4FDEEFF0, 0x0319, 0x11CF, 0xB4, 0xCF, 0x00, 0xAA, 0x0D, 0xBB, 0xB6, 0xE6)
Copy code Copy code
//{2067A790-2A45-11D1-EB86-00A0C90DCA6D}
DEFINE_GUID (IID_IPSTX2, 0x2067A790, 0x2A45, 0x11D1, 0xEB, 0x86, 0x00, 0xA0, 0xC9, 0x0D, 0xCA, 0x6D)
Copy code Copy code
//{55f15320-111b-11d2-a999-006008b05aa7}
DEFINE_GUID (IID_IPSTX3, 0x55f15320, 0x111b, 0x11d2, 0xa9, 0x99, 0x00, 0x60, 0x08, 0xb0, 0x5a, 0xa7)
Copy code Copy code
//{aa2e2092-ac08-11d2-a2f9-0060b0ec3d4f}
DEFINE_GUID (IID_IPSTX4, 0xaa2e2092, 0xac08, 0x11d2, 0xa2, 0xf9, 0x00, 0x60, 0xb0, 0xec, 0x3d, 0x4f)
Copy code Copy code
//{55f15322-111b-11d2-a999-006008b05aa7}
DEFINE_GUID (IID_IPSTX5, 0x55f15322, 0x111b, 0x11d2, 0xa9, 0x99, 0x00, 0x60, 0x08, 0xb0, 0x5a, 0xa7)
Copy code Copy code
//{55f15323-111b-11d2-a999-006008b05aa7}
DEFINE_GUID (IID_IPSTX6, 0x55f15323, 0x111b, 0x11d2, 0xa9, 0x99, 0x00, 0x60, 0x08, 0xb0, 0x5a, 0xa7)
Copy code Copy code
//{d2d85db4-840f-49b8-9982-07d2405ec6b7}
DEFINE_GUID (IID_IOSTX, 0xd2d85db4,  0x840f, 0x49b8, 0x99, 0x82, 0x07, 0xd2, 0x40, 0x5e, 0xc6, 0xb7)

Use the two following interface identifiers with IMAPIContainer::OpenEntry, IMAPISession::OpenEntry, or IMsgStore::OpenEntry to open and ignore any provider check on a folder object and a message object, respectively.

Copy code Copy code
//{57D333A0-F589-4b23-A3F9-85F82FEC153C}
DEFINE_GUID (IID_IMAPIFolderNoProvChk, 0x57D333A0, 0xF589, 0x4b23, 0xA3, 0xF9, 0x85, 0xF8, 0x2F, 0xEC, 0x15, 0x3C)
Copy code Copy code
//{C3505457-7B2E-4c3b-A8D6-6DD949BB97A1}
DEFINE_GUID (IID_IMessageNoProvChk, 0xC3505457, 0x7B2E, 0x4c3b, 0xA8, 0xD6, 0x6D, 0xD9, 0x49, 0xBB, 0x97, 0xA1)

MAPI Store

This section contains constant definitions and interface identifiers used by APIs that interface with a MAPI store.

Constants

fnevIndexing | ((ULONG) 0x00010000) | A store provider can specify fnevIndexing in the ulEventType member of the NOTIFICATION structure to notify the indexer that an object is ready for indexing. The info member of the NOTIFICATION structure contains an EXTENDED_NOTIFICATION structure.
FS_NONE | 0x00 | A client can call IFolderSupport::GetSupportMask and check for the returned bitmask. FS_NONE indicates that the folder does not support sharing.
FS_SUPPORTS_SHARING | 0x01 | A client can call IFolderSupport::GetSupportMask and check for the returned bitmask. FS_SUPPORTS_SHARING indicates that the folder supports sharing.
INDEXING_SEARCH_OWNER | ((ULONG) 0x00000001) | Identifies the process that is pushing a notification to an indexer that an object is ready for indexing.
MNID_ID | As defined in the Microsoft Windows Software Development Kit (SDK) header file mapidefs.h | A value for the ulKind field of the MAPINAMEID structure.
MNID_STRING | As defined in the Microsoft Windows Software Development Kit (SDK) header file mapidefs.h. | A value for the ulKind field of the MAPINAMEID structure.
MSCAP_RES_ANNOTATION | ((ULONG) 0x00000001) | If a client specifies MSCAP_SEL_RESTRICTION in mscapSelector for IMSCapabilities::GetCapabilities, GetCapabilities can return this value if the store ignores invalid parameters in a restriction.
MSCAP_SECURE_FOLDER_HOMEPAGES | ((ULONG) 0x00000020) | If a client specifies MSCAP_SEL_FOLDER in mscapSelector for IMSCapabilities::GetCapabilities, GetCapabilities can return this value if the store is a non-default store that supports folder home pages.
STORE_PUSHER_OK | ((ULONG) 0x00800000) | A client can get the property PR_SUPPORT_MASK to determine the characteristic of a message store. If the store provider sets the STORE_PUSHER_OK flag in the bitmask, that means the MAPI Protocol Handler will not crawl the store, and the store is responsible to push any changes through notifications to the indexer to have messages indexed.

Definitions for Namespaces

The following globally unique identifiers (GUIDs) represent the namespaces of named properties. They are indexed by the MAPI Protocol Handler (PH), and are documented as read-only.

Caution note Caution

The named properties should not be used to create or modify items.

C++ Copy code Copy code
const GUID PS_INTERNET_HEADERS  = {0x00020386, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PS_PUBLIC_STRINGS    = {0x00020329, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Address       = {0x00062004, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Appointment   = {0x00062002, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Common        = {0x00062008, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Log           = {0x0006200A, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};
const GUID PSETID_Meeting       = {0x6ED8DA90, 0x450B, 0x101B, {0x98, 0xDA, 0x00, 0xAA, 0x00, 0x3F, 0x13, 0x05}};
const GUID PSETID_Task          = {0x00062003, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}};

MNID_ID Properties

Copy code Copy code
// In PSETID_Address
#define dispidWorkAddressStreet 0x8045
#define dispidWorkAddressCity 0x8046
#define dispidWorkAddressState 0x8047
#define dispidWorkAddressPostalCode 0x8048
#define dispidWorkAddressCountry 0x8049
#define dispidInstMsg 0x8062
#define dispidEmailDisplayName 0x8080
#define dispidEmailOriginalDisplayName 0x8084
Copy code Copy code
// In PSETID_Appointment
#define dispidLocation 0x8208
#define dispidApptStartWhole 0x820D
#define dispidApptEndWhole 0x820E
#define dispidApptDuration 0x8213
#define dispidRecurring 0x8223
#define dispidAllAttendeesString 0x8238
#define dispidToAttendeesString 0x823B
#define dispidCCAttendeesString 0x823C
Copy code Copy code
// In PSETID_Common
#define dispidReminderSet 0x8503
#define dispidSmartNoAttach 0x8514
#define dispidCommonStart 0x8516
#define dispidCommonEnd 0x8517
#define dispidRequest 0x8530
#define dispidCompanies 0x8539
#define dispidReminderNextTime 0x8560
Copy code Copy code
// In PSETID_Log (also known as Journal)
#define dispidLogType 0x8700
#define dispidLogStart 0x8706
#define dispidLogDuration 0x8707
#define dispidLogEnd 0x8708MNID_STRING properties
Copy code Copy code
// In PSETID_Task
#define dispidTaskStartDate 0x8104
#define dispidTaskDueDate 0x8105
#define dispidTaskActualEffort 0x8110
#define dispidTaskEstimatedEffort 0x8111
#define dispidTaskFRecur 0x8126

MNID_STRING Properties

Copy code Copy code
// In PS_PUBLIC_STRINGS
"Keywords"
Copy code Copy code
// In PS_INTERNET_HEADERS
"return-path"

Interface Identifiers

Copy code Copy code
//{00375ac3-ecaf-4ef8-a527-34f452fa9c67}
DEFINE_GUID(IID_IFolderSupport, 0x00375ac3, 0xecaf, 0x4ef8, 0xa5, 0x27, 0x34, 0xf4, 0x52, 0xfa, 0x9c, 0x67);
C++ Copy code Copy code
//{29F3AB10-554d-11d0-a97c-00a0c911f50a}
#define DEFINE_PRXGUID(_name, _l) DEFINE_GUID(_name, (0x29f3ab10 + _l), 0x554d, 0x11d0, 0xa9, 0x7c, 0x00, 0xa0, 0xc9, 0x11, 0xf5, 0x0a)
DEFINE_PRXGUID(IID_IProxyStoreObject, 0x00000000L);

Use the DEFINE_OLEGUID macro defined in the Windows SDK header file guiddef.h to associate the following GUID symbolic name with its value.

Copy code Copy code
//{00020393-0000-0000-C000-000000000046}
DEFINE_OLEGUID(IID_IMSCapabilities, 0x00020393, 0, 0)

MAPI Address Book Constants

This section contains constant definitions for the MAPI Address Book.

Constants

CONTAB_ROOT | ((ULONG) 0x00000001) | The root folder for a MAPI address book object.
CONTAB_SUBROOT | ((ULONG) 0x00000002) | A subfolder contained within the root folder of the MAPI address book object.
CONTAB_CONTAINER | ((ULONG) 0x00000003) | An address book container object.
CONTAB_USER | ((ULONG) 0x00000004) | A messaging user object.
CONTAB_DISTLIST | ((ULONG) 0x00000005) | A distribution list object.

Additional MAPI Constants

This section contains constant definitions including error codes, and interface identifiers used by MAPI APIs that were not previously exposed and documented.

DIALOG_MODAL | ((ULONG) 0x00000001) | When a client calls the IAddrBook::Details method, the client must set the DIALOG_MODAL flag in the ulFlags parameter to display the modal dialog box showing the details about a particular address book entry. This constant is defined in mapidefs.h.
ITEMPROC_FORCE | 0x00000800 | In Outlook 2007, wrapped PST stores have rules and spam filtering processed on new messages before MAPI clients are notified of the new messages. A provider or client using the IMAPIFolder::CreateMessage method to create a new message in PST stores should set the ITEMPROC_FORCE flag in the ulFlags parameter of the IMAPIProp::SaveChanges method to indicate to the PST store that the message is eligible for rules processing before the store notifies any listening client of the arrival of the new message. Note that such rules processing only applies to new messages created on a server that is not a Microsoft Exchange Server, because Exchange Server processes rules for messages on the server. Hence the provider or client creating the message must pass this flag in combination with NON_EMS_XP_SAVE, which indicates the server is not an Exchange server.
MAPI_BG_SESSION | 0x00200000 | A client can call the MAPILogonEx function, setting the MAPI_BG_SESSION flag in the flFlags parameter to log on to a session and carry out any operations in the background. In general, if a client intends to do processing on a background thread or in a separate process in a manner that is unobtrusive to the foreground thread, it should call MAPILogonEx with the MAPI_BG_SESSION flag. An example where this is used is a client application, such as an indexing engine, opening a Personal Folders File (PST) for background type access.
MAPI_CACHE_ONLY | 0x00004000 | A client can call the IAddrBook::OpenEntry method, setting the MAPI_CACHE_ONLY flag in the ulFlags parameter to open an address book entry and to access it subsequently only from the cache. An example where this is used is a client application that wants to open the Global Address List in Cached Exchange mode and access an entry in that Address Book from the cache without creating traffic between the client and the server.
MAPI_DIALOG_MODELESS | 0x0000000C | This value can be passed to the Simple MAPI MAPISendMail function in the ulFlags parameter to specify that a modeless dialog box is displayed by the default mail application. If neither this flag nor MAPI_DIALOG (0x00000008) is set, no dialog box is displayed.
MAPI_NO_CACHE | 0x00000200 | If Microsoft Office Outlook is in Cached Exchange Mode and a store has been opened in cached mode, a client or service provider can call IMsgStore::OpenEntry, setting the MAPI_NO_CACHE flag in the ulFlags parameter to open an item or a folder on the remote store. Note that if you open the message store with the MDB_ONLINE flag on the remote server, you do not have to use the MAPI_NO_CACHE flag.
MAPI_UNICODE | 0x80000000 | A client or service provider can call the OpenIMsgOnIStg function, setting the MAPI_UNICODE flag in the ulFlags parameter to create Unicode .msg files. The resulting IMessage : IMAPIProp file shows STORE_UNICODE_OK in its PidTagStoreSupportMask Canonical Property and supports Unicode properties. This constant is defined in mapidefs.h.
MDB_ONLINE | 0x00000100 | If Outlook is in Cached Exchange Mode, a client or service provider can call the IMAPISession::OpenMsgStore method, setting the MDB_ONLINE flag in the ulFlags parameter to override the connection to the local message store and open the store on the remote server. Note that you cannot open an Exchange store in cached mode and in non-cached mode at the same time in the same MAPI session. If you have already opened the cached message store, you must either close the store before you open it with this flag, or open a new MAPI session where you can open the Exchange store on the remote server by using this flag.
NON_EMS_XP_SAVE | 0x00001000 | A client can call the IMAPIProp::SaveChanges method, setting the NON_EMS_XP_SAVE flag in the ulFlags parameter to indicate that the message has not been delivered from an Exchange server. This flag should be used in combination with the ITEMPROC_FORCE flag in the ulFlags parameter to indicate to a PST store that the message is eligible for rules processing before the PST store notifies any listening client of the arrival of the message. This rules processing only applies to new messages that are created with IMAPIFolder::CreateMessage on a server that is not an Exchange server (in which case the Exchange server would have already processed rules on the message).
SPAMFILTER_ONSAVE | 0x00000080 | A client can call IMAPIProp::SaveChanges, setting the SPAMFILTER_ONSAVE flag in the ulFlags parameter to enable spam filtering on a message that is being saved. Spam filtering support is available only if the sender's e-mail address type is Simple Mail Transfer Protocol (SMTP), and the message is being saved to a store for a Personal Folders file (PST).
STORE_ITEMPROC | 0x00200000 | If this flag is set in the PidTagStoreSupportMask Canonical Property of a wrapped PST store, it indicates that when a new message arrives at the store, the store has rules and spam filtering processed on the message separately. The store then calls IMAPISupport::Notify, setting fnevNewMail in the NOTIFICATION structure that is passed as a parameter, and passing the details of the new message to a listening client. Subsequently, when the listening client receives the notification, it does not process rules on the message.
STORE_UNICODE_OK | 0x00040000 | If this flag is included in the PidTagStoreSupportMask Canonical Property, it indicates that the store supports Unicode storage. A client can look for the presence of the flag to decide whether to request or to save Unicode information to the store.

Definitions for Archiving Items in a Folder

The following constant definitions are values used to set the PidTagAgingGranularity Canonical Property.

C++ Copy code Copy code
#define AG_MONTHS 0
#define AG_WEEKS  1
#define AG_DAYS   2

Definitions for Displaying Remote Objects

The following constant and macro definitions are for displaying remote objects. For more information, see the PidTagDisplayTypeEx Canonical Property.

C++ Copy code Copy code
#define DTE_FLAG_REMOTE_VALID0x80000000
#define DTE_FLAG_ACL_CAPABLE    0x40000000
#define DTE_MASK_REMOTE        0x0000ff00
#define DTE_MASK_LOCAL        0x000000ff

#define DTE_IS_REMOTE_VALID(v)(!!((v) & DTE_FLAG_REMOTE_VALID))
#define DTE_IS_ACL_CAPABLE(v)(!!((v) & DTE_FLAG_ACL_CAPABLE))
#define DTE_REMOTE(v)(((v) & DTE_MASK_REMOTE) >> 8)
#define DTE_LOCAL(v)((v) & DTE_MASK_LOCAL)

#define DT_ROOM((ULONG) 0x00000007)
#define DT_EQUIPMENT((ULONG) 0x00000008)
#define DT_SEC_DISTLIST((ULONG) 0x00000009)

Definitions for Exchange Address Book and Message Store Error Codes

The following contains error code definitions for the Exchange Address Book and Message Store, which have reconnection capability. The last call to a disconnected Global Catalog (GC) may result in the MAPI_E_END_OF_SESSION error, which would need to be retried.

Outlook's MAPI supports reconnection to a GC server without special reconfiguration, but some other error codes can be returned to the client.

MAPI_E_END_OF_SESSION | 0x80040200 | Returned when a connection has been disconnected.
MAPI_E_RECONNECTED | 0x80040125 | Returned when the Remote Procedure Call (RPC) connection token is out-of-date. If the token of the current transaction is different from the token of the connection that means it has reconnected, so MAPI_E_RECONNECTED is returned and can be treated the same as MAPI_E_END_OF_SESSION. The call should be retried.
MAPI_E_OFFLINE | 0x80040126 | Returned when the connection is offline. Typically this means that something has occurred in the environment, such as server failure or loss of network connectivity. This error is most likely to occur when using a cached mode profile and attempting to bypass the cache to communicate with the server. If the cache was never able to initially establish a connection to the server, it may be in the offline state in which MAPI_E_OFFLINE could surface.

Neither of the preceding two errors will be returned in all scenarios where they would likely appear to apply. In most cases, MAPI_E_NETWORK_ERROR or MAPI_E_CALL_FAILED will be returned. Neither will appear using the Microsoft Exchange Server MAPI Client and Collaboration Data Objects 1.2.1 download.

Definitions for Exchange Server Mailbox Cached Mode Quotas

The following constant definitions are used by Microsoft Outlook 2010 and Microsoft Outlook 2013 to set the Exchange cached mode profile quotas that are equivalent to the Exchange mailbox quotas otherwise available only with an online profile.

Copy code Copy code
#define PR_QUOTA_WARNING PROP_TAG( PT_LONG, 0x341A)
#define PR_QUOTA_SEND    PROP_TAG( PT_LONG, 0x341B)
#define PR_QUOTA_RECEIVE PROP_TAG( PT_LONG, 0x341C)

These properties map to their correspondent online properties and contain the same values in kilobytes. PR_QUOTA_WARNING maps to PR_STORAGE_QUOTA_LIMIT, PR_QUOTA_SEND to PR_QUOTA_PROHIBIT_SEND_QUOTA, and PR_QUOTA_RECEIVE to PR_PROHIBIT_RECEIVE_QUOTA.

Definitions for Message Format

The following constant definitions are values that are used to set the PidTagMessageEditorFormat Canonical Property.

C++ Copy code Copy code
#define EDITOR_FORMAT_DONTKNOW  ((ULONG) 0)
#define EDITOR_FORMAT_PLAINTEXT ((ULONG) 1)
#define EDITOR_FORMAT_HTML      ((ULONG) 2)
#define EDITOR_FORMAT_RTF       ((ULONG) 3)

Definitions for Using RPC over HTTP

See the PidTagRpcOverHttpFlags Canonical Property topic for constant definitions used as flags to set the property.

See the PidTagRpcOverHttpProxyAuthScheme Canonical Property topic for constant definitions used to set the property.

Identifiers

Use the DEFINE_OLEGUID macro defined in the Microsoft Windows Software Development Kit (SDK) header file guiddef.h to associate the following GUID symbolic names with their values.

C++ Copy code Copy code
//{0002038A-0000-0000-C000-000000000046}
#if !defined(INITGUID) || defined(USES_IID_IMessageRaw)
DEFINE_OLEGUID(IID_IMessageRaw,0x0002038A, 0, 0);
#endif

The following Identifier is for the Capone Profile section of an Address Book, which in support of multiple Exchange (MultiEx) mailboxes contains a PR_AB_CHOOSE_DIRECTORY_AUTOMATICALLY property that effectively turns off the default container specified by SetDefaultDir.

Copy code Copy code
// {00020D0A-0000-0000-C000-000000000046}
DEFINE_OLEGUID(IID_CAPONE_PROF, 0x00020d0a, 0, 0);

Interface Identifiers

IMAPISync

Copy code Copy code
DEFINE_GUID(IID_IMAPISync, 0x5024a385, 0x2d44, 0x486a,  0x81, 0xa8, 0x8f, 0xe, 0xcb, 0x60, 0x71, 0xdd);

IMAPISyncProgressCallback

Copy code Copy code
DEFINE_GUID(IID_IMAPISyncProgressCallback, 0x5024a386, 0x2d44, 0x486a,  0x81, 0xa8, 0x8f, 0xe, 0xcb, 0x60, 0x71, 0xdd);

IID_IContabAdmin

Copy code Copy code
// {CC6A3BA9-E7F5-4769-887B-34E190817BFC}
DEFINE_GUID(IID_IContabAdmin, 0xcc6a3ba9, 0xe7f5, 0x4769, 0x88, 0x7b, 0x34, 0xe1, 0x90, 0x81, 0x7b, 0xfc);

IID_IMAPISECUREMESSAGE

Copy code Copy code
DEFINE_GUID(IID_IMAPISecureMessage, 0x253cc320, 0xeab6, 0x11d0, 0x82, 0x22, 0, 0x60, 0x97, 0x93, 0x87, 0xea);

IID_IMAPIGetSession

Copy code Copy code
DEFINE_GUID(IID_IMAPIGetSession, 0x614ab435, 0x491d, 0x4f5b, 0xa8, 0xb4, 0x60, 0xeb, 0x3, 0x10, 0x30, 0xc6);

PST Override Handler Interface Identifiers

IID_IPSTOVERRIDEREQ

Copy code Copy code
// {892EBC6D-24DC-4d90-BA48-C6CBEC14A86A}
DEFINE_GUID(IID_IPSTOVERRIDEREQ, 0x892ebc6d, 0x24dc, 0x4d90, 0xba, 0x48, 0xc6, 0xcb, 0xec, 0x14, 0xa8, 0x6a);

IID_IPSTOVERRIDE1

Copy code Copy code
// {FBB68D34-F561-44fb-A8CA-AE36696342CA}
DEFINE_GUID(IID_IPSTOVERRIDE1, 0xfbb68d34, 0xf561, 0x44fb, 0xa8, 0xca, 0xae, 0x36, 0x69, 0x63, 0x42, 0xca);

See also

Concepts

About MAPI Additions
About Named Properties Used by Outlook
How to: Access a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Open a Store on the Remote Server When Outlook is in Cached Exchange Mode
How to: Manage a Message in an OST Without Invoking a Synchronization in Cached Exchange Mode


Content Retired Notice (MAPI)

 Copy code hover
[image]

Content Retired Notice (MAPI)
Send feedback

Published: July 16, 2012

The content that you tried to view is no longer available. It may have been deleted or replaced with a more recent version. Explore this set of links to get you up to speed.

Microsoft Outlook 2013 Messaging API (MAPI) Reference

  • Outlook 2013 MAPI Reference

  • Getting Started with the Outlook 2013 MAPI Reference

  • MAPI Samples

  • MAPI Concepts

  • MAPI Reference


Office 2013 documentation copyright notice

 Copy code hover
[image]

Office 2013 documentation copyright notice
Send feedback

Published: July 16, 2012

This document is provided "as-is". Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2013 Microsoft Corporation. All rights reserved.

Microsoft, Access, ActiveX, ClearType, Excel, FrontPage, InfoPath, IntelliSense, JScript, MSDN, MS-DOS, MSN, OneNote, Outlook, PowerPoint, SharePoint, Silverlight, SmartArt, SQL Server, Visio, Visual Basic, Visual C#, Visual C++, Visual Studio, Win32, Windows, Windows PowerShell, Windows Server, and Windows Vista are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.


Outlook 2013 Messaging API (MAPI) Reference Copyright Notice

 Copy code hover
[image]

Outlook 2013 Messaging API (MAPI) Reference Copyright Notice
Send feedback

Published: July 16, 2012

Information in this document, including URLs and other Internet website references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, email addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2012 Microsoft Corporation. All rights reserved.

Microsoft, Access, ActiveX, ClearType, Excel, FrontPage, InfoPath, IntelliSense, JScript, MSDN, MS-DOS, MSN, OneNote, Outlook, PowerPoint, SharePoint, Silverlight, SmartArt, SQL Server, Visio, Visual Basic, Visual C#, Visual C++, Visual Studio, Win32, Windows, Windows PowerShell, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Macintosh is a registered trademark of Apple Inc.

All other trademarks are property of their respective owners.